| 網際網路工程任務組 | fge. Galiegue，編輯 |
| 網路草案 | |
| 預定狀態：資訊性 | K. Zyp |
| 到期日：2017 年 8 月 26 日 | SitePen（美國） |
| G. Court | |
| 2013 |
JSON Schema：互動式與非互動式驗證
draft-fge-json-schema-validation-00
JSON Schema (application/schema+json) 有數個用途，其中之一是實例驗證。驗證過程可能是互動式或非互動式的。例如，應用程式可以使用 JSON Schema 來建立使用者介面，除了使用者輸入檢查之外，還可以啟用互動式內容產生，或驗證從各種來源擷取的資料。此規格描述了專用於驗證目的的 schema 關鍵字。
本網路草案的提交完全符合 BCP 78 和 BCP 79 的規定。
網路草案是網際網路工程任務組（IETF）的工作文件。請注意，其他群組也可能會以網路草案的形式散佈工作文件。目前網路草案的清單位於 http://datatracker.ietf.org/drafts/current/。
網路草案是有效期最長為六個月的草案文件，並且可能會隨時被其他文件更新、取代或廢止。將網路草案用作參考資料或將其引用為「進行中的工作」以外的其他用途是不適當的。
本網路草案將於 2017 年 8 月 26 日到期。
版權 (c) 2013 IETF Trust 和被識別為文件作者的人員。保留所有權利。
本文件受 BCP 78 和 IETF Trust 的《與 IETF 文件相關的法律條款》（http://trustee.ietf.org/license-info）的約束，該條款於本文件發布之日生效。請仔細閱讀這些文件，因為它們描述了您在本文件方面的權利和限制。從本文件中提取的程式碼元件必須包含 Trust 法律條款第 4.e 節中描述的簡化 BSD 授權文字，並且在沒有簡化 BSD 授權中描述的保固的情況下提供。
JSON Schema 可用於要求給定的 JSON 文件（實例）滿足一定數量的條件。這些條件由本規格中描述的一組關鍵字實現。此外，定義了一組關鍵字來協助互動式實例產生。這些也在本規格中描述。
本規格將使用 JSON Schema 核心規格定義的術語。建議讀者備有一份本規格。
本文件中使用的關鍵字「必須」（MUST）、「不得」（MUST NOT）、「必要」（REQUIRED）、「應當」（SHALL）、「不應當」（SHALL NOT）、「應該」（SHOULD）、「不應該」（SHOULD NOT）、「建議」（RECOMMENDED）、「可能」（MAY）和「可選」（OPTIONAL）應按照 RFC 2119 [RFC2119] 中所述進行解釋。
本規格使用術語「容器實例」來指代陣列和物件實例。它使用術語「子系實例」來指代陣列元素或物件成員值。
本規格使用術語「屬性集」來指代物件的成員名稱集；例如，JSON 物件 { "a": 1, "b": 2 } 的屬性集為 [ "a", "b" ]。
如果陣列值的兩個元素根據核心規格的定義不相等，則認為該陣列中的元素是唯一的。
應該注意的是，空字元（\x00）在 JSON 字串中是有效的。要驗證的實例可能包含具有此字元的字串值，無論基礎程式語言是否能夠處理此類資料。
JSON 規格未定義數值範圍或精度的任何界限。JSON Schema 也沒有定義任何此類界限。這表示 JSON Schema 處理的數值實例可以任意大，和/或具有任意大的十進位部分，無論基礎程式語言是否能夠處理此類資料。
兩個驗證關鍵字「pattern」和「patternProperties」使用正規表示式來表達約束。這些正規表示式應根據 ECMA 262 [ecma262] 正規表示式方言有效。
此外，鑑於正規表示式結構支援的高度差異，schema 作者應將自己限制在以下正規表示式 token：
最後，實作不得認為正規表示式在開頭或結尾處被錨定。這表示，例如，「es」會匹配「expression」。
某些驗證關鍵字僅適用於一個或多個基本類型。當給定關鍵字無法驗證實例的基本類型時，此關鍵字和實例的驗證應當成功。
本規格根據關鍵字驗證的基本類型或多個基本類型，將關鍵字分組到不同的章節中。請注意，某些關鍵字會驗證所有實例類型。
為了驗證實例，某些關鍵字會受到其他關鍵字是否存在（或不存在）的影響。在這種情況下，所有這些關鍵字將在同一章節中分組。
如果缺少某些關鍵字，實作可能會將其視為具有預設值。在這種情況下，將會提到預設值。
可以驗證容器實例（陣列或物件）的關鍵字僅驗證實例本身，而不驗證其子系（陣列項目或物件屬性）。但是，其中一些關鍵字確實包含對於計算子系必須驗證的 schema 來說必要的資訊。計算子系實例相關 schema 的演算法在單獨的章節中說明。
應該注意的是，雖然陣列元素只需要驗證一個 schema，但是物件成員值可能需要驗證多個 schema。
「multipleOf」的值必須是 JSON 數字。此數字必須嚴格大於 0。
若數值實例除以關鍵字的數值後，結果為整數，則此數值實例符合 "multipleOf" 的驗證。
"maximum" 的值必須是 JSON 數字。"exclusiveMaximum" 的值必須是布林值。
如果存在 "exclusiveMaximum"，則 "maximum" 也必須存在。
成功驗證取決於 "exclusiveMaximum" 的存在與值
如果 "exclusiveMaximum" 不存在，則可以視為存在，且其布林值為 false。
"minimum" 的值必須是 JSON 數字。"exclusiveMinimum" 的值必須是布林值。
如果存在 "exclusiveMinimum"，則 "minimum" 也必須存在。
成功驗證取決於 "exclusiveMinimum" 的存在與值
如果 "exclusiveMinimum" 不存在，則可以視為存在，且其布林值為 false。
此關鍵字的值必須是整數。此整數必須大於或等於 0。
如果字串實例的長度小於或等於此關鍵字的值，則此字串實例符合此關鍵字的驗證。
字串實例的長度定義為 RFC 4627 [RFC4627] 定義的字元數。
此關鍵字的值必須是整數。此整數必須大於或等於 0。
如果字串實例的長度大於或等於此關鍵字的值，則此字串實例符合此關鍵字的驗證。
字串實例的長度定義為 RFC 4627 [RFC4627] 定義的字元數。
如果 "minLength" 不存在，則可以視為存在，且其整數值為 0。
此關鍵字的值必須是字串。此字串應為根據 ECMA 262 正則表達式方言的有效正則表達式。
如果正則表達式成功匹配實例，則字串實例被視為有效。請注意：正則表達式並非隱含錨點。
"additionalItems" 的值必須是布林值或物件。如果它是物件，則此物件必須是有效的 JSON Schema。
"items" 的值必須是物件或陣列。如果它是物件，則此物件必須是有效的 JSON Schema。如果它是陣列，則此陣列的元素必須是物件，且每個物件都必須是有效的 JSON Schema。
針對這兩個關鍵字，陣列實例的成功驗證方式如下
以下範例涵蓋 "additionalItems" 的布林值為 false 且 "items" 為陣列的情況，因為這是實例可能無法成功驗證的唯一情況。
這是一個範例綱要
{
"items": [ {}, {}, {} ],
"additionalItems": false
}
使用此綱要，以下實例為有效
以下實例為無效
如果缺少任一關鍵字，則可以將其視為存在，且其值為空綱要。
此關鍵字的值必須是整數。此整數必須大於或等於 0。
如果陣列實例的大小小於或等於此關鍵字的值，則此陣列實例符合 "maxItems" 的驗證。
此關鍵字的值必須是整數。此整數必須大於或等於 0。
如果陣列實例的大小大於或等於此關鍵字的值，則此陣列實例符合 "minItems" 的驗證。
如果此關鍵字不存在，則可以將其視為存在，且其值為 0。
此關鍵字的值必須是布林值。
如果此關鍵字的布林值為 false，則實例成功驗證。如果其布林值為 true，則當實例的所有元素都唯一時，此實例成功驗證。
如果不存在，則可以將此關鍵字視為存在，且其布林值為 false。
此關鍵字的值必須是整數。此整數必須大於或等於 0。
如果物件實例的屬性數小於或等於此關鍵字的值，則此物件實例符合 "maxProperties" 的驗證。
此關鍵字的值必須是整數。此整數必須大於或等於 0。
如果物件實例的屬性數大於或等於此關鍵字的值，則此物件實例符合 "minProperties" 的驗證。
如果此關鍵字不存在，則可以將其視為存在，且其值為 0。
此關鍵字的值必須是陣列。此陣列必須至少有一個元素。此陣列的元素必須是字串，且必須是唯一的。
如果物件實例的屬性集包含此關鍵字陣列值的所有元素，則此物件實例符合此關鍵字的驗證。
"additionalProperties" 的值必須是布林值或物件。如果它是物件，則它也必須是有效的 JSON Schema。
"properties" 的值必須是物件。此物件的每個值都必須是物件，且每個物件都必須是有效的 JSON Schema。
"patternProperties" 的值必須是物件。此物件的每個屬性名稱都應為根據 ECMA 262 正則表達式方言的有效正則表達式。此物件的每個屬性值都必須是物件，且每個物件都必須是有效的 JSON Schema。
物件實例針對這三個關鍵字的成功驗證取決於 "additionalProperties" 的值
如果 "properties" 或 "patternProperties" 不存在，則可以將其視為存在，且其值為空物件。
如果 "additionalProperties" 不存在，則可以將其視為存在，且其值為空綱要。
在這種情況下，實例的驗證取決於 "properties" 和 "patternProperties" 的屬性集。在本節中，為方便起見，"patternProperties" 的屬性名稱將稱為正則表達式。
第一步是收集以下集合
收集完這三個集合後，流程如下
如果在這兩個步驟之後，集合 "s" 為空，則實例的驗證成功。
此綱要將用作範例
{
"properties": {
"p1": {}
},
"patternProperties": {
"p": {},
"[0-9]": {}
},
"additionalProperties": false
}
這是要驗證的實例
{
"p1": true,
"p2": null,
"a32&o": "foobar",
"": [],
"fiddle": 42,
"apple": "pie"
}
這三個屬性集為
套用演算法的兩個步驟
集合 "s" 仍然包含兩個元素 "" 和 "fiddle"。因此驗證失敗。
此關鍵字的值必須是物件。此物件的每個值都必須是物件或陣列。
如果值為物件，則它必須是有效的 JSON Schema。這稱為綱要相依性。
如果值為陣列，則它必須至少有一個元素。每個元素都必須是字串，且陣列中的元素必須是唯一的。這稱為屬性相依性。
針對所有綱要相依性的 (名稱, 綱要) 配對，如果實例具有此名稱的屬性，則它也必須成功通過針對綱要的驗證。
請注意，必須成功驗證的是實例本身，而不是與屬性名稱相關聯的值。
針對每個屬性相依性的 (名稱, 屬性集) 配對，如果實例具有此名稱的屬性，則它也必須具有與屬性集相同名稱的屬性。
此關鍵字的值必須為陣列。此陣列必須至少有一個元素。陣列中的元素必須是唯一的。
陣列中的元素可以是任何類型，包括 null。
如果實例的值等於此關鍵字的陣列值中的其中一個元素，則此實例成功通過此關鍵字的驗證。
此關鍵字的值必須是字串或陣列。如果它是陣列，則陣列中的元素必須是字串，並且必須是唯一的。
字串值必須是核心規範定義的七種基本類型之一。
如果實例的基本類型是關鍵字定義的其中一種類型，則此實例成功匹配。請注意：「number」包含「integer」。
此關鍵字的值必須為陣列。此陣列必須至少有一個元素。
陣列中的元素必須是物件。每個物件都必須是有效的 JSON Schema。
如果實例成功通過此關鍵字的值定義的所有 Schema 的驗證，則此實例成功通過此關鍵字的驗證。
此關鍵字的值必須為陣列。此陣列必須至少有一個元素。
陣列中的元素必須是物件。每個物件都必須是有效的 JSON Schema。
如果實例成功通過此關鍵字的值定義的至少一個 Schema 的驗證，則此實例成功通過此關鍵字的驗證。
此關鍵字的值必須為陣列。此陣列必須至少有一個元素。
陣列中的元素必須是物件。每個物件都必須是有效的 JSON Schema。
如果實例成功通過此關鍵字的值定義的正好一個 Schema 的驗證，則此實例成功通過此關鍵字的驗證。
此關鍵字的值必須是一個物件。此物件必須是有效的 JSON Schema。
如果實例未能成功通過此關鍵字定義的 Schema 的驗證，則此實例對於此關鍵字有效。
此關鍵字的值必須是一個物件。此物件的每個成員值都必須是有效的 JSON Schema。
此關鍵字本身在驗證中不起作用。它的作用是為 Schema 作者提供一個標準化的位置，將 JSON Schema 內嵌到更通用的 Schema 中。
{
"type": "array",
"items": { "$ref": "#/definitions/positiveInteger" },
"definitions": {
"positiveInteger": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true
}
}
}
舉例來說，這是一個描述正整數陣列的 Schema，其中正整數的限制是「definitions」中的子 Schema
這兩個關鍵字的值都必須是字串。
這兩個關鍵字都可以用來裝飾使用者介面，提供關於此使用者介面產生之資料的資訊。標題最好簡短，而描述則提供關於此 Schema 所描述之實例的用途的解釋。
這兩個關鍵字可以被用於根 Schema，以及任何子 Schema 中。
對於此關鍵字的值沒有任何限制。
此關鍵字可以用來提供與特定 Schema 相關聯的預設 JSON 值。建議預設值應對於相關聯的 Schema 有效。
此關鍵字可以被用於根 Schema，以及任何子 Schema 中。
單獨的結構驗證可能不足以驗證實例是否滿足應用程式的所有要求。定義「format」關鍵字是為了允許針對由權威資源（無論是 RFC 或其他外部規範）準確描述的固定子集值進行可互操作的語義驗證。
此關鍵字的值稱為格式屬性。它必須是字串。格式屬性通常只能驗證一組給定的實例類型。如果要驗證的實例類型不在這個集合中，則此格式屬性和實例的驗證應成功。
實作可以支援「format」關鍵字。如果他們選擇這樣做
實作可以新增自訂的格式屬性。除非各方之間達成協議，否則 Schema 作者不應期望同級實作支援此關鍵字和/或自訂的格式屬性。
此屬性適用於字串實例。
如果字串實例是 RFC 3339, section 5.6 [RFC3339] 定義的有效日期表示形式，則此字串實例對於此屬性有效。
此屬性適用於字串實例。
如果字串實例是 RFC 5322, section 3.4.1 [RFC5322] 定義的有效網際網路電子郵件地址，則此字串實例對於此屬性有效。
此屬性適用於字串實例。
如果字串實例是 RFC 1034, section 3.1 [RFC1034] 定義的有效網際網路主機名稱表示形式，則此字串實例對於此屬性有效。
此屬性適用於字串實例。
如果字串實例是 RFC 2673, section 3.2 [RFC2673] 定義的「點分四組」ABNF 語法的有效 IPv4 地址表示形式，則此字串實例對於此屬性有效。
此屬性適用於字串實例。
如果字串實例是 RFC 2373, section 2.2 [RFC2373] 定義的有效 IPv6 地址表示形式，則此字串實例對於此屬性有效。
此屬性適用於字串實例。
如果字串實例是 [RFC3986] 定義的有效 URI，則此字串實例對於此屬性有效。
計算子實例必須驗證的 Schema 或 Schema 受到以下因素的影響
此外，重要的是，如果在計算中隱含的一個或多個關鍵字未定義，則應將它們視為存在，並使用它們的預設值，這將在本節中回顧。
子實例的定義特徵是其在陣列中的索引。請注意：陣列索引從 0 開始。
此計算中兩個隱含的關鍵字是「items」和「additionalItems」。
如果任一關鍵字不存在，則將其視為存在，且其值為空 Schema。此外，「additionalItems」的布林值 true 被視為等同於空 Schema。
如果「items」是一個 Schema，則子實例必須對於此 Schema 有效，無論其索引如何，也無論「additionalItems」的值如何。
在這種情況下，Schema 取決於索引
定義特徵是子元素的屬性名稱。
此計算中隱含的三個關鍵字是「properties」、「patternProperties」和「additionalProperties」。
如果「properties」或「patternProperties」不存在，則將其視為存在，且其值為空物件。
如果「additionalProperties」不存在，則將其視為存在，且其值為空 Schema。此外，布林值 true 被視為等同於空 Schema。
以下計算使用以下名稱
如果集合「p」包含值「m」，則將「properties」中的對應 Schema 新增至「s」。
對於「pp」中的每個 regex，如果它成功匹配「m」，則將「patternProperties」中的對應 Schema 新增至「s」。
當且僅當在此階段，「s」為空時，才將「additionalProperties」定義的 Schema 新增至「s」。
JSON Schema 驗證沒有任何超出 JSON Schema 核心規範定義的安全考量。
此規範對於 IANA 沒有任何影響。
| [RFC2119] | Bradner, S., "在 RFC 中用於表示需求層級的關鍵字", BCP 14, RFC 2119, DOI 10.17487/RFC2119, 1997 年 3 月。 |
| [RFC1034] | Mockapetris, P., "網域名稱 - 概念與設施", STD 13, RFC 1034, DOI 10.17487/RFC1034, 1987 年 11 月。 |
| [RFC2373] | Hinden, R. 和 S. Deering, "IP 第 6 版定址架構", RFC 2373, DOI 10.17487/RFC2373, 1998 年 7 月。 |
| [RFC2673] | Crawford, M., "網域名稱系統中的二進制標籤", RFC 2673, DOI 10.17487/RFC2673, 1999 年 8 月。 |
| [RFC3339] | Klyne, G. 和 C. Newman, "網際網路上的日期和時間：時間戳記", RFC 3339, DOI 10.17487/RFC3339, 2002 年 7 月。 |
| [RFC3986] | Berners-Lee, T., Fielding, R. 和 L. Masinter, "統一資源識別符 (URI)：通用語法", STD 66, RFC 3986, DOI 10.17487/RFC3986, 2005 年 1 月。 |
| [RFC4627] | Crockford, D., "JavaScript 物件表示法 (JSON) 的 application/json 媒體類型", RFC 4627, DOI 10.17487/RFC4627, 2006 年 7 月。 |
| [RFC5322] | Resnick, P., "網際網路訊息格式", RFC 5322, DOI 10.17487/RFC5322, 2008 年 10 月。 |
| [ecma262] | ECMA 262 規範" |