JSON Toolkit

JSON Schema로 YAML 검증하기: 설정 파일의 타입 방어선

핵심 요약: YAML 파싱이 통과했다는 것은 문법이 틀리지 않았다는 뜻일 뿐 값이 맞다는 뜻이 아닙니다. country: NO는 YAML 1.1 파서에서 문자열조차 아니고, version: 1.10은 조용히 부동소수점 1.1로 변합니다. 이 가이드는 JSON Schema가 YAML을 검증할 수 있는 이유, CLI와 에디터 두 가지 적용 경로, 노르웨이 국가 코드 사고를 스키마로 미리 막는 방법, 그리고 스키마 검증이 하지 못하는 세 가지를 설명합니다.

중급약 6분 소요2026-11-13 발행2026-11-13 업데이트
JSON Schema로 YAML 설정 파일을 검증하는 타입 방어선 개념도

결론: YAML 1.2는 JSON의 엄격한 상위 집합입니다. 따라서 JSON Schema가 검증하는 것은 파일 형식이 아니라 파싱 후의 데이터 구조이며, 스키마는 한 번만 작성하면 JSON 데이터와 YAML 데이터 모두에 적용됩니다. 이것이 바로 "파서가 조용히 타입을 바꾸는" 사고를 막을 수 있는 이유입니다.

yaml.safe_load가 오류를 내지 않는 것은 그 파일이 합법적인 YAML이라는 증거일 뿐입니다. country: NO가 여전히 문자열이라는 증거가 아닙니다. YAML 1.1 파서에서는 코드가 그 값을 보기 전부터 이미 false입니다.

1. 파싱 통과 ≠ 설정이 올바름: 먼저 실제 사고부터

한 전자상거래 팀이 노르웨이를 배송 국가에 추가했습니다. Ansible group_vars의 목록에 NO 한 줄을 추가하고 리뷰를 통과해 배포했습니다. 일주일 뒤 노르웨이 주문은 0건 — 서버의 JSON 파일에는 "DK", false, "SE"가 들어 있었습니다. Ansible은 변수 파일을 PyYAML(YAML 1.1 파서)으로 읽기 때문에, NO는 파일에서 읽힌 순간 이미 불리언 false였고 to_json 필터는 그대로 내보냈습니다. 템플릿은 정상 렌더링, JSON은 합법, 오류는 전혀 없었습니다. checkout 서비스가 NO not in list로 노르웨이 고객을 계속 거절하고 있었을 뿐입니다.

이런 사고의 공통점은 문법 수준의 도구는 모두 초록불인데 데이터 계층은 이미 틀렸다는 것입니다. 아래 표는 PyYAML 6.0.3으로 실측한 타입 변질입니다. YAML 1.2 파서는 그중 일부만 고칩니다:

작성한 값 YAML 1.1이 읽은 값 YAML 1.2가 읽은 값 의도한 값
country: NO false "NO" "NO"
version: 1.10 부동소수점 1.1 부동소수점 1.1 "1.10"
zip: 02134 8진수 1116 10진수 2134 "02134"
mode: 0755 10진수 493 10진수 755 493 또는 "0755"
ports: ["22:22"] 60진법 1342 "22:22" "22:22"

근본적인 해결책은 코드성 문자열을 모두 따옴표로 감싸는 것입니다. 하지만 따옴표는 사람의 기억에 의존하고, 스키마는 기계의 검사에 의존합니다. 그래서 YAML에 JSON Schema를 붙여야 하는 것입니다.

2. JSON Schema가 YAML을 다룰 수 있는 이유

YAML 1.2 명세는 분명히 말합니다. 1.2의 첫 번째 목표는 YAML을 JSON의 엄격한 상위 집합으로 만드는 것이었고, 1.2 파서는 일반 JSON을 그대로 읽습니다. 두 형식은 파싱 후 같은 데이터 구조가 되므로, 검증기에게 파일 확장자는 아무 의미가 없습니다. 전체 파이프라인은 세 단계입니다:

  1. YAML 파일을 파싱해 객체/배열을 얻는다;
  2. JSON Schema를 로드한다;
  3. 스키마로 데이터를 검증해 오류를 내거나 통과시킨다.

첫 단계에서 YAML을 JSON 텍스트로 직렬화한 뒤 다시 파싱할 필요는 없습니다. 어떤 언어의 YAML 라이브러리든 데이터 구조를 바로 검증기에 넘길 수 있습니다. 스키마 자체를 YAML로 쓸 수도 있습니다(yq -P schema.json > schema.yaml 한 줄로 상호 변환). 하지만 JSON으로 유지하는 편이 안전합니다. 도구 체인 호환성이 좋고, schemastore.org 카탈로그의 모든 스키마도 JSON이기 때문입니다.

3. CLI 세 가지 적용 경로

config.yaml을 예로 듭니다. 스키마는 name과 version을 필수로 요구하고, version은 시맨틱 버전 형식, countries는 두 글자 대문자 문자열 배열이어야 합니다:

# config.yaml
name: checkout
version: "1.4.2"
countries:
  - DK
  - NO
  - SE

Python(jsonschema + PyYAML):

import json, yaml
from jsonschema import validate

data = yaml.safe_load(open("config.yaml", encoding="utf-8"))
schema = json.load(open("schema.json", encoding="utf-8"))
validate(instance=data, schema=schema)

Node(js-yaml + Ajv):

import Ajv from "ajv";
import yaml from "js-yaml";
import fs from "fs";

const schema = JSON.parse(fs.readFileSync("schema.json", "utf8"));
const data = yaml.load(fs.readFileSync("config.yaml", "utf8"));
const validate = new Ajv().compile(schema);
if (!validate(data)) console.error(validate.errors);

순수 파이프(yq + ajv-cli):

yq -o=json config.yaml | ajv validate -s schema.json -d -
# 또는 check-jsonschema는 YAML을 직접 받는다
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml

세 경로의 차이는 파싱 계층뿐입니다. 앞의 두 가지는 명시적 두 단계, 파이프는 한 줄로 흘려보내고, check-jsonschema는 내부에서 YAML→JSON 변환을 대신 해줍니다. 스키마 파일은 셋 모두 같은 것입니다.

4. 에디터 실시간 검증: modeline과 SchemaStore

Red Hat의 YAML 확장(yaml-language-server 기반)은 VS Code에서 약 3000만 건 설치되었고 JSON Schema draft-04/07/2019-09/2020-12를 지원합니다. 연결 방법은 세 가지입니다:

# 방법 1: modeline. 파일 첫 줄에서 스키마를 가리킨다
# yaml-language-server: $schema=./schema.json
name: checkout
// 방법 2/3: .vscode/settings.json에서 파일명 또는 glob으로 매핑
{
  "yaml.schemas": {
    "./schema.json": ["config/*.yaml", "*.config.yaml"],
    "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
  }
}

yaml.schemaStore.enable은 기본적으로 켜져 있습니다. package.json, GitHub workflow, docker-compose 같은 흔한 파일은 schemastore.org 카탈로그에 자동으로 연결되며 설정 한 줄도 필요 없습니다. 스키마의 description은 자동 완성 설명과 호버 텍스트가 되고, required 누락에는 빨간 줄이 그여집니다. 설정 오류가 "배포 후 조사"에서 "키를 누르는 순간"으로 앞당겨집니다. 이것은 또한 SchemaStore가 쓰이는 이유이기도 합니다. YAML에는 공식 스키마 표준이 없고 JSON Schema가 사실상 표준이기 때문입니다.

5. 스키마는 노르웨이 문제를 어떻게 미리 막았을까

1절의 NO 사고로 돌아갑니다. countries에 요소 수준 스키마를 작성합니다:

{
  "type": "object",
  "required": ["name", "version", "countries"],
  "properties": {
    "countries": {
      "type": "array",
      "items": { "type": "string", "pattern": "^[A-Z]{2}$" }
    }
  }
}

PyYAML이 읽은 false는 문자열이 아니므로 type: string이 즉시 실패합니다. 다른 파서가 소문자 "no"로 읽었다 하더라도 pattern이 막습니다. 더 엄격하게 하려면 enum 허용 목록을 추가하면 됩니다. 같은 스키마를 CI에서는 3절의 CLI 경로로, 에디터에서는 4절의 modeline으로 돌리면 양쪽 모두 같은 계약이 됩니다.

yamllint와의 역할 분담도 짚어둡니다. yamllint의 truthy 규칙(true/false만 허용하고 그 외 불리언 비슷한 철자는 모두 경고)이 관할하는 것은 작성 스타일이며, lint 계층에서 flag: yes를 잡아냅니다. JSON Schema가 관할하는 것은 데이터 형태이며 어떤 파서를 쓰든 무관합니다. 사고 팀은 결국 세 가지를 모두 도입했습니다. 문자열 따옴표 처리, 파이프라인에 yamllint truthy 도입, 템플릿에서 두 글자 문자열 단언입니다. 두 방어선은 중복이 아니라 보완입니다.

6. Kubernetes 매니페스트 일괄 검증

Kubernetes API 자체가 OpenAPI로 기술되어 있고, kubernetes-json-schema 프로젝트가 이를 표준 JSON Schema로 변환합니다. kubeconform은 이 스키마군으로 일괄 검증을 수행합니다. 4코어 노트북에서 35139개 파일, 50714개 리소스를 kubeconform -ignore-missing-schemas -n 8 -summary로 검증하는 데 6.7초, 같은 작업을 kubeval로는 35초가 걸렸습니다. Helm 사용자의 정석은 먼저 렌더링하고 검증하는 것입니다:

helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml

-strict는 스키마에 정의되지 않은 필드를 거부하고(오타를 조기 노출), CRD 리소스는 -ignore-missing-schemas로 건너뛰거나 -schema-location으로 사용자 지정 스키마를 연결합니다.

7. 스키마 검증이 하지 못하는 것: 세 가지 경계

  1. 파서 버전 차이는 파싱 계층에서 발생한다. 스키마가 보는 것은 파싱 결과입니다. PyYAML이 읽은 NO는 이미 false이고, 스키마는 type/pattern으로 이 잘못된 값을 붙잡을 수 있을 뿐입니다. 근본 해결책은 여전히 따옴표이며, 스키마에 파서 수정을 기대해서는 안 됩니다.
  2. 논리 오류는 관할 밖이다. selector와 labels의 철자 불일치, K8s에서 selector가 존재하지 않는 라벨을 가리키는 경우, 스키마는 형태만 보고 의미는 보지 못합니다. 이런 오류는 admission webhook, OPA 정책, kubectl apply --dry-run=server로 막아야 합니다.
  3. 중복 키는 조용히 나중 것이 이긴다. 많은 YAML 파서는 중복 키를 경고 없이 받아들입니다. 스키마가 받는 데이터는 이미 한 키를 잃은 상태이며, yamllint의 key-duplicates나 파싱 훅으로만 검출할 수 있습니다.

배포 전 체크리스트: 코드성 문자열은 따옴표로 감싸기 → yamllint(truthy + key-duplicates) → JSON Schema 검증(CI와 에디터 양쪽) → 클러스터 리소스는 --dry-run=server도 통과. 이 네 단계를 밟으면 1절의 노르웨이 사고는 이 파이프라인의 두 번째 단계를 넘지 못합니다.

자주 묻는 질문

JSON Schema는 YAML 파일을 직접 검증할 수 있나요?

가능하지만 검증 대상은 "파일"이 아니라 파일을 파싱한 후의 데이터입니다. YAML 1.2는 JSON의 엄격한 상위 집합이고 양쪽이 같은 데이터 구조로 파싱되므로, 하나의 스키마가 JSON과 YAML 모두에 적용됩니다. Python, Node, yq 파이프, check-jsonschema 네 경로 중 아무거나 선택하며 수동 형식 변환은 필요 없습니다.

SchemaStore는 무엇이고 어떻게 사용하나요?

schemastore.org는 JSON Schema 카탈로그(catalog.json)로, package.json, GitHub workflow, docker-compose 등 수백 종의 흔한 설정 파일 스키마를 수록합니다. YAML/JSON 언어 지원을 설치한 에디터는 기본값으로 자동 연결하며, yaml.schemas에서 URL을 수동 매핑할 수도 있습니다. 자체 프로젝트의 설정 파일이라면 고유 스키마를 카탈로그에 제출할 수도 있습니다.

yamllint와 JSON Schema 검증은 중복 아닌가요?

중복이 아닙니다. yamllint는 작성 스타일(들여쓰기, 행 길이, truthy, 중복 키)을 텍스트 계층에서 검사하고, JSON Schema는 데이터 구조(타입, 필수, 열거, pattern)를 데이터 계층에서 검사합니다. 노르웨이 사고의 수정 목록에는 둘 다 있었습니다. truthy 규칙은 flag: yes 같은 철자를 잡고, 스키마는 문자열 배열에 섞여 들어간 false를 잡습니다.

Kubernetes 검증은 kubeconform과 kubectl dry-run 중 무엇을 쓰나요?

역할이 다릅니다. kubeconform은 오프라인 일괄 처리로 클러스터가 필요 없고 CI에서 구조적 오류를 막는 데 적합합니다. dry-run=server는 실제 API 서버와 통신해 admission webhook과 할당량 계층의 문제를 발견하지만 클러스터 연결이 필수입니다. 표준 조합은 CI에서 kubeconform 실행 후 배포 전에 dry-run=server를 한 번 통과하는 것입니다. 두 방어선 모두 생략하지 마세요.


스키마를 작성한 뒤 온라인 JSON 검증 도구에 YAML에서 변환한 JSON을 붙여 넣어 오류를 먼저 확인할 수 있습니다. 스키마 키워드 작성법은 JSON Schema 완전 가이드를, CI에서 스키마를 테스트로 감시하는 방법은 JSON Schema 계약 테스트를, 일상적인 JSON↔YAML 변환에는 JSON YAML XML 변환 도구를 이용하세요.

참고 자료

관련 문서

JSON Schema: 기초부터 운영까지

키워드는 많지만 매일 쓰는 것은 열두 개 정도입니다. type/properties/required/$ref만 제대로 쓰고 오류 메시지를 잘 처리하면 실무 사례의 80퍼센트를 덮습니다.

중급약 14분 소요2026-10-30 업데이트

JSON Schema 계약 테스트: 검증 규칙을 CI에 용접하기

스키마는 작성으로 끝이 아니라 거기서부터 망가지기 시작합니다. 오타 하나가 검증을 조용히 느슨하게 만들고, 리팩터링 하나가 픽스처 전체를 오작동시킵니다. 이 글은 정례·부례·스냅샷 3종 세트, 스키마 자체의 린트, 컴파일 한 번 재사용, CI에 설치하는 네 개의 게이트로 이루어진 실행 가능한 계약 테스트 구성을 다룹니다.

중급약 8분 소요2026-11-05 업데이트

JSON ↔ YAML과 XML 변환의 경계

JSON이 YAML의 부분 집합이라는 주장은 한 방향만 보장하며, XML에는 공식 JSON 매핑이 전혀 없어 모든 것이 관례에 달려 있습니다.

중급약 12분 소요2026-10-30 업데이트