JSON Schema: JSON文書を記述するためのメディアタイプ

4.1. JSON文書

JSON文書とは、application/jsonメディアタイプによって記述される情報リソース （オクテット列）です。¶

JSON Schemaでは、それが定義するデータモデルのため、"JSON document"、 "JSON text"、および"JSON value"という用語は相互に置き換え可能です。¶

JSON SchemaはJSON文書の上でのみ定義されます。ただし、JSON Schemaデータ モデルに解析できる、またはそのモデルに従って処理できる任意の文書またはメモリ 構造は、JSON Schemaに照らして解釈できます。これには、 CBOR [RFC7049]のようなメディアタイプも含まれます。¶

4.2. インスタンス

スキーマが適用されるJSON文書は、「インスタンス」と呼ばれます。¶

JSON Schemaは、"application/json"または互換性のある文書の上で定義されます。 これには"+json"構造化構文接尾辞を持つメディアタイプが含まれます。¶

これらの中で、この仕様は、URI内のフラグメントの扱いを定義する "application/schema-instance+json"メディアタイプを定義します。¶

6.1. JSON値の範囲

インスタンスは、JSON [RFC8259]で定義される任意の有効なJSON値であり得ます。 JSON Schemaは型に制限を課しません。JSON Schemaは、例えばnullを含む任意のJSON 値を記述できます。¶

7.2. キーワードの相互作用

キーワードの振る舞いは、サブスキーマ（セクション 4.3.5）および/または隣接キーワード （同じスキーマオブジェクト内のキーワード）とそのサブスキーマの 注釈結果の観点で定義されてもかまいません。 そのようなキーワードは循環依存を引き起こしてはなりません。 キーワードは、同じ スキーマオブジェクト（セクション4.3）内の別のキーワードの有無に基づいて、 その振る舞いを変更してもかまいません。¶

7.3. 既定の振る舞い

欠落しているキーワードは、偽のアサーション結果を生成してはならず、 注釈結果を生成してはならず、また自身の振る舞い定義の一部として 他のスキーマを評価させてはなりません。 ただし、欠落しているキーワードは注釈に寄与しないため、 注釈結果がないことが、他のキーワードの振る舞いを間接的に 変える場合があります。¶

場合によっては、キーワードが欠落しているときのアサーションの振る舞いが、 特定の値によって生成される振る舞いと同一であり、キーワード定義は 既知の場合にはそのような値を記載すべきです。ただし、既定の振る舞いを 生成する値が、存在する場合には注釈結果を生成するとしても、 既定の振る舞いは注釈を結果として生じてはなりません。¶

注釈収集は計算量とメモリの両方に大きなコストを加える可能性があるため、 実装はこの機能を選択しないことができます。 収集された注釈の観点で規定されるキーワードは、適切な場合には 妥当な代替手法を説明すべきです。 この手法は、この文書の "items"および "additionalProperties"キーワードで示されています。¶

なお、あるキーワードについてそのような代替手法が不可能な場合、 注釈収集をサポートしない実装は、それらのキーワードまたはそれらを含む語彙を サポートできません。¶

7.4. 識別子

識別子はスキーマのURIを定義するか、 参照（セクション8.2.3）においてそのようなURIが どのように解決されるかに影響を与えるか、またはその両方を行います。 この文書で定義されるCore語彙は、いくつかの 識別キーワードを定義しており、特に"$id"が重要です。¶

正準スキーマURIはインスタンスの処理中に変わってはなりませんが、 URI-referenceの解決に影響するキーワードは、その振る舞いが 実行時にのみ完全に決定される場合があります。¶

カスタム識別子キーワードは可能ですが、語彙設計者は コアキーワードの機能を妨げないよう注意すべきです。例えば、 この仕様の"$dynamicAnchor"キーワードは、そのURI解決効果を 一致する"$dynamicRef"キーワードに限定し、"$ref"の振る舞いを 妨げません。¶

7.8. 予約済み位置

4番目のカテゴリのキーワードは、単に再利用可能なコンポーネントや、 スキーマ作成者にとって関心のあるが再利用には適さないデータを保持する位置を 予約します。これらのキーワードは検証結果または注釈結果に影響しません。 コア語彙におけるその目的は、特定の目的のために位置が 利用可能であり、拡張キーワードによって再定義されないことを確保することです。¶

これらのキーワードは結果に直接影響しませんが、セクション 9.4.2で説明されているように、 再利用可能なスキーマのために位置を予約する認識されない 拡張キーワードは、特定の状況では参照と望ましくない相互作用を起こす場合があります。¶

7.9. インスタンスデータの読み込み

この文書または関連文書の一部として定義される語彙のいずれも、 インスタンスデータを対象にしたり読み込んだりできるキーワードを定義していませんが、 他の語彙がそれを望む可能性はあります。¶

キーワードは、現在の評価位置の外にあるインスタンスの一部を調べるために、 JSON PointerまたはRelative JSON Pointerを使用するよう定義されてもかまいません。¶

Relative JSON Pointerを使用して位置を調整できるキーワードは、 既定値が望ましい場合、現在位置を使用することを既定とすべきです。¶

8.2. 基底URI、アンカー、 逆参照

膨大なエコシステム内でスキーマを区別するため、 スキーマはURI [RFC3986]によって識別され、 そのURIを指定することによって他のスキーマへの参照を埋め込むことができます。¶

いくつかのキーワードは、相対URI-reference [RFC3986]、 または相対URI-referenceを構築するために使用される値を受け入れることができます。 これらのキーワードでは、参照を解決するために基底URIを確立する必要があります。¶

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

8.3. "$comment"によるコメント

このキーワードは、スキーマ作成者からスキーマの読者または保守者へのコメントのための 位置を予約します。¶

このキーワードの値は文字列でなければなりません。実装はこの文字列を エンドユーザーに提示してはなりません。スキーマ編集用ツールは、このキーワードの表示と 編集をサポートすべきです。このキーワードの値は、スキーマを利用する開発者を 対象としたデバッグまたはエラー出力で使用してもかまいません。¶

スキーマ語彙は、語彙キーワードを含む任意のオブジェクト内で"$comment"を許可すべきです。 実装は、語彙がそれを明示的に禁止しない限り、"$comment"が許可されていると 仮定してもかまいません。語彙は、この仕様で説明されているものを超えて "$comment"のいかなる効果も指定してはなりません。¶

他のメディアタイプまたはプログラミング言語をapplication/schema+jsonへ、または application/schema+jsonから変換するツールは、そのメディアタイプまたは プログラミング言語のネイティブコメントを"$comment"値へ、または"$comment"値から 変換することを選択してもかまいません。ネイティブコメントと"$comment" プロパティの両方が存在する場合のそのような変換の振る舞いは実装依存です。¶

実装は、処理中の任意の時点で"$comment"値を削除してもかまいません。 特に、これにより、配備されるスキーマのサイズが問題となる場合に スキーマを短縮できます。¶

実装は、"$comment"プロパティの存在、不在、または内容に基づいて 他のいかなる動作も行ってはなりません。特に、"$comment"の値は 注釈結果として収集されてはなりません。¶

9.1. スキーマの読み込み

9.2. 逆参照

スキーマは、それに与えられた任意のURIによって識別できます。これには、 JSON Pointerや"$id"によって直接与えられたURIが含まれます。すべての場合において、 "$ref"参照を逆参照することは、まずその値を現在の基底URIに対して URI参照として RFC 3986 [RFC3986]に従って解決することを伴います。¶

結果としてのURIが現在の文書内、または実装に利用可能にされた 別のスキーマ文書内のスキーマを識別する場合、そのスキーマは 自動的に使用されるべきです。¶

例えば、次のスキーマを考えてください。¶

{
    "$id": "https://example.net/root.json",
    "items": {
        "type": "array",
        "items": { "$ref": "#item" }
    },
    "$defs": {
        "single": {
            "$anchor": "item",
            "type": "object",
            "additionalProperties": { "$ref": "other.json" }
        }
    }
}

実装が<#/$defs/single>スキーマに遭遇すると、 "$anchor"値を現在の基底URIに対するフラグメント名として解決し、 <https://example.net/root.json#item>を形成します。¶

次に実装が<#/items>スキーマの内部を見ると、 <#item>参照に遭遇し、これを <https://example.net/root.json#item>へ解決します。これは同じ文書内で定義済みとして 見ているため、自動的に使用できます。¶

実装が"other.json"への参照に遭遇すると、 これを<https://example.net/other.json>へ解決しますが、これはこの 文書内では定義されていません。その識別子を持つスキーマが別途実装に供給されている場合、 それも自動的に使用できます。 参照されるスキーマが不明な場合、実装はどうすべきでしょうか。 自動的なネットワーク逆参照が許可される状況はあるでしょうか。 同一オリジンポリシーでしょうか。ユーザー設定可能なオプションでしょうか。 Hyper-Schemaで記述される進化するAPIの場合、新しいスキーマがシステムに 動的に追加されることが想定されるため、スキーマ文書を事前に読み込むという 絶対要件を置くことは現実的ではありません。 ¶

{
    "$id": "https://example.com/foo",
    "items": {
        "$id": "https://example.com/bar",
        "additionalProperties": { }
    }
}

{
    "$id": "https://example.com/foo",
    "items": {
        "$ref": "bar"
    }
}

{
    "$id": "https://example.com/bar",
    "additionalProperties": { }
}

9.3. 複合文書

複合スキーマ文書は、輸送を容易にするために複数の埋め込みJSON Schemaリソースを 同じ文書内にまとめたJSON文書（「バンドルされた」スキーマと呼ばれることもあります）として 定義されます。¶

各埋め込みスキーマリソースは、語彙サポートの決定を含む標準的なスキーマ読み込みおよび 処理要件に従って、個別のスキーマリソースとして扱われなければなりません。¶

9.4. 注意点

9.5. インスタンスと スキーマの関連付け

        Link: <https://example.com/my-hyper-schema>; rel="describedby"

        User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0

10.1. キーワードの独立性

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

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

• "properties"および"patternProperties"の観点で振る舞いが定義される "additionalProperties"¶
• "prefixItems"の観点で振る舞いが定義される"items"¶
• Validation語彙における"minContains"の存在と値によって振る舞いが影響される "contains"¶

10.3. 子インスタンスに サブスキーマを適用するキーワード

これらの各キーワードは、サブスキーマを子インスタンス、具体的にはオブジェクトの プロパティおよび配列項目に適用し、その結果を結合するための規則を定義します。¶

11.1. キーワードの独立性

スキーマキーワードは通常、互いの結果に影響を与えることなく 独立して動作します。ただし、この語彙内のキーワードは 注目すべき例外です。¶

• "prefixItems"、"items"、"contains"、およびそれ自身からの 注釈の観点で振る舞いが定義される"unevaluatedItems"¶
• "properties"、"patternProperties"、 "additionalProperties"、およびそれ自身からの注釈の観点で 振る舞いが定義される"unevaluatedProperties"¶

14.1. application/schema+json

JSON Schemaのために提案されるMIMEメディアタイプは、次のように定義されます。¶

• 型名: application¶
• サブタイプ名: schema+json¶
• 必須パラメーター: N/A¶
• エンコーディングに関する考慮事項: エンコーディングに関する考慮事項は、 "application/json"メディアタイプに対して指定されたものと同一です。 JSON [RFC8259]を参照してください。¶
• セキュリティ上の考慮事項: 上記のセクション 13を参照してください。¶
• 相互運用性に関する考慮事項: 上記のセクション 6.2、 6.3、および 6.4を参照してください。¶
• フラグメント識別子に関する考慮事項: セクション 5を参照してください。¶

14.2. application/schema-instance+json

JSON Schema固有のメディアタイプを必要とするJSON Schemaインスタンスのために 提案されるMIMEメディアタイプは、次のように定義されます。¶

• 型名: application¶
• サブタイプ名: schema-instance+json¶
• 必須パラメーター: N/A¶
• エンコーディングに関する考慮事項: エンコーディングに関する考慮事項は、 "application/json"メディアタイプに対して指定されたものと同一です。 JSON [RFC8259]を参照してください。¶
• セキュリティ上の考慮事項: 上記のセクション 13を参照してください。¶
• 相互運用性に関する考慮事項: 上記のセクション 6.2、 6.3、および 6.4を参照してください。¶
• フラグメント識別子に関する考慮事項: セクション 5を参照してください。¶

15.1. 規定参考文献

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <https://www.rfc-editor.org/info/rfc3986>.

[RFC6839]

Hansen, T. and A. Melnikov, "Additional Media Type Structured Syntax Suffixes", RFC 6839, DOI 10.17487/RFC6839, January 2013, <https://www.rfc-editor.org/info/rfc6839>.

[RFC6901]

Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, April 2013, <https://www.rfc-editor.org/info/rfc6901>.

[RFC8259]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/info/rfc8259>.

[W3C.REC-ldp-20150226]

Speicher, S., Arwe, J., and A. Malhotra, "Linked Data Platform 1.0", World Wide Web Consortium Recommendation REC-ldp-20150226, 26 February 2015, <https://www.w3.org/TR/2015/REC-ldp-20150226>.

[ecma262]

"ECMA-262, 11th edition specification", June 2020, <https://www.ecma-international.org/ecma-262/11.0/index.html>.

15.2. 参考情報文献

[RFC6596]

Ohye, M. and J. Kupke, "The Canonical Link Relation", RFC 6596, DOI 10.17487/RFC6596, April 2012, <https://www.rfc-editor.org/info/rfc6596>.

[RFC7049]

Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 2013, <https://www.rfc-editor.org/info/rfc7049>.

[RFC7231]

Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, <https://www.rfc-editor.org/info/rfc7231>.

[RFC8288]

Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, October 2017, <https://www.rfc-editor.org/info/rfc8288>.

[W3C.WD-fragid-best-practices-20121025]

Tennison, J., "Best Practices for Fragment Identifiers and Media Type Definitions", World Wide Web Consortium WD WD-fragid-best-practices-20121025, 25 October 2012, <https://www.w3.org/TR/2012/WD-fragid-best-practices-20121025>.

[json-schema-validation]

Wright, A., Andrews, H., and B. Hutton, "JSON Schema Validation: A Vocabulary for Structural Validation of JSON", Work in Progress, Internet-Draft, draft-bhutton-json-schema-validation-01, June 2022, <https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-01>.

[json-hyper-schema]

Andrews, H. and A. Wright, "JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON", Work in Progress, Internet-Draft, draft-handrews-json-schema-hyperschema-02, November 2017, <https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-hyperschema-02>.

[xml-names]

Bray, T., Ed., Hollander, D., Ed., Layman, A., Ed., and R. Tobin, Ed., "Namespaces in XML 1.1 (Second Edition)", August 2006, <http://www.w3.org/TR/2006/REC-xml-names11-20060816>.

B.1. スキーマリソースを 単一の文書にバンドルする

一緒に使用することを意図したスキーマリソースの集合は、 それぞれが独自のスキーマ文書にある形、すべてが同じスキーマ文書にある形、 またはその中間の任意の粒度の文書グループ化で編成できます。¶

参照除去のさまざまな種類を実行するための多くのツールが存在します。 その一般的なケースは、すべての参照をそのファイル内で解決できる 単一ファイルを生成することです。これは通常、配布を簡素化するため、 またはJSON Schemaライブラリのさまざまな呼び出しが大量のリソースを 追跡して読み込む必要がないよう、コーディングを簡素化するために行われます。¶

この変換は、すべての静的参照（例: "$ref"）が、正準リソースURIを 基底として使用するURIへ解決されるURI参照を使用し、かつすべてのスキーマ リソースがそのルートスキーマ内の"$id"としてabsolute-URIを持つ限り、 安全かつ可逆的に行うことができます。¶

これらの条件が満たされていれば、各外部リソースは"$defs"の下に コピーでき、リソースのスキーマオブジェクト間の参照を壊すことなく、 また検証または注釈結果のいかなる側面も変更せずに済みます。 "$defs"の下のスキーマ名は、それぞれが一意であると仮定すれば、 埋め込みリソースの正準URIには現れないため、振る舞いに影響しません。¶

B.2. 参照の除去は 常に安全とは限らない

すべての参照を除去して単一のスキーマ文書を生成しようとしても、 すべての場合において、元の形式と同一の振る舞いを持つスキーマが 生成されるわけではありません。¶

"$ref"は現在、他のキーワードと同様に扱われ、同じスキーマオブジェクト内で 他のキーワードが許可されているため、すべての場合に非再帰的な"$ref"除去を 完全にサポートするには、比較的複雑なスキーマ操作が必要になる場合があります。 安全な"$ref"除去変換の集合を決定または提供することは、この仕様の範囲外です。 それらはスキーマ構造だけでなく、意図された使用方法にも依存するためです。¶

D.1. 語彙および メタスキーマ作成者のためのベストプラクティス

語彙作成者は、その語彙が広範な使用を意図し、 かつ他の語彙と組み合わせられる可能性がある場合、キーワード名の衝突を 避けるよう注意すべきです。JSON Schemaは形式的な名前空間システムを 提供しませんが、キーワード名も制約しないため、任意の数の 名前空間化アプローチを可能にします。¶

語彙は、別の語彙のキーワードの振る舞いに関して自身のキーワードの 振る舞いを定義したり、別の語彙のキーワードを許容値の集合を 制限または拡張して使用したりするなど、互いに基づいて構築できます。 そのようなすべての語彙再利用が、その基になる語彙と互換性のある 新しい語彙を生じるとは限りません。語彙作成者は、どの程度の互換性が 期待されるのか、もしあれば、それを明確に文書化すべきです。¶

メタスキーマ作成者は、同じキーワードに対して競合する構文または意味論を 定義する複数の語彙を組み合わせるために"$vocabulary"を使用すべきではありません。 意味論的な競合は一般にスキーマ検証を通じて検出できないため、 実装にそのような競合の検出は期待されません。競合する語彙が宣言された場合、 結果としての振る舞いは未定義です。¶

語彙作成者は、その語彙のキーワードの期待される使用方法を 単独で検証するメタスキーマを提供すべきです。そのようなメタスキーマは 追加キーワードを禁止すべきではなく、Core語彙のいかなる キーワードも禁止してはなりません。¶

メタスキーマ作成者は、各語彙のメタスキーマを "allOf"（セクション10.2.1.1）キーワードを使用して 参照することが推奨されますが、特定のユースケースでは メタスキーマを構築する他の仕組みが適切である場合もあります。¶

メタスキーマの再帰的な性質により、"$dynamicAnchor"および"$dynamicRef"キーワードは、 Validationメタスキーマを拡張するJSON Hyper-Schemaメタスキーマに見られるように、 既存のメタスキーマを拡張するために特に有用です。¶

メタスキーマは、宣言された語彙に関連付けられたメタスキーマが記述する内容を超えて、 追加の制約を課してもかまいません。これには、どの語彙にも存在しない キーワードを記述することも含まれます。これにより、語彙のサブセットへの 使用制限や、再利用を意図しないローカルに定義されたキーワードの検証が可能になります。¶

ただし、メタスキーマは、語彙が期待するものとは異なるJSON型を要求するなど、 自身が宣言するいかなる語彙とも矛盾すべきではありません。 結果としての振る舞いは未定義です。¶

任意の実装における語彙サポートをテストする必要がない、 ローカル使用を意図したメタスキーマは、"$vocabulary"を完全に省略しても 安全です。¶