kotlin-serialization-wire-contract

name	kotlin-serialization-wire-contract
description	Use this skill to statically review kotlinx.serialization wire-contract safety and schema evolution: encodeDefaults/explicitNulls defaults and @EncodeDefault overrides, strict-decode ignoreUnknownKeys behavior, sealed-class closed polymorphism and class-discriminator conventions, and whether a schema change is additive or breaking given how defaults make a field optional on decode. Reads source and serializer configuration only; it never sends or receives real wire traffic.
allowed-tools	Read Grep Glob
metadata	{"author":"github: Raishin","version":"0.1.0","updated":"2026-07-21","category":"data","lifecycle":"experimental"}

kotlin-serialization-wire-contract

Purpose

This skill decides whether a kotlinx.serialization wire contract is safe to ship and safe to evolve. A contract is safe only when encode-side default/null behavior is understood by every consumer, decode-side strictness matches the deployment-coupling reality (lockstep vs rolling), polymorphic types crossing a trust boundary are closed (sealed) rather than open, and a proposed change is correctly classified additive or breaking given that a defaulted property is optional on decode.

Trigger conditions

• A user provides @Serializable classes, Json {} configuration, or a proposed schema change and asks whether it is wire-compatible.
• A user is diagnosing an unexpected SerializationException, a missing/extra field on the wire, or a polymorphic-decode failure.
• A user asks whether a producer and consumer that deploy independently (rolling deploy, mobile clients, separate services) can safely evolve a shared payload type.

When not to use

• The concern is a generic Java/Jackson deserialization vulnerability (default typing, ObjectInputStream, XXE) — route to java-deserialization-and-parser-security-agent.
• The concern is HTTP transport/endpoint production readiness (StatusPages, lifecycle, graceful shutdown) — route to kotlin-backend-production-readiness-agent.
• The concern is the type's binary/source API and ABI rather than its wire behavior — route to kotlin-library-api-abi-governance-agent.
• The concern is Kotlin language-level correctness (nullability platform types, value-class boxing) unrelated to wire behavior — route to kotlin-language-api-correctness-agent.
• The task requires sending or receiving real wire traffic, or real payloads — this skill is static-review only.

Lean operating rules

• CRITICAL — deserializing an open/abstract polymorphic hierarchy from untrusted or external input lets the discriminator value select any registered subtype, including ones the reviewer cannot enumerate from the visible source; require sealed (closed) polymorphism for any type hierarchy that crosses a trust boundary, and treat an open polymorphic hierarchy fed by untrusted input as a critical defect.
• CRITICAL — removing a property's default value, or adding a new required non-default property, to a type already deployed on the wire is a breaking change: a consumer or producer not upgraded in lockstep will fail to decode or silently diverge; require any such change be treated as a coordinated, versioned rollout, never a same-deploy change.
• HIGH — ignoreUnknownKeys defaults to false, so a decoder throws SerializationException on any field it does not declare; if the producer and consumer are not deployed in lockstep (rolling deploy, independent services, older mobile clients), the consumer must explicitly opt into ignoreUnknownKeys = true — flag a strict decoder consumed by a producer that can plausibly deploy new fields first.
• HIGH — encodeDefaults defaults to false, so a property left at its default value is omitted from the encoded payload entirely; flag any consumer code, schema documentation, or contract test that assumes a field is always present in the JSON without confirming the producer's encodeDefaults/@EncodeDefault configuration.
• HIGH — explicitNulls defaults to true, so a null value must be explicitly present in the payload and is required on decode unless the property carries a default — flag a nullable property assumed to be freely omittable on the wire without confirming explicitNulls is disabled or a default is present.
• MEDIUM — the class discriminator key defaults to "type" but is configurable per-Json instance (classDiscriminator) or per-hierarchy (@JsonClassDiscriminator); flag any polymorphic contract whose discriminator key or value set is not explicitly documented, since a producer/consumer mismatch on the discriminator convention breaks decoding silently rather than at compile time.
• MEDIUM — @EncodeDefault(EncodeDefault.Mode.ALWAYS) on a property forces it into the payload even when it holds its default, which is required when a downstream consumer's schema treats the field as always-present; flag any property a consumer treats as required but that is not marked on the producer side (or has at the class/format level).

References

Load these only when needed:

• Encode Defaults And Null Handling
• Decode Strictness And Schema Evolution
• Sealed Polymorphism And Class Discriminators
• Official Sources
• Safety Checklist

Response minimum

• A verdict (pass / pass-with-conditions / block) and the producer/consumer deployment-coupling assumption.
• Encode-defaults/null-handling, decode-strictness, polymorphism, and schema-evolution findings.
• A severity-labelled finding list, each with an evidence-basis label, and safe next actions plus any version-skew claim the user must confirm.