도구 소개
스키마 검증은 “응답이 맞아 보인다”를 필수 필드, 타입, 형식, enum, 배열 형태에 대한 반복 가능한 계약 검사로 바꿔 줍니다. 이 검증기는 많은 JavaScript 테스트 스위트가 쓰는 라이브러리인 Ajv를 사용하며, 이메일, date-time, uuid, uri 검사를 위해 ajv-formats를 함께 사용합니다. 모든 오류는 인스턴스 경로(/items/1/qty)와 이해하기 쉬운 메시지로 표시되고, 첫 번째 오류만이 아니라 전부 보고됩니다. 아직 스키마가 없다면 정상 응답을 붙여 넣어 초기 스키마를 생성한 뒤 직접 다듬으세요.
사용 방법
- 왼쪽에 스키마를, 오른쪽에 JSON 데이터를 붙여 넣거나, 샘플 주문 스키마와 일부러 깨뜨린 데이터를 불러오세요.
- 드래프트를 “Auto”(자동)로 두면 스키마의 $schema 키워드를 따르며, 2020-12나 draft-07로 강제할 수도 있습니다.
- 표시된 오류를 수정하세요. 입력하는 동안 결과가 갱신됩니다.
- 새 스키마를 만들려면 실제 응답을 데이터로 붙여 넣고 “Generate schema from data”(데이터에서 스키마 생성)를 클릭하세요.
JSON Schema 검증기 자주 묻는 질문
draft 2020-12와 draft-07 중 무엇을 써야 하나요?
사용하는 다른 도구가 지원하는 쪽을 쓰세요. OpenAPI 3.1은 2020-12에 맞춰져 있고, 오래된 검증기와 OpenAPI 3.0 도구는 draft-07에 가깝습니다. 눈에 띄는 주요 차이는 튜플 배열(2020-12의 prefixItems, draft-07의 배열 형태 items)과 $defs 대 definitions입니다.
생성된 스키마는 얼마나 믿을 만한가요?
샘플 하나에서 추론한 출발점입니다. 타입, 중첩 객체, 배열 항목 형태, 흔한 문자열 형식을 담고 있으며 샘플에 나온 모든 키를 required로 표시합니다. 어떤 필드가 선택 사항인지, 어떤 값이 enum인지, 숫자 범위가 어떤지는 알 수 없으므로 계약으로 쓰기 전에 검토하세요.
잘못된 이메일이 왜 통과되나요?
“format” 키워드는 검증기가 형식 검사를 활성화했을 때만 적용됩니다. 이 도구는 ajv-formats로 이를 활성화합니다. 테스트 프레임워크에서 활성화하지 않았다면 그쪽에도 formats 플러그인을 추가하세요. 그렇지 않으면 같은 데이터가 통과합니다.