{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://bot.yoyoo.org/schemas/v1/bot-platform-event.schema.json",
  "title": "BotPlatformEvent",
  "description": "YoYoo Bot 开放平台入站事件信封。对齐 CloudEvents 1.0（https://cloudevents.io），经 WebSocket 推送或 Webhook POST 投递；同一 Bot 在任一时刻仅启用一种入站投递模式。",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "specversion",
    "id",
    "type",
    "source",
    "time",
    "datacontenttype",
    "subject",
    "data"
  ],
  "properties": {
    "specversion": {
      "type": "string",
      "const": "1.0",
      "description": "CloudEvents 规范版本。本平台 v1 固定为 \"1.0\"。"
    },
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "事件全局唯一 ID，用于幂等与去重。平台保证在保留窗口内不重复；开发者须按 id 排重。建议格式：evt_<ulid>。"
    },
    "type": {
      "type": "string",
      "pattern": "^io\\.yoyoo\\.bot\\.v1\\.[A-Za-z]+$",
      "description": "事件类型，反向域名命名。v1 见 MessageReceived、MessageEdited、MembershipChanged 等枚举。"
    },
    "source": {
      "type": "string",
      "format": "uri",
      "description": "事件来源 URI。固定为 Bot 资源地址，例如 https://bot.yoyoo.org/v1/bots/{bot_id}。"
    },
    "time": {
      "type": "string",
      "format": "date-time",
      "description": "平台生成该 CloudEvent 的时间，RFC 3339（含时区），例如 2026-08-26T02:14:00Z。"
    },
    "datacontenttype": {
      "type": "string",
      "const": "application/json",
      "description": "data 字段的 MIME 类型。v1 固定 application/json。"
    },
    "subject": {
      "type": "string",
      "minLength": 1,
      "description": "事件主题，通常为 Matrix 房间 ID（!roomId:server）或 Bot ID，便于路由与日志检索。"
    },
    "data": {
      "type": "object",
      "description": "业务载荷。结构由 type 决定；见各 *-data.schema.json。"
    }
  },
  "examples": [
    {
      "specversion": "1.0",
      "id": "evt_01J8XK2M5QZ8Y3VW4N6P7R8S9T",
      "type": "io.yoyoo.bot.v1.MessageReceived",
      "source": "https://bot.yoyoo.org/v1/bots/bot_01HABC",
      "time": "2026-08-26T02:14:00.123Z",
      "datacontenttype": "application/json",
      "subject": "!roomId:yoyoo.org",
      "data": {
        "bot_id": "bot_01HABC",
        "matrix": {
          "room_id": "!roomId:yoyoo.org",
          "event_id": "$eventId:yoyoo.org",
          "sender_id": "@alice:yoyoo.org"
        },
        "message": {
          "body": "你好",
          "msgtype": "m.text",
          "format": "plain"
        },
        "context": {
          "is_direct": true,
          "is_mention": false,
          "thread_root_event_id": null
        }
      }
    }
  ]
}