← Back to blog

JSON vs YAML — when to use which

JSON and YAML can encode the same data structures. That is why people often treat them as interchangeable formats and pick one out of habit. They are not interchangeable. They were designed for different audiences, and each is genuinely better at one half of the work.

The short answer

• Machines talking to machines → JSON. APIs, message queues, log lines, data interchange, anything generated programmatically.
• Humans editing config → YAML. Kubernetes manifests, CI pipelines, Ansible playbooks, application config files that a person opens in a text editor.

Why JSON wins for machine-to-machine

JSON has a strict grammar with six value types — object, array, string, number, boolean, null — and that is the entire spec. Every programming language has a parser in the standard library. Output produced by Python is byte-identical to output produced by Go for the same structure, modulo key ordering. The lack of expressiveness is the feature: there is nothing ambiguous to interpret.

It is also the format the web speaks. application/json is the default content type for REST APIs, GraphQL responses, and browser fetch calls. If your data crosses a network boundary, the cheapest path is JSON.

Why YAML wins for human-edited config

YAML adds three things JSON deliberately omits:

• Comments. A configuration file without comments is a configuration file that gets misused six months later. YAML has # comments; JSON does not.
• Multi-line strings. Pasting a TLS certificate or an SSH key into JSON requires escaping every newline as \n. YAML preserves them with block scalars (| and >).
• Indentation-based structure. Brackets disappear, anchors and aliases let you share repeated values without duplication, and diffs read more like the document the author wrote.

What goes wrong with each

JSON's most common foot-gun is the trailing comma. [1, 2, 3,] is valid JavaScript and invalid JSON. The other classic is single-quoted strings — JSON requires double quotes, and copy-pasting from a Python repr almost always produces invalid output.

YAML's problem is its tolerance. country: NO parses to a booleanfalse in YAML 1.1 because NO is a truthy literal. The stringversion: 1.0 may parse as a number, not a string. These bugs are old, well documented, and still surprise people. YAML 1.2 fixes most of them, but plenty of production parsers still use 1.1.

How RenderHub fits

The JSON tool validates, formats, and minifies — the three operations you actually want when an API request is failing because of malformed JSON. The YAML tool renders the parsed document so you can see how the parser interprets it, which is the fastest way to catch the boolean-NO class of bugs before you ship the config.

JSON과 YAML, 언제 무엇을 써야 할까

JSON과 YAML은 같은 데이터 구조를 표현할 수 있습니다. 그래서 많은 사람들이 둘을 같은 종류로 취급하고, 그냥 익숙한 쪽을 골라서 씁니다. 하지만 두 포맷은 같은 종류가 아닙니다. 서로 다른 독자를 위해 만들어졌고, 각자가 잘 해내는 영역이 분명히 다릅니다.

결론부터

• 기계 ↔ 기계: JSON. API, 메시지 큐, 로그, 데이터 교환 등 프로그램이 생성하는 모든 출력.
• 사람이 직접 편집하는 설정: YAML. 쿠버네티스 매니페스트, CI 파이프라인, 앤서블 플레이북, 애플리케이션 설정 파일처럼 사람이 텍스트 에디터에서 여는 것들.

왜 기계 통신에는 JSON인가

JSON은 객체, 배열, 문자열, 숫자, 불리언, null 여섯 가지 타입과 엄격한 문법이 전부입니다. 거의 모든 언어가 표준 라이브러리에 파서를 가지고 있고, 파이썬이 만든 출력과 Go가 만든 출력이 키 순서를 제외하면 바이트 단위로 같습니다. 표현력이 부족한 것이 오히려 장점입니다 — 해석에 모호함이 없습니다.

또한 웹은 JSON으로 말합니다. REST API, GraphQL 응답, 브라우저의 fetch 호출 모두 기본 콘텐츠 타입이 application/json입니다. 데이터가 네트워크를 건너간다면 가장 저렴한 길은 JSON입니다.

왜 사람이 쓰는 설정에는 YAML인가

YAML은 JSON이 일부러 빼놓은 세 가지를 더합니다.

• 주석. 주석이 없는 설정 파일은 반년만 지나면 잘못 쓰입니다. YAML은 # 주석을 지원하지만 JSON은 지원하지 않습니다.
• 여러 줄 문자열. TLS 인증서나 SSH 키를 JSON에 넣으려면 모든 줄바꿈을 \n으로 이스케이프해야 합니다. YAML은 |와 > 블록 스칼라로 줄바꿈을 그대로 보존합니다.
• 들여쓰기 기반 구조. 괄호가 사라지고, 앵커와 별칭(&, *)으로 반복값을 공유할 수 있으며, diff가 작성자가 쓴 문서와 더 비슷하게 읽힙니다.

각자의 함정

JSON의 가장 흔한 함정은 후행 콤마입니다. [1, 2, 3,]은 자바스크립트로는 유효하지만 JSON으로는 무효합니다. 또 하나의 고전은 작은따옴표 — JSON 문자열은 큰따옴표만 허용되어서, 파이썬 repr 출력을 그대로 붙여 넣으면 거의 항상 무효 JSON이 됩니다.

YAML의 문제는 너무 관대한 점입니다. country: NO는 YAML 1.1에서 노르웨이가 아니라 불리언 false로 파싱됩니다. NO가 거짓 리터럴이기 때문이죠. version: 1.0도 문자열이 아니라 숫자로 파싱될 수 있습니다. 이런 버그는 오래 전부터 잘 알려져 있지만 아직도 사람들을 놀라게 합니다. YAML 1.2가 대부분을 고쳤지만, 프로덕션의 많은 파서가 여전히 1.1을 씁니다.

RenderHub와의 연결

JSON 도구는 검증, 포맷, 압축을 제공합니다 — API 요청이 잘못된 JSON 때문에 실패하고 있을 때 실제로 원하는 세 가지 동작입니다. YAML 도구는 파싱 결과를 시각적으로 보여줘서 파서가 문서를 어떻게 해석하는지 확인할 수 있게 합니다. 위에서 말한 "불리언 NO" 류의 버그를 배포 전에 잡는 가장 빠른 방법입니다.