JSON vs YAML — how to choose when they're almost one format

Let's start with a fact that defuses half the argument: YAML is formally a superset of JSON. Take a valid JSON file, feed it to a YAML parser — it reads it. So choosing "JSON or YAML" isn't picking between warring camps. It's deciding who will read the file more often: a program or a human.

Here's the same data in both formats:

{
  "name": "kodiq-app",
  "port": 3000,
  "features": ["feed", "lessons"]
}

name: kodiq-app
port: 3000
features:
  - feed
  - lessons

Identical meaning. The differences are in character. Let's go through the criteria that actually affect your life.

The table: what matters to a beginner

| Criterion | JSON | YAML | |---|---|---| | Comments | ❌ none at all | ✅ # like this | | Strictness | ✅ rigid, no surprises | ⚠️ lenient, has surprises | | Errors | Loud: the file won't parse | Sneaky: it parses, but wrong | | Indentation-sensitive | No (indentation is decoration) | Yes (indentation is syntax) | | Who usually writes it | A program | A human | | Where you meet it | APIs, data exchange, AI responses | Configs: CI/CD, docker-compose | | Noise in the notation | Braces, quotes, commas | Nearly plain text |

Two rows deserve a closer look.

Comments — the main practical argument. In a config you constantly need to explain: "don't touch until release," "the key lives in .env." JSON can't do this at all — the format has no comment syntax. For a settings file that's disqualifying, and it's exactly why the config world settled on YAML.

Error style — the main trap. Make a mistake in JSON and the parser refuses the whole file, so you find out immediately (the familiar "Unexpected token" parse error is exactly that). Make a mistake in YAML and the file most likely still parses — just not with the meaning you intended: a drifted indent quietly moved a setting into another section, a bare no became false. JSON fails loudly, YAML errs silently — and a silent error always costs more.

Who should pick what

A plain verdict, no fence-sitting:

• Data exchanged between programs — JSON. APIs respond in JSON, structured output from models is requested in JSON, data is stored and shipped as JSON. Strictness is a virtue here: zero ambiguity.
• Settings files edited by humans — YAML. Comments, no syntactic noise, easy on the eyes. The price is indentation discipline and quotes around "surprise-prone" strings.
• You choose less often than you think. GitHub Actions demands YAML, package.json is JSON, an API answers with whatever it answers. The real skill isn't "picking the right format" — it's reading both confidently. And as the example above shows, that's one skill, not two.

A small trick at the seam: when a YAML file misbehaves and you can't see why — ask AI to translate it to JSON. The translation instantly exposes the structure: you see exactly what's nested where.

What about TOML and other formats?

There's a third notable format — TOML (pyproject.toml in Python, Cargo.toml in Rust): designed as "a config without YAML's surprises." If you meet it, don't worry: same "key = value" idea, readable at a glance. Outside its ecosystems it's rare though — for a beginner, JSON and YAML come first.

Can I convert one to the other?

Yes, both ways and losslessly for typical cases — they share the same data structure (values, lists, nested objects). Any AI assistant does it on request ("convert to YAML/JSON") — handy for seeing a file "through the other lens."

Why does AI answer in JSON rather than YAML?

Because a model's response is read by a program, not a human — and for programs JSON is safer: strict syntax is easier to validate, and a broken response fails loudly at parse time. YAML's silent errors would be a liability there.