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