| インターネット技術タスクフォース | A. Wright 編 |
| インターネットドラフト | |
| 予定ステータス：参考情報 | H. Andrews 編 |
| 期限切れ：2021年8月1日 | |
| B. Hutton 編 | |
| 2020年1月28日 |
JSONスキーマ検証：JSONの構造検証のための語彙
draft-bhutton-json-schema-validation-00
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）の作業文書です。他のグループもインターネットドラフトとして作業文書を配布する場合があることに注意してください。現在のインターネットドラフトのリストは、https://datatracker.ietf.org/drafts/current/にあります。
インターネットドラフトは最大6ヶ月有効なドラフト文書であり、いつでも他の文書によって更新、置換、または廃止される可能性があります。「作業中」以外に、インターネットドラフトを参照資料として使用したり、引用したりすることは不適切です。
このインターネットドラフトは、2021年8月1日に期限切れになります。
Copyright (c) 2020 IETF Trustおよび文書の著者として特定された人物。全著作権所有。
このドキュメントは、BCP 78およびこのドキュメントの公開日時点で有効なIETFドキュメントに関するIETFトラストの法的規定（https://trustee.ietf.org/license-info）の対象となります。これらのドキュメントは、このドキュメントに関するあなたの権利と制限を記述しているため、注意深く確認してください。このドキュメントから抽出されたコードコンポーネントには、トラストの法的規定のセクション4.eに記載されているように、簡略化されたBSDライセンステキストを含める必要があり、簡略化されたBSDライセンスに記載されているように、保証なしで提供されます。
JSONスキーマは、特定のJSONドキュメント（インスタンス）が特定の基準を満たしていることを要求するために使用できます。これらの基準は、この仕様で説明されているキーワードを使用して主張されます。さらに、キーワードのセットも定義されており、対話型のユーザーインターフェースインスタンスの生成を支援します。
この仕様では、JSONスキーマコア仕様で定義されている概念、構文、および用語を使用します。
このドキュメントのキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC 2119で説明されているように解釈されます。
この仕様では、「コンテナインスタンス」という用語を配列インスタンスとオブジェクトインスタンスの両方を指すために使用します。「子インスタンス」という用語は、配列要素またはオブジェクトのメンバ値を指すために使用します。
配列値の要素は、この配列の2つの要素が等しくない場合、一意であると言われます。
JSONスキーマ検証は、インスタンスデータの構造に対する制約を主張します。すべての主張された制約を満たすインスタンスの場所は、記述的なメタデータや使用方法のヒントなどの非アサーション情報を含むキーワードで注釈が付けられます。インスタンス内のすべての場所がすべての主張された制約を満たしている場合、インスタンスはスキーマに対して有効であると言われます。
各スキーマオブジェクトは、適用される各インスタンスの場所に対して個別に評価されます。これにより、ドキュメント全体の検証プロセス全体で状態を維持する必要がないため、検証者の実装要件が大幅に簡素化されます。
この仕様は、アサーションキーワードのセットと、JSONインスタンスに役立つ情報を付加するために使用できる小さなメタデータキーワードの語彙を定義します。セクション7キーワードは主に注釈として意図されていますが、オプションでアサーションとして使用できます。セクション8キーワードは、JSON文字列として埋め込まれたドキュメントを操作するための注釈です。
ヌル文字（\u0000）はJSON文字列で有効であることに注意してください。検証するインスタンスには、基になるプログラミング言語がこの種のデータに対処できるかどうかに関係なく、この文字を含む文字列値が含まれている場合があります。
JSON仕様では任意の精度の数値が許可されており、JSONスキーマではそのような境界を追加していません。これは、基になるプログラミング言語がこの種のデータに対処できるかどうかに関係なく、JSONスキーマによって処理される数値インスタンスは、任意に大きく、または任意に長い小数部を持つことができることを意味します。
正規表現を使用するキーワード、またはインスタンス値を正規表現に制約するキーワードは、JSONスキーマコア仕様の正規表現に関する相互運用性の考慮事項の対象となります。
デフォルトのJSONスキーマ方言メタスキーマの現在のURIは<https://json-schema.dokyumento.jp/draft/2020-12/schema>です。スキーマ作成者の便宜のために、このメタスキーマは、この仕様とJSONスキーマコア仕様で定義されているすべての語彙と、移行期間のために予約されている2つの以前のキーワードで構成される方言を記述しています。個々の語彙と語彙メタスキーマのURIは、以下の各セクションに記載されています。サポートするには特定の語彙がオプションであることがあり、関連セクションで詳細に説明されています。
エラーを修正するために、仕様ドラフト間で更新された語彙とメタスキーマのURIが公開される場合があります。実装では、この仕様ドラフトの後、次のドラフトの前に日付が付けられたURIを考慮して、ここにリストされているものと同じ構文とセマンティクスを示す必要があります。
スキーマ内の検証キーワードは、インスタンスの検証に成功するための要件を課します。これらのキーワードはすべて、注釈動作のないアサーションです。
"$vocabulary"を使用しないメタスキーマは、そのURIがtrueの値で存在するかのように、この語彙を必要とするものと見なすべきです。
検証語彙として知られるこの語彙の現在のURIは次のとおりです。<https://json-schema.dokyumento.jp/draft/2020-12/vocab/validation>。
対応するメタスキーマの現在のURIは次のとおりです。<https://json-schema.dokyumento.jp/draft/2020-12/meta/validation>。
このキーワードの値は、文字列または配列のいずれかでなければなりません。配列の場合、配列の要素は文字列でなければならず、かつ一意でなければなりません。
文字列値は、6つのプリミティブ型("null"、"boolean"、"object"、"array"、"number"、または"string")、または小数部分がゼロの任意の数値に一致する"integer"のいずれかでなければなりません。
インスタンスは、このキーワードにリストされている集合のいずれかに存在する場合に限り、検証に合格します。
このキーワードの値は配列でなければなりません。この配列は、少なくとも1つの要素を持つべきです。配列内の要素は一意であるべきです。
インスタンスは、その値がこのキーワードの配列値のいずれかの要素と等しい場合、このキーワードに対して正常に検証されます。
配列内の要素は、nullを含む任意の型にすることができます。
このキーワードの値は、nullを含む任意の型にすることができます。
このキーワードの使用は、単一の値を持つ"enum"と機能的に同等です。
インスタンスは、その値がこのキーワードの値と等しい場合、このキーワードに対して正常に検証されます。
"multipleOf"の値は、0より大きい数値でなければなりません。
数値インスタンスは、このキーワードの値で除算した結果が整数である場合にのみ有効です。
"maximum"の値は、数値インスタンスの上限となる包含的な数値でなければなりません。
インスタンスが数値の場合、このキーワードは、インスタンスが"maximum"以下である場合にのみ検証に合格します。
"exclusiveMaximum"の値は、数値インスタンスの上限となる排他的な数値でなければなりません。
インスタンスが数値の場合、インスタンスは"exclusiveMaximum"より厳密に小さい値（等しくない）を持つ場合にのみ有効です。
"minimum"の値は、数値インスタンスの下限となる包含的な数値でなければなりません。
インスタンスが数値の場合、このキーワードは、インスタンスが"minimum"以上である場合にのみ検証に合格します。
"exclusiveMinimum"の値は、数値インスタンスの下限となる排他的な数値でなければなりません。
インスタンスが数値の場合、インスタンスは"exclusiveMinimum"より厳密に大きい値（等しくない）を持つ場合にのみ有効です。
このキーワードの値は、非負の整数でなければなりません。
文字列インスタンスは、その長さがこのキーワードの値以下である場合、このキーワードに対して有効です。
文字列インスタンスの長さは、RFC 8259で定義されているように、その文字数として定義されます。
このキーワードの値は、非負の整数でなければなりません。
文字列インスタンスは、その長さがこのキーワードの値以上である場合、このキーワードに対して有効です。
文字列インスタンスの長さは、RFC 8259で定義されているように、その文字数として定義されます。
このキーワードを省略した場合、値0と同じ動作になります。
このキーワードの値は文字列でなければなりません。この文字列は、ECMA-262正規表現方言に従って、有効な正規表現であるべきです。
正規表現がインスタンスに正常に一致した場合、文字列インスタンスは有効とみなされます。繰り返しますが、正規表現は暗黙的にアンカーされません。
このキーワードの値は、非負の整数でなければなりません。
配列インスタンスは、そのサイズがこのキーワードの値以下である場合、「maxItems」に対して有効です。
このキーワードの値は、非負の整数でなければなりません。
配列インスタンスは、そのサイズがこのキーワードの値以上である場合、「minItems」に対して有効です。
このキーワードを省略した場合、値0と同じ動作になります。
このキーワードの値はブール値でなければなりません。
このキーワードがブール値falseの場合、インスタンスは正常に検証されます。ブール値trueの場合、インスタンスのすべての要素が一意である場合にのみ、インスタンスは正常に検証されます。
このキーワードを省略した場合、値falseと同じ動作になります。
このキーワードの値は、非負の整数でなければなりません。
同じスキーマオブジェクト内に"contains"が存在しない場合、このキーワードは効果がありません。
インスタンス配列は、隣接する"contains"キーワードのアノテーション結果の形式に応じて、2つの方法で"maxContains"に対して有効になります。最初の方法は、アノテーション結果が配列であり、その配列の長さが"maxContains"値以下である場合です。2番目の方法は、アノテーション結果がブール値"true"であり、インスタンス配列の長さが"maxContains"値以下である場合です。
このキーワードの値は、非負の整数でなければなりません。
同じスキーマオブジェクト内に"contains"が存在しない場合、このキーワードは効果がありません。
インスタンス配列は、隣接する"contains"キーワードのアノテーション結果の形式に応じて、2つの方法で"minContains"に対して有効になります。最初の方法は、アノテーション結果が配列であり、その配列の長さが"minContains"値以上である場合です。2番目の方法は、アノテーション結果がブール値"true"であり、インスタンス配列の長さが"minContains"値以上である場合です。
値0は許可されますが、0から"maxContains"の値までの発生範囲を設定する場合にのみ役立ちます。"maxContains"がない状態で値0の場合、「contains」は常に検証に合格します。
このキーワードを省略した場合、値1と同じ動作になります。
このキーワードの値は、非負の整数でなければなりません。
オブジェクトインスタンスは、そのプロパティ数がこのキーワードの値以下である場合、「maxProperties」に対して有効です。
このキーワードの値は、非負の整数でなければなりません。
オブジェクトインスタンスは、そのプロパティ数がこのキーワードの値以上である場合、「minProperties」に対して有効です。
このキーワードを省略した場合、値0と同じ動作になります。
このキーワードの値は配列でなければなりません。この配列の要素（存在する場合）は文字列でなければならず、かつ一意でなければなりません。
オブジェクトインスタンスは、配列内のすべての項目がインスタンス内のプロパティ名である場合、このキーワードに対して有効です。
このキーワードを省略した場合、空の配列と同じ動作になります。
このキーワードの値はオブジェクトでなければなりません。このオブジェクトのプロパティ（存在する場合）は配列でなければなりません。各配列の要素（存在する場合）は文字列でなければならず、かつ一意でなければなりません。
このキーワードは、特定の他のプロパティが存在する場合に必須となるプロパティを指定します。それらの必須要件は、他のプロパティの存在に依存しています。
インスタンスとこのキーワードの値の両方に出現する名前ごとに、対応する配列内のすべての項目がインスタンス内のプロパティ名でもある場合、検証は成功します。
このキーワードを省略した場合、空のオブジェクトと同じ動作になります。
構造検証だけでは、アプリケーションが特定の値を正しく使用できるようにするには不十分な場合があります。"format"アノテーションキーワードは、スキーマ作成者が、RFCやその他の外部仕様など、権威あるリソースによって正確に記述されている値の固定サブセットに関するセマンティック情報を伝えることを可能にするために定義されています。
このキーワードの値は、フォーマット属性と呼ばれます。これは文字列でなければなりません。フォーマット属性は、一般的に特定のインスタンスタイプの集合のみを検証できます。検証するインスタンスの型がこの集合にない場合、このフォーマット属性とインスタンスの検証は成功するはずです。このセクションで定義されているすべてのフォーマット属性は文字列に適用されますが、コアJSONスキーマで定義されているデータモデルで定義されている任意のインスタンスタイプに適用されるようにフォーマット属性を指定できます。[CREF1]この仕様の"type"キーワードは、データモデルの一部ではない"integer"型を定義していることに注意してください。したがって、フォーマット属性は数値に限定できますが、整数に限定することはできません。ただし、数値フォーマットは"type"キーワードと値"integer"と共に使用するか、数値が整数でない場合は常に合格するように明示的に定義できます。これにより、整数にのみ適用する場合と本質的に同じ動作が得られます。
フォーマットアノテーション語彙として知られるこの語彙の現在のURIは、<https://json-schema.dokyumento.jp/draft/2020-12/vocab/format-annotation>です。対応するメタスキーマの現在のURIは、<https://json-schema.dokyumento.jp/draft/2020-12/meta/format-annotation>です。この語彙のサポートの実装は必須です。
"format"をアサーションとして定義するカスタムメタスキーマのための二次語彙も用意されています。フォーマットアサーション語彙のURIは、<https://json-schema.dokyumento.jp/draft/2020-12/vocab/format-assertion>です。対応するメタスキーマの現在のURIは、<https://json-schema.dokyumento.jp/draft/2020-12/meta/format-assertion>です。フォーマットアサーション語彙のサポートの実装はオプションです。
フォーマットアノテーション語彙とフォーマットアサーション語彙の両方を指定することは、その要件がフォーマットアノテーション語彙のスーパーセットであるため、フォーマットアサーション語彙のみを指定することと機能的に同等です。
"format"キーワードは、参照されている語彙によって定義されているように機能します。
実装がアノテーションの収集をサポートしている場合、「format」の値はアノテーションとして収集**しなければなりません**。これにより、スキーマ検証が利用できない場合や不十分な場合でも、アプリケーションレベルでの検証が可能になります。
実装は、「format」をアノテーションに加えてアサーションとして扱い、指定されたセマンティクスへの値の適合性を検証しようとすることも**できます**。実装は、そのような評価の有効化と無効化のオプションを提供**しなければならず**、デフォルトでは無効化されてい**なければなりません**。実装は、そのような検証に対するサポートレベルを文書化**するべきです**。[CREF2]Format-Annotation語彙の指定と実装での検証の有効化は、Format-Assertion語彙の指定と同等とは見なされません。なぜなら、実装はFormat-Assertion語彙が指定されていない場合、完全な検証サポートを提供する必要がないからです。
実装がアサーション動作に設定されている場合、[CREF3]これは、実装の現状と一致しています。実装では、いくつかの、またはすべてフォーマット属性に対して、まったく検証しない場合も含め、幅広いレベルの検証が提供されています。これはまた、アノテーション動作のみに依存し、アプリケーションでセマンティック検証を実行することを推奨するベストプラクティスを促進することを目的としています。
Format-Assertion語彙がtrueの値で宣言されている場合、実装は、この仕様で定義されているすべてのフォーマットに対して完全な検証サポートを提供**しなければなりません**。完全な検証サポートを提供できない実装は、スキーマの処理を拒否**しなければなりません**。
多くの属性に関連する複雑さのために、フォーマット属性の最小限の検証の要件は意図的に曖昧で許容範囲が広いものです。特に、要件は構文チェックに限定されていることに注意してください。実装が電子メールを送信したり、URLへの接続を試みたり、フォーマットインスタンスによって識別されるエンティティの存在を確認したりすることは期待されていません。
実装は、各フォーマットに対して共通の構文解析ライブラリ、またはよく知られている正規表現を使用することを**推奨します**。実装は、各フォーマット属性がどのように、そしてどの程度検証されるかを明確に文書化する**べきです**。
デフォルトでは実装はこれをアサーションとしてサポートする必要がないため、標準のコアおよび検証メタスキーマは、その"$vocabulary"キーワードにfalseの値を使用してこの語彙を含んでいます。trueの値でformat語彙をサポートすることは、コードサイズを大幅に増加させ、場合によっては実行時間を増加させることが理解されており、すべての実装に適しているわけではありません。
実装は、カスタムフォーマット属性をサポート**できます**。当事者間の合意を除き、スキーマ作成者は、ピア実装がそのようなカスタムフォーマット属性をサポートすることを期待してはいけません。実装は、未知のフォーマットをアノテーションとして収集することに失敗してはいけません。Format-Assertion語彙が指定されている場合、実装は未知のフォーマットに遭遇したときに失敗**しなければなりません**。
語彙は、キーワードに対して異なる値セットを具体的に宣言することをサポートしていません。この制限と、このキーワードのこれまで不均一な実装のために、相互運用性を求める場合は、追加のフォーマット属性ではなく、カスタム語彙に追加のキーワードを定義することを**推奨します**。
これらの属性は文字列インスタンスに適用されます。
日付と時刻のフォーマット名は、RFC 3339、セクション5.6から派生しています。期間フォーマットは、RFC 3339の付録Aに記載されているISO 8601 ABNFからのものです。
フォーマットをサポートする実装は、次の属性のサポートを実装**するべきです**
実装は、そのRFCのどこかに定義されている他のプロダクション名を使用して、追加の属性をサポート**できます**。「full-date」または「full-time」が実装されている場合、対応する短縮形（それぞれ「date」または「time」）を実装**しなければならず**、同じように動作**しなければなりません**。実装は、そのプロダクションのルールに従って検証しない限り、RFC 3339プロダクションと一致する名前を持つ拡張属性を定義してはいけません。[CREF5]現在、すべてのRFC 3339フォーマットをサポートする必要性に関するコンセンサスはありません。そのため、名前空間を予約するこのアプローチは、セット全体にコミットすることなく実験を促進します。フォーマット実装の要件は一般的により柔軟になるか、これらは完全に指定された属性に昇格されるか、削除される可能性が高いです。
これらの属性は文字列インスタンスに適用されます。
文字列インスタンスは、以下のとおり有効なインターネット電子メールアドレスである場合、これらの属性に対して有効です。
「email」属性に対して有効なすべての文字列は、「idn-email」属性に対しても有効であることに注意してください。
これらの属性は文字列インスタンスに適用されます。
文字列インスタンスは、以下のとおり有効なインターネットホスト名の表現である場合、これらの属性に対して有効です。
「hostname」属性に対して有効なすべての文字列は、「idn-hostname」属性に対しても有効であることに注意してください。
これらの属性は文字列インスタンスに適用されます。
文字列インスタンスは、以下のとおり有効なIPアドレスの表現である場合、これらの属性に対して有効です。
これらの属性は文字列インスタンスに適用されます。
有効なURIはすべて有効なIRIであり、有効なURI参照はすべて有効なIRI参照でもあることに注意してください。
また、「uuid」フォーマットはプレーンなUUID用であり、URN内のUUID用ではないことに注意してください。例：「f81d4fae-7dec-11d0-a765-00a0c91e6bf6」。URNとしてのUUIDには、「uri」フォーマットを使用し、「pattern」正規表現に「^urn:uuid:」を指定して、URIスキームとURN名前空間を示します。
この属性は文字列インスタンスに適用されます。
文字列インスタンスは、[RFC6570]に従って有効なURIテンプレート（任意のレベル）である場合、この属性に対して有効です。
URIテンプレートはIRIに使用できることに注意してください。個別のIRIテンプレート仕様はありません。
これらの属性は文字列インスタンスに適用されます。
絶対JSONポインタと相対JSONポインタの両方を許可するには、「anyOf」または「oneOf」を使用して、どちらかのフォーマットのサポートを示します。
この属性は文字列インスタンスに適用されます。
正規表現。これはECMA-262正規表現方言に従って有効である**べきです**。
フォーマットを検証する実装は、この仕様の正規表現セクションで定義されているECMA-262のサブセットを少なくとも受け入れる**必要があり**、すべての有効なECMA-262式を受け入れる**べきです**。
このセクションで定義されているアノテーションは、インスタンスがJSON文字列にエンコードされた非JSONデータを含んでいることを示しています。
これらのプロパティは、JSONデータをリッチマルチメディアドキュメントとして解釈するために必要な追加情報を提供します。それらは、コンテンツの種類、エンコード方法、および/または検証方法を記述します。それらは検証アサーションとして機能しません。形式が正しくない文字列エンコードドキュメントは、含まれているインスタンスが無効と見なされる原因になってはいけません。
"$vocabulary"を使用しないメタスキーマは、そのURIがtrueの値で存在するかのように、この語彙を必要とするものと見なすべきです。
この語彙（コンテンツ語彙として知られている）の現在のURIは次のとおりです。<https://json-schema.dokyumento.jp/draft/2020-12/vocab/content>。
対応するメタスキーマの現在のURIは次のとおりです。<https://json-schema.dokyumento.jp/draft/2020-12/meta/content>。
セキュリティとパフォーマンスに関する懸念事項、および考えられるコンテンツタイプのオープンエンドな性質のために、実装はデフォルトで文字列の内容を自動的にデコード、解析、および/または検証してはいけません。これはさらに、含んでいるドキュメントを処理したものとは異なるコンシューマによる処理を目的とした埋め込みドキュメントの使用例をサポートします。
このセクションのすべてのキーワードは文字列のみに適用され、他のデータ型には影響しません。
実装は、文字列の内容を自動的にデコード、解析、および/または検証する機能を提供してもよい。ただし、これらの操作をデフォルトでは実行してはならず、各文字列エンコードされたドキュメントの検証結果を、上位ドキュメントとは別に提供しなければならない。このプロセスは、インスタンスを元のスキーマに対して完全に評価し、その後にアノテーションを使用して各文字列エンコードされたドキュメントをデコード、解析、および/または検証する処理と同等であるべきである。[CREF6]現時点では、このような自動デコード、解析、および検証機能からの解析済みデータおよび/または検証結果を実行および返すための正確なメカニズムは未定義である。この機能が普及した場合、将来のドラフトでより詳細に規定される可能性がある。
インスタンス文字列をこれらのキーワードに従って自動的に処理することによって導入される可能性のある脆弱性については、セキュリティに関する考慮事項のセクションも参照のこと。
インスタンスの値が文字列の場合、このプロパティは、その文字列をバイナリデータとして解釈し、このプロパティで指定されたエンコーディングを使用してデコードする必要があることを定義する。
いくつかのバリエーションを持つbase 16、32、および64エンコーディングを示す可能性のある値は、RFC 4648にリストされている。さらに、RFC 2045の6.7節と6.8節には、MIMEで使用されるエンコーディングが記載されている。「base64」は両方のRFCで定義されているため、文字列がMIMEコンテキストで使用されることを意図していない限り、RFC 4648からの定義を採用すべきである。これらのエンコーディングはすべて、7ビットASCII文字のみからなる文字列になることに注意。したがって、このキーワードは、その範囲外の文字を含む文字列には意味を持たない。
このキーワードが存在せず、「contentMediaType」が存在する場合は、エンコーディングが同一性エンコーディングであることを示す。つまり、コンテンツをUTF-8文字列で表現するために変換は必要なかったことを意味する。
このプロパティの値は文字列でなければならない。
インスタンスが文字列の場合、このプロパティは文字列の内容のメディアタイプを示す。「contentEncoding」が存在する場合は、デコードされた文字列を記述する。
このプロパティの値は文字列でなければならず、RFC 2046で定義されているように、メディアタイプでなければならない。
インスタンスが文字列であり、「contentMediaType」が存在する場合は、このプロパティに文字列の構造を記述するスキーマが含まれる。
このキーワードは、JSONスキーマのデータモデルにマップできるメディアタイプで使用できる。
このプロパティの値は有効なJSONスキーマでなければならない。「contentMediaType」が存在しない場合は無視されるべきである。
ここに、「contentEncoding」と「contentMediaType」の使用を示すスキーマの例を示す。
{
"type": "string",
"contentEncoding": "base64",
"contentMediaType": "image/png"
}
このスキーマで記述されるインスタンスは文字列であることが期待され、その値はbase64エンコードされたPNG画像として解釈可能であるべきである。
別の例
{
"type": "string",
"contentMediaType": "text/html"
}
このスキーマで記述されるインスタンスは、JSON文字列がデコードされた文字セットを使用するHTMLを含む文字列であることが期待される。RFC 8259の8.1節に従って、完全に閉じたシステム以外では、これはUTF-8でなければならない。
この例は、HMAC SHA-256アルゴリズムを使用してMACされたJWTを記述しており、そのクレームセットに「iss」フィールドと「exp」フィールドを必要とする。
{
"type": "string",
"contentMediaType": "application/jwt",
"contentSchema": {
"type": "array",
"minItems": 2,
"prefixItems": [
{
"const": {
"typ": "JWT",
"alg": "HS256"
}
},
{
"type": "object",
"required": ["iss", "exp"],
"properties": {
"iss": {"type": "string"},
"exp": {"type": "integer"}
}
}
]
}
}
「contentEncoding」は表示されないことに注意。「application/jwt」メディアタイプはbase64urlエンコーディングを使用するが、それはメディアタイプによって定義されており、JWT文字列が2つのJSONデータ構造のリストにデコードされる方法を決定する。最初のヘッダー、そしてペイロード。JWTメディアタイプはJWTをJSON文字列で表現できることを保証するため、さらにエンコードまたはデコードする必要はない。
これらの汎用アノテーションキーワードは、ドキュメントおよびユーザーインターフェースの表示目的で一般的に使用される情報を提供する。それらは、機能の包括的なセットを形成することを意図していない。むしろ、より複雑なアノテーションベースのアプリケーションのために、追加のボキャブラリを定義することができる。
"$vocabulary"を使用しないメタスキーマは、そのURIがtrueの値で存在するかのように、この語彙を必要とするものと見なすべきです。
メタデータボキャブラリとして知られるこのボキャブラリの現在のURIは、次のとおりである。<https://json-schema.dokyumento.jp/draft/2020-12/vocab/meta-data>。
対応するメタスキーマの現在のURIは次のとおりである。<https://json-schema.dokyumento.jp/draft/2020-12/meta/meta-data>。
これらのキーワードの値は両方とも文字列でなければならない。
これらのキーワードは両方とも、このユーザーインターフェースによって生成されたデータに関する情報を用いてユーザーインターフェースを装飾するために使用できる。タイトルは短くするのが好ましく、説明は、このスキーマによって記述されるインスタンスの目的について説明する。
このキーワードの値には制限がない。このキーワードの複数回出現が単一のサブインスタンスに適用される場合、実装は重複を削除する必要がある。
このキーワードは、特定のスキーマに関連付けられたデフォルトのJSON値を提供するために使用できる。デフォルト値は、関連付けられたスキーマに対して有効であることが推奨される。
このキーワードの値はブール値でなければならない。このキーワードの複数回出現が単一のサブインスタンスに適用される場合、アプリケーションは、いずれかの出現がtrueの値を指定している場合、インスタンスの場所が廃止されたと見なす必要がある。
"deprecated"の値がブール値trueの場合、アプリケーションは宣言されたプロパティの使用を控える必要があることを示す。将来、プロパティが削除される可能性があることを意味する可能性がある。
trueの値を持つ"deprecated"を含むルートスキーマは、記述されているリソース全体が将来削除される可能性があることを示す。
"deprecated"キーワードは、キーワードを含むスキーマオブジェクトが正常に適用される各インスタンスの場所に適用される。これにより、包含する配列またはオブジェクトが廃止されていなくても、すべての配列アイテムまたはオブジェクトプロパティが廃止されるシナリオが発生する可能性がある。
このキーワードを省略した場合、値falseと同じ動作になります。
これらのキーワードの値はブール値でなければならない。これらのキーワードの複数回出現が単一のサブインスタンスに適用される場合、結果の動作は、いずれかの出現がtrueの値を指定している場合はtrueの値の場合と同じであり、それ以外の場合はfalseの値の場合と同じであるべきである。
"readOnly"の値がブール値trueの場合、インスタンスの値は所有権を持つ機関によって排他的に管理され、アプリケーションがプロパティの値を変更しようとしても、その所有権を持つ機関によって無視または拒否されることが期待されることを示す。
ドキュメント全体について"readOnly"としてマークされているインスタンスドキュメントは、所有権を持つ機関に送信された場合、無視されるか、機関の裁量でエラーが発生する可能性がある。
"writeOnly"の値がブール値trueの場合、インスタンスが所有権を持つ機関から取得されたときに値が存在しないことを示す。所有権を持つ機関にドキュメント（またはそれが表すリソース）を更新または作成するために送信されたときに存在する可能性があるが、インスタンスの更新または新規作成されたバージョンには含まれない。
ドキュメント全体について"writeOnly"としてマークされているインスタンスドキュメントは、何らかの空のドキュメントとして返されるか、取得時にエラーが発生するか、機関の裁量で取得要求が無視される可能性がある。
例として、"readOnly"はデータベース生成の通し番号を読み取り専用としてマークするために使用され、"writeOnly"はパスワード入力フィールドをマークするために使用される。
これらのキーワードは、ユーザーインターフェースインスタンスの生成を支援するために使用できる。特に、アプリケーションは、書き込み専用フィールドに入力値が入力されるときに、入力値を非表示にするウィジェットを使用することを選択できる。
これらのキーワードを省略すると、falseの値と同じ動作になる。
このキーワードの値は配列でなければならない。配列内の値には制限がない。このキーワードの複数回出現が単一のサブインスタンスに適用される場合、実装は配列の配列ではなく、すべての値のフラットな配列を提供しなければならない。
このキーワードは、使用方法を示す目的で、特定のスキーマに関連付けられたサンプルJSON値を提供するために使用できる。これらの値は、関連付けられたスキーマに対して有効であることが推奨される。
実装は、存在する場合は"default"の値を追加の例として使用してもよい。"examples"が存在しない場合でも、"default"はこのように使用してもよい。
JSONスキーマの検証は、JSONスキーマコアのボキャブラリを定義し、そこにリストされているすべてのセキュリティに関する考慮事項に関係する。
JSONスキーマの検証では正規表現の使用が可能であり、正規表現には多数の異なる（多くの場合互換性のない）実装が存在する。一部の実装では任意のコードを埋め込むことが可能だが、これはJSONスキーマの範囲外であり、許可してはならない。正規表現は多くの場合、非常に計算コストの高いもの（いわゆる「カタストロフィックバックトラッキング」）を作成することもでき、サービス拒否攻撃につながる可能性がある。
"contentEncoding"および/または"contentMediaType"に基づいてインスタンス文字列データを検証または評価する機能をサポートする実装は、誤った情報に基づいて安全でない方法でデータを評価するリスクがある。アプリケーションは、スキーマとインスタンス間の関係が確立されている場合（例：同じ権限を共有する）にのみそのような処理を実行することで、このリスクを軽減できる。
メディアタイプまたはエンコーディングの処理は、そのメディアタイプまたはエンコーディングのセキュリティに関する考慮事項の影響を受ける。たとえば、RFC 4329 スクリプトメディアタイプのセキュリティに関する考慮事項は、JSON文字列内にエンコードされたJavaScriptまたはECMAScriptを処理する場合に適用される。
| [RFC4329] | Hoehrmann, B.、「Scripting Media Types」、RFC 4329、DOI 10.17487/RFC4329、2006年4月。 |
このドラフトの時点では、いくつかのキーワードがこのドキュメントからコア仕様に移動されており、場合によっては名前の変更やその他の変更が行われています。これは、以下の以前の検証キーワードに影響します。
JSON Schemaの初期ドラフトに取り組んでいただいたGary Court、Francis Galiegue、Kris Zyp、およびGeraint Luffに感謝いたします。
このドキュメントへの提出物とパッチを提供していただいたJason Desrosiers、Daniel Perrett、Erik Wilde、Evgeny Poberezkin、Brad Bowman、Gowry Sankar、Donald Pipowitch、Dave Finlay、Denis Laxalde、Phil Sturgeon、Shawn Silverman、およびKaren Etheridgeに感謝いたします。
[CREF7]インターネットドラフトのステータスを離れる前に、このセクションを削除する必要があります。