JSON Annotations — Rename, Default, Optional

import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
data class ApiUser(
    @SerialName("user_id")     val userId: Long,
    @SerialName("display_name") val displayName: String,
    @SerialName("created_at")   val createdAt: String,
    val email: String? = null,                   // optional — default null
    val roles: List<String> = emptyList(),       // optional — default empty
    @Transient val passwordHash: String = "",    // NEVER serialized
)

val json = Json {
    encodeDefaults    = false           // omit fields equal to their default
    explicitNulls     = false           // omit null fields in output
    ignoreUnknownKeys = true            // server may add fields we don't care about
}

fun main() {
    val u = ApiUser(userId = 1, displayName = "Alice", createdAt = "2025-03-12")
    println(json.encodeToString(u))
    // {"user_id":1,"display_name":"Alice","created_at":"2025-03-12"}

    val incoming = """{"user_id":2,"display_name":"Bob","created_at":"2025-03-12","unknown_field":"ignored"}"""
    val parsed: ApiUser = json.decodeFromString(incoming)
    println(parsed)                              // ApiUser(userId=2, ...)
}