|
| 1 | +[//]: # (title: Serialization) |
| 2 | + |
| 3 | +**Serialization** is the process of converting data used by an application to a format that can be transferred over a |
| 4 | +network or stored in a database or a file. Deserialization is the opposite process of converting external data back into a runtime object. |
| 5 | +Together, they are essential to most applications that exchange data with third parties. |
| 6 | + |
| 7 | +Some data serialization formats, such as [JSON](https://www.json.org/json-en.html) and [Protocol Buffers](https://protobuf.dev/) are particularly common. |
| 8 | +Being language-neutral and platform-neutral, these formats enable data exchange between systems written in any modern language. |
| 9 | + |
| 10 | +To convert an object tree to a string or to a sequence of bytes, it must go through two mutually intertwined processes: |
| 11 | + |
| 12 | +1. Serialization: Objects are transformed into a sequence of their primitive values. |
| 13 | +This universal process varies depending on the object and is managed by a serializer. |
| 14 | +2. Encoding: The primitive sequence is converted into the desired output format, controlled by an encoder. |
| 15 | + |
| 16 | +{width=700} |
| 17 | + |
| 18 | +The reverse process involves parsing the input format, decoding the primitive values, and then deserializing the resulting |
| 19 | +stream into objects. |
| 20 | + |
| 21 | +If you're new to serialization in Kotlin, we recommend starting with the [Get Started with Serialization](serialization-get-started.md) guide. |
| 22 | +This section provides a step-by-step guide to help you set up and use Kotlin serialization in your projects. |
| 23 | +By following these steps, you can quickly get up to speed with the basics before diving into more complex topics. |
| 24 | + |
| 25 | +## Kotlin serialization libraries |
| 26 | + |
| 27 | +The `kotlinx.serialization` library offers support for all platforms, including JVM, JavaScript, Native. |
| 28 | +It works with various serialization formats, such as JSON, CBOR, and Protocol buffers. For the complete list of supported serialization, |
| 29 | +see the [supported formats](#supported-serialization-formats) section. |
| 30 | + |
| 31 | +All Kotlin serialization libraries are part of the `org.jetbrains.kotlinx:` group, with names |
| 32 | +starting with `kotlinx-serialization-` and suffixes that reflect the serialization format. |
| 33 | +For example: |
| 34 | + |
| 35 | +* `org.jetbrains.kotlinx:kotlinx-serialization-json` provides JSON serialization for Kotlin projects. |
| 36 | +* `org.jetbrains.kotlinx:kotlinx-serialization-cbor` provides CBOR serialization. |
| 37 | + |
| 38 | +Platform-specific dependencies are automatically managed, so you don’t need to add them manually. |
| 39 | +Use the same dependencies for JVM, JavaScript, Native, and multiplatform projects. |
| 40 | + |
| 41 | +The `kotlinx.serialization` libraries follow their own versioning structure, independent of Kotlin. |
| 42 | +You can check out the releases on [GitHub](https://github.com/Kotlin/kotlinx.serialization/releases) to find the latest versions. |
| 43 | + |
| 44 | +## Supported serialization formats |
| 45 | + |
| 46 | +`kotlinx.serialization` includes libraries for various serialization formats: |
| 47 | + |
| 48 | +* [JSON](https://www.json.org/json-en.html): [`kotlinx-serialization-json`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#json) |
| 49 | +* [Protocol buffers](https://protobuf.dev/): [`kotlinx-serialization-protobuf`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#protobuf) |
| 50 | +* [CBOR](https://cbor.io/): [`kotlinx-serialization-cbor`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#cbor) |
| 51 | +* [Properties](https://en.wikipedia.org/wiki/.properties): [`kotlinx-serialization-properties`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#properties) |
| 52 | +* [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) (only on JVM) |
| 53 | + |
| 54 | +All libraries except JSON serialization (`kotlinx-serialization-json`) are [experimental](components-stability.md), which means their API can be changed without notice. |
| 55 | +For more details about JSON serialization, see [JSON serialization overview](configure-json-serialization.md). |
| 56 | + |
| 57 | +There are also community-maintained libraries that support more serialization formats, such as [YAML](https://yaml.org/) or [Apache Avro](https://avro.apache.org/). |
| 58 | + |
| 59 | +You can find out more about experimental serialization formats in [Alternative and custom serialization formats](alternative-serialization-formats.md). |
| 60 | + |
| 61 | +## Supported serialization types |
| 62 | + |
| 63 | +Kotlin serialization supports a variety of built-in types, including all primitive types and composite types from the Kotlin standard library like the `List` type. |
| 64 | +For more information, see [Serialize built-in types](serialization-serialize-builtin-types.md). |
| 65 | + |
| 66 | +> Not all types from the Kotlin standard library are serializable. In particular, [ranges](ranges.md) and the [`Regex`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/) class are not serializable at the moment. |
| 67 | +> Support for their serialization may be added in the future. |
| 68 | +> |
| 69 | +{style="note"} |
| 70 | + |
| 71 | +Additionally, classes annotated with `@Serializable` are fully supported for serialization, enabling the conversion of class instances to and from formats like JSON. |
| 72 | +For more information, see [Serialize classes](serialization-customization-options.md). |
| 73 | + |
| 74 | +## What's next |
| 75 | + |
| 76 | +* Learn the basics of Kotlin serialization in the [Get started with serialization guide](serialization-get-started.md). |
| 77 | +* To explore more complex JSON serialization scenarios, see [JSON serialization overview](configure-json-serialization.md). |
| 78 | +* Dive into the [Serialize classes](serialization-customization-options.md) section to learn how to serialize classes and how to modify the default behavior of the `@Serializable` annotation. |
0 commit comments