インターネット技術タスクフォース A. ライト (編集)
インターネットドラフト
意図されたステータス: 情報提供 H. アンドリュース (編集)
失効: 2018年9月20日 Cloudflare, Inc.
G. ラフ
2018年3月19日

JSON Schema バリデーション: JSON の構造検証のための語彙
draft-handrews-json-schema-validation-01

概要

JSON Schema (application/schema+json) にはいくつかの目的があり、その1つが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ヶ月間有効なドラフト文書であり、いつでも他の文書によって更新、置換、または廃止される可能性があります。インターネットドラフトを参考資料として使用したり、「作業中」以外のものとして引用したりすることは不適切です。

このインターネットドラフトは、2018年9月20日に失効します。

著作権表示

Copyright (c) 2018 IETF Trust およびドキュメントの著者として識別された人物。All rights reserved.

このドキュメントは、BCP 78 およびこのドキュメントの発行日に有効な IETF Trust の IETF ドキュメントに関する法的規定 (http://trustee.ietf.org/license-info) に従います。このドキュメントに関するあなたの権利と制限について説明していますので、これらのドキュメントを注意深く確認してください。このドキュメントから抽出されたコードコンポーネントには、Trust Legal Provisions のセクション4.e に記載されている簡略化された BSD ライセンステキストを含める必要があり、簡略化された BSD ライセンスに記載されているように、保証なしで提供されます。


目次

1. はじめに

JSON Schema は、特定の JSON ドキュメント (インスタンス) が特定の数の基準を満たすことを要求するために使用できます。これらの基準は、この仕様で説明されているキーワードを使用してアサートされます。さらに、対話型ユーザーインターフェイスのインスタンス生成を支援するための一連のキーワードも定義されています。

この仕様では、JSON Schema コア [json-schema] 仕様で定義されている概念、構文、用語を使用します。

2. 表記法と用語

このドキュメントにおけるキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、および「OPTIONAL」は、RFC 2119 [RFC2119] で説明されているように解釈されます。

この仕様では、「コンテナインスタンス」という用語は、配列インスタンスとオブジェクトインスタンスの両方を指すために使用します。「子インスタンス」という用語は、配列要素またはオブジェクトメンバー値を指すために使用します。

配列値内の要素は、この配列の2つの要素が等しくない [json-schema] 場合、一意であると言われます。

3. 概要

JSON Schema バリデーションは、インスタンス内の場所に対してスキーマを適用し、各場所のデータの構造に制約をアサートします。アサートされたすべての制約を満たすインスタンスの場所には、記述的なメタデータや使用ヒントなど、アサーション情報以外の情報を含むキーワードが付加されます。インスタンス内のすべての場所がアサートされたすべての制約を満たしている場合、そのインスタンスはスキーマに対して有効であると言われます。

各スキーマオブジェクトは、適用される各インスタンスの場所に対して個別に評価されます。これにより、バリデーターがドキュメント全体の検証プロセス全体で状態を維持する必要がないようにすることで、実装要件が大幅に簡素化されます。

3.1. 適用性

検証は、ルートスキーマを完全なインスタンスドキュメントに適用することから始まります。そこから、さまざまなキーワードを使用して、現在の場所または子の場所に適用される追加のサブスキーマを決定します。これらのキーワードは、サブスキーマのアサーション結果がどのように変更および/または結合されるかも定義します。このようなキーワードは、それ自体では条件をアサートしません。むしろ、アサーションがどのように適用および評価されるかを制御します。

この仕様のブール論理 [logic] および条件付き [conditional] セクションのキーワードは、親スキーマと同じ場所にサブスキーマを適用します。前者のグループはサブスキーマのアサーション結果に対するブール演算を定義し、後者は1つのサブスキーマを評価し、そのアサーション結果を使用して、他の2つのサブスキーマのどちらを適用するかを決定します。

いくつかのキーワードは、配列項目、オブジェクトプロパティ値、およびオブジェクトプロパティ名にどのサブスキーマが適用されるかを決定します。それらは、「items」、「additionalItems」、「contains」、「properties」、「patternProperties」、「additionalProperties」、および「propertyNames」です。「contains」キーワードは、そのサブスキーマが少なくとも1つの子インスタンスに対して有効であることを要求するだけですが、他のキーワードは、すべてのサブスキーマが適用されるすべての子インスタンスに対して有効であることを要求します。

3.1.1. キーワードの独立性

検証キーワードは通常、互いの結果に影響を与えることなく、独立して動作します。

スキーマ作成者の利便性のために、サブスキーマの適用可能性を制御するキーワードの中にいくつかの例外があります。

3.2. アサーション

検証は、アサーションをチェックするプロセスです。各アサーションは、インスタンスが正常に検証するために満たす必要のある制約を追加します。

存在しないアサーションキーワードは、検証を制限することはありません。場合によっては、このno-op動作は、特定の値を伴って存在するキーワードと同一であり、これらの値は既知の場合に注記されます。

3.2.1. アサーションとインスタンスのプリミティブ型

3.3. アノテーション

3.3.1. アノテーションと検証結果

3.3.2. アノテーションとショートサーキット検証

4. 相互運用性の考慮事項

4.1. 文字列インスタンスの検証

4.2. 数値インスタンスの検証

4.3. 正規表現

5. メタスキーマ

6. 検証キーワード

6.1. 任意のインスタンス型の検証キーワード

6.1.1. type

6.1.2. enum

6.1.3. const

6.2. 数値インスタンスの検証キーワード(数値と整数)

6.2.1. multipleOf

6.2.2. maximum

6.2.3. exclusiveMaximum

6.2.4. minimum

6.2.5. exclusiveMinimum

6.3. 文字列の検証キーワード

6.3.1. maxLength

6.3.2. minLength

6.3.3. pattern

6.4. 配列の検証キーワード

6.4.1. items

6.4.2. additionalItems

6.4.3. maxItems

6.4.4. minItems

6.4.5. uniqueItems

6.4.6. contains

6.5. オブジェクトの検証キーワード

6.5.1. maxProperties

6.5.2. minProperties

オブジェクトインスタンスのプロパティ数が、このキーワードの値以上である場合、そのインスタンスは"minProperties"に対して有効となります。

6.5.3. required

このキーワードの値は、配列でなければなりません。この配列の要素は、もしあれば、文字列でなければならず、かつ一意でなければなりません。

配列内のすべての項目がインスタンス内のプロパティの名前である場合、オブジェクトインスタンスはこのキーワードに対して有効となります。

このキーワードを省略した場合、空の配列と同じ動作になります。

6.5.4. properties

"properties"の値は、オブジェクトでなければなりません。このオブジェクトの各値は、有効なJSON Schemaでなければなりません。

このキーワードは、オブジェクトに対する子インスタンスの検証方法を決定し、直接的なインスタンス自体は検証しません。

インスタンスとこのキーワードの値の両方に名前が現れる場合、その名前の子インスタンスが対応するスキーマに対して正常に検証されれば、検証は成功します。

このキーワードを省略した場合、空のオブジェクトと同じ動作になります。

6.5.5. patternProperties

"patternProperties"の値は、オブジェクトでなければなりません。このオブジェクトの各プロパティ名は、ECMA 262正規表現方言に従って有効な正規表現であるべきです。このオブジェクトの各プロパティ値は、有効なJSON Schemaでなければなりません。

このキーワードは、オブジェクトに対する子インスタンスの検証方法を決定し、直接的なインスタンス自体は検証しません。このキーワードに対するプリミティブインスタンス型の検証は常に成功します。

インスタンス名がこのキーワードの値のプロパティ名として現れる正規表現のいずれかに一致する場合、その名前の子インスタンスが、一致する正規表現に対応する各スキーマに対して正常に検証されれば、検証は成功します。

このキーワードを省略した場合、空のオブジェクトと同じ動作になります。

6.5.6. additionalProperties

"additionalProperties"の値は、有効なJSON Schemaでなければなりません。

このキーワードは、オブジェクトに対する子インスタンスの検証方法を決定し、直接的なインスタンス自体は検証しません。

"additionalProperties"による検証は、"properties"内の名前にも、"patternProperties"内の正規表現にも一致しないインスタンス名の子の値にのみ適用されます。

そのようなすべてのプロパティに対して、子インスタンスが"additionalProperties"スキーマに対して検証されれば、検証は成功します。

6.5.7. dependencies

[CREF1]このキーワードは2つに分割される可能性があり、サブスキーマではなくプロパティ名の配列を使用するバリエーションには新しい名前が与えられます。二重の動作は紛らわしく、実装が比較的困難です。以前のドラフトでは、このキーワードを完全に削除するか、その形式の1つを削除することを提案しましたが、それを維持することを支持するフィードバックを受けました。詳細については、<https://github.com/json-schema-org/json-schema-spec/issues>にあるissue #442と#528を参照してください。さらなるフィードバックをお待ちしています。

このキーワードは、インスタンスがオブジェクトであり、特定のプロパティを含む場合に評価されるルールを指定します。

このキーワードの値は、オブジェクトでなければなりません。各プロパティは依存関係を指定します。各依存関係の値は、配列または有効なJSON Schemaでなければなりません。

依存関係の値がサブスキーマであり、依存関係キーがインスタンス内のプロパティである場合、インスタンス全体が依存関係の値に対して検証されなければなりません。

依存関係の値が配列である場合、配列内の各要素は、もしあれば、文字列でなければならず、かつ一意でなければなりません。依存関係キーがインスタンス内のプロパティである場合、依存関係の値の各項目は、インスタンスに存在するプロパティでなければなりません。

このキーワードを省略した場合、空のオブジェクトと同じ動作になります。

6.5.8. propertyNames

"propertyNames"の値は、有効なJSON Schemaでなければなりません。

インスタンスがオブジェクトである場合、インスタンス内のすべてのプロパティ名が提供されたスキーマに対して検証される場合、このキーワードは検証されます。スキーマがテストしているプロパティ名は常に文字列であることに注意してください。

6.6. サブスキーマを条件付きで適用するためのキーワード

これらのキーワードは、あるサブスキーマの結果に基づいてサブスキーマの条件付き適用を実装するために連携します。

これらのキーワードは、サブスキーマの境界を越えて相互作用してはなりません。言い換えれば、"allOf"のあるブランチの"if"が、別のブランチの"then"または"else"に影響を与えてはなりません。

これらのキーワードのいずれかが存在しない場合、デフォルトの動作はありません。特に、空のスキーマが存在する場合のように扱ってはならず、"if"が存在しない場合、"then"と"else"の両方を完全に無視する必要があります。

6.6.1. if

このキーワードの値は、有効なJSON Schemaでなければなりません。

このキーワードのサブスキーマの検証結果は、全体的な検証結果に直接的な影響を与えません。むしろ、"then"または"else"キーワードのどちらを評価するかを制御します。

このキーワードのサブスキーマに対して正常に検証されたインスタンスは、存在する場合は、"then"キーワードのサブスキーマ値に対しても有効である必要があります。

このキーワードのサブスキーマに対して検証に失敗したインスタンスは、存在する場合は、"else"キーワードのサブスキーマ値に対しても有効である必要があります。

アノテーション [annotations] が収集されている場合、キーワードが"then"または"else"のいずれもなしで存在する場合を含め、通常の方法でこのキーワードのサブスキーマから収集されます。

6.6.2. then

このキーワードの値は、有効なJSON Schemaでなければなりません。

"if"が存在し、インスタンスがそのサブスキーマに対して正常に検証される場合、インスタンスがこのキーワードのサブスキーマに対しても正常に検証されれば、このキーワードに対して検証が成功します。

"if"が存在しない場合、またはインスタンスがそのサブスキーマに対して検証に失敗した場合、このキーワードは効果がありません。このような場合、実装は、検証またはアノテーション収集の目的で、このキーワードに対してインスタンスを評価してはなりません。

6.6.3. else

このキーワードの値は、有効なJSON Schemaでなければなりません。

"if"が存在し、インスタンスがそのサブスキーマに対して検証に失敗した場合、インスタンスがこのキーワードのサブスキーマに対して正常に検証されれば、このキーワードに対して検証が成功します。

"if"が存在しない場合、またはインスタンスがそのサブスキーマに対して正常に検証された場合、このキーワードは効果がありません。このような場合、実装は、検証またはアノテーション収集の目的で、このキーワードに対してインスタンスを評価してはなりません。

6.7. ブール論理を使用してサブスキーマを適用するためのキーワード

6.7.1. allOf

このキーワードの値は、空でない配列でなければなりません。配列の各項目は、有効なJSON Schemaでなければなりません。

インスタンスは、このキーワードの値によって定義されたすべてのスキーマに対して正常に検証された場合、このキーワードに対して正常に検証されます。

6.7.2. anyOf

このキーワードの値は、空でない配列でなければなりません。配列の各項目は、有効なJSON Schemaでなければなりません。

インスタンスは、このキーワードの値によって定義された少なくとも1つのスキーマに対して正常に検証された場合、このキーワードに対して正常に検証されます。

6.7.3. oneOf

このキーワードの値は、空でない配列でなければなりません。配列の各項目は、有効なJSON Schemaでなければなりません。

インスタンスは、このキーワードの値によって定義されたちょうど1つのスキーマに対して正常に検証された場合、このキーワードに対して正常に検証されます。

6.7.4. not

このキーワードの値は、有効なJSON Schemaでなければなりません。

インスタンスは、このキーワードによって定義されたスキーマに対して正常に検証に失敗した場合、このキーワードに対して有効です。

7. "format"を使用したセマンティック検証

7.1. 前書き

構造検証だけでは、インスタンスがアプリケーションのすべての要件を満たしていることを検証するには不十分な場合があります。"format"キーワードは、RFCまたはその他の外部仕様である権威あるリソースによって正確に記述される、固定された値のサブセットに対して、相互運用可能なセマンティック検証を可能にするために定義されています。

このキーワードの値は、フォーマット属性と呼ばれます。文字列でなければなりません。フォーマット属性は通常、特定のインスタンス型のセットのみを検証できます。検証するインスタンスの型がこのセットに含まれていない場合、このフォーマット属性とインスタンスに対する検証は成功するはずです。

7.2. 実装要件

"format"キーワードは、アノテーション(セクション3.3)とアサーション(セクション3.2)の両方として機能します。セマンティックな意味を伝えるアノテーションとして実装するのに特別な努力は必要ありませんが、検証の実装は簡単ではありません。

実装は、検証アサーションとして"format"キーワードをサポートしてもよいです。そうすることを選択した場合、

実装は、カスタムフォーマット属性を追加してもよいです。当事者間の合意を除き、スキーマ作成者は、ピア実装がこのキーワードやカスタムフォーマット属性をサポートすることを期待してはなりません。

7.3. 定義済みのフォーマット

7.3.1. 日付と時刻

これらの属性は、文字列インスタンスに適用されます。

日付と時刻のフォーマット名は、RFC 3339、セクション5.6 [RFC3339]から派生しています。

フォーマットをサポートする実装は、次の属性のサポートを実装するべきです。

date-time
文字列インスタンスは、"date-time"生成規則に従って有効な表現である場合、この属性に対して有効です。
date
文字列インスタンスは、"full-date"生成規則に従って有効な表現である場合、この属性に対して有効です。
time
文字列インスタンスは、"full-time"生成規則に従って有効な表現である場合、この属性に対して有効です。

実装は、そのセクションで定義されている他の生成規則名を使用して、追加の属性をサポートしてもよいです。"full-date"または"full-time"が実装されている場合、対応する短縮形(それぞれ"date"または"time")を実装する必要があり、同じように動作する必要があります。実装は、その生成規則のルールに従って検証されない限り、RFC 3339生成規則に一致する名前で拡張属性を定義するべきではありません。[CREF2]すべてのRFC 3339形式をサポートする必要性について、現在コンセンサスが得られていないため、この名前空間を予約するアプローチは、セット全体にコミットすることなく実験を促すでしょう。フォーマット実装要件は全体的にもっと柔軟になるか、これらは完全に指定された属性に昇格するか、破棄される可能性が高いでしょう。

7.3.2. メールアドレス

これらの属性は、文字列インスタンスに適用されます。

文字列インスタンスは、次のように、有効なインターネットメールアドレスである場合、これらの属性に対して有効です。

email
RFC 5322、セクション3.4.1 [RFC5322]で定義されているとおり。
idn-email
RFC 6531 [RFC6531]で定義されているとおり。

"email"属性に対して有効なすべての文字列は、"idn-email"属性に対しても有効であることに注意してください。

7.3.3. ホスト名

これらの属性は、文字列インスタンスに適用されます。

文字列インスタンスは、次のように、インターネットホスト名の有効な表現である場合、これらの属性に対して有効です。

hostname
RFC 1034、セクション3.1 [RFC1034]で定義されているとおり。また、RFC 5891、セクション4.4 [RFC5891]で指定されているPunycodeアルゴリズムを使用して生成されたホスト名も含まれます。
idn-hostname
hostnameの場合のRFC 1034、またはRFC 5890、セクション2.3.2.3 [RFC5890]で定義されている国際化ホスト名で定義されているとおり。

"hostname"属性に対して有効なすべての文字列は、"idn-hostname"属性に対しても有効であることに注意してください。

7.3.4. IPアドレス

これらの属性は、文字列インスタンスに適用されます。

文字列インスタンスは、次のように、IPアドレスの有効な表現である場合、これらの属性に対して有効です。

ipv4
RFC 2673、セクション3.2 [RFC2673]で定義されている"ドット付きクワッド"ABNF構文に従ったIPv4アドレス。
ipv6
RFC 4291、セクション2.2 [RFC4291]で定義されているIPv6アドレス。

7.3.5. リソース識別子

これらの属性は、文字列インスタンスに適用されます。

uri
文字列インスタンスは、[RFC3986]に従って有効なURIである場合、この属性に対して有効です。
uri-reference
文字列インスタンスは、[RFC3986]に従って有効なURI参照(URIまたは相対参照のいずれか)である場合、この属性に対して有効です。
iri
文字列インスタンスは、[RFC3987]に従って有効なIRIである場合、この属性に対して有効です。
iri-reference
文字列インスタンスがこの属性に対して有効であるのは、[RFC3987]に従って、それが有効なIRI参照(IRIまたは相対参照のいずれか)である場合です。

すべての有効なURIは有効なIRIであり、すべての有効なURI参照も有効なIRI参照であることに注意してください。

7.3.6. uri-template

この属性は文字列インスタンスに適用されます。

文字列インスタンスがこの属性に対して有効であるのは、[RFC6570]に従って、それが有効なURIテンプレート(任意のレベル)である場合です。

URIテンプレートはIRIに使用できることに注意してください。IRIテンプレートの個別の仕様はありません。

7.3.7. JSONポインター

これらの属性は、文字列インスタンスに適用されます。

json-pointer
文字列インスタンスがこの属性に対して有効であるのは、RFC 6901, section 5 [RFC6901]に従って、それがJSONポインターの有効なJSON文字列表現である場合です。
relative-json-pointer
文字列インスタンスがこの属性に対して有効であるのは、それが有効な相対JSONポインター [relative-json-pointer]である場合です。

絶対JSONポインターと相対JSONポインターの両方を許可するには、"anyOf"または"oneOf"を使用して、どちらの形式もサポートすることを示します。

7.3.8. regex

この属性は文字列インスタンスに適用されます。

正規表現。これは、ECMA 262 [ecma262]正規表現の方言に従って有効である必要があります(SHOULD)。

フォーマットを検証する実装は、この仕様の正規表現 [regexInterop]セクションで定義されているECMA 262のサブセットを少なくとも受け入れる必要があり(MUST)、有効なECMA 262式をすべて受け入れる必要があります(SHOULD)。

8. 文字列エンコードされた非JSONデータ

8.1. 前書き

このセクションで定義されているプロパティは、インスタンスにJSON文字列でエンコードされた非JSONデータが含まれていることを示します。それらは、コンテンツのタイプとエンコード方法を記述します。

これらのプロパティは、JSONデータをリッチマルチメディアドキュメントとして解釈するために必要な追加情報を提供します。

8.2. 実装要件

コンテンツキーワードは、注釈(セクション3.3)とアサーション(セクション3.2)の両方として機能します。アプリケーションが文字列内のデータを解釈する方法を伝える注釈として実装するために特別な努力は必要ありませんが、メディアタイプとエンコードへの準拠の検証を実装することは簡単ではありません。

実装は、検証アサーションとして"contentMediaType"キーワードと"contentEncoding"キーワードをサポートしてもよい(MAY)。サポートする場合、これらのキーワードの検証を無効にするオプションを提供する必要があります(SHOULD)。

8.3. contentEncoding

インスタンス値が文字列の場合、このプロパティは、文字列をバイナリデータとして解釈し、このプロパティで指定されたエンコードを使用してデコードする必要がある(SHOULD)ことを定義します。RFC 2045, Sec 6.1 [RFC2045]は、このプロパティに使用できる値をリストしています。

このプロパティの値は文字列である必要があります(MUST)。

記述されたインスタンスが文字列でない場合、このプロパティの値は無視される必要があります(SHOULD)。

8.4. contentMediaType

このプロパティの値は、RFC 2046 [RFC2046]で定義されているメディアタイプである必要があります(MUST)。このプロパティは、このスキーマが定義するインスタンスのメディアタイプを定義します。

このプロパティの値は文字列である必要があります(MUST)。

記述されたインスタンスが文字列でない場合、このプロパティの値は無視される必要があります(SHOULD)。

"contentEncoding"プロパティが存在しないが、インスタンス値が文字列の場合、このプロパティの値はテキストドキュメントタイプを指定する必要があり(SHOULD)、文字セットはJSON文字列値がデコードされた文字セットである必要があります(SHOULD)(デフォルトはUnicodeです)。

8.5.

以下は、"contentEncoding"と"contentMediaType"の使用例を示すスキーマの例です。

{
    "type": "string",
    "contentEncoding": "base64",
    "contentMediaType": "image/png"
}

                    

このスキーマで記述されたインスタンスは文字列である必要があり、その値はbase64エンコードされたPNG画像として解釈できる必要があります。

別の例

{
    "type": "string",
    "contentMediaType": "text/html"
}

                    

このスキーマで記述されたインスタンスは、JSON文字列がデコードされた文字セット(デフォルトはUnicode)を使用し、HTMLを含む文字列である必要があります。

9. "definitions"によるスキーマの再利用

"definitions"キーワードは、スキーマ作成者が再利用可能なJSONスキーマをより一般的なスキーマにインライン化するための標準化された場所を提供します。このキーワードは、検証結果に直接影響しません。

このキーワードの値はオブジェクトである必要があります(MUST)。このオブジェクトの各メンバーの値は、有効なJSONスキーマである必要があります(MUST)。

{
    "type": "array",
    "items": { "$ref": "#/definitions/positiveInteger" },
    "definitions": {
        "positiveInteger": {
            "type": "integer",
            "exclusiveMinimum": 0
        }
    }
}

                    

例として、以下は正の整数の配列を記述するスキーマです。ここで、正の整数の制約は"definitions"内のサブスキーマです。

10. スキーマ注釈

スキーマ検証は、インスタンスデータに追加情報を注釈するのに便利なメカニズムです。注釈がいつ、どのようにインスタンスに関連付けられるかを決定するためのルールは、3.3節で概説されています。

これらの汎用注釈キーワードは、ドキュメントやユーザーインターフェースの表示目的で一般的に使用される情報を提供します。これらは包括的な機能セットを形成することを意図したものではありません。むしろ、より複雑な注釈ベースのアプリケーションのために追加の語彙を定義できます。

10.1. "title"と"description"

これらのキーワードの値はいずれも文字列である必要があります(MUST)。

これらのキーワードはどちらも、このユーザーインターフェースによって生成されたデータに関する情報をユーザーインターフェースで装飾するために使用できます。タイトルは短くすることが望ましく、説明はこのスキーマで記述されたインスタンスの目的に関する説明を提供します。

10.2. "default"

このキーワードの値に制限はありません。このキーワードの複数の出現箇所が単一のサブインスタンスに適用される場合、実装は重複を削除する必要があります(SHOULD)。

このキーワードは、特定のスキーマに関連付けられたデフォルトのJSON値を提供するために使用できます。デフォルト値が関連付けられたスキーマに対して有効であることが推奨されます(RECOMMENDED)。

10.3. "readOnly"と"writeOnly"

これらのキーワードの値はブール値である必要があります(MUST)。これらのキーワードの複数の出現箇所が単一のサブインスタンスに適用される場合、いずれかの出現箇所がtrue値を指定した場合は結果の値はtrueである必要があり(MUST)、それ以外の場合はfalseである必要があります(MUST)。

"readOnly"の値がブール値のtrueである場合、インスタンスの値は所有権のある機関によって排他的に管理され、アプリケーションがこのプロパティの値を変更しようとすると、その所有権のある機関によって無視または拒否されることが想定されます。

ドキュメント全体に対して"readOnly"とマークされているインスタンスドキュメントは、所有権のある機関に送信された場合に無視されるか、機関の裁量でエラーになる可能性があります(MAY)。

"writeOnly"の値がブール値のtrueである場合、値は所有権のある機関からインスタンスを取得するときには決して存在しないことを示します。ドキュメント(またはそれが表すリソース)を更新または作成するために所有権のある機関に送信するときには存在できますが、インスタンスの更新または新規作成されたバージョンには含まれません。

ドキュメント全体に対して"writeOnly"とマークされているインスタンスドキュメントは、ある種の空白ドキュメントとして返されるか、取得時にエラーが発生するか、機関の裁量で取得要求が無視される可能性があります(MAY)。

たとえば、"readOnly"はデータベースで生成されたシリアル番号を読み取り専用としてマークするために使用され、"writeOnly"はパスワード入力フィールドをマークするために使用されます。

これらのキーワードは、ユーザーインターフェースのインスタンス生成を支援するために使用できます。特に、アプリケーションは、書き込み専用フィールドに入力された値を非表示にするウィジェットを使用することを選択してもよい(MAY)。

これらのキーワードを省略した場合の動作は、falseの値と同じです。

10.4. "examples"

このキーワードの値は配列である必要があります(MUST)。配列内の値に制限はありません。このキーワードの複数の出現箇所が単一のサブインスタンスに適用される場合、実装は配列の配列ではなく、すべての値のフラットな配列を提供する必要があります(MUST)。

このキーワードは、使用法を示す目的で、特定のスキーマに関連付けられたサンプルJSON値を提供するために使用できます。これらの値が関連付けられたスキーマに対して有効であることが推奨されます(RECOMMENDED)。

実装は、"default"の値が存在する場合、追加の例として使用してもよい(MAY)。"examples"が存在しない場合、"default"をこの方法で使用してもよい(MAY)。

11. セキュリティに関する考慮事項

JSONスキーマ検証は、JSONスキーマコアの語彙を定義し、そこにリストされているすべてのセキュリティに関する考慮事項に関係します。

JSONスキーマ検証では、正規表現の使用が許可されています。正規表現には、多数の異なる(多くの場合、互換性のない)実装があります。一部の実装では、任意のコードの埋め込みが許可されています。これはJSONスキーマの範囲外であり、許可されてはなりません(MUST NOT)。また、正規表現は、計算に非常にコストがかかるように(いわゆる「壊滅的なバックトラック」を伴って)作成できることが多く、サービス拒否攻撃につながる可能性があります。

"contentEncoding"および/または"contentMediaType"に基づいてインスタンス文字列データの検証またはその他の評価をサポートする実装は、誤った情報に基づいて安全でない方法でデータを評価するリスクがあります。アプリケーションは、スキーマとインスタンス間の関係が確立されている場合(たとえば、同じ機関を共有している場合)にのみそのような処理を実行することで、このリスクを軽減できます。

メディアタイプまたはエンコードの処理は、そのメディアタイプまたはエンコードのセキュリティに関する考慮事項の影響を受けます。たとえば、JSON文字列内でエンコードされたJavaScriptまたはECMAScriptを処理する場合、RFC 4329 Scripting Media Types [RFC4329]のセキュリティに関する考慮事項が適用されます。

12. 参考文献

12.1. 規範的参考文献

, "
[RFC2119] Bradner, S., "RFCで要求レベルを示すために使用するキーワード", BCP 14, RFC 2119, DOI 10.17487/RFC2119, 1997年3月.
[RFC1034] Mockapetris, P., "ドメイン名 - 概念と機能", STD 13, RFC 1034, DOI 10.17487/RFC1034, 1987年11月.
[RFC2045] Freed, N. and N. Borenstein, "多目的インターネットメール拡張(MIME)パート1:インターネットメッセージ本文の形式", RFC 2045, DOI 10.17487/RFC2045, 1996年11月.
[RFC2046] Freed, N. and N. Borenstein, "多目的インターネットメール拡張(MIME)パート2:メディアタイプ", RFC 2046, DOI 10.17487/RFC2046, 1996年11月.
[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, "Uniform Resource Identifier(URI):汎用構文", STD 66, RFC 3986, DOI 10.17487/RFC3986, 2005年1月.
[RFC3987] Duerst, M. and M. Suignard, "国際化リソース識別子(IRI)", RFC 3987, DOI 10.17487/RFC3987, 2005年1月.
[RFC4291] Hinden, R. and S. Deering, "IPバージョン6アドレス指定アーキテクチャ", RFC 4291, DOI 10.17487/RFC4291, 2006年2月.
[RFC5322] Resnick, P., "インターネットメッセージ形式", RFC 5322, DOI 10.17487/RFC5322, 2008年10月.
[RFC5890] Klensin, J., "アプリケーションのための国際化ドメイン名 (IDNA): 定義とドキュメントフレームワーク", RFC 5890, DOI 10.17487/RFC5890, 2010年8月.
[RFC5891] Klensin, J., "アプリケーションにおける国際化ドメイン名 (IDNA): プロトコル", RFC 5891, DOI 10.17487/RFC5891, 2010年8月.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M. and D. Orchard, "URIテンプレート", RFC 6570, DOI 10.17487/RFC6570, 2012年3月.
[RFC6531] Yao, J. and W. Mao, "国際化電子メールのためのSMTP拡張", RFC 6531, DOI 10.17487/RFC6531, 2012年2月.
[RFC6901] Bryan, P., Zyp, K. and 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月.
[ecma262]ECMA 262 仕様"
[relative-json-pointer] Luff, G. and H. Andrews, "相対JSONポインタ", Internet-Draft draft-handrews-relative-json-pointer-01, 2017年11月.
[json-schema] Wright, A. and H. Andrews, "JSON Schema: JSONドキュメントを記述するためのメディアタイプ", Internet-Draft draft-handrews-json-schema-01, 2017年11月.

12.2. 参考情報

[RFC4329] Hoehrmann, B., "スクリプトメディアタイプ", RFC 4329, DOI 10.17487/RFC4329, 2006年4月.

付録 A. 謝辞

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、Denis Laxalde に感謝します。

付録 B. 変更履歴

[CREF3]このセクションはインターネットドラフトのステータスを離れる前に削除されます。

draft-handrews-json-schema-validation-01

draft-handrews-json-schema-validation-00

draft-wright-json-schema-validation-01

draft-wright-json-schema-validation-00

draft-fge-json-schema-validation-00

著者のアドレス

Austin Wright (編集者) メール: [email protected]
Henry Andrews (編集者) Cloudflare, Inc. サンフランシスコ, CA アメリカ メール: [email protected]
Geraint Luff ケンブリッジ, イギリス メール: [email protected]