{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aaep-protocol.org/schemas/v1/envelope.schema.json",
  "title": "AAEP Event Envelope",
  "description": "The required structure of fields that every AAEP event carries, independent of event type. Defined normatively in Chapter 3 of the AAEP specification. Event-type-specific schemas reference this envelope via $ref and extend it with their own payload fields.",
  "type": "object",
  "required": [
    "@context",
    "type",
    "event_id",
    "session_id",
    "timestamp",
    "producer"
  ],
  "properties": {
    "@context": {
      "description": "JSON-LD context identifying the vocabularies used in this event. MUST be either the AAEP core context URL as a string, or an array whose first element is the AAEP core context URL.",
      "oneOf": [
        {
          "type": "string",
          "const": "https://aaep-protocol.org/context/v1"
        },
        {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "format": "uri"
          },
          "prefixItems": [
            {
              "type": "string",
              "const": "https://aaep-protocol.org/context/v1"
            }
          ]
        }
      ]
    },
    "aaep_version": {
      "description": "The AAEP specification version the producer claims to follow. Recommended.",
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[A-Za-z0-9.-]+)?$",
      "examples": [
        "1.0.0",
        "0.1.0-draft"
      ]
    },
    "type": {
      "description": "URI or compact prefixed identifier for the event's semantic category. Core AAEP types use the `aaep:` prefix. Extensions use their own namespaces.",
      "type": "string",
      "minLength": 1,
      "examples": [
        "aaep:agent.session.started",
        "aaep:agent.tool.invoked",
        "aaep:agent.awaiting.confirmation",
        "medai:patient.consulted"
      ]
    },
    "event_id": {
      "description": "Unique identifier for the event, formatted as `evt_` followed by 1-64 alphanumeric characters. Generated by the producer and globally unique within the producer's emission stream.",
      "type": "string",
      "pattern": "^evt_[A-Za-z0-9]{1,64}$",
      "examples": [
        "evt_8a3f5b22c91e4d7a",
        "evt_8a3f5b22c91e4d7a3f5b22c91e4d7a3f"
      ]
    },
    "session_id": {
      "description": "Identifier linking this event to its enclosing session. Formatted as `sess_` followed by 1-64 alphanumeric characters. Stable across all events of the same session.",
      "type": "string",
      "pattern": "^sess_[A-Za-z0-9]{1,64}$",
      "examples": [
        "sess_2c91a7b4d23f1e88",
        "sess_2c91a7b4d23f1e88a7b4d23f1e88a7b4"
      ]
    },
    "sequence_number": {
      "description": "Optional monotonically-increasing position of this event within its session. If present, MUST be 0 for `agent.session.started` and increment by exactly 1 for each subsequent event.",
      "type": "integer",
      "minimum": 0
    },
    "timestamp": {
      "description": "RFC 3339 / ISO 8601 timestamp indicating when the producer emitted this event. UTC (`Z` suffix) or explicit offset. Millisecond precision recommended.",
      "type": "string",
      "format": "date-time",
      "examples": [
        "2026-05-24T14:22:11.342Z",
        "2026-05-24T15:22:11.342+01:00"
      ]
    },
    "producer": {
      "$ref": "#/$defs/Producer"
    },
    "verbosity": {
      "description": "The verbosity level at which this event's human-readable strings are written. Subscribers indicate their preferred verbosity during subscription handshake.",
      "type": "string",
      "enum": ["terse", "normal", "detailed"],
      "default": "normal"
    },
    "urgency": {
      "description": "The producer's recommended priority for this event. `critical` events are exempt from filtering and rate limiting and MUST be delivered promptly.",
      "type": "string",
      "enum": ["background", "normal", "critical"],
      "default": "normal"
    },
    "localization_hints": {
      "$ref": "#/$defs/LocalizationHints"
    },
    "correlation_id": {
      "description": "Optional trace identifier for correlating this event with observability data outside AAEP. Compatible with W3C Trace Context format.",
      "type": "string",
      "examples": [
        "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
      ]
    },
    "extensions": {
      "description": "Optional namespaced object carrying extension fields. Keys are extension prefixes declared in `@context`. Each value is an object containing the extension's own fields.",
      "type": "object",
      "additionalProperties": {
        "type": "object"
      },
      "examples": [
        {
          "medai": {
            "patient_data_accessed": true,
            "phi_categories": ["medications", "medical_history"]
          }
        }
      ]
    }
  },
  "$defs": {
    "Producer": {
      "description": "Identifies the entity emitting the event. Required on every event.",
      "type": "object",
      "required": ["agent_id"],
      "properties": {
        "agent_id": {
          "description": "Stable identifier for the producer. MUST NOT encode version. Recommended convention is a reverse-DNS-style identifier or a short stable slug.",
          "type": "string",
          "minLength": 1,
          "examples": [
            "retirement-planner",
            "com.example.product.support-agent"
          ]
        },
        "agent_version": {
          "description": "The producer's version. Semantic versioning recommended.",
          "type": "string",
          "examples": ["1.4.2", "2.0.0-rc.1"]
        },
        "agent_name": {
          "description": "Human-readable name suitable for announcing to the user.",
          "type": "string",
          "examples": ["Retirement Planning Assistant"]
        },
        "model": {
          "description": "Identifier for the underlying model the agent uses.",
          "type": "string",
          "examples": [
            "claude-opus-4-7",
            "gpt-5-turbo",
            "gemini-2-pro"
          ]
        },
        "manifest_uri": {
          "description": "URI to the producer's published manifest, where the manifest describes capabilities and supported transports.",
          "type": "string",
          "format": "uri",
          "examples": [
            "https://example.com/.well-known/aaep-manifest.json"
          ]
        }
      },
      "additionalProperties": false
    },
    "LocalizationHints": {
      "description": "Structured object describing the language, locale, and text characteristics of human-readable strings in the event payload. See Chapter 11 of the AAEP specification.",
      "type": "object",
      "properties": {
        "primary_language": {
          "description": "BCP 47 language tag for the primary language of this event's text. Required on events with human-readable payload.",
          "type": "string",
          "pattern": "^[a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})*$",
          "examples": [
            "en-US",
            "es-419",
            "yo-NG",
            "ha-NG",
            "ig-NG",
            "sw-KE",
            "ar-SA",
            "zh-Hans",
            "he-IL",
            "ja-JP",
            "pt-BR"
          ]
        },
        "text_direction": {
          "description": "Writing direction. `auto` defers to the Unicode Bidirectional Algorithm (UAX #9).",
          "type": "string",
          "enum": ["ltr", "rtl", "auto"],
          "default": "ltr"
        },
        "available_languages": {
          "description": "Other languages the producer could provide for this event if requested.",
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})*$"
          },
          "maxItems": 32,
          "uniqueItems": true
        },
        "fallback_chain": {
          "description": "Ordered list of languages to try if `primary_language` is unavailable.",
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})*$"
          },
          "maxItems": 16
        },
        "script": {
          "description": "ISO 15924 script code, if not implied by `primary_language`.",
          "type": "string",
          "pattern": "^[A-Z][a-z]{3}$",
          "examples": ["Latn", "Cyrl", "Arab", "Hans", "Hant", "Hebr"]
        },
        "calendar": {
          "description": "Preferred calendar system for date/time formatting.",
          "type": "string",
          "examples": ["gregorian", "islamic", "hebrew", "japanese", "buddhist"]
        }
      },
      "additionalProperties": false
    }
  },
  "examples": [
    {
      "@context": "https://aaep-protocol.org/context/v1",
      "type": "aaep:agent.session.started",
      "event_id": "evt_8a3f5b22c91e4d7a",
      "session_id": "sess_2c91a7b4d23f1e88",
      "timestamp": "2026-05-24T14:22:11.342Z",
      "producer": {
        "agent_id": "retirement-planner",
        "agent_version": "1.4.2"
      }
    },
    {
      "@context": [
        "https://aaep-protocol.org/context/v1",
        "https://example.org/medai/context/v1"
      ],
      "aaep_version": "1.0.0",
      "type": "aaep:agent.tool.invoked",
      "event_id": "evt_8a3f5b22c91e4d7a3f5b22c91e4d7a3f",
      "session_id": "sess_2c91a7b4d23f1e88a7b4d23f1e88a7b4",
      "sequence_number": 7,
      "timestamp": "2026-05-24T14:22:11.342Z",
      "producer": {
        "agent_id": "clinical-assistant",
        "agent_version": "2.1.0",
        "agent_name": "Clinical Decision Support Assistant",
        "model": "claude-opus-4-7",
        "manifest_uri": "https://hospital.example/.well-known/aaep-manifest.json"
      },
      "verbosity": "normal",
      "urgency": "normal",
      "localization_hints": {
        "primary_language": "en-US",
        "text_direction": "ltr",
        "available_languages": ["en-US", "es-419"]
      },
      "correlation_id": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
      "extensions": {
        "medai": {
          "patient_data_accessed": true,
          "phi_categories": ["medications", "medical_history"]
        }
      }
    }
  ]
}