JSON vs YAML: 설정 파일엔 무엇이 더 나을까
JSON과 YAML은 둘 다 구조화된 데이터를 표현하지만, 실무에서는 쓰임새와 실패 패턴이 꽤 다릅니다. 어떤 형식이 “더 좋다”기보다, 사람이 자주 수정하는지, 자동 생성하는지, 문법 오류를 얼마나 쉽게 잡아야 하는지에 따라 선택이 달라집니다.
1) JSON의 장점
JSON은 문법이 단순하고 엄격합니다. 큰따옴표, 쉼표, 괄호 규칙만 지키면 되기 때문에 파서 동작이 예측 가능하고, 많은 언어에서 기본 지원이 좋습니다. API 응답, 로그 구조, 기계 간 데이터 교환에는 여전히 JSON이 가장 안정적입니다.
2) YAML의 장점
YAML은 사람이 읽고 쓰기 편하게 설계되어 있습니다. 따옴표를 생략할 수 있고, 들여쓰기로 구조를 표현하며, 주석도 넣을 수 있어 설정 파일에 자주 사용됩니다. 그래서 Docker Compose, GitHub Actions, Kubernetes 매니페스트처럼 운영 설정에 많이 쓰입니다.
3) YAML이 더 자주 깨지는 이유
YAML은 유연한 대신 함정도 많습니다. 스페이스 들여쓰기 하나만 달라도 구조가 달라질 수 있고, 값이 문자열인지 불리언인지 자동 해석되는 경우도 있습니다. 예를 들어 yes, on, off 같은 값이 의도와 다르게 파싱될 수 있습니다. 사람 친화적이지만, 디버깅은 오히려 더 어려운 편입니다.
4) JSON이 불편한 이유
JSON은 사람이 직접 길게 편집하기에는 다소 번거롭습니다. 모든 키에 큰따옴표가 필요하고, 주석을 허용하지 않으며, trailing comma도 불가능합니다. 문법은 단순하지만 설명을 덧붙이거나 수동 유지 보수를 하기엔 답답할 수 있습니다.
5) 어떤 상황에서 무엇을 쓰나
- 기계 간 교환, API 응답, 로그 구조: JSON
- 사람이 자주 읽고 수정하는 운영 설정: YAML
- 자동 생성 뒤 사람이 거의 안 건드리는 설정: JSON도 충분
- 팀원이 직접 매니페스트를 자주 고치는 운영 환경: YAML이 편할 수 있음
핵심은 “누가 주로 수정하느냐”입니다.
6) 변환이 가능해도 의미가 같은가
대부분의 단순 구조는 JSON과 YAML 사이를 쉽게 변환할 수 있습니다. 하지만 YAML의 앵커, 병합 키, 주석 같은 요소는 JSON으로 완전히 옮기기 어렵습니다. 반대로 JSON은 엄격한 타입 표현이 장점이어서 자동 처리에는 더 예측 가능합니다.
7) 실무 실패 사례
Kubernetes 설정에서 들여쓰기 한 칸 차이로 배열 위치가 바뀌어 배포가 실패하는 경우가 흔합니다. 반대로 JSON 설정 파일은 마지막 쉼표 하나 때문에 앱 시작이 막히는 일이 많습니다. 즉 YAML은 구조 실수가, JSON은 문법 실수가 더 잦다고 볼 수 있습니다.
8) 선택 기준
- 사람이 직접 자주 편집하는가
- 주석이 꼭 필요한가
- 자동 생성과 검증 파이프라인이 있는가
- 팀이 문법 실수보다 구조 실수에 더 취약한가
이 질문에 답하면 대부분 선택이 정리됩니다.
9) 체크리스트
- API와 외부 통신에는 JSON을 우선 고려하는가
- 사람이 읽는 설정에는 YAML의 장단점을 이해하고 쓰는가
- YAML 자동 타입 변환과 들여쓰기 오류를 점검하는가
- JSON은 포매터와 검증기로 저장 전 확인하는가
10) 관련 도구
JSON 문법 검증은 JSON Formatter & Validator가 빠르고, 구조 비교와 상호 변환은 JSON ↔ YAML Converter가 유용합니다. 실제 선택은 도구보다 운영 방식에 더 크게 좌우됩니다.