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