Serialization

Why Serialization Matters on Android

Every REST API call exchanges JSON. Serialization is the process of converting Kotlin objects to JSON (serialization) and JSON back to Kotlin objects (deserialization). The library you choose affects performance, null safety, and code generation.

Gson (Google)

Gson uses reflection at runtime. No code generation. Works out of the box.

// build.gradle.kts
implementation("com.google.code.gson:gson:2.11.0")

data class User(
    val id: Long,
    val name: String,
    val email: String,
    val age: Int?
)

// Serialize
val user = User(1, "Alice", "alice@example.com", 30)
val json = Gson().toJson(user)

// Deserialize
val parsed = Gson().fromJson(json, User::class.java)

Problem: Gson does not distinguish between missing keys and null values. A missing age field deserializes as null, but so does "age": null. This causes subtle bugs when the server omits a field vs sends null.

Moshi (Square)

Moshi uses reflection but with better null safety. It also supports code generation via @JsonClass(generateAdapter = true).

// build.gradle.kts
implementation("com.squareup.moshi:moshi-kotlin:1.15.1")
implementation("com.squareup.moshi:moshi-kotlin-codegen:1.15.1")

@JsonClass(generateAdapter = true)
data class User(
    val id: Long,
    val name: String,
    val email: String,
    val age: Int? = null
)

val moshi = Moshi.Builder()
    .addLast(KotlinJsonAdapterFactory())
    .build()

val adapter = moshi.adapter(User::class.java)
val json = adapter.toJson(user)
val parsed = adapter.fromJson(json)

Moshi throws on unknown keys by default (fail-on-unknown). This catches API schema drift early.

kotlinx.serialization

A Kotlin-first library with compile-time code generation. No reflection. Best performance.

// build.gradle.kts
plugin("org.jetbrains.kotlin.plugin.serialization")
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")

@Serializable
data class User(
    val id: Long,
    val name: String,
    val email: String,
    @SerialName("age") val age: Int? = null
)

val json = Json {
    ignoreUnknownKeys = true
    coerceInputValues = true
}

val serialized = json.encodeToString(user)
val parsed = json.decodeFromString<User>(json)

coerceInputValues = true coerces null values from JSON to default values in Kotlin. ignoreUnknownKeys = true prevents crashes when the server adds new fields.

The Nullable Field Problem

APIs often omit fields rather than sending null. Your data class must handle both cases:

// Server returns {"id": 1, "name": "Alice"} without email or age

// Gson: age and email will be null (same as {"email": null})
// Moshi: age and email will use Kotlin defaults if defined
// kotlinx.serialization: use coerceInputValues = true

Recommended Pattern

@Serializable
data class User(
    val id: Long,
    val name: String,
    val email: String = "",           // Default for missing field
    val age: Int? = null,              // Nullable with default
    val metadata: Map<String, String> = emptyMap()  // Empty map default
)

Always provide defaults for optional fields. This prevents crashes when the server evolves its schema.

Custom Serializers for Complex Types

For types the library cannot handle automatically:

// kotlinx.serialization custom serializer for Instant
class InstantSerializer : KSerializer<Instant> {
    override val descriptor = PrimitiveSerialDescriptor("Instant", PrimitiveKind.STRING)

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

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

@Serializable
data class Event(
    val id: Long,
    @Serializable(with = InstantSerializer::class)
    val timestamp: Instant
)

Polymorphic Serialization

When a field can be one of several types, use sealed classes:

@Serializable
sealed class Result {
    @Serializable
    data class Success(val data: User) : Result()

    @Serializable
    data class Error(val code: Int, val message: String) : Result()
}

// Use JsonContentPolymorphicAdapter with Moshi
// or @JsonClassDiscriminator with kotlinx.serialization

Moshi Adapters vs TypeAdapters

Moshi adapters are faster than Gson TypeAdapters because they avoid boxing primitives. For performance-critical paths, write a custom JsonAdapter.Factory instead of using reflection-based adapters.