博客 • AI / JSON Schema

iPhone 18 AI 功能背後的數據結構：Apple Intelligence、App Actions 與 JSON Schema 如何連接？

iPhone 18 上的 AI 動作能接到 App，靠的不是一段產品介紹，而是一份和 Intent 參數對齊的 JSON Schema。系統模型給出候選字段，@Parameter 聲明 App 能接受什麼。Schema 在兩者中間：對不上的對象進不了動作。

產品敘事見 iPhone 18 爲什麼不只是硬件。一條指令怎麼從短語走到 API，見 App Actions 的數據路徑。本篇只寫字段：類型怎麼映射、哪些值必須拒絕。

• Intent 參數是 App 側的類型合同
• JSON Schema 是你用來卡住模型輸出的同一份字段表
• AppEnum 對 enum，AppEntity 只收 id，不收展示名
• additionalProperties 爲 false，多出來的鍵直接失敗

三邊怎麼接上

App 能接受的值寫在 Intent 參數上。說明見 爲 App Intent 添加參數。模型可以提議一個 JSON 對象，但不能改這張字段表。

1. 1
   系統側給出候選

   設備上的模型或快捷指令填出一個對象：動作名、數量、履約方式、商品 id。這只是候選，不是已經執行的調用。

2. 2
   App 側聲明類型

   每個參數是字符串、整數、固定枚舉，還是必須解析的實體。可選參數不放進 required。

3. 3
   Schema 決定放不放行

   候選對象先過你的 Schema。通過才寫入 Intent。失敗就停在校驗，不調用動作，也不打 API。

類型怎麼對上

字段表以外的鍵用 additionalProperties: false 拒絕。模型多寫一個 note 或 user，也不能混進動作。

一份能貼進校驗器的 Schema

下面這份對齊一個下單動作：意圖名固定，參數裏有商品 id、數量和履約方式。它是你的契約，不是 Apple 的線上格式。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": ["intent", "parameters"],
  "properties": {
    "intent": { "const": "StartOrder" },
    "parameters": {
      "type": "object",
      "additionalProperties": false,
      "required": ["item_id", "quantity", "fulfillment"],
      "properties": {
        "item_id": { "type": "string", "minLength": 1 },
        "quantity": { "type": "integer", "minimum": 1 },
        "fulfillment": { "enum": ["pickup", "delivery"] }
      }
    }
  }
}

{
  "intent": "StartOrder",
  "parameters": {
    "item_id": "sku_42",
    "quantity": 1,
    "fulfillment": "pickup"
  }
}

把履約方式寫成自然語言，或把 item_id 留空，這條就不能過。通過之後才交給上一篇說的執行路徑。

四種應該拒絕的形狀

爲什麼模型輸出先要 Schema，見 AI 爲什麼需要 JSON Schema。本篇把那張表接到 App 動作的參數上。

和另外兩篇怎麼分工

在 JSONNote 裏對上這張表

1. 1
   貼上 Schema

   把上面的 Schema 貼進 JSON Schema。確認 intent 是 const，fulfillment 是 enum。

2. 2
   用一條候選去撞

   用 JSON 校驗 貼一條候選。空 id、額外字段、錯誤枚舉都應該失敗。

3. 3
   改字段後再比

   用 JSON Diff 看 required 裏有沒有少掉 item_id。少一個必填，比改一句文案更危險。

常見問題

JSON Schema 是 Apple 的請求格式嗎？

不是。Apple 用 App Intent 的參數類型描述動作。Schema 是你放在模型輸出和 perform() 之間的校驗。對不上就不要調用。

爲什麼實體字段不能是商品名？

名稱會變、會重複。AppEntity 的主鍵是穩定 id。Schema 用非空字符串卡住 id，名稱只給人看。

可選參數要不要寫進 Schema？

要寫進 properties，但不要放進 required。這樣缺了仍合法，出現了則必須符合類型。

校驗通過就可以執行動作嗎？

還不行。Schema 只證明形狀。實體 id 仍要查詢解析成功。形狀對、對象不存在，一樣不能下單。

和「AI 爲什麼需要 JSON Schema」是同一篇嗎？

不是。那篇講模型輸出爲什麼要有形狀。本篇講這個形狀怎樣對齊 App 動作的參數，多一個鍵或錯一個枚舉就要拒絕。

總結

Apple Intelligence 和 App 動作之間，靠的是同一組字段：動作名、類型、枚舉和實體 id。JSON Schema 把這組字段寫成可以失敗的檢查。

直接結論：參數類型先對齊 Schema；多出來的鍵拒絕；實體只收 id；校驗失敗就不進入動作。

返回博客