| インターネット技術タスクフォース | F. Galiegue 編 |
| インターネットドラフト | |
| 予定ステータス：参考情報 | K. Zyp 編 |
| 期限切れ：2017年8月26日 | SitePen (米国) |
| G. Court | |
| 2013 |
JSON スキーマ：コア定義と用語
draft-zyp-json-schema-04
JSON スキーマは、JSON データの構造を定義するための JSON ベースのフォーマットであるメディアタイプ "application/schema+json" を定義します。JSON スキーマは、特定のアプリケーションに必要な JSON データとその使用方法に関する契約を提供します。JSON スキーマは、JSON データの検証、ドキュメント化、ハイパーリンク ナビゲーション、およびインタラクション制御を定義することを目的としています。
このインターネットドラフトは、BCP 78 および BCP 79 の規定に完全に準拠して提出されています。
インターネットドラフトは、インターネット技術タスクフォース (IETF) の作業文書です。他の団体もインターネットドラフトとして作業文書を配布することに注意してください。現在のインターネットドラフトのリストは、http://datatracker.ietf.org/drafts/current/にあります。
インターネットドラフトは、最大6ヶ月有効なドラフト文書であり、いつでも他の文書によって更新、置換、または廃止される可能性があります。「作業中」以外の参考資料として使用したり、引用したりすることは適切ではありません。
このインターネットドラフトは、2017年8月26日に期限切れになります。
Copyright (c) 2013 IETF Trust および文書の著者として特定された個人。全著作権所有。
この文書は、BCP 78 およびこの文書の公開日に有効な IETF Trust のIETF ドキュメントに関する法的規定 (http://trustee.ietf.org/license-info) の対象となります。これらの文書は、この文書に関するあなたの権利と制限を記述しているため、注意深く確認してください。この文書から抽出されたコードコンポーネントには、Trust 法的規定のセクション 4.e に記載されている簡略化された BSD ライセンステキストを含める必要があり、簡略化された BSD ライセンスに記載されているように、保証なしで提供されます。
JSON スキーマは、JSON データの構造を定義するための JSON メディアタイプです。JSON スキーマは、特定のアプリケーションに必要な JSON データとその使用方法に関する契約を提供します。JSON スキーマは、JSON データの検証、ドキュメント化、ハイパーリンク ナビゲーション、およびインタラクション制御を定義することを目的としています。
この仕様書では、JSON スキーマのコア用語とメカニズムを定義します。関連する仕様書は、この仕様書に基づいて構築され、JSON スキーマのさまざまなアプリケーションを定義します。
この文書におけるキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC 2119 [RFC2119]に記載されているように解釈されます。
この文書における用語「JSON」、「JSON テキスト」、「JSON 値」、「メンバ」、「要素」、「オブジェクト」、「配列」、「数値」、「文字列」、「ブール値」、「true」、「false」、「null」は、RFC 4627 [RFC4627]に定義されているように解釈されます。
[RFC4627]で定義されている JSON オブジェクトを参照する場合、「メンバ」と「プロパティ」という用語は互換的に使用できます。
[RFC4627]で定義されている JSON 配列を参照する場合、「要素」と「項目」という用語は互換的に使用できます。
JSON スキーマは JSON ドキュメントであり、そのドキュメントはオブジェクトである必要があります。JSON スキーマ（この仕様書または関連する仕様書）によって定義されたオブジェクトメンバ（またはプロパティ）は、キーワードまたはスキーマキーワードと呼ばれます。
JSON スキーマには、スキーマキーワードではないプロパティを含めることができます。
空スキーマとは、プロパティがないか、スキーマキーワードではないプロパティを持つ JSON スキーマです。
この JSON スキーマの例には、サブスキーマがありません。
{
"title": "root"
}
JSON スキーマは、この例のようにネストすることもできます。
{
"title": "root",
"otherSchema": {
"title": "nested",
"anotherSchema": {
"title": "alsoNested"
}
}
}
この例では、「nested」と「alsoNested」はサブスキーマであり、「root」はルートスキーマです。
JSON スキーマは、JSON 値の7つのプリミティブ型を定義します。
2つの JSON 値は、次の場合にのみ等しいと言われます。
インスタンスは任意の JSON 値です。インスタンスは、1つ以上のスキーマによって記述される場合があります。
インスタンスは、「JSON インスタンス」または「JSON データ」と呼ばれることもあります。
この文書は、JSON データの記述のための JSON スキーマを識別するための新しいメディアタイプ「application/schema+json」を提案します。JSON スキーマ自体は JSON で記述されています。これと関連する仕様書は、許容値、テキストの説明、および他のリソースとの関係の解釈という観点からこのデータを記述することを可能にするキーワードを定義しています。以降のセクションは、関連する仕様書によって定義された機能の概要です。
JSON スキーマを使用すると、アプリケーションはインタラクティブにまたはインタラクティブでない方法でインスタンスを検証できます。たとえば、アプリケーションは JSON データを収集し、このデータが特定の制約セットに一致することを確認できます。別のアプリケーションは、JSON スキーマを使用して、JSON スキーマによって記述された制約に従ってユーザー入力収集のためのインタラクティブインターフェースを構築できます。
JSON スキーマは、インスタンスから他のリソースへのリンク関係を抽出する方法と、インスタンスをマルチメディアデータとして解釈する方法を提供します。これにより、JSON データは、より大きな関連リソースのセットのコンテキスト内に配置された、リッチなハイパーメディアドキュメントとして解釈できます。
[RFC4627]で定義されているように、インスタンスが任意の有効な JSON 値になる可能性があることは認められています。そのため、JSON スキーマはインスタンスが特定の型であることを義務付けていません。JSON スキーマは、null を含む任意の JSON 値を記述できます。
JSON スキーマは、プログラミング言語に依存しません。[RFC4627]で示されている制限と、ホストプログラミング言語の制限のみが適用されます。
この仕様書は、インターネットで使用されている主要なプロトコルとしての HTTP [RFC2616] の役割と、それに関連する豊富な公式仕様書を認めています。
この仕様書は、これらの仕様書のサブセットを使用して、このプロトコルで使用できるメカニズムのセットを推奨し、JSON インスタンスを1つ以上のスキーマに関連付けます。
JSON スキーマは、HTTP 以外のプロトコルについて、クライアントサーバーインターフェースのセマンティクスを定義しません。これらのセマンティクスは、アプリケーション依存であるか、JSON スキーマを独自のニーズに使用することに関与する当事者間の合意の対象となります。
この仕様書では、一部のプログラミング言語とその関連するパーサーが、浮動小数点数と整数の異なる内部表現を使用する一方、他の言語は使用しないことを認めています。
その結果、相互運用性の理由から、JSONスキーマのコンテキストで使用されるJSON値（JSONスキーマまたはインスタンスのいずれであっても）は、この仕様で定義されている整数として数学的整数を表現する必要があります。
実装では、JSONスキーマに追加のキーワードを定義することを選択できます。明示的な合意がない限り、スキーマ作成者は、これらの追加キーワードがピア実装でサポートされると想定してはなりません。実装は、サポートしていないキーワードを無視する必要があります。
スキーマとインスタンスの両方ともJSON値です。そのため、RFC 4627 [RFC4627]で定義されているすべてのセキュリティに関する考慮事項が適用されます。
"$schema"キーワードは、JSONスキーマのバージョン識別子と、この特定のバージョンに対して記述されたスキーマを記述するリソースの場所の両方として使用されます。
このキーワードは、JSONスキーマのルートに配置する必要があります。このキーワードの値は、URI [RFC3986]および有効なJSON参照 [json-reference]である必要があります。このURIは、絶対的で正規化されている必要があります。このURIにあるリソースは、自身を正常に記述する必要があります。スキーマ作成者は、スキーマにこのキーワードを含めることを推奨します。
次の値は事前に定義されています。
カスタムキーワードを使用してJSONスキーマを拡張する場合は、スキーマ作成者は"$schema"のカスタムURIを定義する必要があります。このカスタムURIは、事前に定義された値のいずれであってはなりません。
JSONスキーマは、スキーマアドレッシングのメカニズムとしてJSON参照 [json-reference]を使用します。これは、この仕様を2つの方法で拡張します。
スキーマ内のURIを変更することを、新しい解決スコープの定義と呼びます。スキーマの初期解決スコープは、スキーマ自体のURI（存在する場合）、またはスキーマがURIからロードされなかった場合は空のURIです。
このキーワードの値は文字列でなければならず、有効なURIである必要があります。このURIは正規化されている必要があり、空のフラグメント（＃）または空のURIであってはなりません。
"id"キーワード（または略して"id"）は、解決スコープを変更するために使用されます。"id"が検出されると、実装は、このIDを最も近い親スコープに対して解決する必要があります。解決されたURIは、別の"id"が検出されるまで、このサブスキーマとそのすべての子の新しい解決スコープになります。
"id"を使用して解決スコープを変更する場合、スキーマ作成者は、解決スコープがスキーマ内で一意であることを確認する必要があります。
このスキーマは例として使用されます。
{
"id": "http://x.y.z/rootschema.json#",
"schema1": {
"id": "#foo"
},
"schema2": {
"id": "otherschema.json",
"nested": {
"id": "#bar"
},
"alsonested": {
"id": "t/inner.json#a"
}
},
"schema3": {
"id": "some://where.else/completely#"
}
}
次のURIエンコードされたJSONポインタ [json-pointer]（ルートスキーマから始まる）にあるサブスキーマは、次の解決スコープを定義します。
解決スコープに対してURIを解決する場合、実装は2つの動作モードを選択できます。
実装は正準逆参照をサポートする必要があり、インライン逆参照をサポートできます。
たとえば、このスキーマを考えてみます。
{
"id": "http://my.site/myschema#",
"definitions": {
"schema1": {
"id": "schema1",
"type": "integer"
},
"schema2", {
"type": "array",
"items": { "$ref": "schema1" }
}
}
}
実装が"schema1"参照を検出すると、それを最も近い親スコープに対して解決し、URI "http://my.site/schema1#"になります。このURIを処理する方法は、選択した逆参照モードによって異なります。
インライン逆参照を使用する場合、解決スコープは、この例のように、JSONポインタではない空でないフラグメント部分を持つURIにつながる可能性があります。
{
"id": "http://some.site/schema#",
"not": { "$ref": "#inner" },
"definitions": {
"schema1": {
"id": "#inner",
"type": "boolean"
}
}
}
インライン逆参照をサポートすることを選択した実装は、この種の参照を使用できる必要があります。ただし、正準逆参照を使用することを選択した実装は、それをサポートする必要はありません。
インライン逆参照は、ルートスキーマの正準URIとは異なる正準URIを生成できます。スキーマ作成者は、正準逆参照を使用する実装が、インライン逆参照を使用する実装と同じコンテンツを取得することを確認する必要があります。
JSONポインタではないフラグメントを使用する拡張JSON参照は、インライン逆参照をサポートしないことを選択した実装によって逆参照できません。この種の参照は下位互換性のために定義されており、新しいスキーマでは使用しないでください。
この仕様では、対話型のJSONスキーマ処理の大部分はHTTPを介して行われることが認められています。したがって、このセクションでは、このプロトコルで現在利用可能なメカニズムを使用してインスタンス/スキーマの関連付けを実現するための推奨事項を示します。インスタンスは、1つ以上のスキーマによって記述されていると言われています。
処理されるインスタンスの"Content-Type"ヘッダーに"profile"という名前のMIMEタイプパラメーターを追加することを推奨します。存在する場合は、このパラメーターの値は有効なURIでなければならず、このURIは有効なJSONスキーマに解決される必要があります。MIMEタイプは"application / json"またはその他のサブタイプでなければなりません。
このようなヘッダーの例を次に示します。
Content-Type: application/my-media-type+json;
profile=http://example.com/my-hyper-schema#
"Link"ヘッダーを使用する場合は、使用されるリレーションタイプは、RFC 5988、セクション5.3 [RFC5988]で定義されている"describedBy"でなければなりません。"Link"ヘッダーのターゲットURIは、有効なJSONスキーマである必要があります。
このようなヘッダーの例を次に示します。
Link: <http://example.com/my-hyper-schema#>; rel="describedBy"
JSONスキーマの提案されたMIMEメディアタイプは、次のように定義されています。
| [RFC2119] | Bradner、S。、「RFCで使用されるキーワードによる要件レベルの表示」、BCP 14、RFC 2119、DOI 10.17487 / RFC2119、1997年3月。 |
| [RFC2616] | Fielding、R。、Gettys、J。、Mogul、J。、Frystyk、H。、Masinter、L。、Leach、P。およびT. Berners-Lee、「ハイパーテキスト転送プロトコル - HTTP / 1.1」、RFC 2616、DOI 10.17487 / RFC2616、1999年6月。 |
| [RFC3986] | Berners-Lee、T。、Fielding、R。およびL. Masinter、「統一資源識別子（URI）：汎用構文」、STD 66、RFC 3986、DOI 10.17487 / RFC3986、2005年1月。 |
| [RFC4627] | Crockford、D。、「JavaScriptオブジェクト表記（JSON）のapplication / jsonメディアタイプ」、RFC 4627、DOI 10.17487 / RFC4627、2006年7月。 |
| [RFC5988] | Nottingham、M。、「Web Linking」、RFC 5988、DOI 10.17487 / RFC5988、2010年10月。 |
| [json-reference] | Bryan、P。およびK. Zyp、「JSON参照（進行中）」、2012年9月。 |
| [json-pointer] | Bryan、P。およびK. Zyp、「JSONポインタ（進行中）」、2012年9月。 |
| [json-schema-03] | Court、G。およびK. Zyp、「JSONスキーマ、ドラフト3」、2012年9月。 |