Message design

Messages that keep their meaning across teams and systems.

Give every event a clear envelope

An event needs more than a payload. Its identity, origin and creation time let a receiver interpret it without guessing which application produced it. Keep these shared fields separate from the business data so that transport changes do not alter their meaning.

Message design
Change a message without surprising its readers

Producers and consumers rarely upgrade at the same instant. A schema change therefore has a transition period in which old and new messages coexist. Design that period explicitly instead of treating deployment as an atomic event across the organisation.

Message design
Follow one interaction across boundaries

A customer action may create several requests, background jobs and notifications. A correlation identifier connects the records of that interaction. It is useful context, but it is not an authentication token and should never grant access on its own.

Message design
Say which clock a timestamp describes

Arrival order is not necessarily event order. Devices can disconnect, clocks can drift and queues can delay publication. A timestamp without a defined meaning encourages readers to combine measurements that describe different moments in a process.

Message design
Make errors useful to the receiving system

An error response should help a caller decide what to do next. Human-readable explanation and machine-readable classification serve different purposes. Keep a stable error code even when the wording changes for clarity or translation.

Message design

Search the library