JSON Schema：用於描述 JSON 文件的媒體類型

摘要

JSON Schema 定義了媒體類型「application/schema+json」，這是一種基於 JSON 的格式，用於描述 JSON 數據的結構。JSON Schema 聲明了 JSON 文件必須符合的外觀、如何從中提取資訊以及如何與之互動。「application/schema-instance+json」媒體類型提供了與「application/schema+json」額外的功能豐富的整合，超出了「application/json」文件所能提供的。¶

1. 簡介

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

本規範定義了 JSON 綱要的核心術語和機制，包括透過參照指向另一個 JSON 綱要、解參照 JSON 綱要參照、指定正在使用的方言、指定方言的詞彙表需求，以及定義預期的輸出。¶

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

2. 慣例與術語

本文檔中的關鍵字「必須（MUST）」、「不得（MUST NOT）」、「必要（REQUIRED）」、「應當（SHALL）」、「不應當（SHALL NOT）」、「應該（SHOULD）」、「不應該（SHOULD NOT）」、「建議（RECOMMENDED）」、「可以（MAY）」和「可選（OPTIONAL）」應按 RFC 2119 [RFC2119] 中所述進行解釋。¶

本文檔中的術語「JSON」、「JSON 文本」、「JSON 值」、「成員」、「元素」、「物件」、「陣列」、「數字」、「字串」、「布林值」、「真」、「假」和「空值」應按 RFC 8259 [RFC8259] 中定義進行解釋。¶

3. 概述

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

JSON 綱要使用關鍵字來對 JSON 實例斷言約束，或使用額外資訊註解這些實例。額外的關鍵字用於對更複雜的 JSON 資料結構應用斷言和註解，或基於某種條件。¶

為了便於重複使用，關鍵字可以組織成詞彙表。詞彙表由關鍵字列表及其語法和語義組成。方言定義為一組詞彙表及其在元綱要中識別的必要支援。¶

JSON 綱表可以透過定義額外的詞彙表來擴展，或者可以透過在任何詞彙表之外定義額外的關鍵字來以較不正式的方式擴展。無法識別的個別關鍵字只會將其值收集為註解，而當宣告正在使用哪些詞彙表時，可以控制對無法識別的詞彙表的行為。¶

本文檔定義了一個核心詞彙表，任何實作都必須支援，且無法停用。其關鍵字都以 "$" 字元作為前綴，以強調其必要性。此詞彙表對於「application/schema+json」媒體類型的運作至關重要，並用於引導其他詞彙表的載入。¶

此外，本文檔還定義了一個建議的關鍵字詞彙表，用於有條件地應用子綱要，以及將子綱要應用於物件和陣列的內容。無論這些綱要的目的是用於斷言驗證、註解或兩者，都需要此詞彙表或非常相似的詞彙表來編寫非簡單 JSON 實例的綱要。雖然它不是必要的核心詞彙表的一部分，但為了最大的互通性，此額外詞彙表包含在本文檔中，並強烈建議使用。¶

用於結構驗證或超媒體註解等目的的進一步詞彙表在其他文件中定義。這些其他文件分別定義了一種方言，該方言收集了為該文件目的編寫綱要所需的標準詞彙表集。¶

4. 定義

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

6. 一般考量

7. 關鍵字行為

JSON Schema 關鍵字分為幾個通用行為類別。斷言驗證實例是否滿足約束，產生布林結果。註解附加應用程式可能以其認為合適的任何方式使用的資訊。應用程式將子schema應用於實例的部分並組合其結果。¶

擴展關鍵字「應該」保留在這些類別中，請記住，特別是註解非常靈活。複雜行為通常最好根據註解資料委託給應用程式，而不是直接作為 schema 關鍵字實作。但是，擴展關鍵字「可以」為特殊目的定義其他行為。¶

針對 schema 評估實例涉及針對實例內適當的位置處理 schema 中的所有關鍵字。通常，會處理應用程式關鍵字，直到達到沒有應用程式（因此沒有子schema）的 schema 物件。實例中適當的位置會根據 schema 物件中的斷言和註解關鍵字進行評估，並且它們的結果會根據應用程式的規則收集到父 schema 中。¶

一旦所有子schema都經過評估，父 schema 物件的評估就可以完成，儘管在某些情況下，由於斷言結果，評估可能會被短路。收集註解時，由於需要檢查所有子schema以收集註解，包括那些無法進一步更改斷言結果的子schema，因此無法進行某些斷言結果短路。¶

{
    "type": ["string", "null"],
    "maxLength": 255
}

{
    "title": "Feature list",
    "type": "array",
    "prefixItems": [
        {
            "title": "Feature A",
            "properties": {
                "enabled": {
                    "$ref": "#/$defs/enabledToggle",
                    "default": true
                }
            }
        },
        {
            "title": "Feature B",
            "properties": {
                "enabled": {
                    "description": "If set to null, Feature B
                                    inherits the enabled
                                    value from Feature A",
                    "$ref": "#/$defs/enabledToggle"
                }
            }
        }
    ],
    "$defs": {
        "enabledToggle": {
            "title": "Enabled",
            "description": "Whether the feature is enabled (true),
                            disabled (false), or under
                            automatic control (null)",
            "type": ["boolean", "null"],
            "default": null
        }
    }
}

{
    "oneOf": [
        {
            "title": "Integer Value",
            "type": "integer"
        },
        {
            "title": "String Value",
            "type": "string"
        }
    ]
}

8. JSON Schema 核心詞彙

本節中宣告的關鍵字（皆以 "$" 開頭）構成 JSON Schema 核心詞彙。這些關鍵字是處理任何綱要 (schema) 或元綱要 (meta-schema) （包括跨多個文件分割的綱要或元綱要）所必需的，或是為了保留關鍵字以用於需要保證互通性的目的而存在。¶

為了引導進一步詞彙的處理，必須始終將核心詞彙視為強制性的。使用 "$vocabulary" (第 8.1 節) 關鍵字宣告所使用詞彙的元綱要，必須明確列出核心詞彙，其值必須為 true，表示為必要詞彙。¶

此詞彙（且僅限於此詞彙）的 false 值行為是未定義的，當存在 "$vocabulary" 但未包含核心詞彙時的行為也是未定義的。但是，建議實作方式偵測這些情況，並在發生時引發錯誤。宣告元綱要可選地使用核心詞彙是沒有意義的。¶

不使用 "$vocabulary" 的元綱要必須被視為需要核心詞彙，如同其 URI 以 true 值存在一樣。¶

核心詞彙目前的 URI 為：<https://json-schema.dev.org.tw/draft/2020-12/vocab/core>。¶

對應的元綱要目前的 URI 為：https://json-schema.dev.org.tw/draft/2020-12/meta/core。¶

雖然 "$" 前綴並未正式保留給核心詞彙使用，但建議擴充關鍵字（在詞彙或其他方面）以 "$" 以外的字元開頭，以避免未來可能發生的衝突。¶

{
    "type": "array",
    "items": { "$ref": "#/$defs/positiveInteger" },
    "$defs": {
        "positiveInteger": {
            "type": "integer",
            "exclusiveMinimum": 0
        }
    }
}

9. 載入和處理 Schema

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

{
    "$id": "https://example.com/foo",
    "items": {
        "$id": "https://example.com/bar",
        "additionalProperties": { }
    }
}

{
    "$id": "https://example.com/foo",
    "items": {
        "$ref": "bar"
    }
}

{
    "$id": "https://example.com/bar",
    "additionalProperties": { }
}

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

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

10. 用於應用子綱要的詞彙表

本節定義了一組應用程式關鍵字的詞彙表，建議用作其他詞彙表的基礎。¶

不使用 "$vocabulary" 的中繼綱要應被視為需要此詞彙表，就像其 URI 以 true 值存在一樣。¶

此詞彙表 (稱為應用程式詞彙表) 的目前 URI 為：<https://json-schema.dev.org.tw/draft/2020-12/vocab/applicator>。¶

對應的中繼綱要的目前 URI 為：https://json-schema.dev.org.tw/draft/2020-12/meta/applicator。¶

11. 未評估位置的詞彙

這些關鍵字的目的是讓模式作者能夠將子模式應用於陣列項目或物件屬性，這些項目或屬性尚未根據任何相鄰關鍵字的任何動態範圍子模式成功評估。¶

這些實例項目或屬性可能未成功地根據一個或多個相鄰關鍵字子模式進行評估，例如當「anyOf」分支中的斷言失敗時。這種失敗的評估不被認為有助於判斷該項目或屬性是否已評估。僅考慮成功的評估。¶

如果陣列中的項目或物件屬性被「成功評估」，則從邏輯上來說，會被認為就預期的物件或陣列的表示形式而言是有效的。例如，如果子模式表示一輛車，該車需要 2-4 個輪子，而「wheels」的值為 6，則實例物件不會被「評估」為一輛車，而「wheels」屬性被視為「未評估（成功地作為已知的東西）」，並且不保留任何註解。¶

回想一下，相鄰關鍵字是同一個模式物件中的關鍵字，而動態範圍子模式包括參考目標以及詞彙子模式。¶

這些關鍵字的行為取決於適用於要驗證的實例位置的相鄰關鍵字的註解結果。¶

不使用「$vocabulary」的 Meta 模式應被視為要求此詞彙表，就像其 URI 以 true 值存在一樣。¶

此詞彙表（稱為未評估應用程式詞彙表）的目前 URI 為：<https://json-schema.dev.org.tw/draft/2020-12/vocab/unevaluated>。¶

相應的 Meta 模式的目前 URI 為：https://json-schema.dev.org.tw/draft/2020-12/meta/unevaluated。¶

14. IANA 考量事項

15. 參考文獻

附錄 B. 操作綱要文件和參考

已建立各種工具，可根據參考（「$ref」）出現的方式和位置重新排列綱要文件。此附錄討論哪些使用案例和動作符合本規格。¶

附錄 D. 使用詞彙表

{
  "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema",
  "$id": "https://example.com/meta/general-use-example",
  "$dynamicAnchor": "meta",
  "$vocabulary": {
    "https://json-schema.dev.org.tw/draft/2020-12/vocab/core": true,
    "https://json-schema.dev.org.tw/draft/2020-12/vocab/applicator": true,
    "https://json-schema.dev.org.tw/draft/2020-12/vocab/validation": true,
    "https://example.com/vocab/example-vocab": true
  },
  "allOf": [
    {"$ref": "https://json-schema.dev.org.tw/draft/2020-12/meta/core"},
    {"$ref": "https://json-schema.dev.org.tw/draft/2020-12/meta/applicator"},
    {"$ref": "https://json-schema.dev.org.tw/draft/2020-12/meta/validation"},
    {"$ref": "https://example.com/meta/example-vocab"}
  ],
  "patternProperties": {
    "^unevaluated": false
  },
  "properties": {
    "localKeyword": {
      "$comment": "Not in vocabulary, but validated if used",
      "type": "string"
    }
  }
}

{
  "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema",
  "$id": "https://example.com/meta/example-vocab",
  "$dynamicAnchor": "meta",
  "$vocabulary": {
    "https://example.com/vocab/example-vocab": true,
  },
  "type": ["object", "boolean"],
  "properties": {
    "minDate": {
      "type": "string",
      "pattern": "\d\d\d\d-\d\d-\d\d",
      "format": "date",
    }
  }
}

附錄 E. 參考和產生式用例

雖然預期參考的存在對於驗證結果是透明的，但諸如程式碼產生器和 UI 渲染器之類的產生式用例通常會認為參考在語義上很重要。¶

為了使此類特定於用例的語義明確，最佳實務是在與諸如 "$ref" 之類的參考關鍵字相同的 schema 物件中建立一個註解關鍵字。¶

例如，這是一個假設的關鍵字，用於確定程式碼產生器是否應將參考目標視為一個不同的類別，以及這些類別之間的關聯方式。請注意，此範例僅用於說明目的，並不打算提出一個功能性的程式碼產生關鍵字。¶

{
    "allOf": [
        {
            "classRelation": "is-a",
            "$ref": "classes/base.json"
        },
        {
            "$ref": "fields/common.json"
        }
    ],
    "properties": {
        "foo": {
            "classRelation": "has-a",
            "$ref": "classes/foo.json"
        },
        "date": {
            "$ref": "types/dateStruct.json",
        }
    }
}

在此，此 schema 表示某種類型的物件導向類別。"allOf" 中的第一個參考被註明為基底類別。第二個沒有被分配類別關係，這意味著程式碼產生器應將目標的定義與此定義組合，就像沒有涉及參考一樣。¶

觀察屬性，「foo」被標記為物件組成，而「date」屬性則否。它僅是一個帶有子欄位的欄位，而不是一個獨立類別的實例。¶

這種使用方式要求註解與參考位於同一個物件中，且該參考必須可被識別為參考。¶

附錄 F. 致謝

感謝 Gary Court、Francis Galiegue、Kris Zyp 和 Geraint Luff 對 JSON Schema 初稿的貢獻。¶

感謝 Jason Desrosiers、Daniel Perrett、Erik Wilde、Evgeny Poberezkin、Brad Bowman、Gowry Sankar、Donald Pipowitch、Dave Finlay、Denis Laxalde、Phil Sturgeon、Shawn Silverman 和 Karen Etheridge 對本文檔的提交和修補程式。¶

附錄 G. 變更記錄

本節將在離開 Internet-Draft 狀態前移除。¶

draft-bhutton-json-schema-01

• 改進和闡明「type」、「contains」、「unevaluatedProperties」和「unevaluatedItems」關鍵字的解釋¶
• 闡明「規範 URI」的各個方面¶
• 評論關於註解和「additionalProperties」的模糊性¶
• 闡明詞彙表不需要正式定義¶
• 移除對剩餘媒體類型參數的參考¶
• 修正多個範例¶

draft-bhutton-json-schema-00

• 嵌入資源的「$schema」可能會變更¶
• 陣列值的「items」功能現在是「prefixItems」¶
• 「items」取代了舊有的「additionalItems」功能¶
• 現在指定「contains」註解行為，以及「contains」和「unevaluatedItems」的互動方式¶
• 將 $recursive* 重新命名為 $dynamic*，並修改行為¶
• $dynamicAnchor 定義了一個類似 $anchor 的片段¶
• $dynamic*（先前為 $recursive）不再使用執行時基準 URI 確定¶
• 定義複合綱要文件（bundle）及其處理方式¶
• 參考 ECMA-262 第 11 版以取得正規表示式支援¶
• 正規表示式應支援 Unicode¶
• 移除媒體類型參數¶
• 指定未知關鍵字會被收集為註解¶
• 將「unevaluatedItems」和「unevaluatedProperties」從核心移至它們自己的詞彙表¶

draft-handrews-json-schema-02

• 更新為 RFC 8259 以取得 JSON 規範¶
• 將「definitions」從驗證規範移至此處作為「$defs」¶
• 將應用關鍵字從驗證規範移為它們自己的詞彙表¶
• 將「dependencies」的綱要形式從驗證規範移為「dependentSchemas」¶
• 正式化註解收集¶
• 指定建議的輸出格式¶
• 根據註解和斷言結果定義關鍵字的互動方式¶
• 新增「unevaluatedProperties」和「unevaluatedItems」¶
• 根據斷言、應用和註解模型定義「$ref」的行為¶
• 允許關鍵字與「$ref」相鄰¶
• 註解對於涉及未知關鍵字的「$ref」目標的未定義行為¶
• 新增遞迴參考，主要用於元綱要擴展¶
• 新增正式詞彙表的概念，以及如何透過元綱要識別它們¶
• 提供關於網路檢索以外的初始基準 URI 的其他指南¶
• 允許「application/schema+json」使用「schema」媒體類型參數¶
• 更好地解釋媒體類型參數和 HTTP Accept 標頭¶
• 僅使用「$id」來建立規範和基準絕對 URI，沒有片段¶
• 將「$id」的純名稱片段形式替換為「$anchor」¶
• 闡明了 JSON 指標跨越「$id」邊界的行為不可靠¶

draft-handrews-json-schema-01

• 本草案純粹是澄清，沒有功能上的變更¶
• 強調註解是 JSON Schema 的主要用途¶
• 透過使用案例闡明 $id¶
• 詳盡的綱要識別範例¶
• 以實作如何以及何時可能從另一個文件中得知綱要來取代「外部參考」¶
• 以實作在解析期間應如何識別綱要識別碼來取代「內部參考」¶
• 取消引用先前的「內部」或「外部」參考總是相同的過程¶
• 小的格式改進¶

draft-handrews-json-schema-00

• 更明確地說明綱要關鍵字詞彙的概念¶
• 請注意，「integer」的概念來自詞彙表，而不是資料模型¶
• 將關鍵字分類為斷言或註解，並描述它們的一般行為¶
• 根據廣義斷言解釋布林綱要¶
• 保留「$comment」作為關於綱要的非使用者可見的註解¶
• 關於「$id」和片段的措辭改進¶
• 請注意使用遞迴參考擴展元綱要的挑戰¶
• 新增「application/schema-instance+json」媒體類型¶
• 建議使用「schema」連結關係/參數，而不是「profile」¶

draft-wright-json-schema-01

• 更新簡介¶
• 允許任何綱要為布林值¶
• 「$schema」不應出現在子綱要中，儘管這可能會變更¶
• 將「id」變更為「$id」；所有核心關鍵字都加上「$」前綴¶
• 闡明並正式化 application/schema+json 的片段¶
• 請注意適用於可以在 JSON 資料模型中表示的格式，例如 CBOR¶

draft-wright-json-schema-00

• 更新 JSON 的參考¶
• 更新 HTTP 的參考¶
• 更新 JSON 指標的參考¶
• 「id」的行為現在根據 RFC3986 指定¶
• 使 URI 的詞彙表用法與 RFC3986 對齊¶
• 移除對 draft-pbryan-zyp-json-ref-03 的參考¶
• 限制「$ref」的使用，使其僅在預期綱要的地方使用¶
• 新增「JSON Schema 資料模型」的定義¶
• 新增其他安全性考量¶
• 定義「id」的子綱要識別碼用法¶
• 重寫關於 HTTP 用法的章節¶
• 重寫關於與 rel="describedBy" 和 rel="profile" 一起使用的章節¶
• 修正許多無效的範例¶

draft-zyp-json-schema-04

• 從草案 v3 中拯救出來。¶
• 將驗證關鍵字拆分到單獨的文件中。¶
• 將超媒體關鍵字拆分到單獨的文件中。¶
• 初始拆分後草案。¶
• 強制使用 JSON 參考、JSON 指標。¶
• 定義「id」的角色。定義 URI 解析範圍。¶
• 新增互通性考量。¶

draft-zyp-json-schema-00

• 初始草案。¶