JSON Schema 實作之間的通用介面

JSON Schema 的使用非常廣泛，而且幾乎同樣廣泛地被實作。有 超過 20 種語言或環境提供了 JSON Schema 驗證的實作。這種普遍性對於使用者選擇來說非常棒 - 作為一個希望使用 JSON Schema 的人，你幾乎可以肯定會找到適合你的目標環境的實作。

但是，當涉及到社群支援時，很難知道如何在特定的程式庫或實作中執行各種 JSON Schema 操作，因為每個程式庫或實作可能具有略微不同（或超過略微不同）的 API。當考慮到規格本身不一定規定或要求，但在實務中為了使用 JSON Schema，卻是常見、有用，甚至需要的行為時，這可能會變得特別具有挑戰性。本頁旨在記錄許多這些*常見操作*，記錄現有 JSON Schema 生態系統中許多實作所提供的介面。

對於每一項操作，我們首先使用規格中的術語（如果有的話）來命名和描述該操作，否則使用旨在簡潔但精確的術語。本頁的部分目的是作為重要 JSON Schema 操作的參考，以及為特定語言和實作量身定制幫助的一種方式。因此，我們在已知的情況下，包括跨實作的每個介面或功能範例。本頁上的章節排序並不一定表示它們彼此之間的重要性。遺漏功能（即，如果你在下面找不到使用給定實作執行某些操作的方法）*不一定*表示該實作不支援該功能，儘管這可能表示頁面作者無法輕易找到該功能。我們特別歡迎實作者的貢獻和更正，以及文件連結！

為了使本頁的某些章節更精確，我們假設存在一組*抽象類型*，所有這些類型都可以在下面引用，並且在給定的程式語言或實作中將具有特定的具體類型。除了像 String、Number、Boolean、Mapping、Callable 等佔位符類型之外，與 JSON Schema 相關的類型包括

Schema

JSON Schema 的類型，在 JSON Schema 的不同方言中也可能有所不同。對於 JSON Schema 的常見或現代版本，此類型必須基本上能夠表示任意 JSON 物件以及布林值。

Instance

JSON 實例的類型。此類型基本上應該是 Any 或能夠表示所有 JSON 值的類型，因為 JSON Schema 適用於任何可表示的 JSON。

Dialect

JSON 方言或方言識別符號的類型。如果方言在實作中以其 URI 或某些簡短名稱表示，則此類型可以簡單地是 String。

評估選項 (EvaluationOptions)

「完全準備好」的綱要 (schemas) 和實例 (instances) 以及任何額外的、實作特定的可自訂行為的類型。至少，此類型為 綱要 → 實例 或 綱要 × 實例 (取決於實作是否將綱要和實例一起處理，或編譯綱要，然後產生一個獨立的函數來接收實例以進行驗證)。它很可能在以下至少某些方面更豐富：

• 由於可能支援某種形式的綱要註冊表，以便支援參考外部綱要，因此此類型可能會包含某種註冊表，例如 Mapping<URI, 綱要> → 綱要 → ...
• 如果實作支援自訂哪些 JSON 類型對應到哪些程式語言類型（如下文討論），則此類型可能會包含此對應的某種表示形式，例如 Mapping<String, Callable[...]> → 綱要 → ...，封裝了此評估期間每個類型的對應方式。
• 同樣地，如果存在用於格式斷言啟用的特定 API，則在上下文中會存在對 format 關鍵字行為的某種表示形式。
• 如果實作支援方言的建立或自訂，尤其是在綱要可以包含跨不同方言的子綱要時，則上下文將包含方言的某種表示形式，例如 方言 → 綱要 → ...

結果 (Result)

JSON 綱要驗證結果的類型，即封裝給定 實例 在 綱要 下的有效性的物件。在某些實作或語言中，此類型可能僅為 布林值。

帶註釋的結果 (ResultWithAnnotations)

URI

符合 RFC 3986 的 URI 的類型。此類型通常不應與 String 相同，因為 URI 有多種可能的字串表示形式，並且需要正規化才能具有正確的語意。

由於此頁面處理跨越語言障礙的問題，並且不同的程式語言在如何表示帶外錯誤（透過例外、選項類型、包裝返回類型、哨兵值或其他機制）方面具有不同的能力，因此此頁面還引入了¹特定的符號來表示包含帶外錯誤的函數類型。解釋這些類型將取決於程式語言。用一個例子更容易解釋以上內容：

考慮一個浮點數的除法函數，表示為 x / y。

我們會將此函數的類型寫成 Float → Float → Float <!> DivideByZeroError，其中此簽名的解釋是該函數接收 2 個浮點數並返回一個浮點數，但 <!> 表示它也可能傳播 DivideByZeroError（在這種情況下，當函數被要求除以零時）。

DivideByZeroError 的具體表現形式將取決於程式語言。在具有例外的語言中，此函數可能會引發一個與 DivideByZeroError 等效的例外，呼叫者必須或可能需要處理該例外。在具有選項類型的語言中，「正確」的類型簽名可能實際上包裹在 Option 類型中，該類型表示除以零的情況（因此在這種語言中，「真正的」簽名將是 Option[Float → Float → Float]）。在具有包裝返回類型的語言中，真正的類型簽名可能是 Result<Float, DivideByZeroError>，其中必須檢查返回的值，以確保它包含成功的結果，並且除以零錯誤是一個可能的錯誤值。在具有返回「垃圾」值約定的語言中，真正的類型可能正是 Float → Float → Float，其中在除以零時返回一些任意浮點數值，而沒有進一步的指示。

在上述所有情況下，當引發例外（對應地，錯誤或垃圾值）時，我們按照慣例假設任何正常的返回值都完全不存在於程式語言的機制中，或者被認為毫無意義。

此外，本頁面通常不會考慮或提及可能因特定章節中討論以外的原因而引發錯誤的可能性。例如，上面提到的除法範例可能會在動態類型語言中，當提供字串時引發其他類型的錯誤（在這種情況下，這種可能性會在執行時存在），這樣「真正」的除法函數可能看起來更像 Float → Float → Float <!> DivideByZeroError | TypeError 甚至更多的錯誤可能性。就 JSON 綱要而言，這可能表示下面提到的每個介面都具有包含 <!> InvalidSchema | NotValidJSON | ... 的類型，表示它們被提供了根據規範無效的綱要，或不符合 JSON 資料模型等的狀況，但我們認為這些是隱含的，除非與正在討論的介面直接相關，否則不會明確提及。

實例驗證

實例驗證是 JSON 綱要的關鍵功能之一。它是在特定綱要下，判斷給定資料是否有效或無效的過程。實作可能會提供以下一個或多個特定介面來執行此驗證。

例外驅動的驗證

類型：評估選項 → None <!> ValidationError 或 評估選項 → 結果 <!> ValidationError

當驗證本身失敗時，會導致特定於語言的失敗或例外的驗證 API。如果成功，此 API 可以返回包含更多詳細資訊的結果，或者可以簡單地靜默繼續執行。

布林值驗證

類型：評估選項 → 布林值

產生一個簡單布林值結果的 API，指示實例在綱要下的有效性。

雙參數驗證

類型：綱要 × 實例 → 結果

一個 API，同時接收綱要和實例，並產生一個結果，指示實例在給定綱要下是否有效。

在某種意義上，雙參數驗證是 JSON 綱要驗證最簡單的 API；它僅詢問給定的實例在給定的綱要下是否有效，而沒有重複使用（綱要）或額外計算的假設。

重複驗證/綱要編譯

類型：綱要 → 實例 → 結果

嘗試準備綱要以供重複使用的 API。它可能會（並且很可能會）執行某種形式的預最佳化，預先執行某些工作，這樣在驗證許多實例時就不需要重複。

子綱要驗證

類型：綱要 × 字串 × 實例 → 結果

支援針對給定綱要中包含的子綱要驗證實例的 API。

子綱要通常透過 JSON 指標或等效語法來識別，並且與使用透過 $ref 關鍵字參考子綱要的新綱要進行驗證相反。

註釋收集

類型：評估選項 → 帶註釋的結果

一個 API，收集處理給定綱要和實例時產生的註釋。

綱要驗證

類型：綱要 → 結果

一個 API，用於在為其編寫的方言下驗證綱要本身。此 API 可能會使用方言的相應後設綱要（或多個後設綱要），但通常必須執行額外的工作，以確保即使在後設綱要中未檢查的條件下，綱要也不是無效的。

明確的版本選擇

類型：方言 → 評估選項 → 結果

一個 API，用於控制當給定一個未另行指示其方言的綱要（即未宣告 $schema 屬性）時，實作將假設的方言。

版本偵測

類型：綱要 → 方言

一個 API，用於識別給定綱要是為哪個方言編寫的，返回方言本身或特定於方言的驗證函數。

類型客製化

一個 API，允許（重新）配置哪些語言級別的類型對應到哪些 JSON Schema 類型，並且可能允許定義新的類型。

字串驗證

類型： 字串 → 字串 → 結果

一個 API，直接使用 schema 驗證實例，其中 schema 和實例都以字串形式表示（序列化的 JSON），而不是反序列化的 JSON。

語言物件驗證

類型： EvaluationOptions → 結果

一個 API，使用 schema 驗證實例，其中 schema 和實例都已反序列化為語言級別的物件，或者可能是直接以程式方式建構為語言級別的物件。

format 驗證

格式斷言啟用

一個 API，用於配置 format 關鍵字的行為，在某些方言中，此行為並非僅由 JSON Schema 詞彙啟用控制。

格式註冊

類型： 字串 × (實例 → 布林值)→EvaluationOptions`

一個 API，允許註冊新的格式及其實現，以便與 format 關鍵字一起使用，通常是在用來斷言時使用。

某些實現可能還允許為不同的方言註冊不同的可用格式集。

格式查詢

一個 API，用於查詢或列出已註冊的可用格式集合。

直接格式驗證

類型： 字串 × 實例 → 布林值

一個 API，允許直接檢查 JSON 類型的數值是否滿足特定格式，而無需 schema 的存在。

Schema 註冊表填充

一個 API，用於配置在驗證過程中可供參考的 schema 包。

外部識別的 Schema

一個 API，允許將一個或多個 URI 與 schema 相關聯，其中 URI 並非由 $id 關鍵字（或方言特定的等效關鍵字）內部指示。

內部識別的 Schema

一個 API，允許將 URI 與 schema 相關聯，其中 URI 由 schema 中存在的 $id 關鍵字（或方言特定的等效關鍵字）內部指示。

Schema 探索

一個 API，（遞迴地）爬取根 schema 或多個 schema，發現任何存在的且可識別的子資源（子 schema），並使這些子資源的 URI 可用於進一步參考。

動態 URI 解析

一個 API，允許對註冊表中未預先填充的任何參考執行任意動態查找行為。

輸出格式選擇/生成

一個 API，用於配置在產生結果時使用哪個 JSON Schema 的輸出格式，或允許在給定 結果 的情況下產生特定的輸出格式。

詞彙註冊

一個 API，用於促進創建新的 JSON Schema 詞彙，通常用於稍後建構新的方言時使用。

方言建立

一個 API，用於促進創建新的 JSON Schema 方言，通常以某種方式註冊它們，以便它們可以在實作中進一步使用。

失敗詳情

一個 API，允許程式化地檢查特定驗證失敗的原因，至少包含導致失敗的失敗關鍵字、值和個別訊息。