Get started with Kotlin serialization

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

// build.gradle.kts
plugins {
    kotlin("plugin.serialization") version "2.4.0"
}

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

// build.gradle
plugins {
    id 'org.jetbrains.kotlin.plugin.serialization' version '2.4.0'  
}

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

<!-- pom.xml -->
<properties>
    <kotlin.version>2.4.0</kotlin.version>
    <serialization.version>1.11.0</serialization.version>
</properties>

<build>
    <plugins>
        <plugin>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-plugin</artifactId>
            <version>${kotlin.version}</version>
            <executions>
                <execution>
                    <id>compile</id>
                    <phase>compile</phase>
                    <goals>
                        <goal>compile</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <compilerPlugins>
                    <plugin>kotlinx-serialization</plugin>
                </compilerPlugins>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>org.jetbrains.kotlin</groupId>
                    <artifactId>kotlin-maven-serialization</artifactId>
                    <version>${kotlin.version}</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

<dependencies>
    <dependency>
        <groupId>org.jetbrains.kotlinx</groupId>
        <artifactId>kotlinx-serialization-json</artifactId>
        <version>${serialization.version}</version>
    </dependency>
</dependencies>

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:

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

This dependency automatically includes the core serialization library as well.

Configure R8 for Kotlin serialization in Android projects

The Kotlin serialization library includes default ProGuard rules, so you don't need additional setup to keep serializers for all serializable classes after shrinking. 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 you use to your proguard-rules.pro file:

# 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;
}

# 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
{
    *;
}

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

Let's look at an example:

Import declarations from the necessary serialization libraries:
import kotlinx.serialization.* import kotlinx.serialization.json.*
Make a class serializable by annotating it with @Serializable:
@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.
Use the Json.encodeToString() function to serialize an instance of this class:
// 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"} }
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:
val bookList = listOf(Book(1937, "The Hobbit"), Book(1867, "War and Peace")) val jsonList = Json.encodeToString(bookList)

Deserialize objects from JSON

Deserialization converts a JSON string back into an object.

To deserialize an object from JSON in Kotlin:

Import declarations from the necessary serialization libraries:
import kotlinx.serialization.* import kotlinx.serialization.json.*
Make a class serializable by annotating it with @Serializable:
@Serializable data class Book(val yearPublished: Int, val title: String)
Use the Json.decodeFromString() function to deserialize an object from JSON:
// 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<Book>("""{"yearPublished":1937, "title": "The Hobbit"}""") println(obj) // Book(yearPublished=1937, title=The Hobbit) }

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.
Discover how to customize class serialization and adjust the default behavior of the @Serializable annotation in Serialize classes.
Dive deeper into handling JSON data and configuring JSON serialization in the JSON serialization overview.

16 June 2026