Before you open a schema.
The whole model in one read. Everything on this page is SOM 1.0 as published: every field name and every value below is in the schemas served at /schema/1.0/. The schemas are normative. This is the reading guide.
The idea in three sentences
Tools stop talking to each other and talk to a shared, live description of the story. Any system can say what it knows about a story; any other system can act on that without a point-to-point integration and without asking permission. Nothing is in charge: there is no orchestrator, and each system reads the story and decides for itself.
Three nouns
Everything in SOM sits in one of three layers. They were transcribed from how working newsrooms already describe what they do, not invented.
Story
The happening. A context that one publisher owns and asserts, carrying everything true about the story right now.
story_type: PLANNED · ACTIVE · KILLED · SPIKED · ARCHIVED · ORPHAN
carries: lifecycle · priority · premise · editorial_gates · compliance · editorial_source · assets · assertions · relations · content_refs
Published as story.context, always in full, by the story owner.
Asset
A discrete piece of media or editorial work, classified by where it sits in the evidential chain. Assets exist whether or not anything is ever published from them.
evidential_position: PRIMARY · SECONDARY · TERTIARY
status: READY · IN_PRODUCTION · PREPARED · INVALIDATED
asset_type: VIDEO · AUDIO · GRAPHIC · STILL · SCRIPT · TRANSCRIPT · SUMMARY · SOCIAL_POST · ARTICLE and nine more
Telling
The moment an asset meets an audience through a destination, with its own record of when exposure started and ended.
events: telling.started · telling.ended · telling.exposed
A Telling follows from a link, the asset-to-destination connection, and the clearance for that route rides the link, not the asset.
The envelope
Every SOM message is one envelope with the payload inside it. Eight fields are required, and four rules govern them.
message_type is the only parsing discriminator. Select the payload schema from it, never from topic, filename, publisher or payload shape.
correlation_id is required and links every message about one story. It is the natural partition key.
message_id must be a UUID; UUIDv7 is recommended because it sorts by time. topic must begin som.
som_version is informative. Producers emit the pack they conform to, 1.0.0. Consumers never branch on it; 0.3.2 is not 1.0.
The other required fields are timestamp, the authoritative time of the event, originating_system, and payload. extensions carries vendor fields under a reverse-domain namespace, com.vendor.*, and every consumer must ignore extensions it does not recognise.
Seven message families
A conformant system does not implement seven families. It implements the envelope plus whichever families it has something to say about or something to do with.
| FAMILY | PUBLISHED BY | WHAT IT SAYS |
|---|---|---|
story.context | the story owner | the whole story, republished in full on every change |
som.telling.* | the exposure publisher | an asset met an audience: started, ended, exposed |
som.link.* | the committing system | an asset was committed to a destination, its gate changed, or it was withdrawn |
delivery.media_available | the media store | media has arrived, with a tams:// source and time range or a store locator |
som.system.audit | any governance actor | a clearance, suppression, withholding or override, with actor and reason |
skill.warning.raised | a skills executor | a rule fired against the story: what, how severe, what it blocks |
| the envelope | every publisher | the wrapper all of the above travel in |
Snapshots, not deltas
story.context is always the whole story. A tool that comes back after an hour reads one message and is current. The rules that make that safe: story_id never changes; sequence_number must increase, and only the owner sets it; updated_at moves forward; originating_system is re-stamped by whoever publishes, so a correction is attributed to the corrector, not to whoever first minted the story. One owner per story, and minting is deployment policy rather than a rule of the standard: the owner is whichever of the newsroom's systems is nominated, never the agency.
Lifecycle and priority
lifecycle.phase: DEVELOPING → READY_TO_AIR → BREAKING → PUBLISHED
The phase carries its previous_phase, so a consumer can tell a story that has just gone to air from one that has been on air for an hour. Priority is separate from phase: ROUTINE, STANDARD, HIGH, URGENT, FLASH. A flash is a level of urgency, not a lifecycle state.
Evidence and claims
Three things that look similar and are kept apart.
Where material came from. editorial_source[] records each source with a type, WIRE, OFFICIAL, FIELD_CREW, USER_GENERATED, SOCIAL, ARCHIVE among eleven, and a credibility the publisher asserts: TRUSTED, VERIFIED, ENDORSED, UNVERIFIED.
Who made it. authorship_provenance says HUMAN or MODEL, so anything a model produced can be told apart later.
What has been claimed about it. assertions[] holds claims made by tools: FACT_CHECK, DETECTION, MATCH, each with a target (an asset, a link, a telling or the story) and a review_state of PENDING, CONFIRMED or REJECTED. An assertion is evidence for a decision, never the decision. A deepfake verdict stays an assertion; the gate on the clip reads it there.
Gates, flags and clearances
Three mechanisms, three different kinds of thing.
An editorial gate is a decision. editorial_gates[]: a person approves or rejects, status PENDING, APPROVED, REJECTED, and the gate names what it blocks, an ASSET or a PHASE.
A compliance flag is a condition. compliance[]: severity LOW to CRITICAL, status ACTIVE, RESOLVED or WAIVED. A flag raised by a tool sits in the story until a person resolves or waives it.
A clearance is per route. compliance_gate_status on the link between an asset and a destination: PENDING, CLEARED, BLOCKED. The same asset can be cleared for digital and blocked for broadcast at once, because the state rides the connection, not the asset.
Where more than one rule bears on an output, holds combine: any hold holds. Every clearance, suppression, withholding and override is recorded in som.system.audit with actor, target and reason.
Skills
A Skill is a rule the newsroom has written down, in the open format at agentskills.io. Skills declare; executors act. A skill reads the story and says what is true against its rule; the tool that owns the executor decides what to do about it, and silence is a valid outcome. A skill never sends work to another tool.
When a rule fires, the executor publishes skill.warning.raised with a severity that is the standard's only lower-case vocabulary: hold, the executor must withhold the output; flag, the output may go with the warning attached; inform, for the record. The warning names its rule_id, the affected_fields, what it blocks, and whether it is non_overridable. The story's skills_config lists which skills are active, their type, NEWSROOM, VENDOR or REFERENCE, and their priority.
Media
Media never travels the bus. A story points at frames held elsewhere. Against a TAMS store the pointer is a tams:// source and a time range, frame accurate; against anything else it is a locator of store plus reference. The media store announces arrivals with delivery.media_available, and nothing is bound to a story on arrival. Binding happens at the editorial act, when a journalist decides the material belongs, never at ingest.
The conformance floor
A system is SOM 1.0 conformant if every message it publishes is a valid envelope, every payload validates against the schema for the message_type it declares, and it ignores what it does not recognise. That is the whole floor. A planning system that only publishes story.context and only reads skill.warning.raised is fully conformant.
The requirement most implementations get wrong by default: JSON Schema treats format as an annotation, so most validators accept "message_id": "NOT-A-UUID" unless format assertion is switched on. A conformant implementation must assert uuid and date-time. tools/validate.py in the repository does; anything that passes where it fails is not conformant.
Implementations should state which families they produce and which they consume. That statement, not the size of the implementation, is what an integrator needs.
What will not change
Within 1.x, schema identifiers never move, changes are additive only, and a field destined for removal is deprecated first and never removed. Producers may start emitting new optional fields at any 1.x release; consumers must keep accepting deprecated ones. Anything that would break a 1.0 consumer is, by definition, 2.0. What is not yet settled is written down in the open register rather than left to be discovered.
Glossary
| TERM | MEANING |
|---|---|
| Story | the happening; a context one publisher owns and asserts |
| Asset | a discrete piece of media or editorial work on a story, classified primary, secondary or tertiary |
| Telling | an asset meeting an audience through a destination, with exposure start and end |
| Link | the asset-to-destination connection; carries the clearance for that route |
| Destination | an output: a bulletin, a page, a platform |
| Envelope | the wrapper every message travels in |
| Family | one of the seven message types, each with its own schema |
| Snapshot | a story.context message: always the whole story |
| Owner | the one system that mints a story and sets its sequence number |
| Minting | creating a story and its story_id; once, by the owner, never by an agency |
| Premise | the story's expected outcome and what changed, with confidence |
| Editorial gate | a human decision to approve or reject an asset or a phase |
| Compliance flag | a condition on the story, with severity, active until resolved or waived |
| Clearance | the per-route gate status on a link: pending, cleared, blocked |
| Assertion | a claim made by a tool: fact check, detection, match; evidence, never a decision |
| Credibility | the publisher's assessment of a source: trusted, verified, endorsed, unverified |
| Skill | a rule the newsroom wrote, in the agentskills.io format; declares, never acts |
| Executor | the part of a tool that runs skills and acts on its own rules |
| Warning | a skill.warning.raised message: hold, flag or inform |
| Extension | vendor fields under com.vendor.*, ignored by everyone else |
| TAMS | BBC R&D's open media store standard; every frame addressable; the frame-accurate junction |
| Open register | the published list of what the working group has not yet settled |
Next: the conformance document for the exact rules, the worked examples for what a conformant message looks like, and joining for what an integration actually involves.
the schemas