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

摘要

JSON Schema 定義了媒體類型 "application/schema+json"，這是一種基於 JSON 的格式，用於描述 JSON 資料的結構。JSON Schema 斷言 JSON 文件必須看起來像什麼樣子、如何從中提取資訊，以及如何與之互動。除了 "application/json" 文件所能提供的功能外，"application/schema-instance+json" 媒體類型還提供了與 "application/schema+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 值」、「成員」、「元素」、「物件」、「陣列」、「數字」、「字串」、「布林值」、「true」、「false」和「null」等術語應按照 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 以進行註解收集，包括那些無法進一步更改斷言結果的子 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（包括跨越多個文件的 schema）所必需的，或是為了保留關鍵字以用於需要保證互通性的目的而存在。¶

為了引導後續詞彙的處理，核心詞彙必須始終被視為強制性的。使用 "$vocabulary" (第 8.1 節) 關鍵字來宣告所使用詞彙的 meta-schema，必須明確列出核心詞彙，且其值必須為 true，表示它是必需的。¶

這個詞彙（而且只有這個詞彙）的 false 值的行為是未定義的，當存在 "$vocabulary" 但未包含核心詞彙時的行為也是未定義的。然而，建議實作檢測這些情況，並在發生時引發錯誤。宣告 meta-schema 可選擇性地使用核心詞彙是沒有意義的。¶

不使用 "$vocabulary" 的 meta-schema 必須被視為需要核心詞彙，如同其 URI 出現且值為 true 一樣。¶

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

對應的 meta-schema 目前的 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. 載入和處理綱要

{
    "$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」的元綱要，應被視為要求此詞彙表，如同其 URI 存在且值為 true 一樣。¶

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

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

14. IANA 考量

15. 參考文獻

附錄 B. 操作 schema 文件和參考

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

附錄 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」）相同的綱要物件中使用註釋關鍵字。¶

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

{
    "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",
        }
    }
}

在這裡，此綱要表示某種類型的物件導向類別。「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 綱要的主要用途¶
• 透過使用案例澄清 $id¶
• 詳盡的綱要識別範例¶
• 將「外部參考」替換為實作如何以及何時得知來自另一個文件的綱要¶
• 將「內部參考」替換為實作如何在剖析期間識別綱要識別符號¶
• 取消參考先前的「內部」或「外部」參考始終是相同的過程¶
• 微小的格式改進¶

draft-handrews-json-schema-00

• 使綱要關鍵字詞彙的概念更加清晰¶
• 請注意，「整數」的概念來自詞彙表，而不是資料模型¶
• 將關鍵字分類為斷言或註解，並描述它們的一般行為¶
• 根據廣義斷言解釋布林綱要¶
• 保留 "$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 綱要資料模型」的定義¶
• 新增額外的安全性考量¶
• 定義用於 "id" 的子綱要識別符號的使用¶
• 重寫關於 HTTP 使用的部分¶
• 重寫關於使用 rel="describedBy" 和 rel="profile" 的部分¶
• 修正了許多無效的範例¶

draft-zyp-json-schema-04

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

draft-zyp-json-schema-00

• 初始草案¶