システム
ライト
ダークJSON ハイパースキーマ Draft-06 リリースノート
draft-luff-json-hyper-schema-00 (draft-04) から draft-wright-json-schema-hyperschema-01 (draft-06) への移行に関するリリースノート。
draft-07 の移行ノートでは、draft-04 から draft-07 への移行について、draft-05 および draft-06 の複雑な中間状態をスキップすることで、より直接的な概要を提供しています。このページは歴史的な関心のために保持されていますが、最新のドラフトをすぐに使用したい場合には推奨されません。
実装者向け: draft-06 以前ではなく、draft-07 を実装することを推奨します。
- Q: draft-04 と draft-06 の間にはどのような非互換な変更がありますか？
- Q: draft-06 の公開直前に、なぜハイパースキーマにいくつかの大きな変更が加えられたのですか？
- Q: なぜ仕様はもはや HTML のように言及したり動作したりしないのですか？
- Q: では、リンクでサポートされている HTTP メソッドをどのように示すのですか？
- Q: いいえ、本当に。リンクでサポートされている HTTP メソッドを明示的に示すにはどうすればよいですか？
- Q: "targetSchema" がレスポンスではない場合、レスポンスをどのように記述するのですか？
Q: draft-04 と draft-06 の間にはどのような非互換な変更がありますか？
draft 04 と 06 の間で、ハイパースキーマの大幅な再検討を行いました。ハイパースキーマは、JSON スキーマ検証ほど広く採用されていませんでした。
draft-06 にはまだ大きなギャップがあることは承知していましたが、フィードバックを収集するための適切な変更セットだと感じました。draft-07 が公開されたので、そのドラフト以降を使用する必要があり、draft-06 は歴史的な関心事になります。
draft-04 から draft-05 への変更
| キーワード | 変更 | 結果 |
|---|---|---|
"base" | "href" のベース URI を決定するために、最も近い "self" リンクを検索する代わりに利用 | ベースを変更するために "self" リンクに依存していた場合は、"base" を明示的に設定してください |
"rel" | "full" 関係が削除されました | "item" を使用 |
"rel" | "instances" および "create" 関係が削除されました | "collection" を使用 |
"rel" | "root" 関係が削除されました | "href" URI テンプレートでフラグメントを使用してください |
"fragmentResolution" | 削除されました | メディアタイプがフラグメントの解釈方法を決定します |
"pathStart" | 削除されました | [代替なし] |
"method" | HTML フォームセマンティクス の "get" と "post" に戻りました。これは、すべての HTTP メソッドではなくなりました | [混乱を招くというフィードバックにより、draft-06 で再度変更されました] |
draft-05 から draft-06 への変更
| キーワード | 変更 | 結果 |
|---|---|---|
"method" | 削除されました | HTTP メソッドの提案については、#73 および #296 を参照してください（必要に応じて、拡張キーワードとして "method" または "allow" のいずれかを使用してください）。"schema" および "encType" の使用方法を示す必要はなくなりました |
"schema" | 削除されました | "hrefSchema"、"submissionSchema"、または "targetSchema" を使用してください |
"encType" | 削除されました | リクエストボディには "submissionEncType" を使用してください。URI クエリ文字列には不要になりました |
"hrefSchema" | 追加されました | "method": "get", "schema": {...} を置き換え、追加機能も備えています |
"submissionSchema" | 追加されました | は、"method": "post", "schema": {...} を置き換えます。 |
"submissionEncType" | 追加されました | は、"method": "post", "encType": "..." を置き換えます。 |
"href" | プリプロセッシングで削除されました。 | 今後の草案で置き換えられ、拡張される予定です。 |
"targetSchema" の適切な使用法
"targetSchema" は最近のどちらの草案でも意味が変わっていませんが、広く誤解されてきました。そのため、指定されたとおりに使用すると変更のように感じるかもしれません。
draft-04 では、個々の HTTP メソッドを "method" 値として強調していたため、多くのユーザーが "targetSchema" を "method" におけるメソッドへの応答のヒントとして解釈しました。これは決して正しい解釈ではありませんでした。すべての草案でこのキーワードは、HTTP GET への応答として表示されるターゲットリソースの表現を記述するものと定義されており、他の応答に表示される場合とされない場合があります。
draft-06 では、この使用法を明確にし、さまざまな HTTP メソッドでの使用に関するガイダンスを提供しています。これには、PUT および PATCH のリクエスト記述として "targetSchema" を使用することが含まれます。draft-04 では、多くのユーザーが PUT および PATCH リクエストを記述するために "schema" を使用していましたが、これは不要です。
ただし、"targetHints" 提案は draft-07 に受け入れられました。特に、「Accept-Patch」のヒントを有効にするものであり、HTTP PATCH で "targetSchema" を適切に使用するために必要です。draft-07 には例と詳細なガイダンスが記載されます。
Q: draft-06 の公開直前に、なぜ Hyper-Schema にいくつかの大きな変更が加えられたのですか？
A: 最終レビュー中に、仕様の記述どおりの使い方に関して合意がないことが明らかになりました。遅れての変更は、曖昧さのない意味を持つ仕様を公開するために必要であり、これにより、異なる解釈ではなく、内容に関するフィードバックを得ることができました。当初は、そこにあったものを単に明確にしようとしましたが、そもそもそこに何があるのかについて合意がないことに気づきました。
Q: なぜ仕様はもはや HTML のように言及したり動作したりしないのですか？
A: 既存のアナロジーは、次の 2 つの理由から、良い影響よりも悪い影響を与えるというコンセンサスに達しました。
- draft-03 から draft-04 への変更で、
"method"が HTML の<form method="...">の "get" および "post" 値の代わりに、任意の HTTP メソッドを示すようになったことで、HTML との元々のアナロジーが壊れてしまい、それを元に戻そうとしても受け入れられませんでした。 - URI クエリ文字列 (URI の他の部分ではない) またはリクエストボディのいずれかに
"schema"と"encType"しか使用できず、両方を一度に扱う方法がないことは、API 設計にとって過度に制限的でした。
"schema" の分割
"method" に応じて "schema" が 2 つの異なることを行う代わりに、それぞれの用途に合わせて 2 つのキーワードに分割しました。これにより、HTML フォームにはないユースケースである、必要なときに両方を同時に使用できます。
"hrefSchema" は、"method": "get" の使用法を置き換えますが、URI テンプレート変数を活用することで、クライアントデータ駆動の動的 URI がクエリ文字列に限定されなくなります。このアプローチでは "encType" は不要になります。
"submissionSchema" は、"method": "post" の使用法を直接置き換え、"submissionEncType" が "encType" を置き換えます。
"method" の削除
draft-05 では、"method" の draft-03 の動作を復元しようとしましたが、フィードバックによると、ユーザーはその変更に非常に混乱していました。"schema" が分割されたことで、"method" の draft-05 の動作は不要になりました。
draft-04 の "method" の動作に戻すこともできましたが、何度も往復することでさらに混乱が生じるだけでなく、"method" に対する draft-04 のアプローチは、そもそも LDO 設計の他の部分と一貫性がありませんでした。特に、上記のように "targetSchema" の使用に問題を引き起こしました。
Q: では、リンクでサポートされている HTTP メソッドをどのように示すのですか？
A: 理想的には、これはリンク関係タイプによって暗黙的に伝えられます。これは、一般的に機械指向ハイパーメディア全体におけるセマンティクスの主要な指標です。RFC 5988 は、カスタム (別名「拡張」) リンク関係の作成に関するガイダンスを提供しています。
urn: スキームの UUID 名前空間や tag: スキームなど、いくつかの URI スキームと名前空間は、一意の識別子の作成に特に適しています。
そしてもちろん、HTTP の "Allow" レスポンスヘッダーや、メソッドを試して 405 Method Not Allowed エラーを適切に処理するなど、これを実行時に検出する方法があります。
Q: いいえ、本当に。リンクでサポートされている HTTP メソッドを明示的に示すにはどうすればよいですか？
A: "targetHints" 提案は draft-07 の一部であるため、draft-06 の拡張として使用することもできますが、現時点では draft-07 を使用することを推奨します。
Q: "targetSchema" が応答でない場合、応答を記述するにはどうすればよいですか？
A: さまざまな成功およびエラー応答に対してハイパースキーマを用意する必要がありますが、それらをリンクに接続することは、使用法に関する質問というよりもドキュメントに関する質問です。各応答は独自のスキーマを示すため、実行時に事前に知っておく必要はありません。
HTTP メソッドなどの操作に応答を明示的に関連付けるハイパースキーマのキーワードはこれまでありませんでした。これに関するユースケースは API ドキュメントの生成に関するものであると思われるため、これは JSON Schema API ドキュメント語彙の候補になる可能性が非常に高いです。