Walk through the three synthetic artifacts the kotlinx.serialization plugin generates for a @Serializable class and the role of each.
answer
- $serializer object = the engine
- SerialDescriptor = the shape/metadata
- serialize/deserialize = the read+write loop
- decodeElementIndex loop + DECODE_DONE
- Bitmask tracks seen fields for defaults
basics
~20 sFor 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 sThe 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@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
Can name the serializer, descriptor, and serialize/deserialize even if fuzzy on the loop details.
Explains the index-based encode/decode loop and that the descriptor carries field metadata.
Describes the seen-field bitmask, synthetic constructor marker, decodeSequentially fast path, and how one $serializer serves many formats.
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