Event Schema Evolution
Change event contracts safely while old producers, new consumers, retained logs, and replay coexist.
2–5 minute refresher
P0104105106107
P181828384
Consumer group A · offset 106Consumer group B · offset 82
An event contract must survive versions moving independently in both time directions.
30second
refresher
refresher
Event producers and consumers deploy independently, while retained events may be replayed months later. Schema evolution defines how fields, meanings, defaults, and versions change without coordinated downtime.
What problem does it solve?
A field rename or semantic change can break live consumers, corrupt projections during replay, or silently change the meaning of historical data.
How it works
- Define an owned contract and compatibility policy.
- Prefer additive optional fields with safe defaults.
- Deploy tolerant readers before new writers.
- Version semantic breaks explicitly rather than reusing fields.
- Test new consumers against retained historical samples and replay.
Decision guide
Key trade-offs
| Choice | What you gain | What it costs |
|---|---|---|
| Backward compatible | New readers handle old data | Defaults preserve legacy meaning |
| Forward compatible | Old readers tolerate new data | Unknown fields must be ignorable |
| New event type | Clean semantic boundary | Migration and dual consumption |
What happens if?
A field keeps its type but changes meaning
amount remains an integer but changes from cents to micros. Every schema check passes while consumers calculate values incorrectly. Semantic versioning and contract tests must cover units and invariants.
Where it appears
- Kafka contracts
- CDC streams
- Data lakes
- Workflow events
Senior interview modeIs adding an optional field always safe?Show answer
Only syntactically. A default can still change behavior, validation, ordering, privacy, or downstream storage. Compatibility requires testing real consumers and historical replay, not only the schema registry.