BroadRouter
始める

JSON Schema(JSON スキーマ)

更新日

JSON Schema とは、JSON データの構造(型、必須フィールド、許可される値、入れ子)を記述・検証するための、JSON で書かれた語彙です。現行バージョンは 2020-12 です。LLM API はツールのパラメーターや、構造化出力が従うべき正確な形の定義に使います。

別名: JSON スキーマ、JSONスキーマ、スキーマ定義、json_schema、JSON Schema draft 2020-12

「JSON で答えて」と書いただけのプロンプトでは、形は運任せです。JSON Schema は形を書き出し、機械がチェックできるようにします。

しくみ

仕様は主に 2 つの部分からなります。Core は「defines the basic foundation of JSON Schema」(訳:JSON Schema の基本的な土台を定義する)、Validation は「defines the validation keywords」(訳:検証用キーワードを定義する)ものです。現行バージョンは 2020-12 で、その前は 2019-09 でした。

{
  "type": "object",
  "properties": {
    "name":    {"type": "string"},
    "amount":  {"type": "number", "minimum": 0},
    "currency": {"type": "string", "enum": ["SAR", "AED", "USD"]},
    "note":    {"type": ["string", "null"]}
  },
  "required": ["name", "amount", "currency", "note"],
  "additionalProperties": false
}

LLM API がスキーマを使う場面は 2 つあります。ツール定義では parameters にスキーマを入れて引数を記述します。構造化出力では response_format に {"type": "json_schema", "json_schema": {...}} としてスキーマを送ります。OpenAI によると、これは「ensures the model will match your supplied JSON schema」(訳:モデルが渡された JSON スキーマに一致することを保証する)ものです。

OpenAI の strict モードが受け付けるのはサブセットだけです。対応スキーマの節によると次のとおりです。

  • 型:string、number、boolean、integer、object、array、enum、anyOf。
  • ルートはオブジェクトでなければならず、anyOf は使えません。
  • additionalProperties: false とし、すべてのフィールドを required に列挙します。フィールドを省略可能にしたいときは、上の note のように null を許可します。
  • オブジェクトのプロパティは最大 5000 個、入れ子は 10 階層まで、enum の値は合計 1000 個まで。
  • 非対応:allOf、not、dependentRequired、dependentSchemas、if、then、else。

なぜ重要か

  • 検証。 モデルを導くのと同じスキーマで、コード側の応答チェックもできます。チェックに失敗すれば、そのまま送り返せる正確なエラーが得られます。
  • 移植性。 strict のサブセットに沿って書いたスキーマは、あらゆるキーワードを使ったスキーマより多くのプロバイダーで動きます。
  • トークン。 ツール定義のスキーマは、毎回のリクエストで入力として送られます。長い説明文はターンごとにトークンを消費します。

BroadNet Inference の場合

BroadNet の API リファレンスは、GLM 5.3 と Qwen3.8 27B のツール呼び出しと構造化出力を記載していますが、どのスキーマキーワードが強制されるかは書かれていません。スキーマは上記のシンプルなサブセットにとどめ、応答は毎回検証してください。スキーマは JSON Schema ジェネレーターで作り、応答は LLM JSON 出力バリデーターでチェックできます。完全な例は構造化出力の記事をご覧ください。ほかのモデルでは、プロンプトで JSON を求めて応答を検証してください。JSON モードは BroadNet のドキュメントに記載がないので、頼る前に試してください。

よくある間違い

  • allOf や条件付きキーワードを使い、サーバーが強制してくれると思い込むこと。
  • strict モードで、null を許可する代わりに required から外してフィールドを省略可能にしようとすること。

よくある質問

LLM API は JSON Schema のすべてに対応していますか?

いいえ。OpenAI が対応しているのはサブセットです。たとえばルートはオブジェクトでなければならず、すべてのフィールドが必須で、additionalProperties は false にする必要があり、allOf、not、if/then/else などのキーワードは使えません。

JSON Schema と JSON モードの違いは何ですか?

JSON モードが約束するのは有効な JSON であることだけです。JSON Schema は、その JSON がどのフィールドと型を持つべきかを、モデルとバリデーターの両方に伝えます。

BroadNet Inference で JSON Schema を使えますか?

どちらもスキーマを使うツールのパラメーターと構造化出力は、GLM 5.3 と Qwen3.8 27B について記載されています。BroadNet はどのスキーマキーワードを強制するかを記載していないので、応答は毎回検証してください。

Markdown で読むChatGPT に聞くClaude に聞くPerplexity に聞く