Event Versioning and Contract Evolution

An order event has a field called totalMinorUnits. Reporting uses it as the amount the customer agreed to pay, including shipping and tax. A producer team later changes it to mean the items subtotal. The field is still an integer, every record still decodes, and the schema checker accepts the change. The reports are now wrong.

An event contract includes more than field types. It also defines what happened, what consumers may conclude, and how producers and consumers maintain that promise over time.

In this chapter, we’ll decide when to evolve an existing event, when to introduce a new contract, and how to migrate consumers while preserving correct live processing and replay.