JSON Schema 이해하기: 프로처럼 데이터 검증하기

API가 42(숫자) 대신 "42"(문자열)을 반환해서 하위 처리가 모두 망가진 적이 있나요? 아니면 누군가 필수 필드 없이 요청을 보내서 유용한 오류 대신 앱이 크래시한 적은요? JSON Schema는 바로 이런 문제를 방지하기 위해 존재합니다.

JSON 데이터의 청사진이라고 생각하면 됩니다 — 데이터가 어떤 형태여야 하는지 설명하고, 일치하지 않는 것을 잡아냅니다.

JSON Schema의 모습

JSON Schema 자체가 JSON으로 작성됩니다(꽤 메타적이죠?). 사용자 객체를 위한 간단한 스키마 예시입니다:

이것은 "필수 name(비어있지 않은 문자열)과 email(유효한 이메일 형식), 그리고 선택적 age(0에서 150 사이의 정수)를 가진 객체를 기대한다"는 뜻입니다. 누군가 {"name": "", "email": "not-an-email"}을 보내면, 검증기가 두 가지 문제를 모두 잡아냅니다.

스키마를 단계별로 구축하기

타입부터 시작하세요. 모든 스키마는 "type"으로 시작합니다: object, array, string, number, integer, boolean, null.

제약 조건을 추가하세요. 문자열: minLength, maxLength, pattern(정규식). 숫자: minimum, maximum, multipleOf. 배열: minItems, maxItems, uniqueItems. 공식 JSON Schema 가이드에 전체 목록이 있습니다.

필수 필드를 표시하세요. 객체 수준에서 "required" 배열을 사용합니다. 반드시 있어야 하는 필드만 나열하세요 — 정말 의도한 것이 아니라면 모든 것을 필수로 만들지 마세요.

중첩 객체를 정의하세요. "properties" 안에 스키마 정의를 중첩하면 됩니다. 주소가 포함된 사용자 예시입니다:

우편번호의 pattern이요? 5자리 미국 우편번호만 허용되도록 합니다. 이런 실용적인 검증이 쓰레기 데이터가 데이터베이스에 들어가는 것을 방지합니다.

왜 실제로 사용해야 하는가

API 검증: API 경계에서 들어오는 요청 본문을 검증하세요. 잘못된 데이터는 비즈니스 로직에 닿기 전에 명확한 오류 메시지와 함께 거부됩니다. 대부분의 프레임워크가 이를 지원합니다 — JavaScript의 Ajv는 매우 빠릅니다.

설정 검증: 앱 시작 시 설정 파일을 검증하세요. 5분 후 알 수 없는 null 포인터 예외 대신 "설정에 database.host 필드가 없습니다"라는 명확한 메시지로 빠르게 실패시키세요.

문서화: JSON Schema는 살아있는 문서 역할도 합니다. Swagger UI 같은 도구가 스키마에서 직접 API 문서를 생성합니다.

코드 생성: 스키마에서 TypeScript 인터페이스, Go 구조체, Python 데이터클래스를 생성할 수 있습니다. 한 번 작성하고 어디서나 사용하세요.

테스팅: 테스트 스위트에서 API 응답을 검증하여 회귀를 자동으로 감지합니다.

30초 만에 시작하기

가장 빠른 방법은? 기존 JSON 데이터에서 스키마를 생성하는 것입니다. 샘플 JSON 응답을 저희 JSON Schema Generator에 붙여넣으세요 — 데이터를 분석하고 다듬을 수 있는 스키마를 생성합니다. 그런 다음 JSON Schema Validator를 사용해 실제 데이터로 테스트하세요.

프로그래밍 방식으로도 검증할 수 있습니다. Ajv를 사용한 간단한 Node.js 예시입니다:

Python의 경우 jsonschema 라이브러리를 확인하세요. Java에는 everit-json-schema가 있습니다. 거의 모든 언어에 탄탄한 지원이 있습니다 — 전체 구현 목록을 확인하세요.

알아야 할 고급 스키마 기능

기본을 마스터했다면, JSON Schema에는 복잡한 검증을 가능하게 하는 강력한 기능들이 있습니다.

oneOf, anyOf, allOf — 스키마 결합:

때때로 필드가 여러 타입 중 하나일 수 있습니다. 예를 들어, API가 문자열 ID와 숫자 ID 모두 허용할 수 있습니다:

이 스키마는 {"id": "PRD-1234"}와 {"id": 42} 모두 허용하지만, {"id": -1}이나 {"id": "invalid"}는 거부합니다.

$ref — 재사용 가능한 스키마 정의:

스키마가 커지면 같은 정의를 반복하고 싶지 않을 것입니다. $ref 키워드를 사용하면 공유 정의를 참조할 수 있습니다:

이제 billing_address와 shipping_address 모두 정확히 같은 검증 규칙을 사용합니다. address 정의를 한 번 변경하면 두 필드 모두 업데이트됩니다. 대규모 스키마를 유지 관리 가능하게 유지하는 데 필수적입니다.

additionalProperties — 객체 잠그기:

기본적으로 JSON Schema는 properties에 나열되지 않은 추가 속성을 허용합니다. 이것은 종종 원하지 않는 것입니다 — 예상치 못한 필드는 클라이언트 버그나 버전 불일치를 나타낼 수 있습니다. "additionalProperties": false를 설정하여 알 수 없는 필드를 거부하세요:

이 스키마에서는 {"name": "Alice", "email": "[email protected]", "admin": true}가 admin이 정의된 속성이 아니기 때문에 거부됩니다.

흔한 JSON Schema 실수

경험 많은 개발자도 스키마를 작성할 때 이런 실수를 합니다:

1. required가 속성 수준이 아닌 객체 수준이라는 것을 잊기. 이것은 잘못된 방법입니다:

올바른 방법은 이것입니다:

2. "type": "integer"를 의미하면서 "type": "number"를 사용하기. number 타입은 3.14 같은 소수를 허용하고, integer는 정수만 허용합니다. 필드가 카운트나 ID라면 integer를 사용하세요.

3. 일반적인 패턴에 format을 지정하지 않기. JSON Schema에는 email, uri, date-time, ipv4, ipv6, uuid 등을 위한 내장 포맷 검증기가 있습니다. 복잡한 정규식 패턴을 작성하는 대신 이것들을 사용하세요.

4. 모든 것을 필수로 만들기. 정말 있어야 하는 필드만 필수로 표시하세요. 스키마를 과도하게 제약하면 API 진화가 어려워집니다 — 새로운 선택적 필드를 추가하는 것은 비파괴적 변경이지만, 모든 것이 필수이면 그 유연성을 잃게 됩니다.

실전 예시: E-Commerce 제품 스키마

제품 API에 사용할 수 있는 실용적인 스키마를 살펴봅시다:

이 스키마는 모든 제품에 이름(1-200자), 양수 가격, 고정 목록의 카테고리가 있도록 강제합니다. 태그는 선택 사항이지만 최대 10개의 고유한 문자열이어야 합니다. enum 키워드는 특정 값만 허용해야 하는 필드에 매우 유용합니다.

JSON Schema 버전: 어떤 Draft를 사용할까

JSON Schema는 여러 드래프트를 거쳤으며, 각각 IETF Internet-Draft로 게시되었습니다. 이는 초보자에게 혼란스러울 수 있습니다. 빠른 개요입니다:

새 프로젝트에는 2020-12(최신)을 사용하세요. 기존 코드베이스로 작업 중이라면, 검증기가 어떤 드래프트를 지원하는지 확인하세요. Ajv 같은 대부분의 최신 검증기는 Draft 7 이상을 지원합니다.

JSON Schema를 워크플로에 통합하기

Express.js API에 JSON Schema 검증을 추가하는 실용적인 접근 방법입니다:

이 패턴은 명확한 오류 메시지와 함께 자동 요청 검증을 제공합니다. allErrors: true 옵션은 첫 번째 오류만이 아니라 모든 검증 오류가 한 번에 보고되도록 합니다.

직접 해보세요

프로젝트에 스키마 검증을 추가할 준비가 되셨나요? 이 도구들로 시작하세요:

• JSON Schema Generator — 아무 JSON 데이터나 붙여넣으면 자동으로 스키마가 생성됩니다. 샘플 API 응답에서 스키마를 부트스트랩하는 데 완벽합니다.
• JSON Schema Validator — 실제 데이터에 대해 스키마를 테스트하여 잡아야 할 것을 잡고 허용해야 할 것을 허용하는지 확인하세요.
• JSON Validator — 스키마 검증을 걱정하기 전에 JSON이 구문적으로 유효한지 빠르게 확인하세요.

JSON Schema는 처음에는 추가 작업처럼 보일 수 있지만, 비즈니스 로직 깊숙한 곳이 아니라 시스템의 경계에서 버그를 잡아줌으로써 여러 배로 보상해 줍니다.