Events need a meaning that survives new consumers

A field name leaves room for disagreement

Imagine an order service that publishes an event with a status of complete. The warehouse interprets complete as packed. Finance interprets it as paid. Both consumers parse the same message successfully, but they act on different assumptions.

Renaming the field does not settle the disagreement. The producer needs to state which business transition occurred and what evidence made that transition true. An order dispatched event is more specific than an order updated event when dispatch is the fact that consumers need.

Start with a sentence someone outside the implementation can review. For example, the warehouse has handed this consignment to the carrier. Then specify whether that statement remains true if the order is subsequently refunded or returned. Historical facts should not silently change meaning when current state changes.

Separate the envelope from the business contract

The envelope helps infrastructure identify, route and trace the event. The payload describes the domain fact. CloudEvents provides a common event format, but adopting an envelope does not define what an order, payment or dispatch means in your business.

Keep event identity distinct from entity identity. Two changes to one order need different event identifiers. A redelivery of the same occurrence should retain the identity needed for duplicate handling.

Choose what replay is supposed to reconstruct

A snapshot says what selected state looked like at a point in time. A change event says something happened. These support different recovery strategies.

If a consumer receives only an order identifier and fetches the current order, replay reconstructs current knowledge. It cannot reliably recreate the historical order state unless the producer exposes that history. This may be suitable for a search index, but unsuitable for explaining which price a customer accepted.

Conversely, publishing every field creates copies that must be secured and retained. Include the facts consumers need for their agreed purpose. Do not turn the event bus into an unrestricted database export because a future consumer might find it convenient.

Check behaviour as well as compatibility

Schema checks can catch structural incompatibility. Their rules depend on the format and configured policy. They do not establish that a numeric amount still uses the same unit or that a timestamp still represents the same milestone.

Keep small examples beside the contract. Show a normal occurrence, a missing optional value and a correction. Run them through consumers and inspect the resulting business state. A parser returning success is only the first checkpoint.

Give one team responsibility for the meaning of each event. Other teams can own their consumers, but a shared field cannot have a different definition in every service. That ownership becomes most useful when an apparently harmless change needs a clear answer before release.