JSON 超媒體綱要 Draft-07 發行說明

JSON 超媒體綱要 draft-07 完成了在 draft-06 中開始的超媒體綱要重新設計。

超媒體綱要現在僅專注於向 JSON 文件添加超連結，因此用於其他目的的關鍵字（readOnly 和 media）已移至驗證規範。

為求清晰易懂，新的草案已完全重寫，因此最好將其視為一個新的提案。我們希望在某些時候添加教學材料，但這不屬於發行說明的範圍。

但是，如果您希望從較早的草案遷移，本頁是關鍵變更的指南。新增內容（數量更多）應該直接從新的規範中學習，直到我們可以提供教學為止。

請注意，draft-handrews-json-schema-hyperschema-00 已被 draft-handrews-json-schema-hyperschema-01 取代，以修復令人困惑的錯誤。較新的 -01 草案仍然被認為是 draft-07。它現在使用正確的 URI 引用 draft-07 元綱要，以及其他排版修復。 -00 和 -01 之間沒有功能上的變更。

• 從 draft-06 遷移
• 從 draft-05 遷移
• 從 draft-04 遷移
  • GET
  • PUT
  • DELETE
  • POST
  • PATCH

從 draft-06 遷移

沒有更改 draft-06 的功能，儘管為了清晰和一致性，重命名了兩個關鍵字

• mediaType -> targetMediaType
• submissionEncType -> submissionMediaType

此外，hrefSchema 有點令人困惑，因此在解釋其工作原理以及如何融入整體連結解析過程中，投入了更多精力。

從 draft-05 遷移

有關 draft-05 的資訊，請參閱 draft-06 發行說明。

從 draft-04 遷移

在理想的 draft-07 世界中，連結和操作並不是相同的概念。使用從OpenAPI 的 Operation Object 借用的術語，HTTP 方法是操作，而每個連結（如單個 LDO 所描述）可以支援多個操作。

因此，與 draft-04 不同，draft-07 超媒體綱要沒有針對每個操作的單獨連結。這使得以下的遷移指南充其量只是近似的。

有關 draft-04 的 method 和 targetSchema 通常如何用於建立單一操作連結，以及這如何對遷移到多操作連結構成挑戰的更詳細說明，請參閱 draft-06 發行說明。這些發行說明還解釋了 draft-04 中定義的連結關係及其後續刪除的情況，以及實例基礎 URI 的決定方式的變更。

除了這些變更之外，最少的遷移將遵循以下幾行，儘管刻意缺少明確的響應描述（除非響應恰好是目標資源的表示形式）意味著 draft-04 的某些用法在 draft-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

在 Hyper-Schema 中，如何對正確的 PATCH（在請求中使用 patch 媒體類型而不是 application/json）進行建模一直不是很清楚。 一種選擇是將其與 PUT 相同地處理，除了在 encType 中使用 patch 媒體類型。假設這種方法 (以及與 PUT 相同的 taregetSchema/ mediaType 警告)

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