JSON Schema 詞彙表

本文收集了 JSON Schema 社群中可能遇到的術語的簡短解釋。

雖然以下許多條目都有精確的技術定義，但優先考慮對其會話使用的解釋，並連結額外的參考資料以獲取更多資訊。本頁並非旨在規範性，也不打算包含完全原創的研究或解釋。其目的是幫助那些不熟悉 JSON Schema 中使用的正式語言或更廣泛規範的人理解。（事實上，以下條目會盡量避免使用像「規範性」這樣的術語，原因正如剛才提到的。）

如果您遇到希望在此處定義的術語，請隨時提出請求的 issue。

本頁上的條目可以通過錨點連結（例如 https://json-schema.dev.org.tw/learn/glossary.html#vocabulary）與他人分享定義時使用。

方言 (dialect)

可在 schema 中使用的一組有凝聚力的關鍵字集合，通常代表 JSON Schema 規範的特定用例的單個版本。

方言，特別是 2019-09 和 2020-12 方言，通常通過一組詞彙來定義。

每個方言都由一個 URI 識別，即其方言識別符，schemas 然後可以在它們的 $schema 關鍵字中引用。這樣做會將 schema 識別為以該方言編寫，並因此指出其中可以使用哪些關鍵字，以及它們的預期含義。

JSON Schema 規範定義了許多方言，每個方言都啟用適用於該方言特定用例的詞彙。這些詞彙在 meta-schemas 中描述。

草案 (draft)

JSON Schema 規範的單個發布版本。

JSON Schema 草案並不打算成為臨時文件，就像外行人使用「草案」這個詞所暗示的那樣。

雖然未來的草案可能會引入新的行為或對現有行為的變更，但每個草案都是一個完整的、已發布的文件，將規範的變更批次處理在一起，並旨在實作和使用。

目前的草案列表可以在此處找到。

JSON

一種普遍存在的資料交換格式，用於將資料表示和傳輸為人類可讀的文本。JSON 的使用非常廣泛，並且幾乎每種常用的程式語言都有可以讀寫它的剖析器。

JSON Schema 明顯地建立在 JSON 的之上，因為 JSON schemas 本身是描述 JSON 值的 JSON 物件。然而，這兩者是概念難題中完全不同的部分，JSON 是一種表示資料的具體格式，而 JSON Schema 是一種架構化以 JSON 相容格式編寫的資料的方法。

JSON 格式是一種開放格式，有其自己的首頁，以及分別在 ECMA 和 IETF 的 ECMA-404 和 RFC-8259 文件中發布的規範。特別是，它不是由 JSON Schema 團隊管理或開發的，他們只是簡單地使用這種格式。

JSON Hyper-Schema

JSON Hyper-Schema 擴展了 JSON Schema，提供了一個詞彙表來使用超媒體控制項註解 JSON 文件。此擴展有助於描述可以在 JSON 資料上執行的連結和動作，使其成為開發超媒體驅動 API 的強大工具。

JSON Hyper-Schema 的精髓在於它能夠定義可對 JSON 資料執行的連結和動作。這是透過使用 links 關鍵字來實現的，此關鍵字允許建立動態、互動式的資料表示。例如，一個代表部落格文章的 JSON 文件可能包含一個 "author" 屬性。描述此文件的 JSON Hyper-Schema 可以包含一個超媒體控制的範本，該範本使用 實例 中的作者識別符來建構一個指向作者個人資料的連結。開發人員不需要手動建構 URL，這透過提供無縫的導覽體驗來增強開發人員的體驗。

換句話說，JSON Hyper-Schema 透過引入建立超媒體控制的功能來擴展 JSON Schema。這有助於建立互動式 API，並確保與現有 JSON HTTP API 的相容性，保持無縫整合。它為 JSON 文件增加了一層互動性，使其更容易與遠端的 JSON 資源互動。

JSON 指標

JSON 指標 是一種字串語法，用於識別 JSON 文件中指定位置的值。它用於精確地引用文件的特定部分以進行檢索或操作。子綱要通常使用 JSON 指標來識別，指定其在包含資源中的位置。

關鍵字

出現在綱要物件中的屬性。

JSON Schema 規格定義了大量關鍵字的行為，這些關鍵字可用於描述實例。

實作

歷史上，「實作」一詞曾被用來描述驗證器/註解器（規格的範圍）以及各種其他 JSON Schema 工具。然而，由於這種模糊性，我們決定首選的會話術語應該是「工具」。

實例

要由綱要描述的一段 JSON 資料。

JSON Schema 可用於描述任何類型的 JSON 值（以及許多可以合理表示為 JSON 的類 JSON 格式的值）。

JSON Schema 規格本身對實例的結構沒有做廣泛的假設，超出 JSON 規格本身的假設。特別是，它沒有在其自己的使用範圍內保留 JSON 物件中的任何屬性，也沒有要求 JSON 解析器支援超出 JSON 實作已規定的功能。

元綱要

一個綱要，其本身旨在描述其他綱要。

JSON Schema 定義了一種使用 JSON 編寫的綱要來描述任何實例的語言。由於綱要本身也是 JSON 值，因此它們也可以被視為實例，因此可以由其他綱要來描述。

我們將綱要的綱要稱為「元綱要」來表達這種用法。

規範性

在 JSON Schema 的背景下，以及更廣泛的正式規格中，一份概述標準化行為的文件。這與旨在解釋、簡化或提供意見的非規範性或資訊性文件不同。

區分文件是否為規範性旨在向使用文件的人員澄清，其內容是否允許與其他規範性文件中描述的行為相矛盾或擴充。JSON Schema 的規範性文件特別包括其規格。例如，此頁面不是規範性文件，因此無法規定規格中未涵蓋的新 JSON Schema 行為。

另請參閱

• Mozilla 詞彙表中的規範性和非規範性及其連結

綱要

根據 JSON Schema 規格的規定結構編寫的文件，可用於描述實例。

構成哪些綱要符合規範的規則，以及驗證實例時管理其行為的規則，由JSON Schema 規格定義。

嚴格來說，根據規格，綱要本身是JSON 文件，儘管它們通常以其他易於轉換為 JSON 的語言（例如 YAML）編寫或維護。

在規格的最新草案中，綱要不是 JSON 物件就是 JSON 布林值。

子綱要

一個綱要，其本身包含在周圍的父綱要中。與綱要本身一樣，在 JSON Schema 的最新草案中，子綱要不是 JSON 物件就是 JSON 布林值。

在 JSON Schema 規格及其方言中，許多關鍵字將子綱要作為其值的一部分。例如，not 關鍵字採用子綱要值並反轉其結果，只要子綱要未成功，它就會成功，使得實例12 在{"type": "string"} 下無效，但在{"not": {"type": "string"}} 下有效，其中{"type": "string"} 是完整綱要中包含的子綱要。

一些子綱要可能會出現在父綱要中更複雜的巢狀位置。例如，allOf 關鍵字採用多個子綱要的陣列，並且只要所有子綱要各自都成功，它就會成功。

如果沒有上下文或關於它在父綱要中位置的知識，則某些其他看似為綱要的東西（基於其內容）實際上是否為子綱要，可能乍看之下會產生誤導。具體來說，在上面的例子中，{"type": "string"} 是較大綱要的子綱要，但在綱要{"const": {"type": "string"}}中，它不是子綱要。即使作為一個值看起來相同，將實例與特定預期值進行比較的const 關鍵字，其值並非子綱要，其值是不具特定含義的不透明值（使得在此綱要中，數字 12 無效，但精確的實例{"type": "string"} 有效）。更簡單地說，特定值是否為子綱要取決於其在父綱要中的精確位置，因為該值的解釋取決於其所在的關鍵字的定義行為。

子綱要本身可能包含子子綱要，儘管口語上通常使用術語「子綱要」而不管巢狀的層級，並在需要時進一步說明哪個更大的綱要是父綱要。

工具

JSON Schema 工具（或口語上稱為「工具」）是任何用於以某種方式處理或評估綱要的軟體應用程式或程式庫。

以下被視為工具

• 驗證器程式庫
• CLI 驗證器
• 綱要或程式碼產生器
• UI 表單產生器

在內部使用 JSON Schema 而不以某種方式公開該功能（例如驗證組態檔或 Web 請求）的應用程式不被視為工具。

驗證結果

在 JSON Schema 的背景下，驗證結果是指將整個 JSON Schema 應用於整個實例文件的結果。此結果可以包含的不僅僅是一個布林值斷言，並且可以包含各種輸出格式，例如錯誤訊息、錯誤代碼或詳細的驗證報告。它表示實例文件是否符合綱要中指定的規則和約束。驗證結果表示實例文件是否通過或未通過針對綱要的驗證。

詞彙

為了方便重複使用而分組的緊密相關的關鍵字集合。

詞彙由散文文件或規格指定，該文件或規格以適合詞彙實作者和使用者的方式解釋其關鍵字的語義。它通常還包括一個元綱要（或多個元綱要），這些元綱要定義了其關鍵字的語法。

任何人都可以建立和發佈詞彙，並且實作通常會包含擴展自身以支援其他詞彙及其關鍵字的功能。JSON Schema 規格包括許多涵蓋它定義的每個關鍵字的詞彙。

在 JSON Schema 的某些方言中，$vocabulary 關鍵字可用於將詞彙定義的關鍵字包含到方言中，並指示實作是否必須特別識別該詞彙才能處理以該方言編寫的綱要。

另請參閱

• json-schema-vocabularies，一個收集已知第三方 JSON Schema 詞彙的儲存庫