JSON Schema와 일반 JSON은 어떻게 다른가요?

일반 JSON은 실제 데이터를 담는 문서입니다. JSON Schema는 그 데이터가 어떤 구조와 타입을 가져야 하는지 설명하고 검증하는 문서입니다. 따라서 문법적으로 읽히는 JSON이라도 필수 필드가 빠지거나 허용되지 않은 값이 들어가면 Schema 검증에서는 실패할 수 있습니다.

대형 언어 모델의 도구 호출에 Schema가 필요한 이유는 무엇인가요?

도구 호출에서는 모델이 생성한 인자가 바로 실행기로 전달될 수 있습니다. Schema는 필드 이름, 타입, 필수 여부, 허용 값을 미리 제한해 파싱 오류를 줄입니다. 다만 접근 권한, 실제 주문 소유권, 금액의 업무 규칙까지 자동으로 보장하지는 않으므로 별도의 실행 전 검증이 필요합니다.

OpenAI, Gemini, Claude는 완전한 JSON Schema를 지원하나요?

세 플랫폼 모두 JSON Schema를 활용하지만 전체 표준을 그대로 지원한다고 보면 안 됩니다. OpenAI Structured Outputs와 Gemini Structured Output은 지원하는 하위 집합과 제약이 있고, Claude 도구 호출도 입력 Schema를 사용합니다. 내부 기준 Schema를 만든 뒤 플랫폼별 변환본과 호환성 테스트를 관리하는 편이 안전합니다.

MCP의 inputSchema와 outputSchema는 어떤 역할을 하나요?

MCP의 inputSchema는 도구가 받을 인자의 형태를 설명합니다. outputSchema는 선택 사항이며 구조화된 결과의 형태를 설명하고, structuredContent와 함께 결과 검증과 후속 처리를 돕습니다. MCP는 도구를 노출하고 호출하는 프로토콜이지, 모델이 어떤 도구를 선택할지 결정하는 모델 제어 기능 자체는 아닙니다.

하나의 JSON Schema를 모든 AI 플랫폼에서 그대로 쓸 수 있나요?

작은 객체와 기본 타입만 사용한다면 재사용 가능성이 높습니다. 그러나 참조, 조건부 조합, 추가 속성, 형식 검증처럼 플랫폼별 차이가 드러나는 키워드는 그대로 통과하지 않을 수 있습니다. 주 Schema와 플랫폼별 단순화 규칙, 버전, 변환 결과를 함께 저장해야 운영 장애를 줄일 수 있습니다.

AI 에이전트 ·

JSON Schema란 무엇인가? 왜 OpenAI, Gemini, Claude와 MCP는 점점 JSON Schema에 의존하는가?

게시 2026.08.18 약 7분

JSON Schema는 AI Agent의 응답과 도구 인자를 안정적으로 관리하는 데이터 계약입니다. 이 글에서는 OpenAI, Gemini, Claude, MCP의 구조화 출력과 도구 호출 차이를 비교하고, 플랫폼별 변환본과 회귀 검증을 운영하는 방법을 설명합니다.

판단: JSON Schema는 AI Agent의 데이터 계약으로 사용해야 합니다. 다만 OpenAI, Gemini, Claude, MCP가 지원하는 범위가 서로 다르므로 하나의 Schema를 무조건 그대로 재사용하지 말고, 내부 기준 Schema와 플랫폼별 변환본을 함께 관리하는 방식이 적합합니다.

이 글은 안정적인 구조화 응답과 도구 인자를 정의하려는 AI 애플리케이션 개발자에게 적합합니다. 플랫폼 엔지니어는 여러 모델에서 데이터 계약을 재사용하는 방법을 확인할 수 있습니다. 테스트 엔지니어는 자동 검증과 호환성 회귀 기준을 세울 수 있습니다.

JSON Schema의 역할

일반 JSON은 실제 값을 담습니다. JSON Schema는 그 값의 모양을 설명합니다. 객체인지 배열인지, 필드가 문자열인지 숫자인지, 어떤 필드가 필수인지, 허용되는 값이 무엇인지 정의합니다.

공식 JSON Schema 사양은 구조 설명과 검증을 분리합니다. 현재 공식 사양의 대표 기준은 Draft 2020-12입니다. 다만 각 API가 이 표준 전체를 구현한다는 뜻은 아닙니다. JSON Schema 공식 사양과 검증 어휘 문서를 기준으로 내부 계약을 작성하는 편이 좋습니다.

구분	일반 JSON	JSON Schema	AI Agent에서의 의미
목적	실제 데이터 전달	데이터 구조와 제약 설명	모델과 실행기의 계약
예시	`{"status":"paid"}`	`status`의 타입과 허용 값 정의	후속 파서가 예측 가능
검증	문법만 확인	필수 필드와 타입까지 확인	잘못된 호출을 실행 전 차단
한계	업무 의미를 알 수 없음	구조만 보장	권한과 실제 자원은 별도 확인

예를 들어 {"order_id":"a12"}는 문법적으로 올바른 JSON입니다. 그러나 Schema가 order_id, customer_id, status를 필수로 지정했다면 계약에는 맞지 않습니다. 반대로 Schema를 통과해도 해당 주문이 실제로 존재하거나 요청자에게 귀속된다는 뜻은 아닙니다.

구조화 응답과 출력 계약

구조화 응답에서는 모델이 자유로운 문장을 반환하지 않고 정해진 객체를 반환하도록 제한합니다. type, properties, required, enum이 핵심입니다. 배열의 원소 구조도 items로 지정합니다.

OpenAI Structured Outputs는 함수 도구의 strict 설정이나 구조화된 응답 형식으로 Schema 준수를 강화합니다. 일반 JSON 모드는 파싱 가능한 JSON을 만드는 데 초점을 두며 특정 Schema 일치를 보장하지 않습니다. OpenAI의 Structured Outputs 안내도 이 차이를 설명합니다.

Gemini Structured Output 역시 객체, 배열, 문자열, 숫자, 정수, 불리언 같은 기본 Schema 타입을 사용하지만 JSON Schema의 일부만 지원합니다. Gemini 공식 구조화 출력 문서에는 지원 타입과 제한 범위가 정리되어 있습니다.

출력 요구	권장 Schema 설계	실패하기 쉬운 지점
분류 결과	`enum`으로 상태값 제한	모델이 새 상태를 임의로 생성
정보 추출	필수 필드와 배열 원소 지정	누락 필드와 빈 배열 혼동
보고서 생성	중첩 객체와 명확한 설명 사용	지나치게 복잡한 조합 키워드
API 응답	내부 API 계약과 같은 필드명 사용	모델 출력용 이름과 실행용 이름 불일치

여기서 중요한 점은 값의 진실성과 구조의 정확성이 다르다는 사실입니다. 날짜가 2026-08-18 형식에 맞아도 실제 존재하는 날짜인지 별도 확인해야 합니다. 금액이 숫자여도 결제 한도를 넘지 않는지는 업무 검증 대상입니다.

Function Calling의 입력 경계

도구 호출에서 Schema는 모델이 생성할 인자의 모양을 설명합니다. 실행기는 모델이 보낸 JSON을 먼저 검증한 뒤 API나 내부 함수를 호출해야 합니다.

Claude의 도구 정의도 input_schema에 JSON Schema 객체를 넣는 방식입니다. Claude 도구 사용 공식 문서는 도구 이름, 설명, 입력 Schema를 별도 계약으로 관리하도록 안내합니다.

그러나 Schema는 권한 부여 장치가 아닙니다. 다음 항목은 실행기에서 다시 확인해야 합니다.

요청자가 해당 계정에 접근할 수 있는지 확인합니다.
주문이나 파일이 실제로 존재하는지 조회합니다.
금액, 날짜, 상태 전이가 업무 규칙에 맞는지 검사합니다.
삭제, 결제, 배포처럼 되돌리기 어려운 작업은 별도 승인 단계를 둡니다.
Schema를 통과하지 못한 요청은 모델 재시도보다 먼저 차단합니다.

운영 경험: enum으로 "paid", "cancelled"를 제한해도 모델이 실제 주문의 현재 상태를 알고 있다는 뜻은 아닙니다. Schema 검증은 형식 단계이고, 데이터베이스 조회와 권한 검증은 실행 단계입니다.

MCP 도구 계약

MCP는 도구를 노출하고 호출하는 프로토콜입니다. 모델 제공 업체의 도구 선택 로직을 대신하지 않습니다. MCP 도구에는 inputSchema가 들어가며, 선택적으로 outputSchema와 structuredContent를 사용할 수 있습니다.

MCP 공식 도구 명세에 따르면 inputSchema는 예상 인자를 정의합니다. outputSchema는 구조화 결과의 형태를 설명합니다. 서버는 정의한 출력 Schema에 맞는 결과를 제공해야 하며, 클라이언트는 결과를 검증하는 것이 권장됩니다. MCP 도구 명세를 기준으로 구현해야 합니다.

MCP 필드	책임	구현 시 확인할 점
`inputSchema`	도구 입력 형태 설명	루트 인자는 보통 객체로 설계
`outputSchema`	구조화 출력 형태 설명	선택 필드지만 사용하면 검증 기준이 생김
`structuredContent`	기계가 읽는 결과 전달	출력 Schema와 일치해야 함
`content`	사람이 읽는 결과 전달	이전 클라이언트 호환용 텍스트를 고려

MCP의 Schema 지원 범위는 버전과 클라이언트에 따라 확인해야 합니다. 2026년 8월 18일 기준으로 관련 제안에는 JSON Schema 2020-12 지원을 넓히는 내용이 있지만, 제안 상태와 실제 배포 상태를 구분해야 합니다. MCP의 Schema 관련 제안을 정식 확정 기능으로 오해하면 안 됩니다.

여러 모델 변환 전략

세 플랫폼에 하나의 Schema를 그대로 전달하는 방식은 작은 예제에서는 작동할 수 있습니다. 운영 환경에서는 위험합니다. OpenAI Structured Outputs, Gemini Structured Output, Claude 도구 호출은 모두 JSON Schema를 사용하지만 지원하는 키워드와 제약이 같다고 볼 수 없습니다.

저희는 다음 구조를 권장합니다.

내부 기준 Schema에 업무상 필요한 모든 필드를 정의합니다.
플랫폼별 지원 목록을 문서화합니다.
$ref, 복잡한 oneOf, 조건부 키워드처럼 호환성이 낮은 부분을 변환합니다.
변환 결과마다 플랫폼명, 모델명, API 버전, Schema 버전을 기록합니다.
같은 입력 샘플을 세 플랫폼에 보내 출력 구조를 검증합니다.
플랫폼 문서나 API 버전이 바뀌면 회귀 테스트를 다시 실행합니다.
실패 시 이전 변환본으로 되돌릴 수 있도록 보관합니다.

선택지	개발 속도	재사용성	장애 대응	권장도
하나의 원본을 모든 곳에 그대로 전달	높음	중간	낮음	낮음
플랫폼별 Schema를 수동 작성	낮음	낮음	중간	조건부
내부 기준본과 자동 변환본 운영	중간	높음	높음	높음
모델별 별도 업무 계약 운영	낮음	중간	높음	복잡한 업무에 적합

내부 기준본에는 참조와 업무 설명을 충분히 남겨도 됩니다. 반면 플랫폼 변환본은 지원이 불확실한 키워드를 제거하고, 필수 필드와 기본 타입 중심으로 단순화하는 편이 안정적입니다. 변환 규칙을 코드와 문서로 함께 저장해야 나중에 왜 특정 필드가 빠졌는지 추적할 수 있습니다.

업무 검증과 계약 관리

구조 검증을 통과한 뒤에는 업무 검증을 실행해야 합니다. 이 두 단계를 섞으면 장애 원인을 찾기 어렵습니다.

구조 검증: 필드 존재, 타입, 배열, 열거값을 확인합니다.
업무 검증: 날짜 존재, 주문 소유권, 금액 범위, 상태 전이를 확인합니다.
보안 검증: 권한, 도구 범위, 민감 정보 접근 여부를 확인합니다.
실행 검증: 실제 API 응답과 결과 Schema를 다시 확인합니다.

Schema에는 이름 규칙도 필요합니다. 예를 들어 order_id와 orderId를 플랫폼마다 다르게 쓰면 변환 계층이 복잡해집니다. 버전은 order.lookup.v1처럼 업무와 버전을 함께 표현하는 방식이 관리하기 쉽습니다.

필드를 추가할 때는 선택 필드로 시작합니다. 기존 필드를 삭제하거나 타입을 바꾸는 변경은 새 버전으로 분리합니다. 배열 원소의 타입 변경도 하위 호환성을 깨뜨릴 수 있으므로 별도 테스트가 필요합니다.

멀티 모델 검증과 지속적인 테스트가 필요하다면 한국 클라우드 맥 대여 환경처럼 맥 운영 체제 기반 실행 노드를 별도로 검토할 수 있습니다. 일본 사용자와 연결된 테스트라면 일본 클라우드 맥 대여 환경도 비교 대상이 됩니다.

자주 묻는 내용

FAQ는 단순한 용어 설명보다 실제 설계 판단에 초점을 둡니다. 세부 질문은 메타데이터의 구조화 답변과 함께 관리하면 검색 노출과 문서 재사용에 유리합니다.

JSON Schema와 일반 JSON의 차이

일반 JSON은 값을 전달합니다. JSON Schema는 값이 지켜야 할 구조와 제약을 설명합니다. 따라서 JSON 문법 검증만 통과한 응답과 업무 계약까지 통과한 응답은 다릅니다. AI Agent에서는 모델 출력, 도구 인자, API 응답을 같은 계약으로 연결하는 역할을 합니다.

도구 호출에 Schema가 필요한 이유

모델이 만든 도구 인자는 곧 실행 명령으로 사용될 수 있습니다. Schema는 허용 필드와 타입을 제한해 잘못된 호출을 줄입니다. 하지만 권한이나 실제 자원 존재 여부는 판단하지 못합니다. 실행기에서 접근 제어와 업무 검증을 추가해야 합니다.

세 플랫폼의 완전한 지원 여부

OpenAI, Gemini, Claude는 JSON Schema를 지원하지만 전체 표준과 동일한 기능을 제공하지는 않습니다. OpenAI와 Gemini는 구조화 출력에서 지원 하위 집합을 안내합니다. Claude는 도구 입력 Schema를 사용합니다. 따라서 플랫폼별 문서와 실제 회귀 테스트를 함께 기준으로 삼아야 합니다.

MCP의 입력과 출력 Schema

inputSchema는 도구가 받을 인자의 구조를 정의합니다. outputSchema는 구조화된 결과의 형태를 설명합니다. structuredContent는 기계가 처리할 결과이고 content는 사람이 읽을 결과입니다. MCP는 호출 프로토콜이며 모델의 도구 선택 정책과는 구분됩니다.

하나의 Schema를 그대로 재사용할 수 있는지

기본 객체, 배열, 문자열, 숫자, 불리언 정도는 재사용하기 쉽습니다. 참조와 조건부 조합, 추가 속성 제한은 플랫폼 차이로 실패할 수 있습니다. 내부 기준본을 유지하고 각 플랫폼용 변환 규칙과 버전을 저장하는 방식이 안전합니다.

구현 순서

저희가 신규 AI Agent에 적용하는 순서는 다음과 같습니다.

출력과 도구 입력을 분리해 계약을 작성합니다.
모든 필드의 타입과 필수 여부를 결정합니다.
업무 규칙과 보안 규칙을 Schema 밖의 검증 목록으로 분리합니다.
OpenAI, Gemini, Claude용 변환 규칙을 작성합니다.
MCP 도구에는 inputSchema를 먼저 적용합니다.
결과를 후속 도구가 읽는다면 outputSchema와 structuredContent를 추가합니다.
정상값, 누락값, 잘못된 타입, 권한 없는 자원 샘플을 자동 검증합니다.
API 버전 변경 때 같은 샘플을 다시 실행합니다.
실패한 Schema와 결과를 저장해 원인과 회귀 여부를 추적합니다.

JSON Schema AI Agent 설계에서 가장 큰 오류는 Schema 통과를 곧바로 업무 성공으로 해석하는 것입니다. 구조, 업무, 보안, 실행 결과를 각각 확인해야 합니다.

현재 방식이 프롬프트만으로 JSON을 만들거나 플랫폼별 Schema를 따로 관리하는 구조라면 필드 불일치, 재시도 증가, 버전별 회귀 누락이 생기기 쉽습니다. 반면 ZekVPS의 원격 맥 환경은 여러 모델의 변환 테스트와 맥 운영 체제 기반 CI 작업을 분리해 실행할 때 선택지가 될 수 있습니다. 장기간 고정 부하나 물리 장비 연결이 핵심이라면 직접 맥을 운영하는 편이 낫습니다. 임시 검증 노드와 반복 가능한 테스트 환경이 필요할 때만 ZekVPS 클라우드 맥 대여를 비교하는 것이 합리적입니다.