元派遣プログラマの自称技術系ブログです。雑記とか自作のオープンソースプロジェクトの話とか。
Javaとか組込とかできます。お仕事ください。

json-schema-coreのメモ

JSON Schema: A Media Type for Describing JSON Documents

全然わからんので必要なところだけ拾い読み。

1. Introduction

2. Conventions and Terminology

3. Overview

4. Definitions

4.1. JSON Document

4.2. Instance

4.2.1. Instance Data Model

4.2.2. Instance Equality

4.2.3. Non-JSON Instances

4.3. JSON Schema Documents

4.3.1. JSON Schema Objects and Keywords

インスタンスに適用されるオブジェクトプロパティは、キーワードまたはスキーマキーワードと呼ばれます。大まかに言えば、キーワードは次の5つのカテゴリのいずれかに分類されます。

  • identifiers:スキーマの正規URIを設定したり、ベースURIの決定方法を変更したりして、スキーマの識別を制御します。
  • annotations:インスタンスに適用するとブール結果を生成します
  • annotations:アプリケーションで使用するためにインスタンスに情報を添付する
  • applicators:インスタンス内の特定の場所に1つ以上のサブスキームを適用し、それらの結果を結合または変更します
  • reserved locations:結果に直接影響を与えることはありませんが、相互運用性を確保するために特定の目的のための場所を予約してください

キーワードは複数のカテゴリに分類される場合がありますが、applicatorsはサブスキーマの結果に基づいてアサーション結果のみを生成する必要があります。サブスキームとは関係なく、追加の制約を定義するべきではありません。

同じスキーマオブジェクト内のプロパティであるキーワードは、隣接キーワードと呼ばれます。

拡張キーワード、つまりこのドキュメントとそのコンパニオンの外部で定義されているキーワードは、他の動作も自由に定義できます。

JSONスキーマには、スキーマキーワードではないプロパティが含まれる場合があります。不明なキーワードはannotationsとして扱われるべきであり、キーワードの値はannotationsの値です。

空のスキーマは、プロパティがないか、不明なプロパティのみを持つJSONスキーマです。

4.3.2. Boolean JSON Schemas

4.3.3. Schema Vocabularies

4.3.4. Meta-Schemas

4.3.5. Root Schema and Subschemas and Resources

5. Fragment Identifiers

6. General Considerations

6.1. Range of JSON Values

6.2. Programming Language Independence

6.3. Mathematical Integers

6.4. Regular Expressions

6.5. Extending JSON Schema

7. Keyword Behaviors

7.1. Lexical Scope and Dynamic Scope

7.2. Keyword Interactions

7.3. Default Behaviors

7.4. Identifiers

7.5. Applicators

7.5.1. Referenced and Referencing Schemas

7.6. Assertions

7.6.1. Assertions and Instance Primitive Types

7.7. Annotations

7.7.1. Collecting Annotations

7.8. Reserved Locations

7.9. Loading Instance Data

8. The JSON Schema Core Vocabulary

このセクションで宣言されているキーワードは、すべて"$"で始まり、JSON Schema Coreの語彙を構成しています。これらのキーワードは、複数のドキュメントに分割されたものも含め、あらゆるスキーマやメタスキーマを処理するために必要なもの、または、相互運用性を保証する必要がある目的のためにキーワードを確保するために存在するものです。

コア・ボキャブラリーは、他のボキャブラリーの処理を起動するために、常に必須とみなされなければなりません(MUST)。メタスキーマが「$vocabulary」キーワードを使用して使用中の語彙を宣言する場合、Core語彙を明示的にリストアップしなければなりません(必須であることを示すtrueの値を持たなければなりません)。

「$vocabulary」キーワードを使用していないメタスキーマは、そのURIがtrueの値で存在するかのように、コア・ボキャブラリーを必要としていると考えなければなりません(MUST)。

The current URI for the Core vocabulary is: https://json-schema.org/draft/2020-12/vocab/core.
The current URI for the corresponding meta-schema is: https://json-schema.org/draft/2020-12/meta/core.

コア・ボキャブラリーでは「$」というプレフィックスは正式には予約されていませんが、将来の衝突を避けるために、(ボキャブラリーやその他の)拡張キーワードは「$」以外の文字で始めることが推奨されています。

8.1. Meta-Schemas and Vocabularies

8.1.1. The "$schema" Keyword

8.1.2. The "$vocabulary" Keyword

8.1.3. Updates to Meta-Schema and Vocabulary URIs

8.2. Base URI, Anchors, and Dereferencing

8.2.1. The "$id" Keyword

キーワード "$id" は、スキーマ・リソースをその正規の URI で識別します。

この URI は識別子であり、必ずしもネットワークロケータではないことに注意してください。ネットワークアドレスを示すURLである場合、スキーマはその正規のURIからダウンロードできなくてもよい。

この値が存在する場合、値は文字列でなければならず(MUST)、有効な URI-reference を表さなければならない(MUST)。このURI-referenceは正規化されるべきであり(SHOULD)、(フラグメントを含まない)absolute-URIに解決しなければならない(MUST)。したがって、「$id」は空でないフラグメントを含んではならず、空のフラグメントを 含むべきではない(SHOULD NOT)。

application/schema+jsonメディアタイプのコンテキストにおける空のフラグメントは、フラグメントのないベースURIと同じリソースを参照するので、実装はフラグメントを削除することで、空のフラグメントで終わるURIを正規化してもよい(MAY)。しかし,スキーマ作成者は,実装間でのこの動作に依存すべきではない(SHOULD NOT)。[CREF3].

このURIは,コンテンツに埋め込まれたベースURIに関するRFC3986のセクション5.1.1に従い,スキーマリソース内のキーワードにおける相対URI参照のベースURIとしても機能する。

サブスキーマに「$id」が存在することは、そのサブスキーマが単一のスキーマ文書内の別個のスキーマリソースを構成していることを示す。さらに、実体のカプセル化に関する

RFC 3986 の 5.1.2 節に従い、サブスキーマ内の "$id" が相対 URI 参照の場合、その参照を解決するためのベース URI は親スキーマリソースの URI となる。

スキーマオブジェクトが「$id」を持つリソースとして明示的に識別されない場合、ベースとなるURIは、前節の手順で確立されたドキュメント全体のURIとなる。

8.2.2. Defining location-independent identifiers

8.2.3. Schema References

8.2.3.1. Direct References with "$ref"

「$ ref」キーワードは、静的に識別されたスキーマを参照するために使用されるアプリケーターです。 その結果は、参照されたスキーマの結果です。 [CREF5]

「$ ref」キーワードの値は、URI参照である文字列でなければなりません。 現在のURIベースに対して解決され、適用するスキーマURIを生成します。 インスタンスを評価するプロセスでは参照の解決方法を変更できないため、この解決はスキーマのロード時に安全に実行できます。

8.2.4. Schema Re-Use With "$defs"

キーワード "$defs" は、スキーマ作成者が再利用可能な JSON スキーマをより一般的なスキーマにインライン化するための場所を確保します。このキーワードは、検証結果に直接影響を与えるものではありません。

このキーワードの値は、オブジェクトでなければなりません (MUST)。このオブジェクトの各メンバー値は、有効なJSONスキーマでなければなりません(MUST)。

例として、正の整数の配列を記述するスキーマを示します。正の整数の制約は、"$defs" のサブスキーマです。

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

8.3. Comments With "$comment"

9. Loading and Processing Schemas

9.1. Loading a Schema

9.1.1. Initial Base URI

9.1.2. Loading a referenced schema

9.1.3. Detecting a Meta-Schema

9.2. Dereferencing

9.2.1. JSON Pointer fragments and embedded schema resources

9.3. Compound Documents

9.3.1. Bundling

9.3.2. Differing and Default Dialects

9.3.3. Validating

9.4. Caveats

9.4.1. Guarding Against Infinite Recursion

9.4.2. References to Possible Non-Schemas

9.5. Associating Instances and Schemas

9.5.1. Usage for Hypermedia

10. A Vocabulary for Applying Subschemas

10.1. Keyword Independence

スキーマキーワードは通常、互いの結果に影響を与えることなく、独立して機能します。

スキーマ作成者の便宜のために、この語彙のキーワードにはいくつかの例外があります。

  • 「additionalProperties」。その動作は「properties」と「patternProperties」で定義されます。
  • 「items」。その動作は「prefixItems」で定義されます。
  • 「contains」、その動作は「minContains」で定義されます

10.2. Keywords for Applying Subschemas in Place

これらのキーワードは、親スキーマが適用されているのと同じインスタンス内の同じ場所にサブスキーマを適用します。 サブスキーマの結果をさまざまな方法で組み合わせたり変更したりできます。

これらのキーワードのサブスキーマは、インスタンスを完全に独立して評価するため、そのようなサブスキーマの1つの結果が、兄弟のサブスキーマの結果に影響を与えてはなりません。 したがって、サブスキームは任意の順序で適用できます。

10.2.1. Keywords for Applying Subschemas With Logic

これらのキーワードは、サブスキーマの評価assertionsの結果を結合または変更するための論理演算子に対応します。 これらは、同じアノテーションキーワードを異なる値を持つインスタンスの場所に適用できるようにしますが、アノテーションコレクションに直接影響を与えることはありません。 注釈キーワードは、そのような値を組み合わせるための独自のルールを定義します。

10.2.1.2. anyOf

このキーワードの値は、空でない配列でなければなりません。 配列の各項目は、有効なJSONスキーマである必要があります。

インスタンスは、このキーワードの値で定義された少なくとも1つのスキーマに対して正常に検証される場合、このキーワードに対して正常に検証されます。 注釈が収集されているときは、すべてのサブスキーマを調べて、検証が正常に行われた各サブスキーマから注釈が収集されるようにする必要があることに注意してください。

10.2.1.3. oneOf

このキーワードの値は、空でない配列でなければなりません。配列の各項目は、有効なJSONスキーマである必要があります。

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

10.2.1.4. not

このキーワードの値は、有効なJSONスキーマである必要があります。

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

10.2.2. Keywords for Applying Subschemas Conditionally

10.3. Keywords for Applying Subschemas to Child Instances

10.3.1. Keywords for Applying Subschemas to Arrays

10.3.2. Keywords for Applying Subschemas to Objects

11. A Vocabulary for Unevaluated Locations

11.1. Keyword Independence

11.2. unevaluatedItems

11.3. unevaluatedProperties

12. Output Formatting

12.1. Format

12.2. Output Formats

12.3. Minimum Information

12.3.1. Keyword Relative Location

12.3.2. Keyword Absolute Location

12.3.3. Instance Location

12.3.4. Error or Annotation

12.3.5. Nested Results

12.4. Output Structure

出力は、「valid」という名前のブールプロパティを含むオブジェクトである必要があります。 結果に関する追加情報が必要な場合、以下に説明するように、出力には「エラー」またはannotations」も含まれている必要があります。

12.4.1. Flag

  • valid -全体的な検証の成功または失敗を示すブール値
  • errors -失敗した検証によって生成されたエラーまたは注釈のコレクション
  • annotations-検証が成功したことによって生成されたエラーまたは注釈のコレクション

これらの例では、次のスキーマインスタンスが使用されます。

{
  "$id": "https://example.com/polygon",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "point": {
      "type": "object",
      "properties": {
        "x": { "type": "number" },
        "y": { "type": "number" }
      },
      "additionalProperties": false,
      "required": [ "x", "y" ]
    }
  },
  "type": "array",
  "items": { "$ref": "#/$defs/point" },
  "minItems": 3
}

[
  {
    "x": 2.5,
    "y": 1.3
  },
  {
    "x": 1,
    "z": 6.7
  }
]

このインスタンスは検証に失敗してエラーを生成しますが、アノテーションを生成するスキーマを渡すための例を推測するのは簡単です。

具体的には、生成されるエラーは次のとおりです。

  1. 2番目のオブジェクトには「y」プロパティがありません。
  2. 2番目のオブジェクトには、許可されていない「z」プロパティがあります。
  3. オブジェクトは2つだけですが、3つ必要です。

これらの例に示されているエラーメッセージの文言は、この仕様の要件ではないことに注意してください。 実装は、オーディエンスに合わせたエラーメッセージを作成するか、ユーザーが独自のメッセージを作成できるようにするテンプレートメカニズムを提供する必要があります。

12.4.2. Basic

12.4.3. Detailed

12.4.4. Verbose

12.4.5. Output validation schemas

13. Security Considerations

14. IANA Considerations

14.1. application/schema+json

14.2. application/schema-instance+json

15. References

15.1. Normative References

15.2. Informative References

Appendix A. Schema identification examples

Appendix B. Manipulating schema documents and references

B.1. Bundling schema resources into a single document

B.2. Reference removal is not always safe

Appendix C. Example of recursive schema extension

Appendix D. Working with vocabularies

D.1. Best practices for vocabulary and meta-schema authors

D.2. Example meta-schema with vocabulary declarations

Appendix E. References and generative use cases

Appendix F. Acknowledgments

Appendix G. ChangeLog

Authors' Addresses