-
Notifications
You must be signed in to change notification settings - Fork 666
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 1 commit
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. | ||
|
||
|
|
||
| Before you start, import the following declarations from the serialization libraries: | ||
daniCsorbaJB marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ```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 | ||
daniCsorbaJB marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| 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 | ||
|
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
Author
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 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 👍
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. You have one at the beginning of |
||
| } | ||
| ``` | ||
|
|
||
| ## 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. | ||
Uh oh!
There was an error while loading. Please reload this page.