JSON Schemaとは？なぜOpenAI、Gemini、Claude、MCPはJSON Schemaにますます依存しているのか？

AI Agent、API連携、ツール実行でJSON Schemaが必要になる理由を、出力形式、Function Calling、MCP、マルチモデル対応の4つの場面から整理します。各社の対応範囲は同一ではないため、内部の主Schemaと変換用Schemaを分けて管理する設計方針も紹介します。

「JSONとして返ってきたのに、必須フィールドが欠けて下流の処理が止まる」。この症状には、プロンプトの追加より先にSchema検証を入れるのが近道です。

判断：JSON SchemaとAI Agentの組み合わせは、複数モデルや外部ツールを扱う開発者に適しています。 ただし、1つのSchemaを全サービスへ無変換で送るのではなく、内部の主Schemaと各API向けの適応版を分けて管理してください。

AIアプリケーション開発者は、安定した出力とツール引数を定義したい場合に読んでください。プラットフォームエンジニアは、複数モデルでデータ契約を再利用したい場合に役立ちます。テストエンジニアは、Schemaの検証と互換性回帰を自動化する設計材料として使えます。

JSON SchemaがAI Agentで固定する境界

普通のJSONは、データを表現する形式です。例えば次の値は構文上は正しいJSONです。

{
  "status": "done",
  "amount": "1000"
}

しかし、下流システムがamountに数値を要求しているなら、このデータは業務上使えません。statusにpending、paid、cancelledだけを許可する場合も、JSONの構文だけでは制約できません。

JSON Schemaは、オブジェクト、フィールド、型、必須項目、列挙値、配列の要素などを機械可読な形で定義します。現在の公式仕様では2020-12が案内されており、$schemaによって使用するDialectを宣言できます。詳しくはJSON Schemaの公式仕様とDialectおよびVocabularyの解説を確認してください。

ここで区別したいのは、次の3層です。

• データ記述：どのフィールドが存在するかを示します。
• 構造検証：型、必須項目、列挙値、配列構造を検証します。
• 業務検証：注文の所有者、日付の存在、金額上限、状態遷移を検証します。

Schema検証に成功したからといって、注文番号が実在するとは限りません。モデルが出したorder_idがデータベースに存在するか、依頼者に閲覧権限があるかは、実行器と業務ロジックの責任です。

Structured Outputで出力を安定させる方法

AI Agentが商品分類、情報抽出、ルーティング、テスト結果の要約を行うとき、最終回答を自然文ではなく決まったJSONにしたい場面があります。このときSchemaは、モデルに「何を返すか」だけでなく、下流処理がどの形を期待するかを伝えます。

例えば、社内の主Schemaを次のように定義します。

{
  "type": "object",
  "properties": {
    "decision": {
      "type": "string",
      "enum": ["approve", "review", "reject"]
    },
    "reasons": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["decision", "reasons"],
  "additionalProperties": false
}

この定義で重要なのは、decisionの値が3種類に限定されること、reasonsが配列であること、両方が必須であることです。自然文のプロンプトだけで同じ制約を表現すると、モデルや入力内容が変わったときに抜けが発生しやすくなります。

OpenAIのStructured Outputsは、JSON Schemaに基づく出力形式を指定できます。ただし、厳密なSchema遵守を有効にする場合も、対応するJSON Schemaの範囲は限定されています。OpenAIのStructured Outputs関連リファレンスでは、json_schema形式とサブセット対応が説明されています。

Gemini Structured OutputもJSON Schemaのサブセットを使用します。公式ドキュメントでは、string、number、integer、boolean、object、array、nullなどが案内され、required、enum、minimum、maximumなどの扱いも説明されています。一方で、構文的に正しいJSONでも値が業務上正しいとは限らないため、アプリケーション側の検証が必要です。GeminiのStructured Output公式ガイドを参照してください。

ツール呼び出しでSchemaが権限の代わりにならない理由

Function Callingやツール呼び出しでは、Schemaの役割が少し変わります。ここでSchemaが説明するのは、モデルの最終回答ではなく、実行する関数へ渡す引数です。

例えば検索ツールなら、次のような入力を要求します。

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": ["query"]
}

この定義により、実行器はqueryの欠落やlimitの型違いを処理前に拒否できます。しかし、Schemaは次のことを保証しません。

• 呼び出したユーザーに検索権限があるか。
• 指定されたリソースが実際に存在するか。
• 金額や日時が社内ルールに合っているか。
• モデルが本当にそのツールを呼ぶべきだったか。

Claudeのツール定義では、input_schemaがツールへ渡す引数のJSON Schemaとして使われます。Claudeはツールの説明とSchemaをもとにtool_useを返し、アプリケーション側が実行して結果をtool_resultとして返す流れです。ClaudeのTool Use公式ドキュメントに、この構造が記載されています。

第一段階：モデルの前に実行器を守る

実装では、次の順番にすると障害範囲を限定できます。

1. モデルへツール名、説明、入力Schemaを渡します。
2. モデルが返した引数をJSONとして解析します。
3. JSON Schemaバリデーターで構造を検証します。
4. 認証トークンとユーザー権限を確認します。
5. 注文、ファイル、アカウントなどの実在性を確認します。
6. 金額、日付、状態遷移を業務ルールで検証します。
7. 実行結果を出力Schemaで検証し、モデルへ返します。

この順番なら、モデルがorder_idを正しい文字列で返しても、その注文が別ユーザーのものなら実行段階で止められます。

MCPにおけるinputSchemaとoutputSchemaの役割

Model Context Protocolは、モデルそのものの出力形式を規定する機能ではありません。MCPは、ホスト、クライアント、サーバー間でリソース、プロンプト、ツールを公開・呼び出しするためのプロトコルです。メッセージはJSON-RPC 2.0を利用します。MCP公式仕様の概要では、ツールがモデル制御の機能として公開される構造が説明されています。

MCPツールでは、主に次の2つを分けて考えます。

• inputSchema：ツールへ渡す引数の構造です。
• outputSchema：ツールが返す構造化結果の構造です。
• structuredContent：Schemaに適合する構造化された実行結果です。

MCPの公式ツール仕様では、inputSchemaは期待するパラメーターを定義し、outputSchemaは任意の出力構造を定義できます。structuredContentを返す場合、後方互換性のためにシリアライズ済みのテキストも併せて返す設計が推奨されています。MCP Toolsの公式仕様を確認してください。

ここで注意すべきなのは、MCPがモデルのツール選択を代替するわけではない点です。MCPはツールを発見し、説明し、呼び出す通信規約です。どのツールを選ぶか、ユーザー承認を要求するか、失敗時に再試行するかは、ホストやモデル連携層の設計に残ります。

4つの利用場面で見るSchemaの判断表

評価は「Schemaを使うか」ではなく、「どの境界に置くか」で決まります。出力、ツール入力、ツール出力、業務データの4箇所に同じ検証を置く必要はありません。それぞれの責任を分けることで、失敗時の原因を追いやすくなります。

一つのSchemaを各プラットフォームへ直接渡せるのか

結論は、単純なSchemaなら再利用しやすいものの、完全な無変換共有は避けるべきです。

JSON Schema仕様がキーワードやDialectを定義していても、各APIが実装する範囲は同一ではありません。OpenAIはStructured Outputsで対応サブセットを示し、Geminiも構造化出力でサポート範囲を限定しています。Claudeはツールのinput_schemaとしてJSON Schemaを受け取りますが、SDKや利用形態によって送信前に制約を調整する場合があります。

私たちは、次の3層で管理する設計を推奨します。

1. 主Schema：社内のデータ契約。完全性と意味を優先します。
2. 適応Schema：OpenAI、Gemini、Claude、MCPなど接続先ごとの制約に合わせます。
3. 業務検証：データベース、認証、金額、日付、状態遷移を検証します。

例えば主Schemaで$ref、oneOf、条件分岐を使っていても、接続先によっては展開した単純なobjectへ変換します。変換時には、次の情報を必ず保存してください。

• 主Schemaの識別子とバージョン。
• 対象APIとモデルのバージョン。
• 変換前後のSchema。
• 削除または簡略化したキーワード。
• 変換理由と互換性上の注意。
• 正常系、欠落、型違い、未知フィールドのテスト結果。

第二段階：互換性を回帰テストに組み込む

次の手順をCIに組み込みます。

1. オブジェクト、配列、列挙値、参照、追加プロパティを含む代表Schemaを用意します。
2. 主Schemaを各接続先向けに変換します。
3. 生成されたSchema自体をバリデーターで検証します。
4. 正常なJSON、必須欠落、型違い、未知フィールドを用意します。
5. 各APIのStructured Outputまたはツール定義へ投入します。
6. 実行結果をローカルのSchemaバリデーターでも再検証します。
7. API仕様やモデルを変更したときに同じテストを再実行します。

MCPについても、仕様の更新内容を確認してください。公式の変更履歴では、構造化されたツール出力の追加などが変更点として案内されています。MCPの変更履歴を固定リンクとして管理し、利用するプロトコルリビジョンをテスト記録に残すのが安全です。

独立したMCPサーバーやCI環境を複数の開発者で再現する場合は、実行環境の差も問題になります。macOS上のテスト、署名処理、Apple向けビルドを同じ条件で回したいチームは、日本向けのクラウドMacレンタルやクラウドMacレンタルの全体案内も比較対象に入れられます。

業務データではSchemaの後に検証する項目

例えば、次の値はSchema上では問題なく通る可能性があります。

{
  "order_id": "A-1001",
  "amount": 1000,
  "status": "paid"
}

しかし、実際には次の確認が必要です。

• order_idがデータベースに存在するか。
• 呼び出したユーザーが注文の所有者か。
• amountが保存済み金額と一致するか。
• paidへの状態変更が現在の状態から許可されるか。
• 操作の監査ログを残す必要があるか。

JSON Schemaは構造契約です。ビジネスルールの実行エンジンではありません。この区別を曖昧にすると、「Schema検証済みだから安全」という誤った判定が発生します。

Schemaの説明文も過信できません。descriptionはモデルの理解を助けますが、認証や権限チェックを実装するものではありません。MCP公式仕様でも、ツールの注釈は信頼できるサーバーから取得した場合を除き、信頼できないものとして扱う必要があると説明されています。

よくある確認事項

FAQでは、JSON Schemaと普通のJSONの違い、ツール呼び出しでSchemaが必要な理由、3社の対応範囲、MCPの入出力Schema、一つのSchemaを複数サービスへ再利用する条件を整理しています。実装では、これらを別々の検証責任として扱うことが重要です。

まとめ：共有するのはSchema本体ではなく契約と変換規則です

JSON Schemaは、JSONを説明し、構造を検証し、AI Agentとツール実行器の境界を明確にするための契約です。合法なJSONと、業務システムが受け入れられるJSONは同じではありません。

OpenAI Structured Outputs、Gemini Structured Output、Claudeのツール定義、Model Context ProtocolはいずれもSchemaを活用しますが、対応するキーワードや用途は一致しません。したがって、内部の主Schemaを保管し、各接続先向けの変換版、テスト結果、バージョン情報をセットで管理する方法が現実的です。

現在の実行環境だけで運用すると、モデルごとのSchema差分、CIでの再現性、macOS依存のビルド処理が別々の問題として残ります。特にローカル端末に依存した検証は、担当者不在時の再実行、署名環境の差、テスト用Macの確保が負担になります。

一時的な検証環境や、macOSを使うCIタスクを安定して回したい場合は、ZekVPSのクラウドMac環境を選択肢にできます。長期にわたる固定負荷や物理インターフェースが必要なら自社所有のMacが適しますが、Schema変換の回帰テストや短期のAgent開発なら、必要な期間だけMac環境を借りる方が運用を整理しやすいケースがあります。