JSON Schema Validator

JSON Schema란 무엇이며 왜 중요한가?

JSON(JavaScript Object Notation)은 웹 API, 설정 파일, 데이터 교환의 공통 언어입니다. 하지만 원시 JSON에는 내장 타입 시스템이 없습니다 — 하나의 필드가 어느 날은 문자열이고 다음 날은 숫자가 될 수 있으며, 불일치를 발견하는 유일한 방법은 런타임 오류나 미묘한 데이터 버그입니다. JSON Schema가 이 공백을 채웁니다: JSON 문서의 예상 구조와 제약을 설명하기 위한 선언적 어휘로, 런타임에 실제 데이터에 대해 검증됩니다.

팀들은 API 요청 페이로드를 처리 전에 검증하고, 시작 시 로드되는 설정 파일의 형태를 강제하고, 단일 진실 소스에서 문서와 UI 폼을 자동 생성하고, 마이크로서비스 전반에 걸쳐 계약 일관성을 유지하기 위해 JSON Schema를 사용합니다. OpenAPI — REST API 문서의 표준 — 은 JSON Schema 위에 직접 구축되어, 웹에서 가장 널리 배포된 데이터 검증 표준이 되었습니다.

JSON Schema 초안 버전: Draft-07, Draft 2019-09, Draft 2020-12

JSON Schema는 여러 사양 초안을 거쳐왔습니다. 2018년에 출시된 Draft-07은 모든 주요 유효성 검사기 라이브러리에서 가장 널리 지원되며 OpenAPI 3.0에서 사용하는 방언입니다. 강력한 if/then/else 조건부 검증 키워드, readOnly/writeOnly 속성 주석, 콘텐츠 인코딩 키워드를 도입했습니다. 오늘 스키마를 작성하고 최신 기능이 필요하지 않다면, Draft-07이 최대 생태계 호환성을 위한 가장 안전한 선택입니다.

Draft 2020-12는 현재의 안정적인 사양으로 여러 중요한 변경 사항을 도입합니다: 튜플 검증을 위한 items 키워드가 prefixItems로 대체되었고, 동적 참조는 $recursiveRef 대신 $dynamicRef를 사용하며, 새로운 unevaluatedProperties와 unevaluatedItems 키워드가 추가 콘텐츠에 대한 더 정밀한 제어를 제공합니다.

핵심 JSON Schema 키워드 설명

type 키워드는 데이터 타입을 강제합니다: string, number, integer, boolean, array, object, 또는 null. required는 객체에 존재해야 하는 속성을 나열합니다. properties는 각 속성 이름을 자체 서브 스키마에 매핑합니다. pattern은 문자열 값에 정규 표현식을 적용합니다. minimum, maximum, minLength, maxLength는 숫자 및 문자열 범위를 제약합니다. enum은 값을 허용된 값의 고정 집합으로 제한하고, const는 단일 값으로 제한합니다.

컴포지션 키워드는 단순한 빌딩 블록으로 복잡한 규칙을 구성할 수 있게 해줍니다: allOf는 논리 AND, anyOf는 OR, oneOf는 XOR처럼 동작합니다. not 키워드는 스키마를 반전시킵니다. if/then/else 키워드는 조건부 검증을 가능하게 합니다. 함께 사용하면 커스텀 명령형 코드 없이 거의 모든 검증 규칙을 표현할 수 있습니다.

운영 환경에서의 JSON Schema: API 계약과 CI 파이프라인

운영 시스템에서 JSON Schema 검증은 Ajv(JavaScript/Node.js), jsonschema(Python), 또는 Newtonsoft.Json(C#) 같은 라이브러리를 사용하여 서버 측 또는 CI 파이프라인에서 실행됩니다. 스키마는 애플리케이션 코드와 함께 버전 관리에 커밋되어 계약 변경이 다른 변경처럼 검토되고 추적됩니다. 필수 필드 제거나 타입 축소 같은 파괴적 변경은 운영 환경에 도달하기 전에 코드 리뷰에서 발견됩니다.

이 브라우저 기반 도구는 커밋하기 전에 스키마를 반복적으로 설계하고 디버그하는 데 이상적입니다. 데이터를 붙여넣고, 스키마를 작성하고, 검증을 클릭하고, 상세한 오류 메시지를 읽고 개선하세요 — 서버 없이, npm install 없이, 왕복 없이. 유효성 검사기는 각 검증 실행 시 JSON을 보기 좋게 출력하여 편리한 JSON 포매터와 스키마 테스터 조합이 됩니다.

실용 예제: API 응답 검증

API가 사용자 객체를 반환한다고 가정해보겠습니다. 이를 검증하는 JSON Schema는 정수 id, 비어있지 않은 문자열 name, 이메일 패턴과 일치하는 문자열 email, 그리고 'admin', 'editor', 'viewer' enum에서 선택적 문자열 role을 요구할 수 있습니다. additionalProperties를 false로 설정하면 API가 다운스트림 소비자가 의도치 않게 의존할 수 있는 문서화되지 않은 필드를 조용히 반환하는 것을 방지합니다.

if/then/else 기능은 조건부 규칙을 가능하게 합니다 — 예를 들어, role이 'admin'이면 permissions 배열이 필요하고, 그렇지 않으면 금지됩니다. 이러한 컴포지션 규칙은 속성 정의를 복제하지 않고 단일 스키마가 객체의 여러 유효한 형태를 커버할 수 있게 합니다.

UtiloKit과 다른 JSON Schema 유효성 검사기 비교

대부분의 온라인 JSON Schema 유효성 검사기 도구는 두 가지 범주로 나뉩니다: 시각적 스키마 빌더와 서버 측 API 유효성 검사기. jsonschema.net은 스키마를 구성하기 위해 포인트 앤 클릭 UI를 통해야 합니다 — 스키마 구조를 배우는 초보자에게 유용하지만, 필요한 키워드를 이미 알고 빠르게 테스트하려는 개발자에게는 느립니다.

Microsoft의 Newtonsoft.Json 라이브러리 위에 구축된 jsonschemavalidator.net은 JavaScript 개발자에게 낯선 .NET 속성 경로와 오류 코드를 사용하여 오류를 보고합니다. Stoplight와 SwaggerHub 같은 도구는 완전한 OpenAPI 문서의 일부로 스키마를 검증하며 프로젝트 설정과 계정이 필요합니다.

UtiloKit의 유효성 검사기는 대부분의 Node.js, Express, Fastify 애플리케이션을 구동하는 것과 동일한 Ajv 엔진에서 실행됩니다. 오류 메시지, JSON 포인터 경로, 키워드 동작이 운영 환경과 정확히 일치합니다 — 계정, 업로드, 파일 크기 제한, 일일 사용량 제한 없이 브라우저에서 무료로 실행됩니다.