YAML JSON 차이 — 문법·주석·파서별 동작과 용도별 선택 기준

YAML과 JSON의 차이 — 결론부터

한마디로 요약하면 API나 시스템 간 데이터 교환에는 JSON을 쓰고, 사람이 직접 손으로 작성하고 관리하는 설정 파일에는 YAML을 쓰는 것이 기본 원칙입니다. 두 형식 모두 객체(오브젝트), 배열(리스트), 문자열, 숫자, 불리언이라는 동일한 데이터 모델을 표현할 수 있습니다. 하지만 JSON은 엄격하고 명시적인 반면, YAML은 들여쓰기 기반으로 가독성이 높고 주석을 공식 지원한다는 차이가 있습니다.

핵심 요약

• JSON은 엄격하고 파싱 속도가 빠르며 기계 처리에 최적화되어 있고, YAML은 들여쓰기 기반으로 사람이 읽기 쉽고 주석을 달 수 있습니다
• REST API, 로그 스트림, 대용량 처리에는 JSON이 적합하고, Kubernetes, GitHub Actions, Ansible처럼 사람이 편집하는 설정 파일에는 YAML이 적합합니다
• YAML은 주석, 앵커(참조), 여러 줄 문자열, 날짜 타입을 내장 지원하지만 JSON은 지원하지 않습니다
• LLM 프롬프트에 전달할 때 들여쓰기된(pretty) JSON보다 YAML이 약 20% 토큰을 덜 소비합니다(본 사이트 실측 -22%). 다만 공백을 모두 제거한 압축(compact) JSON의 경우 순위가 역전되어 JSON이 더 적은 토큰을 사용합니다. JSON은 파싱이 빠르고 신뢰할 수 없는 입력에 대해서도 안전합니다

이 글에서는 구체적인 문법 차이, 동일한 데이터의 포맷별 작성 예시, 실무에서의 선택 기준, 그리고 포맷 변환 시 자주 겪는 함정을 순서대로 설명합니다. 2026년 들어 많은 관심을 받는 LLM 프롬프트 입력 시의 토큰 비용 관점도 함께 다룹니다.

설정 파일을 두 형식으로 직접 비교해 보고 싶다면, 먼저 YAML을 YAML to JSON 변환기에 붙여넣어 JSON으로 변환한 뒤, 결과 JSON을 JSON to YAML 변환기에 다시 넣어 보면 동일한 데이터가 어떻게 바뀌는지 1분 안에 확인할 수 있습니다. 모든 처리는 브라우저 안에서 완료되며 외부 서버로 데이터가 전송되지 않습니다.

실무에서의 용도별 구분과 선택 기준

문법을 자세히 살펴보기 전에, 실무에서 "어떤 형식을 골라야 하는가"는 대부분 다음과 같은 패턴으로 결정됩니다.

• Kubernetes 매니페스트, Helm 차트 — YAML
• Docker Compose 파일 — YAML
• GitHub Actions, GitLab CI, CircleCI 파이프라인 설정 — YAML
• Ansible 플레이북 — YAML
• REST API의 요청 및 응답 본문(Body) — JSON
• package.json, composer.json, 브라우저와 서버 간 통신 — JSON
• 로그 레코드 및 이벤트 스트림 — JSON Lines (JSONL)
• OpenAPI / Swagger 명세서 — YAML 또는 JSON (작성은 YAML로 하고 도구가 JSON을 생성하는 경우가 많음)

기준은 명확합니다. 사람이 직접 읽고 편집하는 파일은 YAML, 프로그램이 생성하고 소비하는 데이터는 JSON입니다. 포맷 선택에서 고민될 때는 이 기준을 가장 먼저 떠올리면 됩니다.

문법 비교: 같은 데이터의 YAML과 JSON 표현

동일한 웹 서버 설정을 두 형식으로 작성해 비교해 봅니다.

YAML:

# 웹 서버 설정
server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - https://example.com
    - https://staging.example.com
  headers:
    X-Frame-Options: DENY
    Strict-Transport-Security: "max-age=31536000"

JSON:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": [
      "https://example.com",
      "https://staging.example.com"
    ],
    "headers": {
      "X-Frame-Options": "DENY",
      "Strict-Transport-Security": "max-age=31536000"
    }
  }
}

주목할 점은 두 가지입니다. 첫째, YAML은 괄호와 따옴표가 적어 코드 길이가 짧습니다. 위 두 스니펫의 길이를 세어 보면 YAML은 232자, JSON은 291자로 약 20% 차이가 납니다(JSON에 쓸 수 없는 주석 줄을 제외하고 비교하면 약 25% 차이입니다). 둘째, 상단의 주석 # 웹 서버 설정을 유지할 수 있는 것은 YAML뿐이며, JSON으로 변환하면 이 정보는 완전히 사라집니다.

데이터 타입: YAML에는 있고 JSON에는 없는 것

YAML과 JSON 모두 문자열, 숫자, 불리언, null, 객체(맵), 배열을 지원합니다. 하지만 YAML은 설정 파일 작성을 돕는 몇 가지 데이터 타입을 추가로 다룰 수 있습니다.

날짜와 타임스탬프

YAML 파서는 ISO 8601 형식의 날짜를 1급 객체 값으로 인식합니다.

release_date: 2026-04-01
created_at: 2026-04-01T09:30:00Z

JSON에는 날짜 타입이 없으므로 단순 문자열로 다뤄야 합니다. 수신하는 애플리케이션 측에서 별도로 날짜 파싱 처리를 해야 합니다.

{
  "release_date": "2026-04-01",
  "created_at": "2026-04-01T09:30:00Z"
}

여러 줄 문자열

YAML은 긴 텍스트 블록을 처리하기 위한 두 가지 표기법을 제공합니다. 리터럴 블록(|)은 줄바꿈을 그대로 유지하고, 폴디드 스칼라(>)는 줄바꿈을 공백 하나로 합칩니다.

description: |
  이 서비스는 GitHub 웹훅을 수신하여
  내부 큐로 전달합니다.

summary: >
  모든 트래픽은 Cloudflare를 통해 프록시되며,
  오리진 서버는 100 rps로 속도가 제한됩니다.

JSON에서 동일한 내용을 표현하려면 한 줄 안에 \n 이스케이프 문자를 넣어 작성해야 합니다.

{
  "description": "이 서비스는 GitHub 웹훅을 수신하여\n내부 큐로 전달합니다.\n",
  "summary": "모든 트래픽은 Cloudflare를 통해 프록시되며, 오리진 서버는 100 rps로 속도가 제한됩니다."
}

느슨한 암묵적 타입 추론

YAML은 따옴표가 없는 값에서 데이터 타입을 자동으로 추론하려고 합니다. 사양 버전에 따라 yes, no, on, off가 불리언 값(true/false)으로 해석되고, 숫자로 보이는 문자열은 숫자가 됩니다. 사람이 작성할 때는 편리하지만 예기치 않은 버그의 원인이 되기도 합니다. 대표적인 사례가 "노르웨이 문제(Norway problem)"로, 국가 코드 country: NO가 불리언 false로 파싱되는 현상입니다. 반면 JSON은 문자열에 항상 큰따옴표가 붙고 모든 타입이 명시적이므로 이러한 모호함이 발생하지 않습니다.

주석: YAML이 설정 파일에 강한 이유

YAML 주석은 #부터 해당 줄의 끝까지입니다. "왜 이 설정값이 필요한지", "어떤 제약이 있는지"를 기록하는 데 매우 유용합니다.

retries: 3  # 상류 서비스 타임아웃을 초과하지 않도록 설정

JSON 표준(RFC 8259)에는 주석 문법이 없습니다. JSON에 주석을 남기기 위해 "_comment": "..." 같은 더미 필드를 두거나 비표준인 JSONC·JSON5를 활용하는 우회법이 쓰이는 것도 바로 이 제약 때문입니다. 자세한 대안과 활용법은 JSON 주석처리 방법을 참고하세요.

앵커와 별칭(Alias): YAML의 재사용 기능

YAML은 값을 한 번 정의하고 다른 위치에서 참조할 수 있습니다. &로 앵커(기준점)를 지정하고, *로 별칭(Alias)을 참조하며, <<: 병합 키로 공통 블록을 가져옵니다.

defaults: &defaults
  adapter: postgres
  host: db.internal
  pool: 5

development:
  <<: *defaults
  database: myapp_dev

production:
  <<: *defaults
  database: myapp_prod
  pool: 20

이 파일을 JSON으로 변환하면 앵커가 인라인으로 전개되어 development와 production이 기본값을 복제하여 갖게 됩니다. 데이터 자체는 온전하지만 "공통 기본값을 공유하고 있다"는 원본 작성자의 의도는 JSON 구조에서 사라집니다.

파싱 성능과 파일 크기

시스템 간 데이터 전송 관점에서는 JSON이 훨씬 빠릅니다. JSON.parse, json.loads, encoding/json처럼 주요 프로그래밍 언어 런타임에는 고도로 최적화된 표준 파서가 내장되어 있습니다. 반면 YAML은 문법이 복잡하고 모호한 규칙이 많아 파싱 속도가 느리며, 대부분의 YAML 라이브러리는 내부적으로 JSON 상당의 트리 구조를 만듭니다.

파일 크기는 "어떤 JSON과 비교하느냐"에 따라 결과가 다릅니다. 토큰 측정에 사용한 것과 동일한 32줄 샘플(scripts/benchmarks/yaml-vs-json-tokens/)로 실측한 결과, YAML은 667바이트, 들여쓰기된 JSON은 857바이트로 YAML이 약 22% 작습니다. 하지만 줄바꿈과 공백을 없앤 압축(compact) JSON은 686바이트로 YAML과 거의 차이가 없습니다. 또한 네트워크 전송 시 gzip 압축을 적용하면 그 차이마저 거의 사라집니다. YAML의 실질적인 비용은 바이트 크기가 아니라 파싱 시의 CPU 연산 시간과 암묵적 타입 추론이 유발하는 예기치 않은 동작입니다.

YAML을 선택해야 하는 경우

• 사람이 직접 읽고 손으로 편집하는 파일인 경우
• 데이터 페이로드가 아니라 애플리케이션이나 인프라 설정 파일인 경우
• 설정 의도를 명시하기 위해 주석이 반드시 필요한 경우
• Kubernetes, Docker Compose, Ansible, CI/CD 등 이미 YAML을 전제로 하는 도구 생태계인 경우
• 앵커와 별칭을 사용해 중복 설정을 줄이고자 하는 경우

보유한 JSON 설정을 YAML로 변환해 가독성을 높이고 싶다면 JSON to YAML 변환기를 사용할 수 있습니다. 중첩 구조와 들여쓰기를 브라우저 안에서 바로 확인할 수 있습니다.

YAML을 쓰지 말아야 하는 경우

YAML이 적합해 보이는 상황이라도 실제로는 부작용이 더 큰 경우가 있습니다.

• 프로그램이 자동으로 생성하는 설정 파일 — 암묵적 타입 추론으로 인해 version: 2.0이 숫자 2로 바뀌는 등 데이터가 조용히 변질될 수 있습니다
• 실시간 고성능 데이터 스트림 — 파싱 오버헤드가 누적되어 처리량에 영향을 줍니다
• 보안상 신뢰할 수 없는 외부 입력 — !!python/object와 같은 YAML 태그로 인해 임의 코드가 실행될 위험이 있습니다. 파싱 시 반드시 yaml.safe_load 등의 안전한 로더를 사용해야 합니다
• 짧고 단순한 단일 계층 데이터 — 들여쓰기로 얻는 간결함이 없고 오히려 JSON이 더 직관적입니다

JSON을 선택해야 하는 경우

• 데이터를 생성하고 소비하는 주체가 프로그램인 경우
• 다양한 프로그래밍 언어 간의 상호운용성이 중요하고 예기치 않은 타입 변환을 방지해야 하는 경우
• REST API나 네트워크를 통해 데이터를 주고받는 경우
• 모호함 없이 엄격하고 일관된 파싱 결과가 필요한 경우
• 고성능 처리가 요구되어 파싱 속도와 리소스 예측 가능성이 중요한 경우

사람이 작성한 YAML을 기계가 처리하는 JSON으로 넘겨야 하는 상황은 실무에서 매우 흔합니다. YAML to JSON 변환기를 사용하면 문법 오류를 줄 번호와 함께 확인하고 타입 추론으로 변질될 수 있는 값을 사전에 점검할 수 있습니다.

결정 매트릭스: YAML vs JSON 한눈에 비교

선택 기준을 표 한 장으로 정리합니다. 왼쪽 열에서 자신의 상황을 찾아 해당 행의 판정을 확인하세요.

YAML을 JSON으로 변환할 때 주의할 함정

YAML에서 JSON으로의 변환은 대부분 무손실로 이루어지지만, 몇 가지 주의할 엣지 케이스가 있습니다.

• 주석 소실 — JSON에는 주석 문법이 없으므로 #으로 시작하는 설명 줄은 모두 제거됩니다
• 앵커의 인라인 전개 — 공유 블록이 각 위치에 복사되어 데이터가 중복됩니다
• 날짜의 문자열화 — ISO 형식 날짜의 고유 타입 정보가 사라지고 일반 문자열이 됩니다
• 타입 추론의 예기치 않은 변환 — version: 2.0 같은 YAML 값이 JSON에서는 숫자 2로 변환될 수 있습니다
• 다중 문서(Multi-document) 처리 — ---로 구분된 여러 YAML 문서는 JSON 단일 파일로 담을 수 없으므로, 하나를 선택하거나 바깥 배열로 감싸야 합니다
• 중복 키(Duplicate keys) — YAML 사양상 중복 키 처리는 구현체에 따라 다르며, JSON에서는 마지막에 선언된 값만 남습니다
• 태그 및 사용자 정의 타입 — YAML의 !!timestamp나 독자 태그는 JSON에 일치하는 대응 타입이 없습니다

실측: 같은 YAML을 4개 파서에 넣었을 때 나타나는 4가지 결과

"타입 추론의 예기치 않은 결과"는 실제로 동일한 한 줄의 YAML이 라이브러리에 따라 어떻게 다른 값으로 변환되는지 확인하기 전까지는 체감하기 어렵습니다. 모호한 스칼라 값들을 널리 쓰이는 주요 파서 4종(js-yaml 4.1.1, yaml/eemeli 2.8.3, PyYAML 6.0.3 safe_load, ruamel.yaml 0.19.1)에 전달하여 실측했습니다(재현 스크립트와 원본 데이터는 scripts/benchmarks/yaml-parser-differences/에 위치하며, 2026-07-10 Apple M5 Pro 환경에서 측정). 변환 후 생성된 JSON에 실제로 들어가는 값은 다음과 같습니다.

포맷 변환 관점에서 주목할 실측 결과는 3가지입니다.

첫째, Norway 문제는 "YAML 전체의 결함"이 아닙니다. 4개 파서 중 NO를 false로 변환하는 것은 YAML 1.1 계열 로더인 PyYAML뿐이며, YAML 1.2 사양을 따르는 나머지 3개 파서는 문자열 "NO"를 그대로 유지합니다.

둘째, 따옴표 없는 날짜는 3가지 방식으로 나뉩니다. eemeli의 yaml 파서는 순수 문자열을 반환하지만, js-yaml, PyYAML, ruamel.yaml은 날짜 객체를 생성하므로 후속 JSON 직렬화 과정에서 별도의 포맷 처리가 필요합니다.

셋째, 병합 키 <<:는 기본 설정 상태의 eemeli yaml 파서에서 동작이 달라집니다. 공유 블록을 병합하는 대신 리터럴 "<<" 키가 JSON 출력에 그대로 남게 되며, 이는 다운스트림 서비스가 실패할 때에야 발견되는 치명적인 데이터 변질로 이어집니다.

파이프라인에서 사용하는 파서를 직접 선택할 수 없는 환경이라면 모호한 값("NO", "1:30", "2026-07-10")을 변환 전에 반드시 큰따옴표로 감싸 두는 것이 안전합니다. 대상 파일을 YAML to JSON 변환기에 붙여넣으면 프로덕션 환경에 배포하기 전에 브라우저 안에서 각 값이 어떻게 변환되는지 미리 확인할 수 있습니다.

자세한 변환 방법과 실무 예제는 YAML JSON 변환 가이드를 참고하세요. 변환 후 생성된 JSON을 읽기 쉽게 정리하는 팁은 JSON 정렬 방법과 팁에서 확인할 수 있습니다.

FormatArc로 YAML ⇄ JSON 변환하기

FormatArc는 브라우저 안에서 모든 변환 처리를 완료합니다. 파일 업로드나 회원가입이 필요 없으며, 데이터는 사용자의 로컬 환경을 벗어나지 않습니다.

• YAML to JSON — YAML을 붙여넣어 JSON을 생성하며 문법 오류 발생 시 줄 번호를 표시합니다
• JSON to YAML — 반대 방향 변환으로 중첩 구조를 유지한 깔끔한 YAML을 출력합니다
• JSON 포맷터 — 변환된 JSON을 정렬하고 문법 오류를 검증합니다

스크립트나 자동화 파이프라인에서 처리하려면 yq새 탭에서 열립니다나 Python의 yaml.safe_load를 사용하는 것이 일반적입니다. Python 원라이너 명령어로 변환하려면 다음과 같이 실행합니다.

python3 -c "import yaml,json,sys; print(json.dumps(yaml.safe_load(sys.stdin),indent=2))" < config.yaml

자주 묻는 질문

YAML은 JSON의 상위 호환(슈퍼셋)인가요?

YAML 1.2 사양부터 유효한 JSON 문서는 그대로 유효한 YAML로 파스될 수 있습니다. 즉 YAML 파서는 JSON 파일을 직접 읽을 수 있습니다. 하지만 반대의 경우는 성립하지 않아 JSON 파서는 YAML을 읽지 못합니다. 또한 실무에서 쓰이는 많은 YAML 라이브러리가 여전히 구형 YAML 1.1을 기본값으로 사용하므로 호환성이 완벽하지 않을 수 있습니다.

Kubernetes나 Docker Compose는 왜 JSON 대신 YAML을 채택했나요?

설정 파일을 사람이 직접 읽고 편집한다는 점을 전제로 설계되었기 때문입니다. 들여쓰기 기반의 문법과 주석 지원 덕분에 방대한 인프라 설정을 사람이 유지보수하기 훨씬 유리합니다. 다만 상태를 조회하거나 외부 도구로 출력할 때는 kubectl get ... -o json처럼 기계 처리를 위한 JSON 출력 모드를 별도로 지원합니다.

YAML 파싱이 JSON보다 빠른가요?

아닙니다. JSON 파싱이 훨씬 빠릅니다. 모든 주요 언어의 JSON 파서는 고도로 최적화되어 있는 반면, YAML은 문법 규칙이 풍부하고 모호하여 파싱 속도가 상대적으로 느립니다. 성능과 처리 속도가 중요한 네트워크 데이터 전송에는 JSON이 훨씬 유리합니다.

JSON을 YAML로 변환하면 데이터가 손실되나요?

일반적으로 손실되지 않습니다. JSON은 기능이 단순한 형식이므로 JSON에서 YAML로의 변환은 거의 무손실로 처리됩니다. 원본 JSON에 없던 주석을 추가할 수는 없지만 데이터 모델 자체는 온전하게 왕복 변환됩니다. JSON to YAML 변환기에서 브라우저를 통해 직접 테스트해 볼 수 있습니다.

YAML에서 country: NO를 썼을 때 false로 바뀌는 이유는 무엇인가요?

널리 알려진 "노르웨이 문제(Norway problem)" 때문입니다. 구형 YAML 파서(YAML 1.1 사양)는 따옴표 없이 쓰인 NO를 불리언 false로 해석합니다. country: "NO"처럼 큰따옴표로 감싸면 해결됩니다. YAML 1.2 사양에서는 이 규칙이 제거되었지만 많은 도구가 여전히 1.1 동작을 기본값으로 사용하고 있습니다.

LLM 프롬프트에 넣을 때 YAML과 JSON 중 어떤 것이 토큰 효율이 더 좋나요?

비교 대상인 JSON의 형식을 어떻게 구성하느냐에 따라 결론이 달라집니다. 본 사이트에서는 32줄의 Kubernetes 설정 스타일 샘플(scripts/benchmarks/yaml-vs-json-tokens/)을 OpenAI의 tiktoken 라이브러리로 실측했습니다.

들여쓰기가 적용된 JSON(json.dumps(data, indent=2))과 비교하면, YAML은 cl100k_base와 o200k_base 인코딩 모두에서 약 22% 토큰을 덜 소비합니다(YAML 218 토큰 vs 들여쓰기 JSON 281 토큰).

그러나 공백과 줄바꿈을 모두 제거한 압축 JSON(json.dumps(data, separators=(",", ":")))과 비교하면 결과가 역전되어 JSON이 약 18~21% 더 적은 토큰을 소비합니다(압축 JSON 180 토큰).

중첩이 깊은 JSON은 {, }, [, ], " 기호 각각을 별도 토큰으로 소비하지만, YAML은 들여쓰기로 계층을 표현하며 닫는 괄호를 쓰지 않습니다. 따라서 JSON이 공백을 제거하면 그 차이가 상쇄됩니다.

실무 구현을 위한 판단 기준은 다음과 같습니다.

1. 공백 없는 압축 JSON을 전달할 수 있는 상황이라면 JSON이 가장 저렴합니다
2. 사람도 함께 검토해야 하는 설정이거나 여러 줄 문자열이 포함된 데이터라면 YAML이 가독성이 높고 전체적으로 경제적입니다
3. 모델에 따라 엄격한 JSON 구조를 지정했을 때 출력이 더 안정적이므로, 2026년 현재 "입력은 YAML로 전달하고 출력은 JSON으로 요구"하는 비대칭 패턴이 널리 사용됩니다

YAML의 주석은 JSON으로 변환해도 유지되나요?

유지되지 않습니다. 주석은 소스 파일 내의 줄 위치에 결합된 텍스트 정보이며, 파서를 거쳐 구조화된 데이터 객체가 되는 순간 버려집니다. JSON으로 변환한 뒤 다시 복원할 수 있는 방법은 없으므로, 설정 설명이나 주석이 필요하다면 원본 YAML 파일을 보관해야 합니다.

관련 글

• JSON 주석처리 방법
• JSON 정렬(Pretty Print) 방법
• JSON YAML 변환 가이드
• 마크다운 프론트매터 YAML을 JSON으로 변환하기
• JSON이란
• YAML이란
• YAML 문법 가이드
• YAML JSON 변환 가이드

정리

• YAML과 JSON은 동일한 데이터 모델을 다루지만 "누가 읽는가"에 따라 최적의 선택이 다릅니다
• 사람이 직접 편집하는 설정 파일에는 YAML을, 시스템과 프로그램 간의 데이터 통신에는 JSON을 권장합니다
• YAML을 JSON으로 변환할 때는 암묵적 타입 추론, 앵커 인라인 전개, 주석 소실에 유의해야 합니다
• FormatArc를 사용하면 브라우저 안에서 안전하게 양방향 변환과 줄 번호 오류 검증을 활용할 수 있습니다