When the shape of messages changes.
WHERE THIS ARISES
Event payloads Files exchanged between systems Stored messages awaiting processing
WHY IT MATTERS
Old messages exist in queues and archives when the format changes.
WHAT TO INCLUDE IN EVERY MESSAGE
A version.
WHY FROM THE BEGINNING
Adding it later leaves messages that cannot be identified.
WHAT CONSUMERS SHOULD DO
Handle the versions they know, and reject others clearly.
WHAT TO AVOID
Consumers guessing based on which fields are present.
WHAT ADDITIVE CHANGE MEANS
New optional fields, ignored by older consumers.
WHY THAT IS THE SAFEST APPROACH
It requires no coordination.
WHAT REQUIRES COORDINATION
Removing or renaming fields Changing meanings
WHAT ORDER TO DEPLOY IN
Consumers first, understanding both formats Then producers, emitting the new one Then remove the old, later
WHY CONSUMERS FIRST
They must understand the new format before it arrives.
WHAT TO DO ABOUT MESSAGES IN FLIGHT
Ensure consumers handle both during the transition.
WHAT TO KEEP
The ability to reprocess old messages.
WHY
It is needed when a defect is found later.
WHAT TO DOCUMENT
Each version, and when it was in use.
