Event schemas evolve compatibly

A change to a published event never breaks a consumer already reading it: fields are added, not renamed or removed.

HighChecked by hand

Applies to:
Services that publish events
Rule id:
events.schema-evolution

Why it matters

You can't deploy every consumer of an event at the same moment as its publisher, and old events stay in the log long after the code that wrote them is gone. A renamed or removed field breaks consumers you may not know exist, and breaks replay of history for everyone.

How to apply it

  • Only make additive changes: new optional fields with a default. Never rename, remove or change the type of a field.
  • When a change can't be compatible, publish a new event type or version alongside the old one, and retire the old one once nobody reads it.
  • Check compatibility in CI, with a schema registry or a contract test, so a breaking change fails the build.
  • Tell consumers to ignore fields they don't know.

Example

OrderPlaced gains an optional salesChannel. Old consumers ignore it and new ones read it. Changing total from a number to an object is not compatible, so the team publishes OrderPlaced.v2 next to v1 for a quarter, then stops v1 when the registry shows no readers.

References

Checklists with this rule

Related agent skill: event-driven-governance