JSON Schema 예제: 검증에 쓰는 실전 패턴

JSON Schema 한눈에

JSON Schema는 JSON 데이터의 허용 형태와 규칙을 기술합니다. 구문 검사는 “JSON이 맞는가”, 스키마 검증은 “계약에 맞는가”를 봅니다.

예시는 Draft 2020-12 ($schema) 기준입니다. 사용하는 검증기가 지원하는 초안과 맞추세요.

JSON 기초는 What is JSON?에서 복습할 수 있습니다.

최소 object 스키마

스키마 — name(문자열), age(정수) 필수, tags 선택:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/person.min.json",
  "title": "Person",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "integer", "minimum": 0 },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["name", "age"]
}

유효 인스턴스

{ "name": "Asha", "age": 30, "tags": ["beta"] }

무효 예 (age 누락, additionalProperties: false 때문에 extra 불가)

{ "name": "Asha", "extra": true }

문자열: 길이, pattern, format

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "handle": { "type": "string", "pattern": "^[a-z0-9_]{3,20}$" },
    "contact": { "type": "string", "format": "email" },
    "createdAt": { "type": "string", "format": "date-time" }
  },
  "required": ["handle"]
}

참고: format은 코어에서 주석에 가깝고, Ajv 등은 플러그인으로 켭니다. 런타임에서 켜지 않으면 문서용으로만 취급하세요.

숫자: 범위와 배수

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "qty": { "type": "integer", "minimum": 1, "maximum": 99 },
    "price": { "type": "number", "minimum": 0, "multipleOf": 0.01 }
  },
  "required": ["qty", "price"]
}

정수는 integer, 소수는 number로 구분합니다.

enum과 const

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "role": { "type": "string", "enum": ["admin", "editor", "viewer"] },
    "version": { "const": 1 }
  },
  "required": ["role", "version"]
}

배열: items, 길이, uniqueItems

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "ids": {
      "type": "array",
      "items": { "type": "string", "pattern": "^[A-Z]{3}-[0-9]{4}$" },
      "minItems": 1,
      "maxItems": 10,
      "uniqueItems": true
    }
  },
  "required": ["ids"]
}

anyOf, oneOf, allOf

anyOf — 최소 한 가지 분기 일치(“문자열 또는 숫자”).

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "value": {
      "anyOf": [
        { "type": "string", "minLength": 1 },
        { "type": "number" }
      ]
    }
  },
  "required": ["value"]
}

oneOf — 정확히 하나(겹치는 조건 주의). allOf — 모든 부분 스키마 제약 결합.

$defs와 $ref로 재사용

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "Email": { "type": "string", "format": "email" }
  },
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "owner": { "$ref": "#/$defs/Email" },
    "billing": { "$ref": "#/$defs/Email" }
  },
  "required": ["owner"]
}

additionalProperties와 API 계약

루트에서 additionalProperties: false로 naem 같은 오타를 잡기 쉽습니다. 공개 API에서는 properties·required와 함께 쓰는 경우가 많습니다.

흔한 실수

• • $ref 프래그먼트 오타나 초안 차이로 해석 실패.

• • null은 기본 허용되지 않음. { "type": ["string", "null"] } 등으로 명시.

• • oneOf 분기가 겹치면 “여러 개 일치” 오류.

• • integer vs number 혼동.

JSON Work에서 시도

• • 스키마와 페이로드를 JSON Validator에 붙여 넣어 브라우저에서 검증.

• • 샘플 JSON에서 초안 스키마는 JSON to Schema 활용.

운영 파이프라인에서는 Ajv, jsonschema 등 라이브러리의 초안 지원을 확인하세요.