BLUEPRINT
5 Schema与交付物关系
第五章：Schema 与交付物关系
本章描述 CAP 项目的交付物体系结构，明确协议 Schema 定义文件在交付物中的核心地位，以及 Schema 版本与协议版本的对应关系。理解交付物之间的层级关系和依赖关系，是协议实现者和社区贡献者参与项目协作的基础。
5.1 三类核心交付物
CAP 项目的交付物体系由三类核心交付物组成，从文档到定义到实现形成完整的交付链：
| 交付物类别 | 说明 | 仓库路径示例 |
|---|---|---|
| 多语言协议文档 | 包括架构蓝图（Blueprint）和协议技术规范（Specification），以 9 种语言等价发布，为协议的设计意图、能力范围和技术细节提供人类可读的描述 | docs/{lang}/blueprint/、docs/{lang}/specification/ |
| 协议 Schema 定义文件 | 协议消息格式的权威定义，以机器可读和人类可读的多种格式提供，是 SDK 实现和互操作性测试的基准 | schema/{version}/ |
| 各语言 SDK 实现 | 协议的具体编程语言实现，基于 Schema 定义文件开发，为不同技术栈的开发者提供开箱即用的协议集成能力 | sdk/{language}/ |
三类交付物之间的层级关系：
- 多语言协议文档处于战略层和规范层，定义协议"做什么"和"怎么做"的顶层设计
- 协议 Schema 定义文件处于定义层，将协议规范中的消息格式转化为精确的、可机器处理的形式化定义
- 各语言 SDK 实现处于实现层，基于 Schema 定义文件将协议能力转化为可直接调用的编程接口
三类交付物的更新遵循自上而下的传导路径：协议文档的变更驱动 Schema 定义的更新，Schema 定义的更新驱动 SDK 实现的适配。
5.2 Schema 定义文件的作用
Schema 定义文件是 CAP 协议消息格式的权威定义（Authoritative Definition），在项目交付物体系中承担以下核心作用：
- 消息格式的唯一真相源（Single Source of Truth）：Schema 定义文件精确描述了 CAP 协议中所有消息类型的字段名称、数据类型、必填/可选约束和嵌套结构。当协议文档的文字描述与 Schema 定义存在歧义时，以 Schema 定义为准
- SDK 实现的开发基准：各语言 SDK 的消息序列化/反序列化逻辑必须严格遵循 Schema 定义。SDK 开发者通过 Schema 定义文件了解每种消息的精确结构，确保不同语言的 SDK 实现在消息格式上完全一致
- 互操作性测试的校验基准：不同语言 SDK 之间的互操作性测试以 Schema 定义为校验标准。一个 SDK 序列化的消息必须能被另一个 SDK 正确反序列化，Schema 定义文件是判定"正确"的唯一依据
- 自动化验证的基础：Schema 定义文件（特别是 schema.json）可被自动化工具直接消费，用于消息格式的自动校验、代码生成和文档生成，减少人工错误
5.3 Schema 版本与协议版本对应关系
每个正式发布的 CAP 协议版本对应一个 Schema 版本，Schema 文件存放在以协议版本发布日期命名的目录下，确保版本对应关系清晰可追溯。
目录命名规则：
| 协议状态 | Schema 目录 | 说明 |
|---|---|---|
| 草案（Draft） | schema/draft/ | 开发中的 Schema 定义，可随时变更，不承诺兼容性 |
| 正式发布 | schema/{YYYY-MM-DD}/ | 以发布日期命名，如 schema/2025-10-25/，发布后不可变更（immutable） |
版本对应规则：
- 一对一对应：每个正式发布的协议版本恰好对应一个 Schema 版本目录，目录名称使用该协议版本的发布日期
- 草案共享：所有处于草案阶段的 Schema 变更共享
schema/draft/目录，草案阶段不区分版本号 - 不可变性：正式发布的 Schema 目录中的文件在发布后不再修改。任何 Schema 变更（包括错误修正）都通过发布新版本实现
- 历史保留：旧版本的 Schema 目录永久保留在仓库中，供历史参考和向后兼容性验证使用
当前版本对应关系：
| 协议版本 | Schema 目录 | 状态 |
|---|---|---|
| draft | schema/draft/ | 开发中 |
| 2025-10-25 | schema/2025-10-25/ | 已发布 |
5.4 Schema 文件格式说明
每个 Schema 版本目录下包含 3 种格式的 Schema 定义文件，分别面向不同的使用场景和消费者：
| 格式 | 文件名 | 用途 | 主要消费者 |
|---|---|---|---|
| JSON Schema | schema.json | 机器可读的消息格式定义，用于自动化验证、代码生成和跨语言互操作性校验 | 自动化工具、CI/CD 流水线、SDK 代码生成器 |
| TypeScript | schema.ts | TypeScript 类型定义，为 TypeScript/JavaScript 生态提供原生类型支持，用于 TS/JS SDK 开发和 IDE 类型检查 | TypeScript/JavaScript SDK 开发者、前端集成开发者 |
| MDX | schema.mdx | 可渲染的文档格式，将 Schema 定义以人类友好的方式呈现，用于文档站点展示和协议学习 | 协议学习者、文档站点、技术评审人员 |
三种格式的关系：
- schema.json 是权威格式：当三种格式之间存在差异时，以 schema.json 为准。schema.ts 和 schema.mdx 应与 schema.json 保持语义一致
- schema.ts 是开发便利格式：schema.ts 将 schema.json 中的类型定义转化为 TypeScript 原生类型，使 TS/JS 开发者能够直接在 IDE 中获得类型提示和编译时检查
- schema.mdx 是展示格式：schema.mdx 将 schema.json 中的结构化定义转化为可渲染的文档内容，支持在文档站点中以交互式方式浏览 Schema 定义
文件目录结构示例：
schema/
├── draft/
│ ├── schema.json
│ ├── schema.ts
│ └── schema.mdx
└── 2025-10-25/
├── schema.json
├── schema.ts
└── schema.mdx