Kubernetes 매니페스트, GitHub Actions 워크플로, docker-compose 파일을 연 적이 있다면, YAML을 사용한 것이다. REST API를 호출하거나 Node.js 프로젝트의 설정 파일을 작성한 적이 있다면, JSON을 사용한 것이다. 둘 다 직렬화 형식이다. 둘 다 같은 종류의 데이터 구조를 설명한다 — 맵, 배열, 문자열, 숫자, 불리언, 널. 그런데 왜 둘이 있는가?
간단한 답: YAML은 인간을 위해 최적화하고, JSON은 기계를 위해 최적화한다. 긴 답은 몇 십 년의 개발 경험, 몇몇 위원회 회의, 그리고 놀라운 수의 엣지 케이스를 포함한다. 함께 살펴보자.
JSON이 잘하는 것
JSON(JavaScript Object Notation)은 2000년대 초에 AJAX 요청을 위한 페이로드 형식으로 대중화되었다. 의도적으로 작았다 — 여섯 가지 값 타입, 코멘트 없음, 트레일링 쉼표 없음, 모호함 없음. 그 엄격함이 네트워크에서의 강점이다:
- 파서가 작고 빠르다.
JSON.parse는 모든 브라우저와 모든 언어 런타임에 포함되어 있다. 생각할 것이 없다. - 오류가 모호하지 않다. JSON이 깨지면, 파서는 정확히 몇 번째 줄과 몇 번째 열인지 알려준다.
- 기계가 의미를 합의한다. 숫자는 숫자이고, 문자열은 문자열이고,
true는true이다. “yes는 불리언인가 문자열인가?” 토론이 없다.
그래서 JSON이 API의 lingua franca이다. 두 서비스가 통신할 때, 가장 적은 놀라움을 가진 형식을 원한다.
YAML이 잘하는 것
YAML(YAML Ain’t Markup Language)은 인간이 작성하는 설정 파일을 위해 설계되었다. JSON의 엄격함 일부를 가독성과 교환했다:
- 중괄호 없음, 대괄호 없음. 구조는 들여쓰기이다.
docker-compose.yml은 목록처럼 위에서 아래로 읽힌다. - 코멘트.
#이 코멘트를 시작한다. JSON에는 코멘트 문법이 없다 — 그리고 코멘트의 부재는 팀이 설정 파일을 위해 JSON에서 YAML로 이동하는 가장 일반적인 이유이다. - 앵커와 참조.
&anchor와*reference는 값을 한 번 정의하고 재사용할 수 있게 해준다. JSON에는 동등한 것이 없다; 복붙해야 한다. - 멀티라인 문자열. 리터럴 블록(
|)과 폴드 블록(>)은 이스케이프 처리 없이 산문과 코드를 처리한다.
그래서 YAML이 인간이 수동으로 읽고 쓰는 곳에서 지배한다: Kubernetes, GitHub Actions, GitLab CI, Ansible 플레이북, docker-compose, CloudFormation, OpenAPI 사양, 그리고 2025년대 AI 에이전트 설정 파일 급증(.github/agents.yml, MCP 서버 매니페스트, 평가 하네스).
비대칭
더러운 비밀: YAML은 JSON 데이터 모델의 상위 집합이다. 유효한 JSON 파일은 모두 YAML로 표현될 수 있지만, 반대는 사실이 아니다. YAML은 JSON이 갖지 못하는 기능을 가지고 있다 — 코멘트, 앵커, 다중 문서 파일, 사용자 정의 태그. 앵커가 있는 YAML을 작성하면, 손실 없이 JSON으로 다시 변환할 수 없다. 앵커가 사라진다.
이것은 도구 측면에서 중요하다. &defaults *defaults가 있는 YAML 파일이 있으면, JSON으로 변환하면 참조를 확장(조용히 더 큰 파일을 생성)하거나 삭제(조용히 더 작은 파일을 생성)한다. 코멘트도 마찬가지이다. JSON은 넣을 곳이 없다.
언제 어떤 것을 사용할 때
JSON을 사용할 때:
- 네트워크를 통해 데이터를 보내는 경우 (API, 메시지 큐, 이벤트 페이로드).
- 파일이 인간이 아닌 코드에 의해 읽히는 경우.
- 엄격한 파서에서 모호하지 않은 오류 메시지를 원하는 경우.
- 제한된 장치에서 파싱 속도를 최적화하는 경우.
YAML을 사용할 때:
- 인간이 파일의 주요 작성자이자 독자인 경우.
- 의도를 설명하는 코멘트를 원하는 경우.
- 앵커로 설정 덩어리를 재사용하고 싶은 경우.
- 도메인의 도구가 그것을 기대하는 경우 (Kubernetes, CI 등).
대부분의 팀에 대한 실용적인 답: 네트워크용 JSON, 설정용 YAML, 둘 다 데이터 교환용. 의심이 나면, 정규 버전을 JSON에 저장(손실 없음)하고, 청중이 텍스트 편집기를 여는 개발자인 경우에만 코멘트와 앵커가 있는 YAML을 생성하라.
둘 사이 변환 시 일반적인 함정
- 숫자와 불리언은 YAML에서 자동 타입화된다.
port: 8080은 숫자이다.port: "8080"은 문자열이다. 따옴표를 잊으면 타입이 변경될 수 있다. - 앵커와 코멘트는 JSON에서 삭제된다. 이것에 대한 방법이 없다 — 형식이 넣을 곳이 없다.
- YAML
null은 모호하다.key:(빈 값)는null이다.key: null도null이다.key: ""는 빈 문자열이다. 세 가지 다른 것이다. - 탭은 YAML을 망가뜨린다. 들여쓰기는 반드시 공백이어야 한다. 탭은 오류이다.
- YAML 1.1 vs 1.2 vs 1.2.2. YAML 1.1은
yes,no,on,off를 불리언으로 취급했다. YAML 1.2 (2026년에 js-yaml, PyYAML, 대부분의 파서가 사용하는 사양)는 그렇지 않다. 2025년의 1.2.2 유지보수 릴리즈는 문서 끝 마커와 BOM 처리 주변의 몇 가지 엣지 케이스를 강화했다 — 대부분의 파서가 조용히 수정을 채택했다. 2018년대 코드베이스에서 이동하는 경우, 설정이 여전히 미묘하게 깨질 수 있다.
도움이 되는 도구
둘 사이를 이동할 때 — 그리고 그렇게 할 것이다, 모든 팀이 둘 다 사용하니까 — 빠른 클라이언트 사이드 변환기가 친구이다. DevSpeedTools의 YAML to JSON과 JSON to YAML 도구는 브라우저에서 완전히 실행되므로, 비밀이 포함된 설정 파일은 절대 기계를 떠나지 않는다. DevTools → Network를 열면 데이터를 담은 요청이 영 보이지 않을 것이다.
시간이 지나면서 지저분해진 YAML의 경우, YAML 포맷터가 들여쓰기를 두 공백으로 정규화하고 일관되지 않은 따옴표를 수정한다. 파싱되지 않는 파일의 경우, YAML 검증기가 모든 오류의 정확한 줄과 열을 보여준다.
결론: YAML과 JSON을 경쟁하는 형식으로 대우하는 것을 중단하라. 그것들은 보완적이다. 올바른 형식은 파일을 읽는 사람에 달려 있다 — 기계, 또는 왜 배포가 깨졌는지 파악하려는 오후 11시의 피곤한 개발자.