kotlinx.serialization plugin

Active contributors: Dmitriy Novozhilov, Leonid Startsev, Kirill Rakhman

plugins/kotlinx-serialization/ is the compiler plugin behind kotlinx.serialization. When a class is annotated @Serializable, the plugin generates the corresponding KSerializer<T> implementation and the supporting serializer() companion methods, so the runtime library doesn't have to use reflection.

Purpose

Generate, at compile time, the KSerializer for every @Serializable class. The generated serializers know exactly which properties to encode/decode, in what order, with what default values, and across all Kotlin Multiplatform targets — without runtime reflection (which is unavailable on Kotlin/Native and expensive on Kotlin/JS).

Directory layout

plugins/kotlinx-serialization/
├── kotlinx-serialization-compiler-plugin.cli/     CLI / argument layer
├── kotlinx-serialization-compiler-plugin.common/  Common compiler-side helpers
├── kotlinx-serialization-compiler-plugin.k1/      K1 (descriptor-based) implementation
├── kotlinx-serialization-compiler-plugin.k2/      K2 (FIR) implementation
├── kotlinx-serialization-compiler-plugin.gradle/  Gradle helpers
├── tests/                                         Tests
└── ChangeLog.md

Key abstractions

Concept	Role
@Serializable	Marks a class for serialization-compiler-plugin processing.
@Polymorphic, @Serializer(forClass = ...), @SerialName	Auxiliary annotations the plugin recognizes.
Generated serializer() companion	A method on the companion object returning a KSerializer<T> for T.
Generated KSerializer impl	The materialized serializer — knows the descriptor, encoder, and decoder pattern.

How it works

graph LR
    Class["@Serializable<br/>data class Foo(val x: Int)"] --> FirExt["Serialization FIR ext"]
    FirExt -->|declares synthetic<br/>serializer() member| FirExt2["FIR with synthetic decls"]
    Fir2Ir --> IR["IR"]
    IR --> IrExt["Serialization IR ext"]
    IrExt -->|generates body<br/>of serializer() and KSerializer| IR2["IR with generated bodies"]
    IR2 --> Backend["JVM/JS/Wasm/Native"]

The plugin is split between K1 and K2 backends to support both frontend modes. Both produce equivalent IR. The IR stage is shared.

Generated serializer shape

For a class:

@Serializable
data class Foo(val x: Int, val y: String = "hi")

The plugin generates (roughly):

• A companion object with a serializer() method.
• A Foo$$serializer object implementing KSerializer<Foo>, with a descriptor listing properties in declaration order, a serialize method that encodes each property, and a deserialize method that decodes them and applies defaults.

Backward compatibility

The serializer descriptor and serialize/deserialize methods are part of the binary API of the class. Adding a property requires careful handling: a default value plus appropriate @OptionalProperty-style annotations to preserve compatibility. The plugin enforces some of this; the kotlinx.serialization documentation describes the rest.

KGP integration

libraries/tools/kotlin-serialization/ (KGP DSL) and libraries/kotlin-maven-serialization/ (Maven). Apply via:

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

Multiplatform

The plugin runs at the IR layer and is target-agnostic, so generated serializers work on every Kotlin target. The kotlinx.serialization runtime (kotlinx-serialization-core) and format libraries (kotlinx-serialization-json, -protobuf, ...) live in a separate repository.

Tests

plugins/kotlinx-serialization/tests/ run golden-file tests on the generated IR plus end-to-end tests that serialize/deserialize known fixtures.

Integration points

• Consumed by: every Kotlin project using kotlinx.serialization.
• Co-traveler: the kotlinx.serialization runtime libraries (separate repo).
• K1/K2 split: separate code paths in .k1 and .k2 subprojects.

Where to start

For a new annotation or an additional serializer-generation feature: split the work between .k2/ (FIR side) and the IR generator. Look at the existing @SerialName handling for a pattern.

See plugins/index.md for the broader plugin landscape.