JSON 스키마 검증: 오류를 경로와 이유로 확인
스키마와 JSON 데이터를 붙여넣으면 JSON 스키마 검증 결과가 바로 나와요. 일치하지 않으면 실패한 값까지의 경로와 알아보기 쉬운 이유가 오류마다 $.users[0].email처럼 표시돼요. draft-07, 2019-09, 2020-12를 지원하고, 두 입력란의 내용은 내 기기 밖으로 나가지 않아요.
스키마로 JSON을 검사하는 순서
- JSON 스키마 입력란에 스키마를 붙여넣으세요(입력란에는 “여기에 JSON 스키마를 붙여넣으세요...”라고 적혀 있어요).
- JSON 데이터 입력란에 검사할 데이터를 붙여넣으세요.
- 결과를 확인하세요. 붙여넣을 때, 또는 입력을 멈추고 약 300밀리초 뒤에 갱신되니 누를 버튼이 없어요.
- 초록색 유효함과 “JSON 데이터가 스키마와 일치해요.”가 보이면 통과예요. 빨간색 “유효하지 않음: 오류 3개”가 보이면 실패한 곳이 하나씩 목록에 나와요.
- 데이터(또는 스키마)를 고치면 편집하는 대로 결과가 바뀌어요.
두 입력란이 채워지기 전에는 결과에 “스키마와 JSON 데이터를 붙여넣으면 검사해요.”라고 나와요. 한쪽 입력란에 JSON이 아닌 텍스트가 있으면 빨간 올바르지 않은 JSON 상자에 이유와 “X행, Y열”이 표시되고, 결과가 어느 입력란을 고쳐야 하는지 알려줘요. 먼저 지저분한 문서를 정리하고 싶다면 “JSON 포맷터”가 깨진 JSON에 대해 같은 행과 열을 보여줘요.
오류 읽는 법: 경로와 이유
오류는 경로와 이유 두 부분으로 이뤄져요. 경로는 데이터의 루트인 $에서 시작해서 속성 이름은 점으로, 배열 위치는 0부터 세어 대괄호로 이어가요. 예를 들어 스키마가 id는 1 이상의 정수, email은 email 형식, tags는 중복 없음으로 정했고 데이터가 {"id":"7","email":"ana@","tags":["a","a"]}라면 결과는 “유효하지 않음: 오류 3개”예요.
$.id: 필요한 형식: 정수, 현재 형식: 문자열$.email: 다음 형식과 일치해야 해요: “email”$.tags: 항목 [0], [1]: 서로 같지만 모든 항목은 달라야 해요.
첫 번째 오류만이 아니라 모든 오류가 목록에 나와서 문서 전체를 한 번에 고칠 수 있어요. 오류가 100개를 넘으면 목록 끝에 “오류 250개가 더 있지만 표시하지 않았어요” 같은 줄이 붙고, 제목의 개수는 정확하게 유지돼요. 필수 속성(required)이 없으면 오류는 그 속성을 가져야 할 객체의 경로, 예를 들어 $.users[0]에 표시돼요. not, contains, propertyNames, dependentRequired, if/then/else 같은 흔치 않은 키워드에도 각각 알기 쉬운 이유가 있어요.
엄격 모드: additionalproperties false
기본적으로 스키마는 추가 속성을 허용해요. 스키마에 나오지 않는 nick 필드가 데이터에 있어도 그냥 통과해요. 엄격 모드(“스키마에 없는 속성이 데이터에 있으면 실패로 처리해요.”)를 켜면 오타와 남은 속성을 찾아낼 수 있어요. 앞의 스키마와 데이터 {"id":1,"email":"ana@example.com","nick":"x"}로 보면, 모드를 끄면 “유효함”이고 켜면 $에서 “유효하지 않음: 오류 1개”(예상하지 못한 속성이에요: “nick”)가 나와요.
스위치 뒤에서는 루트 스키마와, 객체를 설명하는 속성 또는 항목 스키마마다 unevaluatedProperties: false가 추가되고, $ref를 넘어서도 동작해요. 입력란의 텍스트는 절대 바뀌지 않아요.
- 이미
additionalProperties나unevaluatedProperties를 설정한 스키마는 그 설정을 유지해요. properties없이 자유롭게 쓴{"type":"object"}는 열린 채로 남아요.allOf,anyOf,oneOf의 각 분기와$defs의 항목은 스스로 잠기지 않아서, 나란한 분기가 각자 속성을 선언할 수 있어요.
JSON 스키마 버전과 $ref, 형식
스키마의 "$schema" 줄을 읽고 거기에 맞는 규칙으로 데이터를 검사해요. http://json-schema.org/draft-07/schema#는 draft-07, https://json-schema.org/draft/2019-09/schema는 2019-09, https://json-schema.org/draft/2020-12/schema는 2020-12로 처리해요. "$schema"가 없으면 2020-12이고, items에 배열을 쓰는 옛 문법이면 2019-09예요. draft-04, draft-06이나 다른 주소는 지원하지 않으며, 결과에 스키마가 선언한 주소가 표시돼요. 버전마다 키워드가 바뀌었기 때문이에요. prefixItems는 2020-12의 것이고, definitions는 2019-09에서 $defs가 됐어요. 참조 경로는 #/$defs/name과 #/definitions/name 두 가지 모두 쓸 수 있어요.
$ref는 같은 스키마 안에서만 따라가요. 아무것도 다운로드하지 않으므로https://example.com/address.json같은 외부 참조는 스키마가 정의하지 않은 참조로 보고돼요. 그 스키마를 내$defs에 붙여넣고$ref가 거기를 가리키게 하세요.format은 무시하지 않고 검사해요. email, date, date-time, uri, uuid 같은 흔한 형식은 맞지 않으면 “다음 형식과 일치해야 해요”로 실패해요.- 스키마가 깨져 있으면 “스키마 자체가 올바르지 않아요”와 함께 스키마 안의 위치를 가리키는 문제와 경로가 나와요(예:
"type": "strng"). 스키마를 고치기 전까지 데이터는 검사하지 않아요. 올바른 정규식이 아닌 패턴이 있으면 “스키마를 사용할 수 없었어요”라고 나와요.
제한 사항과 개인정보
- 입력란마다 최대 5,000,000자까지 넣을 수 있어요. 넘으면 결과가 더 작은 부분을 붙여넣으라고 안내해요.
- 목록에는 처음 100개의 오류가 표시되고, 전체 개수는 항상 세어요.
- JSON만 지원해요. YAML이나 OpenAPI 파일 전체는 먼저 변환해야 해요. 이 도구는 검증만 하고, 데이터로 스키마를 만들거나 데이터를 대신 고치지는 않아요.
- 숫자는
JSON.parse와 같은 방식으로 읽어서, 9,007,199,254,740,991보다 큰 정수는 검사 전에 정밀도를 잃어요. - 스키마와 데이터는 내 브라우저 안에서 검사해요. 업로드하거나 저장하지 않아요.
자주 묻는 질문
JSON 스키마 검증을 브라우저에서 하려면 어떻게 하나요?
“JSON 스키마” 입력란에 스키마를, “JSON 데이터” 입력란에 검사할 데이터를 붙여넣으세요. 결과는 붙여넣는 즉시, 또는 입력을 멈추고 약 300밀리초 뒤에 나타나요. 초록색 “유효함”은 데이터가 일치한다는 뜻이고, 빨간색 “유효하지 않음”은 각 오류를 경로와 이유와 함께 보여줘요. 누를 버튼은 없어요.
어떤 JSON Schema 버전을 지원하나요? draft-07, 2019-09, 2020-12 중에서요.
세 가지 모두 지원해요. 버전은 스키마의 “$schema” 줄로 정해져요. “$schema”가 없는 스키마는 2020-12로, items에 배열을 쓰는 옛 문법이면 2019-09로 검사해요. draft-04, draft-06이나 다른 $schema 주소를 선언한 스키마는 지원하지 않는다고 알려줘요.
$.users[0].email 같은 경로는 무슨 뜻인가요?
실패한 값의 위치예요. $는 JSON 데이터의 루트, .users는 users 속성, [0]은 그 배열의 첫 번째 항목(세기는 0부터), .email은 그 안의 속성이에요. $.users[2].address.zip 같은 경로도 똑같이 한 단계씩 값까지 이어져요.
필수 속성이 없다는 오류가 왜 부모 객체에 표시되나요?
없는 속성은 가리킬 대상이 없기 때문이에요. 오류는 그 속성을 가져야 할 객체의 경로, 예를 들어 $.users[0]에 “필수 속성이 없어요: “email””라는 이유와 함께 표시돼요. 그 객체에 속성을 추가하면 오류가 사라져요.
스키마가 추가 속성을 거부하게 하려면 어떻게 하나요(additionalproperties false)?
“엄격 모드”를 켜세요. 루트 스키마와 객체를 설명하는 속성 또는 항목 스키마마다 unevaluatedProperties: false가 추가돼서, 스키마에 없는 속성은 “예상하지 못한 속성이에요”로 실패해요. 이미 additionalProperties나 unevaluatedProperties를 설정한 스키마는 그 설정을 유지해요.
email, date-time, uri, uuid 같은 형식도 검사하나요?
네. “format” 키워드를 검사하기 때문에 ana@ 같은 주소는 “format”: “email”인 문자열에서 실패하고 “다음 형식과 일치해야 해요: “email””가 표시돼요. email, date, date-time, time, uri, uuid, ipv4, ipv6, hostname 등 흔한 형식을 지원해요.
$ref로 다른 파일이나 URL을 따라갈 수 있나요?
같은 스키마 안에서만 가능해요. 예를 들어 #/$defs/name이나 #/definitions/name이에요. 아무것도 다운로드하지 않기 때문에 https://example.com/address.json 같은 참조는 스키마가 정의하지 않은 참조로 보고돼요. 참조하는 스키마를 내 $defs에 복사하고 $ref가 거기를 가리키게 하세요.
“스키마 자체가 올바르지 않아요”는 무슨 뜻인가요?
스키마가 JSON Schema 규칙을 어겼다는 뜻이에요. 예를 들어 “type”: “strng”이거나 “minimum”이 문자열로 적혀 있는 경우예요. 결과에 스키마 안의 위치를 가리키는 경로와 함께 문제가 나열돼요. 스키마를 고치기 전까지 데이터는 검사하지 않아요.
JSON Schema validator online처럼 스키마나 데이터가 어딘가로 업로드되나요?
아니요. 스키마와 데이터는 모두 브라우저 안에서 검사해요. 업로드하거나 저장하지 않고, 계정도 필요 없어요.
