JSON Schema가 실제로 해결하는 것
핵심 요약: Schema는 구조와 타입을 다스리지 업무 의미를 다스리지 않습니다. 필드 누락, 타입 오류, 범위 밖 열거를 막고, 금액이 0 초과 같은 규칙은 코드에 남습니다.
핵심부터 말하면, JSON Schema가 구조, 타입, 범위, 형식을 강제하게 하고, 필드 간 규칙, 업무 불변 조건, 외부 상태는 코드에 남기세요. 공개 API와 공유 페이로드에는 도입하고, 다섯 필드 내부 서비스에는 도입하지 마세요.
"이 데이터 모양이 올바른가"에 답하지, "이 데이터가 말이 되는가"에 답하지 않습니다.
잘하는 것
구조 완전성. 어떤 필드가 존재해야 하는지, 추가 필드가 허용되는지(required, additionalProperties).
타입. port가 숫자인지 문자열인지, tags가 배열인지 스칼라인지. 이것만으로 다국어 시스템의 방어 코드가 크게 줄어듭니다.
범위. enum, minimum/maximum, 문자열과 배열 길이.
형식. 날짜, 이메일, URI, UUID용 format과 이를 강제하는 검증기.
중첩. 객체와 배열의 모든 수준이 자체 제약을 얻고, 오류가 정확한 경로를 담습니다.
문서화. Schema가 계약입니다. 필드를 바꾸면 diff가 영향 범위를 보여 줍니다. 타입과 폼도 생성해 한 정의가 여러 소비자에게 공급됩니다.
못 하는 것
필드 간 의존. "종료가 시작보다 뒤여야 함"은 if/then/else로 표현할 수 있지만 결과가 세 줄 코드보다 길고 읽기 어렵습니다.
업무 불변 조건. "재고는 음수가 될 수 없음"은 외부 상태에 달려 있습니다. Schema는 한 문서만 봅니다.
의미. price: -100은 {"type": "number"}를 완벽히 만족합니다. 합법적인 가격인지는 Schema의 지식 밖입니다.
운용 가능한 분업
| 계층 | 소유자 |
|---|---|
| 문법: 유효한 JSON인가 | 파서 |
| 구조: 필드, 타입, 범위, 형식 | JSON Schema |
| 의미: 필드 간, 업무 규칙, 외부 상태 | 애플리케이션 코드 |
| 안전: 크기, 깊이, 속도 | 게이트웨이 / 미들웨어 |
이를 한곳에 몰면 Schema가 다섯 수준의 if/then과 수백 줄로 자랍니다. 그 시점에 사람들은 이를 우회합니다.
이득이 되는 때
- 소비자가 알려지지 않은 공개 API
- 같은 페이로드를 읽는 여러 서비스
- 오타가 빠르게 실패해야 하는 설정 주도 시스템
- 계약에서 타입이나 폼 생성
다섯 필드와 프런트엔드 하나의 작은 내부 서비스에는 손으로 쓴 검사가 유지하기 더 빠릅니다. 거기에 Schema를 도입하는 것은 부정적인 작업입니다.
FAQ
JSON Schema 도입 여부를 어떻게 결정하나?
공개 소비자, 같은 페이로드를 읽는 여러 서비스, 타입이나 폼 생성 필요를 저울질하세요. 다섯 필드와 프런트엔드 하나의 작은 내부 서비스에는 손으로 쓴 검사가 유지하기 더 빠릅니다.
필드 간 규칙이 왜 코드에 남아야 하나?
"종료가 시작보다 뒤여야 함"은 if/then/else에 밀어 넣을 수 있지만 결과가 몇 줄 코드보다 길고 읽기 어렵습니다. Schema는 외부 상태도 볼 수 없습니다.
Schema가 페이로드 크기와 중첩 깊이를 검증해야 하나?
아니요. Schema는 크기나 깊이가 아니라 구조를 기술합니다. 그 한도는 게이트웨이나 미들웨어 계층에 속합니다.