storyobjectmodel.dev

Referenz · SOM 1.0

Die sieben Nachrichtenfamilien

Alles Normative an SOM sind sieben JSON Schemas: das Envelope, die Story und fünf Familien für Links, Tellings, eintreffende Medien, Audit und Skill-Warnungen. Jedes liegt unter einer URL, die sich während der gesamten Lebensdauer von 1.x nicht ändert.

Die Familienstory.contextEintreffende MedienLinks & TellingsAuditWas Sie implementieren

Schemas

Alles, was über die Leitung geht

Die meisten Familien sind optional: Implementieren Sie das Envelope und die Familien, zu denen Sie etwas zu sagen haben. Die Benennung der Topics liegt bei Ihnen — einzige Regel ist das Präfix som., und Consumer verteilen nach message_type, nie nach dem Topic.

Familiemessage_typeVeröffentlicht vonSchema
Nachrichten-Envelope
Die geschlossene Hülle, die jede Nachricht trägt. Ihr Payload ist polymorph über message_type.
(jede Nachricht)
jeder Publisherenvelope.schema.json ↗
story.context
Der vollständige Zustand einer Story zu einem Zeitpunkt — ein Snapshot, niemals ein Delta.
story.context
der Eigentümer der Storystory-context.schema.json ↗
som.telling.*
Wann ein Asset auf ein Publikum traf. Der On-Air-Zustand wird daraus abgeleitet, nie am Asset gespeichert.
telling.started
telling.ended
telling.exposed
der Exposure-Publishertelling-event.schema.json ↗
som.link.*
Ein Asset, das einem Ziel zugesagt ist, mit einem Compliance-Gate pro Ziel. assets[].usage[] wird allein aus diesen Events gepflegt.
link.committed
link.gate_changed
link.withdrawn
das festschreibende Systemlink-event.schema.json ↗
delivery.media_available
Medien sind in einem Speicher eingetroffen — per TAMS Source oder per Nicht-TAMS-Locator. Keine Bytes, keine story_id.
delivery.media_available
der Medienspeicher (MAM / TAMS)delivery-media-available.schema.json ↗
som.system.audit
Die Governance-Spur: CLEARED, SUPPRESSED, WITHHELD oder OVERRIDDEN, bezogen auf einen Link, ein Asset oder ein Telling.
system.audit
jeder Governance-Akteursystem-audit.schema.json ↗
skill.warning.raised
Was ein Skill über eine Story deklariert hat, veröffentlicht vom Executor in dem Tool, das ihn per Recall geladen hat.
skill.warning.raised
ein Skills-Executorskill-warning.schema.json ↗
# check one message from the command line
pip install jsonschema rfc3339-validator
curl -sO https://storyobjectmodel.com/schema/1.0/story-context.schema.json

Die Familie, die Sie zuerst implementieren

story.context

Der vollständige Zustand einer Story zu einem Zeitpunkt. Pflicht: story_id, slug, headline, story_type, sequence_number, updated_at — dazu lifecycle, wenn die Story ACTIVE ist. Alles andere ist optional, und das Objekt ist geschlossen.

{
  "story_id": "hurricane-2026-0911",
  "slug": "HURRICANE-GULF",
  "headline": "Hurricane upgraded to Cat 4 after landfall",
  "story_type": "ACTIVE",
  "lifecycle": { "phase": "BREAKING",
                 "phase_entered_at": "2026-09-11T16:24:00Z" },
  "sequence_number": 4,
  "updated_at": "2026-09-11T16:26:00Z",
  "tags": [
    { "scheme": "iptc-mediatopic", "value": "17000000",
      "label": "weather" },
    { "scheme": "newsroom", "value": "us-desk" }
  ],
  "editorial_source": [ { "source_id": "src-ap-wire",
    "source_type": "WIRE", "provider": "AP",
    "credibility": "TRUSTED", "received_at": "…" } ]
}
Was eine Story sonst noch tragen kann
  • tags[] — worum es in der Story geht. Geordnet (das erste ist das primäre) und mit Schema qualifiziert: newsroom, iptc-mediatopic oder com.{vendor}.{name}.
  • priority, premise (erwarteter Ausgang, Konfidenz, ob er sich geändert hat und welche Assets das betrifft), story_meaning (ein begrenzter 5W1H-Kern).
  • assets[] mit media_refs[], provenance, standards_clearance, authenticity_credential und dem Rückindex usage[].
  • assertions[], compliance[]-Flags (mit optionalem media_range, der die eingeschränkten Frames festlegt) und editorial_gates[].
  • government_approval — ein Veröffentlichungs-Gate, über das der Executor nicht hinweg veröffentlichen darf, solange es blockiert.
  • skills_config, content_refs[], relations[], collaboration, extensions.

Eintreffende Medien

delivery.media_available

Ein Speicher meldet, dass Medien eingetroffen sind. Mehr tut die Nachricht nicht: keine Bytes, keine Zugangsdaten und bewusst keine story_id — Sie lösen asset_id → Asset → Story über den Story-Stream auf.

// a TAMS store
{
  "message_type": "delivery.media_available",
  "delivery_id":  "0190a000-0000-7000-8000-00000000aaa1",
  "asset_id":     "asset-presser-feed",
  "source":       "tams://tams-gcp-store/9f2e7c1a",
  "time_range":   "[0:0_1260:0)",
  "arrived_in":   "tams-gcp-store",
  "arrived_at":   "2026-09-11T16:30:00Z"
}

// any other store
{
  "message_type": "delivery.media_available",
  "delivery_id":  "0190a000-0000-7000-8000-00000000ccc1",
  "asset_id":     "asset-still-embassy",
  "locator": { "store": "image-mam",
               "ref":   "stills/2026/07/embassy-front-04.jpg" },
  "arrived_in":   "image-mam",
  "arrived_at":   "2026-07-09T15:00:00Z"
}
Die Regeln
  • Eines von source oder locator ist Pflicht. Eine source ist eine vollqualifizierte TAMS-Source-URI, tams://store/id — Sources, niemals Flows.
  • time_range ist eine TAMS-Timerange: Grenzen in Klammern als seconds:nanoseconds, offener Anfang oder offenes Ende erlaubt — ein Feed, der noch aufzeichnet, ist [0:0_).
  • Bei einem Locator zählt ein Bereich ab dem eigenen Nullpunkt der gespeicherten Datei, nie ab einem eingebetteten Quell-Timecode.
  • Medien werden beim redaktionellen Akt an eine Story gebunden, nie beim Ingest. Ein Clip, der zu keiner Story passt, wird in einer ORPHAN-Hüllen-Story gehalten, bis ein vorgeschlagener Treffer bestätigt ist.

Distribution

Links und Tellings

som.link.*

Asset ↔ Ziel

link.committed, link.gate_changed, link.withdrawn. Jedes Event trägt link_id, asset_id, destination_id und einen compliance_gate_status von PENDING, CLEARED oder BLOCKED. Ein Commit nennt wer und wann; ein Rückzug nennt wer, wann und warum.

Das Gate gilt pro Ziel, sodass ein Asset zugleich für Digital freigegeben und für Broadcast blockiert sein kann. assets[].usage[] der Story wird allein aus diesen Events gepflegt — nur was committet ist, und fail-closed.

som.telling.*

Exposure

telling.started (verlangt exposure_start, verbietet exposure_end), telling.ended und telling.exposed für eine augenblickliche Exposure, die beides trägt. Exposure-Zeiten sind unveränderlich; scheduled_start ist veränderlich und wird nie zur Ableitung des On-Air-Zustands genutzt.

transforms[] hält Umformungen am Rand fest — CROP, TRIM, CAPTION_BURN oder einen x--Herstellerwert — in Anwendungsreihenfolge, nur anhängend. Eine Transformation hebt nie einen Hold aus compliance[].media_range auf.

Governance

som.system.audit — die Spur

{
  "audit_id":    "0190e000-0008-7000-8000-0000000000f3",
  "action":      "SUPPRESSED",
  "target":      { "kind": "ASSET", "id": "pkg-acquit" },
  "actor":       { "actor_id": "automation-01", "actor_type": "system" },
  "reason":      "Acquit package suppressed; never linked to air",
  "recorded_at": "2026-06-23T14:30:02.000000Z"
}
  • action ist eines von CLEARED, SUPPRESSED, WITHHELD, OVERRIDDEN; target.kind ist LINK, ASSET oder TELLING.
  • Der Akteur ist ein Objekt, nie ein flacher String. Eine Unterdrückung zielt auf das zurückgehaltene Asset — der Zweig, der nie gesendet wird, bekommt nie einen Link.
  • Getrennt von den Ausführungsprotokollen der Skills. Es hält Governance fest: Freigaben, Unterdrückungen, Zurückhaltungen und Übersteuerungen, mit wer und warum.

Integration

Was Sie implementieren, nach Rolle

Sie sind…VeröffentlichenLesenAchten Sie auf
Eigentümer der Story
NCS, Planung		story.contextskill.warning.raised, Assertions von anderenJedes Feld in jedem Snapshot. Unveränderliche story_id, steigende sequence_number, neu gestempeltes originating_system.
Tool mit Executor
Rundown, MAM, CMS, Playout, Grafik		skill.warning.raisedstory.contextIhr Tool entscheidet, was es zurückhält. Bearbeiten Sie nie Inhalte, um einen Hold aufzuheben, und stellen Sie einen Hold nie als Banner mit einem Button „trotzdem veröffentlichen“ dar.
Medienspeicher
TAMS, MAM		delivery.media_available—Source-URIs, keine Flow-IDs — oder ein Locator. Melden Sie erneut mit wachsender time_range, solange die Aufnahme läuft.
Festschreibendes / ausspielendes System
CMS, Playout, Social		som.link.*, som.telling.*story.contextGate-Status pro Ziel. Exposure-Zeiten werden per Event gestempelt und sind unveränderlich.
Governance-Akteur
Standards, Recht, Automation		som.system.auditalles RelevanteAkteure sind Objekte. Halten Sie den Grund fest.

Weiter: wie ein Skill per Recall geladen wird →