BLUEPRINT
5 Schemaと成果物の関係
第5章：Schema と成果物の関係
本章では CAP プロジェクトの成果物体系構造を記述し、プロトコル Schema 定義ファイルの成果物における中核的な位置づけ、および Schema バージョンとプロトコルバージョンの対応関係を明確にする。成果物間の階層関係と依存関係を理解することは、プロトコル実装者とコミュニティ貢献者がプロジェクト協力に参加するための基盤である。
5.1 3種類のコア成果物
CAP プロジェクトの成果物体系は3種類のコア成果物で構成され、ドキュメントから定義、実装まで完全な成果物チェーンを形成する：
| 成果物カテゴリ | 説明 | リポジトリパス例 |
|---|---|---|
| 多言語プロトコルドキュメント | アーキテクチャブループリント（Blueprint）とプロトコル技術仕様（Specification）を含み、9言語で等価に公開される。プロトコルの設計意図、能力範囲、技術詳細について人間が読める記述を提供する | docs/{lang}/blueprint/、docs/{lang}/specification/ |
| プロトコル Schema 定義ファイル | プロトコルメッセージフォーマットの権威ある定義であり、機械可読および人間可読の複数フォーマットで提供される。SDK 実装と相互運用性テストの基準となる | schema/{version}/ |
| 各言語 SDK 実装 | プロトコルの具体的なプログラミング言語実装であり、Schema 定義ファイルに基づいて開発される。異なる技術スタックの開発者にすぐに使えるプロトコル統合機能を提供する | sdk/{language}/ |
3種類の成果物間の階層関係：
- 多言語プロトコルドキュメントは戦略層と仕様層に位置し、プロトコルが「何をするか」と「どのように行うか」のトップレベル設計を定義する
- プロトコル Schema 定義ファイルは定義層に位置し、プロトコル仕様のメッセージフォーマットを精密な機械処理可能な形式化定義に変換する
- 各言語 SDK 実装は実装層に位置し、Schema 定義ファイルに基づいてプロトコル機能を直接呼び出し可能なプログラミングインターフェースに変換する
3種類の成果物の更新はトップダウンの伝達パスに従う：プロトコルドキュメントの変更が 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 プロトコルバージョンは1つの Schema バージョンに対応し、Schema ファイルはプロトコルバージョンのリリース日付で命名されたディレクトリに格納される。これによりバージョン対応関係が明確に追跡可能となる。
ディレクトリ命名規則：
| プロトコル状態 | Schema ディレクトリ | 説明 |
|---|---|---|
| ドラフト（Draft） | schema/draft/ | 開発中の Schema 定義。いつでも変更可能で、互換性は約束しない |
| 正式リリース | schema/{YYYY-MM-DD}/ | リリース日付で命名。例：schema/2025-10-25/。リリース後は変更不可（immutable） |
バージョン対応規則：
- 一対一対応：正式にリリースされた各プロトコルバージョンは正確に1つの 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 定義を人間にフレンドリーな方式で提示し、ドキュメントサイト表示とプロトコル学習に使用 | プロトコル学習者、ドキュメントサイト、技術レビュー担当者 |
3種類のフォーマットの関係：
- schema.json が権威フォーマット：3種類のフォーマット間に差異がある場合、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