A team needs to change the schema of an event that many consumers read. What is the safe process?

The safe process

• Additive changes only, by default. New optional fields with defaults, which existing consumers ignore. This requires the tolerant-reader contract to have been established before the first version — unknown fields ignored, unknown enum values defaulted — because consumers written without it break on an added field.
• A schema registry with an enforced compatibility mode, so an incompatible change is rejected at publication rather than discovered by a consumer.
• For a genuinely breaking change: a new event type, published alongside the old, with consumers migrating on their own schedule and the old type deprecated with a notice period.
• Usage telemetry per consumer per field, since "who reads this field" must be answerable before it can be removed — and without it, removal either never happens or breaks someone unknown.

The change that no compatibility check catches

A semantic change with an identical shape: an event that now fires at a different point in a lifecycle, a status value reused for a new case, a field whose units changed.

Nothing breaks, no schema check fails, and consumer behaviour quietly diverges. This is the hardest failure to detect in an event-driven system, and the only defences are documented semantics, a consumer registry, and the discipline of emitting a new event type rather than redefining an existing one.

What must be documented alongside the schema

Exactly when the event fires, what each value means, units, timezone, and what it does not mean. The negative statements are the valuable ones, and they are what a consumer needs to avoid an assumption the producer never intended.

The organisational requirement

A consumer registry. Without knowing who consumes what, a producer cannot assess a change and therefore does not make one — which is the coupling that event-driven architecture was adopted to avoid, in a less visible form.

A platform that makes producers unable to evolve has failed differently from one that breaks consumers, and the second failure is at least visible.