系統
淺色
深色JSON Hyper-Schema 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-07，而不是 draft-06 或更早的版本。
- 問：draft-04 和 draft-06 之間的不相容變更有哪些？
- 問：為什麼在 draft-06 發佈前對 Hyper-Schema 進行了幾項重大變更？
- 問：為什麼規格不再提及或表現得像 HTML？
- 問：那麼我該如何指示鏈接支援哪些 HTTP 方法？
- 問：不，我是認真的。我該如何明確指示鏈接支援哪些 HTTP 方法？
- 問：如果 "targetSchema" 不是回應，我該如何描述回應？
問：draft-04 和 draft-06 之間的不相容變更有哪些？
在 draft-04 和 draft-06 之間，我們對 Hyper-Schema 進行了重大重新檢視，而 Hyper-Schema 從未像 JSON Schema 驗證那樣被廣泛採用。
雖然我們知道 draft-06 仍然存在重大缺陷，但我們認為這是一組很好的變更，可以收集回饋。隨著 draft-07 的發布，應使用該草案或更新的版本，而 draft-06 則成為歷史上的奇聞。
從 draft-04 到 draft-05 的變更
| 關鍵字 | 變更 | 後果 |
|---|---|---|
"base" | 取代了查找最近的 "self" 鏈接以確定 "href" 的基本 URI | 如果您依賴 "self" 鏈接來更改基本 URI，請明確設定 "base" |
"rel" | "full" 關係已移除 | 使用 "item" |
"rel" | "instances" 和 "create" 關係已移除 | 使用 "collection" |
"rel" | "root" 關係已移除 | 在您的 "href" URI 範本中使用片段 |
"fragmentResolution" | 已移除 | 媒體類型決定如何解釋片段 |
"pathStart" | 已移除 | [無替代方案] |
"method" | 改回 "get" 和 "post" 的 HTML 表單語義，而不是所有 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 方法中使用的指南。這包括將 "targetSchema" 作為 PUT 和 PATCH 的請求描述。在 draft-04 中，許多使用者使用 "schema" 來描述 PUT 和 PATCH 請求，這是沒有必要的。
然而，"targetHints" 提案已被接受納入 draft-07 中。其中，它允許提示 "Accept-Patch"，這對於在 HTTP PATCH 中正確使用 "targetSchema" 是必要的。在 draft-07 中將會有範例和詳細的指南。
問：為什麼在 draft-06 發佈之前，對 Hyper-Schema 進行了幾項重大變更？
答：在最終審查期間，很明顯對於如何使用現有的規格沒有共識。為了發布一個具有明確含義的規格，以便我們可以獲得有關其內容的回饋，而不是不同的解釋，這些後期的變更是有必要的。最初，我們試圖單純地釐清已有的內容，但後來我們意識到，首先對於已有的內容就沒有達成共識。
問：為什麼這個規格不再提及或表現得像 HTML？
答：我們達成共識，現有的類比弊大於利，原因有二
- 在 draft-03 和 draft-04 之間的變更中，讓
"method"指示任何 HTTP 方法，而不是 HTML 的<form method="...">"get" 和 "post" 值，打破了與 HTML 的原始類比，並且試圖改回此類比並未受到歡迎 - 只能夠為 URI 查詢字串（但不是 URI 的其他部分）或請求主體使用
"schema"和"encType"，但無法同時處理兩者，對於 API 設計來說過於限制
分割 "schema"
我們沒有讓 "schema" 根據 "method" 執行兩個不同的操作，而是將其分割為兩個關鍵字，每個操作一個關鍵字。這樣可以在需要時同時使用兩者，這是在 HTML 表單中不存在的使用案例。
"hrefSchema" 取代了 "method": "get" 的用法，但利用 URI 範本變數，使得客戶端數據驅動的動態 URI 不再侷限於查詢字串。"encType" 在這種方法中不再需要。
"submissionSchema" 直接取代了 "method": "post" 的用法，而 "submissionEncType" 取代了 "encType"。
移除 "method"
Draft-05 嘗試恢復 draft-03 的 "method" 行為，但回饋告訴我們，使用者覺得這個變更非常令人困惑。在 "schema" 分割後，draft-05 的 "method" 行為不再需要。
我們可以切換回 draft-04 的 "method" 行為，但除了來回切換會產生更多混淆之外，draft-04 對於 "method" 的處理方式無論如何都與 LDO 設計的其他部分不一致。最值得注意的是，它導致了上述 "targetSchema" 的使用問題。
問：那麼我該如何指示鏈接支援哪些 HTTP 方法？
答：理想情況下，這應由您的連結關係類型隱含傳達，這是機器導向超媒體中整體語義的主要指標。RFC 5988 提供了建立自訂（又稱「擴充」）連結關係的指南。
幾個 URI 方案和命名空間，例如 urn: 方案中的 UUID 命名空間，或者 tag: 方案，特別適用於建立唯一識別符。
當然，也有一些方法可以在執行時偵測到這一點，例如 HTTP 的 "Allow" 回應標頭，或者嘗試一種方法並相應地處理 405 Method Not Allowed 錯誤。
問：不，真的。我如何明確地指出連結支援哪些 HTTP 方法？
答："targetHints" 提案是 draft-07 的一部分，因此將其作為 draft-06 的擴充是一個選項，但我們建議此時直接使用 draft-07。
問：如果 "targetSchema" 不是回應，那麼我該如何描述回應？
答：您應該為您的各種成功和錯誤回應提供超模式，但將它們連結到連結更多是文件問題，而不是使用問題：每個回應都會指出自己的模式，因此您不需要在執行時提前知道它。
從來沒有 Hyper-Schema 關鍵字來明確地將回應與 HTTP 方法等操作關聯起來。這樣的使用案例似乎是關於產生 API 文件，因此這很可能是 JSON Schema API 文件詞彙的候選者。