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

Choose a reason for hiding this comment

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

Suggested change
In addition to using the default configuration, you can [customize the `Json` instance](serialization-json-configuration.md) for specific different use cases,
In addition to using the default configuration, you can [customize the `Json` instance](serialization-json-configuration.md) for special use cases,

Copy link
Author

Choose a reason for hiding this comment

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

I like the idea of removing different from here 🤔 , but I prefer specific is better than "special" ("special" would indicate something unexpected imho, unlike "specific", which signals that customization is intended for known, intentional scenarios)

Copy link
Contributor

Choose a reason for hiding this comment

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

My view is that in general you want to create your own (stored) instance, and have to in many cases. As such calling the cases "special" (or "specific different"???) misleads as the customization being the generic solution, and the default instance a special case shortcut.

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