2026 JSON Schema 相容性怎麼驗收：三家模型共用一套定義嗎？

JSON Schema 官方規格目前列有 Draft 2020-12，但規格版本不代表模型 API 已完整實作所有關鍵字；可參考 JSON Schema 官方規格總覽 與 Draft 2020-12 說明 驗證版本邊界。本週建議先把業務核心 Schema、供應商轉換器與統一樣例集分開，再以 OpenAI、Gemini、Claude 各自的介面文件逐項驗收；不要把原始檔案直接視為三家共用格式。

這篇內容適合維護多模型適配層、需要建立 Schema 轉換邊界的平台工程師；也適合負責 API 驗收、希望用同一組輸入比較結果的測試人員。若您負責 Schema 設計，重點則是刪除沒有業務價值的深層巢狀與供應商專用寫法。

先確認「相容」究竟指哪一層

跨模型的 JSON Schema 相容性至少分成四層，不能以「請求成功」作為唯一通過標準。

• 規格層：檔案是否符合指定 JSON Schema 版本，語法與型別是否可由標準驗證器解析。
• 介面層：Schema 是否能以正確參數包裝到 OpenAI Structured Outputs、Gemini Structured Output 或 Claude Structured Outputs 的請求格式。
• 輸出層：模型回應是否能通過對應的結構驗證，包括必填欄位、枚舉、陣列項目與額外屬性限制。
• 業務層：欄位內容是否符合權限、資源狀態、資料庫約束與事實要求。

JSON Schema 驗證器的工作方式能說明一個關鍵邊界：驗證器判斷的是資料是否符合 Schema，不會替團隊判斷資料是否真實或適合執行。因此「結構通過」與「業務可用」必須在報告中分欄記錄。

第一步：由 Schema 作者建立可共享核心

Schema 作者不應先追求三家平台都能接受的最大功能集合，而應先保留業務真正需要的最小核心。建議逐項勾選：

• [ ] 固定規範識別與版本，並在檔案中記錄 $schema 的用途。
• [ ] 明確定義物件、字串、數字、布林值、陣列等基本型別。
• [ ] 為會影響流程的欄位列入 required，不要只依賴模型自行補值。
• [ ] 只在業務真的需要時使用 enum、陣列限制與額外屬性控制。
• [ ] 釐清 $ref、$defs 等引用是否能被目標介面接受，不能只因標準允許便直接使用。
• [ ] 為 additionalProperties 寫清楚目的：是拒絕未知欄位、容許擴充，還是只為了方便開發。

這裡的核心不是把所有規範關鍵字刪光，而是分辨「刪除後是否改變業務含義」。例如，移除只用於文件描述的限制，通常只是可接受的適配；移除代表權限範圍的枚舉，則可能讓錯誤請求進入下游，應直接阻斷。

第二步：為每家供應商設計可追蹤轉換

適配層應把核心 Schema 當作來源檔，另外輸出供應商版本，而不是在執行期間靜默修改原始內容。OpenAI 的 Structured Outputs 官方指南、Gemini Structured Output 文件及 Claude 工具使用文件應分別列為驗收依據。

轉換器至少要記錄以下資訊：

1. 來源 Schema 版本與雜湊值。
2. 目標模型、API 版本及請求介面。
3. 被保留、改寫、拒絕或移除的關鍵字。
4. 每次轉換的原因，以及是否影響結構或業務語義。
5. 轉換後 Schema 的驗證結果與回滾方式。

特別要檢查參數包裝與欄位名稱。某平台可能要求把結構化定義放在特定輸出格式欄位，另一平台則在工具宣告中傳遞；即使兩者最後都產生 JSON，請求形狀也不代表相同。對不支援的關鍵字，應優先選擇明確拒絕或進入人工審查，而不是默默刪除。

提醒：若轉換器移除了 required、權限相關枚舉或未知屬性限制，報告不能只寫「供應商不支援」，還要標記受影響的業務規則，並決定是否改用供應商專用 Schema 或拆分工作流。

第三步：讓測試人員以同一樣例集比較結果

跨模型 JSON Schema 自動化測試的關鍵，不是把三個成功回應並排，而是讓每個平台面對完全相同的輸入、業務前置條件與驗證器。樣例集至少應包含：

• 正常輸入：所有必要欄位及合法枚舉值均存在。
• 缺欄位：移除一個會影響流程的必要欄位。
• 錯誤型別：把字串、數字、布林值或陣列故意互換。
• 未知屬性：加入核心 Schema 沒有列出的欄位。
• 深層巢狀：檢查巢狀物件、陣列項目與引用轉換是否一致。
• 超長輸入：觀察截斷、拒絕、解析不完整或欄位遺失的差異。

測試報告應同時保存請求版本、模型識別、API 版本、Schema 版本、測試日期、回應狀態碼、原始回應、結構驗證結果及業務驗證結果。模型拒絕請求、回傳無法解析的內容、通過結構但被業務規則拒絕，必須分成三類，否則團隊無法判斷問題在介面、模型還是下游。

第四步：FAQ 先釐清常見誤判

一份核心定義可以共用，但執行檔案不必相同

三家模型可以共享欄位語義、型別、必填規則與合法值範圍；真正送出的 Schema 則應由轉換器產生。這個做法可保留單一業務來源，又能讓平台差異顯性化，避免工程師為了某一次請求成功而直接修改核心定義。

2020-12 是規格基準，不是三家 API 的承諾

JSON Schema 2020-12 能作為作者與驗證器的共同參考，但各模型文件只代表該平台已聲明的支援範圍。任何「完整支援」的說法都必須回到指定介面、指定版本與實際樣例，不能由規格文件或另一家平台的能力推導出來。

結構合規不能保證資料正確

模型可以產生型別正確、欄位齊全，卻不存在的資源編號、過期的狀態或超出使用者權限的操作。這也是為什麼 Agent 執行器與下游消費者必須擁有獨立的安全與語義驗收，而不能把 Schema 驗證當作完整防線。

第五步：由 Agent 執行器加上安全閘門

即使工具參數已符合 Schema，危險操作也不應直接執行。執行器應在模型輸出與實際 API 之間再檢查：

• 權限主體是否有權操作指定資源。
• 資源識別碼是否存在、屬於正確租戶且仍在有效狀態。
• 是否有幂等鍵，重試時會否重複扣款、刪除或提交。
• 操作範圍是否符合目前工作階段與人工授權。
• 是否需要人工確認、速率限制或唯讀模式。

這些檢查不應被塞進一個難以維護的 Schema 關鍵字中。Schema 負責描述可解析的形狀，執行器負責限制可執行的動作，兩者邊界清楚，才容易在模型或 API 更新後重跑驗收。

第六步：由下游消費者驗收語義與事實

資料庫、工作流與報表系統不能只接收「驗證器通過」的結果。下游仍要檢查欄位間關係，例如結束時間不可早於開始時間、貨幣與金額精度必須一致、狀態轉移符合既定流程，以及外部資源真的存在。

當內容涉及事實時，應保留來源、查詢時間或工具回應，而不是要求模型在 JSON 中自行宣稱正確。若下游無法獨立核驗，這筆結果應標記為待審，而不是因為格式漂亮便進入正式資料表。

用條件分支決定是否共用

平台團隊可以依照以下決策條件落地：

• 若三家都能接受核心型別、必填、枚舉與陣列規則，且轉換沒有刪除業務限制，則共用一份業務核心 Schema，產生三份介面版本。
• 若只有某一家不支援引用、額外屬性或特定條件式規則，但可用等價結構保留語義，則選用供應商專用 Schema，並將轉換納入版本控制。
• 若轉換後無法保留權限、資源範圍、狀態關係或幂等要求，則阻斷上線，不以「模型已回傳有效 JSON」作為例外理由。
• 若三家在拒絕行為、深層結構或長輸入處理上差異太大，則拆分工作流，讓不同模型負責不同階段，避免用一份 Schema 強行抹平風險。

若團隊還在建立 API 適配規範，可先參考 Vuncloud 幫助中心整理測試環境與權限管理需求；這類文件不應取代官方 API 版本記錄，而是協助團隊固定內部操作流程。

驗收報告的三張表應固定下來

何時應使用遠端 Mac 測試環境

若跨模型驗收只在單一開發者電腦上執行，常會漏掉不同軟體版本、命令列工具、憑證權限與連線設定造成的差異；若測試團隊需要批量建立隔離工作區，也應把測試環境版本寫入報告，而不是只記錄模型名稱。

相較於臨時使用 Windows 或 Linux 工作站，這類方案常見的缺點是 Apple 平台工具鏈與測試條件不一致、團隊無法快速重建同一環境，並且實體設備排程會限制並行驗收。自購 Mac 對長期固定負載或需要實體介面的團隊可能更合理，但對短期跨模型回歸、CI/CD 驗證與多組環境切換，租用 Vuncloud 的遠端 Mac 測試環境通常更容易按批次建立、重置與交接；可先查看 Vuncloud Mac 雲端租用方案，再依測試週期、權限要求與是否需要實體硬體作出選擇。