워로디스

JSON Schema 치트시트 본문

정리/데이터직렬화형식

JSON Schema 치트시트

워로디스 2026. 5. 3. 21:11

기준: JSON Schema Draft 2020-12

1. 기본 타입

string

Schema — JSON

{
  "type": "string"
}

Schema — YAML

type: string

Valid instance

"hello"

Invalid instance

123

integer

Schema — JSON

{
  "type": "integer"
}

Schema — YAML

type: integer

Valid instance

42

Invalid instance

3.14

number

Schema — JSON

{
  "type": "number"
}

Schema — YAML

type: number

Valid instance

3.14

Valid instance

42

Invalid instance

"42"

boolean

Schema — JSON

{
  "type": "boolean"
}

Schema — YAML

type: boolean

Valid instance

true

Invalid instance

"true"

null

Schema — JSON

{
  "type": "null"
}

Schema — YAML

type: "null"

Valid instance

null

Invalid instance

"null"

array

Schema — JSON

{
  "type": "array"
}

Schema — YAML

type: array

Valid instance

["a", "b", "c"]

Invalid instance

{
  "0": "a",
  "1": "b"
}

object

Schema — JSON

{
  "type": "object"
}

Schema — YAML

type: object

Valid instance

{
  "id": 1,
  "name": "Alice"
}

Invalid instance

[
  ["id", 1],
  ["name", "Alice"]
]

2. 여러 타입 허용

string 또는 null

Schema — JSON

{
  "type": ["string", "null"]
}

Schema — YAML

type:
  - string
  - "null"

Valid instance

"nickname"

Valid instance

null

Invalid instance

123

3. 객체 필드 정의

기본 객체

Schema — JSON

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    }
  },
  "required": ["id", "name"],
  "additionalProperties": false
}

Schema — YAML

type: object
properties:
  id:
    type: integer
  name:
    type: string
required:
  - id
  - name
additionalProperties: false

Valid instance

{
  "id": 1,
  "name": "Alice"
}

Invalid instance — 필수 필드 누락

{
  "id": 1
}

Invalid instance — 추가 필드 존재

{
  "id": 1,
  "name": "Alice",
  "age": 30
}

4. properties는 필수가 아니다

Schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    }
  }
}

Valid instance

{}

Valid instance

{
  "name": "Alice"
}

Invalid instance

{
  "name": 123
}

핵심:

properties는 “있다면 이 타입이어야 한다”는 뜻이다.
필수로 만들려면 required가 필요하다.

5. 문자열 제약

길이 제한

Schema — JSON

{
  "type": "string",
  "minLength": 3,
  "maxLength": 10
}

Schema — YAML

type: string
minLength: 3
maxLength: 10

Valid instance

"hello"

Invalid instance

"hi"

정규식 패턴

Schema — JSON

{
  "type": "string",
  "pattern": "^[a-z][a-z0-9-]*$"
}

Schema — YAML

type: string
pattern: "^[a-z][a-z0-9-]*$"

Valid instance

"my-service-1"

Invalid instance

"My Service"

format

Schema — JSON

{
  "type": "string",
  "format": "email"
}

Schema — YAML

type: string
format: email

Valid instance

"user@example.com"

Invalid instance

"not-an-email"

주의:

format 검증은 validator 설정에 따라 강제되지 않을 수 있다.

6. 숫자 제약

범위 제한

Schema — JSON

{
  "type": "integer",
  "minimum": 1,
  "maximum": 65535
}

Schema — YAML

type: integer
minimum: 1
maximum: 65535

Valid instance

8080

Invalid instance

70000

초과 / 미만

Schema — JSON

{
  "type": "number",
  "exclusiveMinimum": 0,
  "exclusiveMaximum": 100
}

Schema — YAML

type: number
exclusiveMinimum: 0
exclusiveMaximum: 100

Valid instance

50

Invalid instance

0

배수

Schema — JSON

{
  "type": "integer",
  "multipleOf": 5
}

Schema — YAML

type: integer
multipleOf: 5

Valid instance

15

Invalid instance

17

7. 배열 제약

문자열 배열

Schema — JSON

{
  "type": "array",
  "items": {
    "type": "string"
  }
}

Schema — YAML

type: array
items:
  type: string

Valid instance

["api", "backend"]

Invalid instance

["api", 123]

배열 길이 제한

Schema — JSON

{
  "type": "array",
  "minItems": 1,
  "maxItems": 3
}

Schema — YAML

type: array
minItems: 1
maxItems: 3

Valid instance

["a", "b"]

Invalid instance

[]

중복 금지

Schema — JSON

{
  "type": "array",
  "uniqueItems": true
}

Schema — YAML

type: array
uniqueItems: true

Valid instance

["a", "b", "c"]

Invalid instance

["a", "b", "a"]

객체 배열

Schema — JSON

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer"
      },
      "name": {
        "type": "string"
      }
    },
    "required": ["id", "name"],
    "additionalProperties": false
  }
}

Schema — YAML

type: array
items:
  type: object
  properties:
    id:
      type: integer
    name:
      type: string
  required:
    - id
    - name
  additionalProperties: false

Valid instance

[
  {
    "id": 1,
    "name": "Alice"
  },
  {
    "id": 2,
    "name": "Bob"
  }
]

Invalid instance

[
  {
    "id": 1,
    "name": "Alice",
    "age": 30
  }
]

튜플 배열

Schema — JSON

{
  "type": "array",
  "prefixItems": [
    {
      "type": "string"
    },
    {
      "type": "integer"
    }
  ],
  "items": false
}

Schema — YAML

type: array
prefixItems:
  - type: string
  - type: integer
items: false

Valid instance

["Alice", 30]

Invalid instance — 순서 오류

[30, "Alice"]

Invalid instance — 추가 요소

["Alice", 30, true]

8. enum / const

enum

Schema — JSON

{
  "type": "string",
  "enum": ["dev", "staging", "prod"]
}

Schema — YAML

type: string
enum:
  - dev
  - staging
  - prod

Valid instance

"prod"

Invalid instance

"local"

const

Schema — JSON

{
  "const": "prod"
}

Schema — YAML

const: prod

Valid instance

"prod"

Invalid instance

"dev"

9. 추가 필드 제어

추가 필드 금지

Schema — JSON

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    }
  },
  "required": ["id"],
  "additionalProperties": false
}

Schema — YAML

type: object
properties:
  id:
    type: integer
required:
  - id
additionalProperties: false

Valid instance

{
  "id": 1
}

Invalid instance

{
  "id": 1,
  "name": "Alice"
}

추가 필드는 문자열만 허용

Schema — JSON

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    }
  },
  "additionalProperties": {
    "type": "string"
  }
}

Schema — YAML

type: object
properties:
  id:
    type: integer
additionalProperties:
  type: string

Valid instance

{
  "id": 1,
  "nickname": "alice"
}

Invalid instance

{
  "id": 1,
  "age": 30
}

10. 필드명 패턴

x-로 시작하는 확장 필드

Schema — JSON

{
  "type": "object",
  "patternProperties": {
    "^x-": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Schema — YAML

type: object
patternProperties:
  "^x-":
    type: string
additionalProperties: false

Valid instance

{
  "x-trace-id": "abc-123"
}

Invalid instance

{
  "trace-id": "abc-123"
}

모든 필드명 형식 제한

Schema — JSON

{
  "type": "object",
  "propertyNames": {
    "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
  }
}

Schema — YAML

type: object
propertyNames:
  pattern: "^[a-zA-Z_][a-zA-Z0-9_]*$"

Valid instance

{
  "user_name": "Alice"
}

Invalid instance

{
  "user-name": "Alice"
}

11. 조건부 검증

if / then / else

Schema — JSON

{
  "type": "object",
  "properties": {
    "type": {
      "enum": ["card", "bank"]
    },
    "cardNumber": {
      "type": "string"
    },
    "accountNumber": {
      "type": "string"
    }
  },
  "required": ["type"],
  "if": {
    "properties": {
      "type": {
        "const": "card"
      }
    }
  },
  "then": {
    "required": ["cardNumber"]
  },
  "else": {
    "required": ["accountNumber"]
  }
}

Schema — YAML

type: object
properties:
  type:
    enum:
      - card
      - bank
  cardNumber:
    type: string
  accountNumber:
    type: string

required:
  - type

if:
  properties:
    type:
      const: card

then:
  required:
    - cardNumber

else:
  required:
    - accountNumber

Valid instance

{
  "type": "card",
  "cardNumber": "1234"
}

Valid instance

{
  "type": "bank",
  "accountNumber": "9876"
}

Invalid instance

{
  "type": "card",
  "accountNumber": "9876"
}

12. 필드 의존성

A가 있으면 B도 필요

Schema — JSON

{
  "type": "object",
  "properties": {
    "creditCard": {
      "type": "string"
    },
    "billingAddress": {
      "type": "string"
    }
  },
  "dependentRequired": {
    "creditCard": ["billingAddress"]
  }
}

Schema — YAML

type: object
properties:
  creditCard:
    type: string
  billingAddress:
    type: string

dependentRequired:
  creditCard:
    - billingAddress

Valid instance

{
  "creditCard": "1234-5678",
  "billingAddress": "Seoul"
}

Valid instance

{
  "billingAddress": "Seoul"
}

Invalid instance

{
  "creditCard": "1234-5678"
}

13. 조합 키워드

allOf — 모두 만족

Schema

{
  "allOf": [
    {
      "type": "string"
    },
    {
      "minLength": 3
    }
  ]
}

Valid instance

"hello"

Invalid instance

"hi"

anyOf — 하나 이상 만족

Schema

{
  "anyOf": [
    {
      "type": "string"
    },
    {
      "type": "integer"
    }
  ]
}

Valid instance

"hello"

Valid instance

123

Invalid instance

true

oneOf — 정확히 하나만 만족

Schema

{
  "oneOf": [
    {
      "type": "integer"
    },
    {
      "minimum": 0
    }
  ]
}

Valid instance

-1

Invalid instance — 둘 다 만족해서 실패

1

주의:

oneOf는 “하나 이상”이 아니라 “정확히 하나”다.
둘 이상 만족해도 실패한다.

not — 만족하면 실패

Schema

{
  "not": {
    "type": "null"
  }
}

Valid instance

"hello"

Invalid instance

null

14. 재사용

$defs + $ref

Schema — JSON

{
  "$defs": {
    "UserId": {
      "type": "integer",
      "minimum": 1
    }
  },
  "type": "object",
  "properties": {
    "id": {
      "$ref": "#/$defs/UserId"
    }
  },
  "required": ["id"]
}

Schema — YAML

$defs:
  UserId:
    type: integer
    minimum: 1

type: object
properties:
  id:
    $ref: "#/$defs/UserId"
required:
  - id

Valid instance

{
  "id": 1
}

Invalid instance

{
  "id": 0
}

15. Discriminated union 패턴

Schema — JSON

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "kind": {
          "const": "email"
        },
        "email": {
          "type": "string",
          "format": "email"
        }
      },
      "required": ["kind", "email"],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "kind": {
          "const": "sms"
        },
        "phone": {
          "type": "string"
        }
      },
      "required": ["kind", "phone"],
      "additionalProperties": false
    }
  ]
}

Schema — YAML

oneOf:
  - type: object
    properties:
      kind:
        const: email
      email:
        type: string
        format: email
    required:
      - kind
      - email
    additionalProperties: false

  - type: object
    properties:
      kind:
        const: sms
      phone:
        type: string
    required:
      - kind
      - phone
    additionalProperties: false

Valid instance

{
  "kind": "email",
  "email": "user@example.com"
}

Valid instance

{
  "kind": "sms",
  "phone": "+82-10-1234-5678"
}

Invalid instance

{
  "kind": "email",
  "phone": "+82-10-1234-5678"
}

16. 완성 예제: 설정 파일

Schema — JSON

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "AppConfig",
  "type": "object",
  "properties": {
    "appName": {
      "type": "string",
      "minLength": 1
    },
    "port": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535
    },
    "debug": {
      "type": "boolean",
      "default": false
    },
    "logLevel": {
      "type": "string",
      "enum": ["debug", "info", "warn", "error"]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    }
  },
  "required": ["appName", "port"],
  "additionalProperties": false
}

Schema — YAML

$schema: "https://json-schema.org/draft/2020-12/schema"
title: AppConfig
type: object
properties:
  appName:
    type: string
    minLength: 1
  port:
    type: integer
    minimum: 1
    maximum: 65535
  debug:
    type: boolean
    default: false
  logLevel:
    type: string
    enum:
      - debug
      - info
      - warn
      - error
  tags:
    type: array
    items:
      type: string
    uniqueItems: true
required:
  - appName
  - port
additionalProperties: false

Valid JSON instance

{
  "appName": "payment-service",
  "port": 8080,
  "debug": false,
  "logLevel": "info",
  "tags": ["api", "internal"]
}

Valid YAML instance

appName: payment-service
port: 8080
debug: false
logLevel: info
tags:
  - api
  - internal

Invalid JSON instance

{
  "appName": "",
  "port": 70000,
  "logLevel": "verbose",
  "tags": ["api", "api"],
  "extra": true
}

실패 이유:

appName: minLength 위반
port: maximum 위반
logLevel: enum 위반
tags: uniqueItems 위반
extra: additionalProperties 위반

17. 제일 많이 쓰는 패턴 예제

JSON

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "minimum": 1
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "email": {
      "type": ["string", "null"],
      "format": "email"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["admin", "user", "viewer"]
      },
      "minItems": 1,
      "uniqueItems": true
    }
  },
  "required": ["id", "name", "roles"],
  "additionalProperties": false
}

YAML

$schema: "https://json-schema.org/draft/2020-12/schema"
type: object
properties:
  id:
    type: integer
    minimum: 1
  name:
    type: string
    minLength: 1
  email:
    type:
      - string
      - "null"
    format: email
  roles:
    type: array
    items:
      type: string
      enum:
        - admin
        - user
        - viewer
    minItems: 1
    uniqueItems: true
required:
  - id
  - name
  - roles
additionalProperties: false

Valid instance

{
  "id": 1,
  "name": "Alice",
  "email": null,
  "roles": ["admin", "user"]
}

Invalid instance

{
  "id": 0,
  "name": "",
  "email": "not-email",
  "roles": ["admin", "admin"],
  "age": 30
}

실패 이유:

id: minimum 위반
name: minLength 위반
email: format 위반 가능
roles: uniqueItems 위반
age: additionalProperties 위반

'정리 > 데이터직렬화형식' 카테고리의 다른 글

JSON Schema 정리  (0) 2026.05.03
JSONL, NDJSON 정리  (0) 2026.05.03
'정리/데이터직렬화형식' Related Articles more