ToolDeck

JSON Schema 검사기

JSON Schema(Draft 7)에 대해 JSON 데이터 유효성 검사

예시 시도

JSON 데이터

JSON Schema

로컬에서 실행 · 시크릿 붙여넣기 안전
로컬에서 실행 · 시크릿 붙여넣기 안전

JSON Schema 유효성 검사란?

JSON Schema 유효성 검사는 JSON 문서가 JSON Schema에 정의된 구조적·값 제약 조건을 준수하는지 확인하는 과정입니다. Schema 자체도 JSON 문서로, 데이터의 예상 형태를 기술합니다. 어떤 프로퍼티가 필수인지, 각 타입이 무엇이어야 하는지, 숫자의 허용 범위, 문자열 패턴, 배열 길이 등을 정의합니다. JSON Schema 명세는 json-schema.org에서 관리되며 일련의 IETF 초안으로 게시됩니다. Draft 7과 Draft 2020-12가 가장 널리 채택되어 있습니다.

단순 JSON 유효성 검사는 구문만 확인합니다(괄호가 올바르게 닫혔는지, 문자열에 따옴표가 있는지 등). Schema 유효성 검사는 한 걸음 더 나아가 구조적 계약을 검사합니다. 이 API 응답에 항상 정수형인 "id" 필드가 포함되어 있는지, "status" 필드가 허용된 세 가지 값 중 하나인지, 중첩 객체의 형태가 올바른지 등을 확인합니다. 이러한 구조적 검증은 구문 검사가 잡아내지 못하는 버그를 발견합니다. 구문상 유효한 JSON이라도 애플리케이션에 의미상으로는 잘못될 수 있기 때문입니다.

JSON Schema는 OpenAPI/Swagger 정의, 설정 파일 유효성 검사, 폼 유효성 검사, 데이터베이스 문서 제약 조건, 자동화 테스트 등에 활용됩니다. Ajv(JavaScript), jsonschema(Python), check-jsonschema(CLI) 같은 도구들이 명세를 구현하여 프로그래밍 방식으로 데이터를 검사할 수 있게 해줍니다. 이 온라인 검사기는 Schema와 데이터 문서를 모두 붙여넣어 라이브러리 설치 없이 즉시 준수 여부를 확인할 수 있습니다.

온라인 JSON Schema 검사기를 사용하는 이유

Schema를 작성하고 유효성 오류를 직접 디버깅하는 것은 시간이 많이 걸립니다. 온라인 JSON Schema 검사기는 데이터가 Schema와 일치하는지 즉각적인 피드백을 제공하며, 실패한 프로퍼티를 명확한 오류 메시지로 정확히 가리킵니다.

즉각적인 유효성 검사 피드백
Schema와 데이터를 붙여넣으면 실시간으로 검사 결과를 확인할 수 있습니다. 각 오류는 JSON 경로와 실패한 특정 제약 조건을 표시하므로, 검사 라이브러리 출력을 일일이 읽지 않고도 문제를 수정할 수 있습니다.
🔒
개인정보 우선, 브라우저 전용 처리
JSON 데이터는 브라우저 밖으로 전송되지 않습니다. 모든 유효성 검사는 JavaScript로 로컬에서 실행됩니다. 서버도, 로그도, 데이터 보관도 없습니다. 내부 API를 기술하거나 독점 필드명을 포함하는 Schema에도 안전하게 사용할 수 있습니다.
🎯
Draft 인식 유효성 검사
type, required, properties, enum, pattern, minimum/maximum, items, anyOf, oneOf, allOf, additionalProperties 등 Draft 7 Schema 키워드를 처리합니다. 빌드 파이프라인이나 테스트 스위트에 연결하기 전에 여기서 Schema를 테스트해보세요.
📋
계정이나 설치 불필요
페이지를 열고 JSON을 붙여넣어 검사하면 됩니다. npm install도, pip 패키지도, Docker 이미지도 필요 없습니다. 개발 도구를 설치할 수 없는 환경에서 빠른 Schema 확인이 필요할 때 유용합니다.

JSON Schema 유효성 검사 활용 사례

API 계약 테스트
OpenAPI 명세에 정의된 Schema에 대해 API 응답을 검사합니다. 필드 타입이 정수에서 문자열로 바뀌는 등의 브레이킹 체인지를 프로덕션에 반영되기 전에 발견합니다.
설정 파일 검증
커밋 전에 CI/CD 파이프라인, Kubernetes 매니페스트, 애플리케이션 설정 등의 JSON 설정 파일이 예상 Schema와 일치하는지 확인합니다. 누락되거나 잘못 입력된 키로 인한 배포 실패를 방지합니다.
DevOps 파이프라인 게이트
CI 단계에 Schema 유효성 검사를 추가하여 계약을 위반하는 페이로드를 거부합니다. Terraform 변수 파일, GitHub Actions 입력값, 또는 자동화에서 사용하는 구조화된 JSON에 적용할 수 있습니다.
QA 및 테스트 데이터 검토
테스트 픽스처와 목 데이터 파일이 애플리케이션이 기대하는 Schema와 일치하는지 검증합니다. 불일치하는 테스트 데이터는 거짓 양성 테스트 결과의 흔한 원인입니다.
데이터 파이프라인 수집
데이터 파이프라인의 진입점에서 수신 JSON 레코드를 검사합니다. Schema 유효성 검사는 잘못된 형식의 이벤트를 데이터 웨어하우스에 도달하기 전에 걸러내어 하류의 정제 비용을 줄여줍니다.
JSON Schema 구문 학습
Schema 키워드를 대화형으로 실험해보세요. Schema를 작성하고 테스트 데이터를 붙여넣어 어떤 제약 조건이 통과하거나 실패하는지 확인합니다. 터미널에서 스크립트를 작성하고 매번 실행하는 것보다 훨씬 빠릅니다.

JSON Schema 키워드 참조

JSON Schema는 검사 대상 데이터에 각각 제약을 부과하는 키워드로 구성됩니다. 아래 표는 Draft 7 이상에서 가장 많이 사용되는 키워드를 나열합니다. 모든 키워드는 같은 Schema 객체 안에서 다른 키워드와 조합할 수 있습니다.

키워드용도예시
typeRestricts the data type"type": "string"
propertiesDefines expected object keys and their schemas"properties": { "name": { "type": "string" } }
requiredLists mandatory properties"required": ["id", "name"]
itemsSchema for array elements"items": { "type": "number" }
enumRestricts value to a fixed set"enum": ["active", "inactive"]
patternRegex constraint on strings"pattern": "^[A-Z]{2}\\d{4}$"
minimum / maximumNumeric range bounds"minimum": 0, "maximum": 100
minLength / maxLengthString length bounds"minLength": 1, "maxLength": 255
$refReuses another schema by URI"$ref": "#/$defs/address"
additionalPropertiesControls extra keys in objects"additionalProperties": false
anyOf / oneOf / allOfCombines multiple schemas logically"anyOf": [{ "type": "string" }, { "type": "null" }]
if / then / elseConditional schema application"if": { "properties": { "type": { "const": "email" } } }

JSON Schema Draft 비교: Draft 7 vs 2019-09 vs 2020-12

JSON Schema는 여러 Draft 버전을 거쳤습니다. 2018년에 게시된 Draft 7이 도구 지원 면에서 가장 널리 지원됩니다. Draft 2019-09는 $defs(definitions 대체), unevaluatedProperties, $recursiveRef를 도입했습니다. 최신 안정 릴리스인 Draft 2020-12는 $recursiveRef를 $dynamicRef로 교체하고 튜플 유효성 검사를 위한 prefixItems를 도입했습니다. Draft를 선택할 때는 유효성 검사 라이브러리가 해당 Draft를 지원하는지 확인하세요. Ajv는 세 Draft 모두 지원합니다. Python의 jsonschema 라이브러리는 버전 4.0부터 2020-12까지 지원합니다.

기능Draft 7Draft 2019-09Draft 2020-12
$schema URIdraft-07/schema#2019-09/schema2020-12/schema
if / then / elseYesYesYes
$defs (definitions)definitions$defs$defs
$ref alongside keysNo (sibling ignored)YesYes
$dynamicRefNoNo ($recursiveRef)Yes
prefixItemsNo (use items array)No (use items array)Yes
unevaluatedPropertiesNoYesYes
$vocabularyNoYesYes

코드 예시

아래 예시는 프로그래밍 방식으로 JSON을 Schema에 대해 검사하는 방법을 보여줍니다. 각 언어 생태계에서 잘 유지 관리되는 라이브러리를 사용합니다.

JavaScript (Ajv)
import Ajv from 'ajv';

const ajv = new Ajv();

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 1 },
    age: { type: 'integer', minimum: 0 },
    email: { type: 'string', format: 'email' }
  },
  required: ['name', 'email'],
  additionalProperties: false
};

const data = { name: 'Alice', age: 30, email: 'alice@example.com' };

const validate = ajv.compile(schema);
const valid = validate(data);
console.log(valid);          // → true
console.log(validate.errors); // → null

// Invalid data — missing required "email"
validate({ name: 'Bob', age: 25 });
console.log(validate.errors);
// → [{ instancePath: '', keyword: 'required', params: { missingProperty: 'email' } }]
Python (jsonschema)
from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "age": {"type": "integer", "minimum": 0},
        "tags": {
            "type": "array",
            "items": {"type": "string"},
            "uniqueItems": True
        }
    },
    "required": ["name"]
}

# Valid data
validate(instance={"name": "Alice", "age": 30, "tags": ["admin"]}, schema=schema)
# → No exception raised

# Invalid data — wrong type for "age"
try:
    validate(instance={"name": "Alice", "age": "thirty"}, schema=schema)
except ValidationError as e:
    print(e.message)
    # → 'thirty' is not of type 'integer'
    print(e.json_path)
    # → $.age
Go (santhosh-tekuri/jsonschema)
package main

import (
    "fmt"
    "strings"
    "github.com/santhosh-tekuri/jsonschema/v5"
)

func main() {
    schemaJSON := `{
        "type": "object",
        "properties": {
            "id": { "type": "integer" },
            "status": { "enum": ["active", "inactive"] }
        },
        "required": ["id", "status"]
    }`

    compiler := jsonschema.NewCompiler()
    compiler.AddResource("schema.json", strings.NewReader(schemaJSON))
    schema, _ := compiler.Compile("schema.json")

    // Valid data
    data := map[string]interface{}{"id": 1, "status": "active"}
    err := schema.Validate(data)
    fmt.Println(err) // → <nil>

    // Invalid — missing "status"
    bad := map[string]interface{}{"id": 2}
    err = schema.Validate(bad)
    fmt.Println(err) // → validation failed: missing properties: 'status'
}
CLI (check-jsonschema)
# Install via pip
pip install check-jsonschema

# Validate a file against a schema
check-jsonschema --schemafile schema.json data.json
# → ok -- validation done

# Validate against a remote schema (e.g., GitHub Actions workflow)
check-jsonschema --builtin-schema vendor.github-workflows my-workflow.yml

# Validate multiple files at once
check-jsonschema --schemafile schema.json file1.json file2.json file3.json

자주 묻는 질문

JSON 유효성 검사와 JSON Schema 유효성 검사의 차이점은 무엇인가요?
JSON 유효성 검사는 문자열이 유효한 JSON 구문인지 확인합니다. 괄호가 올바르게 중첩되었는지, 키에 따옴표가 있는지, 후행 쉼표가 없는지 등을 검사합니다. JSON Schema 유효성 검사는 한 걸음 더 나아가 파싱된 JSON 데이터가 구조적 계약과 일치하는지 확인합니다. 타입이 올바른지, 필수 필드가 있는지, 값이 허용 범위 안에 있는지 등을 검사합니다. Schema를 적용하려면 유효한 JSON이 필요하지만, 유효한 JSON도 Schema 유효성 검사에서 실패할 수 있습니다.
어떤 JSON Schema Draft를 사용해야 하나요?
Draft 7이 가장 안전한 기본값입니다. 언어 전반에 걸쳐 가장 넓은 라이브러리 지원을 갖추고 있으며, 대부분의 프로젝트에 필요한 키워드를 포함합니다. type, properties, required, enum, pattern, anyOf, oneOf, allOf, $ref 등이 지원됩니다. 튜플 유효성 검사를 위한 prefixItems, 확장 가능한 Schema를 위한 $dynamicRef, 엄격한 객체 형태를 위한 unevaluatedProperties 같은 기능이 필요하다면 Draft 2020-12를 사용하세요. 업그레이드 전에 검사 라이브러리 문서에서 Draft 지원 여부를 확인하세요.
JSON Schema에서 $ref는 어떻게 동작하나요?
$ref 키워드를 사용하면 Schema를 중복하지 않고 URI로 다른 Schema를 참조할 수 있습니다. "$ref": "#/$defs/address" 같은 값은 같은 문서의 $defs 섹션에 정의된 Schema를 가리킵니다. "$ref": "https://example.com/schemas/address.json"처럼 외부 파일도 참조할 수 있습니다. Draft 7에서는 $ref가 같은 객체 안의 모든 형제 키워드를 대체합니다. Draft 2019-09 이상에서는 형제 키워드가 $ref와 함께 적용됩니다.
anyOf, oneOf, allOf의 차이점은 무엇인가요?
allOf는 배열의 모든 하위 Schema와 데이터가 일치해야 합니다. anyOf는 하위 Schema 중 하나 이상과 일치하면 됩니다. oneOf는 정확히 하나의 하위 Schema와 일치해야 하며, 하나도 일치하지 않거나 둘 이상 일치하면 실패합니다. nullable 필드에는 type과 null을 포함한 anyOf가 일반적입니다. {"anyOf": [{"type": "string"}, {"type": "null"}]} 형태로 사용합니다. 태그드 유니언처럼 하위 Schema가 상호 배타적인 경우에는 oneOf를 사용하세요.
JSON Schema로 중첩 객체와 배열을 검사할 수 있나요?
가능합니다. properties 키워드를 사용하여 중첩 객체 키에 대한 Schema를 정의하고, items 키워드를 사용하여 모든 배열 요소가 일치해야 하는 Schema를 정의합니다. 이를 원하는 깊이만큼 중첩할 수 있습니다. 각 위치마다 다른 Schema를 갖는 배열(튜플)의 경우 Draft 2020-12에서는 prefixItems를, Draft 7에서는 배열 형태의 items를 사용하세요.
이 도구에 붙여넣은 데이터가 서버로 전송되나요?
아닙니다. 검사기는 JavaScript를 사용하여 브라우저에서 완전히 실행됩니다. JSON 데이터와 Schema는 어떠한 서버에도 전송되지 않습니다. 도구를 사용하는 동안 브라우저 네트워크 인스펙터를 열어 직접 확인할 수 있습니다.
CI/CD 파이프라인에서 JSON Schema 유효성 검사를 어떻게 하나요?
check-jsonschema(Python/pip) 또는 ajv-cli(Node.js/npm) 같은 CLI 검사기를 사용하세요. 둘 다 Schema 파일과 하나 이상의 데이터 파일을 인수로 받습니다. CI 설정에 유효성 검사 명령을 단계로 추가하세요. 검사가 실패하면 프로세스가 0이 아닌 코드로 종료되어 파이프라인이 차단됩니다. GitHub Actions의 경우 check-jsonschema 액션을 직접 사용할 수도 있습니다.