storyobjectmodel.dev

Referencia · SOM 1.0

Las siete familias de mensajes

Todo lo normativo de SOM son siete JSON Schemas: el envelope, la Story y cinco familias para links, Tellings, llegadas de medios, auditoría y advertencias de skills. Cada uno se sirve en una URL que no cambiará durante toda la vida de 1.x.

Las familiasstory.contextLlegadas de mediosLinks y TellingsAuditoríaQué implementar

Schemas

Todo lo que viaja por el cable

La mayoría de las familias son opcionales: implementa el envelope y las familias sobre las que tengas algo que decir. La estructura de los nombres de topic es cosa tuya — la única regla es el prefijo som., y los consumidores despachan según message_type, nunca según el topic.

Familiamessage_typePublicado porSchema
Envelope del mensaje
El envoltorio cerrado que lleva cada mensaje. Su payload es polimórfico según message_type.
(todos los mensajes)
todo publicadorenvelope.schema.json ↗
story.context
El estado completo de una Story en un momento dado — un snapshot, nunca un delta.
story.context
el propietario de la Storystory-context.schema.json ↗
som.telling.*
Cuándo un Asset llegó a una audiencia. El estado «al aire» se deriva de estos eventos, nunca se guarda en el Asset.
telling.started
telling.ended
telling.exposed
el publicador de la exposicióntelling-event.schema.json ↗
som.link.*
Un Asset vinculado a un destino, con un gate de cumplimiento por destino. assets[].usage[] se mantiene exclusivamente a partir de estos eventos.
link.committed
link.gate_changed
link.withdrawn
el sistema que confirma el vínculolink-event.schema.json ↗
delivery.media_available
Han llegado medios a un almacén — por TAMS Source o por un localizador no TAMS. Sin bytes, sin story_id.
delivery.media_available
el almacén de medios (MAM / TAMS)delivery-media-available.schema.json ↗
som.system.audit
El rastro de gobernanza: CLEARED, SUPPRESSED, WITHHELD u OVERRIDDEN, sobre un link, un Asset o un Telling.
system.audit
cualquier actor de gobernanzasystem-audit.schema.json ↗
skill.warning.raised
Lo que una skill declaró sobre una Story, publicado por el executor dentro de la herramienta que la invocó.
skill.warning.raised
un 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

La familia que implementas primero

story.context

El estado completo de una Story en un momento dado. Obligatorios: story_id, slug, headline, story_type, sequence_number, updated_at — más lifecycle cuando la Story es ACTIVE. Todo lo demás es opcional, y el objeto es cerrado.

{
  "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": "…" } ]
}
Qué más puede llevar una Story
  • tags[] — de qué trata la Story. Ordenadas (la primera es la principal) y calificadas por esquema: newsroom, iptc-mediatopic o com.{vendor}.{name}.
  • priority, premise (resultado esperado, confianza, si cambió y a qué Assets afecta), story_meaning (un núcleo 5W1H acotado).
  • assets[] con media_refs[], provenance, standards_clearance, authenticity_credential y el índice inverso usage[].
  • assertions[], flags de compliance[] (con un media_range opcional que fija los fotogramas restringidos) y editorial_gates[].
  • government_approval — un gate de publicación que el executor no debe sobrepasar mientras bloquee.
  • skills_config, content_refs[], relations[], collaboration, extensions.

Llegadas de medios

delivery.media_available

Un almacén que anuncia que han llegado medios. Eso es todo lo que hace: sin bytes, sin credenciales y, a propósito, sin story_id — la resolución asset_id → Asset → Story se hace a partir del flujo de Stories.

// 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"
}
Las reglas
  • Se exige source o locator. Un source es una URI de TAMS Source totalmente calificada, tams://store/id — Sources, nunca Flows.
  • time_range es un timerange de TAMS: límites seconds:nanoseconds entre corchetes, con inicio o final abiertos permitidos — una señal que aún se está grabando es [0:0_).
  • Frente a un localizador, un rango se mide desde el cero propio del archivo almacenado, nunca desde el timecode de origen incrustado.
  • La vinculación de medios a una Story ocurre en el acto editorial, nunca en la ingesta. Un clip que no coincide con ninguna Story se guarda en una Story contenedora ORPHAN hasta que se confirma una coincidencia propuesta.

Distribución

Links y Tellings

som.link.*

Asset ↔ destino

link.committed, link.gate_changed, link.withdrawn. Cada evento lleva link_id, asset_id, destination_id y un compliance_gate_status PENDING, CLEARED o BLOCKED. Una vinculación indica quién y cuándo; una retirada, quién, cuándo y por qué.

El gate es por destino, así que un mismo Asset puede estar aprobado para digital y bloqueado para emisión a la vez. El assets[].usage[] de la Story se mantiene exclusivamente a partir de estos eventos — solo lo vinculado, y fail-closed.

som.telling.*

Exposición

telling.started (exige exposure_start, prohíbe exposure_end), telling.ended, y telling.exposed para una exposición instantánea que lleva ambos. Los tiempos de exposición son inmutables; scheduled_start es mutable y nunca se usa para derivar el estado «al aire».

transforms[] registra las adaptaciones en el borde — CROP, TRIM, CAPTION_BURN o un valor de fabricante x- — en orden de aplicación y solo por adición. Una transformación nunca levanta un hold de compliance[].media_range.

Gobernanza

som.system.audit — el rastro

{
  "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 es uno de CLEARED, SUPPRESSED, WITHHELD, OVERRIDDEN; target.kind es LINK, ASSET o TELLING.
  • El actor es un objeto, nunca una cadena plana. Una supresión apunta al Asset retenido — la rama que nunca sale al aire nunca recibe un link.
  • Distinto de los registros de ejecución de skills. Registra la gobernanza: aprobaciones, supresiones, retenciones y anulaciones, con quién y por qué.

Integración

Qué implementas, según tu papel

Eres…PublicasLeesCuidado con
Propietario de la Story
NCS, planificación		story.contextskill.warning.raised, assertions de otrosTodos los campos en cada snapshot. story_id inmutable, sequence_number creciente, originating_system vuelto a sellar.
Herramienta con executor
escaleta, MAM, CMS, playout, grafismo		skill.warning.raisedstory.contextTu herramienta decide qué retiene. Nunca edites contenido para liberar un hold, y nunca muestres un hold como un aviso con un botón de «publicar de todos modos».
Almacén de medios
TAMS, MAM		delivery.media_available—URIs de Source, no ids de Flow — o un localizador. Vuelve a anunciar con un time_range creciente mientras continúe la captura.
Sistema que vincula / expone
CMS, playout, redes sociales		som.link.*, som.telling.*story.contextEstado del gate por destino. Los tiempos de exposición se sellan en el evento y son inmutables.
Actor de gobernanza
estándares, legal, automatización		som.system.audittodo lo relevanteLos actores son objetos. Registra el motivo.

Siguiente: cómo se invoca una skill →