把契約證據拆開檢查
JSON Schema 線上驗證工具｜OpenAPI 路徑檢視與比對
在瀏覽器本機以 Ajv Draft-07 或 2020-12 驗證 JSON／YAML 資料實例，追蹤錯誤的實例與 Schema 路徑；另可盤點 OpenAPI 路徑、HTTP 方法及 path 增刪。
- 01
解析文件
JSON 或 YAML 語法是否能讀取？
- 02
編譯 Schema
選定的 Ajv 方言是否能編譯這份規則？
- 03
驗證實例
資料是否符合型別、必填欄位與數值限制？
- 04
盤點 API
OpenAPI 有哪些 path 與 HTTP 方法？兩份文件增減了哪些 path？
選擇 Draft，也是在選擇關鍵字與陣列規則
| 比較項目 | Draft-07 | 2020-12 / OpenAPI 3.1 |
|---|---|---|
| 重複使用定義 | definitions | $defs |
| 陣列 tuple 規則 | items 陣列 | prefixItems |
| OpenAPI 關係 | 不等於 OpenAPI 3.0 驗證 | 3.1 Schema Object 對齊 2020-12；完整 OAS 另有結構 |
實例錯誤追蹤
把 instance path 與 schema path 放在一起看。
/items/1/price 必須大於或等於 0 ↳ schema /properties/items/items/properties/price/minimum
instance path 指向不符合規則的資料，schema path 則指出觸發的限制。兩條路徑一起看，才能回到實際欄位與規則，而不只是得到一串模糊訊息。
OpenAPI 3.1 不只是一份 JSON Schema
Path + HTTP 方法參數Request body回應Components / schemas
完整 API 契約還包含參數、請求內容、回應、components 與安全性設定。目前的 OpenAPI 檢視只列出版本、標題、path 與已辨識的 HTTP 方法，不會解析元件引用，也不是完整 OAS 驗證器。
同一份 Schema 內的 $ref 可重現；遠端引用不會載入
Ajv 可以解析所貼 JSON Schema 根節點內可到達的本機 $ref。工具不會向遠端網址抓取 Schema；引用目標不存在或遠端 Schema 未提供時，編譯會失敗，不會被當成通過。OpenAPI 檢視模式也不會展開引用圖。
#/$defs/Order → 由目前貼上的 Schema 解析 https://…/common.json → 不會載入，無法解析時編譯失敗
目前的 diff 只比較最上層 path 名稱
- 同一路徑新增或移除 HTTP 方法
- 新增必填參數或屬性
- 縮小 enum 或數值範圍
- 變更回應狀態碼或 media type
- 變更驗證與授權需求
輸出只會列出新增與移除的 path 候選。方法、參數、request body、response、components 與 security 的變更仍要另外審查；工具不會宣稱它們向下相容或屬於 breaking change。
JSON Schema 與 OpenAPI 常見問題
- JSON 語法正確，就代表通過 JSON Schema 嗎？
- 不代表。解析只證明 JSON 或 YAML 語法可讀；實例驗證才會套用型別、必填欄位與限制。目前 Ajv 設為 validateFormats: false，因此 email、URI、date-time 等 format 不會被斷言為有效。
- 選擇 OpenAPI 3.1 就會完整驗證 OAS 文件嗎？
- 不會。這個選項使用 Ajv 2020-12 處理 JSON Schema 實例規則；OpenAPI 檢視只盤點版本、標題、path 與 HTTP 方法，不會驗證完整 OAS 結構、元件關係或相容性。
- 工具會載入遠端 $ref 嗎？
- 不會。驗證只使用目前貼上的 Schema，沒有從網址載入遠端引用；無法解析的引用會造成編譯錯誤，而不是靜默通過。