Referencia · SOM 1.0
El envelope
Un único envoltorio, compartido por todos los mensajes de todas las familias. Es un objeto cerrado: los campos de primer nivel desconocidos no pasan la validación, y los antiguos campos source y signature se rechazan sin más.
Anatomía
Cada campo, uno a uno
Haz clic en una clave para ver qué lleva y dónde suele confundir a la gente. Los valores de ejemplo siguen el paso 6 del caso práctico del huracán de la especificación.
som_version
La versión del paquete de schemas a la que se ajusta el payload — "1.0.0" para SOM 1.0.
Solo informativo: los consumidores NO DEBEN tomar decisiones en función de él. "0.3.2" no es SOM 1.0 — tres campos se retiraron antes de la ratificación —, así que un consumidor no debe tratarlo como conforme.
Schema: https://storyobjectmodel.com/schema/1.0/envelope.schema.json ↗
Conformidad
El listón está más bajo de lo que crees
Un sistema es conforme con SOM 1.0 si cada mensaje que publica es un envelope válido, cada payload valida contra el schema de su message_type declarado, e ignora lo que no reconoce. Un sistema de planificación que solo publica story.context y solo lee advertencias es plenamente conforme.
Emite "1.0.0", nunca decidas en función de él
Los productores emiten la versión del paquete con la que son conformes; un futuro productor 1.1 emitirá "1.1.0". Los consumidores no deben cambiar su comportamiento según som_version — eso se rompe en 1.1 por definición. Y "0.3.2" no es SOM 1.0: el schema deja el campo abierto, así que un consumidor conforme tiene que aplicar esta regla por su cuenta.
message_type es el único discriminador
Elige el schema del payload a partir de él. No del topic, de un nombre de archivo, de la identidad del publicador ni de la forma del payload.
Valida format
JSON Schema trata format como una anotación, así que la mayoría de los validadores aceptan "message_id": "NOT-A-UUID" sin un solo error. La conformidad exige validar uuid y date-time — en Node, ajv/dist/2020 más ajv-formats; en Python, un format_checker y rfc3339-validator.
Ignora lo que no reconozcas
Las claves de extensions desconocidas se ignoran; nunca son motivo de rechazo. Un message_type que no manejas también se ignora — y eso es lo que permite que 1.x añada familias sin romper nada a nadie.
correlation_id y topic son obligatorios
correlation_id enlaza todos los mensajes sobre el ciclo de vida de una Story. topic debe empezar por som. — más allá de eso, la estructura de topics es cosa tuya.
Di qué produces y qué consumes
Las implementaciones deberían indicar qué familias publican y cuáles leen. Esa declaración, y no el tamaño de la implementación, es lo que necesita un integrador. spec/conformance.md ↗
Payload
skill.warning.raised
Lo que una skill declaró sobre una Story, puesto en el bus por el executor de la herramienta que la invocó. Doce campos obligatorios, un objeto cerrado y dos campos prohibidos explícitamente.
warning_id
Identidad de esta advertencia.
link:{link_id} para una skill específica de un destino, asset:{asset_id} para un Asset, story:{story_id} para toda la Story.
Una aprobación solo cuenta en el alcance en que se declaró el hold: una aprobación de link nunca levanta un hold de story.
El payload de la advertencia rechaza tanto timestamp como el retirado instance_ref. Cuándo se levantó la advertencia lo dice el timestamp del envelope; qué la causó, el causation_id del envelope.
Migración
Si vienes de v0.3.2
1.0 es una ruptura limpia, y pequeña: deja de emitir tres campos retirados, emite som_version: "1.0.0" y activa la validación de formatos. Todos los demás campos, tipos, enums y restricciones siguen igual.
| Retirado en 1.0 | Qué era |
|---|---|
assets[].voice_count | Un entero opcional que llevaba una regla de clasificación editorial que nunca llegó a cerrarse. |
assets[].status → FINALIZING | Un valor de enum propuesto para una salida derivada que aún se está terminando; nunca se ratificó. |
transforms[].transform_id | Un identificador de auditoría estable y opcional para una única transformación; todavía en discusión. |
Cada $id de schema es ahora una URL resoluble que sirve el archivo, como https://storyobjectmodel.com/schema/1.0/story-context.schema.json, estable durante toda la vida de 1.x. Los antiguos identificadores som.spec/schema/v0.3… nunca fueron resolubles.
Los tres directorios de versión desaparecen: un archivo por familia, sin versión en el nombre. Todo lo que se despachaba según "v0.3.2" en una ruta de schema debe seleccionar por familia. authenticity_credential, propuesto en v0.3.2, llega a 1.0 como normativo.
spec/migration-from-v0.3.2.md ↗ · spec/compatibility-policy.md ↗
Renombrados y retirados
Rutas antiguas que ya no validan
Si un productor o una configuración es anterior al cierre del envelope en v0.3, estos campos se han movido — o los rechazan los schemas de 1.0.
| Antes | Ahora |
|---|---|
source (envelope) | originating_system — el campo antiguo se rechaza de plano |
signature (envelope) | Rechazado de plano. No existe ningún campo de firma. |
sources[] | editorial_source[] — credibilidad TRUSTED | VERIFIED | ENDORSED | UNVERIFIED |
skills_config.broadcaster | skills_config.newsroom (la clave antigua se rechaza) |
broadcaster_id | Rechazado de plano. newsroom_id es opcional en 1.0 y, si falta, se deriva de skills_config.newsroom |
collaboration.version | collaboration.editing_version |
content_ref (singular) | content_refs[] |
instances[] | Rechazado de plano. La distribución se modela con links y Tellings |
instance_ref (warning) | Rechazado de plano. Las salidas se acotan mediante scope: link:, asset: o story: |
ai_enrichments[] | Rechazado de plano desde v0.3.2. La salida generativa que se publica es una entrada de assets[] con provenance; las afirmaciones sobre el contenido son assertions[] |
media_refs[].flow_id | source (tams://store/id) + time_range, o un locator |
editorial_gates[].blocks as strings | Obsoleto. Usa { "kind": "ASSET" | "PHASE", "ref": … } |
Extensions
El lugar definido para lo que el estándar no lleva
El envelope, la Story y todas las familias de eventos aceptan un objeto extensions cuyas claves deben coincidir con com.{vendor}. — cualquier otra cosa no pasa la validación. Los consumidores ignoran las claves que no reconocen.
{
"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."
}
}- Los valores de enum de fabricante siguen otra convención:
x-más un token en minúsculas —x-graphics_pack. Se aplica a los registros gobernados pero ampliables, comoasset_type,source_typeytransform_type. - Las etiquetas tienen su propio esquema de fabricante:
com.{vendor}.{name}, junto anewsroomeiptc-mediatopic.
Siguiente: las siete familias a las que pertenecen estos mensajes →