2019-09 發行說明

對於絕大多數的綱要作者，我們希望這些變更對您的影響降到最低。

最有可能令人感到沮喪的是，format 預設不再被視為驗證斷言（雖然應用程式或使用者仍然可以設定驗證器將其視為斷言）。我們認為這是可以接受的，因為許多綱要作者已經對其不一致的行為感到非常沮喪。

對於實作者來說，需要考慮的更多，關於實作主題的進一步指南將會陸續發布。

• 不相容的變更
• 半相容的變更
• 註解、錯誤和輸出
• 關鍵字變更
  • 核心詞彙
  • 應用程式詞彙
  • 驗證詞彙
  • 格式詞彙
  • 內容詞彙
  • 元資料詞彙
  • 超級綱要詞彙

如需每個文件變更的基本列表，請參閱其變更記錄

• 核心
• 驗證
• 超級綱要

不相容的變更

• 預設情況下，format 不再是斷言。這樣做是因為 format 作為斷言的不一致實作，一直以來都是綱要作者感到驚訝問題的無盡根源。現在的預設行為將是可預測的，即使不是理想的。有幾種方法可以開啟斷言功能，如下所述。但是，我們建議在應用程式層中進行語義驗證。
• 純名稱片段不再使用 $id 定義，而是使用新的關鍵字 $anchor（它具有不同的語法）。
• $id 不能再包含片段（除了可能為空的片段，儘管不建議這樣做）。
• 在可以使用多個 URI 表示相同綱要的情況下，現在不建議使用某些 URI。這些 URI 被認為很少使用，因為其行為相當令人困惑，而且直到 draft-07 的更新版本 (draft-handrews-json-schema-01) 才得到很好的解釋。如果這對您來說沒有太多意義，那麼您可能很安全。

半相容的變更

這些關鍵字的舊語法不是錯誤（預設的元綱要仍然驗證它們），因此實作可以提供相容模式。但是，遷移到新的關鍵字很簡單，應該優先使用。

• definitions 現在是 $defs
• dependencies 已拆分為 dependentSchemas 和 dependentRequired

註解、錯誤和輸出

註解關鍵字，例如 title、readOnly 和 default 一直以來都是 JSON Schema 的一部分，但沒有任何關於如何使用它們的指南。此草案正式說明了實作如何將註解資訊提供給應用程式。

同樣地，之前也沒有關於驗證失敗時，什麼構成有用的錯誤報告的指南。

為了解決這兩個問題，我們現在建議實作支援一個或多個標準化的輸出格式。

關鍵字變更

所有關鍵字現在都已組織到詞彙中，其中核心和驗證規格包含多個詞彙。在此過程中，一些關鍵字已從驗證移至核心。

核心詞彙

核心規格，第 8 節

應用程式詞彙

核心規範，第 9 節

這些關鍵字先前位於驗證規範中。

其他 applicator vocabulary 關鍵字為 items、 additionalItems、properties、patternProperties、additionalProperties、anyOf、allOf、oneOf、not、if、then、else。

驗證詞彙

驗證規範，第 6 節

格式詞彙

驗證規範，第 7 節

由於 format 關鍵字的選用性質，它一直以來都有問題。從來沒有一種方法可以確保處理您 schema 的實作完全支援 format，或者如果它支援，它驗證每種類型格式的程度。理論上，由於每種格式都引用標準規範，因此如果支援某種格式，它應該會一致地運作。實際上，情況並非如此。

應用程式有兩種驗證格式的方法：它可以依賴 JSON Schema 實作來驗證它們（這可能具有或不具有預期的結果），或者它可以注意到 format 關鍵字已使用的地方，並基於此執行自己的驗證。第二種方法通過將 format 視為 註解關鍵字 並支援 基本、詳細或詳細輸出格式 來支援。

為了對此系統施加一些可預測性，行為已在多個方面發生變化，如下所示。這裡的關鍵差異在於，format 驗證現在預設為可預測地關閉，但可以配置為開啟。在 draft-07 中，它預設為開啟（但可能未實作），並且可以配置為關閉。

在以下圖表中，「支援」欄位是指實作是否聲稱支援 format 關鍵字，以及（對於 2019-09）支援到什麼程度。「配置」欄位是指是否以某種方式配置了 format 的某些非預設行為（在設定檔中、通過命令行選項或任何其他方式）。

draft-07 行為摘要

顯然，每個實作在 schema 之間都將一致地運作，儘管某些格式可能比其他格式得到更徹底的支援，儘管規範中的措辭如此。但是，複雜的格式在實作中實際上以不同的程度獲得支援。如果它們完全受到支援。

2019-09 行為摘要

此草案的目標是使預設行為可預測，並將不一致的行為作為選擇加入功能。這不是完全令人滿意的，但我們認為這是減少圍繞令人驚訝的結果所看到的投訴數量的好第一步。這樣，至少應該會減少一些驚訝。

• 「盡力而為」驗證是一個相當弱的要求，它符合目前實際運作的方式。簡單的格式可能完全有效，複雜的格式可能只進行最低限度的驗證，甚至根本不驗證。

• 「完整語法」驗證表示您可以期望進行相當徹底的語法驗證，可能對應於實作語言中任何常用的可用程式庫可以執行的驗證。對於 IP 位址和日期等格式，預計將完成驗證。對於更複雜的格式（例如電子郵件位址），支援可能仍然會有很大差異。目前尚不清楚有多少實作曾經提供過這種程度的支援。

• vocabulary 錯誤的結果表示實作將拒絕處理 schema，因為它無法滿足 vocabulary 要求。

請注意，鑑於幾乎沒有 draft-07 或更早的實作提供了每個單一格式的嚴格和完整驗證，因此似乎不太可能有任何實作在實踐中支援選項 3。

此外，新增了兩種新格式，並更新了規範參考

內容詞彙

驗證規範，第 8 節

這些關鍵字現在純粹指定為註解，而不是斷言。提供了一些關於實作如何選擇性地提供此資訊的進一步自動處理（在驗證過程之外）的指導。

元資料詞彙

驗證規範，第 9 節

超級綱要詞彙

超媒體綱要規範，第 5 和 6 節