Skip to content
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


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
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
}
```

## 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