JSON Schema는 또 다른 JSON 문서를 사용해 JSON 문서의 구조가 어떠해야 하는지를 기술하는 방법입니다. 코드에서 조건문으로 데이터를 수동으로 검증하는 대신, 예상되는 타입과 필수 필드, 값 제약을 선언적으로 기술한 뒤 데이터를 자동으로 검사할 수 있습니다.
draft-07의 주요 키워드
type— 예상되는 값의 타입(object, string, number, array 등).required— 반드시 존재해야 하는 객체 필드의 목록.properties— 객체의 각 필드에 대한 개별 스키마 설명.enum— 값을 특정 옵션 집합으로 제한.pattern— 정규 표현식으로 문자열을 검증. 예를 들어 사업자등록번호 형식 검사에 사용.
예시: 사업자등록번호를 위한 pattern
한국의 사업자등록번호는 "123-45-67890"처럼 3자리-2자리-5자리, 총 10자리 숫자를 하이픈으로 구분한 형식을 가집니다. B2B 인보이스 API의 스키마라면 다음과 같이 기술할 수 있습니다: "businessNo": {"type": "string", "pattern": "^\\d{3}-\\d{2}-\\d{5}$"}. 이는 실제 검증 알고리즘(마지막 자리가 체크섬 역할을 하는 계산식)까지 확인하지는 않지만 — 그건 별도 로직이 필요합니다 — 하이픈이 빠진 입력이나 자릿수가 틀린 값처럼 흔한 입력 실수는 즉시 걸러냅니다. 참고로 개인을 식별하는 주민등록번호는 민감정보이므로 API 계약이나 로그에 그대로 포함하지 않는 것이 바람직합니다.
문법 검증과 어떻게 다른가
일반적인 JSON 검증은 텍스트가 문법적으로 올바른지만 확인합니다 — 괄호, 따옴표, 쉼표가 제자리에 있는지. JSON Schema는 훨씬 더 많은 것을 확인합니다: 객체에 필수 필드 email이 있는지, age 값이 문자열이 아닌 숫자인지, status가 허용된 값 목록에 포함되는지.
왜 필요한가
- 서드파티 API의 응답이 문서화된 계약과 일치하는지 확인할 때.
- 배포 전에 설정 파일을 검증해 오류를 조기에 발견할 때.
- 예상되는 데이터 구조를 즉시 자동으로 검사할 수 있는 형식으로 문서화할 때.
additionalProperties: 추가 필드를 허용할 것인가
기본적으로 JSON Schema는 properties에 명시된 필드 외에 객체에 다른 필드가 있어도 허용합니다 — required와 properties는 최소 요건만 정의할 뿐, 전체 목록을 의미하지 않습니다. 알 수 없는 필드를 금지해야 한다면 "additionalProperties": false를 명시적으로 추가해야 합니다 — 이 옵션이 없으면 스키마는 계속 "열린" 상태로 남습니다.