Versioning With Old Clients in the Wild

Assume every response field you ever shipped is read by some installed app. Rules: only additive changes within a version, never change a field's type or meaning, give enums an unknown fallback on clients (tolerant reader), and send the app version with every request (User-Agent: ExampleApp/5.12.0 (iOS 18.1) or X-App-Version) so you can measure who still uses old behavior before removing it.

Change safety matrix

@Serializable
enum class OrderStatus { PENDING, PAID, SHIPPED, @SerialName("unknown") UNKNOWN }

val json = Json {
    ignoreUnknownKeys = true            // new fields don't crash old apps
    coerceInputValues = true            // unknown enum values → default
}
@Serializable data class Order(val id: String, val status: OrderStatus = OrderStatus.UNKNOWN)

enum OrderStatus: String, Decodable {
    case pending, paid, shipped, unknown
    init(from decoder: Decoder) throws {
        let raw = try decoder.singleValueContainer().decode(String.self)
        self = OrderStatus(rawValue: raw) ?? .unknown
    }
}

Common pitfalls

• Strict decoders that crash on unknown fields or enum values.
• Removing a field because the latest app doesn't use it.
• No app-version telemetry, so you can't tell who is affected.

Key points

• Additive-only within a version
• Tolerant readers on clients
• Track app versions per request

Further reading: Martin Fowler: Tolerant Reader