JSON Schema: JSONドキュメントを記述するためのメディアタイプ

概要

JSON Schemaは、JSONデータの構造を記述するためのJSONベースの形式であるメディアタイプ "application/schema+json" を定義します。JSON Schemaは、JSONドキュメントがどのような外観でなければならないか、そこから情報を抽出する方法、およびそれと対話する方法を主張します。"application/schema-instance+json" メディアタイプは、"application/json" ドキュメントに対して提供できるものを超えて、"application/schema+json" との追加の機能豊富な統合を提供します。¶

1. はじめに

JSON Schemaは、JSONデータの構造を定義するためのJSONメディアタイプです。JSON Schemaは、JSONデータの検証、ドキュメント化、ハイパーリンクナビゲーション、およびインタラクション制御を定義することを目的としています。¶

この仕様では、参照による別のJSON Schemaへのポインティング、JSON Schema参照の逆参照、使用されているダイアレクトの指定、ダイアレクトの語彙要件の指定、および期待される出力の定義など、JSON Schemaのコア用語とメカニズムを定義します。¶

他の仕様では、検証、リンク、アノテーション、ナビゲーション、およびインタラクションに関するアサーションを実行する語彙を定義します。¶

2. 規約と用語

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

このドキュメントにおける用語 "JSON", "JSON text", "JSON value", "member", "element", "object", "array", "number", "string", "boolean", "true", "false", および "null" は、RFC 8259 [RFC8259]で定義されているように解釈されるものとします。¶

3. 概要

このドキュメントでは、JSONデータを記述するためのJSON Schemaを識別する新しいメディアタイプ "application/schema+json" を提案します。また、追加の統合機能を提供するために、さらにオプションのメディアタイプ "application/schema-instance+json" を提案します。JSON Schema自体はJSONドキュメントです。この仕様および関連仕様では、著者がJSONデータをいくつかの方法で記述できるキーワードを定義します。¶

JSON Schemaは、キーワードを使用してJSONインスタンスに制約をアサートしたり、それらのインスタンスに追加情報をアノテーションしたりします。追加のキーワードは、より複雑なJSONデータ構造に、または何らかの条件に基づいて、アサーションとアノテーションを適用するために使用されます。¶

再利用を容易にするために、キーワードは語彙に整理できます。語彙は、構文とセマンティクスとともに、キーワードのリストで構成されます。ダイアレクトは、メタスキーマで識別される、語彙のセットとその必要なサポートとして定義されます。¶

JSON Schemaは、追加の語彙を定義するか、語彙の外に追加のキーワードをあまり正式でない方法で定義することによって拡張できます。認識されない個々のキーワードは、アノテーションとして値を収集するだけですが、どの語彙が使用中であるかを宣言するときに、認識されない語彙に関する動作を制御できます。¶

このドキュメントでは、任意の実装でサポートする必要があり、無効にできないコア語彙を定義します。そのキーワードは、必要な性質を強調するために、それぞれ "$" 文字でプレフィックスが付けられます。この語彙は、"application/schema+json" メディアタイプの機能に不可欠であり、他の語彙の読み込みをブートストラップするために使用されます。¶

さらに、このドキュメントでは、サブスキーマを条件付きで適用するため、およびオブジェクトと配列の内容にサブスキーマを適用するためのキーワードの推奨語彙を定義します。この語彙または非常によく似た語彙は、アサーション検証、アノテーション、またはその両方を目的としているかどうかにかかわらず、非自明なJSONインスタンスのスキーマを作成するために必要です。必須のコア語彙の一部ではありませんが、最大限の相互運用性を実現するために、この追加語彙はこのドキュメントに含まれており、その使用が強く推奨されます。¶

構造検証やハイパーメディアアノテーションなどの目的のための追加の語彙は、他のドキュメントで定義されています。これらの他のドキュメントはそれぞれ、そのドキュメントの目的にスキーマを記述するために必要な標準的な語彙セットを収集するダイアレクトを定義します。¶

4. 定義

{
    "title": "root",
    "items": {
        "title": "array item"
    }
}

6. 一般的な考慮事項

7. キーワードの動作

JSONスキーマのキーワードは、いくつかの一般的な動作カテゴリに分類されます。アサーションは、インスタンスが制約を満たしていることを検証し、ブール値を生成します。注釈は、アプリケーションが適切と判断する方法で使用できる情報を添付します。アプ​​リケーターは、インスタンスの一部にサブスキーマを適用し、その結果を結合します。¶

拡張キーワードは、特に注釈が非常に柔軟であることを念頭に置いて、これらのカテゴリ内に留まる必要があります。複雑な動作は通常、スキーマキーワードとして直接実装するよりも、注釈データに基づいてアプリケーションに委任する方が適切です。ただし、拡張キーワードは、特殊な目的のために他の動作を定義してもかまいません。¶

スキーマに対するインスタンスの評価には、インスタンス内の適切な場所に対して、スキーマ内のすべてのキーワードを処理することが含まれます。通常、アプ​​リケーターキーワードは、アプ​​リケーター（したがってサブスキーマがない）を持たないスキーマオブジェクトに到達するまで処理されます。インスタンス内の適切な場所は、スキーマオブジェクト内のアサーションおよび注釈キーワードに対して評価され、それらの結果は、アプ​​リケーターのルールに従って親スキーマに収集されます。¶

親スキーマオブジェクトの評価は、そのすべてのサブスキーマが評価された後に完了できますが、状況によっては、アサーションの結果により評価が途中で打ち切られる場合があります。注釈を収集する場合、アサーションの結果をさらに変更できないサブスキーマを含め、すべてのサブスキーマを調べる必要があるため、アサーション結果の途中で打ち切ることはできません。¶

{
    "type": ["string", "null"],
    "maxLength": 255
}

{
    "title": "Feature list",
    "type": "array",
    "prefixItems": [
        {
            "title": "Feature A",
            "properties": {
                "enabled": {
                    "$ref": "#/$defs/enabledToggle",
                    "default": true
                }
            }
        },
        {
            "title": "Feature B",
            "properties": {
                "enabled": {
                    "description": "If set to null, Feature B
                                    inherits the enabled
                                    value from Feature A",
                    "$ref": "#/$defs/enabledToggle"
                }
            }
        }
    ],
    "$defs": {
        "enabledToggle": {
            "title": "Enabled",
            "description": "Whether the feature is enabled (true),
                            disabled (false), or under
                            automatic control (null)",
            "type": ["boolean", "null"],
            "default": null
        }
    }
}

{
    "oneOf": [
        {
            "title": "Integer Value",
            "type": "integer"
        },
        {
            "title": "String Value",
            "type": "string"
        }
    ]
}

8. JSON Schemaコア語彙

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

コア語彙は、他の語彙の処理をブートストラップするために、常に必須と見なす必要があります。使用する語彙を宣言するために"$vocabulary" (8.1項)キーワードを使用するメタスキーマは、コア語彙を明示的にリストする必要があります。コア語彙は、必須であることを示すtrueの値を持つ必要があります。¶

この語彙（およびこの語彙のみ）のfalse値の動作は未定義であり、"$vocabulary" が存在してもコア語彙が含まれていない場合の動作は未定義です。ただし、実装では、これらのケースを検出し、発生したときにエラーを発生させることを推奨します。メタスキーマがオプションでコアを使用することを宣言することは意味がありません。¶

"$vocabulary" を使用しないメタスキーマは、URIがtrueの値で存在する場合と同様に、コア語彙を必要とすると見なす必要があります。¶

コア語彙の現在のURIは次のとおりです。<https://json-schema.dokyumento.jp/draft/2020-12/vocab/core>。¶

対応するメタスキーマの現在のURIは次のとおりです。https://json-schema.dokyumento.jp/draft/2020-12/meta/core。¶

コア語彙に対して "$" プレフィックスが正式に予約されているわけではありませんが、拡張キーワード（語彙内またはその他の場合）は、将来の衝突の可能性を回避するために "$" 以外の文字で開始することを推奨します。¶

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

9. スキーマのロードと処理

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

{
    "$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": { }
}

        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. サブスキーマを適用するための語彙

このセクションでは、他の語彙の基礎として使用することが推奨されるアプリケーターキーワードの語彙を定義します。¶

"$vocabulary"を使用しないメタスキーマは、そのURIがtrueの値で存在する場合と同様に、この語彙を必要とすると見なされるべきです。¶

アプリケーター語彙として知られる、この語彙の現在のURIは次のとおりです。<https://json-schema.dokyumento.jp/draft/2020-12/vocab/applicator>。¶

対応するメタスキーマの現在のURIは、https://json-schema.dokyumento.jp/draft/2020-12/meta/applicatorです。¶

11. 未評価の場所のための語彙

これらのキーワードの目的は、スキーマ作成者が、隣接するキーワードの動的スコープのサブスキーマによって正常に評価されなかった配列項目またはオブジェクトプロパティにサブスキーマを適用できるようにすることです。¶

これらのインスタンス項目またはプロパティは、「anyOf」のブランチ内のアサーションが失敗した場合など、1つ以上の隣接するキーワードサブスキーマに対して評価が失敗している可能性があります。このような失敗した評価は、項目またはプロパティが評価されたかどうかの判断には考慮されません。成功した評価のみが考慮されます。¶

配列内の項目またはオブジェクトプロパティが「正常に評価」された場合、それは論理的に、期待されるオブジェクトまたは配列の表現に関して有効であると見なされます。たとえば、サブスキーマが2〜4個の車輪を必要とする車を表しており、「wheels」の値が6の場合、インスタンスオブジェクトは車であると「評価」されず、「wheels」プロパティは「評価されていない（既知のものとして成功）」と見なされ、注釈を保持しません。¶

隣接するキーワードは同じスキーマオブジェクト内のキーワードであり、動的スコープのサブスキーマには、字句サブスキーマだけでなく参照ターゲットも含まれることを思い出してください。¶

これらのキーワードの動作は、検証されるインスタンスの場所に適用される隣接するキーワードの注釈結果に依存します。¶

「$vocabulary」を使用しないメタスキーマは、そのURIがtrueの値で存在するかのように、この語彙を必要とすると見なす必要があります。¶

Unevaluated Applicator語彙として知られる、この語彙の現在のURIは次のとおりです： <https://json-schema.dokyumento.jp/draft/2020-12/vocab/unevaluated>。¶

対応するメタスキーマの現在のURIは次のとおりです： https://json-schema.dokyumento.jp/draft/2020-12/meta/unevaluated。¶

14. IANAに関する考慮事項

15. 参考文献

付録 B. スキーマ ドキュメントと参照の操作

参照 ("$ref") がどのように、どこに現れるかに基づいて、スキーマ ドキュメントを再配置するためにさまざまなツールが作成されてきました。この付録では、この仕様に準拠しているユースケースとアクションについて説明します。¶

付録 D. ボキャブラリの操作

{
  "$schema": "https://json-schema.dokyumento.jp/draft/2020-12/schema",
  "$id": "https://example.com/meta/general-use-example",
  "$dynamicAnchor": "meta",
  "$vocabulary": {
    "https://json-schema.dokyumento.jp/draft/2020-12/vocab/core": true,
    "https://json-schema.dokyumento.jp/draft/2020-12/vocab/applicator": true,
    "https://json-schema.dokyumento.jp/draft/2020-12/vocab/validation": true,
    "https://example.com/vocab/example-vocab": true
  },
  "allOf": [
    {"$ref": "https://json-schema.dokyumento.jp/draft/2020-12/meta/core"},
    {"$ref": "https://json-schema.dokyumento.jp/draft/2020-12/meta/applicator"},
    {"$ref": "https://json-schema.dokyumento.jp/draft/2020-12/meta/validation"},
    {"$ref": "https://example.com/meta/example-vocab"}
  ],
  "patternProperties": {
    "^unevaluated": false
  },
  "properties": {
    "localKeyword": {
      "$comment": "Not in vocabulary, but validated if used",
      "type": "string"
    }
  }
}

{
  "$schema": "https://json-schema.dokyumento.jp/draft/2020-12/schema",
  "$id": "https://example.com/meta/example-vocab",
  "$dynamicAnchor": "meta",
  "$vocabulary": {
    "https://example.com/vocab/example-vocab": true,
  },
  "type": ["object", "boolean"],
  "properties": {
    "minDate": {
      "type": "string",
      "pattern": "\d\d\d\d-\d\d-\d\d",
      "format": "date",
    }
  }
}

付録 E. 参照と生成的なユースケース

参照の存在は検証結果に対して透過的であることが期待されますが、コードジェネレーターやUIレンダラーなどの生成的なユースケースでは、参照がセマンティック的に重要であると見なされることがよくあります。¶

このようなユースケース固有のセマンティクスを明示的にするために、ベストプラクティスは、"$ref" などの参照キーワードと並行して、同じスキーマオブジェクトで使用するためのアノテーションキーワードを作成することです。¶

たとえば、これは、コードジェネレーターが参照ターゲットを別のクラスと見なすべきかどうか、およびそれらのクラスがどのように関連しているかを判断するための架空のキーワードです。この例は説明のみを目的としており、機能的なコード生成キーワードを提案することを意図したものではないことに注意してください。¶

{
    "allOf": [
        {
            "classRelation": "is-a",
            "$ref": "classes/base.json"
        },
        {
            "$ref": "fields/common.json"
        }
    ],
    "properties": {
        "foo": {
            "classRelation": "has-a",
            "$ref": "classes/foo.json"
        },
        "date": {
            "$ref": "types/dateStruct.json",
        }
    }
}

ここで、このスキーマは、ある種のオブジェクト指向クラスを表します。"allOf" の最初の参照は、基本クラスとして示されています。2番目の参照にはクラス関係が割り当てられていないため、コードジェネレーターは、参照が関与していないかのように、ターゲットの定義をこの定義と結合する必要があります。¶

プロパティを見ると、"foo" はオブジェクトコンポジションとしてフラグが立てられていますが、"date" プロパティはそうではありません。これは、別のクラスのインスタンスではなく、サブフィールドを持つ単なるフィールドです。¶

このスタイルの使用法では、アノテーションは参照と同じオブジェクト内にある必要があり、参照として認識可能である必要があります。¶

付録 F. 謝辞

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 の各氏に感謝いたします。¶

付録 G. 変更履歴

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

draft-bhutton-json-schema-01

• "type"、"contains"、"unevaluatedProperties"、および "unevaluatedItems" キーワードの説明を改善および明確化しました¶
• "正規URI" のさまざまな側面を明確化しました¶
• アノテーションと "additionalProperties" に関するあいまいさについてコメントしました¶
• ボキャブラリーは正式に定義する必要はないことを明確化しました¶
• 残りのメディアタイプパラメーターへの参照を削除しました¶
• 複数の例を修正しました¶

draft-bhutton-json-schema-00

• "$schema" は、埋め込まれたリソースに対して変更される可能性があります¶
• 配列値の "items" 機能は、現在 "prefixItems" です¶
• "items" は、"additionalItems" の古い機能を包含します¶
• "contains" アノテーションの動作、および "contains" と "unevaluatedItems" の相互作用が指定されました¶
• $recursive* を $dynamic* に名前変更し、動作を変更しました¶
• $dynamicAnchor は、$anchor のようにフラグメントを定義します¶
• $dynamic*（以前は $recursive）は、ランタイムベースURIの決定を使用しなくなりました¶
• 複合スキーマドキュメント（バンドル）とその処理を定義しました¶
• 正規表現のサポートについては、ECMA-262、第11版を参照してください¶
• 正規表現はユニコードをサポートする必要があります¶
• メディアタイプパラメーターを削除しました¶
• 不明なキーワードはアノテーションとして収集されることを指定しました¶
• "unevaluatedItems" および "unevaluatedProperties" をコアから独自のボキャブラリーに移動しました¶

draft-handrews-json-schema-02

• JSON仕様については、RFC 8259に更新しました¶
• "definitions" を検証仕様からここ "$defs" に移動しました¶
• アプリケーターキーワードを検証仕様から独自のボキャブラリーとして移動しました¶
• "dependencies" のスキーマ形式を検証仕様から "dependentSchemas" に移動しました¶
• アノテーションの収集を正式化しました¶
• 推奨される出力形式を指定しました¶
• アノテーションとアサーションの結果に関してキーワードの相互作用を定義しました¶
• "unevaluatedProperties" と "unevaluatedItems" を追加しました¶
• アサーション、アプリケーター、およびアノテーションモデルに関して "$ref" の動作を定義します¶
• "$ref" に隣接するキーワードを許可します¶
• 不明なキーワードを含む "$ref" ターゲットの未定義の動作に注意してください¶
• 主にメタスキーマ拡張のための再帰参照の追加¶
• 形式的な語彙の概念と、メタスキーマを通じてそれらを認識する方法の追加¶
• ネットワーク検索を超えた初期ベース URI に関する追加ガイダンス¶
• "application/schema+json" の "schema" メディアタイプパラメーターの許可¶
• メディアタイプパラメーターと HTTP Accept ヘッダーに関するより良い説明¶
• "$id" を使用して、正規およびベースの絶対 URI のみを確立し、フラグメントは含めない¶
• "$id" のプレーンな名前フラグメントのみの形式を "$anchor" に置き換え¶
• "$id" の境界を越えた JSON ポインターの動作が信頼できないことを明確化¶

draft-handrews-json-schema-01

• このドラフトは機能的な変更を伴わない、純粋な明確化です¶
• JSON スキーマの主要な使用法としてアノテーションを強調¶
• ユースケースによる $id の明確化¶
• 包括的なスキーマ識別の例¶
• 「外部参照」を、実装が別のドキュメントからスキーマをいつ、どのように知るかという説明に置き換え¶
• 「内部参照」を、実装が解析中にスキーマ識別子をどのように認識すべきかの説明に置き換え¶
• 以前の「内部」または「外部」参照の逆参照は、常に同じプロセスです¶
• 軽微なフォーマットの改善¶

draft-handrews-json-schema-00

• スキーマキーワード語彙の概念をより明確にする¶
• 「integer」の概念は、データモデルではなく語彙からのものであることに注意する¶
• キーワードをアサーションまたはアノテーションとして分類し、それらの一般的な動作を説明する¶
• 一般的なアサーションの観点からブールスキーマを説明する¶
• スキーマに関するユーザーには見えないメモ用に "$comment" を予約する¶
• "$id" とフラグメントに関する表現の改善¶
• 再帰参照によるメタスキーマ拡張の課題に言及する¶
• "application/schema-instance+json" メディアタイプを追加する¶
• 「profile」の代わりに「schema」リンク関係/パラメーターを推奨する¶

draft-wright-json-schema-01

• イントロの更新¶
• 任意のスキーマをブール値にできるようにする¶
• "$schema" はサブスキーマに現れるべきではありませんが、変更される可能性があります¶
• "id" を "$id" に変更。すべてのコアキーワードの先頭に "$" を付加¶
• application/schema+json のフラグメントを明確化および形式化¶
• JSON データモデルで表現できる CBOR などのフォーマットへの適用性に言及¶

draft-wright-json-schema-00

• JSON への参照の更新¶
• HTTP への参照の更新¶
• JSON ポインターへの参照の更新¶
• "id" の動作が RFC3986 の観点で指定されるようになった¶
• URI の語彙使用を RFC3986 と整合させた¶
• draft-pbryan-zyp-json-ref-03 への参照を削除¶
• スキーマが期待される場所に "$ref" の使用を制限¶
• "JSON スキーマデータモデル" の定義を追加¶
• 追加のセキュリティに関する考慮事項を追加¶
• "id" のサブスキーマ識別子の使用を定義¶
• HTTP での使用に関するセクションを書き直し¶
• rel="describedBy" および rel="profile" での使用に関するセクションを書き直し¶
• 多数の無効な例を修正¶

draft-zyp-json-schema-04

• ドラフト v3 から回収¶
• 検証キーワードを別のドキュメントに分割¶
• ハイパーメディアキーワードを別のドキュメントに分割¶
• 分割後の最初のドラフト¶
• JSON リファレンス、JSON ポインターの使用を義務付け¶
• "id" の役割を定義。URI解決スコープを定義¶
• 相互運用性に関する考慮事項を追加¶

draft-zyp-json-schema-00

• 最初のドラフト¶