| インターネットエンジニアリングタスクフォース | A. Wright, 編集 |
| インターネットドラフト | |
| 予定ステータス：参考情報 | G. Luff |
| 期限切れ：2017年10月23日 | |
| H. Andrews, 編集 | |
| Cloudflare, Inc. | |
| 2017年4月21日 |
JSONスキーマ検証：JSONの構造検証のための語彙
draft-wright-json-schema-validation-01
JSONスキーマ (application/schema+json) はいくつかの目的を持っており、その1つにJSONインスタンスの検証があります。このドキュメントは、JSONドキュメントの意味を記述し、JSONデータを使用するユーザーインターフェースへのヒントを提供し、有効なドキュメントがどのようなものになるべきかについての表明を行うための、JSONスキーマの語彙を規定します。
このドラフトの課題リストは、<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ドキュメントに関するIETFトラストの法的規定（http://trustee.ietf.org/license-info）の対象となります。これらのドキュメントをよく確認してください。これらは、このドキュメントに関するあなたの権利と制限について説明しています。このドキュメントから抽出したコードコンポーネントには、トラストの法的規定のセクション4.eに記載されている簡略化されたBSDライセンステキストを含める必要があり、簡略化されたBSDライセンスに記載されているように、保証なしで提供されます。
JSONスキーマは、特定のJSONドキュメント（インスタンス）が一定数の基準を満たしていることを要求するために使用できます。これらの基準は、この仕様で説明されているキーワードを使用して表明されます。さらに、インタラクティブなユーザーインターフェースインスタンスの生成を支援するためのキーワードのセットも定義されています。
この仕様では、JSONスキーマコア [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スキーマではそのような境界は追加されません。これは、JSONスキーマによって処理される数値インスタンスは、基礎となるプログラミング言語がそのようなデータに対処できるかどうかに関係なく、任意の大きさ、または任意の長さの10進数部分を持つことができることを意味します。
2つの検証キーワード「pattern」と「patternProperties」は、正規表現を使用して制約を表現します。これらの正規表現は、ECMA 262 [ecma262]正規表現ダイアレクトに従って有効である必要があります。
さらに、正規表現構成のサポートには大きなばらつきがあるため、スキーマ作成者は、次の正規表現トークンに限定することをお勧めします。
最後に、実装は正規表現を入力の先頭と末尾のどちらにもアンカーされないものとして扱う必要があります。つまり、たとえば、パターン「es」は「expression」に一致します。
ほとんどの検証キーワードは、特定のプリミティブ型内の値のみを制約します。インスタンスの型がキーワードの対象となる型でない場合、検証は成功します。
たとえば、「maxLength」キーワードは、特定の文字列（長すぎる文字列）のみが有効でないように制限します。インスタンスが数値、ブール値、null、配列、またはオブジェクトの場合、キーワードは検証に合格します。
プリミティブ型の2つである配列とオブジェクトは、子値を許可します。プリミティブ型の検証は、子インスタンスの検証とは別に考慮されます。
配列の場合、プリミティブ型の検証は、「minItems」と「maxItems」を使用して長さに関する制限を検証することから構成され、「items」と「additionalItems」は、どのサブスキーマが配列のどの要素に適用されるかを決定します。さらに、「uniqueItems」と「contains」は、配列の内容全体を検証します。
オブジェクトの場合、プリミティブ型の検証は、「required」、「minProperties」、「maxProperties」、「propertyNames」、および「dependencies」の文字列配列形式を使用して、どのプロパティがどのように表示されるかについての制限を検証することから構成され、「properties」、「patternProperties」、「additionalProperties」は、どのサブスキーマがオブジェクトのプロパティ値に適用されるかを決定します。さらに、「dependencies」のスキーマ形式は、特定のプロパティ名の存在に基づいてオブジェクト全体を検証します。
各JSONスキーマ検証キーワードは、インスタンスが正常に検証するために満たす必要がある制約を追加します。
欠落している検証キーワードは、検証を制限することはありません。場合によっては、この無操作の動作は、特定の値を持つキーワードと同じであり、既知の場合はそれらの値が示されます。
検証キーワードは通常、互いの結果に影響を与えることなく、独立して動作します。
スキーマ作成者の便宜上、いくつかの例外があります。
JSONスキーマ検証の現在のURIは、<https://json-schema.dokyumento.jp/draft-06/schema#>です。
スキーマ内の検証キーワードは、インスタンスの検証が成功するための要件を課します。
"multipleOf"の値は、0より大きい数値でなければなりません。
数値インスタンスは、このキーワードの値で除算した結果が整数の場合のみ有効です。
"maximum"の値は、数値インスタンスの上限（包含的）を表す数値でなければなりません。
インスタンスが数値の場合、このキーワードは、インスタンスが"maximum"以下である場合のみ検証に成功します。
"exclusiveMaximum"の値は、数値インスタンスの上限（排他的）を表す数値でなければなりません。
インスタンスが数値の場合、インスタンスは"exclusiveMaximum"より厳密に小さい値を持つ場合のみ有効です（等しくない）。
"minimum"の値は、数値インスタンスの下限（包含的）を表す数値でなければなりません。
インスタンスが数値の場合、このキーワードは、インスタンスが"minimum"以上である場合のみ検証に成功します。
"exclusiveMinimum"の値は、数値インスタンスの下限（排他的）を表す数値でなければなりません。
インスタンスが数値の場合、インスタンスは"exclusiveMinimum"より厳密に大きい値を持つ場合のみ有効です（等しくない）。
このキーワードの値は、非負の整数でなければなりません。
文字列インスタンスは、その長さがこのキーワードの値以下である場合、このキーワードに対して有効です。
文字列インスタンスの長さは、RFC 7159 [RFC7159]で定義されている文字数として定義されます。
このキーワードの値は、非負の整数でなければなりません。
文字列インスタンスは、その長さがこのキーワードの値以上である場合、このキーワードに対して有効です。
文字列インスタンスの長さは、RFC 7159 [RFC7159]で定義されている文字数として定義されます。
このキーワードを省略した場合、値0と同様の動作になります。
このキーワードの値は文字列でなければなりません。この文字列は、ECMA 262正規表現方言に従って、有効な正規表現であるべきです。
正規表現がインスタンスに正常にマッチした場合、文字列インスタンスは有効とみなされます。正規表現は暗黙的にアンカーされません。
"items"の値は、有効なJSONスキーマまたは有効なJSONスキーマの配列のいずれかでなければなりません。
このキーワードは、配列の子インスタンスがどのように検証されるかを決定し、インスタンス自体を直接検証するものではありません。
"items"がスキーマの場合、配列内のすべての要素がそのスキーマに対して検証に成功した場合、検証は成功します。
"items"がスキーマの配列の場合、インスタンスの各要素が同じ位置（存在する場合）にあるスキーマに対して検証に成功した場合、検証は成功します。
このキーワードを省略した場合、空のスキーマと同様の動作になります。
"additionalItems"の値は、有効なJSONスキーマでなければなりません。
このキーワードは、配列の子インスタンスがどのように検証されるかを決定し、インスタンス自体を直接検証するものではありません。
"items"がスキーマの配列の場合、"items"のサイズより大きい位置にあるすべてのインスタンス要素が"additionalItems"に対して検証に成功した場合、検証は成功します。
それ以外の場合は、"additionalItems"は無視されます。"items"スキーマ（空のスキーマのデフォルト値の可能性がある）はすべての要素に適用されます。
このキーワードを省略した場合、空のスキーマと同様の動作になります。
このキーワードの値は、非負の整数でなければなりません。
配列インスタンスは、そのサイズが、このキーワードの値以下である場合、"maxItems"に対して有効です。
このキーワードの値は、非負の整数でなければなりません。
配列インスタンスは、そのサイズが、このキーワードの値以上である場合、"minItems"に対して有効です。
このキーワードを省略した場合、値0と同様の動作になります。
このキーワードの値はブール値でなければなりません。
このキーワードのブール値がfalseの場合、インスタンスは検証に成功します。ブール値がtrueの場合、そのすべての要素がユニークであれば、インスタンスは検証に成功します。
このキーワードを省略した場合、値falseと同様の動作になります。
このキーワードの値は、有効なJSONスキーマでなければなりません。
配列インスタンスは、その要素の少なくとも1つが指定されたスキーマに対して有効である場合、"contains"に対して有効です。
このキーワードの値は、非負の整数でなければなりません。
オブジェクトインスタンスは、そのプロパティ数が、このキーワードの値以下である場合、"maxProperties"に対して有効です。
このキーワードの値は、非負の整数でなければなりません。
オブジェクトインスタンスは、そのプロパティ数が、このキーワードの値以上である場合、"minProperties"に対して有効です。
このキーワードを省略した場合、値0と同様の動作になります。
このキーワードの値は配列でなければなりません。この配列の要素（存在する場合）は文字列でなければならず、一意でなければなりません。
オブジェクトインスタンスは、配列内のすべての項目がインスタンス内のプロパティの名前である場合、このキーワードに対して有効です。
このキーワードを省略した場合、空の配列と同様の動作になります。
"properties"の値はオブジェクトでなければなりません。このオブジェクトの各値は、有効なJSONスキーマでなければなりません。
このキーワードは、オブジェクトの子インスタンスがどのように検証されるかを決定し、インスタンス自体を直接検証するものではありません。
インスタンスとこのキーワードの値の両方に出現する名前について、その名前の子インスタンスが対応するスキーマに対して検証に成功した場合、検証は成功します。
このキーワードを省略した場合、空のオブジェクトと同様の動作になります。
"patternProperties"の値はオブジェクトでなければなりません。このオブジェクトのプロパティ名は、ECMA 262正規表現方言に従って、有効な正規表現であるべきです。このオブジェクトのプロパティ値は、有効なJSONスキーマでなければなりません。
このキーワードは、オブジェクトの子インスタンスがどのように検証されるかを決定し、インスタンス自体を直接検証するものではありません。プリミティブインスタンスタイプのこのキーワードに対する検証は常に成功します。
このキーワードのプロパティ名として表示される正規表現のいずれかに一致するインスタンス名について、その名前の子インスタンスが一致する正規表現に対応する各スキーマに対して検証に成功した場合、検証は成功します。
このキーワードを省略した場合、空のオブジェクトと同様の動作になります。
"additionalProperties"の値は、有効なJSONスキーマでなければなりません。
このキーワードは、オブジェクトの子インスタンスがどのように検証されるかを決定し、インスタンス自体を直接検証するものではありません。
"additionalProperties"による検証は、"properties"のいずれの名前にも一致せず、"patternProperties"の正規表現にも一致しないインスタンス名の値の子にのみ適用されます。
このようなプロパティすべてについて、子インスタンスが"additionalProperties"スキーマに対して検証に成功した場合、検証は成功します。
このキーワードを省略した場合、空のスキーマと同様の動作になります。
このキーワードは、インスタンスがオブジェクトであり、特定のプロパティを含む場合に評価されるルールを指定します。
このキーワードの値はオブジェクトでなければなりません。各プロパティは依存関係を指定します。各依存関係の値は、配列または有効なJSONスキーマでなければなりません。
依存関係の値がサブスキーマであり、依存関係のキーがインスタンスのプロパティである場合、インスタンス全体が依存関係の値に対して検証に成功しなければなりません。
依存関係の値が配列の場合、配列内の各要素（存在する場合）は文字列でなければならず、一意でなければなりません。依存関係のキーがインスタンスのプロパティである場合、依存関係の値内の各項目は、インスタンスに存在するプロパティでなければなりません。
このキーワードを省略した場合、空のオブジェクトと同様の動作になります。
"propertyNames"の値は、有効なJSONスキーマでなければなりません。
インスタンスがオブジェクトの場合、このキーワードは、インスタンス内のすべてのプロパティ名が提供されたスキーマに対して検証に成功するかどうかを検証します。スキーマがテストするプロパティ名は常に文字列であることに注意してください。
このキーワードを省略した場合、空のスキーマと同様の動作になります。
このキーワードの値は配列でなければなりません。この配列には少なくとも1つの要素があるはずです。配列内の要素は一意であるべきです。
インスタンスは、その値がこのキーワードの配列値の要素の1つと等しい場合、このキーワードに対して検証に成功します。
配列内の要素は、nullを含む任意の値にすることができます。
このキーワードの値は、nullを含む任意の型にすることができます。
インスタンスは、その値がこのキーワードの値と等しい場合、このキーワードに対して検証に成功します。
このキーワードの値は、文字列または配列のいずれかでなければなりません。配列の場合、配列の要素は文字列でなければならず、一意でなければなりません。
文字列値は、6つのプリミティブ型（"null"、"boolean"、"object"、"array"、"number"、または"string"）のいずれか、または小数部がゼロである任意の数値と一致する"integer"でなければなりません。
インスタンスはこのキーワードにリストされているセットのいずれかにある場合、かつその場合にのみ検証に成功します。
このキーワードの値は、空でない配列でなければなりません。配列の各項目は、有効なJSONスキーマでなければなりません。
インスタンスはこのキーワードの値によって定義されたすべてのスキーマに対して検証に成功した場合、このキーワードに対して検証に成功します。
このキーワードの値は、空でない配列でなければなりません。配列の各項目は、有効なJSONスキーマでなければなりません。
インスタンスはこのキーワードの値によって定義された少なくとも1つのスキーマに対して検証に成功した場合、このキーワードに対して検証に成功します。
このキーワードの値は、空でない配列でなければなりません。配列の各項目は、有効なJSONスキーマでなければなりません。
インスタンスはこのキーワードの値によって定義された正確に1つのスキーマに対して検証に成功した場合、このキーワードに対して検証に成功します。
このキーワードの値は、有効なJSONスキーマでなければなりません。
インスタンスはこのキーワードによって定義されたスキーマに対して検証に成功しない場合、このキーワードに対して有効です。
このキーワードの値はオブジェクトでなければなりません。このオブジェクトの各メンバー値は、有効なJSONスキーマでなければなりません。
このキーワードは、検証自体には何ら役割を果たしません。その役割は、スキーマ作成者がより一般的なスキーマにJSONスキーマをインラインで埋め込むための標準化された場所を提供することです。
{
"type": "array",
"items": { "$ref": "#/definitions/positiveInteger" },
"definitions": {
"positiveInteger": {
"type": "integer",
"exclusiveMinimum": 0
}
}
}
例として、正の整数の配列を記述するスキーマを示します。「definitions」には正の整数制約がサブスキーマとして含まれています。
これらのキーワードの値は、文字列**でなければなりません**。
これらのキーワードは両方とも、このユーザーインターフェースによって生成されたデータに関する情報を用いてユーザーインターフェースを装飾するために使用できます。タイトルは短くするのが望ましく、説明は、このスキーマによって記述されるインスタンスの目的についての説明を提供します。
このキーワードの値には、制限はありません。
このキーワードは、特定のスキーマに関連付けられたデフォルトのJSON値を提供するために使用できます。デフォルト値が関連するスキーマに対して有効であることが**推奨**されます。
このキーワードの値は配列**でなければなりません**。配列内の値には制限はありません。
このキーワードは、使用方法を示す目的で、特定のスキーマに関連付けられたサンプルJSON値を提供するために使用できます。これらの値が関連するスキーマに対して有効であることが**推奨**されます。
実装では、存在する場合は"default"の値を追加の例として使用しても構いません。"examples"が存在しない場合でも、"default"をこのように使用しても構いません。
構造検証だけでは、インスタンスがアプリケーションのすべての要件を満たしていることを検証するには不十分な場合があります。"format"キーワードは、RFCやその他の外部仕様などの信頼できるリソースによって正確に記述される、固定された値のサブセットに対して相互運用可能な意味論的検証を可能にするために定義されています。
このキーワードの値は、フォーマット属性と呼ばれます。それは文字列**でなければなりません**。フォーマット属性は、一般的に特定のインスタンス型のセットのみを検証できます。検証対象のインスタンスの型がこのセットにない場合、このフォーマット属性とインスタンスの検証は**成功するべき**です。
実装では"format"キーワードをサポートしても構いません。サポートする場合
実装では、カスタムフォーマット属性を追加しても構いません。当事者間の合意がない限り、スキーマ作成者は、ピア実装がこのキーワードやカスタムフォーマット属性をサポートすることを期待してはいけません。
この属性は文字列インスタンスに適用されます。
文字列インスタンスは、RFC 3339、セクション5.6 [RFC3339]で定義されているように、有効な日付表現である場合、この属性に対して有効です。
この属性は文字列インスタンスに適用されます。
文字列インスタンスは、RFC 5322、セクション3.4.1 [RFC5322]で定義されているように、有効なインターネットメールアドレスである場合、この属性に対して有効です。
この属性は文字列インスタンスに適用されます。
文字列インスタンスは、RFC 1034、セクション3.1 [RFC1034]で定義されているように、有効なインターネットホスト名表現である場合、この属性に対して有効です。
この属性は文字列インスタンスに適用されます。
文字列インスタンスは、RFC 2673、セクション3.2 [RFC2673]で定義されている「ドット付きクワッド」ABNF構文に従って、有効なIPv4アドレスの表現である場合、この属性に対して有効です。
この属性は文字列インスタンスに適用されます。
文字列インスタンスは、RFC 2373、セクション2.2 [RFC2373]で定義されているように、有効なIPv6アドレスの表現である場合、この属性に対して有効です。
この属性は文字列インスタンスに適用されます。
文字列インスタンスは、[RFC3986]に従って、有効なURIである場合、この属性に対して有効です。
この属性は文字列インスタンスに適用されます。
文字列インスタンスは、[RFC3986]に従って、有効なURI参照（URIまたは相対参照のいずれか）である場合、この属性に対して有効です。
この属性は文字列インスタンスに適用されます。
文字列インスタンスは、[RFC6570]に従って、有効なURIテンプレート（任意のレベル）である場合、この属性に対して有効です。
この属性は文字列インスタンスに適用されます。
文字列インスタンスは、[RFC6901]に従って、有効なJSONポインターである場合、この属性に対して有効です。
JSONスキーマ検証は、JSONスキーマコアの語彙を定義し、そこにリストされているすべてのセキュリティに関する考慮事項を扱います。
JSONスキーマ検証では正規表現の使用が許可されていますが、正規表現には多くの異なる（多くの場合互換性のない）実装があります。一部の実装では、任意のコードの埋め込みを許可していますが、これはJSONスキーマの範囲外であり、**許可されてはなりません**。正規表現は、多くの場合、「壊滅的なバックトラッキング」と呼ばれる非常に計算コストの高いものを作成することができ、サービス拒否攻撃につながる可能性があります。
| [RFC2119] | Bradner, S.、RFCで要件レベルを示すために使用するキーワード、BCP 14、RFC 2119、DOI 10.17487/RFC2119、1997年3月。 |
| [json-schema] | JSONスキーマ：JSON文書を記述するためのメディアタイプ、インターネットドラフトdraft-wright-json-schema-00、2016年10月。 |
| [RFC1034] | Mockapetris, P.、「ドメイン名 - 概念と機能」、STD 13、RFC 1034、DOI 10.17487/RFC1034、1987年11月。 |
| [RFC2373] | Hinden, R. and 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. and C. Newman、「インターネットにおける日付と時刻：タイムスタンプ」、RFC 3339、DOI 10.17487/RFC3339、2002年7月。 |
| [RFC3986] | Berners-Lee, T.、Fielding, R. and L. Masinter、「統一資源識別子（URI）：汎用構文」、STD 66、RFC 3986、DOI 10.17487/RFC3986、2005年1月。 |
| [RFC6570] | Gregorio, J.、Fielding, R.、Hadley, M.、Nottingham, M. and D. Orchard、「URIテンプレート」、RFC 6570、DOI 10.17487/RFC6570、2012年3月。 |
| [RFC6901] | Bryan, P.、Zyp, K. and M. Nottingham、「JavaScriptオブジェクト表記（JSON）ポインター」、RFC 6901、DOI 10.17487/RFC6901、2013年4月。 |
| [RFC7159] | Bray, T.、「JavaScriptオブジェクト表記（JSON）データ交換形式」、RFC 7159、DOI 10.17487/RFC7159、2014年3月。 |
| [RFC5322] | Resnick, P.、インターネットメッセージフォーマット、RFC 5322、DOI 10.17487/RFC5322、2008年10月。 |
| [ecma262] | ECMA 262仕様" |
JSONスキーマの初期ドラフト作成にご尽力いただいた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]インターネットドラフトステータスを終了する前に、このセクションを削除してください。