What does the @ExperimentalSerializationApi status of ProtoBuf/CBOR mean in practice, and how do you handle it in production code?

## What 'experimental' means Kotlin has an **opt-in** system (`@RequiresOptIn`). kotlinx.serialization marks parts of its API with `@ExperimentalSerializationApi`, including the binary formats and annotations like `@ProtoNumber`. This signals: the API may change, and there is **no binary-compatibility guarantee** across versions. ## How the compiler reacts Touching an experimental API without opting in produces a warning (or error, depending on config). You resolve it explicitly: ```kotlin @OptIn(ExperimentalSerializationApi::class) fun encode(u: User): ByteArray = ProtoBuf.encodeToByteArray(u) ``` Or project-wide: ```kotlin // build.gradle.kts kotlin { compilerOptions { optIn.add("kotlinx.serialization.ExperimentalSerializationApi") } } ``` Prefer **local** `@OptIn` so you stay aware of every experimental touch point rather than silencing the whole project. ## Production discipline - **Opt in deliberately**, ideally close to the call, not via a blanket suppression that hides future surprises. - **Pin the version** of `kotlinx-serialization` and bump intentionally. - **Isolate** format access behind a thin adapter (one `encode`/`decode` boundary) so a breaking change is a one-file fix. - **Golden/round-trip tests**: assert `decode(encode(x)) == x` and keep byte-level fixtures so a wire change is caught by CI before it reaches consumers. - **Read release notes** when upgrading; experimental APIs are exactly where changes land. ## What is NOT experimental The `@Serializable` annotation and the core JSON format are stable. Only the binary format surface (and some advanced APIs) carry the experimental marker, so the risk is contained to that boundary.