Polymorphic JSON with Jackson and Kotlin Sealed Types

Polymorphism is the one place where JSON and Kotlin's type system disagree the most. A `sealed interface` or `sealed class` models a closed set of variants beautifully in code, but on the wire JSON is just untyped objects. When you serialize a `PaymentMethod` that is really a `CreditCard`, the resulting JSON has no idea which subtype it came from. On the way back in, Jackson sees an abstract type and has no way to pick a concrete class. The fix is to embed a small type discriminator in the JSON and tell Jackson how to read it. That is exactly what `@JsonTypeInfo` and `@JsonSubTypes` do.

`@JsonTypeInfo` is placed on the base type (the sealed interface or class) and answers two questions: how is the type encoded, and where does it live? The most common and most readable choice is `use = JsonTypeInfo.Id.NAME` together with `include = JsonTypeInfo.As.PROPERTY` and a `property = "type"`. This produces a logical name (like `"credit_card"`) stored in a sibling field called `type`, rather than a fully-qualified Java class name. Using logical names instead of `Id.CLASS` is important: class names leak your package structure, break the moment you rename or move a class, and are a security risk because they let a payload pick which class gets instantiated.

`@JsonSubTypes` is the registry that maps each logical name to a concrete subclass. You annotate the base type with a list of `@JsonSubTypes.Type` entries, each pairing a `value` (the Kotlin class) with a `name` (the discriminator string). Because the names are explicit, the JSON contract is now decoupled from your code: you can rename `CreditCard` to `CardPayment` in Kotlin without changing a single byte of the public API, as long as the `name = "credit_card"` stays put. This is the whole reason to prefer the annotation approach over reflection-based defaults.

Kotlin sealed types are the ideal carrier for this pattern because exhaustiveness is enforced by the compiler, not by hope. Once Jackson hands you back a `PaymentMethod`, a `when` expression over its subtypes needs no `else` branch, and adding a new variant turns every consumer into a compile error until it is handled. Pair that with `data class` variants so you get structural `equals`, `copy`, and a sane `toString` for free. Annotate the variants' constructor parameters, and remember that Jackson on Kotlin needs the `jackson-module-kotlin` module registered so it can see your primary constructors and `val` properties.

Round-tripping an ADT means `deserialize(serialize(x)) == x` for every value in the type. With `data class` variants this equality check is real and testable, which makes it a great invariant to assert in a unit test. The discriminator field is symmetric: Jackson writes it on the way out and consumes it on the way in, so as long as both sides share the same `ObjectMapper` configuration, values survive the trip intact. Watch out for two gotchas: a missing discriminator in incoming JSON throws an `InvalidTypeIdException`, and an unknown discriminator value does too unless you configure a `defaultImpl` fallback.

Configuration matters as much as the annotations. Register the Kotlin module (`jacksonObjectMapper()` from `jackson-module-kotlin` does this for you), and for Kotlin's nullability to be respected, that module is what teaches Jackson that a non-null `val` is actually required. In a Spring Boot 3 application you usually do not build the mapper by hand at all; Boot autoconfigures one and, if `jackson-module-kotlin` is on the classpath, registers it automatically. You can still customize it with a `Jackson2ObjectMapperBuilderCustomizer` bean to add modules like `JavaTimeModule` or to set `FAIL_ON_UNKNOWN_PROPERTIES` to false for forward compatibility.

There is also a placement subtlety worth internalizing. `include = As.PROPERTY` puts the discriminator alongside the data fields, which is the friendliest format for most REST clients. `As.EXISTING_PROPERTY` is the right choice when the subtype itself already declares a `val type` field that you want serialized as both real data and the discriminator, avoiding a duplicate or phantom field. `As.WRAPPER_OBJECT` nests the payload under a key named by the type, which some event schemas prefer. Pick one deliberately and document it, because changing it later is a breaking change to every stored or in-flight message.

Finally, this pattern scales naturally to event sourcing and message queues, where you persist a stream of heterogeneous events as JSON and must reconstruct their exact Kotlin types later. A sealed `DomainEvent` hierarchy with stable discriminator names gives you a durable, versionable contract: old events keep deserializing because their `name` never changes, and new event types are added to `@JsonSubTypes` without disturbing the rest. Keep the discriminator names in a single place, treat them as part of your public schema, and never derive them from class names you might one day refactor.