toolsy.one

JSON vs YAML: which should you use, and when?

Two ways to write structured data — and when each one shines.

JSON and YAML describe the same kinds of data: objects, arrays, strings, numbers, booleans and null. In fact, JSON is (almost) a subset of YAML — most JSON is valid YAML. So why do both exist, and which should you reach for? The answer comes down to who or what is going to read the file.

JSON: built for machines

JSON (JavaScript Object Notation) is strict, unambiguous and everywhere. Every browser and language parses it natively, and its rigidity is a feature: there’s exactly one way to write a given structure. That makes it ideal for APIs and data interchange, where two systems must agree precisely on the format. The downside is human ergonomics — all those braces, brackets and double-quotes get noisy, and JSON allows no comments. 

{
  "service": "api",
  "port": 8080,
  "tags": ["web", "public"]
}

YAML: built for humans

YAML uses indentation instead of braces, drops most quotes, and — crucially — allows comments. That’s why it dominates configuration files: CI pipelines, Kubernetes manifests, Docker Compose and countless app configs. The same data as above reads more like prose: 

service: api
port: 8080
tags:
  - web
  - public   # visible to anyone

YAML’s footguns

YAML’s flexibility has sharp edges worth knowing:

  • The “Norway problem.” Older YAML treats no, yes, on, off as booleans — so the country code NO can silently become false. Quote ambiguous strings.
  • Indentation matters. A stray tab or wrong indent changes meaning or breaks the parse. JSON’s braces are immune to this.
  • Numbers vs strings. A version like 1.10 may be read as the number 1.1. Quote it: "1.10".

A simple rule of thumb

Use JSON when a program is the audience (API responses, data you send over the wire, anything generated and consumed by code). Use YAML when a person is the audience (config files you’ll edit by hand and want to annotate). When you receive one and need the other, you don’t have to convert by hand.

Convert between the two instantly with our JSON ⇄ YAML converter, and tidy up messy JSON with the JSON formatter & validator. Both run entirely in your browser, so it’s safe even for config that contains secrets.

Related tools: JSON ⇄ YAML · JSON formatter