-
Notifications
You must be signed in to change notification settings - Fork 665
feat: adding JSON overview and Json configuration docs #3102
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: doc-restructuring-master
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| 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. | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I see we can nicely add
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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: | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 |
||
| 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 | ||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 |
||
| } | ||
| ``` | ||
|
|
||
| ## 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. | ||
There was a problem hiding this comment.
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, becauseJsonclass does not have a public constructor on its own.