Serialization with kotlinx.serialization
Apps constantly turn objects into JSON to send over the network or save to disk, and back again. kotlinx.serialization is Kotlin's official, compiler-driven library for exactly that.
Learn Serialization with kotlinx.serialization in our free Kotlin course — a beginner-friendly interactive lesson with worked examples, a practice exercise…
Part of the free Kotlin course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.
By the end you'll annotate classes with @Serializable , convert objects with Json.encodeToString and decodeFromString , and remap keys with @SerialName .
What You'll Learn in This Lesson
1️⃣ @Serializable, encode, and decode
Annotate a class with @Serializable , then use Json.encodeToString to turn an instance into JSON and Json.decodeFromString to parse it back.
No manual JSON building, no reflection at runtime — the compiler plugin generated a type-safe serializer for User .
2️⃣ Remapping Keys with @SerialName
When the JSON uses different key names than your Kotlin properties, @SerialName bridges the gap so your code stays idiomatic.
3️⃣ Serializing Collections
Collections of serializable types work directly — encode and decode a List<Task> with the same calls.
Your turn. Replace the TODO , then run and compare.
Mini-Challenge: Round-trip a Point
Encode a small object to JSON, decode it back, and prove the data survived the round trip.
Common Errors (and the fix)
- Missing @Serializable — Encoding a non-annotated class fails to compile. Add the annotation to the class.
- Forgetting the type on decode — Use decodeFromString<User>(json) so the library knows what to build.
- Key mismatch — If JSON keys differ from property names, add @SerialName .
- Unknown extra keys — Configure Json { ignoreUnknownKeys = true } to tolerate them.
Pro Tips
- 💡 Reuse a configured Json: create one Json { ... } instance with your settings and reuse it.
- 💡 Default values help: properties with defaults make decoding resilient to missing keys.
- 💡 Pair with Retrofit: a Json converter lets Retrofit decode responses straight into your data classes.
📋 Quick Reference — Serialization
Concept
Kotlin
Mark class
@Serializable data class User(...)
Object to JSON
Json.encodeToString(user)
JSON to object
Json.decodeFromString<User>(json)
Remap key
@SerialName("user_id") val userId
Lenient parse
Json { ignoreUnknownKeys = true }
Frequently Asked Questions
🎉 Lesson Complete!
- ✅ Serialization turns objects into JSON and back
- ✅ @Serializable enables a generated serializer
- ✅ encodeToString / decodeFromString do the conversion
- ✅ @SerialName remaps JSON keys
- ✅ Collections of serializable types work directly
- ✅ Next lesson: Networking with Retrofit
Practice quiz
What does serialization mean?
- Compiling code to bytecode
- Converting an object into a transferable format like JSON text
- Encrypting a password
- Running tests in order
Answer: Converting an object into a transferable format like JSON text. Serialization turns an in-memory object into a format (e.g. JSON) you can store or send.
Which annotation marks a class for kotlinx.serialization?
- @Json
- @SerializedName
- @Serializable
- @Serialize
Answer: @Serializable. @Serializable (from kotlinx.serialization) makes a class serializable.
Which call converts an object to a JSON string?
- Json.encodeToString(value)
- Json.toJson(value)
- value.serialize()
- Json.write(value)
Answer: Json.encodeToString(value). Json.encodeToString(value) produces the JSON text for a @Serializable object.
Which call parses a JSON string back into an object?
- Json.parse(text)
- Json.fromJson(text)
- Json.decodeFromString<T>(text)
- text.deserialize()
Answer: Json.decodeFromString<T>(text). Json.decodeFromString<T>(jsonString) reconstructs the object of type T.
What does @SerialName("user_id") do?
- Renames the class
- Maps a Kotlin property to a different JSON key name
- Makes the property private
- Marks it transient
Answer: Maps a Kotlin property to a different JSON key name. @SerialName customizes the JSON key for a property, e.g. userId <-> user_id.
Deserialization is the opposite of serialization. What does it produce?
- A JSON string
- An object reconstructed from the serialized data
- A compiled class
- A network request
Answer: An object reconstructed from the serialized data. Deserialization turns serialized text back into an in-memory object.
Which import provides the Json object in kotlinx.serialization?
- import org.json.JSONObject
- import com.google.gson.Gson
- import java.util.Json
- import kotlinx.serialization.json.Json
Answer: import kotlinx.serialization.json.Json. The Json entry point lives in kotlinx.serialization.json.
How do you serialize/deserialize a list of @Serializable items?
- You cannot serialize collections
- Convert each element to a string manually
- Json.encodeToString and decodeFromString work with List<T> directly
- Use a database
Answer: Json.encodeToString and decodeFromString work with List<T> directly. kotlinx.serialization supports List<T> (and other collections) of serializable types out of the box.
What is a common reason to configure Json { ignoreUnknownKeys = true }?
- To speed up the app
- To ignore JSON keys not present in your data class instead of throwing
- To encrypt the output
- To pretty-print only
Answer: To ignore JSON keys not present in your data class instead of throwing. ignoreUnknownKeys lets you tolerate extra fields in the JSON your model does not declare.
Why is kotlinx.serialization well suited to Kotlin compared to reflection-based libraries?
- It runs on the GPU
- It only works on Android
- It uses a compiler plugin for type-safe, reflection-free serialization
- It requires no annotations ever
Answer: It uses a compiler plugin for type-safe, reflection-free serialization. A compiler plugin generates serializers at build time, avoiding runtime reflection and supporting multiplatform.