skip to content

Walk through the three synthetic artifacts the kotlinx.serialization plugin generates for a @Serializable class and the role of each.

level: middleimportance: must knowfreq 55%

answer

  1. $serializer object = the engine
  2. SerialDescriptor = the shape/metadata
  3. serialize/deserialize = the read+write loop
  4. decodeElementIndex loop + DECODE_DONE
  5. Bitmask tracks seen fields for defaults

basics

~20 s

For each @Serializable class the plugin adds a hidden serializer object, a descriptor that lists the fields, and the functions that turn the object into data and back. Together they replace what reflection would do.

solid answer

~30 s

The plugin generates: (1) a nested synthetic object `$serializer` implementing `KSerializer<T>`; (2) its `SerialDescriptor`, built via `buildClassSerialDescriptor`/`PluginGeneratedSerialDescriptor`, listing each element's serial name, index, kind, optionality and nullability; (3) the `serialize(encoder, value)` and `deserialize(decoder)` overrides. `serialize` calls `encoder.beginStructure(descriptor)` then `encodeXxxElement(descriptor, index, value)` per property and `endStructure`. `deserialize` calls `decoder.beginStructure`, loops on `decodeElementIndex` until `CompositeDecoder.DECODE_DONE`, decodes each element, then constructs the object — tracking which optional fields were seen with a bitmask so it can apply default values. The plugin also synthesizes the companion `serializer()` accessor. Everything is keyed by **index**, which is why it needs no name-based reflection.

code

kotlin · 10 lines
kotlin
@Serializable
data class Point(val x: Int, val y: Int = 0)

fun main() {
    val d = Point.serializer().descriptor
    println(d.serialName)            // Point
    println(d.elementsCount)         // 2
    println(d.getElementName(1))     // y
    println(d.isElementOptional(1))  // true (has default)
}

go deeper

for a junior

Can name the serializer, descriptor, and serialize/deserialize even if fuzzy on the loop details.

for a middle

Explains the index-based encode/decode loop and that the descriptor carries field metadata.

for a senior

Describes the seen-field bitmask, synthetic constructor marker, decodeSequentially fast path, and how one $serializer serves many formats.

for a principal

Reasons about IR-level synthesis, descriptor caching/identity, and the contract that keeps formats decoupled from generated code.

## The three artifacts For `@Serializable class T`, the compiler plugin emits, at the IR/bytecode level: ### 1. `T.$serializer : KSerializer<T>` A **nested synthetic object** (singleton). `KSerializer<T>` combines `SerializationStrategy<T>` (write) and `DeserializationStrategy<T>` (read) plus a `descriptor`. This object is the engine the format (JSON/ProtoBuf/CBOR) calls. ### 2. `descriptor: SerialDescriptor` Describes the **shape** without the data: the class's `serialName`, the number of elements, and per element the serial name, **index**, `SerialKind`, whether it's `isOptional` (has a default), and whether it's nullable. The plugin uses an internal `PluginGeneratedSerialDescriptor`; you can build an equivalent by hand with `buildClassSerialDescriptor("T") { element<Int>("id") }`. Formats walk the descriptor to decide structure (object vs list), keys, and required-ness. ### 3. `serialize` and `deserialize` ```kotlin // Simplified shape of generated code override fun serialize(encoder: Encoder, value: T) { val out = encoder.beginStructure(descriptor) out.encodeIntElement(descriptor, 0, value.id) out.encodeStringElement(descriptor, 1, value.name) out.endStructure(descriptor) } override fun deserialize(decoder: Decoder): T { val inp = decoder.beginStructure(descriptor) var id = 0; var name = "" var bitMask = 0 // tracks which fields were read (for defaults) while (true) { when (val i = inp.decodeElementIndex(descriptor)) { 0 -> { id = inp.decodeIntElement(descriptor, 0); bitMask = bitMask or 1 } 1 -> { name = inp.decodeStringElement(descriptor, 1); bitMask = bitMask or 2 } CompositeDecoder.DECODE_DONE -> break else -> throw SerializationException("Unexpected index $i") } } inp.endStructure(descriptor) return T(id, name) } ``` ## Key mechanics - **Index-based:** every call passes a numeric `index`, not a string — no map/reflection lookup. - **Sequential fast path:** for trivially ordered input the runtime may use `decodeSequentially()` and skip the index loop. - **Bitmask for defaults:** the generated `deserialize` (and a synthetic constructor with a trailing `Int` seen-mask + `SerializationConstructorMarker`) records which optional fields appeared so defaults fill the rest. This is also why missing **non-optional** fields raise `MissingFieldException`. - **Companion accessor:** the plugin adds `companion object { fun serializer(): KSerializer<T> = $serializer }` (creating a companion if none exists). For generic types it generates `serializer(vararg typeParams: KSerializer<*>)`. ## Why three pieces, not one The split lets formats stay generic: the **descriptor** answers structural questions, while **serialize/deserialize** drive the actual byte/char stream through the abstract `Encoder`/`Decoder`. The same `$serializer` therefore works for JSON, ProtoBuf, CBOR, etc., with no per-format code.

  • Why does the generated deserialize use a bitmask?
    To record which fields actually appeared in the input so defaults are applied to absent optional fields and a MissingFieldException is thrown for absent required ones.
  • What is decodeSequentially() for?
    A fast path: when the decoder guarantees elements arrive in descriptor order with none missing, the generated code reads them directly without the index loop.

  • Saying deserialize reads fields by name lookup
  • Not knowing the descriptor is separate from serialize/deserialize
  • Claiming defaults work without any seen-field tracking
  • Thinking the serializer is regenerated on every call instead of being a singleton object
  • Confusing SerialDescriptor with the encoded output itself

context