Kotlin Serialization: The Definitive Guide to JSON Parsing on Android

// build.gradle.kts (module)
plugins {
    id("com.android.library")
    // Same version as the Kotlin compiler
    id("org.jetbrains.kotlin.plugin.serialization") version "2.4.21"
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0")

    // Optional: Retrofit converter
    implementation("com.squareup.retrofit2:converter-kotlinx-serialization:3.0.0")

    // Optional: Ktor client
    implementation("io.ktor:ktor-serialization-kotlinx-json:3.6.0")
}

@Serializable
data class User(
    val id: Long,
    val email: String,
    val name: String,
    val role: UserRole = UserRole.VIEWER,                     // Default if the key is missing
    @SerialName("avatar_url") val avatarUrl: String? = null,  // Renamed, nullable
    @Transient val localTimestamp: Long = 0L                  // Never serialized
)

@Serializable
enum class UserRole {
    @SerialName("admin") ADMIN,
    @SerialName("editor") EDITOR,
    @SerialName("viewer") VIEWER
}

val json = Json { ignoreUnknownKeys = true }

// Checked here, when the string is decoded
val user: User = json.decodeFromString("""
    {"id": 42, "email": "dev@example.com", "name": "Rocky"}
""")
// user.role == UserRole.VIEWER (default applied)
// user.avatarUrl == null (default applied)

// {"id": 42, "email": null, "name": "Rocky"} would throw:
// email is declared non-null.

val jsonString: String = json.encodeToString(user)

@Serializable
sealed class PushNotification {
    abstract val id: String
    abstract val timestamp: Long

    @Serializable
    @SerialName("message")
    data class ChatMessage(
        override val id: String,
        override val timestamp: Long,
        val senderId: String,
        val text: String
    ) : PushNotification()

    @Serializable
    @SerialName("order_update")
    data class OrderUpdate(
        override val id: String,
        override val timestamp: Long,
        val orderId: String,
        val status: String
    ) : PushNotification()
}

// The "type" key picks the subclass
val notifications: List<PushNotification> = json.decodeFromString("""
    [
        {"type": "message", "id": "1", "timestamp": 1711540800, "senderId": "u42", "text": "Hello!"},
        {"type": "order_update", "id": "2", "timestamp": 1711540900, "orderId": "ord-99", "status": "shipped"}
    ]
""")

// Retrofit setup
val contentType = "application/json; charset=utf-8".toMediaType()

val jsonConfig = Json {
    ignoreUnknownKeys = true   // A new server field must not break old clients
    explicitNulls = false      // Omit null fields from request bodies
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/v1/")
    .addConverterFactory(jsonConfig.asConverterFactory(contentType))
    .build()

interface UserApi {
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Long): User

    @POST("users")
    suspend fun createUser(@Body request: CreateUserRequest): User
}

@Serializable
data class CreateUserRequest(
    val email: String,
    val name: String,
    val role: UserRole = UserRole.VIEWER
)

// Ktor setup
val client = HttpClient {
    install(ContentNegotiation) {
        json(jsonConfig)
    }
}

// Custom serializer with a unique, qualified descriptor name
object InstantSerializer : KSerializer<Instant> {
    override val descriptor: SerialDescriptor =
        PrimitiveSerialDescriptor("com.myapp.Instant", PrimitiveKind.STRING)

    override fun serialize(encoder: Encoder, value: Instant) {
        encoder.encodeString(value.toString())
    }

    override fun deserialize(decoder: Decoder): Instant =
        Instant.parse(decoder.decodeString())
}

// Option 1: name the serializer on the property
@Serializable
data class Event(
    val id: String,
    @Serializable(with = InstantSerializer::class)
    val createdAt: Instant
)

// Option 2: contextual. Mark the property AND register the serializer.
@Serializable
data class AuditEntry(
    val id: String,
    @Contextual val recordedAt: Instant
)

val json = Json {
    ignoreUnknownKeys = true
    serializersModule = SerializersModule {
        contextual(InstantSerializer)
    }
}

// Migration: one Retrofit instance per converter, one shared client
val legacyRetrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/v1/")
    .client(okHttpClient)
    .addConverterFactory(GsonConverterFactory.create())
    .build()

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/v1/")
    .client(okHttpClient)
    .addConverterFactory(jsonConfig.asConverterFactory(contentType))
    .build()

val ordersApi = legacyRetrofit.create(OrdersApi::class.java) // Not migrated yet
val userApi = retrofit.create(UserApi::class.java)           // Migrated