@SerialName

Learn JSON key names with @SerialName.

What is @SerialName?

@SerialName is the annotation that changes the JSON counterpart of a property. It bridges a Kotlin property name and a JSON field name that differ.

Example: @Serializable data class User(@SerialName("user_name") val name: String). In this class the name property appears as user_name in JSON. When reading JSON it also looks for user_name. This adapts external JSON to existing Kotlin naming. The annotation goes right above the property declaration.

@SerialName usage examples

@SerialName is especially useful for JSON from APIs. JSON field names use snake_case while Kotlin uses camelCase.

Example: an API returns {"first_name": "Alex", "created_at": "2024-01-01"}. You write @SerialName("first_name") val firstName: String and @SerialName("created_at") val createdAt: String. This keeps Kotlin code readable while preserving JSON field names. Each property gets its own annotation. @SerialName only affects serialization; it does not change runtime behavior.

Exercise Map a field with @SerialName

Define a data class User(@SerialName("user_name") val name: String) marked with @Serializable. Inside main, print println("User ready").

Show example solution

@Serializable
data class User(@SerialName("user_name") val name: String)

fun main() {
    println("User ready")
}

Test yourself

Match @SerialName parts

@SerialName

Maps field name
user_name

JSON field
name

Kotlin property
@Serializable

Marks the class
When is @SerialName used?
- When the class is sealed
- When the property is null
- When the Kotlin property name differs from the JSON field name
- When prettyPrint is wanted
Show answer

When the Kotlin property name differs from the JSON field name — @SerialName bridges a name difference.

Complete the @SerialName call

@Serializable
data class User(@____("user_name") val name: String)

Show answer

@Serializable
data class User(@SerialName("user_name") val name: String)

Next lesson: @Optional

We Are Enhancing Your Experience

Cookie Preferences

Strictly Necessary Cookies

Analytical Cookies