Blog • AI / JSON Schema

The Data Shape Behind iPhone 18 AI: How Apple Intelligence, App Actions, and JSON Schema Connect

An AI action on iPhone 18 reaches an app through a JSON Schema aligned with the Intent parameters, not through a product paragraph. The system model proposes fields. @Parameter declares what the app can accept. The schema sits between them: an object that does not match never enters the action.

The product story is in why iPhone 18 is more than hardware. How one request travels from a phrase to an API is in the App Actions data path. This article is only the fields: how types map, and which values must be rejected.

• Intent parameters are the app's type contract
• JSON Schema is the same field list, used to stop model output
• AppEnum maps to enum. AppEntity accepts an id, not a display name
• With additionalProperties false, an extra key fails immediately

How the three sides connect

The values an app accepts are written as Intent parameters. See Adding parameters to an app intent. A model may propose a JSON object. It may not rewrite the field list.

1. 1
   The system proposes a candidate

   The on-device model or a Shortcut fills an object: action name, quantity, fulfillment, and item id. That is a candidate, not a call that has already run.

2. 2
   The app declares types

   Each parameter is a string, an integer, a fixed enum, or an entity that must be resolved. Optional parameters stay out of required.

3. 3
   The schema decides whether it proceeds

   The candidate passes your schema before it is written into the Intent. On failure it stops at validation. The action does not run, and the API is not called.

How the types line up

Keys outside the field list are rejected by additionalProperties: false. An extra note or user from the model still cannot enter the action.

A schema you can paste into a validator

The schema below matches one order action: a fixed intent name, plus item id, quantity, and fulfillment. It is your contract, not Apple's wire format.

{
  "$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"
  }
}

A natural-language fulfillment, or an empty item_id, does not pass. Only a passing object continues on the execution path from the previous article.

Four shapes that should fail

Why model output needs a schema first is in why AI needs JSON Schema. This article attaches that list to an app action's parameters.

How this differs from the other two articles

Check the field list in JSONNote

1. 1
   Paste the schema

   Paste the schema above into JSON Schema. Confirm intent is const and fulfillment is an enum.

2. 2
   Throw one candidate at it

   Use JSON validate and paste a candidate. An empty id, an extra field, and a bad enum should all fail.

3. 3
   Diff after you edit fields

   Use JSON Diff to see whether required dropped item_id. Losing one required field is more serious than rewriting a sentence.

FAQ

Is JSON Schema Apple's request format?

No. Apple describes the action with App Intent parameter types. The schema is your check between the model output and perform(). If it does not match, do not call the action.

Why can't the entity field be the product name?

Names change and collide. The key of an AppEntity is a stable id. The schema requires a non-empty string for that id. The name is only for display.

Should an optional parameter appear in the schema?

Put it in properties, not in required. Missing is still valid. If it is present, it must match the type.

Can the action run once validation passes?

Not yet. The schema only proves the shape. The entity id still has to resolve. A valid shape with a missing object is still not an order.

Is this the same article as why AI needs JSON Schema?

No. That one explains why model output needs a shape. This one aligns that shape with an app action's parameters. An extra key or a wrong enum is a reject.

Conclusion

Apple Intelligence and an app action meet on the same fields: action name, types, enums, and an entity id. JSON Schema turns that field list into a check that can fail.

Direct conclusion: align parameter types with the schema first. Reject extra keys. Accept only an id for an entity. A failed check never enters the action.

Back to the blog