Draft-06 版本說明

從 zyp-04 和 fge-00 (draft-04) 遷移到 wright-01 (draft-06) 的版本說明。

注意：draft-07 已發布

請注意，draft-07 的核心和驗證與 draft-06 向後相容。如需更多資訊，請參閱該草案的遷移說明。

問：draft-04 和 draft-06 之間有哪些變更？
問：draft-05 發生了什麼事？
問：關於使用 "additionalProperties" 重複使用 schema 的所有討論發生了什麼事？

問：draft-04 和 draft-06 之間有哪些變更？

向後不相容的變更

關鍵字	變更	後果
`"id"`	被 `"$id"` 取代	不再容易與名為 `"id"` 的實例屬性混淆
`"$id"`	取代 `"id"`	行為相同，`$` 前綴與其他兩個核心關鍵字匹配
`"$ref"`	僅允許在預期 schema 的地方	現在可以描述名為 `"$ref"` 的實例屬性
`"exclusiveMinimum"` 和 `"exclusiveMaximum"`	從布林值變更為數字，以符合關鍵字獨立性的原則	無論之前其中一個為真的地方，將值變更為對應的 `"minimum"` 或 `"maximum"` 值，並移除 `"minimum"`/`"maximum"` 關鍵字
`"type"`	`"integer"` 的定義	在 draft-04 中，`"integer"` 被列為基本類型，並定義為「不帶分數或指數部分的 JSON 數字」；在 draft-06 中，`"integer"` 不被視為基本類型，並且僅在關鍵字 `"type"` 的部分中定義為「任何具有零分數部分的數字」；因此，`1.0` 在 draft-04 和更早版本中不是有效的 `"integer"` 類型，但在 draft-06 和更高版本中是有效的 `"integer"` 類型；請注意，兩個草案都說整數應該在 JSON 中編碼，而沒有分數部分

新增和向後相容的變更

關鍵字	變更	後果
布林值作為 schema	允許在任何地方，而不僅僅是 `"additionalProperties"` 和 `"additionalItems"`	`true` 等同於 `{}`，`false` 等同於 `{"not": {}}`，但意圖更明確，且實作可以更容易地最佳化這些情況。
`"propertyNames"`	已新增	接受一個 schema，該 schema 會驗證所有屬性的「名稱」，而不是它們的值。
`"contains"`	已新增	陣列關鍵字，如果其 schema 驗證至少一個陣列項目，則通過驗證。
`"const"`	已新增	單一元素 `"enum"` 更具可讀性的形式。
`"required"`	允許空陣列。	空陣列表示不需要任何屬性。
`"dependencies"`	允許屬性相依性的空陣列。	空陣列表示給定屬性沒有任何相依性。
`"format": "uri-reference"`	已新增	允許每個 RFC 3986 的相對 URI 參考；請參閱下方關於作為格式的 `"uri"` 的章節。
`"format": "uri-template"`	已新增	表示符合 RFC 6570 的 URI 範本值，如同 JSON Hyper-Schema 中用於 `"href"` 的情況。
`"format": "json-pointer"`	已新增	表示 JSON 指標值，例如 `/foo/bar`；請「不要」將其用於 JSON 指標 URI 片段，例如 `#/foo/bar`：這些的正確格式是 `"uri-reference"`。
`"examples"`	已新增	不影響驗證的範例陣列；`"default"` 的值可用作範例，而無需在此關鍵字下重複。

格式：`"uri"` 與 `"uri-reference"`

雖然技術上不是變更，但 "uri" 格式的行為並未清楚說明，且經常被錯誤地實作和使用（包括在 draft-04 元 schema 中）。

只有在需要絕對 URI（以 scheme 開頭）時，才應使用 "uri"。

當允許相對路徑、片段或任何其他樣式的 URI 參考（根據 RFC 3986）時，請使用 "uri-reference"。

提供從 draft-04 轉換到 draft-06 的實作可能希望提供將 "uri" 格式轉換為 "uri-reference" 的選項，但為了嚴格符合規範，任何此類選項都應預設停用。

問：draft-05 發生了什麼事？

draft-05 核心和驗證規範旨在對 draft-04 進行更清晰易讀的重寫，以便為 draft-06 的變更提供穩固的基礎。實作人員應不實作或宣傳對「draft-05」的支援。

透過實作 draft-04 發布後不久的提案來支援「draft-05」的實作，應移除該支援或為其提供不同的名稱，以避免混淆。

問：關於使用 `"additionalProperties"` 重新使用 schema 的所有討論發生了什麼事？

有幾個相互競爭的提案，旨在讓重新使用將 "additionalProperties" 設定為 true 以外的值的 schema。大多數人特別關心它為 false 的情況，但任何非 true 值都會發生相同的行為。

此區域的所有提案將會是 draft-08 的重點。雖然我們在 draft-07 期間在消除一些選項方面取得了進展，但剩餘的分歧足以證明將其作為 draft 的主要重點是合理的（draft-07 的主要重點是 Hyper-Schema）。

困難之處在於，如果您嘗試這樣做

data

{ "type": "object", "allOf": [ { "$ref": "#/definitions/foo" }, { "$ref": "#/definitions/bar" } ], "definitions": { "foo": { "properties": { "foo": { "type": "string" } }, "additionalProperties": false }, "bar": { "properties": { "bar": { "type": "number" } }, "additionalProperties": false } }}

對於任何非空的物件實例，驗證都將始終失敗。"additionalProperties" 只知道直接相鄰的 "properties" 和 "patternProperties"，以確保每個子 schema 無論是與另一個子 schema 一起使用還是單獨使用，都表示相同的含義。

因此，在此範例中，如果實例具有「bar」屬性，它將會因為「bar」不是「foo」而使第一個子 schema 失敗。如果它具有「foo」屬性，它將會因為「foo」不是「bar」而使第二個子 schema 失敗。而任何其他屬性都會使這兩個 schema 失敗。

可以使用新的 "propertyNames" 關鍵字來解決。

data

{ "type": "object", "allOf": [ { "$ref": "#/definitions/foo" }, { "$ref": "#/definitions/bar" } ], "propertyNames": { "anyOf": [ { "$ref": "#/definitions/fooNames" }, { "$ref": "#/definitions/barNames" } ] }, "definitions": { "foo": { "properties": { "foo": { "type": "string" } } }, "fooNames": { "enum": ["foo"] }, "bar": { "properties": { "bar": { "type": "number" } } }, "barNames": { "enum": ["bar"] } }}