구조화 출력 도구

LLM 구조화 출력 JSON Schema 검증 및 자동 수정기

함수 호출이나 response_format용 JSON Schema를 붙여넣어 OpenAI, Claude, Gemini에서 HTTP 400 거부를 유발하는 규칙을 정확히 찾고 정규화된 strict 스키마를 원클릭으로 복사하세요.

실행 방식로그인 불필요 · 100% 브라우저 로컬스키마 규칙 확인: 2026년 11월 11일

원본 JSON Schema 입력

자동 정규화된 strict JSON Schema

request.example

{
  "type": "object",
  "properties": {
    "invoiceId": {
      "type": "string"
    },
    "currency": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "USD",
        "EUR",
        "GBP"
      ]
    },
    "totalAmount": {
      "type": "number"
    },
    "customer": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "taxId": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "name",
        "taxId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "invoiceId",
    "currency",
    "totalAmount",
    "customer"
  ],
  "additionalProperties": false
}

호환성 진단 상세

$.additionalPropertiesstrict 모드에서는 모든 객체 스키마에 "additionalProperties": false를 설정해야 합니다.
$.required (currency, customer)OpenAI strict 모드에서는 모든 속성을 required에 포함해야 하므로 선택적 속성을 nullable 유니온으로 변환했습니다.
$.properties.invoiceId.pattern엄격한 구조화 출력은 값 제약 키워드를 거부하는 경우가 많으므로 규칙을 description으로 옮기고 앱 코드에서 Zod나 Pydantic으로 검증하세요.
$.properties.totalAmount.minimum엄격한 구조화 출력은 값 제약 키워드를 거부하는 경우가 많으므로 규칙을 description으로 옮기고 앱 코드에서 Zod나 Pydantic으로 검증하세요.
$.properties.customer.additionalPropertiesstrict 모드에서는 모든 객체 스키마에 "additionalProperties": false를 설정해야 합니다.
$.properties.customer.required (taxId)OpenAI strict 모드에서는 모든 속성을 required에 포함해야 하므로 선택적 속성을 nullable 유니온으로 변환했습니다.

엔지니어링 참고 및 배포 점검

유효한 Draft-07 JSON Schema가 LLM API에서 HTTP 400으로 실패하는 이유

제약 디코딩 엔진은 생성을 시작하기 전에 JSON Schema를 문맥 자유 문법이나 유한 상태 토큰 마스크로 컴파일합니다. 문법 컴파일을 빠르고 유한하게 유지하기 위해 OpenAI, Anthropic, Google는 각각 표준 Ajv, Zod, Pydantic이 기본 출력하는 것보다 더 엄격한 JSON Schema 하위 집합을 강제합니다.

예를 들어 OpenAI의 strict: true 모드는 additionalProperties: false가 빠지거나 required 배열에서 누락된 속성이 있는 객체를 거부하므로, 선택적 필드도 required에 넣되 ["string", "null"] 같은 nullable 유니온으로 표현해야 합니다. 반대로 Google Gemini의 generationConfig.responseSchema는 additionalProperties 키워드 자체를 아예 거부합니다.

스키마 규칙	OpenAI Strict (strict: true)	Anthropic 엄격 도구 / JSON	Gemini responseSchema
루트 type이 "object"여야 함	필수	필수	권장
모든 객체에 "additionalProperties": false	필수 (누락 시 400)	필수 (누락 시 400)	거부됨 (포함 시 400)
모든 속성을 "required"에 포함	필수 (선택 항목은 [type, "null"] 사용)	선택 키 생략 허용	선택 키 생략 허용
정규식 pattern / minLength / format	strict 문법에서 미지원	제한적; description 및 앱 검증 권장	대부분의 문자열 format 미지원

안정적인 구조화 추출 및 도구 스키마를 위한 운영 체크리스트

문법 거부를 자동 수정하면 HTTP 400은 통과하지만, 안정적인 추출을 위해서는 스키마 내부의 명확한 의미 정의도 중요합니다. 필드 이름을 직관적으로 짓고 깊은 재귀 중첩을 피하며 모델의 거부 응답(refusal)을 항상 명시적으로 처리하세요.

정규식 패턴, 문자열 길이 제한, 숫자 범위는 필드의 description으로 옮기고 파싱 후 Zod나 Pydantic으로 확정 검증하세요.
JSON.parse를 호출하기 전에 finish_reason(또는 stop_reason)에서 max_tokens 잘림 여부를 확인하세요. strict 모드라도 잘린 JSON은 파싱에 실패합니다.
파싱된 구조화 출력을 읽기 전에 안전 또는 정책 거부(refusal) 필드를 먼저 처리하세요.

자주 묻는 질문

OpenAI strict 모드에서 선택적 필드는 어떻게 표현하나요?

객체의 required 배열에 필드 이름을 포함시키고 type을 ["string", "null"] 같은 nullable 유니온으로 변경하세요. 위 자동 수정기가 이 변환을 자동으로 수행합니다.

OpenAI에서 작동하는 스키마를 Gemini가 거부하는 이유는 무엇인가요?

OpenAI strict 모드는 모든 객체에 additionalProperties: false를 요구하지만, OpenAPI 기반인 Gemini의 responseSchema 파서는 additionalProperties를 포함한 알 수 없는 키워드를 거부합니다. 위 대상 드롭다운을 Google Gemini로 전환하면 호환되지 않는 키가 제거됩니다.

그래도 LLM 응답을 Zod나 Pydantic으로 검증해야 하나요?

네. 제약 디코딩은 JSON 타입과 필수 키 일치를 보장하며, 양수 금액·유효한 날짜·인가된 ID 같은 비즈니스 불변 조건은 애플리케이션 검증기가 담당합니다.

실제 모델 라우트에서 strict 스키마 테스트하기

위에서 정규화된 JSON Schema를 복사해 LLMFly AI에서 비스트리밍 요청으로 검증하세요.

API 키 만들기