Kotlinx.serialization: Kotlin's Native Data Converter

Why it exists

Applications constantly need to send data over a network or store it in a file. This requires converting in-memory objects, like a Kotlin data class, into a standard format like JSON and then back again. Kotlinx.serialization provides a first-party, type-safe, and performant way to handle this directly in Kotlin without relying on third-party libraries that use reflection.

The mental model

Think of kotlinx.serialization as a built-in translator for your Kotlin data classes. You annotate a class with @Serializable, and a compiler plugin automatically writes the conversion logic for you. You give the library an object, and it gives you back a JSON string. You give it a JSON string and a type, and it gives you back a matching object.

How it works

The process has three parts. First, apply the kotlin("plugin.serialization") plugin in your Gradle build script. Second, add a dependency for the specific format you need, like kotlinx-serialization-json. Third, annotate your data class with @Serializable. The compiler plugin then generates the necessary code behind the scenes. To use it, you call functions like Json.encodeToString(myObject) to serialize and Json.decodeFromString<MyClass>(jsonString) to deserialize.

When to use it

Use kotlinx.serialization for most standard serialization tasks in a modern Kotlin project. It is the idiomatic choice for consuming JSON APIs in Android apps, building Ktor backends, or writing multiplatform code that needs to share data models and serialization logic across JVM, JavaScript, and Native targets.

When not to use it

If you need to work with a format not officially supported (like YAML or Avro), you'll need a community-maintained or third-party library. Be cautious using the non-JSON formats like Protobuf or CBOR in production, as their APIs are marked Experimental and can change. For legacy projects with heavy investment in other libraries like Gson or Moshi, a full migration might not be practical.

One canonical example

To serialize a project object, first define the class: @Serializable data class Project(val name: String, val active: Boolean). Then, create an instance and encode it: val project = Project(name = "KMP App", active = true). The call Json.encodeToString(project) produces the JSON string {"name":"KMP App","active":true}. To reverse the process, Json.decodeFromString<Project>("{\"name\":\"KMP App\",\"active\":true}") recreates the original Project object.