블로그 • AI / JSON Schema

iPhone 18 AI 기능 뒤의 데이터 구조: Apple Intelligence, App Actions, JSON Schema는 어떻게 연결되나

iPhone 18의 AI 동작이 앱에 연결되는 것은 제품 소개 문장이 아니라, Intent 파라미터에 맞춘 JSON Schema 때문이다. 시스템 모델은 후보 필드를 낸다. @Parameter 가 앱이 받을 수 있는 것을 선언한다. Schema는 그 사이에 있고, 맞지 않는 객체는 동작에 들어가지 않는다.

제품 이야기는 iPhone 18이 하드웨어 업그레이드만이 아닌 이유 에 있다. 지시 하나가 문구에서 API로 가는 길은 App Actions 데이터 경로 에 있다. 이 글은 필드만 다룬다. 타입이 어떻게 대응하는지, 어떤 값을 거절해야 하는지.

• Intent 파라미터는 앱 쪽의 타입 계약이다
• JSON Schema는 모델 출력을 막는 같은 필드 표다
• AppEnum은 enum에 대응한다. AppEntity는 id만 받고 표시 이름은 받지 않는다
• additionalProperties가 false면 추가 키는 바로 실패한다

세 쪽이 어떻게 연결되는가

앱이 받을 수 있는 값은 Intent 파라미터에 적는다. 설명은 App Intent에 파라미터 추가. 모델은 JSON 객체를 제안할 수 있지만 필드 표는 바꾸지 못한다.

1. 1
   시스템 쪽이 후보를 낸다

   기기 모델이나 단축어가 객체를 채운다. 동작 이름, 수량, 수령 방식, 상품 id. 이것은 후보이지 이미 실행된 호출이 아니다.

2. 2
   앱 쪽이 타입을 선언한다

   각 파라미터는 문자열, 정수, 고정 열거, 또는 해석이 필요한 엔티티다. 선택 파라미터는 required에 넣지 않는다.

3. 3
   Schema가 통과 여부를 정한다

   후보는 먼저 Schema를 통과한다. 통과해야 Intent에 쓴다. 실패하면 검증에서 멈추고 동작도 API도 호출하지 않는다.

타입이 어떻게 맞는가

필드 표 밖의 키는 additionalProperties: false 로 거절한다. 모델이 note나 user를 더 써도 동작에 들어가지 않는다.

검증기에 붙일 수 있는 Schema

아래 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가 필요한 이유 에 있다. 이 글은 그 표를 앱 동작 파라미터에 연결한다.

다른 두 글과의 분담

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가 필요한 이유와 같은 글인가요?

아니다. 그 글은 모델 출력에 모양이 필요한 이유다. 이 글은 그 모양을 앱 동작 파라미터에 맞추고, 키가 더 있거나 열거가 틀리면 거절한다.

정리

Apple Intelligence와 앱 동작은 같은 필드로 만난다. 동작 이름, 타입, 열거, 엔티티 id. JSON Schema는 그 표를 실패할 수 있는 검사로 만든다.

결론: 파라미터 타입을 먼저 Schema에 맞춘다. 추가 키는 거절한다. 엔티티는 id만 받는다. 검증에 실패하면 동작에 넣지 않는다.

블로그로 돌아가기