JSON Schema 자동생성기가 놓치는 null과 배열 타입 함정
샘플 JSON 하나를 넣으면 스키마를 뚝딱 만들어주는 JSON Schema 생성기는 API 문서화나 폼 검증 초안을 잡을 때 매우 편리합니다. 하지만 "생성됐다"는 사실과 "정확하다"는 사실은 다릅니다. 이 도구뿐 아니라 대부분의 샘플 기반 스키마 자동생성기가 구조적으로 놓치는 두 가지 지점 — null 값 처리와 배열 타입 추론 — 을 실제 코드 로직으로 뜯어보고, 왜 이런 한계가 생기는지, 어떻게 수동으로 보정해야 하는지 정리했습니다.
1. 샘플 기반 추론의 근본적 한계
JSON Schema 자동생성기는 마법이 아니라 단순한 규칙입니다. 입력된 JSON 값 하나하나의 typeof를 확인해서 대응하는 스키마 타입을 매핑할 뿐입니다. 문자열이면 string, 불린이면 boolean, 정수면 integer로 변환하는 식입니다. 문제는 이 방식이 "지금 이 샘플에 존재하는 값 하나"만 보고 판단한다는 점입니다. 실제 운영 데이터에서 같은 필드가 다른 타입의 값을 가질 수 있다는 가능성은 애초에 고려 대상이 아닙니다. null과 배열은 이 한계가 가장 뚜렷하게 드러나는 두 지점입니다.
2. null 값: nullable이 아니라 "null 전용" 스키마가 생성된다
JSON Schema 생성기의 실제 추론 함수를 보면 첫 줄이 if(val===null)return{type:'null'};입니다. 즉 값이 null이면 무조건 {"type":"null"}만 돌려주고, 다른 타입과 결합한 {"type":["string","null"]} 같은 유니온 표현은 애초에 생성 로직에 없습니다. 문제는 실무 API 응답에서 어떤 필드가 "값이 있을 때는 문자열, 없을 때는 null"인 경우가 흔하다는 점입니다. 하필 샘플로 넣은 JSON에서 그 필드가 null이었다면, 생성된 스키마는 이후 그 필드에 실제 문자열 값이 들어온 데이터를 전부 검증 실패로 처리합니다.
{"middleName": null}을 넣으면 생성되는 스키마는"middleName": {"type": "null"}이 스키마로
{"middleName": "Kim"}이라는 정상 데이터를 검증하면 타입 불일치 오류가 발생합니다. 올바른 스키마는 사람이 직접"middleName": {"type": ["string", "null"]}로 고쳐야 합니다.
3. 배열: 첫 번째 요소만 보고 나머지는 버려진다
배열 처리 로직도 마찬가지로 단순합니다. if(val.length>0)s.items=inferSchema(val[0],...) — 배열의 첫 번째 요소 하나만 재귀 호출해서 그 결과를 items 스키마로 통째로 채택합니다. 배열 안에 타입이 섞인 값(heterogeneous array)이 있어도 두 번째 요소부터는 아예 읽지도 않습니다. JSON Schema 명세 자체는 items에 여러 타입을 허용하는 anyOf나 튜플 검증(prefixItems) 같은 표현을 지원하지만, 이 생성기는 그런 표현을 시도조차 하지 않고 첫 요소의 타입 하나로 단순화합니다.
| 입력 배열 | 실제 구성 | 생성된 items 스키마 | 문제 |
|---|---|---|---|
[1,"two",3] | 숫자+문자열 혼합 | {"type":"integer"} | 문자열 "two"는 검증 시 오류 처리됨 |
["admin","user"] | 문자열만 | {"type":"string"} | 문제 없음(우연히 동질적 배열) |
여기서 두 번째 행처럼 실제 배열이 처음부터 동질적(모든 요소가 같은 타입)이면 우연히 정확한 스키마가 나옵니다. 문제는 개발자가 넣은 샘플 하나만으로는 그 배열이 "우연히 동질적이었던 것"인지 "원래 이질적인데 샘플이 운 좋게 통일된 것"인지 구분할 수 없다는 점입니다.
4. 배열 안의 객체 구조가 다를 때는 더 위험하다
배열 요소가 객체인 경우 이 한계는 한층 더 커집니다. 예를 들어 사용자 목록 배열의 첫 번째 객체에는 email 필드가 있지만 두 번째 객체부터는 phone 필드가 추가로 있다면, 생성기는 오직 첫 번째 객체의 properties만 보고 items 스키마를 확정합니다. phone 필드는 생성된 스키마 어디에도 등장하지 않아, 이 필드가 있는 실제 데이터를 additionalProperties: false 옵션과 함께 검증하면 오히려 유효한 데이터가 거부되는 역설적인 상황이 생깁니다.
5. 실전 체크리스트: 생성된 스키마를 그대로 배포하지 않기
- 샘플 JSON에 null 값이 하나라도 있다면, 해당 필드의
"type":"null"을["실제타입","null"]배열로 직접 고칠 것. - 배열 필드는 실제 운영 데이터에서 요소 타입이 항상 동일한지 먼저 확인하고, 섞여 있다면
anyOf로 수동 보강할 것. - 배열 안 객체들의 필드 구성이 다양하다면 여러 샘플을 모아 필드 합집합을 직접
properties에 반영할 것. - 생성 결과는 초안일 뿐이며,
minLength·minimum·enum같은 제약 조건은 이 도구가 추가하지 않으므로 별도로 채워야 합니다.
자주 묻는 질문
Q. null 필드가 있는 스키마를 그대로 API 검증에 쓰면 어떻게 되나요?
해당 필드에 null이 아닌 실제 값(문자열·숫자 등)이 들어오면 스키마 검증이 실패합니다. 사람이 ["실제타입","null"] 형태로 직접 수정해야 정상 작동합니다.
Q. 배열의 타입 혼합 문제를 자동으로 잡아주는 방법은 없나요?
이 도구는 샘플 하나의 첫 요소만 보는 단순 규칙이라 자동 감지 기능이 없습니다. 배열 요소 타입이 다양할 가능성이 있다면 생성 후 반드시 직접 검토해야 합니다.
Q. 여러 개의 샘플 JSON을 합쳐서 넣으면 문제가 해결되나요?
아니요. 이 도구는 한 번에 하나의 JSON 값만 입력받아 그 구조를 그대로 반영하므로, 여러 샘플을 합치는 기능 자체가 없습니다. 여러 샘플을 비교해 필드·타입의 합집합을 만드는 작업은 사람이 직접 해야 합니다.
Q. 생성된 스키마에 required 배열은 정확한가요?
required 배열은 샘플 객체에 실제로 존재하는 모든 키를 그대로 필수로 지정합니다. 특정 필드가 선택적(optional)이어야 한다면, 생성 후 required 배열에서 해당 필드명을 수동으로 제거해야 합니다.