JSON Schema
JSONデータの構造を記述する言語
どのようなものか
JSON Schemaは、JSONデータに求める構造を記述する言語で、それ自体もJSONで書きます。この言語による記述をスキーマと呼び、そこに規則を定めます。この値はオブジェクトで、これらのプロパティーが必要、この値は一以上の整数、別の値は最大200文字の文字列、といった規則です。バリデーターというプログラムが、スキーマと、検査するデータであるインスタンスを受け取り、インスタンスが適合するか、適合しなければどこに、どの理由で違反があるかを返します。プロジェクト名は、Sを大文字にしてJSON Schemaと書きます。この言語で書いた個々の文書は、英語では小文字のschemaです。
仕様は、json-schema.orgのJSON Schemaプロジェクトが保守しています。現在の版は2020-12で、その前は2019-09です。それ以前はdraft-04やdraft-07のような番号付きのドラフトで、古いツールや記事では、今もその名前を使います。仕様は二部に分かれます。中核の文書は、スキーマの処理方法、別のスキーマを参照する方法、メディアタイプapplication/schema+jsonを定義します。もう一つの検証に関する文書は、値を検査するキーワードを定義します。現行の2020-12の文書は、どちらも2022年6月16日付です。
各キーワードが、一つの制約を加えます。typeは、string(文字列)、number(数値)、boolean(真偽値)、array(配列)、object(オブジェクト)、nullという六つの基本型か、小数部分がゼロの数だけを受け入れるintegerを指定します。数値にはminimum、maximum、multipleOf、文字列にはminLength、maxLength、正規表現のpattern、配列にはminItems、maxItems、uniqueItems、オブジェクトにはproperties、required、additionalPropertiesを使います。allOf、anyOf、oneOf、notなどのキーワードは、スキーマを組み合わせます。$refは、別の場所、多くの場合は同じ文書の$defsの下で定義したスキーマを指し、一度書いた構造を多くの箇所で使えるようにします。スキーマが触れないものは、すべて許可します。空のスキーマ{}は、あらゆるインスタンスを受け入れます。
スキーマには、言語のどの版で書いたかも示せます。$schemaキーワードが持つのは、その版の有効なスキーマを記述する、メタスキーマのアドレスです。仕様のページは、このメタスキーマが自分自身を検証すると説明しています。2020-12では、アドレスはhttps://json-schema.org/draft/2020-12/schemaです。

写真: amazed / Pixabay 
写真: tookapic / Pixabay
用語の背後にある前提を検証する
解説とリンク先の実績を参考に、プロジェクトについての質問を整理してください。ツールを選ぶ前に、前提を一緒に検討できます。 ETL/ELTパイプライン6本を設計・運用 — 6 3種類のDBエンジンにまたがるETLパイプライン
なぜ重要なのか
JSONは、意味について何も定めません。形式が正しければ、読むプログラムが扱えるかどうかに関係なく、文書を解析できます。明文化した記述がなければ、文書を読む各プログラムが、有効なデータとは何かを、コード内の条件に分散した形で、それぞれに判断します。その判断は次第に食い違い、本番で要求が失敗するまで気付かないことがあります。スキーマは、人とプログラムの両方が読める形で規則を一か所に集めます。ほかのファイルと同じように、保存、版管理、レビュー、公開できます。
仕様が掲げる用途は、広いものです。JSON Schemaは、JSONデータの検証と文書化、ハイパーリンクによる移動、操作の制御を目的とし、検証用の語彙には、データを表示する画面へ、そのデータについてのヒントを与える役割もあります。実際には、一つの記述を使って、サービスの入口で不正な入力を拒否し、APIを文書化し、フォームを動かし、言語モデルが返すJSONに次の処理が期待するフィールドがあるかを検査できます。
ほかの仕様が基礎とする、共通の仕組みにもなっています。OpenAPI 3.1は、Schema ObjectをJSON Schema 2020-12の上位集合と定義するため、API記述内の要求本文と応答本文は、いくつかの追加を持つJSON Schemaです。AIエージェントがツールを見つけ、呼び出すプロトコルのMCPも、各ツールのパラメーターを、JSON SchemaであるinputSchemaで記述します。結果をoutputSchemaで記述することもでき、クライアントは、それに対して構造化された結果を検証するべきです。そのため、バリデーター、API文書、エージェントで共通の記述を利用できます。
実際の活用例
次のスキーマは、配送枠を予約するツールの入力を記述します。使う仕様の版を示し、四つのプロパティーとその規則を列挙し、どの三つが必須かを指定し、列挙していないプロパティーを拒否します。
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/tools/book-slot.json",
"title": "Book a delivery slot",
"type": "object",
"properties": {
"order": { "type": "string", "pattern": "^[0-9]{4,8}$" },
"date": { "type": "string", "format": "date" },
"pallets": { "type": "integer", "minimum": 1, "maximum": 30 },
"note": { "type": ["string", "null"], "maxLength": 200 }
},
"required": ["order", "date", "pallets"],
"additionalProperties": false
}規則に違反するインスタンスです。
{ "order": "4471", "date": "27/10/2026", "pallets": 0, "pallet": 2 }このインスタンスは、二点で違反します。palletsが最小値1未満であり、palletはpalletsの打ち間違いで、スキーマに列挙していないプロパティーです。noteが欠けても問題ありません。noteはrequiredにないためです。nullとして送っても、型がnullを認めるため、合格します。日付は、理解の助けになる例です。date形式は年を先に求めますが、27/10/2026は日を先に書いています。それでも、既定設定のバリデーターは受け入れます。仕様では、formatを、検査を有効にしたときだけ検査する注釈としているためです。日付を検査できるバリデーターで、その機能を有効にすると、同じインスタンスは三点で違反します。
こうした記述を持つツールは、このサイトの既存ソフトウェアをAIエージェント用のツールにするページが扱うものです。配送枠の予約や注文のリリースなど、エージェントが使えるようにする操作を、型付きの入力、エージェントが対処できるエラー、再試行でも二重予約しない冪等な呼び出しを持つツールとして提供すると説明しています。記述は、コードから生成するOpenAPI文書で、MCPサーバーも同じ操作を提供します。同ページは、エージェントは古くなった記述も信じてしまい、手書きの記述は実装と食い違う可能性があると論じています。そのため、そこでの記述は、コードを起点に、データベース、API、記述、クライアントへと生成します。各段階で、二つが食い違えばビルドを失敗させる検査を行います。
問題が起きるところ
プロパティーを列挙しても、必須にはしていません。 propertiesが検査するのは、存在するプロパティーだけです。そのため、すべて省いたオブジェクトも合格します。存在を求めるのは別のキーワードで、requiredを書かなければ、何も必須にはなりません。毎回、requiredをpropertiesと並べて書き、各必須プロパティーを取り除いたテストケースを用意します。
打ち間違いが追加プロパティーとして通ります。 additionalPropertiesがなければ、列挙しないプロパティーも許可するため、palletが通り、本来のpalletsが欠けても気付かないことがあります。falseにすると、それ以外を拒否しますが、このキーワードが見るのは、自分と同じスキーマオブジェクト内のpropertiesとpatternPropertiesだけです。allOfや$refで別のスキーマを基礎にし、この方法で閉じると、継承したはずのプロパティーまで拒否します。2020-12には、この場合に使うunevaluatedPropertiesがあります。allOf、$ref、そのほか同じ対象にスキーマを適用するキーワードを通して検査したプロパティーも数えるためです。単独のスキーマにはadditionalProperties: false、組み合わせたスキーマにはunevaluatedProperties: falseを使います。
formatが何も検査しません。 既定では、formatは注釈であり、検証条件ではありません。仕様は、形式を検査できるバリデーターにも、明示的に求められるまで、その検査を無効に保つよう求めています。有効にしても、バリデーターは、どんな形式も検査せず通してよいことになっています。OpenAPI 3.1も同じ規則に従い、検査の程度は実装によって異なるとも述べています。使うバリデーターで形式の検査を有効にし、失敗するはずのテストケースで確かめます。重要な形式なのに検査できなければ、patternか、コードによる検査を追加します。
パターンが値の一部分に一致します。 patternは先頭や末尾に固定されていないため、[0-9]{4}はorder 4471bを受け入れます。どこかに四桁の数字があればよいためです。仕様自体の例では、esがexpressionに一致します。値全体を一致させる必要があれば、先頭に^、末尾に$を付けます。パターンはECMA-262の正規表現の構文に従います。仕様は、どこでも同じ動きを求めるパターンに、限られた構文の使用を勧めています。そのため、単純な文字クラス、量指定子、アンカーにとどめます。
欠落、null、空を同じものと見なします。 存在しないプロパティー、nullを設定したプロパティー、空文字列は、三つの異なるインスタンスです。"type": "string"はnullを拒否し、requiredにないプロパティーは、省けます。値なしを表すためにnullを送るクライアントは、省略を想定したスキーマに対して、そのような要求を送るたびに失敗します。三者の意味をプロパティーごとに決め、明記します。nullに意味があれば["string", "null"]、任意のプロパティーならrequiredに含めず、空文字列を値と認めなければminLength: 1を使います。
$schemaがないか、二つの版が混ざります。 スキーマのルートに$schemaがなければ、仕様は動作を実装に委ね、各バリデーターは、それぞれが既定とする版を適用します。各版には、重要な違いがあります。2019-09では、itemsに配列を与えるとタプルを記述しました。2020-12では、その役目はprefixItemsに移り、itemsはadditionalItemsの役目を引き継ぎました。すべてのルートに$schemaを入れ、版を移すときはリリースノートに従い、CIで各スキーマをメタスキーマに対して検証します。
参考資料
- JSON Schema仕様 — 現在の版、メタスキーマ、過去の各ドラフトのリリースノートをまとめた、プロジェクトの索引です。
- JSON Schema:JSON文書を記述するメディアタイプ — Core 2020-12です。スキーマの処理、
$schema、$ref、$defs、スキーマを組み合わせるキーワードを扱います。 - JSON Schema検証:JSONの構造を検証する語彙 — 値の型ごとのキーワード、
required、formatの規則です。 - JSON Schema 2020-12リリースノート — 2019-09からの変更です。
prefixItems、$dynamicRefと、それぞれが置き換えた仕組みを対比します。 - OpenAPI仕様v3.1.1 — JSON Schema 2020-12の上位集合としてのSchema Objectと、既定で注釈である
formatです。 - Model Context Protocol:ツール — ツールが、パラメーターと構造化した出力をJSON Schemaで宣言する方法です。

