JSON serialization overview

The Kotlin serialization library allows you to easily convert Kotlin objects to JSON and back. The Json class is the primary tool for this, offering flexibility in how JSON is generated and parsed. You can configure Json instances to handle specific JSON behaviors or use its default instance for basic tasks.

With the Json class, you can:

Serialize Kotlin objects to JSON strings using the encodeToString() function.
Deserialize JSON strings back to Kotlin objects with the decodeFromString() function.
Work directly with the JsonElement when handling complex JSON structures using the encodeToJsonElement() and the decodeFromJsonElement() functions.
Use Experimental extension functions to serialize and deserialize I/O sources without creating intermediate strings, including JVM streams as well as kotlinx-io and Okio types.

Before you start, import the following declarations from the serialization library:

import kotlinx.serialization.*
import kotlinx.serialization.json.*

Here's a simple example that uses the default Json instance to show how JSON serialization works in Kotlin:

// Imports declarations from the serialization library
import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
@Serializable
data class User(val name: String, val age: Int)

fun main() {
    // Uses the default Json instance
    val json = Json

    // Creates a User object
    val user = User("Alice", 30)

    // Converts the User object to a JSON string
    val jsonString = json.encodeToString(user)
    println(jsonString)
    // {"name":"Alice","age":30}

    // Converts the JSON string back to a User object
    val deserializedUser = json.decodeFromString<User>(jsonString)
    println(deserializedUser)
    // User(name=Alice, age=30)
//sampleEnd
}

In addition to using the default configuration, you can customize the Json instance for specific use cases, such as ignoring unknown keys:

// Imports declarations from the serialization library
import kotlinx.serialization.*
import kotlinx.serialization.json.*

//sampleStart
@Serializable
data class Project(val name: String)

// Configures a Json instance to ignore unknown keys
val customJson = Json {
    ignoreUnknownKeys = true
}

fun main() {
    val data = customJson.decodeFromString<Project>("""
        {"name":"kotlinx.serialization","language":"Kotlin"}
    """)
    println(data)
    // Project(name=kotlinx.serialization)
}
//sampleEnd

What's next

Learn how to customize Json instances to address different use cases for serialization and deserialization.
Explore advanced JSON element handling to manipulate and work with JSON data before it is parsed or serialized.
Discover how to transform JSON during serialization and deserialization for more control over your data.

16 June 2026