telling-event

SOM 1.0.0 14 fields

A telling is the moment an asset meets an audience through a destination, with its own record of when exposure started and ended. (SOM 1.0 introduction The idea)

Message types	telling.started, telling.ended, telling.exposed
Typically published by	The system that puts the story out: playout, a CMS, social publishing. (SOM Managed Bus)
Schema	https://storyobjectmodel.com/schema/1.0/telling-event.schema.json (source at 7297fef)
Defined by SOM	10 of 14 fields

Payloads for telling.started / telling.ended / telling.exposed (v0.3.1 Proposal §3.2), implementing the ratified event-pair semantics (§5): exposure_start/exposure_end immutable and event-stamped; scheduled_start mutable; instantaneous exposures carry both with exposure_start = exposure_end. Stuck-LIVE guard and clock discipline are normative in §5. v0.3.2 addition: transforms[] — edge reshapes recorded against the Telling. Boundary test: if the reshaped output gets its own TAMS Source it is a new Source as today; if not, it is a transform on the telling. The array is APPLICATION-ORDERED and APPEND-ONLY — entries are never edited or removed (the provenance claim depends on it). Compliance invariant: a telling-side transform NEVER lifts a compliance[].media_range hold — holds evaluate against the Source time range regardless of transforms. (SOM 1.0 schema)

Required: message_type, telling_id, link_id

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

Rules across fields:

• When message_type is telling.started, exposure_start is required.
• When message_type is telling.ended, exposure_end is required.
• When message_type is telling.exposed, exposure_start and exposure_end are required.

Fields

Field		Type	Defined by SOM
message_type	required	string	yes
telling_id	required	string (uuid)	not yet
link_id	required	string (uuid)	yes
exposure_start	optional	string (date-time)	yes
exposure_end	optional	string (date-time)	yes
scheduled_start	optional	string (date-time)	yes
extensions	optional	object	yes
transforms	optional	array of object	yes
transforms.transform_type	required	string	yes
transforms.params	optional	object	yes
transforms.applied_by	required	object	yes
transforms.applied_by.actor_id	required	string	not yet
transforms.applied_by.actor_type	required	string	not yet
transforms.applied_at	required	string (date-time)	not yet

message_type

Required

Type string · Allowed values telling.started · telling.ended · telling.exposed

Example telling.started (from examples/telling/started-with-transforms.json)

• Repeats the envelope's message_type, which is what selects this schema. The two must agree: the bus refuses a payload that says something else (payload.message_type_mismatch). (SOM Managed Bus)

Checked by the bus telling-event.required · telling-event.type · telling-event.enum

telling_id

Required

Type string (uuid)

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 telling-event.required · telling-event.type · telling-event.format.uuid

link_id

Required

Type string (uuid)

• The 1.0 schema: “The link this Telling followed from — referenced, not duplicated” (SOM 1.0 schema)

Checked by the bus telling-event.required · telling-event.type · telling-event.format.uuid

exposure_start

Optional

Type string (date-time)

Example 2026-07-08T18:00:00Z (from examples/telling/started-with-transforms.json)

• The SOM glossary, On-Air Model (CONFIRMED): How on-air is represented on a Telling: immutable, event-stamped exposure_start and exposure_end record actual air; a mutable scheduled_start records intended air.
• Actual air: immutable and event-stamped. (SOM glossary: On-Air Model)
• Whether something aired is read from the telling (exposure_start, exposure_end). (SOM glossary: Telling)

Checked by the bus telling-event.type · telling-event.format.date-time

exposure_end

Optional

Type string (date-time)

• The SOM glossary, On-Air Model (CONFIRMED): How on-air is represented on a Telling: immutable, event-stamped exposure_start and exposure_end record actual air; a mutable scheduled_start records intended air.
• Actual end of air: immutable and event-stamped. An instantaneous exposure carries both, with exposure_start equal to exposure_end. (SOM 1.0 schema)

Checked by the bus telling-event.type · telling-event.format.date-time

scheduled_start

Optional

Type string (date-time)

Example 2026-06-12T18:00:00Z (from examples/telling/started.json)

• The 1.0 schema: “Mutable intended-air; never used to derive on-air state” (SOM 1.0 schema)
• The SOM glossary, On-Air Model (CONFIRMED): How on-air is represented on a Telling: immutable, event-stamped exposure_start and exposure_end record actual air; a mutable scheduled_start records intended air.
• Intended air, and mutable. It is never used to decide whether something is on air. (SOM glossary: On-Air Model)

Checked by the bus telling-event.type · telling-event.format.date-time

extensions

Optional

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

• 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 telling-event.type · telling-event.additionalProperties

transforms

Optional

Type array of object · Unknown fields refused

• The 1.0 schema: “Application-ordered, append-only edge reshapes on this telling; none of them new media.” (SOM 1.0 schema)
• Reshapes applied on the way out (a crop, a trim, burnt-in captions), recorded in the order they were applied and never edited or removed. If a reshaped output gets its own TAMS Source it is new media, not a transform. (SOM 1.0 schema)
• A transform never lifts a media_range hold on the asset: holds are evaluated against the Source time range, whatever was cut. (SOM 1.0 schema)
• transforms[].transform_id was withdrawn at 1.0 and is a candidate for 1.1. Application order is the array position. (SOM 1.0 open register §1)

Checked by the bus telling-event.type · telling-event.additionalProperties

transforms.transform_type

Required

Type string · Allowed values CROP · TRIM · CAPTION_BURN · or a value matching ^x-[a-z0-9_]+$

Example TRIM (from examples/telling/started-with-transforms.json)

• The 1.0 schema: “Governed-but-extensible registry (same model as Platform / framing_treatment); seed values CROP / TRIM / CAPTION_BURN; vendor values x-lowercase.” (SOM 1.0 schema)

Checked by the bus telling-event.required · telling-event.type · telling-event.enum · telling-event.pattern

transforms.params

Optional

Type object

• The 1.0 schema: “Per-type payload (not generic from/to): CROP {aspect_ratio | geometry}, TRIM {time_range}, CAPTION_BURN {caption_ref | style}. Shapes settle with the registry.” (SOM 1.0 schema)

Checked by the bus telling-event.type

transforms.applied_by

Required

Type object · Unknown fields refused

• The 1.0 schema: “Audit actor shape (shared convention).” (SOM 1.0 schema)

Checked by the bus telling-event.required · telling-event.type · telling-event.additionalProperties

transforms.applied_by.actor_id

Required

Type string

Example social-desk-tool (from examples/telling/started-with-transforms.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 telling-event.required · telling-event.type

transforms.applied_by.actor_type

Required

Type string

Example system (from examples/telling/started-with-transforms.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 telling-event.required · telling-event.type

transforms.applied_at

Required

Type string (date-time)

Example 2026-07-08T17:50:00Z (from examples/telling/started-with-transforms.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 telling-event.required · telling-event.type · telling-event.format.date-time

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
telling-transform-id.json	transform_id was withdrawn at 1.0	transforms	telling-event.additionalProperties
telling-transform-missing-type.json	every transform must declare transform_type	transforms.transform_type	telling-event.required

---

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.