找出遺漏欄位與型別錯誤

使用工具

• 開啟此工具: JSON Schema 驗證

先準備一組有效資料與 Schema

{"name":"Notebook","count":2,"status":"draft"}

{
  "type": "object",
  "required": ["name", "count"],
  "properties": {
    "name": { "type": "string" },
    "count": { "type": "integer", "minimum": 0 },
    "status": { "enum": ["draft", "published"] }
  }
}

此組合通過：name、count 存在，前者字串，後者非負整數，status 為允許值。先有通過基準，才能區分資料錯誤和 Schema 錯誤。之後固定 Schema，每次只改一項資料。

寫進 properties 不代表必填

{"name":"Notebook","status":"draft"}

count 在 required 中，缺失會失敗；僅刪 status 則通過。properties 描述欄位存在時的條件，required 列必須存在的欄位。已定義欄位缺失卻不報錯時，檢查這一區別。

必填不等於非空。此例 name 為空字串仍通過，因為只要求字串。拒絕空字串需另加條件，不能把通過理解為業務名稱有效。

2、"2" 與 null 是不同值

{"name":"Notebook","count":"2","status":"draft"}

引號中的 2 是字串，不滿足 integer，驗證不會因看似數值就轉換。null 雖欄位存在，也不是整數。應區分缺失、空字串、null 與數值 0。

CSV 轉換常出現此問題，看似 2 的儲存格不一定變 JSON 整數。帶前導零的 ID 可能必須保留字串。不要只為通過 Schema 把所有數字樣文字轉數值，應確認欄位意義。

型別正確，也可能不是允許值

{"name":"Notebook","count":-1,"status":"archived"}

-1 是整數但不滿足 minimum:0，archived 不在 enum。型別本身不描述業務值域。改 count 為 0、status 為 draft 可解決兩項。每次修復後再驗，不假定一處修改會消掉所有錯誤。

把 archived 加入 enum 可能通過，但接收方未必會處理。應判斷資料錯誤還是正式規格變化，不為消除報錯而放寬契約。產生與使用方需使用對應版本。

此例沒有禁止未知欄位

加 extra 不被此 Schema 禁止，因為 properties 不是排他允許清單。SheepDev 會拒絕 additionalProperties 等未支援關鍵字。需要完整契約時，應另用支援對應版本與關鍵字的驗證器。

含 $schema、$ref、$dynamicRef 的 Schema 也會被拒絕，不外部取得。官方範例可能不能直接執行。刪除未支援部分後通過，不等於驗證原完整 Schema，應區分局部實驗與完整檢查。

記錄通過原因與未檢查條件

成功後記錄檢查了哪些必填、型別、列舉與範圍。認證、ID 實際存在、庫存和跨欄位業務規則不在本例。Schema 通過不等於 API 必接受，只是傳送前一環。

除正常例，還保留缺欄位、數值字串、null、負數和未知狀態測試。同時驗證該接受與該拒絕的輸入，能發現 Schema 變更造成的意外放寬。依據錯誤路徑判斷改資料還是契約。

為什麼通過 Schema 仍不能下單？

數量為大於等於一的整數、商品 ID 為字串，仍可能停售或缺貨。結構驗證與業務資料校驗是不同層。工具不查詢資料庫或服務，成功不證明 ID 存在或訂單可完成，應明確通過的是哪層。

保留缺必填項、數字變字串、列舉外值等反例。Schema 修改後以前失敗的例子通過，應確認是有意放寬。只為消除錯誤去掉 required 可能只是減少檢查，並未修好資料。還要確認關鍵字受此實作支援，未支援的條件不能算已驗證。

參考資料

• JSON Schema — Object properties and required fields (在新分頁開啟)

使用工具

• JSON Schema 驗證