開發者工具 · JSON 格式化程式和驗證程序
有效 JSON 與針對模式有效：「有效」的兩種意義
· 背景
json 標準 驗證
驗證器說您的 JSON 有效只表示它可以解析。這篇文章解釋了有效性的層級（語法、結構、語義）以及為什麼 JSON 模式對於語法之外的所有內容都存在。
有效，但仍被拒絕
請求可能是無可挑剔的 JSON 但仍然無法被 API 接受。 `{"username":"nori","plan":"gold"}` 具有平衡的分隔符號、帶有引號的名稱和合法值，但服務可能需要電子郵件、拒絕計劃名稱或禁止在目前狀態下建立帳戶。解析器和應用程式正在回答不同的問題，因此兩個結果都可能是正確的。
ToolAcre 只回答第一個問題：該文字可以在其輸入限制內解析為嚴格的 JSON 嗎？它不會載入架構、檢查所需屬性、驗證格式、聯絡資料庫或評估業務規則。當工具顯示“有效”時，請將其解釋為“格式正確的 JSON 語法”，而不是將其視為來自將使用該值的系統的批准。
第一級：格式良好的語法
語法驗證檢查 JSON 語法：一個頂級值、正確配對的容器、帶引號的物件名稱、有效的逗號和冒號、合法字串、合法數字和精確文字。它拒絕 `NaN` 和 `Infinity`、註解、尾隨逗號和單引號字串。它接受任何語法有效的形狀，包括單獨的數字或具有不熟悉欄位的物件。
格式錯誤的來源有一個文字故障點，因此 ToolAcre 可以報告第一個不可能字元的行和列。缺少逗號可能會導致報告下一個引用；尾隨逗號可能會導致報告結束分隔符號。修復語法會建立一個可解析的值，但不能確定該值具有另一個程式所期望的形狀或意義。
第二級：形狀
形狀驗證詢問解析的值是否與宣告的合約相符。使用者架構可能需要 `email`，將 `age` 限制為至少 18 的整數，將 `tier` 限制為 `free` 或 `pro`，並禁止未知屬性。 `{"email":false,"tier":"gold"}` 是有效的 JSON 語法，但不符合這些結構規則，因為值類型和允許的選擇是錯誤的。
JSON Schema 是表達此類限制的一種方法，但 ToolAcre 不會執行它。模式驗證器通常會報告實例路徑（例如 `/tier`）、關鍵字（例如 `enum`）以及解釋性訊息而不是解析器插入符號。診斷此等級時，將架構版本和 API 合約保留在有效負載旁邊；更改標點符號不會修復錯誤形狀的正確解析值。
第三級：意義
意義取決於超出檔案靜態形狀的事實和規則。 `accountId` 可以在不命名帳戶的情況下具有正確的字串模式。開始日期可以符合 ISO 樣式格式，但晚於結束日期。數量可以為正但超過當前庫存。這些故障需要應用程式上下文、儲存狀態或欄位之間的關係。
一些語意限制可以在模式中近似，但許多屬於可以使用權威資料和事務狀態的服務邏輯。此層級的錯誤回應應識別相關欄位或規則，而不會假裝 JSON 文字格式錯誤。 ToolAcre 無法重現這些決策，因為它既不知道合同，也不將輸入發送到擁有業務規則的應用程式。
工作範例：通過三項檢查的一個有效負載
從 `{"sku":"A-19","quantity":3,"warehouse":"north"}` 開始。 ToolAcre 接受它：所有名稱和值都遵循 JSON 語法。然後，模式可以需要一個物件、一個非空字串 SKU、一個正整數數量和一個記錄的倉庫代碼。假設該有效負載也通過了這些約束。兩項檢查均未確認 SKU A-19 存在或 North 擁有三個單位。
庫存服務根據目前記錄執行第三次檢查，並可能因不可用而拒絕請求。改變縮排不能改變結果。如果 `quantity` 寫成 `03`，語法會先失敗；如果是 `"3"`，解析將會通過，但模式類型檢查將會失敗；使用數字 `3` 時，只保留活畜規則。因此，由於三個不同的原因，同一欄位可能在三個不同的層上失敗。
每張支票所屬的地方
在編輯時儘早執行語法驗證，因為後續檢查無法對未解析的文字進行可靠操作。在每個不受信任的應用程式邊界強制執行宣告的形狀，而不是假設客戶端已經這樣做了。評估擁有所需狀態的元件中的業務不變量，尤其是當答案可能在請求之間發生變化時。
用戶端檢查可改善回饋，但不會取代伺服器端強制執行。相反，伺服器回應「invalid JSON」應該保留用於解析失敗，而不是用於每個被拒絕的請求。清晰的分離產生有用的診斷：用於語法的行和列、用於結構約束的實例路徑以及用於語義衝突的特定於域的程式碼或訊息。 ToolAcre 僅提供第一類。
這不包括什麼
此格式化程式不會建立或評估 JSON 架構、選擇架構草稿、解析架構參考、插入預設值或將字串強制轉換為數字。它也不知道 API 的 OpenAPI 檔案或自訂驗證約定。在輸入旁邊提供模式不會改變 ToolAcre 的結果，因為該工具中沒有模式處理步驟。
語法驗證也不會在此偵測重複的物件名稱； `JSON.parse` 保留格式化前最後一次出現的情況。它也不保證數位精確度、規範位元組、安全渲染或授權。每個問題都需要自己的合約和實施。避免將它們壓縮成一個綠色的「有效」徽章，因為這樣做會隱藏收集了哪些證據以及從未提出過哪些問題。
重點：「有效」需要限定符
驗證每項驗證宣告。 「有效JSON」表示文字遵循文法。 「針對此模式有效」表示解析的值滿足命名的結構契約。 「服務接受」是指目前應用規則允許操作。在許多工作流程中，通過一個層對於下一個層是必要的，但並不能證明所有後續層都已通過。
使用 ToolAcre 格式化和檢查嚴格語法，包括拒絕非 JSON 文字，例如 `NaN` 和 `Infinity`。然後使用實際管理有效負載的模式和應用程式。當請求仍然失敗時，請在其自身層讀取錯誤，而不是重複重新格式化正確的 JSON。該工具沒有模式檢查，並明確的邊界比過於寬泛的有效性承諾更有用。