diff --git a/docs-website/cfg/buildprofiles.xml b/docs-website/cfg/buildprofiles.xml new file mode 100644 index 000000000..3addec084 --- /dev/null +++ b/docs-website/cfg/buildprofiles.xml @@ -0,0 +1,10 @@ + + + + + true + https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/ + true + + + \ No newline at end of file diff --git a/docs-website/images/get-started-serialization.svg b/docs-website/images/get-started-serialization.svg new file mode 100644 index 000000000..482ca3beb --- /dev/null +++ b/docs-website/images/get-started-serialization.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/docs-website/serialization.tree b/docs-website/serialization.tree new file mode 100644 index 000000000..785272791 --- /dev/null +++ b/docs-website/serialization.tree @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs-website/topics/serialization-customization-options.md b/docs-website/topics/serialization-customization-options.md new file mode 100644 index 000000000..ccc165707 --- /dev/null +++ b/docs-website/topics/serialization-customization-options.md @@ -0,0 +1,519 @@ +[//]: # (title: Serialize classes) + +The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation enables the default serialization of all class properties with [backing fields](properties.md#backing-fields). +You can customize this behavior to fit your specific needs. +This page covers various serialization techniques, showing you how to specify which properties are serialized, and how the serialization process is managed. + +Before starting, make sure you've imported the [necessary library dependencies](serialization-get-started.md). + +## The @Serializable annotation + +The `@Serializable` annotation enables the automatic serialization of class properties, +allowing a class to be converted to and from formats such as JSON. + +In Kotlin, only properties with backing fields are serialized: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +class Project( + // Property with a backing field – serialized + var name: String +) { + // Property with a backing field – serialized + var stars: Int = 0 + + // Getter-only property without a backing field - not serialized + val path: String + get() = "kotlin/$name" + + // Delegated property - not serialized + var id by ::name +} + +fun main() { + val data = Project("kotlinx.serialization").apply { stars = 9000 } + // Prints only the name and the stars properties + println(Json.encodeToString(data)) + // {"name":"kotlinx.serialization","stars":9000} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-annotation-example"} + +### Serialize class references + +Classes annotated with `@Serializable` can contain properties that reference other classes. +The referenced classes must also be annotated with `@Serializable`. +When encoded to JSON, this results in a nested JSON object: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +// The owner property references another serializable class User +class Project(val name: String, val owner: User) + +// The referenced class must also be annotated with @Serializable +@Serializable +class User(val name: String) + +fun main() { + val owner = User("kotlin") + val data = Project("kotlinx.serialization", owner) + println(Json.encodeToString(data)) + // {"name":"kotlinx.serialization","owner":{"name":"kotlin"}} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-class-references-example"} + +> To reference non-serializable classes, annotate the corresponding properties with [`@Transient`](#exclude-properties-with-the-transient-annotation), or +> provide a [custom serializer](create-custom-serializers.md) for them. +> +{style="tip"} + +### Serialization of repeated object references + +Kotlin serialization is designed to encode and decode plain data. It doesn't support reconstruction +of arbitrary object graphs with repeated object references. +For example, when serializing an object that references the same instance twice, it's encoded twice: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +class Project(val name: String, val owner: User, val maintainer: User) + +@Serializable +class User(val name: String) + +fun main() { + val owner = User("kotlin") + // References owner twice + val data = Project("kotlinx.serialization", owner, owner) + println(Json.encodeToString(data)) + // {"name":"kotlinx.serialization","owner":{"name":"kotlin"},"maintainer":{"name":"kotlin"}} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-repeated-references"} + +> If you attempt to serialize a circular structure, it results in stack overflow. +> To exclude references from serialization, use [the @Transient annotation](#exclude-properties-with-the-transient-annotation). +> +{style="tip"} + +### Serialize generic classes + +Generic classes in Kotlin support type-polymorphism, which is enforced by Kotlin serialization at +compile-time. For example, consider a generic serializable class `Payload`: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +// The Payload class can be used with built-in types like Int +// or with @Serializable user-defined types like Repository +class Payload(val value: T) + +@Serializable +data class Repository(val name: String, val language: String) + +@Serializable +class BackupData( + val issueCount: Payload, + val mainRepo: Payload +) + +fun main() { + val backup = BackupData( + Payload(42), + Payload(Repository("kotlinx.serialization", "Kotlin")) + ) + println(Json.encodeToString(backup)) + // {"issueCount":{"value":42},"mainRepo":{"value":{"name":"kotlinx.serialization","language":"Kotlin"}}} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-generic-classes-example"} + +When you serialize a generic class like `Box`, the JSON output depends on the actual type you specify for `T` at compile time. +If that type isn't serializable, you get a compile-time error. + +## Optional properties + +Properties with _default values_ are optional during deserialization and can be skipped during serialization, +if the format is configured to do so. +For example, the default JSON configuration skips encoding default values. + +### Set default values for optional properties + +In Kotlin, an object can be deserialized only when all its properties are present in the input. +To make a property optional for serialization, set a default value that's used when no value is provided in the input: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +// Sets a default value for the optional language property +data class Project(val name: String, val language: String = "Kotlin") + +fun main() { + val data = Json.decodeFromString(""" + {"name":"kotlinx.serialization"} + """) + println(data) + // Project(name=kotlinx.serialization, language=Kotlin) +} +//sampleEnd +``` +{kotlin-runnable="true" id="deserialize-optional-properties"} + +### Serialize nullable properties + +Kotlin serialization natively supports nullable properties. +[Like other default values](#manage-the-serialization-of-default-properties-with-encodedefault), `null` values aren't encoded in the JSON output: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +// Defines a class with the renamedTo nullable property that has a null default value +class Project(val name: String, val renamedTo: String? = null) + +fun main() { + val data = Project("kotlinx.serialization") + // The renamedTo property isn't encoded because its value is null + println(Json.encodeToString(data)) + // {"name":"kotlinx.serialization"} +} +//sampleEnd +``` +{kotlin-runnable="true" id="nullable-properties-example"} + +Additionally, Kotlin's [null safety](null-safety.md) is strongly enforced during deserialization. +If a JSON object contains a `null` value for a non-nullable property, an exception is thrown +even when the property has a default value: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +data class Project(val name: String, val language: String = "Kotlin") + +fun main() { + val data = Json.decodeFromString(""" + {"name":"kotlinx.serialization","language":null} + """) + println(data) + // JsonDecodingException +} +//sampleEnd +``` +{kotlin-runnable="true" validate="false" id="deserialize-nullable-exception-example"} + +> If you need to handle `null` values from third-party JSON, you can [coerce them to a default value](serialization-json-configuration.md#coerce-input-values). +> +> You can also [omit explicit `null` values](serialization-json-configuration#omit-explicit-nulls) from the encoded JSON with the `explicitNulls` property. +> +{style="tip"} + +### Initializers in optional properties + +When the serialization input includes a value for an optional property, the property's initializer isn't called. +For this reason, avoid using code with side effects in property initializers. + +Here's an example: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +fun computeLanguage(): String { + println("Computing") + return "Kotlin" +} + +@Serializable +// Skips the initializer if language is in the input +data class Project(val name: String, val language: String = computeLanguage()) + +fun main() { + val data = Json.decodeFromString(""" + {"name":"kotlinx.serialization","language":"Java"} + """) + println(data) + // Project(name=kotlinx.serialization, language=Java) +} +//sampleEnd +``` +{kotlin-runnable="true" id="deserialize-initializer-example"} + +In this example, since the `language` property is specified in the input, the `Computing` string isn't printed +in the output. + +### Manage the serialization of default properties with `@EncodeDefault` + +By default, JSON serialization excludes properties that have default values. +This reduces the size of the serialized data and avoids unnecessary visual clutter. + +Here's an example where the `language` property is excluded from the output because its value equals the default: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +data class Project(val name: String, val language: String = "Kotlin") + +fun main() { + val data = Project("kotlinx.serialization") + println(Json.encodeToString(data)) + // {"name":"kotlinx.serialization"} +} +//sampleEnd +``` +{kotlin-runnable="true" id="default-properties-example"} + +> You can configure a `Json` instance to [encode default values](serialization-json-configuration.md#encode-default-values) for all properties by default. +> +{style="tip"} + +To always serialize a property, regardless of its value or format settings, use the [`@EncodeDefault`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-encode-default/) annotation. +Alternatively, you can set the [`EncodeDefault.Mode`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-encode-default/-mode/) parameter to change this behavior. + +Let's look at an example where the `language` property is always included in the serialized output, +while the `projects` property is excluded when it's an empty list: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* +import kotlinx.serialization.EncodeDefault.Mode.NEVER + +//sampleStart +@Serializable +data class Project( + val name: String, + // Always includes the language property in the serialized output + // even if it has the default value "Kotlin" + @EncodeDefault val language: String = "Kotlin" +) + +@Serializable +data class User( + val name: String, + // Excludes projects when it's an empty list, even if it has a default value + @EncodeDefault(NEVER) val projects: List = emptyList() +) + +fun main() { + val adminUser = User("Alice", listOf(Project("kotlinx.serialization"))) + val guestUser = User("Bob") + // Serializes projects because it contains a value + // language is always serialized + println(Json.encodeToString(adminUser)) + // {"name":"Alice","projects":[{"name":"kotlinx.serialization","language":"Kotlin"}]} + + // Excludes projects because it's an empty list + // and EncodeDefault.Mode is set to NEVER, so it's not serialized + println(Json.encodeToString(guestUser)) + // {"name":"Bob"} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-encode-default"} + +### Make properties required with the `@Required` annotation + +Annotate a property with [`@Required`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-required/) to make it required in the input. +This enforces that the input contains the property, even if it has a [default value](#set-default-values-for-optional-properties): + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* +import kotlinx.serialization.Required + +//sampleStart +@Serializable +// Marks the language property as required +data class Project(val name: String, @Required val language: String = "Kotlin") + +fun main() { + val data = Json.decodeFromString(""" + {"name":"kotlinx.serialization"} + """) + println(data) + // MissingFieldException +} +//sampleEnd +``` +{kotlin-runnable="true" id="required-annotation-example"} + +## Customize class serialization + +Kotlin serialization provides several ways to modify how classes are serialized. +This section covers techniques for customizing property names, controlling property inclusion, and more. + +### Customize serial names + +By default, property names in the serialization output, such as JSON, match their names in the source code. + +You can customize these names, called _serial names_, +with the [`@SerialName`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serial-name/) annotation. +Use it to make a property name more descriptive in the serialized output: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +// Changes the lang property to language using @SerialName +class Project(val name: String, @SerialName("language") val lang: String) + +fun main() { + val data = Project("kotlinx.serialization", "Kotlin") + // Prints the more descriptive property name in the JSON output + println(Json.encodeToString(data)) + // {"name":"kotlinx.serialization","language":"Kotlin"} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serial-names"} + +### Define constructor properties for serialization + +A class annotated with `@Serializable` must declare all parameters in its primary constructor as properties. + +If you need to perform additional initialization logic before assigning values to properties, use a [secondary constructor](classes.md#secondary-constructors). +The primary constructor can remain `private` and handle property initialization. + +Here's an example where the secondary constructor parses a string into two values, which are then passed to the primary constructor for serialization: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +class Project private constructor(val owner: String, val name: String) { + // Creates a Project object using a path string + constructor(path: String) : this( + owner = path.substringBefore('/'), + name = path.substringAfter('/') + ) + + val path: String + get() = "$owner/$name" +} +fun main() { + println(Json.encodeToString(Project("kotlin/kotlinx.serialization"))) + // {"owner":"kotlin","name":"kotlinx.serialization"} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-constructor-properties"} + +### Validate data in the primary constructor + +After deserialization, the `kotlinx.serialization` plugin runs the class's [initializer blocks](classes.md#initializer-blocks), +just like when you create an instance. +This allows you to validate constructor parameters and reject invalid data during deserialization. + +Here's an example: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +class Project(val name: String) { + // Validates that the name is not empty + init { + require(name.isNotEmpty()) { "name cannot be empty" } + } +} + +fun main() { + val data = Json.decodeFromString(""" + {"name":""} + """) + println(data) + // Exception in thread "main" java.lang.IllegalArgumentException: name cannot be empty +} +//sampleEnd +``` +{kotlin-runnable="true" id="validate-constructor-example"} + +### Exclude properties with the `@Transient` annotation + +You can exclude a property from serialization with the [`@Transient`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-transient/) annotation. +Transient properties must have a default value. + +If you explicitly specify a value for a transient property in the input, even if it matches the default value, a `JsonDecodingException` is thrown: + +```kotlin +// Imports declarations from the serialization library +import kotlinx.serialization.* +import kotlinx.serialization.Transient +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +// Excludes the language property from serialization +data class Project(val name: String, @Transient val language: String = "Kotlin") + +fun main() { + // Throws an exception even though input matches the default value + val data = Json.decodeFromString(""" + {"name":"kotlinx.serialization","language":"Kotlin"} + """) + println(data) + // JsonDecodingException +} +//sampleEnd +``` +{kotlin-runnable="true" validate="false" id="transient-annotation-example"} + +> To avoid exceptions from unknown keys in JSON, including those marked with the `@Transient` annotation, enable the [`ignoreUnknownKeys`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-builder/ignore-unknown-keys.html) configuration property. +> For more information, see the [Ignore unknown keys](serialization-json-configuration.md#ignore-unknown-keys) section. +> +{style="tip"} + +## What's next + +* Explore more complex JSON serialization scenarios in the [JSON serialization overview](configure-json-serialization.md). +* Learn how to define and customize your own serializers in [Create custom serializers](serialization-custom-serializers.md). diff --git a/docs-website/topics/serialization-get-started.md b/docs-website/topics/serialization-get-started.md new file mode 100644 index 000000000..b183d0f88 --- /dev/null +++ b/docs-website/topics/serialization-get-started.md @@ -0,0 +1,281 @@ +[//]: # (title: Get started with Kotlin serialization) + +[Serialization](serialization.md) converts objects into a format you can store or transmit and later reconstruct. + +Kotlin serialization supports multiple formats. +This tutorial shows you how to add the necessary plugins and dependencies for Kotlin serialization, and how to serialize and deserialize objects in JSON format. + +## Add plugins and dependencies + +To include the `kotlinx.serialization` library in your project, add the corresponding plugin and dependency configuration based on your build tool: + + + + +```kotlin +// build.gradle.kts +plugins { + kotlin("plugin.serialization") version "%kotlinVersion%" +} + +dependencies { + implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:%serializationVersion%") +} +``` + + + + +```groovy +// build.gradle +plugins { + id 'org.jetbrains.kotlin.plugin.serialization' version '%kotlinVersion%' +} + +dependencies { + implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:%serializationVersion%' +} +``` + + + + +```xml + + + %kotlinVersion% + %serializationVersion% + + + + + + org.jetbrains.kotlin + kotlin-maven-plugin + ${kotlin.version} + + + compile + compile + + compile + + + + + + kotlinx-serialization + + + + + org.jetbrains.kotlin + kotlin-maven-serialization + ${kotlin.version} + + + + + + + + + org.jetbrains.kotlinx + kotlinx-serialization-json + ${serialization.version} + + +``` + + + + +> To set up the Kotlin compiler plugin for Bazel, follow the example from the [rules_kotlin repository](https://github.com/bazelbuild/rules_kotlin/tree/master/examples/plugin/src/serialization). +> Bazel isn't officially supported by the Kotlin team, and this repository is maintained independently. +> +{style="tip"} + +### Add the library to a multiplatform project + +To use Kotlin serialization for JSON in multiplatform projects, add the JSON serialization library dependency to your common source set: + +```kotlin +commonMain { + dependencies { + implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:%serializationVersion%") + } +} +``` + +This dependency automatically includes the core serialization library as well. + +### Configure R8 for Kotlin serialization in Android projects {initial-collapse-state="collapsed" collapsible="true"} + +The Kotlin serialization library includes default [ProGuard rules](https://github.com/Kotlin/kotlinx.serialization/blob/master/rules/common.pro), so you don't need additional setup to keep serializers for all serializable classes after [shrinking](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization). +However, these rules don't apply to classes with named companion objects. + +To retain serializers for classes with named companion objects, add rules based on the [compatibility mode](https://r8.googlesource.com/r8/+/refs/heads/master/compatibility-faq.md) you use to your `proguard-rules.pro` file: + + + + +```bash +# Serializer for classes with named companion objects are retrieved using getDeclaredClasses +# If you have any such classes, replace the examples below with your own +-keepattributes InnerClasses # Required for getDeclaredClasses + +-if @kotlinx.serialization.Serializable class +com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions +com.example.myapplication.HasNamedCompanion2 +{ + static **$* *; +} +-keepnames class <1>$$serializer { # Using -keepnames is enough for the serializer() call to reference the class correctly + static <1>$$serializer INSTANCE; +} +``` + + + + + +```bash +# Serializer for classes with named companion objects are retrieved using getDeclaredClasses +# If you have any such classes, replace the examples below with your own +-keepattributes InnerClasses # Required for getDeclaredClasses + +-if @kotlinx.serialization.Serializable class +com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions +com.example.myapplication.HasNamedCompanion2 +{ + static **$* *; +} +-keepnames class <1>$$serializer { # Using -keepnames is enough for the serializer() call to reference the class correctly + static <1>$$serializer INSTANCE; +} + +# Keep both serializer and serializable classes to save the attribute InnerClasses +-keepclasseswithmembers, allowshrinking, allowobfuscation, allowaccessmodification class +com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions +com.example.myapplication.HasNamedCompanion2 +{ + *; +} +``` + + + + +> You can exclude serializable classes that are never serialized at runtime by using custom ProGuard rules with narrower [class specifications](https://www.guardsquare.com/manual/configuration/usage). +> +{style="tip"} + +## Serialize objects to JSON + +In Kotlin, you can serialize objects to JSON using the `kotlinx.serialization` library. + +To make a class serializable, you need to mark it with the [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation. +This annotation instructs the compiler to generate the code required for serializing and deserializing instances of the class. +For more information, see [The `@Serializable` annotation](serialization-customization-options.md#the-serializable-annotation). + +Let's look at an example: + +1. Import declarations from the necessary serialization libraries: + + ```kotlin + import kotlinx.serialization.* + import kotlinx.serialization.json.* + ``` + +2. Make a class serializable by annotating it with `@Serializable`: + + ```kotlin + @Serializable + data class Book(val yearPublished: Int, val title: String) + ``` + + > The `@Serializable` annotation enables default serialization of all properties with backing fields. + > You can customize serialization behavior with property-level annotations, optional properties, and more. + > + > For more information, see [Serialize classes](serialization-customization-options.md). + > + {style="note"} + +3. Use the [`Json.encodeToString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/encode-to-string.html) function to serialize an instance of this class: + + ```kotlin + // Imports declarations from the serialization and JSON handling libraries + import kotlinx.serialization.* + import kotlinx.serialization.json.* + + // Marks the Book class as serializable + @Serializable + data class Book(val yearPublished: Int, val title: String) + + fun main() { + // Serializes an instance of the Book class into a JSON string + val json = Json.encodeToString(Book(1937, "The Hobbit")) + println(json) + // {"yearPublished":1937,"title":"The Hobbit"} + } + ``` + {kotlin-runnable="true" id="serialize-get-started"} + + As a result, you get a string containing the state of this object in JSON format: `{"yearPublished":1937,"title":"The Hobbit"}` + + > You can also serialize a collection of objects in a single call: + > + > ```kotlin + > val bookList = listOf(Book(1937, "The Hobbit"), Book(1867, "War and Peace")) + > val jsonList = Json.encodeToString(bookList) + > ``` + > + {style="tip"} + +## Deserialize objects from JSON + +Deserialization converts a JSON string back into an object. + +To deserialize an object from JSON in Kotlin: + +1. Import declarations from the necessary serialization libraries: + + ```kotlin + import kotlinx.serialization.* + import kotlinx.serialization.json.* + ``` + +2. Make a class serializable by annotating it with `@Serializable`: + + ```kotlin + @Serializable + data class Book(val yearPublished: Int, val title: String) + ``` + +3. Use the [`Json.decodeFromString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/decode-from-string.html) function to deserialize an object from JSON: + + ```kotlin + // Imports declarations from the serialization and JSON handling libraries + import kotlinx.serialization.* + import kotlinx.serialization.json.* + + // Marks the Book class as serializable + @Serializable + data class Book(val yearPublished: Int, val title: String) + + fun main() { + // Deserializes a JSON string into an instance of the Book class + val obj = Json.decodeFromString("""{"yearPublished":1937, "title": "The Hobbit"}""") + println(obj) + // Book(yearPublished=1937, title=The Hobbit) + } + ``` + {kotlin-runnable="true" id="deserialize-get-started"} + +Congratulations! You have successfully serialized an object to JSON and deserialized it back into an object in Kotlin. + +## What's next + +* Learn how to serialize basic types such as primitives and strings, as well as certain standard library classes, in [Serialize built-in types](serialization-serialize-builtin-types.md). +* Discover how to customize class serialization and adjust the default behavior of the `@Serializable` annotation in [Serialize classes](serialization-customization-options.md). +* Dive deeper into handling JSON data and configuring JSON serialization in the [JSON serialization overview](configure-json-serialization.md). diff --git a/docs-website/topics/serialization-serialize-builtin-types.md b/docs-website/topics/serialization-serialize-builtin-types.md new file mode 100644 index 000000000..feed03dd4 --- /dev/null +++ b/docs-website/topics/serialization-serialize-builtin-types.md @@ -0,0 +1,433 @@ +[//]: # (title: Serialize built-in types) + +The Kotlin serialization library supports a variety of built-in types, including basic types such as primitives and strings, as well as certain standard library classes. +The following sections describe these types in detail and show how to serialize them. + +## Basic types + +Kotlin serialization provides built-in serializers for types that are represented as a single value in serialized data. +This includes primitives, strings, and enums. + +For example, here's how you can serialize a `Long` type: + +```kotlin +// Imports the necessary library declarations +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +class Data(val signature: Long) + +fun main() { + val data = Data(0x1CAFE2FEED0BABE0) + println(Json.encodeToString(data)) + // {"signature":2067120338512882656} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-long-class"} + +### Numbers + +You can serialize all Kotlin number types, including integers and floating-point numbers, using their natural JSON representations: + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.json.* +import kotlin.math.PI + +//sampleStart +@Serializable +class Data( + val answer: Int, + val pi: Double +) + +fun main() { + val data = Data(42, PI) + println(Json.encodeToString(data)) + // {"answer":42,"pi":3.141592653589793} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-numbers"} + +### Unsigned numbers + +Kotlin serialization supports Kotlin's [unsigned integer types](unsigned-integer-types.md) like `UByte` and `UInt`. +In JSON, these values are serialized as regular JSON numbers and preserve their full unsigned range: + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +class Counter(val counted: UByte, val description: String) + +fun main() { + val counted = 239.toUByte() + println(Json.encodeToString(Counter(counted, "tries"))) + // {"counted":239,"description":"tries"} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-unsigned-numbers"} + +> Although JSON preserves the full range of unsigned numbers, other serialization formats may handle them differently. +> For example, ProtoBuf and CBOR serialize these types using their signed counterparts. +> +{style="note"} + +### `Long` numbers as strings + +You can represent `Long` numbers as strings in JSON. +This is useful in JavaScript environments, where JavaScript's `Number` type can't precisely represent all Kotlin `Long` values, which may lead to precision loss. + +Use [`LongAsStringSerializer`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.builtins/-long-as-string-serializer/) with the `@Serializable` annotation to encode `Long` values as strings in JSON: + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.builtins.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +class Data( + @Serializable(LongAsStringSerializer::class) + val signature: Long +) + +fun main() { + val data = Data(0x1CAFE2FEED0BABE0) + println(Json.encodeToString(data)) + // {"signature":"2067120338512882656"} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-long-as-string"} + +> You can also specify serializers like `LongAsStringSerializer` for all properties in a file. +> For more information, see [Specify serializers for a file](third-party-classes.md#specify-serializers-for-a-file). +> +{style="tip"} + +### Enum classes + +All `enum` classes are serializable by default without the `@Serializable` annotation. +When serialized in JSON, an `enum` is encoded as a string: + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +// The @Serializable annotation isn't required for enum classes +enum class Status { SUPPORTED } + +@Serializable +class Project(val name: String, val status: Status) + +fun main() { + val data = Project("kotlinx.serialization", Status.SUPPORTED) + println(Json.encodeToString(data)) + // {"name":"kotlinx.serialization","status":"SUPPORTED"} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-enum"} + +> When targeting Kotlin/JS or Kotlin/Native, you must use the `@Serializable` annotation for an `enum` class to use it as a root object, +> such as in `encodeToString(Status.SUPPORTED)`. +> +{style="note"} + +#### Customize serial names of enum entries + +To customize the serial names of enum entries, use the `@SerialName` annotation and mark the enum class with `@Serializable`: + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +// Requires the @Serializable annotation because of @SerialName +@Serializable +enum class Status { @SerialName("maintained") SUPPORTED } + +@Serializable +class Project(val name: String, val status: Status) + +fun main() { + val data = Project("kotlinx.serialization", Status.SUPPORTED) + println(Json.encodeToString(data)) + // {"name":"kotlinx.serialization","status":"maintained"} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-enum-serialname"} + +For more information on customizing serial names, see [Customize serial names](serialization-customization-options.md#customize-serial-names). + +## Standard library types + +Kotlin serialization supports several types from the standard library, but some classes, +such as ranges and the [`Regex`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/) class, aren't supported. + +### Pair and triple + +You can serialize the [`Pair`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-pair/) and [`Triple`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-triple/) classes from the Kotlin standard library: + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +class Project(val name: String) + +fun main() { + val pair = 1 to Project("kotlinx.serialization") + println(Json.encodeToString(pair)) + // {"first":1,"second":{"name":"kotlinx.serialization"}} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-pair"} + +### Collections + +Kotlin serialization supports collection types, including both read-only and mutable variants of [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/), [`Set`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/), and [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/). +It also supports their concrete implementations such as [`ArrayList`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-array-list/) and [`LinkedHashSet`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-linked-hash-set/), as well as generic and primitive array types. +The way these collections are represented depends on the serialization format. + +In JSON, lists and sets are serialized as JSON arrays, and maps are represented as JSON objects. + +Kotlin uses the declared type to deserialize JSON. +During deserialization, the type of the resulting object is determined by the static type specified in the source code. +This type can be either the type of the property or the type parameter of the decoding function. + +#### Serialize lists + +Kotlin serialization serializes [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/) types as JSON arrays. +Here's an example with a list of classes: + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +class Project(val name: String) + +fun main() { + val list = listOf( + Project("kotlinx.serialization"), + Project("kotlinx.coroutines") + ) + println(Json.encodeToString(list)) + // [{"name":"kotlinx.serialization"},{"name":"kotlinx.coroutines"}] +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-list"} + +#### Serialize sets + +[`Set`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/) types are serialized as JSON arrays, just like [`List` types](#serialize-lists): + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +class Project(val name: String) + +fun main() { + val set = setOf( + Project("kotlinx.serialization"), + Project("kotlinx.coroutines") + ) + println(Json.encodeToString(set)) + // [{"name":"kotlinx.serialization"},{"name":"kotlinx.coroutines"}] +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-set"} + +> By default, you can deserialize sets with duplicate entries. +> +{style="tip"} + + + +#### Serialize maps + +Kotlin serialization supports [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/) types with primitive or enum keys: + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +class Project(val name: String) + +fun main() { + // Creates a map with Int keys + val map = mapOf( + 1 to Project("kotlinx.serialization"), + 2 to Project("kotlinx.coroutines") + ) + println(Json.encodeToString(map)) + // {"1":{"name":"kotlinx.serialization"},"2":{"name":"kotlinx.coroutines"}} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-map"} + +Map serialization depends on the format. +In JSON, maps are represented as objects. Since JSON object keys are always strings, keys are encoded as strings even if they are numbers in Kotlin. +Other formats, such as CBOR, support maps with non-primitive keys and preserve them as such. + +> JSON doesn't natively support complex or composite keys. +> To encode structured objects as map keys, see [Encode structured map keys](serialization-json-configuration.md#encode-structured-map-keys). +> +{style="note"} + +#### Deserialization behavior of collections + +Kotlin uses the declared type to deserialize JSON. +For example, with collections, a `List` preserves duplicates, while a `Set` enforces uniqueness: + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +data class Data( + val a: List, + val b: Set +) + +fun main() { + val data = Json.decodeFromString(""" + { + "a": [42, 42], + "b": [42, 42] + } + """) + // Duplicates are removed from data.b because the Set type enforces unique elements + println(data) + // Data(a=[42, 42], b=[42]) +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-collections"} + +> For more information about collections in Kotlin, see [Collections overview](collections-overview.md). +> +{style="tip"} + +### Unit and singleton objects + +Kotlin's [`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/) type and other singleton objects are serializable. +A [singleton](object-declarations.md) is a class with only one instance, where the state is defined by the object itself rather than by external properties. +In JSON, singleton objects are serialized as empty structures: + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +object SerializationVersion { + val libraryVersion: String = "1.0.0" +} + +fun main() { + println(Json.encodeToString(SerializationVersion)) + // {} + println(Json.encodeToString(Unit)) + // {} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-singleton"} + +> You can use serialized singleton objects in [closed polymorphic hierarchies](serialization-polymorphism.md#serialize-objects-in-sealed-hierarchies) +> to represent cases without additional fields. +> +{style="tip"} + +### Duration and Instant + +Kotlin's [`Duration`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.time/-duration/) type is serialized to a string using the ISO-8601-2 format: + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.json.* +import kotlin.time.* + +//sampleStart +fun main() { + val duration = 1000.toDuration(DurationUnit.SECONDS) + println(Json.encodeToString(duration)) + // "PT16M40S" +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-duration"} + +Starting with Kotlin 2.2.0, you can serialize Kotlin's [`Instant`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.time/-instant/) type +as a string representing a point in time using the ISO-8601-1 format: + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.json.* +import kotlin.time.* + +//sampleStart +fun main() { + val instant = Instant.fromEpochMilliseconds(1607505416124) + println(Json.encodeToString(instant)) + // "2020-12-09T09:16:56.124Z" +} +//sampleEnd +``` +{kotlin-runnable="true" kotlin-min-compiler-version="2.2" id="serialize-instant"} + +### Nothing + +The [`Nothing`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-nothing.html) type is serializable by default. +It has no instances, so encoding or decoding it throws an exception. +Use `Nothing` when a type is syntactically required, but not involved in serialization, like in [polymorphic classes with generic base types](serialization-polymorphism.md#serialize-polymorphic-types-with-generic-base-types): + +```kotlin +import kotlinx.serialization.* +import kotlinx.serialization.builtins.* +import kotlinx.serialization.json.* + +//sampleStart +@Serializable +sealed class ParametrizedParent { + @Serializable + data class ChildWithoutParameter(val value: Int) : ParametrizedParent() +} + +fun main() { + println(Json.encodeToString(ParametrizedParent.ChildWithoutParameter(42))) + // {"value":42} +} +//sampleEnd +``` +{kotlin-runnable="true" id="serialize-nothing"} + +## What's next + +* Dive into [Serialize classes](serialization-customization-options.md) to learn how to serialize classes and how to modify the default behavior of the `@Serializable` annotation. +* To explore more complex JSON serialization scenarios, see [JSON serialization overview](configure-json-serialization.md). +* Learn more about polymorphism and serializing different types through a shared base in [Serialize polymorphic classes](serialization-polymorphism.md). diff --git a/docs-website/topics/serialization.md b/docs-website/topics/serialization.md new file mode 100644 index 000000000..ea76e1bb9 --- /dev/null +++ b/docs-website/topics/serialization.md @@ -0,0 +1,75 @@ +[//]: # (title: Serialization) + +**Serialization** is the process of converting data used by an application to a format that can be transferred over a +network, or stored in a database or a file. Deserialization is the opposite process of converting external data back into a runtime object. +Together, they are essential to most applications that exchange data with third parties. + +Some data serialization formats, such as [JSON](https://www.json.org/json-en.html) and [Protocol Buffers](https://protobuf.dev/), are particularly common. +These formats are language-neutral and platform-neutral, so you can use them to exchange data between systems written in any modern language. +Kotlin provides this functionality through the [`kotlinx.serialization` libraries](#kotlin-serialization-libraries), +which support multiple platforms and data formats. + +If you're new to serialization in Kotlin, we recommend starting with the [Get Started with Serialization](serialization-get-started.md) tutorial. +It walks you through adding the Kotlin serialization library to your project and shows you how to serialize and deserialize your first class. + +Get started with serialization + +## Kotlin serialization libraries + +Kotlin serialization offers support for all platforms, including JVM, JavaScript, and Native. +You can use the same [dependency declaration](serialization-get-started.md#add-plugins-and-dependencies-for-kotlin-serialization) regardless of the target platform. + +Kotlin serialization supports various serialization formats, such as JSON, CBOR, and Protocol buffers through different serialization format libraries. +These libraries build on the core `kotlinx.serialization` library. +For the complete list of supported serialization formats, see [Supported serialization formats](#supported-serialization-formats). + +All Kotlin serialization format libraries are part of the `org.jetbrains.kotlinx:` group, with names +starting with `kotlinx-serialization-` and suffixes that reflect the serialization format. +For example: + +* `org.jetbrains.kotlinx:kotlinx-serialization-json` provides JSON serialization. +* `org.jetbrains.kotlinx:kotlinx-serialization-cbor` provides CBOR serialization. + +The `kotlinx.serialization` libraries follow their own versioning, independent of Kotlin. +You can find the latest release versions on [GitHub](https://github.com/Kotlin/kotlinx.serialization/releases). + +> When you're not using a specific format library, for example, when you're writing your own serialization format, +> use the `kotlinx-serialization-core` library as the dependency. +> +{style="tip"} + +## Supported serialization formats + +`kotlinx.serialization` includes serialization format libraries for various formats: + +| Format | Artifact ID | Platform | Status | +|--------------|--------------------------------------------------------------------------------------------------------------------------------|-------------------------|--------------| +| [JSON](https://www.json.org/json-en.html) | [`kotlinx-serialization-json`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#json) | All supported platforms | Stable | +| [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md) | [`kotlinx-serialization-hocon`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#hocon) | JVM only | Experimental | +| [Protocol Buffers](https://protobuf.dev/) | [`kotlinx-serialization-protobuf`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#protobuf) | All supported platforms | Experimental | +| [CBOR](https://cbor.io/) | [`kotlinx-serialization-cbor`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#cbor) | All supported platforms | Experimental | +| [Properties](https://en.wikipedia.org/wiki/.properties) | [`kotlinx-serialization-properties`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#properties) | All supported platforms | Experimental | + +All serialization format libraries, except for the JSON serialization library (`kotlinx-serialization-json`), are [Experimental](components-stability.md). Their APIs might change at any time. +For more details about JSON serialization, see [JSON serialization overview](configure-json-serialization.md). + +There are also community-maintained libraries that support more serialization formats, such as [YAML](https://yaml.org/) or [Apache Avro](https://avro.apache.org/). + +You can find out more about experimental serialization formats in [Alternative and custom serialization formats](alternative-serialization-formats.md). + +## Supported serialization types + +Kotlin serialization supports a variety of built-in types, including all primitive types and most composite types from the Kotlin standard library like the `List` type. +For more information, see [Serialize built-in types](serialization-serialize-builtin-types.md). + +Additionally, classes annotated with `@Serializable` are fully supported for serialization, enabling the conversion of class instances to and from formats like JSON. +For more information, see [Serialize classes](serialization-customization-options.md). + +## What's next + +* Learn the basics of Kotlin serialization in the [Get started with serialization tutorial](serialization-get-started.md). +* See how the Kotlin serialization library processes [primitives, collections, and other built-in types](serialization-serialize-builtin-types.md) +* Explore more complex JSON serialization scenarios in the [JSON serialization overview](configure-json-serialization.md). +* Dive into [Serialize classes](serialization-customization-options.md) to learn how to serialize classes and modify the default behavior of the `@Serializable` annotation. +* Learn how to define and customize your own serializers in [Create custom serializers](serialization-custom-serializers.md). +* See how to serialize different types through a shared base type in [Serialize polymorphic classes](serialization-polymorphism.md). \ No newline at end of file diff --git a/docs-website/v.list b/docs-website/v.list new file mode 100644 index 000000000..a82f92137 --- /dev/null +++ b/docs-website/v.list @@ -0,0 +1,7 @@ + + + + + + + \ No newline at end of file diff --git a/docs-website/writerside.cfg b/docs-website/writerside.cfg new file mode 100644 index 000000000..fb7df0af8 --- /dev/null +++ b/docs-website/writerside.cfg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + \ No newline at end of file