Concepts
SOM in ten minutes
Three nouns, one snapshot, and a handful of rules about who writes and who decides. Learn these and the schemas read themselves.
The three nouns
Story, Asset, Telling
A story is a real-world event: it grows, splits and changes direction, and nobody knows its shape until it’s over. Mapping that onto a schema came down to three words journalists already use.
Story
The happening. What it is about (tags[], story_meaning), where it has got to (lifecycle, priority), what the newsroom expects (premise), its sources and their credibility, and the gates and compliance flags standing on it.
story_type: PLANNED, ACTIVE, KILLED, SPIKED, ARCHIVED, ORPHAN.
Asset
What the newsroom gathers and makes: VIDEO, SCRIPT, GRAPHIC, TRANSCRIPT, and generative outputs such as SUMMARY and SOCIAL_POST. References only — media stays in its store.
status is editorial only: READY, IN_PRODUCTION, PREPARED, INVALIDATED. “Live” and “aired” are never stored here.
Telling
An asset meeting an audience through a destination. It follows a link — the commitment of that asset to that destination — and records when exposure started and ended.
The compliance position belongs to the telling. The same asset can be cleared on one link and blocked on another at the same moment.
Snapshots, never deltas
A story is published whole, every time
story_idis immutable. A revision is the next snapshot, not a new story.sequence_numberMUST increase andupdated_atMUST move forward.- Whoever publishes re-stamps
originating_system, so a correction is attributed to the corrector, not to whoever first minted the story. - One writer mints: the publisher’s story management system owns the story and its sequence — never the wire, even on a flash.
- A tool that joins late, restarts or reconnects after an outage reads one object and is current.
Omission means absent, not unchanged
A producer MUST NOT leave out fields it didn’t modify. A writer that sends only its own fields silently erases every other system’s work on the story.
The specification ships tools/validate_sequence.py to check a run of snapshots for exactly these properties — the bugs no single message can reveal.
Story lifecycle
Four phases, only on active stories
A lifecycle block is required when story_type is ACTIVE and forbidden otherwise — a schema rule, not a convention. Select a phase.
DEVELOPING
The story exists and is being worked. Fields arrive over successive snapshots: a premise with a confidence, early editorial_source[] entries, the first assets and assertions.
Each change is a new full snapshot with a higher sequence_number. Tools reading the story re-evaluate against every one.
Orphans. A clip that arrives with no story gets a minimal ORPHAN shell story to hold it, carrying a MATCH assertion that proposes the real story. On confirmation the clip moves — same asset_id, original timestamps — and the shell always retires to ARCHIVED. It is never deleted, and consumers filter orphans out with one story_type predicate.
Evidence & claims
Where things came from, and what is being claimed
Sources and credibility
Each source carries a type (WIRE, OFFICIAL, USER_GENERATED, …) and a declared credibility: TRUSTED, VERIFIED, ENDORSED or UNVERIFIED. Credibility is a different axis from media authenticity.
Authorship
HUMAN or MODEL, with model and version only for models. A C2PA authenticity_credential records present: false rather than hiding its absence. Confidence is optional — don’t invent one for free text.
Claims under review
FACT_CHECK (a metric and value), DETECTION or MATCH, each with a review of PENDING, CONFIRMED or REJECTED. Rejected entries are marked, never deleted. On any disagreement, the assertion wins.
Gates & audit
Nothing reaches an audience without an editorial gate
A skill declares, the tool that owns the executor decides, and a person approves. A clearance is granted to a version of the words, so a rewrite reopens the gate rather than inheriting the approval.
hold
The executor MUST withhold output on the affected fields. Released only by a clearance on the same scope — not by time passing, and not by the flag vanishing from a later snapshot.
flag
Mark for review. A tool may show it; nothing is withheld because of it alone.
inform
Advisory only. No blocking action and no mandatory response.
Where several gates bind the same fact on the same telling, it is served only when every gate permits — any one hold means held. “Most restrictive wins” and “story owner takes precedence” were withdrawn in favour of this. Compliance fails closed, and a transform — trim, crop, caption burn — never lifts a hold.
The governance trail. An action of CLEARED, SUPPRESSED, WITHHELD or OVERRIDDEN, against a LINK, ASSET or TELLING, with an actor and a reason. A suppression targets the held asset, because the branch that never airs never gets a link.
Declare, then act
SOM carries context. Skills carry knowledge.
What a story is, what state it’s in, what’s held and what’s cleared, where material came from. The same everywhere, and carrying no judgement of its own.
Editorial standards, compliance rules, institutional practice: what legitimately differs from one newsroom to the next. The framework is open; your workflow stays yours, and no vendor needs a copy of your policy.
Silence is a valid outcome. A skill that finds nothing to declare says nothing, and a tool proves it read the story only by publishing in its turn. That is also why the audit trail is a by-product of how writes work rather than a feature somebody bolted on. How recall works →
Principles
Why SOM is shaped the way it is
Six working principles open the specification, and they are the test any future change must pass.
Single-story scope
The standard coordinates within one story. Relationships to other stories travel as references, and the scope stops there.
Messages, not organisations
SOM describes what travels on the bus. It has no opinion about your desks, roles or tools — two very different workflows can speak the same story.
Publisher-asserted state
A story context says what its owner is willing to put their name to. Nothing in it is a guess inferred across sources.
Coordination, not consumption
A field belongs if another system needs it to act correctly. SOM does not carry the content, and it is not a delivery format.
Default no, justify yes
A field earns its place by blocking a real integration without it. 1.0 withdrew three proposed fields for exactly that reason.
Vocabulary growth governed
Structure can be permissive; the words that carry meaning cannot. Extension has a defined shape, so vendor and newsroom terms share a message on equal footing.
How it behaves
Nothing sits in charge
No orchestrator, no central application. Each tool reads the story and decides for itself.
Skills declare, executors act
A skill states what is true against a rule its newsroom wrote. Only the tool that owns the executor acts — and silence is a valid outcome.
One writer mints
The publisher’s story management system owns the story and its sequence. Never the wire.
Full republish, never a delta
A tool switched on halfway through the night reads one object and knows everything.
Binding at the editorial act
Media becomes part of a story when a person decides it is — never simply because it landed.
A transform never lifts a hold
Cutting, cropping or re-versioning an asset cannot launder its compliance position.
Reading leaves no trace
A tool proves it read something by publishing in its turn — which is why the audit trail falls out of how writes work.
Where the standard stops. SOM describes one story and everything true about it, and nothing more. What each newsroom does with what it reads is its own business. 1.0 is a commitment to stability, not a claim of completeness: what isn’t settled is written down in the open register ↗.
Glossary
The vocabulary
| Term | Meaning |
|---|---|
| Story | The happening in the world, held as a context its publisher owns and asserts. Published as full story.context snapshots keyed by an immutable story_id. |
| Asset | A discrete piece of media or editorial work on a story, classified by evidential position (PRIMARY / SECONDARY / TERTIARY). Exists whether or not anything is published from it. |
| Telling | The moment an asset meets an audience through a destination, with immutable exposure_start / exposure_end. On-air state is derived from tellings. |
| Link | An asset committed to a destination, with a compliance gate per destination (PENDING / CLEARED / BLOCKED). |
| Source (TAMS) | Media addressed as tams://store/id plus an optional time range. SOM references Sources, never Flows. |
| Locator | A non-TAMS media reference: store + ref. A MAM path, an object key, a CMS id. |
| Assertion | A claim about a story, asset, link or telling — FACT_CHECK, DETECTION or MATCH — with provenance and a review state. The authoritative home of a confirmed fact. |
| Provenance | Who or what authored an output: HUMAN or MODEL. Authorship-general, never AI-keyed. |
| Editorial gate | Something that must be settled before an asset or phase proceeds. PENDING / APPROVED / REJECTED. |
| Orphan | A minimal shell story (story_type: ORPHAN) minted to hold a clip that arrived with no story, until a proposed match is confirmed. |
| Skill | A passive rule file in the agentskills.io shape. It declares; it never acts, and never changes content. |
| Executor | The part of a vendor tool that recalls skills, publishes their warnings and decides what the tool withholds. Tools have executors; newsrooms do not have a central one. |
| Configured instance | One generic skill file with one house’s values loaded, watching one condition. A house runs several off the same file. |
| Story Archaeology | The method behind the model: trace one real story after transmission and record how its context actually moved. |
| Extension | extensions["com.{vendor}.{field}"] — the defined place for fields the standard doesn’t carry. Unknown keys are ignored. |
The full glossary lives in the specification: spec/glossary.md ↗
Next: the wire format
Every message shares one envelope. Here is every field, and what conformance asks of it.