01
선택과 선언을 일치시키기
기본 드래프트는 2020-12입니다. $schema 선언과 선택이 다르면 실패합니다. Draft-07의 튜플은 items 배열을, 2020-12는 prefixItems를 사용하므로 선택만 바꾸어 기존 규칙을 이전할 수는 없습니다.
스키마와 실제 데이터 검사
JSON 스키마 검증기실패한 값에서 조건까지 추적
예제로 시작할 수 있습니다. 스키마만 검사는 데이터 없이 실행하고, 데이터 검증은 두 문서를 함께 확인합니다.
JSON 스키마 검증기
JSON Schema
JSON 데이터
입력과 참조는 이 브라우저에서 처리하며 검증 데이터를 전송하거나 원격 참조를 가져오지 않습니다.
수동 검증을 실행할 수 있습니다.
JSON 스키마 검증기는 정수가 필요한 곳의 문자열, 누락된 필수 키, 허용하지 않은 속성을 찾아냅니다. JSON 문법이 맞아도 API 계약에는 어긋날 수 있습니다. 응답과 규칙을 나란히 두면 어느 쪽을 수정할지 판단하기 쉽습니다.
JSON Schema 검사기에서 키가 없는 경우와 값이 null인 경우는 다릅니다. default를 적어도 데이터가 추가되지는 않으며, 검사 과정은 원본을 고치지 않습니다.
JSON 스키마 검증기를 사용하는 이유
값과 규칙을 함께 추적
JSON 스키마 검증기 보고서는 데이터 위치와 스키마 위치를 함께 제공합니다. /users/0/age의 타입 오류는 해당 값을 가리키지만 required 오류는 부모 객체를 가리킬 수 있습니다. 이때 매개변수에서 빠진 키를 확인하세요.
공통 정의를 파일로 유지
여러 정의를 루트에 매번 복사하지 않아도 됩니다. 가져온 참조 파일은 절대 $id로 등록하고 상대 참조는 기준 URI로 해석합니다. 파일명은 화면 표시용이며 참조 대상을 추측하는 데 쓰지 않습니다.
실행 전 조건 맞추기
02
데이터보다 스키마를 먼저 확인
스키마만 검사는 루트와 가져온 모든 참조를 파싱하고 메타스키마 검사와 컴파일을 수행합니다. 데이터 입력은 읽지 않습니다. 참조마다 # 없는 고유한 절대 $id가 필요하며 누락된 참조는 오류가 됩니다.
03
수정 후 다시 실행
Ctrl/Cmd+Enter로 수동 실행합니다. 입력, 옵션, 참조가 바뀌면 이전 작업이 취소되고 내보내기가 잠깁니다. 예제 교체, 초기화, 참조 삭제는 미리보기 후 적용하며 한 번 되돌리면 이전 입력과 보고서가 복구됩니다.
검사 방식 살펴보기
세 드래프트를 구분해 실행
JSON 스키마 검증기는 Ajv로 draft-07, 2019-09, 2020-12를 처리합니다. 조건과 조합 규칙은 선택한 버전을 따릅니다. 알 수 없는 키워드는 컴파일 오류로 처리하여 조건이 누락된 채 통과하는 일을 막습니다.
형식 검사는 선택 사항
JSON 유효성 검사에서 format은 기본적으로 꺼져 있습니다. 켜면 ajv-formats의 email, date-time, URI, UUID 등을 검사하며 알 수 없는 형식은 거부합니다. 별도 규칙인 pattern은 이 옵션과 관계없이 평가합니다.
스키마 문제와 데이터 위반 구분
JSON Schema 검증기는 문법 오류, 메타스키마 오류, 참조 해석 실패와 실제 데이터 위반을 구분합니다. 완료된 보고서만 복사할 수 있습니다. 화면 안내는 한국어이며 엔진의 기술 설명은 영어 원문으로 보존합니다.
경로와 매개변수 함께 보기
가능한 곳에서 일찍 검사를 종료하지만 조합 분기는 여러 오류를 낼 수 있습니다. instancePath, schemaPath, keyword와 매개변수를 함께 보세요. 목록은 50개씩 표시하고 JSON 다운로드에는 허용된 전체 보고서가 들어갑니다.
판정에 적용되는 제한
- 참조 주소를 다운로드하지 않음
- 내부 참조와 직접 가져온 파일만 해석합니다. HTTP 요청은 하지 않습니다. 참조 파일의 루트에는 # 없는 절대 $id가 필요하고 중복 ID는 실패합니다. 파일명이 맞아도 ID를 대신할 수는 없습니다.
- 자동으로 값을 수정하지 않음
- 타입 변환, default 삽입, 추가 속성 삭제를 하지 않습니다. 모든 문서에서 JSON5, 주석, 끝 쉼표, 중복 키를 거부합니다. 특히 중복 키가 덮어써진 뒤 잘못된 증거로 검사를 진행하지 않습니다.
- 사용자 확장은 지원하지 않음
- 표시된 세 드래프트만 지원합니다. 사용자 메타스키마, $vocabulary, $async, $data와 알 수 없는 키워드는 지원하지 않습니다. OpenAPI 문서 전체 대신 호환되는 스키마 부분을 제공해야 합니다. Ajv strictSchema는 if 없는 then처럼 무시되는 규칙도 거부할 수 있습니다. properties, patternProperties, dependencies 맵의 정확한 __proto__ 키는 엔진 누락을 막기 위해 지원하지 않으며 실제 데이터의 같은 키는 허용합니다.
- 임의 정밀도 계산은 아님
- 유한하지 않은 수, 안전 범위를 벗어난 수학적 정수, Number 왕복 변환으로 십진 값이 달라지는 토큰은 거부합니다. 1.0과 1e0은 허용합니다. 일반 소수도 IEEE 754를 쓰므로 multipleOf에서 부동소수점 경계가 드러날 수 있습니다.
- 문서와 실행 예산
- 문서당 500,000자, 50,000노드, 깊이 40까지입니다. 전체 1,000,000자와 참조 파일 10개가 한도입니다. 작업은 5초 후 종료되며 시간 초과는 미완료를 뜻합니다. 유효 또는 무효라는 결론이 아닙니다.
- 모든 위반을 나열하지 않음
- allErrors는 꺼져 있습니다. 보고된 문제를 수정한 뒤 다시 실행하세요. 보고서는 오류 1,000개 및 500,000자까지이며 초과하면 전체 생성이 실패합니다. 한 예제가 통과했다고 미래의 모든 데이터가 올바르다는 뜻은 아닙니다.
JSON 스키마 검증기 질문과 답변
숫자와 불리언에도 enum을 적용할 수 있나요?
네. Ajv는 enum을 문자열에만 한정하지 않습니다. 정수 99는 enum: [1,2,3]에 없으므로 실패하며 불리언도 지정된 값과 비교합니다. type 규칙과 enum 규칙은 별개로 적용됩니다.
minItems와 maxItems로 배열 길이를 검사하나요?
네. minItems와 maxItems는 배열의 최소·최대 길이를 검사하고 uniqueItems는 중복을 제한합니다. 단, 실제 데이터가 배열이어야 하므로 다른 타입도 거부하려면 type: array를 함께 지정하세요.
oneOf와 anyOf 같은 조합 규칙을 지원하나요?
지원합니다. anyOf는 하나 이상, oneOf는 정확히 하나의 분기를 만족해야 합니다. allOf는 모든 분기를 요구합니다. oneOf의 조건이 겹치면 두 분기를 만족해도 실패할 수 있습니다.
email 같은 format은 언제 검사하나요?
형식 검사 옵션을 켰을 때 지원되는 ajv-formats 검사를 수행합니다. 기본값에서는 format을 주석처럼 취급합니다. 알 수 없는 형식은 켠 상태에서 컴파일 오류가 되며 pattern에는 영향이 없습니다.
instancePath가 비어 있으면 어느 위치인가요?
빈 문자열은 루트 값을 뜻합니다. 화면에는 읽기 쉬운 루트 표시를 쓰지만 JSON 보고서에는 빈 문자열을 유지합니다. 슬래시 하나는 빈 이름의 키를 뜻하므로 루트와 바꾸어 해석하면 안 됩니다.
함께 확인할 스키마 사례가 있나요?
다른 실패 사례도 검사
JSON 스키마 검증기에서 통과와 실패 예제를 비교하세요. 보고서와 함께 드래프트 및 format 설정을 기록하면 환경별 결과 차이를 추적하기 쉽습니다.