Envelope

SOM 1.0.0 25 fields

Every SOM message is an envelope with the payload inside it. The envelope is not optional. (SOM 1.0 conformance §2)


Typically published by	Every publisher, on every message. (SOM 1.0 conformance §1)
Schema	`https://storyobjectmodel.com/schema/1.0/envelope.schema.json` (source at 7297fef)
Defined by SOM	17 of 25 fields

The envelope every SOM message carries. som_version is the schema pack version the payload conforms to — 1.0.0 for SOM 1.0. payload is polymorphic on message_type — see story-context.schema.json and the other payload families. (SOM 1.0 schema)

Required: som_version, message_id, correlation_id, message_type, timestamp, originating_system, topic, payload

Unknown fields: refused. The payload lists every field it accepts.

Fields

Field		Type	Defined by SOM
`som_version`	required	string	yes
`message_id`	required	string (uuid)	yes
`correlation_id`	required	string (uuid)	yes
`causation_id`	optional	string (uuid)	yes
`message_type`	required	string	yes
`timestamp`	required	string (date-time)	yes
`originating_system`	required	originating_system	yes
`topic`	required	string	yes
`modification_header`	optional	object	yes
`modification_header.story_version`	optional	integer	not yet
`modification_header.modified_at`	optional	string (date-time)	not yet
`modification_header.modified_by`	optional	string	not yet
`modification_header.change_summary`	optional	string	not yet
`modification_header.history`	optional	array	yes
`_actors`	optional	object	yes
`payload`	required	object	yes
`extensions`	optional	object	yes
`@context`	optional	string or object	yes
`source`	refused	—	yes
`signature`	refused	—	yes

`som_version`

Required

Type string · Pattern ^\d+\.\d+\.\d+$

Example 1.0.0 (from examples/story-context/hurricane-beat6-envelope.json)

The 1.0 schema: “The schema pack version the payload conforms to — 1.0.0 for SOM 1.0. Pre-1.0 values (0.3.2 and earlier) are not conformant to this specification; see spec/migration-from-v0.3.2.md. Informative, never a parsing discriminator — message_type identifies the payload family.” (SOM 1.0 schema)
The SOM glossary, som_version (CONFIRMED): Schema version string on every envelope.
Producers must emit the version of the pack they conform to: "1.0.0" for SOM 1.0. A 1.1 producer will emit "1.1.0", which is why the schema only checks the x.y.z shape. (SOM 1.0 conformance §3)
Consumers must not branch on it: it is informative, and message_type identifies the payload. "0.3.2" is not SOM 1.0, because three fields were withdrawn before 1.0. (SOM 1.0 conformance §3)
The bus refuses a version before 1.0 (som_version.pre_1_0) and a different major version (som_version.unsupported_major). (SOM Managed Bus)

Checked by the bus som_version.pre_1_0 · som_version.unsupported_major · envelope.required · envelope.type · envelope.pattern

`message_id`

Required

Type string (uuid)

Example 0199a1c4-7a2e-7b31-8c55-4d2f9e6a1b07 (from examples/story-context/hurricane-beat6-envelope.json)

The 1.0 schema: “UUIDv7, time-ordered” (SOM 1.0 schema)
The SOM glossary, message_id (CONFIRMED): UUIDv7 unique to each bus message.
Must be a UUID; UUIDv7 is recommended because it sorts by time. Implementations must assert the uuid format: most validators skip it unless told to. (SOM 1.0 conformance §2, §4)
A retry of the same message reuses its message_id; a new message never does. The bus accepts a resend of identical content once and refuses a reused id with different content (message_id.reused). (SOM Managed Bus)

Checked by the bus message_id.reused · envelope.required · envelope.type · envelope.format.uuid

`correlation_id`

Required

Type string (uuid)

The 1.0 schema: “Required as of v0.3 (decision 18); links all messages about the same story lifecycle” (SOM 1.0 schema)
The SOM glossary, correlation_id (CONFIRMED): UUID grouping all messages in the same logical operation.
Required. It links every message about one story lifecycle and is the natural partition key. (SOM 1.0 conformance §2)
The bus keeps order per correlation_id: mint one per story and keep it for the story's life. (SOM Managed Bus)

Checked by the bus correlation_id.changed · envelope.required · envelope.type · envelope.format.uuid

`causation_id`

Optional

Type string (uuid)

Example 0199a1c4-7a2e-7b31-8c55-4d2f9e6a1b06 (from examples/story-context/hurricane-beat6-envelope.json)

The 1.0 schema: “Optional; ID of the message that directly caused this one” (SOM 1.0 schema)
The SOM glossary, causation_id (CONFIRMED): UUID identifying the specific message that directly caused this message.
Set it when a message is a reaction to another one, such as a skill warning raised because of a snapshot. (SOM Managed Bus)

Checked by the bus envelope.type · envelope.format.uuid

`message_type`

Required

Type string · Pattern ^[a-z][a-z0-9_.]*$

Example story.context (from examples/story-context/hurricane-beat6-envelope.json)

The SOM glossary, message_type (CONFIRMED): Enum on envelope selecting payload shape. 20 values.
- In 1.0: The 1.0 envelope accepts any lower-case dotted message_type; the seven 1.0 schemas define payloads for ten of them. (SOM 1.0 schema)
The only parsing discriminator. Implementations must choose the payload schema from message_type, never from the topic, a filename, the publisher or the payload's shape. (SOM 1.0 conformance §2)
A consumer must not fail on a message_type it doesn't handle; it ignores it. This is what lets 1.x add families without breaking anything. (SOM 1.0 conformance §5)
A message_type SOM 1.0 names but publishes no schema for is accepted with the envelope checked and the payload passed through (payload.unvalidated). (SOM Managed Bus)

Checked by the bus message_type.unknown · payload.unvalidated · payload.message_type_mismatch · producer.message_type_not_allowed · envelope.required · envelope.type · envelope.pattern

`timestamp`

Required

Type string (date-time)

Example 2026-09-11T16:41:00.000000Z (from examples/story-context/hurricane-beat6-envelope.json)

The 1.0 schema: “Microsecond precision recommended. Skill-output timestamp lives HERE, not in the payload (decision 18)” (SOM 1.0 schema)
The authoritative time of the event. Skill output carries its timestamp here, not in the payload. (SOM 1.0 conformance §2)
The date-time format must be asserted: a timestamp that isn't one is not conformant, even if a default validator lets it through. (SOM 1.0 conformance §4)

Checked by the bus envelope.required · envelope.type · envelope.format.date-time

`originating_system`

Required

Type originating_system

The SOM glossary, originating_system (CONFIRMED): Proposed rename for the source block on the message envelope identifying which system sent the message.
- In 1.0: Ships in 1.0, required on every envelope. (SOM 1.0 schema)
Whoever publishes a snapshot stamps it, so a correction is attributed to the corrector and not to whoever first minted the story. (SOM 1.0 conformance §6)
On the bus, system_id must be one your connection may stamp (producer.system_id_not_allowed). (SOM Managed Bus)

Checked by the bus envelope.required · envelope.type

`topic`

Required

Type string · Pattern ^som\.

Example som.story.context.hurricane-2026-0911 (from examples/story-context/hurricane-beat6-envelope.json)

The 1.0 schema: “Required per the decision 18 envelope lock” (SOM 1.0 schema)
The SOM glossary, Topic (CONFIRMED): Hierarchical dot-separated routing key for bus pub/sub filtering.
Must begin with som.. (SOM 1.0 conformance §2)

Checked by the bus envelope.required · envelope.type · envelope.pattern

`modification_header`

Optional

Type object

The 1.0 schema: “On snapshot-style messages such as story.context” (SOM 1.0 schema)
The SOM glossary, modification_header (CONFIRMED): Envelope section on story.context messages only.

Checked by the bus envelope.type

`modification_header.story_version`

Optional

Type integer

Example 7 (from examples/story-context/hurricane-beat6-envelope.json)

Not yet defined by SOM

Neither the 1.0 schema nor the SOM glossary says what this field means. Its facts above are exact; its meaning is an open question for the SOM working group.

Checked by the bus envelope.type

`modification_header.modified_at`

Optional

Type string (date-time)

Example 2026-09-11T16:41:00Z (from examples/story-context/hurricane-beat6-envelope.json)

Not yet defined by SOM

Neither the 1.0 schema nor the SOM glossary says what this field means. Its facts above are exact; its meaning is an open question for the SOM working group.

Checked by the bus envelope.type · envelope.format.date-time

`modification_header.modified_by`

Optional

Type string

Example producer-7 (from examples/story-context/hurricane-beat6-envelope.json)

Not yet defined by SOM

Neither the 1.0 schema nor the SOM glossary says what this field means. Its facts above are exact; its meaning is an open question for the SOM working group.

Checked by the bus envelope.type

`modification_header.change_summary`

Optional

Type string

Example Outage figure confirmed by FEMA; priority raised to URGENT (from examples/story-context/hurricane-beat6-envelope.json)

Not yet defined by SOM

Neither the 1.0 schema nor the SOM glossary says what this field means. Its facts above are exact; its meaning is an open question for the SOM working group.

Checked by the bus envelope.type

`modification_header.history`

Optional

Type array

The SOM glossary, History / History Entry (CONFIRMED): Version tracking on envelope and versioned sections.

Checked by the bus envelope.type

`_actors`

Optional

Type object

The 1.0 schema: “Key-value map of short-key actor lookups” (SOM 1.0 schema)
The SOM glossary, _actors (CONFIRMED): Key-value map on the envelope (_actors) providing short-key lookups for actor identities.

Checked by the bus envelope.type

`payload`

Required

Type object

Must validate against the schema for the message_type the envelope declares. (SOM 1.0 conformance §1)

Checked by the bus envelope.required · envelope.type

`extensions`

Optional

Type object · Keys match ^com\.[a-z0-9-]+\. · Unknown fields refused

The 1.0 schema: “Vendor fields, reverse-domain namespaced (com.{vendor}.*); consumers ignore-if-unknown” (SOM 1.0 schema)
The SOM glossary, Extensions (CONFIRMED): Namespaced area on the envelope for vendor-specific data.
Vendor fields, namespaced by reverse domain (com.<vendor>.). Consumers must ignore extensions they don't recognise and must not reject a message for carrying them. (SOM 1.0 conformance §5)

Checked by the bus envelope.type · envelope.additionalProperties

`@context`

Optional

Type string or object

The 1.0 schema: “JSON-LD context — DEFERRED in v0.3 (decision 18); permitted for forward compatibility” (SOM 1.0 schema)
The SOM glossary, @context (CONFIRMED): JSON-LD context field on the envelope.

Checked by the bus envelope.type

`source`

Refused

Type none: publishing it is refused

The SOM glossary, Source (system) (CONFIRMED): The system that originated a message.
- In 1.0: source is refused on the 1.0 envelope; the system is named in originating_system. (SOM 1.0 schema)
Refused. The sending system is named in originating_system. (SOM 1.0 schema)

Checked by the bus envelope.false_schema

`signature`

Refused

Type none: publishing it is refused

The SOM glossary, Signature (CONFIRMED): Cryptographic signature on the envelope.
- In 1.0: Refused by the 1.0 envelope schema. (SOM 1.0 schema)

Checked by the bus envelope.false_schema

Shape: `originating_system`

Used by originating_system.

Renamed from source (first leg of the four-way source disambiguation) (SOM 1.0 schema)

Required: system_id, system_type

Unknown fields: refused. The shape lists every field it accepts.

Field		Type	Defined by SOM
`system_id`	required	string	not yet
`system_type`	required	string	yes
`system_name`	optional	string	not yet
`vendor`	optional	string	not yet
`version`	optional	string	not yet

`system_id`

Required

Type string

Example ncs-nyc-01 (from examples/story-context/hurricane-beat6-envelope.json)

Not yet defined by SOM

Neither the 1.0 schema nor the SOM glossary says what this field means. Its facts above are exact; its meaning is an open question for the SOM working group.

Checked by the bus producer.system_id_not_allowed · envelope.required · envelope.type

`system_type`

Required

Type string · Allowed values ncs · mos_device · graphics · automation · wire_service · ai_agent · compliance_engine · editorial_dashboard · archive · prompter · camera · audio · skill_worker · custom

Example ncs (from examples/story-context/hurricane-beat6-envelope.json)

The SOM glossary, system_type (CONFIRMED): Enum on source block classifying the originating system. 14 values (UPPER_SNAKE per WG decision 13): NCS, MOS_DEVICE, GRAPHICS, AUTOMATION, WIRE_SERVICE, AI_AGENT, COMPLIANCE_ENGINE, EDITORIAL_DASHBOARD, ARCHIVE, PROMPTER, CAMERA, AUDIO, SKILL_WORKER, CUSTOM.
- In 1.0: In the 1.0 schema the values are lower case: ncs, mos_device, graphics and so on. (SOM 1.0 schema)

Checked by the bus envelope.required · envelope.type · envelope.enum

`system_name`

Optional

Type string

Example Newsroom planning system (from examples/story-context/hurricane-beat6-envelope.json)

Not yet defined by SOM

Neither the 1.0 schema nor the SOM glossary says what this field means. Its facts above are exact; its meaning is an open question for the SOM working group.

Checked by the bus envelope.type

`vendor`

Optional

Type string

Example example (from examples/story-context/hurricane-beat6-envelope.json)

Not yet defined by SOM

Neither the 1.0 schema nor the SOM glossary says what this field means. Its facts above are exact; its meaning is an open question for the SOM working group.

Checked by the bus envelope.type

`version`

Optional

Type string

Example 1.0 (from examples/story-context/hurricane-beat6-envelope.json)

Not yet defined by SOM

Neither the 1.0 schema nor the SOM glossary says what this field means. Its facts above are exact; its meaning is an open question for the SOM working group.

Checked by the bus envelope.type

Must be refused

SOM publishes messages that every conformant system must reject. These are the ones that concern this schema, with the rule this bus reports for each, checked by the same validator the gateway runs.

Case	Why it must fail	Field	Bus rule
envelope-extensions-not-namespaced.json	extensions keys must be reverse-domain namespaced com.{vendor}.*	`extensions`	`envelope.additionalProperties`
envelope-message-id-not-uuid.json	message_id must be a UUID; format is asserted at 1.0	`message_id`	`envelope.format.uuid`
envelope-missing-correlation-id.json	correlation_id is required on every message (decision 18)	`correlation_id`	`envelope.required`
envelope-signature-not-allowed.json	signature is not part of the 1.0 envelope	`signature`	`envelope.false_schema`
envelope-som-version-0-3-2.json	som_version 0.3.2 is not SOM 1.0; 1.0.0 is the only wire version	`som_version`	`som_version.pre_1_0`
envelope-source-not-allowed.json	source was renamed originating_system in v0.3 and is rejected	`source`	`envelope.false_schema`
envelope-system-type-unknown.json	originating_system.system_type is a closed enum	`system_type`	`envelope.enum`
envelope-timestamp-not-date-time.json	timestamp must be RFC 3339 date-time	`timestamp`	`envelope.format.date-time`
envelope-topic-not-som.json	topic must begin with som.	`topic`	`envelope.pattern`
envelope-unknown-property.json	the envelope permits no unknown properties	—	`envelope.additionalProperties`

Generated from the SOM 1.0 schemas at upstream commit 7297fef, the pack this bus validates against. Quoted SOM text is © the SOM authors, CC BY 4.0, with two changes: working-group decision numbers are shown without their #, and attributions to named working-group members are left out. How to read this reference: SOM 1.0 schema.

Envelope ​

Fields ​

som_version ​

message_id ​

correlation_id ​

causation_id ​

message_type ​

timestamp ​

originating_system ​

topic ​

modification_header ​

modification_header.story_version ​

modification_header.modified_at ​

modification_header.modified_by ​

modification_header.change_summary ​

modification_header.history ​

_actors ​

payload ​

extensions ​

@context ​

source ​

signature ​

Shape: originating_system ​

system_id ​

system_type ​

system_name ​

vendor ​

version ​

Must be refused ​

Envelope

Fields

`som_version`

`message_id`

`correlation_id`

`causation_id`

`message_type`

`timestamp`

`originating_system`

`topic`

`modification_header`

`modification_header.story_version`

`modification_header.modified_at`

`modification_header.modified_by`

`modification_header.change_summary`

`modification_header.history`

`_actors`

`payload`

`extensions`

`@context`

`source`

`signature`

Shape: `originating_system`

`system_id`

`system_type`

`system_name`

`vendor`

`version`

Must be refused