serialization.md

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 and Protocol Buffers are particularly common. Being language-neutral and platform-neutral, these formats enable data exchange between systems written in any modern language.

To convert an object tree to a string or to a sequence of bytes, it must go through two mutually intertwined processes:

1. Serialization: Objects are transformed into a sequence of their primitive values. This universal process varies depending on the object and is managed by a serializer.
2. Encoding: The primitive sequence is converted into the desired output format, controlled by an encoder.

{width=700}

The reverse process involves parsing the input format, decoding the primitive values, and then deserializing the resulting stream into objects.

If you're new to serialization in Kotlin, we recommend starting with the Get Started with Serialization guide. This section provides a step-by-step guide to help you set up and use Kotlin serialization in your projects. By following these steps, you can quickly get up to speed with the basics before diving into more complex topics.

Kotlin serialization libraries

The kotlinx.serialization library offers support for all platforms, including JVM, JavaScript, Native. It works with various serialization formats, such as JSON, CBOR, and Protocol buffers. For the complete list of supported serialization, see the supported formats section.

All Kotlin serialization 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 for Kotlin projects.
• org.jetbrains.kotlinx:kotlinx-serialization-cbor provides CBOR serialization.

Platform-specific dependencies are automatically managed, so you don’t need to add them manually. Use the same dependencies for JVM, JavaScript, Native, and multiplatform projects.

The kotlinx.serialization libraries follow their own versioning structure, independent of Kotlin. You can check out the releases on GitHub to find the latest versions.

Supported serialization formats

kotlinx.serialization includes libraries for various serialization formats:

• JSON: kotlinx-serialization-json
• Protocol buffers: kotlinx-serialization-protobuf
• CBOR: kotlinx-serialization-cbor
• Properties: kotlinx-serialization-properties
• HOCON: kotlinx-serialization-hocon (only on JVM)

All libraries except JSON serialization (kotlinx-serialization-json) are experimental, which means their API can be changed without notice. For more details about JSON serialization, see JSON serialization overview.

There are also community-maintained libraries that support more serialization formats, such as YAML or Apache Avro.

You can find out more about experimental serialization formats in Alternative and custom serialization formats.

Supported serialization types

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. For more information, see Serialize built-in types.

Not all types from the Kotlin standard library are serializable. In particular, ranges and the Regex class are not serializable at the moment. Support for their serialization may be added in the future.

{style="note"}

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.

What's next

• Learn the basics of Kotlin serialization in the Get started with serialization guide.
• To explore more complex JSON serialization scenarios, see JSON serialization overview.
• Dive into the Serialize classes section to learn how to serialize classes and how to modify the default behavior of the @Serializable annotation.