practice

Streaming Schema Evolution

Changing the shape of events in a topic that has multiple independently deployed producers and consumers, plus retained history that still has to be readable.

schemacompatibilitystreaming

Schema change in streaming is harder than in a request-response API for a reason that is easy to miss: the topic contains history. An API change affects future calls; a topic change affects every consumer replaying from any retained offset, including a new consumer that starts from the beginning next year.

The compatibility modes are the vocabulary for the decision. Backward compatibility lets new consumers read old data — add optional fields, remove fields — and is what you need to upgrade consumers first. Forward compatibility lets old consumers read new data, needed when producers upgrade first. Full compatibility satisfies both and is the right default for a topic with consumers you do not control.

A schema registry with compatibility enforced at publish time is what makes this operational rather than aspirational: an incompatible schema is rejected by the producer's own client, before it reaches the topic and before it breaks anyone.

The changes that are genuinely hard have no clean answer: changing a field's type, changing units, or changing the semantic meaning of a field while keeping its name and type — the last being invisible to every compatibility check and the most damaging of the three. For those, the safe path is a new topic and a migration, not an in-place change.