JSONハイパースキーマドラフト07リリースノート

JSONハイパースキーマ ドラフト07 は、ドラフト06で開始されたハイパースキーマの改訂を完了します。

ハイパースキーマは、JSONドキュメントにハイパーリンクを追加することに重点を置くようになったため、他の目的で使用されていたキーワード（readOnly および media）は 検証仕様に移動されました。

新しいドラフト は、明確さとアクセシビリティのために完全に書き直されているため、単に新しい提案として扱うのが最善です。チュートリアル資料をいつか追加したいと考えていますが、それはリリースノートの範囲外です。

ただし、以前のドラフトから移行する場合は、このページが重要な*変更*のガイドとなります。追加部分ははるかに多いため、チュートリアルを提供できるようになるまでは、新しい仕様から直接学習する必要があります. much more numerous, should be learned directly from the new specification until we can provide tutorials.

draft-handrews-json-schema-hyperschema-00は、紛らわしいバグを修正するためにdraft-handrews-json-schema-hyperschema-01に置き換えられました。新しい-01ドラフトは、依然としてドラフト07と見なされます。現在は、他のタイポの修正に加えて、正しいURIでドラフト07メタスキーマを参照しています。-00と-01の間に機能的な変更はありません。

• ドラフト06からの移行
• ドラフト05からの移行
• ドラフト04からの移行
  • GET
  • PUT
  • DELETE
  • POST
  • PATCH

ドラフト06からの移行

ドラフト06の機能は変更されていませんが、明確さと一貫性のために2つのキーワードの名前が変更されました

• mediaType -> targetMediaType
• submissionEncType -> submissionMediaType

さらに、hrefSchema は多少混乱を招くため、その仕組みとリンク解決プロセス全体への適合方法を説明するために、かなりの労力が費やされました。

ドラフト05からの移行

ドラフト05に関連する情報については、ドラフト06リリースノート を参照してください。

ドラフト04からの移行

理想的なドラフト07の世界では、リンクと 操作 は同じ概念ではありません。OpenAPIの操作オブジェクト から借用した用語を使用すると、HTTPメソッドは操作であり、各リンク（単一のLDOで記述されている）は複数の操作をサポートできます。

したがって、ドラフト04とは異なり、ドラフト07ハイパースキーマは 操作ごとに個別のリンクを持ちません。これにより、以下の移行ガイドラインはせいぜい概算になります。

ドラフト04の method と targetSchema が通常どのように単一操作リンクを作成するために使用されたか、そしてそれが複数操作リンクへの移行にどのように課題をもたらすかについてのより詳細な説明については、ドラフト06リリースノート を参照してください。これらのリリースノートでは、ドラフト04で定義され、その後削除されたリンク関係に何が起こったのか、インスタンスベースURIの決定方法の変更についても説明しています。

これらの変更に加えて、最小限の移行は以下のようになりますが、明示的な応答記述がないこと（応答がターゲットリソースの表現である場合を除く）は、ドラフト04の一部の使用法はドラフト07に直接対応するものがないことを意味します.

以下のリストに記載されていないキーワードは、そのリンク操作では変更されていません。

GET

• "method": "GET" -> "targetHints": {"allow": ["GET"]}
• mediaType -> targetMediaType
• schema -> hrefSchema パラメータがhrefに追加されました
• encType -> application/x-www-form-urlencoded の場合は削除、それ以外の場合はメーリングリストに連絡

PUT

PUT リンクで、schema/encType が targetSchema/mediaType と異なる場合、targetSchema/mediaType が表現ではないレスポンスを記述している場合、これらのフィールドには直接の代替手段がありません。

• "method": "PUT" -> "targetHints": {"allow": ["PUT"]}
• schema -> targetSchema
• encType -> targetMediaType

DELETE

DELETE はリクエストペイロードを受け取らないため、schema と encType は使用されません。 targetSchema と mediaType が、削除されたリソースの表現以外のレスポンスに使用されていた場合、それらに直接の代替手段はありません。

• "method": "DELETE" -> "targetHints": {"allow": ["DELETE"]}
• mediaType -> targetMediaType （表現を記述している場合）

POST

ほとんどの場合、POST のレスポンスは、ターゲットリソースの表現ではなく、POST が実行しようとした何らかの結果またはステータスです。したがって、targetSchema と mediaType はほぼ確実に削除する必要があります。それ以外は

• "method": "POST" -> "targetHints": {"allow": ["POST"]}
• schema -> submissionSchema
• encType -> submissionMediaType

PATCH

リクエストで application/json ではなくパッチメディアタイプを使用する適切な PATCH を Hyper-Schema でどのようにモデル化するかについては、完全には明らかではありませんでした。1 つの選択肢は、encType にパッチメディアタイプを指定する以外は PUT と同じように扱うことでした。そのアプローチ（および PUT と同じ taregetSchema/mediaType の注意事項）を想定すると

• "method": "PATCH" -> "targetHints": {"allow": ["PATCH"]}
• schema -> targetSchema
• "encType": "..." -> "targetHints": {"accept-patch": "..."}