JSON 튜토리얼

JSON Schema란? 사용법, 예제 및 완전 튜토리얼 (2026)

작성자 2026-08-24 공개 2026-08-24 업데이트 약 12분 읽기

API 응답이나 설정 파일을 다룰 때 JSON 구문이 맞다고 해서 데이터가 「유효」한 것은 아닙니다 — 필드 누락, 타입 오류, 값 범위 초과는 종종 런타임까지 드러나지 않습니다. JSON Schema는 바로 이런 문제를 해결하기 위한 규격입니다. 이 글은 정의와 사용 시나리오에서 출발해 기본 작성법, 자주 쓰는 키워드, 실전 검증 흐름, 도구 선택까지 단계별로 설명하여 실행 가능한 JSON 데이터 제약 방안을 잡을 수 있게 돕습니다.

읽기 전 요약

항목	설명
핵심 문제	JSON 구문은 맞지만 구조·값이 비즈니스 약속과 불일치
해결 접근	Schema로 필드 타입·필수·제약 선언 후 자동 검증
권장 버전	Draft 2020-12 (생태계 지원 가장 성숙)
이 글에서 다루는 내용	정의 → 작성 → 키워드 → 실전 → 선택 → FAQ

JSON Schema란?

JSON Schema는 JSON 기반 규격으로, 「JSON 데이터가 만족해야 할 조건」을 기술합니다. 데이터의 타입 선언 + 제약 규칙으로 이해할 수 있습니다: 어떤 필드가 필수인지, 각 필드 타입, 문자열 길이·숫자 범위, 배열 요소 구조 등을 Schema에 담을 수 있습니다.

Schema 자체도 유효한 JSON 문서이지만 의미는 다릅니다 — Schema는 비즈니스 데이터를 담지 않고 데이터의 형태를 기술합니다. OpenAPI 3.x는 JSON Schema로 요청/응답 본문을 기술하고, 많은 CLI 도구가 Schema로 설정 파일을 검증하며, 프론트엔드 폼 라이브러리도 Schema 기반 검증을 씁니다. 익숙해지면 프론트·백엔드·CI에서 동일 제약 정의를 재사용해 「각자 따로 검증」하는 중복을 줄일 수 있습니다.

왜 JSON Schema가 필요한가?

일상 개발에서 JSON.parse()는 괄호 짝, 따옴표 정도만 알려줍니다. 아래 상황에서는 구문 검증이 전혀 도움이 되지 않습니다:

인터페이스가 email 필드를 요구하지만 응답에 누락
age는 정수여야 하는데 클라이언트가 문자열 "25" 전송
열거 필드 status에 약속 밖 값 "unknown" 등장
중첩 객체 address.zip이 우편번호 형식 불일치

JSON Schema의 가치는 위 「암묵적 약속」을 실행 가능하고, 공유 가능하며, 버전 관리 가능한 선언으로 바꾸는 것입니다. 팀은 Code Review 단계에서 Schema와 대조해 인터페이스 변경을 확인할 수 있고, 연동이나 배포 후에야 필드 불일치를 발견하는 일을 줄일 수 있습니다.

JSON Schema 기본 사용법과 예제

최소 Schema는 $schema(사용 규격 버전)와 루트 type을 선언합니다. 아래는 사용자 객체 예: name 필수 문자열, age 선택 비음수 정수.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/user.json",
  "title": "User",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "사용자 이름"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name"],
  "additionalProperties": false
}

유효한 데이터 인스턴스 예:

{ "name": "김철수", "age": 28, "email": "kim@example.com" }

{ "age": 28 }(필수 name 누락) 또는 { "name": "홍길동", "extra": true }(additionalProperties: false로 추가 필드 금지)를 넣으면 검증기가 명확한 오류 경로와 이유를 반환합니다.

자주 쓰는 키워드 빠른 참조

Draft 2020-12에서 개발자가 가장 자주 쓰는 키워드는 다음과 같습니다. Schema 작성 시 거의 항상 사용합니다:

키워드	역할	예제
type	데이터 타입 선언	"string" / "integer" / "object"
properties	객체 필드 정의	{ "id": { "type": "integer" } }
required	필수 필드 목록	["id", "name"]
enum	열거값 제한	["draft", "published"]
format	일반 문자열 형식	"email" / "date-time"
$ref	다른 Schema 조각 참조	"#/$defs/Address"

복잡한 Schema는 $defs로 재사용 조각(Address, Pagination 등)을 나누고 $ref로 참조해 단일 파일 비대화를 피하세요.

JSON Schema와 JSON 구문 검증의 차이

둘은 다른 계층의 문제를 해결하며, 실무에서는 보통 함께 씁니다:

구문 검증: 괄호·따옴표·쉼표 유효 → JSON.parse 가능
Schema 검증: 필드·타입·제약이 약속과 일치 → 비즈니스 규칙 통과

권장 워크플로: 원문을 JSONSort에 붙여 포맷·구문 검사 후 ajv, fastjsonschema 등으로 Schema 검증. 로컬 도구는 구문, Schema는 의미 — 역할을 분리하세요.

실전: API 계약 검증 흐름

일반적인 REST 프로젝트 예로, 전체 흐름을 네 단계로 나눌 수 있습니다:

Schema 정의: 저장소에 schemas/user.json 유지, OpenAPI·문서와 버전 동기화.
예제 작성: 유효·무효 샘플 각 1개를 단위 테스트 fixture로 제공.
CI 통합: PR 파이프라인에서 Mock 응답과 Schema 일치 검증, 필드 삭제·이름 변경 방지.
런타임 안전망: 서버가 요청 본문 Schema 검증 후 400과 구조화 오류 반환, 잘못된 데이터 DB 저장 방지.

이 흐름의 핵심 이점은 변경 가시성입니다: 인터페이스 필드 변경이 CI 단계에서 잡히며, 사람 기억이나 연동 중 우연한 발견에 의존하지 않습니다.

JSON Schema와 다른 방안 비교

방안	장점	한계
JSON Schema	언어 독립, OpenAPI 네이티브 지원, 성숙한 생태계	복잡 규칙 표현력 한계, 학습 곡선 존재
TypeScript 타입	IDE 경험 우수, 컴파일 타임 검사	TS 생태계 한정, 런타임 추가 변환 필요
수동 if/else 검증	유연, 추가 의존성 없음	유지보수·재사용 어려움, 경계 케이스 누락 쉬움
Protobuf / Avro	강타입, 고성능 직렬화	컴파일 단계 필요, 순수 JSON API에는 부적합

API가 이미 JSON + OpenAPI라면 JSON Schema가 보통 마찰 최소 선택입니다. 풀스택 TypeScript이고 언어 간 계약이 필요 없다면 TS 중심, Schema 보조가 가능합니다.

JSON Schema에 투자할 가치가 있나?

투자를 권장하는 경우:

외부 API 제공, 호출자와 기계 판독 가능한 계약 공유 필요
설정 구조 복잡, 배포 전 형식 오류 차단 희망
다중 클라이언트(Web / 모바일 / 백엔드)가 동일 데이터 제약 공유
CI에서 인터페이스 breaking change 자동 탐지 필요

미룰 수 있는 경우:

가끔 JSON 포맷·조회만 → JSONSort면 충분
구조 매우 단순·장기 불변 → 수동 검증 비용 더 낮음
팀에 OpenAPI / 계약 테스트 없음 → 문서 습관 후 Schema 도입

자주 묻는 질문 (FAQ)

JSON Schema란?

JSON Schema는 JSON 데이터 구조와 제약을 기술하는 규칙 집합입니다. 필드 타입, 필수 항목, 값 범위 등을 선언해 검증기가 데이터 유효성을 자동 판단합니다.

JSON Schema와 JSON의 차이는?

JSON은 비즈니스 데이터를 담고, JSON Schema는 그 데이터가 어떤 형태여야 하는지 기술합니다. 비유: JSON은 「인스턴스」, Schema는 「금형」.

어떤 버전을 선택해야 하나?

신규 프로젝트는 Draft 2020-12 우선. 기존 Draft-07 / 2019-09 사용 중이면 새 키워드 의존이 아니면 강제 마이그레이션 불필요.

로컬에서 어떻게 검증하나?

구문은 JSONSort로 포맷·검사; Schema는 ajv(Node.js), jsonschema(Python), VS Code JSON Schema 확장.

OpenAPI와 JSON Schema의 관계는?

OpenAPI 3.x 요청/응답 본문 정의는 JSON Schema 부분집합을 확장한 것입니다. OpenAPI 문서 작성은 본질적으로 Schema 작성입니다.

결론

JSON Schema가 푸는 질문은 「JSON을 파싱할 수 있는가」가 아니라 「데이터가 팀 약속에 맞는가」입니다. 정의·작성부터 CI 통합까지, 암묵 규칙을 명시적·실행 가능한 계약으로 바꾸는 것이 가치입니다. 작은 인터페이스나 설정 파일부터 Schema를 작성·검증에 연결한 뒤 점차 확장하세요.

더 읽어보기

JSON Schema 공식 규격 권위 있는 키워드·버전 설명
JSONSort 로컬 JSON 도구 모음 포맷, 구문 검증, Diff — 브라우저 로컬 실행
블로그 전체 글 더 많은 JSON 개발 튜토리얼과 실습

변경 로그: 2026-08-24 초稿 공개