How would you evolve the payload schemas of Debezium outbox events without breaking downstream consumers?

## What the outbox does and does not give you Routing domain events out of an outbox table rather than publishing raw row images removes the accidental coupling: an `ALTER TABLE` on a business table is invisible to consumers, and the published shape is something a person designed. That is real. What it does not give you is any enforcement. The router ships whatever string the service wrote. A single deploy that changes how the service serialises its payload can break every consumer, and nothing between the service and the consumer will notice. The outbox moves the contract from accidental to deliberate; keeping it *safe* is an organisational job. ## Rule one: additive by default The cheapest evolution is the one consumers never notice. Add fields, make them optional, give them defaults, and never repurpose the meaning of an existing field. A consumer built against last quarter's schema keeps working; a consumer built today reads the new field. Ninety percent of real evolution fits inside this rule, and a team that internalises it rarely has to run the expensive machinery below. What breaks: removing a field, narrowing a type, renaming, changing units or semantics under a stable name. That last one is the nastiest because no automated check catches it — a `total` that quietly starts excluding tax passes every compatibility rule and corrupts every downstream number. ## Rule two: version the event, do not mutate it When a change genuinely cannot be additive, publish a new event version rather than changing the existing one. The natural carrier is the event type column the router already reads: `OrderPlaced` becomes `OrderPlaced.v2`, or a dedicated version column is projected into a header so consumers can dispatch without deserialising. The migration then has a shape: the service writes both v1 and v2 rows inside the same local transaction, so both remain exactly as consistent with the business change as they were before. Consumers migrate at their own pace. When telemetry — consumer group lag on the old type, or a simple counter — shows nothing reads v1, the producer drops it. That window is the deprecation policy, and it should be written down in advance rather than negotiated per incident. ## Rule three: get the registry subject right Here is the piece that catches teams out. Routing by aggregate type means one topic carries every event *type* for that aggregate — `OrderPlaced`, `OrderCancelled`, `OrderRefunded` all land on the orders topic. Under the default subject naming strategy, which derives the subject from the topic, all three schemas compete for one subject, and the registry's compatibility rule is applied *across unrelated event types*. Each new event type looks like a wildly incompatible change to the previous one. The fix is a record-name-based subject strategy, so the subject follows the schema's own name and each event type versions independently on the shared topic. Deciding this at design time is nearly free; discovering it after six months of registered garbage is not. ## Rule four: enforce at the producer The schema belongs in the producing service's repository, next to the code that writes the outbox row, and its compatibility should be checked in that service's CI against the currently registered version. That way an incompatible change fails a build in the team that made it, seconds after they made it — rather than failing a connector task at 3am in a team that did not. Pair it with ownership: a named owner per event type, a catalogue of which events exist, and a subscriber list so a producer can see who they would break. The technical mechanisms above are worthless without knowing who to talk to. ## Rule five: decide what a violation should do This is the judgment call, and it has no single answer. Strict enforcement means an incompatible change stops the pipeline: no bad data, but an outage, and on a source with finite log retention a long enough outage forces a re-snapshot. Permissive handling means the pipeline keeps flowing and the problem surfaces downstream as wrong numbers. For a system of record — payments, ledgers — stopping is usually right. For behavioural telemetry, flowing with quarantine of the bad records is usually right. State the reasoning; an interviewer at this level is testing whether you know the choice exists. ## What this looks like when it works Producers ship additive changes weekly without telling anyone. Breaking changes are rare, announced, dual-published, and retired on a published schedule. The registry holds independently-versioned subjects per event type. The producing team's CI is the gate. And the data platform team is not the bottleneck for any of it — which is the actual goal, because a governance model that requires a central team to approve every change fails at the second team that adopts it.