| 網際網路工程任務組 | F. Galiegue, Ed. |
| 網際網路草案 | |
| 預期狀態：資訊性 | K. Zyp, Ed. |
| 到期日：2017 年 8 月 26 日 | SitePen (美國) |
| G. Court | |
| 2013 |
JSON 綱要：核心定義與術語
draft-zyp-json-schema-04
JSON 綱要定義了媒體類型「application/schema+json」，這是一種基於 JSON 的格式，用於定義 JSON 資料的結構。JSON 綱要為給定應用程式所需的 JSON 資料以及如何與之互動提供了合約。JSON 綱要旨在定義 JSON 資料的驗證、文件、超連結導航和互動控制。
本網際網路草案的提交完全符合 BCP 78 和 BCP 79 的規定。
網際網路草案是網際網路工程任務組 (IETF) 的工作文件。請注意，其他群組也可能將工作文件作為網際網路草案發佈。目前網際網路草案的清單位於 http://datatracker.ietf.org/drafts/current/。
網際網路草案是有效期最長為六個月的草案文件，並且可能會隨時被其他文件更新、取代或廢棄。將網際網路草案用作參考資料或將其引用為「進行中的工作」以外的任何用途都是不恰當的。
本網際網路草案將於 2017 年 8 月 26 日到期。
版權所有 © 2013 IETF Trust 及被識別為文件作者的人士。保留所有權利。
本文件受 BCP 78 和 IETF Trust 有關 IETF 文件的法律條款 (http://trustee.ietf.org/license-info) 的約束，該條款在本文件發佈之日生效。請仔細閱讀這些文件，因為它們描述了您在本文件方面的權利和限制。從本文件中提取的程式碼元件必須包含 Trust 法律條款第 4.e 節中描述的簡化 BSD 許可證文本，並且在簡化 BSD 許可證中描述的情況下提供，不提供任何擔保。
JSON 綱要是一種 JSON 媒體類型，用於定義 JSON 資料的結構。JSON 綱要為給定應用程式所需的 JSON 資料以及如何與之互動提供了合約。JSON 綱要旨在定義 JSON 資料的驗證、文件、超連結導航和互動控制。
本規範定義了 JSON 綱要核心術語和機制；相關規範以此規範為基礎，並定義了 JSON 綱要的不同應用。
本文件中使用的關鍵字「MUST」（必須）、「MUST NOT」（不得）、「REQUIRED」（必要）、「SHALL」（應當）、「SHALL NOT」（不應當）、「SHOULD」（應該）、「SHOULD NOT」（不應該）、「RECOMMENDED」（建議）、「MAY」（可以）和「OPTIONAL」（可選）應按照 RFC 2119 [RFC2119] 中的說明進行解釋。
本文件中使用的術語「JSON」、「JSON 文字」、「JSON 值」、「成員」、「元素」、「物件」、「陣列」、「數字」、「字串」、「布林值」、「true」、「false」和「null」應按照 RFC 4627 [RFC4627] 中的定義進行解釋。
當引用 [RFC4627] 定義的 JSON 物件時，術語「成員」和「屬性」可以互換使用。
當引用 [RFC4627] 定義的 JSON 陣列時，術語「元素」和「項目」可以互換使用。
JSON 綱要是一個 JSON 文件，並且該文件必須是一個物件。由 JSON 綱要（本規範或相關規範）定義的物件成員（或屬性）稱為關鍵字或綱要關鍵字。
JSON 綱要可以包含不是綱要關鍵字的屬性。
空綱要是一個沒有屬性或其屬性不是綱要關鍵字的 JSON 綱要。
此 JSON 綱要範例沒有子綱要
{
"title": "root"
}
JSON 綱要也可以巢狀，如以下範例所示
{
"title": "root",
"otherSchema": {
"title": "nested",
"anotherSchema": {
"title": "alsoNested"
}
}
}
在此範例中，「nested」和「alsoNested」是子綱要，「root」是根綱要。
JSON 綱要為 JSON 值定義了七種基本類型
當且僅當以下情況時，兩個 JSON 值才被認為相等
實例是任何 JSON 值。一個實例可以由一個或多個綱要描述。
實例也可以稱為「JSON 實例」或「JSON 資料」。
本文件提出了一種新的媒體類型「application/schema+json」，以識別用於描述 JSON 資料的 JSON 綱要。JSON 綱要本身以 JSON 撰寫。本規範和相關規範定義了關鍵字，允許根據允許的值、文字描述和解釋與其他資源的關係來描述這些資料。以下章節是相關規範定義的功能摘要。
JSON 綱要允許應用程式驗證實例，無論是非互動式還是互動式。例如，應用程式可以收集 JSON 資料並檢查此資料是否符合給定的一組約束；另一個應用程式可以使用 JSON 綱要來建立互動式介面，以便根據 JSON 綱要描述的約束收集使用者輸入。
JSON 綱要提供了一種方法，用於從實例中提取到其他資源的連結關係，以及描述實例作為多媒體資料的解釋。這允許將 JSON 資料解釋為豐富的超媒體文件，放置在更大的相關資源集中。
公認的是，實例可以是 [RFC4627] 定義的任何有效 JSON 值。因此，JSON 綱要不強制規定實例必須是特定類型：JSON 綱要可以描述任何 JSON 值，包括 null 值。
JSON 綱要是與程式語言無關的。唯一的限制是 [RFC4627] 和主機程式語言的限制。
本規範承認 HTTP [RFC2616] 作為網際網路上使用的主要協定，及其相關的豐富官方規範。
本規範使用這些規範的子集，建議一組機制，可由本協定使用，將 JSON 實例與一個或多個綱要相關聯。
JSON 綱要未定義 HTTP 以外的任何其他協定的客戶端-伺服器介面的任何語義。這些語義取決於應用程式，或取決於參與使用 JSON 綱要以滿足自身需求的各方之間的協議。
本規範承認，某些程式語言及其關聯的剖析器對浮點數和整數使用不同的內部表示形式，而其他程式語言則不使用。
因此，出於互通性原因，在 JSON 綱要內容中使用的 JSON 值（無論該 JSON 是 JSON 綱要還是實例）應確保數學整數表示為本規範定義的整數。
實作可以選擇定義 JSON 綱要的其他關鍵字。除非有明確協議，否則綱要作者不得期望同級實作支援這些其他關鍵字。實作應忽略它們不支援的關鍵字。
綱要和實例都是 JSON 值。因此，適用 RFC 4627 [RFC4627] 中定義的所有安全性考量。
「$schema」關鍵字既用作 JSON 綱要版本識別碼，又用作資源位置，該資源本身是一個 JSON 綱要，用於描述針對此特定版本撰寫的任何綱要。
此關鍵字必須位於 JSON 綱要的根目錄。此關鍵字的值必須是 URI [RFC3986] 和有效的 JSON 參考 [json-reference]；此 URI 必須是絕對且正規化的。位於此 URI 的資源必須成功地自我描述。建議綱要作者在其綱要中包含此關鍵字。
以下值為預先定義的值
當使用自訂關鍵字擴展 JSON Schema 時，綱要作者應為 "$schema" 定義一個自訂 URI。此自訂 URI 不得為預定義值之一。
JSON Schema 使用 JSON Reference [json-reference] 作為綱要尋址機制。它透過以下兩種方式擴展此規範：
在綱要中變更 URI 稱為定義新的解析範圍。綱要的初始解析範圍是綱要本身的 URI（如果有的話），如果綱要不是從 URI 載入，則為空 URI。
此關鍵字的值必須為字串，且必須為有效的 URI。此 URI 必須經過正規化，且不應為空片段 (#) 或空 URI。
"id" 關鍵字（或簡稱 "id"）用於變更解析範圍。當遇到 id 時，實作必須將此 id 解析為最直接的父範圍。解析後的 URI 將成為此子綱要及其所有子項目的新解析範圍，直到遇到另一個 id 為止。
當使用 "id" 來變更解析範圍時，綱要作者應確保解析範圍在綱要內是唯一的。
此綱要將作為範例
{
"id": "http://x.y.z/rootschema.json#",
"schema1": {
"id": "#foo"
},
"schema2": {
"id": "otherschema.json",
"nested": {
"id": "#bar"
},
"alsonested": {
"id": "t/inner.json#a"
}
},
"schema3": {
"id": "some://where.else/completely#"
}
}
以下 URI 編碼的 JSON 指標 [json-pointer]（從根綱要開始）的子綱要定義了以下解析範圍
在針對解析範圍解析 URI 時，實作可以選擇兩種操作模式
實作必須支援標準取消引用，且可以支援內嵌取消引用。
例如，考量此綱要
{
"id": "http://my.site/myschema#",
"definitions": {
"schema1": {
"id": "schema1",
"type": "integer"
},
"schema2", {
"type": "array",
"items": { "$ref": "schema1" }
}
}
}
當實作遇到 "schema1" 參考時，它會針對最直接的父範圍解析它，從而產生 URI "http://my.site/schema1#"。根據選擇的取消引用模式，處理此 URI 的方式將會不同
當使用內嵌取消引用時，解析範圍可能會產生具有非空片段部分的 URI，該片段部分不是 JSON 指標，如此範例所示
{
"id": "http://some.site/schema#",
"not": { "$ref": "#inner" },
"definitions": {
"schema1": {
"id": "#inner",
"type": "boolean"
}
}
}
選擇支援內嵌取消引用的實作應該能夠使用此類型的參考。但是，選擇使用標準取消引用的實作不一定需要支援它。
內嵌取消引用可能會產生與根綱要的標準 URI 不同的標準 URI。綱要作者應確保使用標準取消引用的實作所取得的內容與使用內嵌取消引用的實作相同。
選擇不支援內嵌取消引用的實作無法取消引用使用非 JSON 指標的片段的擴展 JSON Reference。此類型的參考是為了向後相容性而定義的，不應在新綱要中使用。
本規範承認，大多數互動式 JSON Schema 處理都將透過 HTTP 進行。因此，本節提供了使用此通訊協定目前可用的機制來實現執行個體/綱要關聯的建議。執行個體據說由一個（或多個）綱要描述。
建議將名為 "profile" 的 MIME 類型參數附加到正在處理的執行個體的 "Content-Type" 標頭。如果存在，此參數的值必須為有效的 URI，且此 URI 應解析為有效的 JSON Schema。MIME 類型必須為 "application/json" 或任何其他子類型。
此標頭的範例如下
Content-Type: application/my-media-type+json;
profile=http://example.com/my-hyper-schema#
當使用 "Link" 標頭時，使用的關係類型必須為 "describedBy"，如 RFC 5988, section 5.3 [RFC5988] 中所定義。 "Link" 標頭的目標 URI 必須為有效的 JSON Schema。
此標頭的範例如下
Link: <http://example.com/my-hyper-schema#>; rel="describedBy"
JSON Schema 的擬議 MIME 媒體類型定義如下
| [RFC2119] | Bradner, S., "在 RFC 中用於指示要求層級的關鍵字", BCP 14, RFC 2119, DOI 10.17487/RFC2119, 1997 年 3 月。 |
| [RFC2616] | Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. 和 T. Berners-Lee, "超文字傳輸通訊協定 -- HTTP/1.1", RFC 2616, DOI 10.17487/RFC2616, 1999 年 6 月。 |
| [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 月。 |
| [RFC5988] | Nottingham, M., "Web 連結", RFC 5988, DOI 10.17487/RFC5988, 2010 年 10 月。 |
| [json-reference] | Bryan, P. 和 K. Zyp, "JSON Reference（進行中）", 2012 年 9 月。 |
| [json-pointer] | Bryan, P. 和 K. Zyp, "JSON 指標（進行中）", 2012 年 9 月。 |
| [json-schema-03] | Court, G. 和 K. Zyp, "JSON Schema, draft 3", 2012 年 9 月。 |