JSON Schema 是什麼？為什麼 OpenAI、Gemini、Claude 和 MCP 都越來越依賴 JSON Schema？

如果 AI Agent 的輸出偶爾缺欄位、工具參數格式不一致，問題通常不只是提示詞，而是缺少可驗證的資料契約。本文從結構化輸出、Function Calling、MCP 工具與跨模型適配四個場景，說明 JSON Schema 能解決什麼，以及哪些問題仍須交給業務驗證。

同一個 Agent 在不同模型上回傳的欄位名稱不一致，工具執行器因此把合法 JSON 判成無效輸入。

最快解法：把 JSON Schema 當成模型、工具、API 與測試系統共用的機器可讀契約；但不要直接把同一份 Schema 原封不動塞給所有平台。 各家介面只支援 JSON Schema 的不同子集，較穩定的做法是維護一份內部主 Schema，再產生供應商適配版本。

這篇適合三類讀者： AI 應用開發者，需要固定模型輸出與工具參數；平台工程師，需要跨模型共用資料契約；測試工程師，需要建立自動驗證與相容性回歸。

JSON Schema AI Agent 到底解決哪一層問題？

JSON 只是資料交換格式。只要雙引號、括號與逗號正確，內容就可能是合法 JSON；但合法不等於符合應用程式期待。

例如，下列資料在語法上都是合法 JSON：

{"status":"paid","amount":"100"}

{"status":"payment_completed","amount":100}

如果下游程式要求 status 只能是 pending、paid 或 failed，而 amount 必須是數字，那麼第二個範例仍可能因列舉值不合而被拒絕。JSON Schema 的作用，就是把物件、欄位、型別、必填欄位、列舉值與額外屬性規則寫成可被工具讀取的契約。

JSON Schema 目前的主流規格頁面以 Draft 2020-12 為現行版本，規格分為 Core 與 Validation 等部分；type、required、enum、properties 等關鍵字主要用來描述或驗證資料結構。可參考 JSON Schema 官方規格 與 Validation Vocabulary 文件。

這也回答了常見疑問：

JSON Schema 和普通 JSON 有什麼區別？

普通 JSON 是「實例資料」，例如某筆訂單；JSON Schema 是「描述這筆資料應該長什麼樣子」的規則。前者供系統傳遞，後者供模型、驗證器、編輯器與測試流程理解邊界。

我們在 AI Agent 中通常需要三層檢查：

1. 語法層：能否被 JSON 解析器讀取。
2. 結構層：是否符合 JSON Schema，例如欄位型別、必填欄位與列舉。
3. 業務層：資料是否真的合理，例如日期是否存在、訂單是否屬於目前使用者、金額是否落在允許範圍、狀態轉換是否合法。

JSON Schema 主要處理前兩層。它不會替我們查詢資料庫，也不會證明一個訂單編號真的存在。

四種場景中，Schema 分別放在哪裡？

第一種：結構化回答，把輸出變成可解析結果

在分類、摘要、資料抽取與工作流分派中，模型不是只要「回答得像人」，而是要產生下游程式能穩定接收的結果。

一個客服分類 Agent 可能要求：

{
  "type": "object",
  "properties": {
    "intent": {
      "type": "string",
      "enum": ["refund", "shipping", "technical"]
    },
    "priority": {
      "type": "integer"
    },
    "entities": {
      "type": "array",
      "items": {"type": "string"}
    }
  },
  "required": ["intent", "priority", "entities"],
  "additionalProperties": false
}

這裡的 enum 限定業務分類，required 防止欄位消失，additionalProperties 則可避免模型自行加入下游沒有處理的欄位。

OpenAI 的 Structured Outputs 在嚴格模式下要求輸出遵循指定 Schema，但官方文件同時明確指出，嚴格模式只支援 JSON Schema 的一部分。這表示「有 Schema」不等於「完整支援所有 Draft 2020-12 關鍵字」。可參考 OpenAI Structured Outputs 官方文件。

Gemini 的 Gemini Structured Output 也採用 JSON Schema 子集。官方文件列出可用的基本型別與物件、陣列、描述欄位等能力，因此在設計跨模型 Schema 時，不宜把複雜組合、動態引用或平台未列出的關鍵字視為必然可用。可參考 Gemini Structured Output 官方文件。

第二種：Function Calling，把 Schema 放在工具參數上

為什麼大模型工具呼叫需要 Schema？

因為模型需要知道工具接受哪些參數，而執行器需要知道如何驗證模型產生的參數。以查詢訂單為例，工具可能只允許：

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "訂單識別碼"
    },
    "include_items": {
      "type": "boolean"
    }
  },
  "required": ["order_id"]
}

資料流不是「模型直接執行 API」，而是：

1. 應用程式把工具名稱、用途與 Schema 傳給模型。
2. 模型選擇工具並產生參數。
3. 應用程式驗證參數。
4. 執行器檢查權限、資源存在性與業務規則。
5. 工具執行後回傳結果，再交給模型整理。

Gemini 官方的 Function Calling 流程也把「由應用程式執行函式」列為開發者責任，而不是讓模型本身取得執行權限；Anthropic 的 Claude 工具使用則以 input_schema 描述工具預期參數。可參考 Gemini Function Calling 文件 與 Claude Tool Use 文件。

因此要記住：Schema 能限制「參數形狀」，不能授予權限，也不能保證 order_id 對應真實訂單。權限、租戶隔離、資源查詢與副作用控制，仍須由執行器完成。

第三種：MCP 工具，同時描述輸入與輸出

Model Context Protocol 把工具暴露與呼叫流程標準化。在 MCP 工具定義中，inputSchema 用來描述工具預期接收的參數；outputSchema 可選，用來描述結構化結果；工具結果則可放在 structuredContent。

MCP 的 inputSchema 和 outputSchema 有什麼作用？

inputSchema 讓客戶端與模型知道工具需要什麼輸入。MCP 規格目前要求工具輸入的根型別為物件。outputSchema 則讓伺服器宣告回傳結果的結構，客戶端可以依此驗證。若提供輸出 Schema，伺服器必須產生符合該 Schema 的結構化結果；為了相容較舊客戶端，規格也建議同時保留序列化後的文字內容。可參考 MCP Tools 規格。

MCP 的重點是「工具如何被發現、描述與呼叫」，不是替模型決定要不要選工具。模型側仍可能有自己的工具選擇模式、強制呼叫設定與參數格式。

MCP 規格總覽也說明，JSON Schema 被用於協定中的驗證；這正是 MCP 越來越依賴 Schema 的原因：協定訊息、工具參數與工具結果需要可被不同語言、不同客戶端與不同測試工具理解。可參考 MCP 基礎規格文件。

第四種：跨模型適配，不要假設一份 Schema 到處通用

三家模型是否支援完整 JSON Schema？

不能這樣假設。OpenAI 的嚴格結構化輸出、Gemini 的結構化輸出，以及 Claude 的工具 input_schema，都存在介面層級、功能範圍或版本差異。即使三者都接受名為 JSON Schema 的物件，也不代表每個關鍵字的行為一致。

我們建議採用「主 Schema＋適配 Schema」：

• 主 Schema：按照內部資料契約設計，保留完整欄位語義、版本與業務註記。
• OpenAI 版本：只保留目標模型與嚴格模式可接受的子集。
• Gemini 版本：依 Structured Output 文件列出的型別與限制轉換。
• Claude 工具版本：以工具輸入為核心，將不需要交給模型的內部欄位移除。
• MCP 版本：依 MCP 工具根型別、輸出欄位與客戶端相容性處理。

一套 JSON Schema 能否跨平台直接複用？

只有在所有平台都支援相同關鍵字、相同根型別限制、相同引用行為，而且測試結果一致時才可以。生產環境不應只看文件宣稱，而應使用包含物件、陣列、列舉、引用與額外屬性的樣例，分別在各模型與 API 版本上驗證。

第二步：如何建立可回滾的 Schema 治理流程？

我們在多模型 Agent 中通常按以下順序落地：

1. 先定義業務資料契約

先寫清楚欄位名稱、型別、必填條件與列舉值，再決定要轉成哪一家模型的格式。不要先從某個供應商範例反推整個平台。

1. 標記每個關鍵字的層級

區分模型一定要理解的欄位，與只供後端驗證器使用的欄位。description 可以協助模型理解，但不能取代 enum、required 與執行器驗證。

1. 產生供應商適配版本

建立明確轉換規則。例如移除未被目標介面支援的 $ref，把複雜聯合型別展平成多個工具，或把根層陣列包成物件。

1. 加入結構與業務兩段驗證

第一段用 JSON Schema 驗證欄位與型別；第二段查詢訂單歸屬、日期存在性、金額上限與狀態轉換。兩段都通過後才允許執行有副作用的工具。

1. 建立版本與相容性測試

每份 Schema 都保存版本號、來源模型、API 版本、轉換規則與測試樣例。新增欄位通常可採向後相容方式；刪除必填欄位或改變列舉值，則應升級版本並保留回滾路徑。

1. 把回歸測試放進 CI/CD

每次更換模型、更新 API、調整工具描述或升級 MCP 客戶端，都重新驗證同一批樣例。測試不只看 JSON 能否解析，也要檢查 Schema 驗證結果、工具權限與實際業務結果。

JSON Schema 的 format 也要特別小心。官方規格區分 annotation 與 assertion；某些驗證器可能只把 format 當作提示資訊，而不執行嚴格判定。因此日期、電子郵件或資源識別碼等欄位，不應只依賴 format，仍要由應用程式進行語義檢查。

什麼情況不應把 Schema 當成安全邊界？

Schema 驗證成功，只代表資料符合結構契約，不代表內容可信。

以下幾種問題不能由 Schema 單獨解決：

• user_id 格式正確，但可能不是目前登入者的帳號。
• amount 是數字，但可能超過帳戶可用額度。
• date 符合日期格式，但可能是不存在的日期或已過期日期。
• status 屬於允許列舉，但不代表目前狀態可以轉換到該值。
• 工具參數型別正確，但工具可能具有刪除、付款或修改資料的副作用。

我們會把 Schema 視為「進入執行器前的第一道門」，而不是授權系統。對破壞性工具，應另外要求權限檢查、明確確認、冪等設計、審計記錄與錯誤回復。

對需要持續執行 Schema 測試、模型回歸與 macOS 自動化的團隊，真正的瓶頸往往不是 Schema 本身，而是 CI/CD 執行環境是否穩定。若測試涉及 Xcode、Apple 平台工具鏈或 macOS 專用流程，可以先查看 ZekVPS 的 Mac 使用支援說明，再依任務頻率評估執行節點。若要了解服務定位，也可參考 ZekVPS 服務介紹。

最後給一個可執行的判斷：如果團隊只偶爾呼叫單一模型、沒有工具副作用，也許簡單的結構驗證已經足夠；但只要同時接入 OpenAI、Gemini、Claude 或 MCP，就應在部署前建立主 Schema、適配版本與回歸樣例。

相較於把測試散落在不同雲端工作環境，臨時使用 Windows 或 Linux 主機處理 macOS 專用流水線，常見缺點是工具鏈不一致、環境重建成本高，以及 GUI 或 Apple 平台測試難以還原。若您需要的是短期、多模型批量驗證與穩定的 macOS CI/CD 節點，租用 ZekVPS 的遠端 Mac 會比臨時拼接不相容環境更容易維持測試一致性；若是長期滿載或需要實體介面，則應先比較自購設備與固定節點的總成本。