Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions docs-website/topics/configure-json-serialization.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
[//]: # (title: JSON serialization overview)

The Kotlin serialization library allows you to easily convert Kotlin objects to JSON and back.
The [`Json`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/) class is the primary tool for this, offering flexibility in how JSON is generated and parsed.
You can configure `Json` instances to handle specific JSON behaviors or use it without any changes for basic tasks.

With the `Json` class, you can:

* Serialize Kotlin objects to JSON strings using the [`encodeToString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/encode-to-string.html) function.
* Deserialize JSON strings back to Kotlin objects with the [`decodeFromString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/decode-from-string.html) function.
* Work directly with the [`JsonElement`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/) when handling complex JSON structures using the [`encodeToJsonElement()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/encode-to-json-element.html) and the [`decodeFromJsonElement()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/decode-from-json-element.html) functions.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see we can nicely add encodeToStream/decodeFromStream to the list here. IMO it's OK to add a separate page for them + Okio integration

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes it definitely fits neatly here 👍

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great. Oh, and Okio's encodeToSink/decodeFromSource can also go there

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we give the link to serialization-json-elements.md here instead of API reference for JsonElement? IMO guides are easier to read than plain reference.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sure thing 👍 good idea — we can modify it as:


Before you start, import the following declarations from the serialization libraries:

```kotlin
import kotlinx.serialization.*
import kotlinx.serialization.json.*
```

Here's a simple example that demonstrates how JSON serialization works in Kotlin:

```kotlin
// Imports declarations from the serialization and JSON handling libraries
import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
@Serializable
data class User(val name: String, val age: Int)

fun main() {
// Creates a Json instance with default settings
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does not create an instance; it uses the default one. I suggest rewriting example to use Json object directly. You can slightly change sentence above: "Here's a simple example that demonstrates how JSON serialization works in Kotlin:" to "Here's a simple example that demonstrates how you can use default Json instance to do serialization in Kotlin"

Copy link
Author

@daniCsorbaJB daniCsorbaJB Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤔 What do you think about:

Here's a simple example that uses the default Json instance to show how JSON serialization works in Kotlin:

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

val json = Json

// Creates a User object
val user = User("Alice", 30)

// Converts the User object to a JSON string
val jsonString = json.encodeToString(user)
println(jsonString)
// {"name":"Alice","age":30}

// Converts the JSON string back to a User object
val deserializedUser = json.decodeFromString<User>(jsonString)
println(deserializedUser)
// User(name=Alice, age=30)
//sampleEnd
}
```
{kotlin-runnable="true"}

In addition to using the default configuration, you can [customize the `Json` instance](serialization-json-configuration.md) for specific different use cases,
such as ignoring unknown keys:

```kotlin
// Configures a Json instance to ignore unknown keys
val customJson = Json {
ignoreUnknownKeys = true
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this snippet be here? It feels incomplete. You can remove it or add customJson.decodeFromString() to show what it does

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it should be.. 🤔 It's probably not too much information for the user learning about it for the first time, so let's just make it a complete example 👍

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You have one at the beginning of serialization-json-configuration.md page, maybe you can reuse it here

}
```

## What's next

* Learn how to [customize `Json` instances](serialization-json-configuration.md) to address different use cases for serialization and deserialization.
* Explore [advanced JSON element handling](serialization-json-elements.md) to manipulate and work with JSON data before it is parsed or serialized.
* Discover how to [transform JSON during serialization and deserialization](serialization-transform-json.md) for more control over your data.
Loading