storyobjectmodel.dev

Referência · SOM 1.0

As sete famílias de mensagens

Tudo o que é normativo no SOM cabe em sete JSON Schemas: o envelope, a história e cinco famílias para links, tellings, chegada de mídia, auditoria e avisos de skills. Cada um é servido numa URL que não muda durante toda a vida da 1.x.

As famíliasstory.contextChegada de mídiaLinks e tellingsAuditoriaO que implementar

Schemas

Tudo o que passa pelo fio

A maioria das famílias é opcional: implemente o envelope e as famílias sobre as quais você tem algo a dizer. A organização dos nomes de topic é com você — a única regra é o prefixo som., e os consumidores despacham por message_type, nunca pelo topic.

Famíliamessage_typePublicada porSchema
Envelope de mensagem
O invólucro fechado que toda mensagem carrega. Seu payload é polimórfico conforme o message_type.
(toda mensagem)
todo publicadorenvelope.schema.json ↗
story.context
O estado completo de uma história num dado momento — um snapshot, nunca um delta.
story.context
o dono da históriastory-context.schema.json ↗
som.telling.*
Quando um asset encontrou um público. O estado no ar é derivado destes eventos, nunca armazenado no asset.
telling.started
telling.ended
telling.exposed
o publicador de exposiçãotelling-event.schema.json ↗
som.link.*
Um asset vinculado a um destino, com um gate de compliance por destino. assets[].usage[] é mantido exclusivamente a partir destes eventos.
link.committed
link.gate_changed
link.withdrawn
o sistema que faz o commitlink-event.schema.json ↗
delivery.media_available
A mídia chegou a um repositório — por uma Source TAMS ou por um localizador fora do TAMS. Sem bytes, sem story_id.
delivery.media_available
o repositório de mídia (MAM / TAMS)delivery-media-available.schema.json ↗
som.system.audit
A trilha de governança: CLEARED, SUPPRESSED, WITHHELD ou OVERRIDDEN, sobre um link, um asset ou um telling.
system.audit
qualquer ator de governançasystem-audit.schema.json ↗
skill.warning.raised
O que uma skill declarou sobre uma história, publicado pelo executor dentro da ferramenta que a acionou (recall).
skill.warning.raised
um executor de skillsskill-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

A família que você implementa primeiro

story.context

O estado completo de uma história num dado momento. Obrigatórios: story_id, slug, headline, story_type, sequence_number, updated_at — mais lifecycle quando a história é ACTIVE. Todo o resto é opcional, e o objeto é fechado.

{
  "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": "…" } ]
}
O que mais uma história pode carregar
  • tags[] — do que trata a história. Ordenadas (a primeira é a principal) e qualificadas por esquema: newsroom, iptc-mediatopic ou com.{vendor}.{name}.
  • priority, premise (desfecho esperado, grau de confiança, se ele mudou e quais assets isso afeta), story_meaning (um núcleo 5W1H com limite de tamanho).
  • assets[] com media_refs[], provenance, standards_clearance, authenticity_credential e o índice reverso usage[].
  • assertions[], flags de compliance[] (com um media_range opcional que marca os quadros restritos) e editorial_gates[].
  • government_approval — um gate de publicação que o executor não pode ultrapassar enquanto ele estiver bloqueando.
  • skills_config, content_refs[], relations[], collaboration, extensions.

Chegada de mídia

delivery.media_available

Um repositório anunciando que uma mídia chegou. É só isso que ele faz: sem bytes, sem credenciais e, de propósito, sem story_id — você resolve asset_id → Asset → Story a partir do fluxo de histórias.

// 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"
}
As regras
  • É obrigatório um entre source e locator. Um source é uma URI de Source TAMS totalmente qualificada, tams://store/id — Sources, nunca Flows.
  • time_range é um timerange TAMS: limites seconds:nanoseconds entre colchetes, com início ou fim em aberto permitidos — um feed ainda gravando é [0:0_).
  • Com um locator, o intervalo é contado a partir do zero do próprio arquivo armazenado, nunca do timecode de origem embutido.
  • A vinculação da mídia a uma história acontece no ato editorial, nunca na ingestão. Um clipe que não corresponde a nenhuma história fica numa história-casca ORPHAN até que uma correspondência proposta seja confirmada.

Distribuição

Links e tellings

som.link.*

Asset ↔ destino

link.committed, link.gate_changed, link.withdrawn. Todo evento carrega link_id, asset_id, destination_id e um compliance_gate_status igual a PENDING, CLEARED ou BLOCKED. Um commit diz quem e quando; uma retirada diz quem, quando e por quê.

O gate é por destino, então um mesmo asset pode estar liberado para o digital e bloqueado para a TV ao mesmo tempo. O assets[].usage[] da história é mantido exclusivamente a partir desses eventos — só o que foi vinculado, e fail-closed.

som.telling.*

Exposição

telling.started (exige exposure_start, proíbe exposure_end), telling.ended e telling.exposed para uma exposição instantânea que carrega os dois. Os horários de exposição são imutáveis; scheduled_start é mutável e nunca é usado para derivar o estado no ar.

transforms[] registra as remodelagens na ponta — CROP, TRIM, CAPTION_BURN ou um valor de fornecedor x- — na ordem de aplicação, só por acréscimo. Uma transformação nunca derruba um hold de compliance[].media_range.

Governança

som.system.audit — a trilha

{
  "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 é um de CLEARED, SUPPRESSED, WITHHELD, OVERRIDDEN; target.kind é LINK, ASSET ou TELLING.
  • O ator é um objeto, nunca uma string simples. Uma supressão tem como alvo o asset retido — o ramo que nunca vai ao ar nunca ganha um link.
  • É distinto dos registros de execução de skills. Registra a governança: liberações, supressões, retenções e overrides, com quem e por quê.

Integração

O que você implementa, por papel

Você é…PublicaLêCuidado com
Dono da história
NCS, pauta		story.contextskill.warning.raised, assertions de terceirosTodos os campos em todo snapshot. story_id imutável, sequence_number crescente, originating_system carimbado de novo.
Ferramenta com um executor
espelho, MAM, CMS, playout, grafismo		skill.warning.raisedstory.contextSua ferramenta decide o que retém. Nunca edite o conteúdo para liberar um hold, e nunca mostre um hold como um banner com um botão “publicar mesmo assim”.
Repositório de mídia
TAMS, MAM		delivery.media_available—URIs de Source, não ids de Flow — ou um locator. Anuncie de novo com um time_range crescente enquanto a captura continua.
Sistema que vincula / expõe
CMS, playout, redes sociais		som.link.*, som.telling.*story.contextStatus do gate por destino. Os horários de exposição são carimbados pelo evento e imutáveis.
Ator de governança
padrões editoriais, jurídico, automação		som.system.audittudo o que for relevanteAtores são objetos. Registre o motivo.

A seguir: como uma skill é acionada (recall) →