JSON Schema 校驗入門:用模式約束介面資料

什麼是 JSON Schema,如何用它校驗 API 返回的 JSON 是否合法,附可複製的 draft-07 示例。

目錄

什麼是 JSON Schema

JSON Schema 是一份描述 JSON 資料「應該長什麼樣」的 JSON 文件,常見版本為 draft-07。它用 typerequiredpropertiesenum 等關鍵字宣告欄位型別與約束,常用來校驗介面請求/響應、配置檔案是否合規。

寫一個最小 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 的校驗器適合快速除錯與複製結果。
← 返回「JSON 與資料」內容叢集