Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
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.
Copy link
Member

Choose a reason for hiding this comment

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

Maybe use words like use its default instance? Otherwise it is unclear what to use, because Json class does not have a public constructor on its own.


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


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

Choose a reason for hiding this comment

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

Given that we do not make a lot of emphasis on the fact that -core and -json are separate, maybe it is better to just use "serialization library"


```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
Copy link
Member

Choose a reason for hiding this comment

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

Same here. IMO "Imports declarations from the serialization library" is enough

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"

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

}
```

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