2026 JSON Schema 호환성 검수: 세 모델이 한 정의를 공유할까?

2026년 JSON Schema 모델 호환성 검수에서는 원본 파일을 세 모델에 그대로 넣지 말고, 공통 업무 Schema와 공급자별 변환기를 분리해야 합니다. 이 기준은 OpenAI, Gemini, Claude의 공식 문서가 각자 지원 범위를 선언한다는 전제에서만 유효합니다.

이 글은 다중 모델 적응 계층을 관리하는 플랫폼 엔지니어, 같은 입력을 여러 API에 보내는 테스트 담당자, 불필요한 중첩과 공급자 확장을 줄이려는 Schema 설계자를 위한 내용입니다. 단일 모델 설정법보다 출시 차단 조건과 책임 경계를 확인하려는 팀에 적합합니다.

먼저 정할 것: 공통 Schema와 공급자 Schema를 분리합니다

JSON Schema는 하나의 업무 데이터 구조를 설명하는 공통 언어가 될 수 있습니다. 그러나 표준 전체를 각 모델의 구조화 출력 인터페이스가 동일하게 처리한다고 가정하면 안 됩니다. JSON Schema 공식 사양 안내와 2020-12 초안 설명을 기준으로 원본의 의미를 정한 뒤, 각 플랫폼 문서에 맞춰 변환해야 합니다.

검수 대상	공통 계층에서 확인할 내용	공급자 계층에서 확인할 내용
구조	객체, 배열, 문자열, 숫자, 불리언의 목적	요청 본문에서 Schema를 감싸는 위치
필수성	반드시 있어야 하는 필드와 선택 필드	엄격 모드 또는 구조화 출력 옵션
값 제한	열거값, 형식, 배열 항목	지원되지 않는 키워드의 처리 방식
추가 필드	낯선 속성을 허용할지 여부와 업무 이유	플랫폼별 제한 또는 변환 규칙
참조	참조가 유지되어야 하는지, 펼칠 수 있는지	참조를 펼친 결과의 의미 보존

검수 기록에는 Schema 식별자, 인터페이스 버전, 테스트 실행일을 함께 남겨야 합니다. 특정 플랫폼에서 통과했다는 사실은 다른 플랫폼의 호환성을 증명하지 않습니다.

대형 Schema보다 의미가 분명한 핵심 부분집합을 선택합니다

Schema 작성자는 복잡한 표현을 추가하기 전에 해당 제약이 실제 업무 판단에 필요한지 확인해야 합니다. 필드 유형, 필수 목록, 열거값, 배열 항목, 참조, 추가 속성 정책은 대체로 먼저 검토할 대상입니다. 반면 사용하지 않는 형식 제약이나 과도한 중첩은 변환기와 테스트 케이스를 불필요하게 늘립니다.

다음 조건을 만족하면 공통 핵심 Schema에 남깁니다.

데이터베이스 열이나 외부 API 필드와 직접 대응합니다.
누락되었을 때 업무 처리가 중단되거나 보류되어야 합니다.
허용값 목록이 실제 정책을 나타냅니다.
추가 속성 허용 여부가 보안 또는 저장 정책과 연결됩니다.

조건을 만족하지 않으면 설명 문서로 옮기거나 공급자별 확장으로 분리합니다. 구조화 출력은 형태를 제한하는 도구이지, 사실 여부를 보증하는 장치가 아닙니다. JSON Schema 검증기가 구조를 확인하는 방식은 공식 검증기 안내에서 확인할 수 있습니다.

첫 번째 단계: 세 공식 문서에서 지원 범위를 대조합니다

OpenAI Structured Outputs는 OpenAI 공식 안내를 기준으로 확인합니다. Gemini Structured Output은 Gemini 구조화 출력 문서와 생성 콘텐츠 API 참고 자료를 함께 대조합니다. Claude Structured Outputs라는 표현을 사용할 때도 실제 검수 대상이 도구 사용의 입력 Schema인지, 별도 구조화 응답 기능인지 구분해야 하며, Claude 도구 사용 문서의 선언 범위를 기준으로 기록해야 합니다.

판정	적용 방식	출시 판단
세 모델에서 같은 의미로 검증됨	공통 핵심 Schema 사용	통합 테스트를 통과하면 진행
한 모델에서 표현만 다름	공급자 변환기에서 명시적으로 변환	공통 원본과 변환 결과를 함께 보관
중요한 제약이 한 모델에서 사라짐	해당 기능을 사용하지 않거나 흐름 분리	변환만으로 출시하지 않음
구조는 맞지만 업무 규칙이 다름	후단 검증과 승인 절차 추가	모델 응답만으로 실행 금지

지원하지 않는 키워드를 변환기에서 조용히 삭제하면 안 됩니다. 삭제로 인해 필수성, 허용값, 추가 필드 정책이 약해졌다면 검수 결과는 실패여야 합니다. 단순한 이름 변경과 업무 의미를 바꾸는 완화는 서로 다른 로그로 남겨야 합니다.

두 번째 단계: 적응 계층의 변환을 추적 가능하게 만듭니다

변환기는 원본 Schema의 복사본이 아니라 책임이 있는 소프트웨어 구성요소입니다. 입력에는 공통 Schema 버전과 공급자 이름을 받고, 출력에는 변환된 Schema와 경고 목록을 남겨야 합니다. 요청 포장 방식, 필드 이름, 엄격 모드, 참조 처리, 지원되지 않는 키워드의 대체 규칙을 코드와 문서에서 동일하게 관리합니다.

권장되는 변환 결과는 다음 정보를 포함합니다.

원본 Schema의 고정 식별자
공급자별 출력 Schema의 해시 또는 저장 위치
삭제, 완화, 펼침이 발생한 경로
변환으로 약해진 제약과 그에 대한 후단 검증
요청에 사용한 모델과 API 버전

OpenAI API 참고 자료처럼 요청 필드의 위치가 명시된 문서도 함께 확인해야 합니다. Schema 자체가 같아도 요청 포장 방식이 다르면 실제 호출은 실패할 수 있습니다.

질문을 바꾸어 검수합니다: 완전한 2020-12를 지원한다고 봐도 될까요?

그렇게 보면 안 됩니다. JSON Schema 2020-12는 표준 사양의 한 버전이지만, OpenAI, Gemini, Claude의 구조화 출력 또는 도구 호출 기능은 각각 문서에 적힌 지원 부분집합을 기준으로 판단해야 합니다. 한 모델에서 처리되는 키워드를 세 모델의 공통 기능으로 승격하지 않는 것이 안전합니다.

따라서 팀의 문서에는 “2020-12 사용”이라는 문장만 적지 말고 다음을 분리해 적습니다.

원본이 의도하는 표준 문법
각 공급자가 실제로 받는 문법
변환 뒤에도 보존되는 제약
별도 코드에서 검사해야 하는 업무 규칙

세 번째 단계: 같은 샘플을 세 API에 반복 투입합니다

여러 모델을 대상으로 하는 JSON Schema 자동화 테스트는 모델별로 다른 프롬프트를 만드는 방식보다 동일한 입력 계약을 유지하는 방식이 적합합니다. 테스트 샘플에는 정상 요청만 넣지 않아야 합니다. 누락 필드, 잘못된 유형, 허용되지 않은 열거값, 알 수 없는 속성, 깊은 중첩, 긴 입력을 포함해야 합니다.

각 실행마다 다음 항목을 저장합니다.

실행일과 요청 버전
모델 및 API 버전
사용한 원본과 변환 Schema
HTTP 응답 상태
원문 응답과 파싱 결과
Schema 검증 결과
업무 규칙 검증 결과
재시도 여부와 실패 원인

주의: 파싱에 성공한 JSON은 검수 통과가 아닙니다. 필드가 존재해도 허용되지 않은 값, 다른 자원의 식별자, 사실과 다른 내용이 들어가면 업무 검수에서는 실패로 처리해야 합니다.

네 번째 단계: 실행기는 Schema 이후를 차단합니다

도구 호출 인자가 Schema에 맞는다고 해서 바로 실행할 수는 없습니다. 권한, 자원 식별자, 요청자의 업무 범위, 멱등 키, 호출 대상의 상태를 실행기에서 다시 확인해야 합니다. 특히 삭제, 결제, 배포, 접근 권한 변경처럼 되돌리기 어려운 도구는 모델 출력을 승인 신호로 사용하면 안 됩니다.

조건별 선택은 다음처럼 정리할 수 있습니다.

세 모델이 핵심 필드와 값 제약을 같은 의미로 통과시키면 공통 Schema를 유지하고 공급자별 포장만 적용합니다.
한 모델에서 표현만 다르고 업무 제약이 보존되면 공급자 전용 Schema를 생성하되 원본과 변환 기록을 함께 배포합니다.
필수성이나 권한 범위 같은 중요한 제약이 사라지면 변환기를 고치거나 해당 모델의 흐름을 분리합니다.
모델 응답만으로 자원 범위와 사실성을 판정해야 한다면 자동 실행을 중단하고 후단 검증 또는 사람 승인을 추가합니다.

다섯 번째 단계: 구조 검증과 의미 검증을 분리합니다

Schema 적합성인데도 잘못된 데이터가 나오는 이유는 구조와 의미가 다른 문제이기 때문입니다. 예를 들어 날짜 형식이 맞아도 실제 존재하지 않는 일정일 수 있습니다. 사용자 식별자가 문자열이어도 현재 요청자의 권한 범위를 벗어날 수 있습니다. 열거값이 허용 목록 안에 있어도 해당 상태 전환이 업무상 허용되지 않을 수 있습니다.

하위 소비자는 다음을 확인해야 합니다.

필드 사이의 상호 관계
데이터베이스의 외래 키와 고유성 제약
자원 소유자와 요청자 권한
외부 시스템에서 조회한 사실과 응답 내용의 일치
같은 멱등 키로 재실행했을 때의 결과

이 단계에서 실패하면 모델이나 Schema만 바꾸는 것으로 해결되지 않습니다. 조회, 정책 판정, 승인, 저장을 별도 단계로 나누어야 할 수 있습니다.

최종 판정: 통과, 전용 Schema, 작업 흐름 분리

검수 보고서는 세 가지 결론 중 하나를 명확히 선택해야 합니다.

출시 가능: 세 모델에서 공통 핵심 Schema의 구조와 주요 제약이 보존되고, 동일 샘플과 후단 업무 검증을 통과합니다.
공급자 전용 Schema 필요: 공통 원본은 유지되지만 한 플랫폼의 포장이나 지원 범위 때문에 변환본이 필요합니다. 변환 경고와 회귀 테스트가 필수입니다.
작업 흐름 분리 필요: 중요한 제약이 사라지거나, 권한·사실·상태 전환을 모델 출력으로 안전하게 보장할 수 없습니다.

보고서에는 최소한 Schema 버전, 인터페이스 버전, 모델 식별자, 실행일, 샘플 묶음, 실패 분류, 승인자를 고정해 기록해야 합니다. 공급자 문서의 지원 부분집합이 바뀌면 같은 샘플을 다시 실행해야 하며, 과거 통과 결과를 새 버전의 근거로 재사용해서는 안 됩니다.

플랫폼 팀이 현재 사용하는 단일 Schema 파일을 세 모델에 직접 재사용하면 변환 실패가 조용히 누적되고, 지원되지 않는 제약이 사라지며, 모델별 재현성도 떨어질 수 있습니다. 반대로 Vuncloud의 원격 Mac 테스트 환경을 활용하면 여러 API 호출 환경을 분리해 반복 검증하고, 팀 장비를 새로 마련하지 않은 상태에서 공급자별 적응 계층을 확인할 수 있습니다. 다만 장기간 고정된 대규모 부하나 물리 장치 직접 연결이 핵심이면 자체 장비가 더 적합할 수 있습니다. 배포 전 원격 테스트 환경을 검토하는 팀은 Vuncloud의 Mac 지원 안내와 한국용 Mac mini 대여 환경을 함께 확인하면 됩니다. 처음 환경과 테스트 범위를 조율해야 한다면 Vuncloud 문의 페이지에서 필요한 모델 수, 반복 주기, 권한 조건을 전달하는 편이 효율적입니다.