JSON vs YAML — 문법 차이와 변환할 때 주의점

API 응답은 JSON인데 배포 설정은 YAML이고, 같은 내용 같은데 생김새만 다릅니다. 실제로 두 형식은 같은 데이터 구조를 다른 문법으로 적은 것입니다. 차이가 무엇이고 언제 뭘 쓰는지, 서로 바꿀 때 뭘 조심해야 하는지 정리합니다.

같은 데이터, 다른 문법

아래 두 코드는 완전히 같은 내용입니다.

// JSON
{ "name": "도구상자", "free": true, "tools": ["QR", "PDF"] }

# YAML
name: 도구상자
free: true
tools:
  - QR
  - PDF

JSON은 중괄호·대괄호·따옴표로 구조를 만들고, YAML은 들여쓰기와 하이픈으로 만듭니다. 그래서 JSON은 기계가 다루기 좋고, YAML은 사람이 읽고 쓰기 좋습니다.

핵심 차이 4가지

• 따옴표 — JSON은 키·문자열 모두 큰따옴표 필수. YAML은 대부분 생략 가능합니다.
• 구조 표현 — JSON은 괄호, YAML은 들여쓰기(공백만 허용, 탭 금지)로 단계를 나타냅니다.
• 주석 — YAML은 # 주석을 지원하지만 JSON 표준에는 주석이 없습니다. 설정 파일에 YAML이 많이 쓰이는 큰 이유입니다.
• 엄격함 — JSON은 마지막 쉼표 하나에도 에러를 내는 엄격한 문법이라 기계 간 교환에 안전하고, YAML은 느슨해서 손으로 쓰기 편한 대신 모호한 해석의 여지가 있습니다.

언제 뭘 쓰나

• JSON — API 요청·응답, 프로그램 간 데이터 교환, 자바스크립트와의 연동. 사실상 웹 데이터의 표준입니다.
• YAML — 도커 컴포즈, 쿠버네티스, 깃허브 액션, CI 설정 등 사람이 직접 작성·수정하는 설정 파일의 표준입니다.
• 선택권이 있다면: 기계가 만들고 기계가 읽으면 JSON, 사람이 자주 열어 고치면 YAML이 무난합니다.

변환할 때 빠지기 쉬운 함정

• 탭 들여쓰기 — YAML은 공백만 허용합니다. 알 수 없는 문법 에러의 단골 원인이 탭입니다.
• 따옴표 없는 값의 해석 — YAML에서 country: no는 문자열 "no"가 아니라 false로 해석될 수 있습니다(노르웨이 국가코드 문제로 유명). 3.10이 숫자 3.1로 바뀌는 것도 같은 부류입니다. 헷갈리는 값은 따옴표로 감싸세요.
• 주석 소실 — YAML → JSON 변환에서 # 주석은 사라집니다. 필요한 설명은 변환 전에 따로 보관하세요.
• 검증은 변환기로 — 변환기에 넣어 보는 것 자체가 문법 검사가 됩니다. 에러 줄 번호를 알려 주니 디버깅에도 유용합니다.