YAML and JSON are both human-readable data serialisation formats — but they're used in very different contexts, and they have different strengths. Knowing when to reach for each one (and how to convert between them) saves time and avoids subtle bugs.
What Is JSON?
JSON (JavaScript Object Notation) is the lingua franca of web APIs. It's strict, unambiguous, and universally supported:
``json
{
"name": "Alice",
"age": 30,
"active": true,
"roles": ["admin", "editor"],
"address": {
"city": "London",
"postcode": "EC1A 1BB"
}
}
`
JSON's rules are tight:
- Keys must be quoted strings
- Trailing commas are not allowed
- No comments
- Numbers, strings, booleans, arrays, objects, and null are the only types
That strictness is a feature — it means every JSON parser produces the same result.
What Is YAML?
YAML (YAML Ain't Markup Language) is a superset of JSON designed for human-written configuration files. The same data in YAML:
<code>yaml
<p>name: Alice</p>
<p>age: 30</p>
<p>active: true</p>
<p>roles:</p>
<p>- admin</p>
<p>- editor</p>
<p>address:</p>
<p>city: London</p>
<p>postcode: EC1A 1BB</p>
</code>
YAML is more compact for nested data, supports comments, and is easier to read in complex config files. It's the default format for Docker Compose, Kubernetes manifests, GitHub Actions, Ansible, and most CI/CD pipelines.
Key Differences
| Feature | JSON | YAML |
|---|---|---|
| Comments | ❌ Not supported | ✅ # comments |
| Trailing commas | ❌ Invalid | ✅ Not applicable |
| Multiline strings | Awkward (\n) | ✅ Block scalars (|, >) |
| Type coercion | Explicit | Implicit (can cause bugs) |
| Parser availability | Universal | Most languages |
| File size | Slightly larger | Often smaller |
| Human readability | Moderate | High |
When to Use JSON
Use JSON when:
- Data is consumed by APIs — REST APIs use JSON by default; every HTTP client can parse it
- You need strict types — JSON makes no assumptions ("30"
stays a string, 30 stays a number) - The data is generated programmatically — serialisation libraries produce valid JSON without comment support
- You're working in a browser — JSON.parse()
and JSON.stringify() are built-in
When to Use YAML
Use YAML when:
- Humans write and maintain the file — config files, CI pipelines, deployment manifests
- You need comments — annotating production config files is important for team context
- Deeply nested structures — YAML's indentation is cleaner than JSON's brackets at depth
- Multi-line strings — YAML's block scalars (|
for literal, > for folded) are much cleaner
YAML Gotchas to Know
Implicit type coercion is YAML's most common source of bugs.
<code>yaml
<p>version: 1.0 # parsed as float 1.0, not string "1.0"</p>
<p>enabled: yes # parsed as boolean true in YAML 1.1</p>
<p>port: 8080 # parsed as integer</p>
</code>
If you mean a string, quote it explicitly:
<code>yaml
<p>version: "1.0"</p>
<p>flag: "yes"</p>
</code>
Indentation must be consistent. Mixing tabs and spaces causes parse errors. Two-space indent is the conventional standard.
Anchors and aliases — YAML supports reuse with &anchor and *alias, which JSON cannot express:
`yaml
defaults: &defaults
timeout: 30
retries: 3
production:
<<: *defaults
host: prod.example.com
staging:
<<: *defaults
host: staging.example.com
`
Converting Between YAML and JSON
Sometimes you need to convert: an API returns JSON but your deployment tool expects YAML, or you want to pretty-print a YAML config as JSON for debugging.
The rules are straightforward:
JSON is valid YAML — any JSON file is also a valid YAML fileYAML → JSON: strip comments, expand anchors, quote implicit typesJSON → YAML: remove brackets, convert to indented block syntax, add comments as needed
For quick, one-off conversions, the YAML ↔ JSON Converter on SnappyTools converts in both directions instantly in your browser — no library setup needed.
Real-World Example: Docker Compose to JSON
A Docker Compose file (YAML):
<code>yaml
<p>version: "3.8"</p>
<p>services:</p>
<p>web:</p>
<p>image: nginx:alpine</p>
<p>ports:</p>
<p>- "80:80"</p>
<p>volumes:</p>
<p>- ./html:/usr/share/nginx/html</p>
<p>db:</p>
<p>image: postgres:15</p>
<p>environment:</p>
<p>POSTGRES_PASSWORD: secret</p>
</code>
As JSON (for use with the Docker API or tooling that expects JSON):
<code>json
<p>{</p>
<p>"version": "3.8",</p>
<p>"services": {</p>
<p>"web": {</p>
<p>"image": "nginx:alpine",</p>
<p>"ports": ["80:80"],</p>
<p>"volumes": ["./html:/usr/share/nginx/html"]</p>
<p>},</p>
<p>"db": {</p>
<p>"image": "postgres:15",</p>
<p>"environment": {</p>
<p>"POSTGRES_PASSWORD": "secret"</p>
<p>}</p>
<p>}</p>
<p>}</p>
<p>}</p>
</code>`
Summary
- Use JSON for APIs, data serialisation, and programmatically generated data
- Use YAML for config files, CI/CD, and anything humans write and maintain
- Watch out for YAML's implicit type coercion — quote strings when type matters
- Both formats are interchangeable when you need to convert; the structures map 1:1
SnappyTools builds free, fast, browser-based tools for developers — including a YAML ↔ JSON Converter and JSON Schema Validator.
Originally published at https://snappytools.app/yaml-json-converter/</a></em></p>
