JSON Schema 실전 예제: 객체, 배열, enum, 조건부 규칙

JSON Schema는 JSON 데이터의 구조와 제약을 설명합니다. API 계약, 설정 파일, 가져오기 파이프라인의 규칙을 실행 가능한 형태로 만들 수 있습니다.

객체와 필수 필드

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "status"],
  "properties": {
    "id": { "type": "string", "minLength": 1 },
    "status": { "enum": ["pending", "active", "disabled"] }
  },
  "additionalProperties": false
}

additionalProperties: false는 오타와 예상하지 못한 키를 찾는 데 유용합니다. 다만 새 필드를 허용해야 하는 공개 API에서는 호환성을 고려해야 합니다.

중첩 객체 검증

{
  "type": "object",
  "required": ["name", "address"],
  "properties": {
    "name": { "type": "string" },
    "address": {
      "type": "object",
      "required": ["country", "postalCode"],
      "properties": {
        "country": { "type": "string", "minLength": 2 },
        "postalCode": { "type": "string", "pattern": "^[A-Za-z0-9 -]+$" }
      },
      "additionalProperties": false
    }
  }
}

정규식은 문자열 모양만 확인합니다. 실제 주소, 재고, 권한 같은 사실은 애플리케이션에서 검증해야 합니다.

배열과 항목 제한

{
  "type": "array",
  "minItems": 1,
  "uniqueItems": true,
  "items": {
    "type": "object",
    "required": ["sku", "quantity"],
    "properties": {
      "sku": { "type": "string", "minLength": 1 },
      "quantity": { "type": "integer", "minimum": 1 }
    }
  }
}

uniqueItems는 전체 JSON 값을 비교합니다. 특정 필드의 고유성은 보통 애플리케이션이나 데이터베이스에서 보장합니다.

$defs로 정의 재사용

{
  "$defs": {
    "money": {
      "type": "object",
      "required": ["amount", "currency"],
      "properties": {
        "amount": { "type": "number", "minimum": 0 },
        "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
      }
    }
  },
  "type": "object",
  "properties": {
    "subtotal": { "$ref": "#/$defs/money" },
    "total": { "$ref": "#/$defs/money" }
  }
}

정확한 금액 계산이 필요하면 검증된 십진 문자열이나 최소 통화 단위 정수를 고려하세요.

조건부 필수 규칙

{
  "type": "object",
  "required": ["deliveryMethod"],
  "properties": {
    "deliveryMethod": { "enum": ["pickup", "shipping"] },
    "shippingAddress": { "type": "string" },
    "pickupLocationId": { "type": "string" }
  },
  "allOf": [
    {
      "if": { "properties": { "deliveryMethod": { "const": "shipping" } } },
      "then": { "required": ["shippingAddress"] },
      "else": { "required": ["pickupLocationId"] }
    }
  ]
}

Schema는 읽기 쉽게 유지하세요. 전체 워크플로, 권한, 재고 로직은 애플리케이션 코드가 담당해야 합니다.

권장 작업 순서

1. 정상 및 비정상 샘플을 준비합니다.

1. JSON Schema 생성기로 기본 구조를 만듭니다.

1. 실제 계약에 맞춰 required와 경계 규칙을 추가합니다.

1. 누락, 잘못된 타입, 추가 키, 빈 컬렉션을 테스트합니다.

1. Schema를 버전 관리하고 자동화 테스트에서 실행합니다.

키워드와 draft 동작은 JSON Schema 공식 가이드를 참고하세요. 생성 결과는 출발점이며, 최종 규칙은 실제 비즈니스 의도를 반영해야 합니다.