zero gravitySOLUTIONS
← All insightsBACKEND & RELIABILITY / COMPATIBILITY ROLLOUT GUIDE

Evolving Kafka events with old consumers

QUICK ANSWER

Event schema evolution must support the producer and consumer versions that coexist, including historical records. Schema-registry compatibility is a useful structural gate, but consumer behavior needs separate tests for defaults, enums, meaning changes, and replay. Choose rollout order from the required compatibility direction.

Inside this article 5 sections

A new event schema enters a system where not everything upgrades together. One consumer may deploy immediately, another may be maintained by a partner, and a rebuilding projection may read records written months earlier. The compatibility question is therefore about a set of writers, readers, and retained data, not just the latest producer and latest consumer.

Use a shipment event that originally contains a single delivery address. A new product requirement introduces several delivery stops. Replacing the old address with a list may look like a straightforward data-model improvement, but an older invoicing consumer still expects one destination and may apply business rules that the new model no longer satisfies.

Draw the reader-writer matrix

Backward compatibility asks whether a new reader can consume older data. Forward compatibility asks whether an old reader can consume newly written data. Full compatibility requires both directions under the schema system's rules. Transitive checks extend the comparison beyond only the immediately previous version. These definitions help select a gate, but the actual allowed changes depend on the serialization format and configuration.

List the versions that must coexist before choosing rollout order. If old consumers must continue reading new events, testing only a new consumer against old fixtures is insufficient. If a new projection rebuilds from the retained log, validating only the newest producer payload is also insufficient. Keep those two responsibilities separate in the release checklist.

Minimum producer-reader fixtures for a shipment event change
Writer payloadReaderRequired assertion
Existing versionExisting consumerBaseline behavior remains unchanged
Existing versionNew consumerHistorical replay produces the intended projection
New versionExisting consumerCoexistence is valid or explicitly prevented by routing
New versionNew consumerNew capability works without changing old meaning
Passing deserialization is only the first assertion. Each cell also checks the business result produced by that reader.

Use additive changes only when meaning stays stable

An optional field can be structurally compatible while changing behavior. Suppose a new delivery_mode field defaults to standard. An old event that predates delivery modes may actually mean unknown, not standard. Choosing a convenient default can rewrite the interpretation of historical records during replay.

New enum values can also break consumers that deserialize successfully but use exhaustive business switches. Test the fallback path explicitly. Decide whether an unknown value means reject, hold for review, or preserve the raw value without acting. Silently selecting a familiar value can be worse than a visible failure when the event controls fulfillment.

Do not change units under an existing field name. A number representing kilograms must not begin representing grams merely because the schema still accepts an integer. Add an explicit field or a new event contract with defined conversion, and test historical values. Structural compatibility systems cannot infer that a field's commercial meaning changed.

Keep transport identity separate from event meaning

An event envelope can carry a stable event identifier, business entity identifier, occurrence time, and schema reference or version. Keep business sequencing separate where consumers require it. A registry schema identifier describes serialization; it does not necessarily describe the business version of a workflow or the revision of an entity.

Illustrative fixture names for a shipment contract:
shipment-created.v1.single-stop.json
shipment-created.v2.single-stop.json
shipment-created.v2.multi-stop.json
shipment-created.v2.unknown-mode.json
shipment-created.v1.missing-optional-field.json

For each supported reader:
  deserialize fixture
  assert normalized business representation
  assert allowed side effects or explicit rejection

Keep fixtures synthetic and stable. Include absent fields, explicit nulls where allowed, empty collections, unknown enum values, and boundary values. Different serializers can treat these differently. Test with the actual generated clients or reader libraries used in production rather than a generic JSON parser that ignores the contract.

Scope registry subjects and compatibility policy deliberately. If unrelated event families share one subject, an otherwise sensible change can be checked against the wrong history. If each producer invents a new subject for every release, compatibility checks may never compare the records that consumers actually mix. Include subject naming and registration configuration in the versioned contract fixture.

Stage the change around active consumers

For a genuinely additive change, deploy readers that understand both representations before relying on the new field. Then update producers, observe which consumers receive the new payloads, and enable the new business behavior only after its prerequisites are met. Record which old readers remain and why they are still supported.

For the multi-stop shipment change, an old single-destination consumer may have no safe interpretation. A new event type or topic can make the semantic break explicit. During migration, avoid publishing two events that both trigger the same invoice unless consumers share a deduplication or routing policy. Dual publication is a compatibility mechanism, not automatic duplicate protection.

A translation adapter can help when the old meaning is still derivable. Document any information it discards and which new cases it cannot represent. If multi-stop shipments cannot be mapped honestly to one destination, route them away from the old contract or require consumer migration before enabling that feature.

Test replay and rollback as separate releases

Rebuild a projection from a mixed stream of old and new fixtures, including duplicates and delayed records. Verify final business state, not only message counts. The consumer may need a versioned normalization layer so its core logic operates on one explicit internal representation while preserving information required for audit.

Then roll the producer back while the new consumer remains deployed. Does the reader still accept old records? Roll a consumer back after new records already exist. If that rollback cannot work, the deployment plan must say so and provide another recovery path. Retained data makes rollback more complex than restoring a binary.

Track consumer ownership and last-seen contract versions so removal decisions use evidence. The Kafka guide explains independent readers, and late-arriving events covers time-related replay meaning. Event integration implementation should make compatibility a tested behavior rather than an optimistic label attached to a schema change.

FROM INSIGHT TO ACTIONCustom software development

Evolve events without coordinating every release.

We can implement compatibility fixtures, schema gates, and staged producer-consumer migrations with visible rollback behavior.

Explore software developmentDiscuss your build

Start with your goals.
We’ll work through the next step together.