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