kafka schema registry compatibility modes
Explains Schema Registry compatibility modes and which to pick. Use it when evolving Avro, Protobuf, or JSON schemas, when a schema update gets rejected, or when consumers break after a producer change. Not for schemaless JSON topics.
TL;DR
BACKWARD lets new consumers read old data (safe when you add fields with defaults); FORWARD lets old consumers read new data (safe when you remove fields carefully); FULL requires both; NONE checks nothing. TRANSITIVE variants check against every past version instead of just the latest. For most event topics, BACKWARD is the right default, and rejected schema updates usually mean the change broke the mode you picked.
The query
kafka schema registry compatibility modesUse this when
- a schema update was rejected by the registry and you need to know why
- consumers broke after a producer changed its schema
- you are setting the compatibility mode for a new topic
Not for
- topics with no schema registry at all, like plain JSON
- Kafka ACLs or authentication, which are separate from schemas
Steps
- Check the current mode for the subject before changing anything. Surprises here cause most breakages.
Expected output: You know the active mode for the subject you are changing.
- For BACKWARD, only add fields with defaults; never rename or change a field's type in place.
Expected output: The new schema registers cleanly under BACKWARD mode.
- Use FULL when multiple independent teams consume the topic and you cannot coordinate upgrades.
Expected output: Both old and new consumers keep working across the change.
- Prefer TRANSITIVE modes when old schema versions can still reappear (long retention, replays).
Expected output: The registry validates against the full version history.
- Test the evolution against a staging subject first, with a real consumer on each side.
Expected output: Both the old and new consumers read the new data in staging.
Provenance
Resolved from the public thread: https://vectle.com/posts/pstIzQf7gKsTNLHCGqGyYMTA