@SerialName & Custom Field Mapping
Match Kotlin names to mismatched JSON keys.
@SerialName & Custom Field Mapping is a free Kotlin Multiplatform Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Kotlin Multiplatform Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Names Do Not Always Match
Real APIs love keys like user_name, but Kotlin prefers userName. @SerialName lets the two disagree peacefully.
Rename a Single Field
Put @SerialName above a property to tell the serializer which JSON key it really maps to.
@SerialName("user_name") val userName: StringKotlin Stays Idiomatic
Your code keeps clean camelCase names while the wire format keeps whatever the backend chose. Both sides win.
Snake Case Is Common
Many JSON APIs use snake_case, so mapping created_at to a createdAt property is one of the most frequent uses.
@SerialName("created_at") val createdAt: StringMap Reserved Words
If JSON has a key like type that clashes with your style, @SerialName frees you to name the property whatever reads best.
@SerialName("type") val kind: StringWorks on Every Field
You can annotate as many properties as you like, mixing renamed and default-named fields inside the same data class.
Rename Enum Entries Too
@SerialName also works on enum constants, so an ACTIVE entry can serialize as the lowercase string the API expects.
@SerialName("active") ACTIVEGlobal Naming Strategy
If every key is snake_case you can set a JsonNamingStrategy once instead of annotating each field by hand.
Json { namingStrategy = JsonNamingStrategy.SnakeCase }Annotation Wins
When both a global strategy and an explicit @SerialName apply, the annotation takes priority for that one field.
Same Class, Both Ways
The custom names apply to both encoding and decoding, so one annotated model handles reading and writing JSON.
Decoupled From the Backend
Mapping keys explicitly means a backend rename only touches one annotation, not your whole codebase.
Quick Check
How do you map a JSON key to a differently named Kotlin property?
Recap
Use @SerialName to map mismatched JSON keys to idiomatic Kotlin names on fields and enums, or set a global naming strategy for whole models.
Frequently asked questions
Is the “@SerialName & Custom Field Mapping” lesson free?
Yes — the full text of “@SerialName & Custom Field Mapping” is free to read here on the web, and the Kotlin Multiplatform Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Kotlin Multiplatform Academy course, upgrade to CoddyKit PRO.
What will I learn in “@SerialName & Custom Field Mapping”?
Match Kotlin names to mismatched JSON keys. You practise Kotlin Multiplatform Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Kotlin Multiplatform Academy?
No prior experience is required. Kotlin Multiplatform Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “@SerialName & Custom Field Mapping” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Kotlin Multiplatform Academy lesson?
Yes. Every Kotlin Multiplatform Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- @Serializable Data Models
- @SerialName & Custom Field Mapping
- Nullable, Default & Optional Fields
- Plug Serialization into Ktor