구조화된 출력은 스키마 제약까지 보장하지 않는다

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

Structured Outputs는 객체 구조를 맞추더라도 Provider가 지원하지 않는 JSON Schema 제약 키워드를 생성 전에 제거할 수 있습니다. 작성자는 OpenAI 변환본을 72개 값에 검증해 허용값이 2개에서 36개로 늘어난 것을 측정했고, Gemini의 최신 표면에서는 2개에서 96개로 늘어났다고 기록했습니다. Gemini는 `oneOf`를 `anyOf`처럼 처리할 수 있어 분기 의미도 달라집니다. 따라서 모델 응답을 원본 스키마로 다시 검증하거나, 제거된 조건을 추적하는 `schema-envoy` 같은 변환 계층을 사용해야 합니다.

실용적 조언

Provider에 전달하기 전 원본 JSON Schema와 Provider 변환본을 비교해 제거된 키워드를 기록해야 합니다. 모델 응답을 받은 뒤에는 원본 스키마 전체를 다시 검증해 문자열 길이, 숫자 범위, 배열 크기, 중복 허용 여부를 확인해야 합니다. `schema-envoy`는 이런 변환과 제거 제약 검사를 자동화하며, 재현에는 `ajv`와 README만 필요하고 API 키는 필요하지 않습니다.
OpenAI의 strict 모드에서 선택 속성을 required로 바꿀 때는 해당 속성의 타입을 `null`과의 union으로 재작성해야 합니다. Gemini의 경우 사용하는 API 표면이 최신 `parametersJsonSchema`인지 구형 `FunctionDeclaration.parameters`인지 구분하고, `oneOf`가 필요한 분기에는 `anyOf` 변환으로 인한 중복 일치 가능성을 별도로 검사해야 합니다.

섹션별 상세

OpenAI의 strict: true는 구조 준수와 세부 제약 준수를 분리합니다. 작성자는 `pattern`, `format`, `minLength`, `maxLength`, `minimum`, `maximum`, `multipleOf`, `minItems`, `maxItems`, `uniqueItems`를 포함한 지원 제외 키워드 19개가 생성 전에 스키마에서 제거되고, 제거 사실을 알리는 신호도 없다고 적었습니다. OpenAI의 문서화된 변환 규칙을 적용한 다섯 속성 스키마를 ajv로 72개 값에 검증한 결과, 원본 스키마의 허용값은 2개였지만 변환 후에는 36개로 늘었고 35개 값의 판정이 거부에서 허용으로 바뀌었습니다.

Gemini에서는 지원 범위와 분기 스키마의 의미 변화가 별도 문제로 제기됩니다. 작성자는 11월 JSON Schema 확장에 해당하는 최신 `parametersJsonSchema` 표면에서 비교 스키마의 키워드 7개가 제거되자 96개 값 모두가 허용됐으며, 원래 스키마에서는 2개만 허용됐다고 측정했습니다. 구형 `FunctionDeclaration.parameters` 표면은 지원 키워드가 총 22개이고, Google 문서상 `oneOf`를 `anyOf`로 읽기 때문에 Zod의 `discriminatedUnion`이 내보내는 배타적 분기 조건도 그대로 보존되지 않습니다.

Provider 경계를 통과한 뒤에도 원본 스키마의 제약을 별도로 검사해야 한다는 결론이 제시됩니다. 작성자가 만든 `schema-envoy`는 Provider별 지원 부분집합으로 변환하면서 제거한 키워드와 유효성이 바뀐 구체적 값을 기록하고, 응답 후 제거된 제약만 다시 검사하는 validator를 반환합니다. 선택 속성을 required로 바꿀 때 null union 재작성까지 생략하면 기존에 유효했던 형태 12개 중 11개가 거부되는 사례도 있어, 변환 규칙과 사후 검증을 함께 적용해야 구조 보장으로 인한 과신을 줄일 수 있습니다.

용어 해설

구조화된 출력(Structured Outputs): — 모델 응답을 JSON Schema 형태에 맞춰 생성하도록 유도하는 기능입니다. 다만 Provider가 지원하지 않는 제약 키워드는 생성 전에 스키마에서 제거될 수 있어, 객체 구조는 맞아도 문자열 길이·숫자 범위·배열 조건 같은 세부 제약은 보장되지 않습니다.
JSON 스키마(JSON Schema): — JSON 데이터의 타입과 구조, 값의 허용 조건을 선언하는 표준입니다. 이 글에서는 Provider가 지원하는 키워드만 생성 단계에 적용하고 나머지 조건은 응답 후 별도 검증해야 한다는 차이가 핵심으로 다뤄집니다.
엄격 모드(strict: true): — Structured Outputs에서 모델이 스키마 구조를 따르도록 Provider의 변환 규칙을 적용하는 설정입니다. OpenAI에서는 모든 속성을 required로 만들고 선택 속성을 null과의 union으로 바꾸지만, 일부 제약 키워드는 조용히 제거합니다.
oneOf: — 여러 스키마 분기 중 정확히 하나와 일치해야 한다는 JSON Schema 조건입니다. Gemini는 이를 anyOf처럼 읽는다고 문서화하고 있어 여러 분기와 동시에 일치하는 값에서 원래의 배타적 의미가 유지되지 않습니다.
ajv: — JSON Schema에 따라 데이터를 검증하는 JavaScript 라이브러리입니다. 글에서는 원본 스키마와 Provider 변환 후 스키마를 72개 또는 96개의 값으로 비교하는 재현 실험에 사용되며, API 키 없이 검증 결과를 확인할 수 있습니다.

언급된 도구

schema-envoy추천

Provider별 JSON Schema 부분집합으로 변환하고 제거된 키워드, 유효성 판정이 바뀐 구체적 값, 사후 재검증용 validator를 제공하는 라이브러리입니다.

ajv중립

원본 스키마와 Provider 변환 스키마를 값 코퍼스에 적용해 허용·거부 결과를 비교하는 JSON Schema 검증 라이브러리입니다.

Zod중립

`discriminatedUnion`을 통해 `oneOf`를 생성하는 스키마 정의 도구로 소개됩니다.