宣告方言

JSON Schema 的一個版本稱為方言。方言代表可用於評估 schema 的一組關鍵字和語意。每個 JSON Schema 發行版本都是 JSON Schema 的一種新方言。JSON Schema 提供了一種方法，讓您可以宣告 schema 符合哪種方言，並提供描述您自己的自訂方言的方法。

$schema

$schema 關鍵字用於宣告 schema 是為哪個版本的 JSON Schema 方言所編寫。 $schema 關鍵字的值也是一個 schema 的識別符，可用於根據 $schema 所識別的方言來驗證 schema 是否有效。描述另一個 schema 的 schema 稱為「meta-schema」。

$schema 適用於整個文件，且必須位於根層級。它不適用於外部參照的（$ref、$dynamicRef）文件。這些 schema 需要宣告它們自己的 $schema。

如果未使用 $schema，實作可能會允許您從外部指定值，或者可能會假設應使用哪個規格版本來評估 schema。建議所有 JSON Schema 都具有 $schema 關鍵字，以告知讀者和工具預期的規格版本。因此，在大多數情況下，您會希望將此關鍵字放在 schema 的根目錄中

1"$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema"

詞彙表

2019-09 草案新增功能

文件即將推出

特定草案資訊

在詞彙表引入之前，您仍然可以使用自訂關鍵字擴充 JSON Schema，但此過程不太正式。您首先需要一個包含自訂關鍵字的 meta-schema。最好的方法是複製您要擴充的版本的 meta-schema，並對您的副本進行變更。您需要選擇一個自訂 URI 來識別您的自訂版本。此 URI 不得為用於識別官方 JSON Schema 規格草案的 URI 之一，且可能應包含您擁有的網域名稱。您可以將此 URI 與 $schema 關鍵字搭配使用，以宣告您的 schema 使用您的自訂版本。

準則

JSON Schema 的優勢之一在於它可以使用 JSON 編寫，並應用於各種環境。例如，它可以同時用於前端和後端的 HTML 表單驗證。使用自訂詞彙的問題在於，您想要使用 schema 的每個環境都需要理解如何評估您詞彙的關鍵字。Meta-schema 可以用來確保 schema 編寫正確，但每個實作都需要自訂程式碼才能理解如何評估詞彙的關鍵字。

Meta-data 關鍵字是最具互通性的，因為它們不會影響驗證。例如，您可以新增一個 units 關鍵字。這將始終如預期般與符合規範的驗證器一起運作。

schema

{ "type": "number", "units": "kg"}

資料

42

符合 schema

資料

"42"

不符合 schema

自訂關鍵字的下一個最佳選擇是不會應用其他 schema 且不會修改現有關鍵字行為的關鍵字。舉例來說，isEven 關鍵字就是一個例子。在某些驗證比沒有驗證更好的情況下，例如在瀏覽器中驗證 HTML 表單，這個 schema 將會盡可能地發揮作用。仍然需要進行完整的驗證，並且應該使用能夠理解自訂關鍵字的驗證器。

schema

{ "type": "integer", "isEven": true}

資料

2

符合 schema

這會通過，因為驗證器不理解 isEven

資料

3

符合 schema

schema 並未完全失效，因為它不理解 isEven

資料

"3"

不符合 schema

最不具互通性的自訂關鍵字類型是應用其他 schema 或修改現有關鍵字行為的關鍵字。例如，像是 requiredProperties 這種宣告屬性並使其成為必填項的關鍵字。這個例子顯示當使用不理解自訂關鍵字的驗證器進行評估時，schema 如何變得幾乎完全無用。這不一定表示 requiredProperties 是一個不好的關鍵字想法，只是如果 schema 可能需要在不理解自訂關鍵字的環境中使用，這就不是一個正確的選擇。

schema

{ "type": "object", "requiredProperties": { "foo": { "type": "string" } }}

資料

{ "foo": "bar" }

符合 schema

這會通過，因為 requiredProperties 不被理解

資料

{}

符合 schema

這會通過，因為 requiredProperties 不被理解

資料

{ "foo": 42 }

符合 schema