{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api.forgeling.io/schemas/event_envelope.json",
  "title": "Event envelope",
  "description": "What every event, webhook body and stream record looks like around its type's data.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "type",
    "created_at",
    "api_version",
    "workspace",
    "stream",
    "turn_id",
    "source",
    "data"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$"
    },
    "type": {
      "type": "string",
      "description": "The event type. Clients ignore types they do not know."
    },
    "created_at": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
      "description": "When the API ingested the event, never the sandbox's clock."
    },
    "api_version": {
      "const": "2026-11-01"
    },
    "workspace": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": false,
      "required": [
        "id",
        "external_id"
      ],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^ws_[0-9A-HJKMNP-TV-Z]{26}$"
        },
        "external_id": {
          "type": "string"
        }
      },
      "description": "The workspace of the event; null for bundle.* and ping."
    },
    "stream": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": false,
      "required": [
        "type",
        "id",
        "seq"
      ],
      "properties": {
        "type": {
          "const": "run"
        },
        "id": {
          "type": "string",
          "pattern": "^run_[0-9A-HJKMNP-TV-Z]{26}$"
        },
        "seq": {
          "type": "integer",
          "minimum": 1,
          "description": "Gap-free within the stream."
        }
      },
      "description": "The stream of the event; null for workspace.*, bundle.* and ping."
    },
    "turn_id": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^trn_[0-9A-HJKMNP-TV-Z]{26}$",
      "description": "The turn the event belongs to, if any."
    },
    "source": {
      "enum": [
        "platform",
        "sandbox"
      ]
    },
    "repo_policy": {
      "enum": [
        "require_push_block",
        "allow_unprotected"
      ],
      "description": "Present only on runs that set it."
    },
    "metadata": {
      "type": "object",
      "additionalProperties": true,
      "description": "Present only when turn_id is set: the turn's metadata, echoed as the app sent it."
    },
    "data": {
      "type": "object",
      "additionalProperties": true,
      "description": "The payload; its schema is events/<type>.json."
    }
  }
}