Event Envelope

An event envelope is the shared metadata around an event’s business payload. It commonly carries event identity, name and version, source, timestamps and correlation identifiers. The exact field names depend on the protocol; an envelope is a design role, not a universal JSON standard.

For an order event, order_id and amount may be payload properties, while event_id identifies this occurrence and received_time records collector arrival. Different events about one order need different event identities. Declare the scope of each key; producer-local IDs may need a tenant or source prefix.

A source field saying server does not authenticate its sender. The collector should establish trusted identity and stamp its own arrival time. Validate top-level fields as well as nested properties. Preserve original timestamps because device clocks, buffering and retries can make occurrence time differ from arrival time.

Which version, and reading old events

An event can need two kinds of version information: the envelope format, which defines shared metadata, and the business payload schema, which defines what an OrderPlaced contains. Separate identifiers let these evolve independently. A single overall contract version can also work if its mapping to both formats is explicit and retained.

CloudEvents separates these roles. Its required specversion identifies the CloudEvents specification in use. The optional dataschema identifies the payload schema, and the specification recommends a different URI for incompatible schema changes. An application still needs an agreed way to identify and interpret its payload when that optional attribute is absent.

Version identity helps a historical reader select an interpretation; it does not preserve that interpretation by itself. Retain the relevant schemas, meaning definitions, and reader or conversion code for every version that remains in the supported replay scope. A version label pointing to a lost schema cannot make the record readable.

• Carry enough schema identity with each record. A topic may contain several payload versions. Use record metadata, a schema-registry identifier, or another documented binding that remains available during replay, rather than inferring the schema from the topic name alone.
• Choose a reader strategy. Use one reader for several compatible versions, keep version-specific readers, or upcast old payloads on read. Upcasting can simplify downstream logic when the conversion preserves meaning. Test its rules, and do not invent information absent from the old event merely to fit the current shape.
• Define the supported compatibility range. A newer version can be accepted when a declared and tested forward-compatibility rule covers it. Reject or quarantine records outside that range whose meaning cannot be established. A default value is safe only when its meaning is part of the contract.
• State the replay commitment. Readers must handle the versions actually retained in the supported topic or archive. Preserve the required readers or migrate records with verified meaning. Time or size retention and compaction may remove history, so replay from the earliest available offset does not necessarily revisit every event ever published.

Compatibility direction is the other half of this and belongs to the schema rather than the envelope — see schema evolution and compatibility. The envelope’s job is narrower and still essential: carrying the identity needed to select the applicable schema, while the surrounding system preserves that schema and its interpretation.

References

• Snowplow event timestamps
• CloudEvents specification
• Apache Kafka 4.1, Design: Log Compaction