JSON Schema 校驗入門:用模式約束介面資料
什麼是 JSON Schema,如何用它校驗 API 返回的 JSON 是否合法,附可複製的 draft-07 示例。
什麼是 JSON Schema
JSON Schema 是一份描述 JSON 資料「應該長什麼樣」的 JSON 文件,常見版本為 draft-07。它用 type、required、properties、enum 等關鍵字宣告欄位型別與約束,常用來校驗介面請求/響應、配置檔案是否合規。
寫一個最小 Schema
下面這段 schema 要求物件必須包含 name(字串)和 age(非負整數),role 只能是 user/admin:
在 ToolBox 中校驗
開啟 JSON Schema 校驗器,左側貼上資料、右側貼上 schema,點選校驗即可看到逐欄位結果。把示例資料故意改成 "age": -3 會立即報「minimum」錯誤。
常見校驗錯誤
type mismatch:欄位型別不符;required:缺少必填欄位;enum:值不在允許集合;additionalProperties:出現了 schema 未宣告的欄位(可設為 false 嚴格校驗)。
常見問題
- JSON Schema 能校驗陣列嗎?
- 能。用 "type":"array" 配合 "items" 描述每個元素的 schema,還可加 "minItems"/"maxItems" 限制長度。
- draft-07 和 2020-12 有什麼區別?
- 語法大體相容,2020-12 引入了 $defs、dependentRequired 等更細的約束;多數業務用 draft-07 已足夠。
- 前端能用 JSON Schema 校驗嗎?
- 可以。Ajv 等庫能在瀏覽器內按 schema 校驗表單與介面資料,ToolBox 的校驗器適合快速除錯與複製結果。