| インターネット技術タスクフォース | A.ライト氏 編集 |
| インターネットドラフト | |
| 意図されたステータス：参考情報 | H.アンドリュース氏 編集 |
| 期限切れ：2017年10月23日 | Cloudflare, Inc. |
| G.ラッフ氏 | |
| 2017年4月21日 |
JSONハイパーシーマ：JSONのハイパーメディアアノテーションのためのボキャブラリ
draft-wright-json-schema-hyperschema-01
JSON Schemaは、JSONデータの構造を定義するためのJSONベースのフォーマットです。このドキュメントは、ハイパーリンクと、HTTPのようなハイパーメディア環境を通じてリモートJSONリソースの処理と操作に関する指示を用いて、JSONドキュメントにハイパーリンクを付与するためのJSON Schemaのハイパーリンクおよびハイパーメディア関連キーワードを規定しています。
このドラフトの課題リストは、<https://github.com/json-schema-org/json-schema-spec/issues>にあります。
詳細については、<https://json-schema.dokyumento.jp/>を参照してください。
フィードバックを提供するには、この課題トラッカー、ホームページに記載されている連絡方法、またはドキュメント編集者へのメールを使用してください。
このインターネットドラフトは、BCP 78およびBCP 79の規定に完全に準拠して提出されています。
インターネットドラフトは、インターネットエンジニアリングタスクフォース（IETF）の作業文書です。他のグループもインターネットドラフトとして作業文書を配布する場合があることに注意してください。最新のインターネットドラフトのリストは、http://datatracker.ietf.org/drafts/current/にあります。
インターネットドラフトは、最大6ヶ月間有効なドラフト文書であり、いつでも他の文書によって更新、置換、または廃止される可能性があります。「作業中」以外の参照資料として、またはそれらを引用することは不適切です。
このインターネットドラフトは、2017年10月23日に期限切れになります。
Copyright (c) 2017 IETF Trustおよび文書の著者として特定された人物。すべての権利を保有。
このドキュメントは、BCP 78およびIETFドキュメントに関するIETFトラストの法的規定（http://trustee.ietf.org/license-info）（このドキュメントの公開日に有効）に従います。これらのドキュメントをよく確認してください。それらは、このドキュメントに関するあなたの権利と制限について説明しています。このドキュメントから抽出されたコードコンポーネントには、トラスト法的規定のセクション4.eに記載されている簡略化されたBSDライセンステキストを含める必要があり、簡略化されたBSDライセンスに記載されているように、保証なしで提供されます。
JSON Schemaは、JSONデータの構造を定義するためのJSONベースのフォーマットです。このドキュメントは、JSON Schemaのハイパーリンクおよびハイパーメディア関連キーワードを規定しています。
これらのキーワードを使用するJSON Schemaを参照するために、JSONハイパーシーマという用語が使用されます。
この仕様では、JSON Schemaコア仕様 [json-schema]で定義されている用語を使用します。読者はこの仕様のコピーを持っていることをお勧めします。
このドキュメントのキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「MAY」、「OPTIONAL」は、RFC 2119 [RFC2119]に記載されているように解釈されます。
"schema"と"instance"という用語は、JSON Schemaコア仕様 [json-schema]で定義されているように解釈されます。
このドキュメントでは、JSON Schemaを使用してインスタンスデータにハイパーリンクを定義する方法について説明します。また、JSONデータをリッチマルチメディアドキュメントとして解釈するために必要な追加情報を提供する方法も定義します。
すべてのJSON Schemaキーワードと同様に、「スキーマキーワード」セクションで説明されているすべてのキーワードはオプションです。最小限の有効なJSONハイパーシーマは空のオブジェクトです。
ハイパーリンクを定義し、「imgData」プロパティのマルチメディア解釈を提供するJSON Schemaの例を次に示します。
{
"title": "Written Article",
"type": "object",
"properties": {
"id": {
"title": "Article Identifier",
"type": "number",
"readOnly": true
},
"title": {
"title": "Article Title",
"type": "string"
},
"authorId": {
"type": "integer"
},
"imgData": {
"title": "Article Illustration (thumbnail)",
"type": "string",
"media": {
"binaryEncoding": "base64",
"type": "image/png"
}
}
},
"required" : ["id", "title", "authorId"],
"links": [
{
"rel": "self",
"href": "/article{?id}"
},
{
"rel": "author",
"href": "/user?id={authorId}"
}
]
}
この例では、インスタンスのプロパティが定義されています。「imgData」プロパティについては、base64でデコードし、結果のバイナリデータをPNG画像として扱う必要があることを指定しています。また、インスタンスのリンクリレーションを定義し、インスタンスからの値を含むURIを使用しています。[CREF1]「id」は通常、サーバーによって割り当てられるまで新しいインスタンスには不明な「id」プロパティがあるため、必須キーワードではない方が良いでしょう。ただし、このプロパティはリンクで使用されており、これがないと、複数の異なるインスタンスに同じrel=self URIが与えられます！
上記のスキーマで記述されたJSONインスタンスの例を次に示します。
{
"id": 15,
"title": "Example data",
"authorId": 105,
"imgData": "iVBORw...kJggg=="
}
可読性を高めるために、base-64データは省略されています。
インスタンスがハイパーシーマ内またはハイパーシーマを含む検証キーワードに対して検証に失敗した場合、ハイパーシーマをインスタンスに適用してはなりません。「anyOf」または「oneOf」で検証されないブランチ、またはインスタンスに関連しない「dependencies」サブスキーマにあるハイパーシーマキーワードは無視する必要があります。
任意の深さにある「not」に含まれるサブスキーマ（介在する追加の「not」サブスキーマの数に関係なく）にあるハイパーシーマキーワードは無視する必要があります。
"contains"キーワードのサブスキーマにハイパーシーマキーワードが含まれている場合、それらはスキーマに対して検証されるすべての配列要素に適用する必要があります。単一の検証要素を見つけることで検証結果を決定するのに十分ですが、ハイパーシーマキーワードが存在する場合は、サブスキーマをすべての配列要素に対して評価する必要があります。
JSON Schema検証の現在のURIは<https://json-schema.dokyumento.jp/draft-06/hyper-schema#>です。
存在する場合、このキーワードは、インスタンス全体が見つかった現在のURIベースに対して解決され、インスタンス内のURI参照の新しいURIベースを設定します。そのため、見つかった順序に関係なく、最初に解決されるURI参照となります。
URIは、リンク記述オブジェクトの"href" [href]プロパティについて説明されているのと同じプロセスを使用して、提供されたURIテンプレートから計算されます。
"base"を使用するJSONスキーマの例
{
"base": "/object/{id}",
"links": [
{
"rel": "self",
"href": ""
},
{
"rel": "next",
"href": "{nextId}"
}
]
}
このスキーマを使用してrel="self"とrel="next"リンクを生成するJSONインスタンスの例
{
"id": 41,
"nextId": 42
}
ドキュメントURIが<http://example.com/?id=41>の場合、新しいURIベースは<http://example.com/object/41>になります。
このURIベースに対して2つのリンク記述オブジェクトを解決すると、次の絶対形式のHTTPリンクヘッダーと完全に等価な2つのリンクが作成されます。
スキーマの"links"プロパティは、リンク記述オブジェクトをインスタンスに関連付けるために使用されます。このプロパティの値は配列でなければならず、配列内のアイテムは、以下で定義されているリンク記述オブジェクトでなければなりません。
"links"キーワードを使用するスキーマの例
{
"title": "Schema defining links",
"links": [
{
"rel": "self",
"href": "{id}"
},
{
"rel": "parent",
"href": "{parent}"
}
]
}
"media"プロパティは、このインスタンスがJSON文字列でエンコードされたJSON以外のデータを含むことを示しています。コンテンツの種類とエンコード方法を記述しています。
このプロパティの値はオブジェクトでなければなりません。記述されているインスタンスが文字列でない場合は、このプロパティの値は無視する必要があります。
"media"キーワードの値には、次のプロパティを含めることができます。
インスタンス値が文字列の場合、このプロパティは、文字列をバイナリデータとして解釈し、このプロパティで指定されたエンコードを使用してデコードする必要があることを定義します。RFC 2045、セクション6.1 [RFC2045]には、このプロパティの可能な値がリストされています。
このプロパティの値は、RFC 2046 [RFC2046]で定義されているメディアタイプでなければなりません。このプロパティは、このスキーマが定義するインスタンスのメディアタイプを定義します。
"binaryEncoding"プロパティが設定されていないが、インスタンス値が文字列の場合、このプロパティの値はテキストドキュメントタイプを指定する必要があり、文字セットはJSON文字列値がデコードされた文字セットである必要があります（デフォルトはUnicode）。
"media"の使用を示すスキーマの例を次に示します。
{
"type": "string",
"media": {
"binaryEncoding": "base64",
"type": "image/png"
}
}
このスキーマで記述されているインスタンスは文字列でなければならず、その値はbase64でエンコードされたPNG画像として解釈できる必要があります。
別の例
{
"type": "string",
"media": {
"type": "text/html"
}
}
このスキーマで記述されているインスタンスは、HTMLを含む文字列でなければならず、JSON文字列がデコードされた文字セット（デフォルトはUnicode）を使用する必要があります。
ブール値trueの値を持つ場合、このキーワードは、インスタンスの値がサーバーまたは所有権のある権限によってのみ管理され、ユーザーエージェントがこのプロパティの値を変更しようとする試みは、サーバーによって無視または拒否されることが期待されることを示します。
たとえば、このプロパティは、サーバー生成のシリアル番号を読み取り専用としてマークするために使用されます。
このキーワードの値はブール値でなければなりません。デフォルト値はfalseです。
リンク記述オブジェクト（LDO）は、インスタンスから別のリソースへの単一のリンクリレーションを記述するために使用されます。リンク記述オブジェクトはオブジェクトでなければなりません。
リンク記述フォーマットはJSON Schemaなしで使用でき、リンクを使用するデータ構造のスキーマとして標準リンク記述スキーマを参照することで、このフォーマットの使用を宣言できます。標準リンク記述スキーマのURIは：https://json-schema.dokyumento.jp/draft-06/links（ドラフト06バージョン）です。
クライアントがリンクを使用してデータを使用できる方法はいくつかあります。
クライアント提供のデータを使用する3つの方法は、リンク記述オブジェクト内の個別のスキーマキーワードによってそれぞれ対処されます。リンク操作は、そのセマンティクスに関連しないスキーマを無視します。
リンク記述オブジェクトは、HTTPメソッドなどの操作がターゲットリソースでサポートされているかどうかを直接示しません。代わりに、操作は主にリンク関係タイプ [rel]とURIスキームから推測する必要があります。ただし、アプリケーションの状態によって操作の可用性が制御されるなど、リソースは常に実行時に操作を拒否する場合があることに注意してください。
"href" [href]内のURIテンプレート変数は、デフォルトでサーバーが提供するインスタンスデータから解決されます。"hrefSchema" [hrefSchema]を使用すると、クライアントが提供するデータからテンプレート変数を解決するためのスキーマをリンクで指定できます。通常のJSONスキーマ検証機能を使用して、ユーザーエージェントデータからの解決を要求したり、禁止したり、ユーザーエージェントデータを使用しながら、ユーザーエージェントデータが提供されない場合はサーバーが提供するインスタンスデータにフォールバックできます。
サーバーが提供するインスタンスデータでテンプレート化されたパスコンポーネントを解決し、クエリ文字列を構築するためにユーザーエージェントデータを受け入れるという一般的なパターンは、「hrefSchema」サブスキーマをパステンプレート変数に対してfalseに設定し、クエリ文字列テンプレート変数にインスタンスに表示されない名前を付けることで実装できます。これにより、パス変数はインスタンスからのみ解決され、クエリ文字列変数はユーザーエージェントデータからのみ解決されるようになります。このアプローチの例については、「hrefSchema」セクションを参照してください。
JSONハイパーシーマでは、"targetSchema" [targetSchema]は、ターゲットリソースの表現に関する権威のない記述を提供します。クライアントは「targetSchema」を使用して、表現の置換または変更のための入力を構成できます。あるいは、「targetSchema」が存在しない場合、またはクライアントが権威のある情報のみを使用することを好む場合は、ターゲットリソースと対話して、その表現構造を確認または検出できます。
"targetSchema"は、応答のセマンティクスがターゲットリソースの表現であることを示している場合を除き、リンク操作の応答を記述することを意図していません。いずれの場合も、応答自体によって示されるスキーマが権威のあるものです。6.6.1セクションで、「targetSchema」をHTTP URIで使用する場合の各HTTPメソッドに固有のガイダンスを参照してください。
"submissionSchema" [submissionSchema]および"submissionEncType" [submissionEncType]キーワードは、ターゲットリソースによって実装される処理関数のドメインを記述します。それ以外の場合は、上記のように、送信スキーマとエンコーディングは、それらが関連しない操作に対して無視されます。
"href"リンク記述プロパティの値は、関連リソースのターゲットURIを決定するために使用されるテンプレートです。インスタンスプロパティの値は、インスタンスのベースURIに対してURI参照 [RFC3986]として解決する必要があります。
このプロパティは必須です。
"href"の値は、RFC 6570 [RFC6570]で定義されているURIテンプレートとして使用されます。ただし、いくつかの特別な考慮事項が適用されます。
URIテンプレートは、外部ソースとインスタンスの組み合わせからのデータを使用して塗りつぶされます。インスタンスデータとユーザーエージェントデータのいずれかを使用できる場合、このセクションでは単に「データ」または「値」を参照します。ソースが重要な場合は、明示的に指定されます。任意のオブジェクトプロパティ（空文字列を含む）または配列インデックスの使用を許可するために、次のルールが定義されます。
URIテンプレート内の特定の変数名に対して、使用する値は次のように決定されます。
"hrefSchema" [hrefSchema]が存在し、ユーザーエージェントデータが提供されている場合、データは「hrefSchema」の値に従って有効なインスタンスである必要があります。上記の処理の後、テンプレート変数は最初にユーザーエージェントデータインスタンスから解決する必要があります。解決されていない変数は、リソースインスタンスデータから解決する必要があります。
URIテンプレートによって参照される値がnull、ブール値、または数値の場合、最初に次のように文字列に変換する必要があります。
一部のソフトウェア環境では、数値の元のJSON表現は使用できません（1.0と1の違いを判別する方法がありません）。そのため、妥当な表現を使用する必要があります。スキーマとAPIの作者はこれを考慮し、正確な表現が重要な場合は、他の型（文字列またはブール値など）を使用する必要があります。
適切な値が使用できない場合があります。たとえば、テンプレートはオブジェクトプロパティの使用を指定している可能性がありますが、そのようなデータは提供されておらず（または「hrefSchema」が存在せず）、インスタンスは配列または文字列です。
テンプレートに必要な値のいずれかが、ユーザーエージェントデータ（関連する場合）とJSONインスタンスのいずれにも存在しない場合、別のソース（デフォルト値など）から置換値を提供できます。それ以外の場合は、リンク定義はインスタンスに適用されないものと見なす必要があります。
"hrefSchema"リンク記述プロパティの値は、有効なJSONスキーマである必要があります。このスキーマは、"href" [href]のURIテンプレートの入力またはその他のユーザーエージェントデータを検証するために使用されます（そのセクションで説明）。
"hrefSchema"を省略するか、スキーマ全体を「false」に設定すると、ユーザーエージェントデータの受け入れが防止されます。
実装では、「hrefSchema」を使用してリソースインスタンスデータから解決された値を検証しようとしてはいけません。これにより、ユーザーエージェントデータに対する異なる検証ルールが可能になります（日付時刻入力にスペルアウトされた月をサポートしますが、標準の日付時刻形式をストレージに使用します）。
たとえば、これはURIテンプレートの各クエリ文字列パラメーターのスキーマを定義します。
{
"href": "/foos{?condition,count,query}",
"hrefSchema": {
"properties": {
"condition": {
"type": "boolean",
"default": true
},
"count": {
"type": "integer",
"minimum": 0,
"default": 0
},
"query": {
"type": "string"
}
}
}
}
この例では、「extra」のスキーマは参照として与えられており、ユーザーエージェントデータ検証制約を対応するプロパティのインスタンス検証制約と同一に保ちますが、「id」にはfalseスキーマが与えられており、その変数のユーザーエージェントデータが防止されます。
{
"definitions": {
"extra": {
"type": "string",
"maxLength": 32
}
},
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"readOnly": true
},
"extra": {"$ref": "#/definitions/extra"}
},
"links": [{
"rel": "self",
"href": "/things/{id}{?extra}",
"hrefSchema": {
"properties": {
"id": false,
"extra": {"$ref": "#/definitions/extra"}
}
}
}]
}
[CREF4]上記の例は、新しい"hrefSchema"キーワードを使用して、以前のドラフトで処理された"method"が"get"の動作をシミュレートしています。
"rel"プロパティの値は、ターゲットリソースへの関係の名前を示します。値は、RFC 5988で確立されたIANAリンク関係タイプレジストリ [RFC5988]からの登録済みリンク関係、またはRFC 3986のURI生成 [RFC3986]に従った正規化されたURIである必要があります。
ターゲットへの関係は、スキーマ（またはサブスキーマ）が適用されるインスタンスから解釈され、インスタンスが見つかった可能性のあるより大きなドキュメントではありません。
関係の定義は通常、メディアタイプに依存せず、ユーザーは既存の承認済み関係定義を使用することをお勧めします。
たとえば、ハイパーシーマが定義されている場合
{
"type": "array",
"items": {
"links": [{
"rel": "item",
"href": "{id}"
}, {
"rel": "up",
"href": "{upId}"
}]
}
}
そして、JSON表現を使用してインスタンスリソースのコレクションが取得された場合
GET /Resource/
[{
"id": "thing",
"upId": "parent"
}, {
"id": "thing2",
"upId": "parent"
}]
これは、コレクションの最初のアイテムについて、独自の資源としてのURIが"/Resource/thing"に解決され、最初のアイテムの「up」関係は"/Resource/parent"のリソースに解決される必要があることを示しています。
これらの関係値は大文字と小文字が区別されず、HTMLとHTTP Linkヘッダー [RFC5988]での使用と一貫しています。
オブジェクトの完全な表現を示すために"self"のリンク関係が使用されている場合、ターゲットURIが、"self"リンクを含むターゲットURIを含むリソース表現を要求するために使用されたURIと等価でないか、またはそのサブパスでない場合、ユーザーエージェントは、表現がターゲットURIによって示されるリソースの権威のある表現であると見なすべきではありません。
たとえば、ハイパーシーマが定義されている場合
{
"links": [{
"rel": "self",
"href": "{id}"
}]
}
そして、somesite.comからリソースが要求された場合
GET /foo/
(改行と空白を追加した)応答があるとします。
Content-Type: application/json; profile="http://example.com/alpha"
[{
"id": "bar",
"name": "This representation can be safely treated
as authoritative "
}, {
"id": "/baz",
"name": "This representation should not be treated as
authoritative the user agent should make request the
resource from '/baz' to ensure it has the authoritative
representation"
}, {
"id": "http://othersite.com/something",
"name": "This representation
should also not be treated as authoritative and the
target resource representation should be retrieved
for the authoritative representation"
}]
このプロパティは、リンクのタイトルを定義します。値は文字列である必要があります。
ユーザーエージェントは、ユーザーにリンクを表示する際にこのタイトルを使用できます。
このプロパティは、リンクターゲットの表現を記述すると予想されるスキーマを提供します。プロトコルによっては、スキーマがリンクに送信された特定の要求への応答を記述するかどうかは異なります。このプロパティはアドバイザリのみです。
リソースの表現とHTTPリクエストと応答の関係は、RFC 7231、セクション4.3.1 - "GET"、セクション4.3.4 "PUT"、セクション3.1.4.2 "Content-Location" [RFC7231]によって決定されます。特に、「targetSchema」は、クライアントがHTTP GETへの応答、または「Content-Location」ヘッダーがリクエストURIと等しい応答、およびクライアントがHTTP PUTリクエストでリソースを置換する場合に送信する必要があるものを期待できることを示唆しています。RFC 5789 [RFC5789]に従って、HTTP PATCHのリクエスト構造は、「targetSchema」とリクエストメディアタイプの組み合わせによって決定されます。
このプロパティは、「mediaType」と同様のセキュリティ上の懸念事項があります。クライアントは、このプロパティの値を使用してリンクに従った応答で受信したデータの解釈を支援してはなりません。これは、「安全な」データが再解釈される可能性があるためです。
たとえば、2人のプログラマーがテキストのみのメッセージボードを使用してWebセキュリティについて議論しているとします。これは、その会話からのデータの一部であり、URIはhttp://forum.example.com/topics/152/comments/13です。
{
"topicId": 152,
"commentId": 13,
"from": {
"name": "Jane",
"id": 5
},
"to": {
"name": "Jason",
"id": 8
},
"message": "It's easy, just add some HTML like
this: <script>doSomethingEvil()</script>"
}
可読性のために、メッセージ文字列は2行に分割されています。
{
"rel": "evil-attack",
"href": "http://forum.example.com/topics/152/comments/13",
"targetSchema": {
"properties": {
"message": {
"description": "Re-interpret `message` as HTML",
"media": {
"type": "text/html"
}
}
}
}
}
その後、サードパーティは別の場所に次のリンク記述オブジェクトを提供する可能性があります。
クライアントが上記のデータの解釈時にこの「targetSchema」値を使用した場合、メッセージの内容がHTMLとして表示される可能性があります。この時点で、メッセージに埋め込まれたJavaScriptが（"forum.example.com"ドメインのコンテキストで）実行される可能性があります。
このプロパティの値はアドバイザリのみであり、このリソースの取得時に返されると予想されるメディアタイプRFC 2046 [RFC2046]を表します。このプロパティの値は、RFC 7231、セクション5.3.2 - HTTP "Accept"ヘッダー [RFC7231]で定義されているのと同じパターンを使用して、メディア範囲である可能性があります。
このプロパティは、HTML の``要素の"type"プロパティ（助言的なコンテンツタイプ）や、HTTP Linkヘッダー [RFC5988] の"type"パラメーターと類似しています。ユーザーエージェントは、この情報を使用して、リンクが辿られる前にユーザーに提示するインターフェースに情報を提供できますが、この情報を結果データの解釈に使用しては**なりません**。このリンクを辿ることによって取得したデータの解釈方法を決定する際には、ユーザーエージェントの動作は、このプロパティの値に関係なく**同一**でなければなりません。
このプロパティの値が指定されていて、リンクのターゲットがHTTP/1.1 の"Accept"ヘッダーRFC 7231, section 5.3.2 [RFC7231] をサポートするプロトコルを使用して取得される場合、ユーザーエージェントは、このプロパティの値をサーバーへのリクエスト時にそのヘッダーの作成に役立てることができます。
このプロパティの値が指定されていない場合、値は"application/json"とみなされます。
例えば、スキーマが定義されている場合
{
"links": [{
"rel": "self",
"href": "/{id}/json"
}, {
"rel": "alternate",
"href": "/{id}/html",
"mediaType": "text/html"
}, {
"rel": "alternate",
"href": "/{id}/rss",
"mediaType": "application/rss+xml"
}, {
"rel": "icon",
"href": "{id}/icon",
"mediaType": "image/*"
}]
}
このスキーマで記述される適切なインスタンスには、4つのリンクが定義されています。 "rel"値が"self"のリンクは、予想されるMIMEタイプが"application/json"（デフォルト）になります。"rel"値が"alternate"の2つのリンクは、現在のアイテムのHTML版とRSS版の場所を指定します。"rel"値が"icon"のリンクは画像へのリンクですが、正確な形式は指定されていません。
上記の例からのアイテムを表示するビジュアルユーザーエージェントは、RSSフィードを表すボタンを表示することがあります。このボタンを押すと、ターゲットURI（計算された"href"値）が、ニュースフィードアグリゲータータブなど、表示に適したビューに渡されます。
上記のやり方でリンクを表示すること、またはURIをニュースフィードアグリゲータービューに渡すことは、データの解釈ではなく、リンクの解釈にすぎません。データ自体の解釈はニュースフィードアグリゲーターによって行われ、メインビューでニュースフィードとして解釈されなかったデータは拒否される**べき**です。
リンク定義における"mediaType"プロパティは、リンクのターゲットの予想される形式を定義します。しかし、これは助言的なものに過ぎず、権威あるものとは**みなしてはいけません**。
データの解釈方法を選択する際には、サーバーによって提供されるタイプ情報（またはファイル名から推測される情報、またはその他の通常の方法）のみを考慮する**必要**があり、リンクの"mediaType"プロパティを使用しては**なりません**。ユーザーエージェントは、この情報を使用して、リンクの表現方法や表示場所（例えば、ホバーテキスト、新しいタブでの開くなど）を決定できます。ユーザーエージェントがリンクを外部プログラムに渡すことを決定した場合、まず、そのデータが通常その外部プログラムに渡されるタイプのデータであることを確認する**べき**です。
これは、"targetSchema"に対する予防措置と同様に、「安全な」データの再解釈を防ぐためです。
存在する場合、このプロパティは、"submissionSchema" [submissionSchema] で記述されているリクエストペイロードにクライアントが使用するべきメディアタイプ形式を示します。
このキーワードを省略すると、"application/json"の値と同じ動作になります。
"submissionEncType"と"submissionSchema"は、HTTP URIに制限されません。
例えば、このリンクは、コンテキストリソースの作成者にメールを送信したい場合、クライアントはプレーンテキストとHTMLの両方の表現を要求する必要があることを示しています。
{
"links": [{
"submissionEncType": "multipart/alternative; boundary=ab12",
"rel": "author",
"href": "mailto:[email protected]{?subject}",
"hrefSchema": {
"type": "object",
"properties": {
"subject": { "type": "string" }
},
"required": ["subject"]
},
"submissionSchema": {
"type": "array",
"items": [
{
"type": "string",
"media": { "type": "text/plain; charset=utf8" }
},
{
"type": "string",
"media": { "type": "text/html" }
}
],
"minItems": 2
}
}]
}
このプロパティは、"submissionEncType"プロパティに従ってエンコードされ、処理のためにターゲットリソースに送信されるドキュメントの許容可能な構造を定義するスキーマを含んでいます。これは、ターゲットリソースによって実装される処理関数のドメインを記述していると見なすことができます。
これは、"targetSchema" [targetSchema] プロパティとは別個の概念です。"targetSchema"はターゲット情報リソース（PUTリクエストのリソースの内容の置換を含む）を記述するのに対し、"submissionSchema"はリソースによって評価されるユーザー送信のリクエストデータを記述します。"submissionSchema"は、ターゲット表現の観点から定義されていないペイロードを持つリクエストで使用することを目的としています。
"submissionSchema"を省略するか、スキーマ全体を"false"に設定すると、ユーザーエージェントデータは受け入れられなくなります。
| [RFC2045] | Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, DOI 10.17487/RFC2045, 1996年11月。 |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, 1997年3月。 |
| [RFC3986] | Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, 2005年1月。 |
| [RFC6570] | Gregorio, J., Fielding, R., Hadley, M., Nottingham, M. and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, 2012年3月。 |
| [json-schema] | Wright, A., "JSON Schema: A Media Type for Describing JSON Documents", Internet-Draft draft-wright-json-schema-00, 2016年10月。 |
| [RFC2046] | Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, DOI 10.17487/RFC2046, 1996年11月。 |
| [RFC5789] | Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, DOI 10.17487/RFC5789, 2010年3月。 |
| [RFC5988] | Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, 2010年10月。 |
| [RFC7231] | Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, 2014年6月。 |
JSON Schemaの初期ドラフト作成にご尽力いただいたGary Court、Francis Galiegue、Kris Zyp、Geraint Luffの皆様に感謝いたします。
このドキュメントへのご投稿とパッチ提供にご尽力いただいたJason Desrosiers、Daniel Perrett、Erik Wilde、Ben Hutton、Evgeny Poberezkin、Brad Bowman、Gowry Sankar、Donald Pipowitch、Dave Finlay、Denis Laxaldeの皆様に感謝いたします。
[CREF5]インターネットドラフトのステータスを離れる前にこのセクションを削除します。