Event schema governance
Release the consumer before requiring the new event field
Plan the period when old and new producers coexist. A new field becomes safe only when every relevant reader handles both its presence and its absence.
In this article
Identify the dependency before changing it
Imagine a dispatch event gaining a carrier service level. A new routing consumer needs that value to choose an escalation deadline. Older producers cannot supply it, and retained messages will never acquire it automatically.
Decide what the consumer should do when the field is absent. It might use a documented conservative policy, fetch a trustworthy historical value or hold the record for review. Guessing a service level from unrelated current data can create a false historical fact.
The fallback is a business decision. Put it in the release notes and test fixtures rather than burying it inside a deserialiser default.
Expand readers first where the change permits
Deploy consumer support for the new field while continuing to accept the previous format. Verify both paths before producers begin sending the addition.
This order is appropriate for an additive change whose old readers can tolerate the new payload under the actual schema and application rules. A breaking semantic change may require a separate event type or explicit translation instead. Do not infer safety merely from adding an optional field.
Exercise mixed producer versions in a test environment. Include the deployment rollback version, since it may resume sending the older shape after new messages already exist.
Introduce production gradually
Enable the new producer behaviour for a controlled scope. Compare missing-field rates, held records and the resulting escalation deadlines. Inspect examples near the policy boundary, not only average processing time.
If two event versions are emitted for one business occurrence, define how consumers avoid performing the same effect twice. Separate event identifiers without a shared business identity can defeat otherwise correct duplicate handling.
Keep the old path available until scheduled consumers and recovery jobs have been exercised. Removing fallback code immediately after the main consumer succeeds creates a hidden dependency on deployment timing.
Contract only after evidence
Stop producing the old shape when consumers are ready. Remove old reading support only when retained history and restore procedures no longer require it, or when a tested translator covers that history.
Document the point beyond which rolling back the producer alone is insufficient. Once consumers rely on newly supplied information, rollback may need an explicit degraded policy. A release plan should tell the operator what the system will do, not simply which image tag to redeploy.
Primary sources
Confluent: schema evolution and compatibilityReferences checked 11 September 2026.