Designing a shared envelope for a long-lived message stream, how do you decide which facts belong outside the encoded payload?
answer
- the envelope couples everyone
- payload is the default home
- who needs it without decoding?
- transfer facts out, domain facts in
- two copies drift, name one authority
basics
~20 sPromote a fact to the envelope only when a participant that cannot decode the payload still needs it, and when it describes the transfer rather than the business event. Everything else stays in the body, with one authority per fact.
solid answer
~50 sTreat the envelope as a second contract, coupled to **every** participant rather than to the producer and consumer alone. Three questions decide each field: does a hop that will not decode the body need it, does it describe the transfer rather than the fact being reported, and does it change on a different clock from the payload schema? A yes to all three earns a header. Then price it: per-message bytes on small payloads, a change that every hop must tolerate, and the risk that the same fact sits in both places and drifts with nothing on the wire naming which copy wins. The practical shape is a small stable core — identity, content type and schema id, timestamp, correlation, length, checksum — plus a namespaced extension area, and a written rule that a fact has exactly one authoritative home.
go deeper
Hold the distinction: the envelope carries facts about moving the message, and the payload carries the fact the message is reporting.
Apply the promotion test to concrete fields and explain the mechanism behind it — a hop that never decodes the body can only act on what the envelope tells it.
Bring the operational consequences: duplicated facts that drift with no authority, headers turning up in logs, and per-message overhead that dominates on small events.
Own the shape of the contract: a small closed core, a namespaced extension area, one authority per fact, a bar for adding a header, and an honest account of how a field would ever be retired.
## The envelope is a second contract, with worse leverage A payload schema couples a producer to its consumers. An envelope couples **everyone**: brokers, proxies, gateways, dead-letter handlers, audit sinks, replay tools, and every service that has ever forwarded a message. That difference in blast radius is the whole of the design problem. A payload field can be added by two teams agreeing; an envelope field is a change the entire path must tolerate, and removing one later is close to impossible. So the default answer is *the payload*, and promotion to the envelope must be argued for. ## Four questions that decide where a fact lives 1. **Does a participant that cannot decode the body need it?** Routing keys, content type, schema id, message id, correlation id, length, checksum. If the answer is yes, the fact must be in the envelope, because for that participant the body does not exist. 2. **Is it about the transfer or about the fact being reported?** Delivery attempt counts, produced-at timestamps and trace context describe the act of moving a message. The order total describes the event. The first family belongs outside, the second inside. 3. **Does it change on a different clock?** Envelope fields evolve with the messaging platform; payload fields evolve with the domain. Mixing clocks means a domain change forces every hop to redeploy. 4. **Is it safe to expose at every hop?** Envelope headers appear in logs, traces and broker consoles. Anything that would be unacceptable there stays in the body — or, where the body is protected, does not travel at all. ## Side by side | | Envelope | Payload | |---|---|---| | Read by | Every hop on the path | The decoding consumer only | | Cost of a change | All participants must tolerate it | Producer and consumers agree it | | Evolves with | The transport and platform | The domain | | Visibility | Logs, traces, broker tooling | Only after a decode | | Good candidates | Ids, content type, schema id, routing, timing, integrity | Business fields, nested structure, anything domain-shaped | | Failure if misplaced | Every hop decodes to route | Domain churn forces platform-wide changes | ## What promoting a field actually costs - **Bytes on every message.** Irrelevant at a megabyte, dominant at 200 bytes — a stream of small events can spend more on headers than on facts. - **Coupling.** Each header is a commitment that no hop will drop or mangle it, and unknown headers must be forwarded untouched or the metadata dies in the middle of the path. - **Drift.** A field copied into both places will disagree, and the wire carries nothing that says which copy is authoritative. Pick one home; if a copy is unavoidable for routing, name the authority in the contract and treat the copy as a derived cache. - **The envelope as a covert API.** Once consumers can act on rich headers, some stop decoding bodies, and a field added for observability silently becomes load-bearing behaviour that nobody may change. - **Leakage.** Headers are the part of a message most likely to end up in a log line. ## What a lead actually standardises 1. **A small closed core** every message carries: message id, type, content type, schema id and version, produced-at, correlation and causation ids, payload length, checksum. Small enough that everyone implements it correctly. 2. **A namespaced extension area** for team- or domain-specific headers, with the rule that unknown extensions are forwarded unchanged and never load-bearing for routing. 3. **One authority per fact**, written down, so a disagreement has a defined resolution instead of an argument at 3 a.m. 4. **An addition process** with a bar: name the participant that cannot decode the body and needs this. No such participant means it stays in the payload. 5. **A sunset story.** Because envelope fields are effectively permanent, it is worth stating up front how one would ever be retired — typically by making it optional first and only removing it once no reader reads it. ## The judgment being tested The question has no single right answer, which is the point. A weak answer lists fields. A strong one states the promotion test, prices the coupling against the convenience, names duplication drift as the failure that actually bites, and admits the asymmetry: putting a field in the envelope is cheap today and expensive forever, while leaving it in the payload is the reversible choice.
- A routing decision genuinely needs a value that also lives inside the payload. How do you handle the duplication?Promote a copy, but declare the payload the authority and the header a derived cache, produced at exactly one place in the producer so the two cannot be written independently. Consumers that decode read the body; hops that cannot, read the header. Then add a check — a sampled comparison or a validation on ingest — because a silent disagreement is the failure this arrangement invites.
- Why is adding an envelope field much harder to reverse than adding a payload field?Because the set of readers is unbounded and mostly unknown: brokers, proxies, audit sinks and tools you did not write may all have come to depend on it. A payload field has a known consumer list you can check. Retiring an envelope field therefore means making it optional, waiting out every reader, and only then removing it.
- What is the argument against a rich, generous envelope on a high-volume stream of small events?Headers are paid per message, so on 200-byte events a generous envelope can cost more than the data, inflating network, broker storage and retention. It also widens coupling: every field is one more thing each hop must forward correctly. On such streams the core stays minimal and anything optional moves into the payload.
A shipping label versus the contents of the parcel: everyone who handles the parcel reads the label, so it stays small and standard, and writing the contents onto the label as well only creates two versions that disagree.
saying these in an interview costs you the question
- Promotes any field that might be useful to route on
- Believes envelope headers are effectively free per message
- Keeps the same fact in both places with no named authority
- Puts domain fields in headers for convenient log filtering
- Assumes an envelope field can be removed later like any other
- Requires the payload schema in order to read the envelope