邁向穩定的 JSON Schema

大約在去年這個時候，我在 API 規格會議上主持了一場關於 JSON Schema 未來的討論。最熱門的討論主題是，JSON Schema 何時會「完成」。當然，我們已經聽過很多次這個問題了。這個問題源於我們在發布版本上標註的「草案」標籤。「草案」一詞多年來為我們的社群帶來了不少困惑，因此讓我們花點時間來了解它從何而來。

為什麼它是「草案」？

JSON Schema 一直以來大致遵循 IETF 標準追蹤 RFC 流程。這表示我們的發布版本是以網際網路草案 (I-D) 的形式呈現。這就是為什麼我們稱它們為草案。然而，由於 JSON Schema 在生產系統中被廣泛使用，因此實際上不可能將規格視為典型的 I-D。因此，我們使用「草案」一詞是當 IETF 流程對 JSON Schema 更有意義時遺留下來的一些歷史產物。

這一直以來都是個問題，因為當人們聽到「草案」時，他們會聽到「未完成」或「尚未準備好用於生產」。這不是我們對待發布版本的方式。每個發布版本都被期望並鼓勵在生產中使用。這與 OpenAPI 發布新版本沒有什麼不同。沒有人會問 OpenAPI 何時會「完成」。JSON Schema 只是因為我們稱我們的發布版本為「草案」而被認為不同。

真正的問題

但這不僅僅是品牌問題。當人們問 JSON Schema 何時會脫離「草案」時，他們真正的意思是，JSON Schema 何時會「穩定」。他們希望能夠編寫一個 schema，並確保無論 JSON Schema 未來如何發展，它都會繼續以相同的方式運作。他們希望能夠更新他們的依賴項，而無需更新他們運作良好的 schema。

這也影響了程式庫維護者。需要在沒有向後或向前相容性保證的情況下支援多個版本的 JSON Schema 變得繁瑣，並導致許多維護者放棄支援較舊的版本。當這種情況發生時，可能會讓使用者必須選擇更新所有未損壞的現有 schema，或釘選到他們正在使用的 JSON Schema 程式庫不再支援的版本。

我們的解決方案

這些是我們旨在在下一個版本中解決的問題。我們的下一個版本不會繼續發布每個版本都是新的、不可變且不相容的 JSON Schema，而是會是一個長期存在、穩定但不斷發展的版本。在這種情況下，「穩定」表示任何變更都必須遵循嚴格的向後和向前相容性要求。它將非常像 JavaScript，隨著它的發展，您可以始終確保現有的 schema 將繼續與您正在使用的任何 JSON Schema 程式庫一起運作，但您使用較新功能時會有風險，因為並非所有程式庫都已實作這些功能。

這種穩定且持續發展的規格願景與 IETF 流程不太相符。我們考慮過一些途徑，但沒有任何提議能讓我們認為可以在短期內繼續發展標準並擺脫「草案」。因此，實現我們願景的第一步是將我們的主要規格開發與 IETF 流程脫鉤。這種拆分允許我們為主要規格開發追求一種新的模型，該模型更有利於我們的願景。

無論您是否喜歡 JavaScript 語言的發展方向，很明顯的是，他們已經提出了一個有效流程，允許持續發展而不會犧牲互通性和持久性。這就是為什麼我們選擇將我們的新流程建立在用於發展 JavaScript 語言的流程之上。在我們的下一個版本中，您今天使用的大多數關鍵字和功能都將被宣告為穩定，並且它們永遠不會再以向後不相容的方式變更。我們不認為適合穩定的功能和關鍵字將成為我們目前正在定義的一個新的階段性發布流程的一部分。階段性發布流程的目標是確保該功能獲得足夠的實作、測試和實際驗證，以便我們有信心宣告其穩定。該流程不僅應使我們更有信心，而且還應使我們能夠更快地實現這種信心。

標準考量

從下一個版本開始，JSON Schema 規格將在我們的網站上自行發布。

自行發布的擔憂之一是關於其他標準是否能夠引用 JSON Schema 規格。我們已收到參與標準開發的人員的回饋，根據我們在 OpenJS 基金會的成員資格，他們認為我們的方法可以接受在其標準中引用我們的規格。我們不知道所有標準機構是否會得出相同的結論，但此回饋使我們確信這不會是一個重大問題。

儘管主要規格將自行發布，但我們仍在 IETF 流程中進行處理，這是有意義的。例如，我們正在透過 HTTPAPIs WG 註冊我們的媒體類型，例如 application/schema+json。我們也正在研究透過 IETF 標準化可重複使用的組件，例如相對 JSON 指標。

重點結論

有關新流程的詳細資訊將在最終確定後於另一篇文章中分享，但以下是使用者可以期望的一些結果。

• 如果您僅使用穩定的功能，則可保證 JSON Schema 程式庫之間的互通性，並且您永遠不需要為了跟上新版本而更新您的 schema。
• 只要使用您 schema 的程式庫支援該功能，您就可以安全地在功能穩定之前使用新功能。
• 相容性/互通性保證僅適用於下一個版本及以後的版本。您需要將您的 schema 更新到穩定版本，但隨著 JSON Schema 的發展，您不必繼續更新它們。
• 自訂方言和詞彙將繼續是自訂和擴充 JSON Schema 的核心概念。
• 實作者不需要維護不同的程式碼來支援過去的穩定版本。支援 2025 年版本的程式庫將自動支援 2023 年和 2024 年的版本。過去的穩定版本不再需要維護為不同的版本。但是，繼續支援「草案」版本的實作仍需要將這些版本與目前的穩定版本分開維護。