Referenz · SOM 1.0
Das Envelope
Eine Hülle für alle Nachrichten aller Familien. Sie ist ein geschlossenes Objekt: Unbekannte Felder auf oberster Ebene fallen bei der Validierung durch, und die Altfelder source und signature werden rundweg abgewiesen.
Anatomie
Jedes Feld, eins nach dem anderen
Klicken Sie auf einen Schlüssel, um zu lesen, was er trägt und wo man darüber stolpert. Die Beispielwerte folgen Beat 6 des durchgerechneten Hurrikan-Beispiels aus der Spezifikation.
som_version
Die Version des Schema-Pakets, der das Payload entspricht — "1.0.0" für SOM 1.0.
Rein informativ: Consumer DÜRFEN NICHT danach verzweigen. "0.3.2" ist nicht SOM 1.0 — drei Felder wurden vor der Ratifizierung zurückgezogen —, ein Consumer darf es also nicht als konform behandeln.
Schema: https://storyobjectmodel.com/schema/1.0/envelope.schema.json ↗
Konformität
Die Hürde liegt niedriger, als Sie denken
Ein System ist konform mit SOM 1.0, wenn jede Nachricht, die es veröffentlicht, ein gültiges Envelope ist, jedes Payload gegen das Schema seines angegebenen message_type validiert und es ignoriert, was es nicht kennt. Ein Planungssystem, das nur story.context veröffentlicht und nur Warnungen liest, ist vollständig konform.
"1.0.0" senden, nie danach verzweigen
Producer senden die Paketversion, der sie entsprechen; ein künftiger 1.1-Producer sendet "1.1.0". Consumer dürfen ihr Verhalten nicht an som_version festmachen — das bricht per Definition mit 1.1. Und "0.3.2" ist nicht SOM 1.0: Das Schema lässt das Feld offen, ein konformer Consumer muss diese Regel also selbst anwenden.
message_type ist der einzige Diskriminator
Wählen Sie das Payload-Schema danach aus. Nicht nach dem Topic, einem Dateinamen, der Identität des Publishers oder der Form des Payloads.
format durchsetzen
JSON Schema behandelt format als Annotation, deshalb akzeptieren die meisten Validatoren "message_id": "NOT-A-UUID" ohne einen einzigen Fehler. Konformität verlangt die Assertion für uuid und date-time — in Node mit ajv/dist/2020 plus ajv-formats; in Python mit einem format_checker und rfc3339-validator.
Ignorieren, was Sie nicht kennen
Unbekannte Schlüssel in extensions werden ignoriert, nie als Grund zur Abweisung. Ein message_type, den Sie nicht verarbeiten, wird ebenfalls ignoriert — genau das erlaubt es 1.x, Familien hinzuzufügen, ohne jemanden zu brechen.
correlation_id und topic sind Pflicht
correlation_id verbindet alle Nachrichten zum Lebenszyklus einer Story. topic muss mit som. beginnen — darüber hinaus ist die Topic-Struktur Ihre Sache.
Sagen Sie, was Sie produzieren und konsumieren
Implementierungen sollten angeben, welche Familien sie veröffentlichen und welche sie lesen. Diese Angabe, nicht der Umfang der Implementierung, ist das, was ein Integrator braucht. spec/conformance.md ↗
Payload
skill.warning.raised
Was ein Skill über eine Story deklariert hat, auf den Bus gelegt vom Executor in dem Tool, das ihn per Recall geladen hat. Zwölf Pflichtfelder, ein geschlossenes Objekt und zwei ausdrücklich verbotene Felder.
warning_id
Identität dieser Warnung.
link:{link_id} für einen zielspezifischen Skill, asset:{asset_id} für ein einzelnes Asset, story:{story_id} für die ganze Story.
Eine Freigabe zählt nur auf dem Scope, auf dem der Hold deklariert wurde: Eine link-Freigabe hebt nie einen story-Hold auf.
Das Warnungs-Payload weist sowohl timestamp als auch das ausgemusterte instance_ref ab. Wann die Warnung ausgelöst wurde, sagt der timestamp des Envelopes; was sie verursacht hat, dessen causation_id.
Migration
Umstieg von v0.3.2
1.0 ist ein sauberer Bruch, und ein kleiner: Senden Sie drei zurückgezogene Felder nicht mehr, senden Sie som_version: "1.0.0" und schalten Sie die Format-Assertion ein. Alle anderen Felder, Typen, Enums und Constraints bleiben unverändert.
| Zurückgezogen in 1.0 | Was es war |
|---|---|
assets[].voice_count | Ein optionaler Integer für eine redaktionelle Klassifizierungsregel, die nie abschließend geklärt wurde. |
assets[].status → FINALIZING | Ein Enum-Wert, vorgeschlagen für eine abgeleitete Ausgabe, die noch fertiggestellt wird; nie ratifiziert. |
transforms[].transform_id | Ein optionaler, stabiler Audit-Handle für eine einzelne Transformation; noch in Diskussion. |
Jede Schema-$id ist jetzt eine auflösbare URL, die die Datei ausliefert, etwa https://storyobjectmodel.com/schema/1.0/story-context.schema.json, stabil für die gesamte Lebensdauer von 1.x. Die alten som.spec/schema/v0.3…-Identifier waren nie auflösbar.
Die drei Versionsverzeichnisse sind weg: eine Datei pro Familie, keine Version im Dateinamen. Alles, was anhand von "v0.3.2" in einem Schema-Pfad verzweigt hat, muss stattdessen nach der Familie auswählen. authenticity_credential, in v0.3.2 vorgeschlagen, ist in 1.0 normativ.
spec/migration-from-v0.3.2.md ↗ · spec/compatibility-policy.md ↗
Umbenannt & ausgemustert
Alte Pfade, die nicht mehr validieren
Stammt ein Producer oder eine Konfiguration aus der Zeit vor dem Envelope-Lock in v0.3, dann sind diese Felder umgezogen — oder werden von den 1.0-Schemas abgewiesen.
| Alt | Jetzt |
|---|---|
source (envelope) | originating_system — das alte Feld wird hart abgewiesen |
signature (envelope) | Hart abgewiesen. Ein Feld signature gibt es nicht. |
sources[] | editorial_source[] — Glaubwürdigkeit TRUSTED | VERIFIED | ENDORSED | UNVERIFIED |
skills_config.broadcaster | skills_config.newsroom (der alte Schlüssel wird abgewiesen) |
broadcaster_id | Hart abgewiesen. newsroom_id ist in 1.0 optional und wird, falls es fehlt, aus skills_config.newsroom abgeleitet |
collaboration.version | collaboration.editing_version |
content_ref (singular) | content_refs[] |
instances[] | Hart abgewiesen. Distribution wird über Links und Tellings modelliert |
instance_ref (warning) | Hart abgewiesen. Ausgaben erhalten ihren Scope über scope: link:, asset: oder story: |
ai_enrichments[] | Hart abgewiesen seit v0.3.2. Generierte Ausgabe, die veröffentlicht wird, ist ein Eintrag in assets[] mit provenance; Aussagen über Inhalte sind assertions[] |
media_refs[].flow_id | source (tams://store/id) + time_range oder ein locator |
editorial_gates[].blocks as strings | Veraltet. Verwenden Sie { "kind": "ASSET" | "PHASE", "ref": … } |
Extensions
Der vorgesehene Ort für alles, was der Standard nicht trägt
Envelope, Story und jede Event-Familie akzeptieren ein extensions-Objekt, dessen Schlüssel auf com.{vendor}. passen müssen — alles andere fällt bei der Validierung durch. Consumer ignorieren Schlüssel, die sie nicht kennen.
{
"warning_id": "0190a000-0000-7000-8000-00000000000a",
"skill_id": "nbcu/editorial-standards",
"scope": "link:l1",
"severity": "flag",
"detail": "Informal term 'cops' in headline.",
"extensions": {
"com.nbcu.rationale": "Style guide proscribes informal register in headlines."
}
}- Für herstellereigene Enum-Werte gilt eine andere Konvention:
x-plus ein kleingeschriebenes Token —x-graphics_pack. Sie gilt für die geregelten, aber erweiterbaren Register wieasset_type,source_typeundtransform_type. - Tags haben ein eigenes Herstellerschema:
com.{vendor}.{name}nebennewsroomundiptc-mediatopic.
Weiter: die sieben Familien, zu denen diese Nachrichten gehören →