| インターネット技術特別調査委員会 | A. Wright, 編 |
| インターネットドラフト | |
| 意図するステータス: 情報提供 | G. Luff |
| 有効期限: 2017年10月23日 | |
| H. Andrews, 編 | |
| Cloudflare, Inc. | |
| 2017年4月21日 |
JSON Schema バリデーション: JSON の構造検証のための語彙
draft-wright-json-schema-validation-01
JSON Schema (application/schema+json) にはいくつかの目的があり、その一つがJSONインスタンスの検証です。このドキュメントでは、JSONドキュメントの意味を記述し、JSONデータを扱うユーザーインターフェイスのヒントを提供し、有効なドキュメントがどのように見えるかを表明するためのJSON Schemaの語彙を規定します。
このドラフトに関する問題点リストは、<https://github.com/json-schema-org/json-schema-spec/issues> にあります。
追加情報については、<https://json-schema.dokyumento.jp/> を参照してください。
フィードバックを提供するには、この課題追跡システム、ホームページに記載されているコミュニケーション方法、またはドキュメント編集者にメールで連絡してください。
このインターネットドラフトは、BCP 78 および BCP 79 の規定に完全に準拠して提出されています。
インターネットドラフトは、インターネット技術特別調査委員会 (IETF) の作業ドキュメントです。他のグループも作業ドキュメントをインターネットドラフトとして配布する場合があることに注意してください。現在のインターネットドラフトの一覧は、http://datatracker.ietf.org/drafts/current/ にあります。
インターネットドラフトは、最大6ヶ月間有効なドラフト文書であり、いつでも他の文書によって更新、置換、または廃止される可能性があります。インターネットドラフトを参考資料として使用したり、「作業中」以外で引用したりすることは不適切です。
このインターネットドラフトは、2017年10月23日に失効します。
Copyright (c) 2017 IETF Trust およびドキュメントの著者として特定された人物。無断複写・転載を禁じます。
このドキュメントは、BCP 78 および、このドキュメントの発行日に有効な IETF Trust の IETF ドキュメントに関する法的規定 (http://trustee.ietf.org/license-info) に従います。このドキュメントに関するあなたの権利と制限について説明していますので、これらのドキュメントを注意深く確認してください。このドキュメントから抽出されたコードコンポーネントには、Trust 法的規定のセクション 4.e に記載されている簡略化された BSD ライセンスのテキストを含める必要があり、簡略化された BSD ライセンスに記載されているように保証なしで提供されます。
JSON Schema は、特定の JSON ドキュメント (インスタンス) が特定の数の基準を満たすことを要求するために使用できます。これらの基準は、この仕様で説明されているキーワードを使用して表明されます。さらに、対話型ユーザーインターフェイスインスタンスの生成を支援するために、一連のキーワードも定義されています。
この仕様では、JSON Schema コア [json-schema] 仕様で定義されている用語を使用します。
このドキュメントにおけるキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC 2119 [RFC2119] で説明されているように解釈されます。
この仕様では、「コンテナインスタンス」という用語を、配列インスタンスとオブジェクトインスタンスの両方を指すために使用します。また、「子インスタンス」という用語を、配列要素またはオブジェクトメンバー値を指すために使用します。
配列値の要素は、この配列の2つの要素が等しくない [json-schema] 場合、一意であると言われます。
ヌル文字 (\u0000) は JSON 文字列で有効であることに注意してください。検証するインスタンスには、基礎となるプログラミング言語がそのようなデータを処理できるかどうかに関係なく、この文字を含む文字列値を含めることができます。
JSON 仕様では、任意の精度を持つ数値を許可しており、JSON Schema はそのような境界を追加しません。これは、JSON Schema によって処理される数値インスタンスは、基礎となるプログラミング言語がそのようなデータを処理できるかどうかに関係なく、任意に大きくしたり、任意に長い小数部を持たせたりできることを意味します。
「pattern」と「patternProperties」の2つの検証キーワードは、制約を表現するために正規表現を使用します。これらの正規表現は、ECMA 262 [ecma262] 正規表現方言に従って有効である必要があります。
さらに、正規表現の構文サポートには大きなばらつきがあるため、スキーマ作成者は次の正規表現トークンに制限する必要があります。
最後に、実装は正規表現が先頭にも末尾にもアンカーされていないと見なす必要があります。これは、たとえば、パターン "es" が "expression" に一致することを意味します。
ほとんどの検証キーワードは、特定のプリミティブ型内の値のみを制約します。インスタンスの型がキーワードの対象とする型でない場合、検証は成功します。
たとえば、「maxLength」キーワードは、特定の文字列 (長すぎる文字列) が有効になるのを制限するだけです。インスタンスが数値、ブール値、null、配列、またはオブジェクトの場合、キーワードは検証に合格します。
プリミティブ型のうち、配列とオブジェクトの2つは、子値を許可します。プリミティブ型の検証は、子インスタンスの検証とは別に考慮されます。
配列の場合、プリミティブ型の検証は、「minItems」と「maxItems」による長さの制限の検証で構成され、「items」と「additionalItems」は配列のどの要素にどのサブスキーマを適用するかを決定します。さらに、「uniqueItems」と「contains」は配列の内容全体を検証します。
オブジェクトの場合、プリミティブ型の検証は、「required」、「minProperties」、「maxProperties」、「propertyNames」、および「dependencies」の文字列配列形式による、どのプロパティがどのように出現するかについての制限の検証で構成され、「properties」、「patternProperties」、および「additionalProperties」は、どのオブジェクトプロパティ値にどのサブスキーマを適用するかを決定します。さらに、「dependencies」のスキーマ形式は、特定のプロパティ名の存在に基づいてオブジェクト全体を検証します。
各 JSON Schema 検証キーワードは、インスタンスが正常に検証されるために満たす必要のある制約を追加します。
欠落している検証キーワードは、検証を制限しません。場合によっては、この非動作動作は、特定の値を持つキーワードが存在する場合と同じであり、これらの値は既知の場合に注記されます。
検証キーワードは通常、互いの結果に影響を与えることなく、独立して動作します。
スキーマ作成者の便宜のために、いくつかの例外があります。
JSON Schema 検証の現在の URI は <https://json-schema.dokyumento.jp/draft-06/schema#> です。
スキーマの検証キーワードは、インスタンスの検証を正常に行うための要件を課します。
「multipleOf」の値は、0 より大きい数値である必要があります。
数値インスタンスは、このキーワードの値で除算した結果が整数になる場合にのみ有効です。
「maximum」の値は、数値インスタンスの包括的な上限を表す数値である必要があります。
インスタンスが数値の場合、このキーワードは、インスタンスが「maximum」以下である場合にのみ検証されます。
「exclusiveMaximum」の値は、数値インスタンスの排他的上限を表す数値である必要があります。
インスタンスが数値の場合、インスタンスは「exclusiveMaximum」より厳密に小さい値 (等しくない) を持つ場合にのみ有効です。
「minimum」の値は、数値インスタンスの包括的な上限を表す数値である必要があります。
インスタンスが数値の場合、このキーワードは、インスタンスが「minimum」以上である場合にのみ検証されます。
「exclusiveMinimum」の値は、数値インスタンスの排他的上限を表す数値である必要があります。
インスタンスが数値の場合、インスタンスは「exclusiveMinimum」より厳密に大きい値 (等しくない) を持つ場合にのみ有効です。
このキーワードの値は、負ではない整数でなければなりません（MUST）。
文字列インスタンスは、その長さがこのキーワードの値以下である場合、このキーワードに対して有効です。
文字列インスタンスの長さは、RFC 7159 [RFC7159]で定義されている文字数として定義されます。
このキーワードの値は、負ではない整数でなければなりません（MUST）。
文字列インスタンスは、その長さがこのキーワードの値以上である場合、このキーワードに対して有効です。
文字列インスタンスの長さは、RFC 7159 [RFC7159]で定義されている文字数として定義されます。
このキーワードを省略した場合、値が0の場合と同じ動作になります。
このキーワードの値は、文字列でなければなりません（MUST）。この文字列は、ECMA 262の正規表現方言に従って、有効な正規表現であるべきです（SHOULD）。
文字列インスタンスは、正規表現がインスタンスに正常に一致した場合に有効とみなされます。注意：正規表現は暗黙的にアンカーされていません。
"items"の値は、有効なJSON Schemaまたは有効なJSON Schemaの配列のいずれかでなければなりません（MUST）。
このキーワードは、配列の子インスタンスがどのように検証されるかを決定し、直接的なインスタンス自体を検証するものではありません。
"items"がスキーマの場合、配列内のすべての要素がそのスキーマに対して正常に検証された場合に検証は成功します。
"items"がスキーマの配列の場合、インスタンスの各要素が、同じ位置にあるスキーマ（存在する場合）に対して検証された場合に検証は成功します。
このキーワードを省略した場合、空のスキーマと同じ動作になります。
"additionalItems"の値は、有効なJSON Schemaでなければなりません（MUST）。
このキーワードは、配列の子インスタンスがどのように検証されるかを決定し、直接的なインスタンス自体を検証するものではありません。
"items"がスキーマの配列の場合、"items"のサイズよりも大きい位置にあるすべてのインスタンス要素が"additionalItems"に対して検証された場合に検証は成功します。
それ以外の場合、"items"スキーマ（おそらく空のスキーマのデフォルト値）がすべての要素に適用されるため、"additionalItems"は無視されなければなりません（MUST）。
このキーワードを省略した場合、空のスキーマと同じ動作になります。
このキーワードの値は、負ではない整数でなければなりません（MUST）。
配列インスタンスは、そのサイズがこのキーワードの値以下である場合、"maxItems"に対して有効です。
このキーワードの値は、負ではない整数でなければなりません（MUST）。
配列インスタンスは、そのサイズがこのキーワードの値以上である場合、"minItems"に対して有効です。
このキーワードを省略した場合、値が0の場合と同じ動作になります。
このキーワードの値は、ブール値でなければなりません（MUST）。
このキーワードがブール値falseを持つ場合、インスタンスは正常に検証されます。ブール値trueを持つ場合、インスタンスのすべての要素が一意である場合に正常に検証されます。
このキーワードを省略した場合、値がfalseの場合と同じ動作になります。
このキーワードの値は、有効なJSON Schemaでなければなりません（MUST）。
配列インスタンスは、少なくとも1つの要素が与えられたスキーマに対して有効である場合、"contains"に対して有効です。
このキーワードの値は、負ではない整数でなければなりません（MUST）。
オブジェクトインスタンスは、プロパティの数がこのキーワードの値以下である場合、"maxProperties"に対して有効です。
このキーワードの値は、負ではない整数でなければなりません（MUST）。
オブジェクトインスタンスは、プロパティの数がこのキーワードの値以上である場合、"minProperties"に対して有効です。
このキーワードを省略した場合、値が0の場合と同じ動作になります。
このキーワードの値は、配列でなければなりません（MUST）。この配列の要素（存在する場合）は文字列でなければならず（MUST）、一意でなければなりません（MUST）。
オブジェクトインスタンスは、配列内のすべての項目がインスタンス内のプロパティの名前である場合、このキーワードに対して有効です。
このキーワードを省略した場合、空の配列の場合と同じ動作になります。
"properties"の値は、オブジェクトでなければなりません（MUST）。このオブジェクトの各値は、有効なJSON Schemaでなければなりません（MUST）。
このキーワードは、オブジェクトの子インスタンスがどのように検証されるかを決定し、直接的なインスタンス自体を検証するものではありません。
インスタンス内とこのキーワードの値内の両方に名前が現れる名前ごとに、その名前の子インスタンスが対応するスキーマに対して正常に検証された場合に検証は成功します。
このキーワードを省略した場合、空のオブジェクトの場合と同じ動作になります。
"patternProperties"の値は、オブジェクトでなければなりません（MUST）。このオブジェクトの各プロパティ名は、ECMA 262の正規表現方言に従って、有効な正規表現であるべきです（SHOULD）。このオブジェクトの各プロパティ値は、有効なJSON Schemaでなければなりません（MUST）。
このキーワードは、オブジェクトの子インスタンスがどのように検証されるかを決定し、直接的なインスタンス自体を検証するものではありません。プリミティブインスタンス型に対するこのキーワードの検証は、常に成功します。
このキーワードの値のプロパティ名として現れる任意の正規表現に一致する各インスタンス名について、その名前の子インスタンスが、一致する正規表現に対応する各スキーマに対して正常に検証された場合に検証は成功します。
このキーワードを省略した場合、空のオブジェクトの場合と同じ動作になります。
"additionalProperties"の値は、有効なJSON Schemaでなければなりません（MUST）。
このキーワードは、オブジェクトの子インスタンスがどのように検証されるかを決定し、直接的なインスタンス自体を検証するものではありません。
"additionalProperties"による検証は、"properties"内のどの名前にも一致せず、"patternProperties"内のどの正規表現にも一致しないインスタンス名の子の値にのみ適用されます。
このようなすべてのプロパティについて、子インスタンスが"additionalProperties"スキーマに対して検証された場合に検証は成功します。
このキーワードを省略した場合、空のスキーマと同じ動作になります。
このキーワードは、インスタンスがオブジェクトであり、特定のプロパティが含まれている場合に評価されるルールを指定します。
このキーワードの値は、オブジェクトでなければなりません（MUST）。各プロパティは、依存関係を指定します。各依存関係の値は、配列または有効なJSON Schemaでなければなりません（MUST）。
依存関係の値がサブスキーマであり、依存関係のキーがインスタンス内のプロパティである場合、インスタンス全体が依存関係の値に対して検証されなければなりません。
依存関係の値が配列の場合、配列内の各要素（存在する場合）は文字列でなければならず（MUST）、一意でなければなりません（MUST）。依存関係のキーがインスタンス内のプロパティである場合、依存関係の値内の各項目は、インスタンス内に存在するプロパティでなければなりません。
このキーワードを省略した場合、空のオブジェクトの場合と同じ動作になります。
"propertyNames"の値は、有効なJSON Schemaでなければなりません（MUST）。
インスタンスがオブジェクトの場合、インスタンス内のすべてのプロパティ名が提供されたスキーマに対して検証された場合に、このキーワードは検証されます。スキーマがテストしているプロパティ名は、常に文字列になることに注意してください。
このキーワードを省略した場合、空のスキーマと同じ動作になります。
このキーワードの値は、配列でなければなりません（MUST）。この配列には、少なくとも1つの要素があるべきです（SHOULD）。配列内の要素は、一意であるべきです（SHOULD）。
インスタンスの値がこのキーワードの配列値内の要素の1つと等しい場合、インスタンスはこのキーワードに対して正常に検証されます。
配列内の要素は、nullを含め、任意の値を指定できます。
このキーワードの値は、nullを含め、任意の型にすることができます（MAY）。
インスタンスの値がキーワードの値と等しい場合、インスタンスはこのキーワードに対して正常に検証されます。
このキーワードの値は、文字列または配列のいずれかでなければなりません（MUST）。配列の場合、配列の要素は文字列でなければならず（MUST）、一意でなければなりません（MUST）。
文字列値は、6つのプリミティブ型（"null"、"boolean"、"object"、"array"、"number"、または"string"）のいずれか、または小数部分がゼロの任意の数に一致する"integer"のいずれかでなければなりません。
インスタンスは、このキーワードにリストされているいずれかのセットに含まれている場合にのみ検証されます。
このキーワードの値は、空ではない配列でなければなりません（MUST）。配列の各項目は、有効なJSON Schemaでなければなりません（MUST）。
インスタンスは、このキーワードの値によって定義されたすべてのスキーマに対して正常に検証された場合に、このキーワードに対して正常に検証されます。
このキーワードの値は、空ではない配列でなければなりません（MUST）。配列の各項目は、有効なJSON Schemaでなければなりません（MUST）。
インスタンスは、このキーワードの値によって定義された少なくとも1つのスキーマに対して正常に検証された場合に、このキーワードに対して正常に検証されます。
このキーワードの値は、空ではない配列でなければなりません（MUST）。配列の各項目は、有効なJSON Schemaでなければなりません（MUST）。
インスタンスは、このキーワードの値によって定義されたちょうど1つのスキーマに対して正常に検証された場合に、このキーワードに対して正常に検証されます。
このキーワードの値は、有効なJSON Schemaでなければなりません（MUST）。
インスタンスは、このキーワードによって定義されたスキーマに対して正常に検証できなかった場合に、このキーワードに対して有効です。
このキーワードの値は、オブジェクトでなければなりません（MUST）。このオブジェクトの各メンバーの値は、有効なJSON Schemaでなければなりません（MUST）。
このキーワードは、検証自体には役割を果たしません。その役割は、スキーマ作成者がJSON Schemaをより一般的なスキーマにインライン化するための標準化された場所を提供することです。
{
"type": "array",
"items": { "$ref": "#/definitions/positiveInteger" },
"definitions": {
"positiveInteger": {
"type": "integer",
"exclusiveMinimum": 0
}
}
}
例として、正の整数の配列を記述するスキーマを以下に示します。ここで、正の整数の制約は、"definitions"内のサブスキーマです。
これらのキーワードの値は、両方とも文字列でなければなりません（MUST）。
これらのキーワードは両方とも、このユーザーインターフェースによって生成されたデータに関する情報でユーザーインターフェースを装飾するために使用できます。タイトルは短いものが望ましいですが、説明はこのスキーマで記述されたインスタンスの目的に関する説明を提供します。
このキーワードの値に制限はありません。
このキーワードは、特定のスキーマに関連付けられたデフォルトのJSON値を提供するために使用できます。デフォルト値は、関連付けられたスキーマに対して有効であることが推奨されます（RECOMMENDED）。
このキーワードの値は、配列でなければなりません（MUST）。配列内の値には制限はありません。
このキーワードは、使用例を説明するために、特定のスキーマに関連付けられたサンプルのJSON値を提供するために使用できます。これらの値は、関連付けられたスキーマに対して有効であることが推奨されます（RECOMMENDED）。
実装は、"default"の値が存在する場合、追加の例として使用できます。 "examples"が存在しない場合でも、"default"をこの方法で使用できます（MAY）。
構造検証だけでは、インスタンスがアプリケーションのすべての要件を満たしていることを検証するのに不十分な場合があります。"format"キーワードは、RFCやその他の外部仕様書などの信頼できるリソースによって正確に記述されている固定された値のサブセットに対する相互運用可能なセマンティック検証を可能にするために定義されています。
このキーワードの値は、フォーマット属性と呼ばれます。文字列でなければなりません（MUST）。フォーマット属性は、一般的に特定のインスタンス型のセットのみを検証できます。検証するインスタンスの型がこのセットに含まれていない場合、このフォーマット属性とインスタンスの検証は成功するべきです（SHOULD）。
実装は、"format"キーワードをサポートする場合があります（MAY）。そうすることを選択する場合は
実装は、カスタムフォーマット属性を追加してもよい（MAY）。当事者間での合意がない限り、スキーマ作成者は、ピア実装がこのキーワードやカスタムフォーマット属性をサポートすることを期待してはならない（SHALL NOT）。
この属性は、文字列インスタンスに適用されます。
文字列インスタンスは、RFC 3339, section 5.6 [RFC3339] で定義されている有効な日付表現である場合に、この属性に対して有効となります。
この属性は、文字列インスタンスに適用されます。
文字列インスタンスは、RFC 5322, section 3.4.1 [RFC5322] で定義されている有効なインターネット電子メールアドレスである場合に、この属性に対して有効となります。
この属性は、文字列インスタンスに適用されます。
文字列インスタンスは、RFC 1034, section 3.1 [RFC1034] で定義されている有効なインターネットホスト名表現である場合に、この属性に対して有効となります。
この属性は、文字列インスタンスに適用されます。
文字列インスタンスは、RFC 2673, section 3.2 [RFC2673] で定義されている「ドット付きクワッド」ABNF構文に従った有効なIPv4アドレス表現である場合に、この属性に対して有効となります。
この属性は、文字列インスタンスに適用されます。
文字列インスタンスは、RFC 2373, section 2.2 [RFC2373] で定義されている有効なIPv6アドレス表現である場合に、この属性に対して有効となります。
この属性は、文字列インスタンスに適用されます。
文字列インスタンスは、[RFC3986] に従って有効なURIである場合に、この属性に対して有効となります。
この属性は、文字列インスタンスに適用されます。
文字列インスタンスは、[RFC3986] に従って有効なURI参照（URIまたは相対参照）である場合に、この属性に対して有効となります。
この属性は、文字列インスタンスに適用されます。
文字列インスタンスは、[RFC6570] に従って有効なURIテンプレート（任意のレベル）である場合に、この属性に対して有効となります。
この属性は、文字列インスタンスに適用されます。
文字列インスタンスは、[RFC6901] に従って有効なJSONポインターである場合に、この属性に対して有効となります。
JSON Schemaバリデーションは、JSON Schemaコアの語彙を定義し、そこに記載されているすべてのセキュリティ上の考慮事項に関係します。
JSON Schemaバリデーションでは、正規表現の使用を許可しています。正規表現には、異なる（多くの場合、互換性のない）実装が多数存在します。一部の実装では、JSON Schemaの範囲外であり、許可すべきではない（MUST NOT）任意のコードの埋め込みが可能です。正規表現は、計算コストが非常に高くなるように（いわゆる「壊滅的なバックトラッキング」を使用して）作成されることも多く、サービス拒否攻撃につながる可能性があります。
| [RFC2119] | Bradner, S., RFCにおける要求レベルを示すためのキーワード", BCP 14, RFC 2119, DOI 10.17487/RFC2119, 1997年3月. |
| [json-schema] | JSON Schema: JSONドキュメントを記述するためのメディアタイプ", インターネットドラフト draft-wright-json-schema-00, 2016年10月. |
| [RFC1034] | Mockapetris, P., "ドメイン名 - 概念と機能", STD 13, RFC 1034, DOI 10.17487/RFC1034, 1987年11月. |
| [RFC2373] | Hinden, R. および S. Deering, "IPバージョン6アドレス指定アーキテクチャ", RFC 2373, DOI 10.17487/RFC2373, 1998年7月. |
| [RFC2673] | Crawford, M., "ドメインネームシステムにおけるバイナリラベル", RFC 2673, DOI 10.17487/RFC2673, 1999年8月. |
| [RFC3339] | Klyne, G. および C. Newman, "インターネットにおける日付と時刻：タイムスタンプ", RFC 3339, DOI 10.17487/RFC3339, 2002年7月. |
| [RFC3986] | Berners-Lee, T., Fielding, R. および L. Masinter, "Uniform Resource Identifier (URI): 一般的な構文", STD 66, RFC 3986, DOI 10.17487/RFC3986, 2005年1月. |
| [RFC6570] | Gregorio, J., Fielding, R., Hadley, M., Nottingham, M. および D. Orchard, "URIテンプレート", RFC 6570, DOI 10.17487/RFC6570, 2012年3月. |
| [RFC6901] | Bryan, P., Zyp, K. および M. Nottingham, "JavaScript Object Notation (JSON) ポインター", RFC 6901, DOI 10.17487/RFC6901, 2013年4月. |
| [RFC7159] | Bray, T., "JavaScript Object Notation (JSON) データ交換形式", RFC 7159, DOI 10.17487/RFC7159, 2014年3月. |
| [RFC5322] | Resnick, P., インターネットメッセージ形式", RFC 5322, DOI 10.17487/RFC5322, 2008年10月. |
| [ecma262] | ECMA 262 仕様" |
JSON Schemaの初期ドラフトに取り組んでくれたGary Court、Francis Galiegue、Kris Zyp、Geraint Luffに感謝します。
ドキュメントへの提出とパッチを提供してくれたJason Desrosiers、Daniel Perrett、Erik Wilde、Ben Hutton、Evgeny Poberezkin、Brad Bowman、Gowry Sankar、Donald Pipowitch、Dave Finlayに感謝します。
[CREF1]このセクションは、インターネットドラフトの状態を離れる前に削除されます。