本文へ移動
Engineer
メニュー
デザイン
日本語

Engineer / 用語集

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です。

なぜ重要なのか

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で各スキーマをメタスキーマに対して検証します。

参考資料

お問い合わせ

必要なことを整理している段階ですか?

うまくいっていないことや、つくりたいものをお聞かせください。何が必要か、おおよそいくらかかるか、私たちが適任かどうかをお伝えします。

時間単価は1,400 DKKから(VAT別)で、ご依頼期間が長いほど下がります。

welcome@engineer.company +45 50 10 61 84 デンマーク、コペンハーゲン