AI가 JSON 형식을 자꾸 바꿀 때, 구조화된 출력을 쓰는 법
결론: AI에게 JSON을 요청했는데 키가 빠지거나 순서·형식이 바뀐다면 일반 텍스트 지시만 반복하지 말고 구조화된 출력과 JSON Schema를 검토하세요. OpenAI는 스키마를 따르는 응답을 설명하고, Google Gemini도 제공한 JSON Schema에 맞는 응답을 구성하는 기능을 문서화합니다.[1][2] 다만 스키마가 맞는 것과 내용이 사실인 것은 별개입니다.
대표 이미지는 Wikimedia Commons의 1U server and peripherals.jpg를 잘라 사용했습니다. 원본 라이선스: CC BY 2.0.
이 기능이 필요한 경우
AI 응답을 앱에서 읽어 이름·날짜·분류를 저장하거나, 매번 같은 필드로 결과를 받아야 할 때 유용합니다. 블로그 글처럼 사람이 읽는 문장을 받는 작업에는 일반 응답이 더 간단할 수 있습니다.
JSON Schema는 답변의 모양을 제한합니다. AI가 잘못된 이름이나 날짜를 넣지 않는다는 보증은 아닙니다.
일반 JSON 요청이 흔들리는 이유
“JSON으로 답해 줘”라고만 쓰면 모델이 설명 문장을 앞에 붙이거나, 필수 키를 빼거나, 숫자를 문자열로 바꿀 수 있습니다. 애플리케이션이 기대하는 구조와 실제 응답이 어긋나면 파싱 단계에서 멈춥니다.
구조화된 출력의 기본 생각
먼저 필요한 필드와 각 필드의 타입을 정합니다. 예를 들어 고객 문의 분류라면 category는 정해진 목록 중 하나, urgent는 참·거짓, summary는 문자열로 정의합니다. OpenAI 문서의 Structured Outputs는 개발자가 정한 JSON Schema를 응답 형식에 적용하는 방식으로 설명됩니다.[1] Google 문서도 JSON Schema에 맞는 구조화된 응답을 설명합니다.[2]
| 필드 | 형식 예시 | 초보자 확인 |
|---|---|---|
| category | 정해진 문자열 목록 | 목록 밖 값을 허용할지 결정 |
| urgent | boolean | “예” 대신 true·false를 받을지 확인 |
| summary | string | 빈 문자열을 허용할지 결정 |
| items | array | 항목이 없을 때 빈 배열인지 확인 |
설계 순서 4단계
1. 먼저 결과를 사람이 적어 보기
코드부터 쓰지 말고 최종 결과 예시를 하나 적습니다. 어떤 키가 항상 있어야 하는지, 없어도 되는 키가 무엇인지 구분하세요.
2. 타입과 허용값을 줄이기
날짜를 자유로운 문장으로 받으면 “다음 주 초”처럼 해석이 갈립니다. 저장할 값이라면 날짜 형식이나 미확인 상태를 별도 값으로 정하세요. 공식 수치가 없을 때는 빈칸을 임의 숫자로 채우지 않도록 지시합니다.
3. 모델의 거절 응답도 처리하기
안전 정책이나 입력 문제로 모델이 요청을 거절할 수 있습니다. 성공 응답만 JSON이라고 가정하지 말고, 거절·오류·빈 응답을 분리해 처리하세요. OpenAI 문서도 구조화 출력의 거절을 별도 고려 사항으로 설명합니다.[1]
4. 파싱 뒤 내용 검증하기
JSON 파싱에 성공해도 이메일 주소가 실제 주소인지, 날짜가 가능한 날짜인지, 분류가 업무 범위에 맞는지는 앱이 다시 검사해야 합니다. 형식 검증과 사실 검증을 한 단계로 합치지 마세요.
해치의 확인 과정
2026년 8월 31일 OpenAI와 Google의 공식 구조화 출력 문서를 비로그인 HTTP로 받아 HTTP 200을 확인하고, 두 문서에서 JSON Schema 관련 설명과 예제 키워드를 대조했습니다. 실제 API 키로 모델을 호출하거나 모델별 실패율을 측정하지는 않았습니다.
이번 실행에서는 API 호출 결과를 성능 수치로 포장하지 않았습니다. 문서에 나온 기능 범위만 글에 반영했습니다.
초보자 체크리스트
- 필수 키와 선택 키를 구분했는가?
- 문자열·숫자·참거짓·배열 타입을 정했는가?
- 허용값 목록 밖의 응답을 처리하는가?
- 거절·오류 응답을 JSON 성공으로 오인하지 않는가?
- 형식이 맞은 뒤에도 내용과 출처를 확인하는가?
자주 묻는 질문
구조화된 출력이면 AI가 틀리지 않나요?
아닙니다. 구조화된 출력은 응답 모양을 일정하게 만드는 기능입니다. 필드 안의 문장이 사실인지, 분류가 적절한지는 별도로 검증해야 합니다.
모든 AI 답변에 JSON Schema가 필요한가요?
아닙니다. 사람이 읽고 끝나는 답변에는 오히려 불편할 수 있습니다. 다른 프로그램이 결과를 읽거나 같은 필드를 반복해서 저장할 때 우선 검토하세요.
관련 글
공식 출처
먼저 필요한 데이터 모양을 작게 정한 뒤, 형식 검증과 내용 검증을 나눠 구현하세요.
최종 확인일: 2026년 8월 31일
