Comparison

JSON vs YAML: Which Format Should You Use for Config, APIs, and DevOps?

JSON and YAML both serialize structured data, but they serve different camps. JSON is the lingua franca of web APIs — every HTTP client on Earth speaks it. YAML is the lingua franca of DevOps — Docker Compose, Kubernetes manifests, Ansible playbooks, and CI pipelines are all written in it. The choice is not 'which is better' but 'which audience am I writing for.'

TL;DR

	JSON	YAML
Comments	Not supported (hack with _comment keys)	Native `#` comments
Syntax	Braces, brackets, commaz and double quotes	Indentation-based (2-space)
Anchors & aliases	No — must repeat values or post-process	Built-in `&anchor` and `*alias` for DRY
Multi-line strings	Only \n escape inside a single string	`\|` (literal) and `>` (folded) block scalars
Primary use	Web APIs, browser<->server, data serialization	Configuration, DevOps, CI/CD
Tooling	JSON.parse is built into every browser and language	Requires a library (PyYAML, js-yaml, Go yaml.v3)

The options in depth

JSON

The universal data-interchange format — every HTTP API consumes it.

JSON is so widely supported that if it needs to be parsed, there's a library for it. REST APIs, GraphQL responses, configuration for tools like ESLint and package.json, and browser localStorage all default to JSON. Its biggest limitation is the lack of comments and multi-line strings — workarounds exist (jsonc, json5, Hjson) but they fragment the ecosystem.

Good for

·Public APIs consumed by arbitrary clients
·Browser-to-server communication
·Data storage where comments don't matter

Avoid when

·Human-maintained config that needs inline documentation
·Files that contain repeated values (look at YAML anchors)
·Multi-line embedded scripts or SQL templates

Try it: JSON Formatter →

YAML

The human-readable config format — DevOps runs on it.

YAML's indentation-based syntax makes it readable without the noise of quotes and brackets. Its killer features are comments (inline documentation), anchors (DRY config), and block scalars (multi-line values without \n). The downside: indentation errors are subtle and hard to debug — a single missing space can silently change the meaning of a Kubernetes manifest.

Good for

·Human-written configuration (Docker, K8s, CI)
·Files maintained by non-developers (ops, data teams)
·DRY configs with repeated values

Avoid when

·Machine-to-machine communication (stick with JSON)
·Performance-sensitive parsing (YAML is 3-5x slower than JSON)
·Untrusted input (YAML unsafe deserialisation can execute code in some languages)

Try it: YAML to JSON →

Which one should you pick?

→ I'm building a REST API — JSON or YAML?

JSON. Every HTTP client supports it out of the box; YAML accept headers are rare and unexpected. If your clients demand YAML, add a Content-Type: application/x-yaml endpoint as an option — but default to JSON for ecosystem compatibility.

→ I'm writing a Kubernetes manifest

YAML. Full stop.

Common pitfalls

⚠YAML's Norway problem — the string 'no' is interpreted as boolean false in old YAML 1.1 parsers. Always quote bare words that could collide with YAML's truthy/falsy set (yes, no, on, off, true, false, null).
⚠JSON doesn't support trailing commaz — a common paste mistake. All JSON tools should auto-strip them or you'll get silent failures in strict parsers.
⚠Mixing tabs and spaces in YAML: a single tab anywhere in indentation makes the file invalid. Most editors auto-convert tabs to spaces for .yml files, but CI pipelines that edit in-place can break this.

Frequently Asked Questions

Can I convert JSON to YAML and back?

Yes — JSON is a valid subset of YAML (since YAML 1.2). Every JSON document is also valid YAML. The reverse is not true: YAML features like anchors, tags, and multiple documents in a stream have no JSON equivalent.

Why does YAML use 2-space indentation?

Convention. YAML accepts any number of spaces, but the entire ecosystem (Docker Compose, Kubernetes, Ansible, Homebrew) standardised on 2-space. Mixing 2 and 4 spaces in the same file causes hard-to-debug errors.

Related comparisons

JSON vs XML

JSON has become the default data interchange format on the web, but XML is far from dead — SOAP, RSS, XHTML, XSLT, and countless enterprise systems still speak XML natively. This guide covers structure, verbosity, tooling, schema, and where each format still wins.