網際網路工程任務組 A. Wright,編輯
網際網路草案
預期狀態:資訊性 H. Andrews,編輯
到期日:2018 年 9 月 20 日 Cloudflare 公司
2018 年 3 月 19 日

JSON Schema:用於描述 JSON 文件的媒體類型
draft-handrews-json-schema-01

摘要

JSON Schema 定義了媒體類型 "application/schema+json",這是一種基於 JSON 的格式,用於描述 JSON 資料的結構。JSON Schema 斷言 JSON 文件必須看起來像什麼、如何從中提取資訊以及如何與之互動。"application/schema-instance+json" 媒體類型提供了與 "application/schema+json" 更豐富的功能整合,超越了 "application/json" 文件所能提供的功能。

讀者須知

本草案的問題清單可在 <https://github.com/json-schema-org/json-schema-spec/issues> 找到。

如需其他資訊,請參閱 <https://json-schema.dev.org.tw/>

如要提供意見回饋,請使用此問題追蹤器、首頁上列出的通訊方法或寄電子郵件給文件編輯人員。

本備忘錄的狀態

本網際網路草案的提交完全符合 BCP 78 和 BCP 79 的規定。

網際網路草案是網際網路工程任務組 (IETF) 的工作文件。請注意,其他群組也可能將工作文件作為網際網路草案發佈。目前網際網路草案的清單位於 http://datatracker.ietf.org/drafts/current/。

網際網路草案是有效期最長為六個月的草案文件,並且可能隨時被其他文件更新、取代或廢棄。將網際網路草案用作參考資料或將其引用為「正在進行的工作」以外的用途是不適當的。

本網際網路草案將於 2018 年 9 月 20 日到期。

著作權聲明

版權所有 (c) 2018 IETF Trust 和被認定為文件作者的人士。保留所有權利。

本文件受 BCP 78 和 IETF Trust 與 IETF 文件相關的法律條款 (http://trustee.ietf.org/license-info) 的約束,這些條款在本文件發佈之日生效。請仔細審閱這些文件,因為它們描述了您對於本文件的權利和限制。從本文件中提取的程式碼元件必須包含「簡化的 BSD 授權」文字,如 Trust 法律條款第 4.e 節所述,並且不提供任何擔保,如「簡化的 BSD 授權」中所述。


目錄

1. 簡介

JSON Schema 是一種 JSON 媒體類型,用於定義 JSON 資料的結構。JSON Schema 旨在定義 JSON 資料的驗證、文件、超連結導覽和互動控制。

本規範定義了 JSON Schema 的核心術語和機制,包括透過參考指向另一個 JSON Schema、取消參考 JSON Schema 參考以及指定正在使用的詞彙表。

其他規範定義了執行有關驗證、連結、註解、導覽和互動的斷言的詞彙表。

2. 慣例和術語

本文件中使用的關鍵字「必須 (MUST)」、「不得 (MUST NOT)」、「必要 (REQUIRED)」、「應 (SHALL)」、「不得 (SHALL NOT)」、「應該 (SHOULD)」、「不應該 (SHOULD NOT)」、「建議 (RECOMMENDED)」、「可以 (MAY)」和「可選 (OPTIONAL)」應按照 RFC 2119 [RFC2119] 中的說明進行解釋。

本文件中使用的術語「JSON」、「JSON 文字」、「JSON 值」、「成員」、「元素」、「物件」、「陣列」、「數字」、「字串」、「布林值」、「true」、「false」和「null」應按照 RFC 7159 [RFC7159] 中的定義進行解釋。

3. 概述

本文件提出一種新的媒體類型 "application/schema+json",以識別用於描述 JSON 資料的 JSON Schema。它還提出了一種可選的媒體類型 "application/schema-instance+json",以提供額外的整合功能。JSON Schema 本身就是 JSON 文件。本文件和相關規範定義了允許作者以多種方式描述 JSON 資料的關鍵字。

3.1. 驗證

JSON Schema 描述 JSON 文件的結構 (例如,必要的屬性和長度限制)。應用程式可以使用此資訊來驗證實例 (檢查是否滿足約束) 或通知介面收集使用者輸入,以滿足約束。

驗證行為和關鍵字在單獨的文件 [json-schema-validation] 中指定。

3.2. 註解

每當實例針對包含註解的 schema 物件及其所有父 schema 物件進行驗證時,JSON Schema 就可以使用資訊註解實例。

詳細的註解行為以及一小組基本的註解關鍵字在驗證規範 [json-schema-validation] 中定義。

3.3. 超媒體和連結

JSON Hyper-Schema 描述 JSON 文件的超文字結構。這包括從實例到其他資源的連結關係、將實例解釋為多媒體資料,以及使用 API 所需的提交資料。

超 schema 行為和關鍵字在單獨的文件 [json-hyper-schema] 中指定。

4. 定義

4.1. JSON 文件

JSON 文件是由 application/json 媒體類型描述的資訊資源 (位元組序列)。

在 JSON Schema 中,由於它定義的資料模型,「JSON 文件」、「JSON 文字」和「JSON 值」這幾個術語可以互換使用。

JSON Schema 僅針對 JSON 文件定義。但是,可以根據 JSON Schema 資料模型解析或處理的任何文件或記憶體結構都可以針對 JSON Schema 進行解釋,包括像 CBOR [RFC7049] 這樣的媒體類型。

4.2. 實例

應用 schema 的 JSON 文件稱為「實例」。

4.2.1. 實例資料模型

JSON Schema 根據資料模型解釋文件。根據此資料模型解釋的 JSON 值稱為「實例」。

實例具有六種基本類型之一,並且根據類型具有一系列可能的值

null
JSON「null」產生式
boolean
JSON「true」或「false」產生式中的「true」或「false」值
object
來自 JSON「object」產生式的屬性的無序集合,將字串對應到實例
array
來自 JSON「array」產生式的實例的有序列表
number
來自 JSON「number」產生式的任意精度的十進制數值
string
來自 JSON「string」產生式的 Unicode 字碼點字串

因此,空白和格式方面的考量,包括資料模型中相等的數字的不同語彙表示,都超出了 JSON Schema 的範圍。希望使用語彙表示中此類差異的 JSON Schema 詞彙表 [vocabulary] 應定義關鍵字,以精確解釋資料模型中格式化的字串,而不是依賴於可用的原始 JSON 表示的 Unicode 字元。

由於物件不能有兩個具有相同鍵的屬性,因此在單一物件中嘗試定義兩個具有相同鍵 (「字串」產生式) 的屬性 (「成員」產生式) 的 JSON 文件的行為是未定義的。

請注意,JSON Schema 詞彙表可以自由定義它們自己的擴充類型系統。這不應與此處定義的核心資料模型類型混淆。例如,「integer」對於詞彙表來說是一個合理的類型,可以將其定義為關鍵字的值,但資料模型不區分整數和其他數字。

4.2.2. 實例媒體類型

JSON Schema 旨在完全適用於 "application/json" 文件,以及使用 "+json" 結構化語法尾碼的媒體類型。

每個媒體類型都定義了一些對於使用 schema 有用的功能,即媒體類型參數和 URI 片段識別碼語法和語義。這些功能對於內容協商和計算實例中特定位置的 URI 非常有用。

本規範定義了 "application/schema-instance+json" 媒體類型,以允許實例作者充分利用參數和片段識別碼來達到這些目的。

4.2.3. 實例相等性

當且僅當兩個 JSON 實例的類型相同並且根據資料模型具有相同的值時,它們才被認為是相等的。具體來說,這表示

此定義隱含陣列長度必須相同,物件成員數量必須相同,物件中的屬性是無序的,無法定義具有相同鍵值的多個屬性,且單純的格式差異(縮排、逗號位置、尾隨零)是無意義的。

4.3. JSON Schema 文件

JSON Schema 文件,簡稱 schema,是用於描述實例的 JSON 文件。 schema 本身被解釋為一個實例,但應該始終給予媒體類型 "application/schema+json",而不是 "application/schema-instance+json"。"application/schema+json" 媒體類型被定義為提供 "application/schema-instance+json" 所提供的媒體類型參數和片段識別符號語法及語義的超集。

4.3.1. JSON Schema 值和關鍵字

JSON Schema 必須是一個物件或布林值。

應用於實例的物件屬性稱為關鍵字,或 schema 關鍵字。廣義來說,關鍵字可分為以下兩個類別中的一者或兩者:

斷言
應用於實例時產生布林值結果
註解
將資訊附加到實例以供應用程式使用

關鍵字可以屬於以上任一或兩個類別。擴展關鍵字,意指在本文件及其附屬文件之外定義的關鍵字,也可以自由定義其他行為。

布林值 schema "true" 和 "false" 是微不足道的斷言,無論實例值為何,總是回傳自身。舉例來說,就驗證詞彙而言,布林值 schema 等同於以下行為:

true
總是通過驗證,如同空 schema {}
false
總是無法通過驗證,如同 schema { "not":{} }

JSON Schema 可以包含非 schema 關鍵字的屬性。未知的關鍵字應該被忽略。

空的 schema 是沒有屬性,或只有未知屬性的 JSON Schema。

4.3.2. JSON Schema 詞彙

JSON Schema 詞彙是一組為特定目的定義的關鍵字。詞彙指定其關鍵字作為斷言、註解和/或任何詞彙定義的關鍵字類別的含義。本文件的兩個附屬標準各自定義了一個詞彙:一個用於實例驗證,另一個用於超媒體註解。詞彙是 JSON Schema 媒體類型內可擴展的主要機制。

任何實體都可以定義詞彙。如果詞彙預期廣泛使用,並可能與其他詞彙組合,則詞彙作者應注意避免關鍵字名稱衝突。JSON Schema 沒有提供任何正式的命名空間系統,但也沒有限制關鍵字名稱,允許任何數量的命名空間方法。

詞彙可以互相建構,例如透過定義其關鍵字相對於另一個詞彙的關鍵字行為的行為,或透過使用另一個詞彙的關鍵字,並限制或擴展可接受值的集合。並非所有此類詞彙重用都會產生與其所建構的詞彙相容的新詞彙。詞彙作者應清楚記錄預期的相容性程度(如果有的話)。

本身描述 schema 的 schema 稱為 meta-schema。Meta-schema 用於驗證 JSON Schema 並指定它正在使用的詞彙。[CREF1]目前,每個 schema 只能指定一個 meta-schema,這表示要使用多個詞彙,必須撰寫一個包含所有詞彙的 meta-schema。超媒體 meta-schema 就是一個例子,它包含驗證詞彙以及超媒體詞彙。

4.3.3. 根 Schema 和子 Schema

根 schema 是包含有問題的整個 JSON 文件的 schema。

某些關鍵字本身採用 schema,允許 JSON Schema 巢狀化

{
    "title": "root",
    "items": {
        "title": "array item"
    }
}

                        

在此範例文件中,名為「array item」的 schema 是子 schema,而名為「root」的 schema 是根 schema。

與根 schema 相同,子 schema 也是物件或布林值。

5. 片段識別符號

根據 [RFC6839] 的 3.1 節,針對任何 +json 媒體類型指定的片段識別符號的語法和語義,應如針對 "application/json" 所指定的。(在本文件發布時,沒有為 "application/json" 定義片段識別語法。)

此外,"application/schema+json" 媒體類型支援兩種片段識別符號結構:純名稱和 JSON 指標。"application/schema-instance+json" 媒體類型支援一種片段識別符號結構:JSON 指標。

JSON 指標作為 URI 片段識別符號的使用方式在 RFC 6901 [RFC6901] 中描述。對於支援兩種片段識別符號語法的 "application/schema+json",符合 JSON 指標語法的片段識別符號(包括空字串)必須解釋為 JSON 指標片段識別符號。

根據 W3C 的 片段識別符號最佳實務 [W3C.WD-fragid-best-practices-20121025],"application/schema+json" 中的純名稱片段識別符號保留用於引用本地命名的 schema。所有不符合 JSON 指標語法的片段識別符號都必須解釋為純名稱片段識別符號。

在 "application/schema+json" 文件中定義和參考純名稱片段識別符號,在 "$id" 關鍵字 [id-keyword] 區段中指定。

6. 一般考量

6.1. JSON 值的範圍

實例可以是 JSON [RFC7159] 定義的任何有效 JSON 值。JSON Schema 對類型沒有任何限制:JSON Schema 可以描述任何 JSON 值,包括 null 值。

6.2. 程式語言獨立性

JSON Schema 與程式語言無關,並支援資料模型中描述的所有值範圍。但是請注意,某些語言和 JSON 解析器可能無法在記憶體中表示 JSON 可描述的所有值範圍。

6.3. 數學整數

某些程式語言和解析器對浮點數使用與整數不同的內部表示法。

為了保持一致性,整數 JSON 數字不應使用小數部分編碼。

6.4. 擴展 JSON Schema

實作可以為 JSON Schema 定義其他關鍵字。除非有明確的協議,否則 schema 作者不得期望對等實作支援這些額外的關鍵字。實作應該忽略它們不支援的關鍵字。

鼓勵 JSON Schema 擴展的作者編寫他們自己的 meta-schema,使用 "allOf" 擴展現有的 meta-schema。應該使用 "$schema" 關鍵字來參考此擴展的 meta-schema,以允許工具遵循正確的行為。

請注意,meta-schema 的遞迴性質需要在擴展的 meta-schema 中重新定義遞迴關鍵字,如 JSON 超媒體 Schema meta-schema 中所示。

7. "$schema" 關鍵字

"$schema" 關鍵字既用作 JSON Schema 版本識別符號,也用作資源的位置,該資源本身是一個 JSON Schema,描述為此特定版本撰寫的任何 schema。

此關鍵字的值必須是一個 URI [RFC3986] (包含 scheme),並且此 URI 必須正規化。目前的 schema 必須針對此 URI 識別的 meta-schema 驗證為有效。

如果此 URI 識別可擷取的資源,則該資源的媒體類型應為 "application/schema+json"。

"$schema" 關鍵字應在根 schema 中使用。它不得出現在子 schema 中。

[CREF2]在同一文件中使用多個 "$schema" 關鍵字,表示詞彙,因此行為可能會在文件中變更。這將需要解決許多尚未明確定義的實作問題。因此,雖然僅在根 schema 中使用 "$schema" 的模式可能仍然是 schema 撰寫的最佳實務,但實作行為可能會在未來草案中修訂或放寬。

此屬性的值在其他文件和其他方中定義。JSON Schema 實作應實作對當前和先前發布的 JSON Schema 詞彙草案的支援,視為合理。

8. 基本 URI 和取消參照

為了區分龐大生態系統中的 schema,schema 由 URI [RFC3986] 識別,並可以透過指定其 URI 來嵌入對其他 schema 的參考。

8.1. 初始基本 URI

RFC3986 第 5.1 節 [RFC3986] 定義如何判斷文件的預設基本 URI。

作為參考,schema 的初始基本 URI 是發現它的 URI,如果不知道 URI,則為適當的替代 URI。

8.2. "$id" 關鍵字

"$id" 關鍵字定義 schema 的 URI,以及 schema 中其他 URI 參考所解析的基本 URI。子 schema 的 "$id" 會根據其父 schema 的基本 URI 解析。如果沒有父項使用 "$id" 設定明確的基本 URI,則基本 URI 為整個文件的 URI,如 RFC 3986 第 5 節 [RFC3986] 所決定。

如果存在,此關鍵字的值必須是字串,且必須表示有效的 URI 參考 [RFC3986]。此值應正規化,且不應為空片段 <#> 或空字串 <>。

8.2.1. 識別根 schema

JSON Schema 文件的根 schema 應包含一個带有 絕對 URI [RFC3986] (包含 scheme,但不包含片段)的 "$id" 關鍵字,或這個絕對 URI 但帶有一個空片段。

8.2.2. 在 schema 檔案中變更基本 URI

當 "$id" 設定基本 URI 時,包含該 "$id" 的物件及其所有子 schema 可以透過使用從該位置開始的 JSON 指標片段來識別。即使是進一步變更基本 URI 的子 schema 也是如此。因此,單個子 schema 可以透過多個 URI 存取,每個 URI 都由子 schema 中宣告的基本 URI 或父項中的基本 URI,以及識別從宣告基本 URI 的 schema 物件到正在識別的子 schema 路徑的 JSON 指標片段組成。此範例顯示在 8.2.4 節中。

8.2.3. 與位置無關的識別符號

使用 JSON 指標片段需要了解 schema 的結構。在撰寫 schema 文件時,如果打算提供可重複使用的 schema,則最好使用與任何特定結構位置無關的純名稱片段。這允許重新定位子 schema,而無需更新 JSON 指標參考。

要指定此類子 schema 識別符號,請將 "$id" 關鍵字設定為带有純名稱片段(不是 JSON 指標片段)的 URI 參考。此值必須以指定片段的數字符號 ("#") 開頭,然後是一個字母 ([A-Za-z]),後跟任意數量的字母、數字 ([0-9])、連字符號 ("-")、底線 ("_")、冒號 (":") 或句點 (".")。

在 "$id" 中使用非空白或不遵循純名稱語法的片段,其效果未定義。[CREF3]包含其他組件的片段的 "$id" URI 參考應該如何解釋?有兩種情況:當其他組件與目前的基準 URI 相符,以及當它們變更基準 URI 時。

8.2.4. 綱要識別範例

考量以下綱要,其中顯示 "$id" 用於識別根綱要、變更子綱要的基準 URI,以及將純名稱片段指派給子綱要

{
    "$id": "http://example.com/root.json",
    "definitions": {
        "A": { "$id": "#foo" },
        "B": {
            "$id": "other.json",
            "definitions": {
                "X": { "$id": "#bar" },
                "Y": { "$id": "t/inner.json" }
            }
        },
        "C": {
            "$id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f"
        }
    }
}

                        

以下 URI 編碼的 JSON 指標 [RFC6901](相對於根綱要)的綱要具有以下基準 URI,並可根據上方 第 5 節,透過任何列出的 URI 識別

#(文件根目錄)
http://example.com/root.json
http://example.com/root.json#

#/definitions/A
http://example.com/root.json#foo
http://example.com/root.json#/definitions/A

#/definitions/B
http://example.com/other.json
http://example.com/other.json#
http://example.com/root.json#/definitions/B

#/definitions/B/definitions/X
http://example.com/other.json#bar
http://example.com/other.json#/definitions/X
http://example.com/root.json#/definitions/B/definitions/X

#/definitions/B/definitions/Y
http://example.com/t/inner.json
http://example.com/t/inner.json#
http://example.com/other.json#/definitions/Y
http://example.com/root.json#/definitions/B/definitions/Y

#/definitions/C
urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f
urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f#
http://example.com/root.json#/definitions/C

8.3. 使用 "$ref" 的綱要參考

"$ref" 關鍵字用於參考綱要,並提供透過自我參考驗證遞迴結構的功能。

具有 "$ref" 屬性的物件綱要必須解譯為 "$ref" 參考。"$ref" 屬性的值必須是 URI 參考。根據目前的 URI 基準解析後,它會識別要使用的綱要的 URI。"$ref" 物件中的所有其他屬性都必須忽略。

URI 不是網路定位器,而僅是識別碼。如果綱要是網路可定址的 URL,則無需從該位址下載,並且實作不應假設在遇到網路可定址的 URI 時應該執行網路操作。

綱要不得針對綱要進入無限迴圈。例如,如果兩個綱要 "#alice" 和 "#bob" 都具有 "allOf" 屬性,該屬性參考另一個綱要,則天真的驗證器可能會在嘗試驗證執行個體時陷入無限的遞迴迴圈中。綱要不應像這樣使用無限的遞迴巢狀結構;行為是未定義的。

8.3.1. 載入參考的綱要

使用 URI 識別遠端綱要並不一定表示下載任何內容,而是 JSON 綱要實作應預先了解它們將使用哪些綱要,以及識別它們的 URI。

當下載綱要時,例如由一般使用者代理程式下載,該代理程式在執行階段之前都不知道要下載哪些綱要,請參閱 超媒體的用法 [hypermedia]

實作應能夠將任意 URI 與任意綱要建立關聯,及/或自動將綱要的 "$id" 給定 URI 建立關聯,具體取決於驗證器對綱要的信任。此類 URI 和綱要可以在處理執行個體之前提供給實作,也可以在處理綱要文件時在其中記錄,從而產生如 8.2.4 節所示的關聯。

綱要可以(且很可能)有多個 URI,但 URI 無法識別多個綱要。當多個綱要嘗試識別為相同的 URI 時,驗證器應引發錯誤條件。

8.3.2. 取消參考

綱要可以透過任何已給予它們的 URI 來識別,包括 JSON 指標或 "$id" 直接給定的 URI。在所有情況下,取消參考 "$ref" 參考都涉及首先根據 RFC 3986 [RFC3986],將其值解析為針對目前基準 URI 的 URI 參考。

如果產生的 URI 識別目前文件中的綱要,或已提供給實作的其他綱要文件中的綱要,則應自動使用該綱要。

例如,考慮此綱要

{
    "$id": "http://example.net/root.json",
    "items": {
        "type": "array",
        "items": { "$ref": "#item" }
    },
    "definitions": {
        "single": {
            "$id": "#item",
            "type": "object",
            "additionalProperties": { "$ref": "other.json" }
        }
    }
}

                        

當實作遇到 <#/definitions/single> 綱要時,它會針對目前的基準 URI 解析 "$id" URI 參考,以形成 <http://example.net/root.json#item>。

當實作然後查看 <#/items> 綱要內部時,它會遇到 <#item> 參考,並將其解析為 <http://example.net/root.json#item>,它已在此相同文件中看到定義,因此可以自動使用。

當實作遇到對 "other.json" 的參考時,它會將其解析為 <http://example.net/other.json>,這未在此文件中定義。如果已以其他方式向實作提供具有該識別碼的綱要,則也可以自動使用。[CREF4]當參考的綱要未知時,實作應該怎麼做?在允許自動網路取消參考的情況下,有什麼情況? 同源政策? 使用者可設定的選項?在使用 Hyper-Schema 描述的演進 API 的情況下,預期會動態地將新的綱要新增至系統,因此絕對要求預先載入綱要文件是不可行的。

9. 使用 "$comment" 的註解

此關鍵字保留給綱要作者對綱要的讀者或維護者的註解。此關鍵字的值必須是字串。實作不得將此字串呈現給終端使用者。用於編輯綱要的工具應支援顯示和編輯此關鍵字。此關鍵字的值可用於針對使用綱要的開發人員的偵錯或錯誤輸出。綱要詞彙表應允許在包含詞彙表關鍵字的任何物件中使用 "$comment"。實作可以假設允許 "$comment",除非詞彙表明確禁止。詞彙表不得指定 "$comment" 超出本規範所述的任何影響。將其他媒體類型或程式設計語言與 application/schema+json 來回轉換的工具,可能會選擇將該媒體類型或程式設計語言的原生註解轉換為或從 "$comment" 值轉換。當原生註解和 "$comment" 屬性都存在時,此類轉換的行為取決於實作。實作應將 "$comment" 的處理方式與未知的擴充關鍵字相同。它們可能會在處理過程中的任何時間點移除 "$comment" 值。特別是,這允許在部署綱要的大小是一個問題時縮短綱要。實作不得根據 "$comment" 屬性的存在、不存在或內容採取任何其他動作。

10. 超媒體的用法

JSON 已被 HTTP 伺服器廣泛採用,用於自動化 API 和機器人。本節說明當與支援媒體類型和 Web 連結 [RFC8288] 的協定一起使用時,如何以更 RESTful 的方式增強 JSON 文件的處理。

10.1. 連結至綱要

建議由綱要描述的執行個體使用連結關係 "describedby" 提供下載 JSON 綱要的連結,如 連結資料協定 1.0,第 8.1 節 [W3C.REC-ldp-20150226] 中所定義。

在 HTTP 中,可以使用 Link 標頭 [RFC8288] 將此類連結附加到任何回應。此類標頭的範例如下

Link: <http://example.com/my-hyper-schema#>; rel="describedby"

                    

10.2. 透過媒體類型參數識別綱要

媒體類型可能允許使用 "schema" 媒體類型參數,這使 HTTP 伺服器能夠根據綱要執行 Content-Type Negotiation。媒體類型參數必須是空白分隔的 URI 清單(即相對參考無效)。

當使用媒體類型 application/schema-instance+json 時,必須提供 "schema" 參數。

綱要 URI 是不透明的,不應自動取消參考。如果實作不了解所提供綱要的語意,則實作可以改為遵循 "describedby" 連結(如果有的話),這可能會提供有關如何處理綱要的資訊。由於 "schema" 不一定指向網路位置,因此 "describedby" 關係用於連結到可下載的綱要。但是,為求簡便,綱要作者應盡可能使這些 URI 指向相同的資源。

在 HTTP 中,媒體類型參數將在 Content-Type 標頭內傳送

Content-Type: application/json;
          schema="http://example.com/my-hyper-schema#"

                    

多個綱要以空白分隔

Content-Type: application/json;
          schema="http://example.com/alice http://example.com/bob"

                    

[CREF5]此段假設我們可以註冊 "schema" 連結關係。我們現在應該改為指定類似 "tag:json-schema.org,2017:schema" 的內容嗎? HTTP 也可以在連結中傳送 "schema",儘管如果這完全取代媒體類型參數,則可能會影響媒體類型語意和 Content-Type Negotiation

Link: </alice>;rel="schema", </bob>;rel="schema"

                    

10.3. 透過 HTTP 使用

當用於網路上的超媒體系統時,HTTP [RFC7231] 通常是用於散佈綱要的選擇協定。如果行為不當的用戶端比必要更頻繁地透過網路提取綱要,則可能會對伺服器維護人員造成問題,因為實際上可以在很長一段時間內快取綱要。

HTTP 伺服器應在 JSON 綱要上設定長時間快取標頭。HTTP 用戶端應觀察快取標頭,且不要在其有效期間內重新請求文件。分散式系統應使用共用快取和/或快取 Proxy。

User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0

                        

用戶端應設定或前置特定於 JSON 綱要實作或軟體產品的 User-Agent 標頭。由於符號以重要性遞減的順序列出,因此 JSON 綱要程式庫名稱/版本應位於較通用的 HTTP 程式庫名稱(如果有的話)之前。例如

用戶端應能夠使用 "From" 標頭提出請求,以便伺服器操作員可以聯絡行為可能不當的腳本的所有者。

11. 安全性考量

綱要和執行個體都是 JSON 值。因此,適用 RFC 7159 [RFC7159] 中定義的所有安全性考量。

執行個體和綱要通常都是由不受信任的協力廠商撰寫,以部署在公用網際網路伺服器上。驗證器應注意根據綱要進行剖析和驗證不會消耗過多的系統資源。驗證器絕不能陷入無限迴圈。

伺服器必須確保惡意方無法透過上傳具有先前存在或非常相似的 "$id" 的綱要來變更現有綱要的功能。

個別 JSON 綱要詞彙表也可能會有其自身的安全性考量。有關更多資訊,請查閱各項規格。

綱要作者應注意 "$comment" 內容,因為惡意實作可能會違反規格將它們顯示給終端使用者,或在預期此類行為時無法移除它們。

惡意綱要作者可能會在 "$comment" 中放置可執行程式碼或其他危險材料。實作絕不能根據 "$comment" 內容進行剖析或採取其他動作。

12. IANA 考量事項

12.1. application/schema+json

JSON 綱要的建議 MIME 媒體類型定義如下

12.2. application/schema-instance+json

需要 JSON 綱要特定媒體類型的 JSON 綱要執行個體的建議 MIME 媒體類型定義如下

13. 參考文獻

13.1. 規範性參考文獻

[RFC2119] Bradner, S., "在 RFC 中用於表示需求層級的關鍵字", BCP 14, RFC 2119, DOI 10.17487/RFC2119, 1997年3月。
[RFC3986] Berners-Lee, T., Fielding, R.L. Masinter, "統一資源識別符 (URI):通用語法", STD 66, RFC 3986, DOI 10.17487/RFC3986, 2005年1月。
[RFC6839] Hansen, T.A. Melnikov, "額外的媒體類型結構化語法後綴", RFC 6839, DOI 10.17487/RFC6839, 2013年1月。
[RFC6901] Bryan, P., Zyp, K.M. Nottingham, "JavaScript 物件表示法 (JSON) 指標", RFC 6901, DOI 10.17487/RFC6901, 2013年4月。
[RFC7159] Bray, T., "JavaScript 物件表示法 (JSON) 資料交換格式", RFC 7159, DOI 10.17487/RFC7159, 2014年3月。
[W3C.REC-ldp-20150226] Speicher, S., Arwe, J.A. Malhotra, "連結資料平台 1.0", 全球資訊網協會建議 REC-ldp-20150226, 2015年2月。

13.2. 參考性參考文獻

[RFC7049] Bormann, C.P. Hoffman, "簡潔二進制物件表示法 (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2013年10月。
[RFC7231] Fielding, R.J. Reschke, "超文字傳輸協定 (HTTP/1.1):語義和內容", RFC 7231, DOI 10.17487/RFC7231, 2014年6月。
[RFC8288] Nottingham, M., "網頁連結", RFC 8288, DOI 10.17487/RFC8288, 2017年10月。
[W3C.WD-fragid-best-practices-20121025] Tennison, J., "片段識別符和媒體類型定義的最佳實踐", 全球資訊網協會 LastCall WD-fragid-best-practices-20121025, 2012年10月。
[json-schema-validation] Wright, A., Andrews, H.G. Luff, "JSON Schema 驗證:JSON 結構驗證的詞彙", Internet-Draft draft-handrews-json-schema-validation-01, 2017年11月。
[json-hyper-schema] Andrews, H.A. Wright, "JSON 超級 Schema:JSON 超媒體註解的詞彙", Internet-Draft draft-handrews-json-schema-hyperschema-01, 2017年11月。

附錄 A. 致謝

感謝 Gary Court、Francis Galiegue、Kris Zyp 和 Geraint Luff 在 JSON Schema 的初始草稿中所做的工作。

感謝 Jason Desrosiers、Daniel Perrett、Erik Wilde、Ben Hutton、Evgeny Poberezkin、Brad Bowman、Gowry Sankar、Donald Pipowitch 和 Dave Finlay 對本文檔的提交和修補。

附錄 B. 變更日誌

[CREF6]本節在離開 Internet-Draft 狀態前將會移除。

draft-handrews-json-schema-01

draft-handrews-json-schema-00

draft-wright-json-schema-01

draft-wright-json-schema-00

draft-zyp-json-schema-04

draft-zyp-json-schema-00

作者的位址

Austin Wright (編輯) 電子郵件:[email protected]
Henry Andrews (編輯) Cloudflare, Inc. 舊金山, CA 美國 電子郵件:[email protected]