JSON Schema 검증기

JSON Schema 검증기란 무엇인가요?

// A 5-line schema that catches three real bugs
const schema = {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "email"],
  "additionalProperties": false
};

// Three bugs the schema catches:
const bad = { "id": "42", "age": 200 };
//   /id   → type: expected integer, got string
//   /email → required: missing
//   /age   → maximum: 200 > 150

// In Node:        new Ajv().compile(schema)(bad)  // false; ajv.errors has the paths
// In Python:      jsonschema.validate(bad, schema)
// In the browser: this tool — same errors, same paths, no install

주요 기능

예시

{
  "id": 42,
  "email": "alice@example.com",
  "age": 30
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "email"],
  "additionalProperties": false
}

{
  "id": "42",
  "age": 200
}

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "maximum": 150 }
  },
  "required": ["id", "email"]
}

{
  "type": "order.created",
  "data": { "orderId": "ORD-001234", "totalUsd": 49.99 }
}

{
  "oneOf": [
    {
      "properties": {
        "type": { "const": "order.created" },
        "data": {
          "type": "object",
          "properties": {
            "orderId": { "type": "string", "pattern": "^ORD-[0-9]{6}$" },
            "totalUsd": { "type": "number", "minimum": 0 }
          },
          "required": ["orderId", "totalUsd"]
        }
      },
      "required": ["type", "data"]
    },
    {
      "properties": {
        "type": { "const": "order.refunded" },
        "data": { "type": "object", "required": ["refundId"] }
      },
      "required": ["type", "data"]
    }
  ]
}

[
  { "sku": "A1", "qty": 3 },
  { "sku": "B2", "qty": 5 },
  { "sku": "A1", "qty": 3 }
]

{
  "type": "array",
  "minItems": 1,
  "uniqueItems": true,
  "items": {
    "type": "object",
    "properties": {
      "sku": { "type": "string", "pattern": "^[A-Z][0-9]+$" },
      "qty": { "type": "integer", "minimum": 1 }
    },
    "required": ["sku", "qty"]
  }
}

사용 방법

1. 1

   JSON Schema 붙여넣기

   스키마를 오른쪽 패널에 넣으세요. $schema URI가 있으면 검증기가 드래프트를 자동 감지하고, 없으면 툴바에서 Draft 2020-12, 2019-09, Draft-07 중 선택하세요.

2. 2

   JSON 데이터 붙여넣기

   검사할 JSON 문서를 왼쪽 패널에 넣으세요. 입력하는 동안 유효성 검사가 실행되며, 큰 입력(>200 KB)은 입력 반응성을 유지하기 위해 수동 Validate 버튼으로 전환됩니다.

3. 3

   오류 목록 읽기

   각 오류는 JSON Pointer 경로, 키워드, 한 줄 메시지를 포함합니다. 오류를 클릭해 데이터의 해당 위치로 이동하고, 수정하면 카운트가 실시간으로 줄어드는 것을 확인하세요.

JSON Schema 흔한 함정

{ "qty": 1.0 }   schema: { "type": "integer" }   → error: not an integer

{ "qty": 1 }     schema: { "type": "integer" }   → valid

{ "properties": { "name": { "type": "string", "required": true } } }

{ "properties": { "name": { "type": "string" } }, "required": ["name"] }

{ "properties": { "id": { "type": "integer" } } }   accepts: { "id": 1, "foo": "bar", "x": null }

{ "properties": { "id": { "type": "integer" } }, "additionalProperties": false }

{ "type": "string", "nullable": true }   in 2020-12: nullable is just an unknown keyword

{ "type": ["string", "null"] }   in 2020-12: explicitly allows null

pattern: "[A-Z]+"   accepts: "helloX"   (because X matches)

pattern: "^[A-Z]+$"   accepts only: "HELLO"

oneOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → error: matches both

anyOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → valid

주요 활용 사례

API 요청 유효성 검사

배포 전에 요청 본문과 엔드포인트 스키마를 붙여넣으세요. 테스트로 못 잡은 400 응답을 잡아냅니다 - 누락된 필수 필드, 잘못된 타입, 범위 밖 숫자.

Webhook 페이로드 검증

벤더가 보낸 페이로드를 핸들러가 거부하나요? 실제 페이로드를 사용자 스키마와 벤더가 공개한 스키마 양쪽으로 검증하세요. 두 결과의 차이가 곧 버그입니다.

설정 파일 린팅

package.json, tsconfig.json, helm values.yaml - 모든 설정 파일에는 공개 스키마가 있습니다. 스키마를 붙여넣고 설정을 붙여넣어 오타를 찾으세요. 시행착오 생략.

OpenAPI 컴포넌트 테스트

OpenAPI 3.1 문서에서 스키마 컴포넌트를 떼어 여기에 붙여넣고 샘플 페이로드를 검증하세요. 모의 서버를 띄우는 것보다 빠르고, 결정적이며, SDK도 필요 없습니다.

폼 제출 사전 점검

프론트엔드 유효성 검사를 연결하기 전에 샘플 폼 페이로드를 붙여넣으세요. 스키마가 거부할 것은 거부하고 받을 것은 받는지 확인한 뒤, 같은 스키마를 클라이언트와 서버에 배포하세요.

데이터 파이프라인 계약 점검

ETL 출력이 변형됐나요? 샘플 행과 다운스트림 스키마를 붙여넣으세요. 파이프라인이 1만 건을 재시도하기 전에 어느 프로듀서가 바뀌고 어느 키가 깨졌는지 짚어냅니다.

기술 세부사항

Draft 2020-12 준수

공개된 Draft 2020-12 스펙을 구현 - 키워드, 타입 시스템, format 어휘. Ajv 8.x와 ajv-formats 출력을 기준으로 교차 검증.

JSON Pointer 오류 경로

오류는 RFC 6901 JSON Pointer(/user/email/0)를 사용합니다. 모든 키워드 실패는 데이터 내부의 단일하고 해석 가능한 위치를 가리킵니다 - 모호함도, 문자열 검색도 없습니다.

내부 $ref 해석

단일 문서 내의 $ref 포인터(#/$defs/foo, #/properties/bar)를 해석합니다. 순환은 감지해 보고하며, 외부 HTTP $ref는 프라이버시를 위해 비활성화되어 있습니다.

모범 사례

항상 additionalProperties: false 설정

입력 계약(요청 본문, 설정 파일, 큐 메시지)에서 알 수 없는 키는 대개 버그입니다 - 오타, 우발적 필드, 공격자 탐색. 기본적으로 거부하세요.

재사용 가능한 서브 스키마는 $defs 사용

같은 형태를 두 번 인라인하면 어긋납니다. 공유 정의를 $defs로 옮기고 $ref로 참조하세요 - 단일 진실 공급원, 모든 변경이 모든 곳에 적용됩니다.

비즈니스 로직 전에 검증

JSON.parse 직후, 파싱된 구조를 건드리기 전에 스키마 유효성 검사를 실행하세요. 타입 좁히기, 기본값 채우기, 영속화는 모두 계약이 성립한다고 가정합니다 - 정말 그런지 확인하세요.

자주 묻는 질문