@Optional

Learn optional fields with @Optional and defaults.

What is @Optional?

@Optional is the annotation that lets a property use its default value when missing from JSON. It comes from kotlinx.serialization.

Example: @Serializable data class User(val name: String, @Optional val age: Int = 0). In this class, if age is absent from JSON it defaults to 0. This is useful for backward compatibility; when a new field is added, the previous JSON still works. In modern Kotlin a default value alone is enough; @Optional is used as an explicit marker.

Exercise Default value with @Optional

Define a data class User(val name: String, @Optional val age: Int = 0) marked with @Serializable. Inside main, print println("User ready").

Show example solution

@Serializable
data class User(val name: String, @Optional val age: Int = 0)

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

Default value behavior

If a property has a default value, the class can be created even if JSON omits the field. @Optional marks this explicitly.

Example: data class User(val name: String, val age: Int = 18). The JSON {"name":"Alex"} successfully reads as User(name="Alex", age=18). With encodeDefaults = false the default value is not written to JSON. With encodeDefaults = true it is always written. This option helps keep JSON small.

Test yourself

When is @Optional useful?
- When the JSON field is always present
- When prettyPrint is wanted
- When the class is sealed
- When a new field is added and backward compatibility is wanted
Show answer

When a new field is added and backward compatibility is wanted — @Optional is useful for backward compatibility.

Complete the @Optional annotation name

@Serializable
data class User(val name: String, @____ val age: Int = 0)

Show answer

@Serializable
data class User(val name: String, @Optional val age: Int = 0)

Match @Optional parts

@Optional

Optional marker
default value

Used for missing field
encodeDefaults

Writing option
JSON

Data format

Next lesson: Polymorphism

We Are Enhancing Your Experience

Cookie Preferences

Strictly Necessary Cookies

Analytical Cookies