Serialization

Libraries

kotlinx.serialization provides sets of libraries for all supported platforms – JVM, JavaScript, Native – and for various serialization formats – JSON, CBOR, protocol buffers, and others. You can find the complete list of supported serialization formats below.

All Kotlin serialization libraries belong to the org.jetbrains.kotlinx: group. Their names start with kotlinx-serialization- and have suffixes that reflect the serialization format. Examples:

• org.jetbrains.kotlinx:kotlinx-serialization-json provides JSON serialization for Kotlin projects.

• org.jetbrains.kotlinx:kotlinx-serialization-cbor provides CBOR serialization.

Platform-specific artifacts are handled automatically; you don't need to add them manually. Use the same dependencies in JVM, JS, Native, and multiplatform projects.

Note that the kotlinx.serialization libraries use their own versioning structure, which doesn't match Kotlin's versioning. Check out the releases on GitHub to find the latest versions.

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)

Note that all libraries except JSON serialization (kotlinx-serialization-core) are Experimental, which means their API can be changed without notice.

There are also community-maintained libraries that support more serialization formats, such as YAML or Apache Avro. For detailed information about available serialization formats, see the kotlinx.serialization documentation.

Example: JSON serialization

Let’s take a look at how to serialize Kotlin objects into JSON.

Before starting, you’ll need to configure your build script so that you can use Kotlin serialization tools in your project:

1. Apply the Kotlin serialization Gradle plugin org.jetbrains.kotlin.plugin.serialization (or kotlin(“plugin.serialization”) in the Kotlin Gradle DSL).

   plugins { kotlin("jvm") version "1.6.0" kotlin("plugin.serialization") version "1.6.0" } 

   plugins { id 'org.jetbrains.kotlin.jvm' version '1.6.0' id 'org.jetbrains.kotlin.plugin.serialization' version '1.6.0' } 

2. Add the JSON serialization library dependency: org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.1

   dependencies { implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.1") } 

   dependencies { implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.1' } 

Now you're ready to use the serialization API in your code. The API is located in the the kotlinx.serialization package and its format-specific subpackages such as kotlinx.serialization.json.

First, make a class serializable by annotating it with @Serializable.

import kotlinx.serialization.Serializable @Serializable data class Data(val a: Int, val b: String) 

You can now serialize an instance of this class by calling Json.encodeToString().

import kotlinx.serialization.Serializable import kotlinx.serialization.json.Json import kotlinx.serialization.encodeToString @Serializable data class Data(val a: Int, val b: String) fun main() { val json = Json.encodeToString(Data(42, "str")) } 

As a result, you get a string containing the state of this object in the JSON format: {"a": 42, "b": "str"}

You can also serialize object collections, such as lists, in a single call.

val dataList = listOf(Data(42, "str"), Data(12, "test")) val jsonList = Json.encodeToString(dataList) 

To deserialize an object from JSON, use the decodeFromString() function:

import kotlinx.serialization.Serializable import kotlinx.serialization.json.Json import kotlinx.serialization.decodeFromString @Serializable data class Data(val a: Int, val b: String) fun main() { val obj = Json.decodeFromString<Data>("""{"a":42, "b": "str"}""") } 

For more information about serialization in Kotlin, see the Kotlin Serialization Guide.