The envelope

Every SOM message is a JSON envelope around a payload. The envelope says who sent what, when, about which story; message_type chooses the payload's schema.

{
  "som_version": "1.0.0",
  "message_id": "0199a1c4-7a2e-7b31-8c55-4d2f9e6a1b07",
  "correlation_id": "0199a1c4-5b10-7c3a-9e4f-2a6b8c0d1e22",
  "causation_id": "0199a1c4-7a2e-7b31-8c55-4d2f9e6a1b06",
  "message_type": "story.context",
  "timestamp": "2026-09-11T16:41:00Z",
  "originating_system": { "system_id": "acme-ncs-test", "system_type": "ncs", "vendor": "acme", "version": "4.2" },
  "topic": "som.story.context",
  "payload": { "story_id": "acme-hurricane-001", "…": "…" }
}

Fields

Each field in full, with the SOM text and glossary entry behind it: Envelope in the SOM 1.0 schema reference.

Field	Rule	Tip
som_version	Exactly "1.0.0" for a 1.0 producer. Anything before 1.0 (such as 0.3.2) is refused: som_version.pre_1_0	Don't copy it from older drafts
message_id	A UUID, unique per message	Use UUIDv7 (time-ordered). A retry of the same message reuses it; a new message never does: message_id.reused
correlation_id	A UUID that ties a story's messages together	Mint one per story and keep it for the story's life. The bus keeps order per correlation_id
causation_id	Optional UUID of the message that caused this one	Set it when you react to another message: a skill warning caused by a snapshot, for example
message_type	Chooses the payload schema, and nothing else does	See Message families
timestamp	RFC 3339 date-time	Always include a time zone: Z or an offset
originating_system	system_id and system_type required; system_name, vendor, version optional. Nothing else is allowed	system_id must be one your connection may stamp: producer.system_id_not_allowed
topic	Must start with som.	e.g. som.story.context, som.telling.started
extensions	Optional; every key reverse-domain namespaced, com.<vendor>.	Consumers ignore extensions they don't know
modification_header, _actors, @context	Optional; the schema allows them. No other top-level field is	See the Envelope schema reference

system_type is one of SOM 1.0's values: ncs, mos_device, graphics, automation, wire_service, ai_agent, compliance_engine, editorial_dashboard, archive, prompter, camera, audio, skill_worker, custom.

Strict on the envelope

The envelope is never relaxed. An unknown field (envelope.additionalProperties), a signature field or a legacy source field (envelope.false_schema) is refused, whatever the som_version. The payload is treated more generously for newer 1.x producers: see Forward compatibility.

What the bus adds

These are rules of the bus, reported with source: policy, not rules of SOM:

• At most 240,000 bytes per message (message.too_large). Media never travels the bus; send references to it.
• One message per request. No batching.
• Your system_ids and message types are the ones granted to your connection (see Credentials).