{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://storyobjectmodel.com/schema/1.0/envelope.schema.json",
  "title": "SOM 1.0 Message Envelope",
  "description": "The envelope every SOM message carries. som_version is the schema pack version the payload conforms to — 1.0.0 for SOM 1.0. payload is polymorphic on message_type — see story-context.schema.json and the other payload families.",
  "type": "object",
  "required": ["som_version", "message_id", "correlation_id", "message_type", "timestamp", "originating_system", "topic", "payload"],
  "properties": {
    "som_version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "description": "The schema pack version the payload conforms to — 1.0.0 for SOM 1.0. Pre-1.0 values (0.3.2 and earlier) are not conformant to this specification; see spec/migration-from-v0.3.2.md. Informative, never a parsing discriminator — message_type identifies the payload family." },
    "message_id": { "type": "string", "format": "uuid", "description": "UUIDv7, time-ordered" },
    "correlation_id": { "type": "string", "format": "uuid", "description": "Required as of v0.3 (decision #18); links all messages about the same story lifecycle" },
    "causation_id": { "type": "string", "format": "uuid", "description": "Optional; ID of the message that directly caused this one" },
    "message_type": { "type": "string", "pattern": "^[a-z][a-z0-9_.]*$", "examples": ["story.context", "skill.warning.raised", "skill.suggestion.created", "skill.run.completed"] },
    "timestamp": { "type": "string", "format": "date-time", "description": "Microsecond precision recommended. Skill-output timestamp lives HERE, not in the payload (decision #18)" },
    "originating_system": { "$ref": "#/$defs/originating_system" },
    "topic": { "type": "string", "pattern": "^som\\.", "description": "Required per the #18 envelope lock" },
    "modification_header": {
      "type": "object",
      "description": "On snapshot-style messages such as story.context",
      "properties": {
        "story_version": { "type": "integer" },
        "modified_at": { "type": "string", "format": "date-time" },
        "modified_by": { "type": "string" },
        "change_summary": { "type": "string" },
        "history": { "type": "array" }
      }
    },
    "_actors": { "type": "object", "description": "Key-value map of short-key actor lookups" },
    "payload": { "type": "object" },
    "extensions": {
      "type": "object",
      "description": "Vendor fields, reverse-domain namespaced (com.{vendor}.*); consumers ignore-if-unknown",
      "patternProperties": { "^com\\.[a-z0-9-]+\\.": {} },
      "additionalProperties": false
    },
    "@context": { "description": "JSON-LD context — DEFERRED in v0.3 (decision #18); permitted for forward compatibility", "anyOf": [{ "type": "string" }, { "type": "object" }] },
    "source": false,
    "signature": false
  },
  "additionalProperties": false,
  "$defs": {
    "originating_system": {
      "type": "object",
      "description": "Renamed from `source` (first leg of the four-way source disambiguation)",
      "required": ["system_id", "system_type"],
      "properties": {
        "system_id": { "type": "string" },
        "system_type": { "type": "string", "enum": ["ncs", "mos_device", "graphics", "automation", "wire_service", "ai_agent", "compliance_engine", "editorial_dashboard", "archive", "prompter", "camera", "audio", "skill_worker", "custom"] },
        "system_name": { "type": "string" },
        "vendor": { "type": "string" },
        "version": { "type": "string" }
      },
      "additionalProperties": false
    }
  }
}