JSON Toolkit

LLM 구조화 출력 실패기: strict 모드의 Schema는 이렇게 고쳐 쓴다

핵심 요약: 평범한 JSON Schema에 바로 strict를 붙이면 400이 돌아온다. 모든 필드 필수, 모든 객체에 additionalProperties 봉인, $ref와 allOf는 즉시 거부. 이 글은 공급자 제약에 맞춰 느슨한 schema를 strict 호환 버전으로 일괄 개写하는 방법과 널 허용 유니언, 하드 리밋, refusal 분기 체크리스트를 제시한다.

중급약 8분 소요2026-11-19 발행2026-11-19 업데이트
LLM strict 모드 JSON Schema 개写 규칙 도식

결론: strict: true는 "조금 더 신중하게" 정도의 스위치가 아니라 JSON Schema의 부분 집합만 받아들이는 계약이다. 모든 필드 필수, 모든 객체에 additionalProperties 봉인, $ref와 allOf는 즉시 거부. 개写하지 않고 strict를 붙이면 더 신뢰할 수 있는 출력 대신 400이 돌아온다.

같은 schema가 로컬 검증기에서는 멀쩡히 통과하다가, strict: true를 붙여 모델 API에 보내면 그대로 반송된다. 모델이 멍청해진 게 아니다. 공급자가 "제약 디코딩"에 필요한 schema 부분 집합에 단단한 경계선을 그었고, 당신의 schema가 그 선을 넘었을 뿐이다.

1. strict는 대체 무엇을 바꾸나: 샘플러를 문법에 잠그다

평범한 모드에서 모델이 생성하는 JSON은 당신의 schema에 "대체로" 맞을 뿐이고, 프롬프트의 "JSON으로 출력하세요" 한 줄이 뒷받침한다. OpenAI 공식 evals에서 gpt-4-0613의 프롬프트만으로 복잡한 schema 준수율은 40% 미만이었다. strict를 켜자 gpt-4o-2024-08-06이 같은 평가 세트에서 100%를 달성했다.

원리는 제약 디코딩(constrained decoding)이다. API는 첫 요청에서 당신의 schema를 유한 상태 기계로 컴파일하고, 디코딩 단계의 모든 토큰은 상태 기계의 통과 허가를 받아야 한다. 모델은 schema를 위반하는 토큰을 "내보낼 수 없다". 이건 모델에게 주의를 주는 게 아니라 물리적으로 자물쇠를 채우는 행위다. 대가는 두 가지: 새 schema의 첫 컴파일에 추가 시간이 들고(보통 10초 이내, 복잡한 schema는 1분까지), 첫 토큰에 5-8%의 지연이 늘어난다. 컴파일 산출물은 캐시되어 이후 요청은 비용을 다시 내지 않는다.

무엇을 보장하고 무엇을 보장하지 않는지 분명히 하자: 문법과 모양은 잠기지만 의미론은 그렇지 않다. 모델은 여전히 estimate_hours에 400을 자신 있게 채워 넣고, 틀린 이메일을 뽑아낼 수 있다. 모양은 바닥이지 천장이 아니다. 의미 품질은 평가 세트로 지킬 수밖에 없다. 2026년 최전선 모델도 부하 상태에서 약 0.4%의 파형률이 남는다. 재시도 루프는 여전히 필수품이다.

2. 세 가지 단단한 규칙: 전부 필수, 남는 키 봉인, 널 허용

strict 모드가 schema에 요구하는 개写 조건은 세 가지뿐이지만, 하나하나가 평범한 schema 작성 직관과 정반대다:

  1. 모든 필드를 required에 적는다. strict는 선택적 필드라는 개념을 받아들이지 않는다. "선택"을 표현하려면 필드를 required에 남겨 두되, 타입을 널 허용 유니언 "type": ["string", "null"]로 쓰고, 누락 시 모델이 null을 반환하게 한다. 이는 required에 정말 필요한 필드만 나열하는 일반적인 JSON Schema 관행과 정확히 반대다.
  2. 모든 객체에 additionalProperties: false를 명시한다. 평범한 실무에서는 흔히 이를 설정하지 않는다(본 사이트의 additionalProperties의 세 가지 런타임 표현 글 참조). 그러나 strict 모드에서 이것은准入 조건이며, 빠뜨리면 오류가 난다. 이유는 단순하다. 상태 기계는 선언된 키만 생성할 수 있고, 선언되지 않은 키는 문법상 애초에 도달 불가능하기 때문이다.
  3. Python 사용자의 함정: Pydantic은 기본값이 있는 필드를 required에서 떨어뜨린다. priority: str = "low" 한 줄이면 생성된 schema의 required가 한 항목 모자라서 strict가 즉시 거부한다. 기본값을 없애거나 아래 스크립트로 일괄 보완해야 한다.

세 규칙은 중첩된 모든 객체 층에 재귀적으로 적용되어야 한다. 최상위만 고치고 하위 객체를 방치하면 여전히 400이 나온다. 최소 적합 예는 다음과 같다:

{
  "type": "object",
  "properties": {
    "intent": { "type": "string", "enum": ["book", "cancel", "question", "other"] },
    "note": { "type": ["string", "null"] }
  },
  "required": ["intent", "note"],
  "additionalProperties": false
}

3. 이런 쓰기는 바로 400: 금지 키워드와 무효 키워드

strict 모드는 JSON Schema의 부분 집합만 지원한다. 키워드를 두 부류로 나눠 처리한다:

부류 키워드 strict 모드에서의 행동
즉시 거부 $ref / $defs 참조, allOf, not, dependentRequired, dependentSchemas, if/then/else API가 오류를 반환하고 요청 실패
조용히 무효 pattern, minLength, maxLength, format, minimum, maximum, multipleOf(파인튜닝 모델) 오류도 강제도 없음. 정규식 제약은 애플리케이션 계층에서 직접 검증

처리 방식이 다르다. 전자는 개写 필수다. $ref를 인라인으로 펼치고 allOf를 properties에 통합한다. 후자는 남겨 둘 수 있지만(받아들이는 설정도 있다) 방어선으로 절대 취급하지 마라. "pattern": "^v\\d+\\.\\d+\\.\\d+$"로 버전 형식을 보장하려는 쓰기는 strict 아래에서 무방비 상태이며, 응답을 받은 뒤 명시적 검증을 한 번 더 돌려야 한다. 최상위 규칙이 하나 더 있다. schema 루트는 배열이나 벌거벗은 유니언 타입이어서는 안 되며, object로 한 겹 감싸야 한다.

4. 하드 리밋: 5000 속성, 10층 중첩, 12만 문자

키워드가 모두 적합해도 규모가 상한을 넘으면 오류가 난다. OpenAI 공식 수치:

  • schema 전체에서 객체 속성 최대 5000개, 중첩 최대 10층(Anthropic 쪽 중첩 상한은 약 6층);
  • 속성명, 정의명, 열거값, const 값의 문자열 총 길이 120000자;
  • 열거값은 합계 최대 1000개. 문자열 열거가 250개를 넘는 단일 속성은 총 길이 15000자 이내라는 조건이 붙는다.

평소에는 이 한계에 닿지 않지만, "회사 사전 전체를 열거값으로 쓰기"와 "3층 객체 그래프를 한 층에 눌러 담기"는 둘 다 실제 장애 현장이다. 만나면 쪼갠다. 거대한 schema를 여러 번 호출로 나누거나 구조를 평탄화한다. 덤으로, 출력 키의 순서는 schema 안의 키 순서와 일치한다. 고정 순서에 의존하는 하류 파서는 이를 특성으로 써도 된다.

5. 스크립트 하나로 느슨한 schema를 일괄 strict화

손으로 층마다 고치면 빠뜨리기 쉽다. 아래 재귀 스크립트(DevToolLab 2026 가이드가 제시한 패턴)는 "모든 객체 봉인, 모든 키 필수"를 한 번에 채운다:

def make_strict(schema: dict) -> dict:
    """additionalProperties:false + 모든 키 필수, 모든 층에 재귀."""
    if isinstance(schema, dict):
        if schema.get("type") == "object" and "properties" in schema:
            schema["additionalProperties"] = False
            schema["required"] = list(schema["properties"].keys())
            for value in schema["properties"].values():
                make_strict(value)
        elif isinstance(schema, dict):
            for value in schema.values():
                make_strict(value)
    elif isinstance(schema, list):
        for item in schema:
            make_strict(item)
    return schema

함께 쓸 워크플로 제안: 먼저 샘플 JSON에서 schema 뼈대를 역추정한다(본 사이트의 /convert/schema 도구 페이지는 JSON에서 Schema로의 단방향 역추정을 한다). 뼈대를 출발점 삼아 strict의 세 규칙으로 조이고, 마지막에 make_strict로 바닥을 깐다. 스크립트는 모양만 다룬다는 점에 주의하라. 널 허용 유니언, 열거, 의미 필드는 여전히 사람이 정한다. $ref를 포함한 schema는 먼저 인라인으로 펼친 뒤 넘겨야 한다.

6. Anthropic의 등가 쓰기: tool-as-schema

Anthropic에는 대응하는 strict: true 스위치가 없다. 2026년의 정석은 응답 schema를 도구의 input_schema로 등록하고, tool_choice로 모델에게 그 호출을 강제하는 것이다:

await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  tools: [{ name: "emit", description: "Emit final summary", input_schema: schema }],
  tool_choice: { type: "tool", name: "emit" },
  messages,
});

도구 호출 채널 자체가 JSON을 검증하므로 효과는 strict 모드와 등가다. 차이는 세부에 있다. Anthropic의 중첩 상한은 약 6층, .optional()이 아니라 .nullable()을 지원한다. 세 공급자(OpenAI, Anthropic, Gemini)가 받아들이는 schema 부분 집합은 완전히 같지 않다. 한 부의 schema를 무수정으로 건너 쓰는 것은 신뢰할 수 없으며, 모델을 바꾸면 재검증이 필요하다.

7. refusal, 절단, 타임아웃을 먼저 분기하고 나서 재시도를 논하라

strict 모드에서 잘못된 것을 받았다면 원인은 세 가지뿐이고, 대응은 완전히 다르다:

  • refusal: 모델이 실행을 거부(불안전한 요청 등). 응답의 refusal 필드가 참이면 JSON을 읽는 것은 무의미하다. 사람에게 넘기거나 요청을 고쳐 쓴다.
  • 절단: finish_reason이 length라면 max_tokens가 부족해 출력이 물리적으로 불완전하다. schema 제약으로는 절단을 구할 수 없다. 예산을 늘리거나 출력 구조를 압축한다. 판정과 부분 복구는 절단 JSON의 판정과 복구 글을 참조.
  • 파형: 공급자가 부분 집합을 완전히 지원하지 않으면 나쁜 JSON이 여전히 도착할 수 있다. 재시도할 때 "다시 한 번"만 말하지 말고 구체적인 검증 오류 원문을 프롬프트에 붙이라. "severity는 low/medium/high/critical 중 하나여야 합니다. urgent가 출력되었습니다. 고쳐서 다시 출력하세요." 오류 맥락을 붙인 재시도는 평균 재시도 횟수를 3회에서 약 1.5회로 줄인다.

재시도에는 단단한 상한(예: 2회)을 두고, 초과하면 더 작은 모델로 교정을 내리거나 사람의 큐로 강등시킨다. 한 줄의 나쁜 출력이 파이프라인 전체를 끌어죽게 두지 마라.

8. 배포 전 자가 점검 목록

점검 항목 통과 기준
required 모든 객체의 모든 필드가 required 안에 있다
additionalProperties 모든 객체에 명시 false, 가장 깊은 층까지 재귀
선택 의미론 ["string", "null"] 유니언으로 흉내. 벌거벗은 optional 없음
금지 키워드 $ref / allOf / if-then-else / dependentRequired 없음
무효 키워드 pattern, format 계열 제약은 애플리케이션 계층에서 이중 검증
규모 속성 ≤5000, 중첩 ≤10층, 문자열 총량 ≤12만 자
분기 refusal / length / 해석 실패 세 갈래를 분리 처리
재시도 검증 오류 원문 첨부, 상한 2회, 초과 시 강등
의미론 schema 밖의 evals 또는 필드 단위 단언으로 보완

이 목록을 통과하면 모양의 신뢰성은 사실상 잠긴다. 의미론과 계약 진화(schema 버전화, 망가진 schema를 CI에서 먼저 붉게 만드는 법)는 Schema 계약을 CI에 용접하기를 참조.

FAQ

strict 모드는 필드 값의 정확성을 보장하나?

아니다. 디코딩 시점에 문법과 모양만 잠그고, "모든 키가 존재하고 타입이 맞으며 열거가 합법"이라는 것만 보장한다. 값의 의미론은 보장하지 않는다. 모델은 여전히 형식은 맞지만 내용이 틀린 데이터를 낼 수 있다. 의미 계층은 평가 세트나 필드 단위 단언으로 지킨다.

왜 선택 필드도 required에 적나?

strict의 상태 기계는 선언된 모든 속성이 도달 가능하길 요구하며, required 항목을 생략하면 검증에서 거부된다. 선택 의미론은 ["string", "null"] 유니언 타입으로 흉내 낸다. 필드는 반드시 나타나고 값은 null일 수 있으며, 하류는 null로 누락을 판단한다.

pattern과 minLength는 완전히 쓸모없나?

파인튜닝 모델과 대부분의 strict 설정에서는 강제되지 않는다. 오류도 내지 않기 때문에 가장 위험하다. 방어선이 있다고 믿지만 실제로는 없다. 이런 제약에 의존하는 응답은 수령 후 ajv나 jsonschema로 명시적으로 재검증하라.

strict가 응답을 느리게 하나?

새 schema의 첫 요청에만 컴파일 비용이 든다(보통 10초 이내, 복잡한 schema는 1분까지). 컴파일 산출물이 캐시된 뒤에는 첫 토큰에 약 5-8%의 지연 증가만 있다. 정상 상태에서는 거의 체감되지 않는다. schema가 자주 바뀔 때만 비용이 된다.

모델 버전을 바꾸면 무엇을 재검증하나?

세 가지: 그 버전이 지원하는 schema 부분 집합의 변화, refusal과 finish_reason 필드의 존재 여부, 중첩과 규모 상한의 조임 여부. 공급자마다 받아들이는 부분 집합이 다르므로, schema를 건너 재사용하기 전에 최소 요청 하나로 검증하라.

참고 자료

관련 문서

JSON Schema 계약 테스트: 검증 규칙을 CI에 용접하기

스키마는 작성으로 끝이 아니라 거기서부터 망가지기 시작합니다. 오타 하나가 검증을 조용히 느슨하게 만들고, 리팩터링 하나가 픽스처 전체를 오작동시킵니다. 이 글은 정례·부례·스냅샷 3종 세트, 스키마 자체의 린트, 컴파일 한 번 재사용, CI에 설치하는 네 개의 게이트로 이루어진 실행 가능한 계약 테스트 구성을 다룹니다.

중급약 8분 소요2026-11-05 업데이트

LLM이 뱉은 JSON이 중간에 잘렸을 때: 먼저 중지 이유를 보고, 그다음 복구를 이야기하자

모델이 돌려준 JSON이 중간에 끝나고 파서는 열 번호 하나만 알려 준다. 괄호를 닫으면 다시 파싱은 되지만 빠진 필드는 데이터 안에 숨어 버린다. 이 글은 stop_reason 판정, 출력 토큰 상한 산정, 스키마 필드 순서, 부분 복구의 정직한 공개까지 정리해 잘림 상황에서 고쳐도 되는 범위와 반드시 재시도해야 하는 범위를 나눈다.

실전약 5분 소요2026-11-14 업데이트

additionalProperties를 닫지 않으면 Schema 검증은 검증이 아니다

검증을 통과해도 데이터가 깨끗하다는 뜻이 아닙니다. Pydantic은 기본으로 미선언 필드를 무시하고, Zod는 제거하며, Ajv는 그대로 통과시킵니다. 본문은 무음 수용의 세 가지 형태를 보이고, 객체를 닫고 강제 형변환을 제어하며 모든 중첩 단계를 조이는 완전한 방법을 제시합니다.

Intermediate약 8분 소요2026-11-02 업데이트