JSON Schema 靠把驗證變成詞彙表而贏得 API 結構描述之爭

API 工具生態曾有一次令人扼腕的差之毫釐：OpenAPI 使用的是類 JSON 的結構描述物件，但那些物件並非完整的 JSON Schema。驗證器、程式碼產生器與文件工具都必須逐一學習箇中細微差異，因此同一份 API 契約在不同技術堆疊中可能代表不同的意義。

優雅的作法並不是另創一門僅供 API 使用的語言。JSON Schema 讓結構描述本身成為一種 JSON 媒體類型，並以詞彙表與中繼結構描述宣告哪些關鍵字與行為會參與其中。OpenAPI 3.1 於是得以表明：請使用 JSON Schema draft 2020-12，而不是它的仿製品。

結果是一個靠成為其他標準底層文法而勝出的標準。OpenAPI 宣稱其 3.1 版與最新的 JSON Schema draft 百分之百相容，而 JSON Schema 則取得了穩定的擴充模型，可涵蓋驗證、程式碼產生、UI 與文件。

讓結構描述成為可擴充的詞彙表

結構描述本身仍是普通 JSON，因此開發者能用既有工具閱讀、比對差異並產生它。

詞彙表為擴充賦予名稱與界線，而不是讓每個平台各自發明私有關鍵字。

OpenAPI 的採用一次把 JSON Schema 拉進 API 文件、驗證與程式碼產生等工作流程。

Draft 2020-12 為實作者提供了穩定的目標，包括方言與中繼結構描述。

當擴充是一等公民且可測試，而不是藏在說明文字或廠商慣例裡時，一種格式才會傳播開來。

OpenAPI 3.1 於 2021 年 2 月 18 日發布，完全相容於 JSON Schema draft 2020-12。這使 JSON Schema 成為龐大 API 工具生態系的共用契約層，而不只是獨立的驗證器格式。