JSON and YAML are the two most common data serialization formats in modern development. You'll find them in API responses, config files, CI/CD pipelines, Docker Compose, Kubernetes manifests, and package metadata. This guide helps you choose the right one — and avoid the pitfalls of each.
Quick Syntax Comparison
The same data in both formats:
JSON
{
"server": {
"host": "0.0.0.0",
"port": 8080,
"ssl": true,
"allowed_origins": [
"https://example.com",
"https://app.example.com"
]
},
"database": {
"url": "postgres://localhost:5432/mydb",
"pool_size": 10,
"timeout_ms": 5000
}
}
YAML
server:
host: "0.0.0.0"
port: 8080
ssl: true
allowed_origins:
- https://example.com
- https://app.example.com
database:
url: postgres://localhost:5432/mydb
pool_size: 10
timeout_ms: 5000
Same data, different trade-offs. Let's break them down.
JSON: Strengths
- Widely available parsers — Many languages provide JSON support in a standard or third-party library; JavaScript provides JSON.parse().
- Unambiguous syntax — Braces, brackets, quotes, and commas leave no room for interpretation. What you see is exactly what the parser sees.
- Native to JavaScript — JSON is a subset of JavaScript object literal syntax, making it the natural format for web APIs.
- Fast parsing — Simple grammar means fast parsers. Performance depends on parser implementation, input, and configuration; benchmark your workload.
- Widely used in APIs — REST APIs, GraphQL responses, and webhook payloads almost universally use JSON.
JSON: Weaknesses
- No comments — The spec doesn't support comments. You can't annotate config files, which is a real limitation.
- Verbose — Quotes around every key, curly braces, commas — it's noisier than YAML for human-edited files.
- Multiline strings — JSON encodes line breaks inside strings as escaped \n sequences; it has no literal block scalar or string-concatenation syntax.
- Trailing commas forbidden — Adding a new item to the end of an array or object requires editing the previous line too, creating noisy diffs.
YAML: Strengths
- Human-readable — Minimal syntax means config files are clean and scannable. Indentation-based nesting is intuitive.
- Comments supported —
# This is a commentworks anywhere. Essential for configuration files. - Multi-line strings — The
|(literal block) and>(folded block) operators make long strings clean. - Anchors & aliases — Reuse data with
&anchorand*aliasto avoid repetition in large config files. - Multiple documents — A single YAML file can contain multiple documents separated by
---.
YAML: Weaknesses
- Whitespace sensitivity — A single wrong indent can change the data structure silently. Indentation must use spaces; tabs may occur in permitted scalar content.
- Implicit type resolution — YAML 1.1 may interpret yes, no, on, off, and NO as booleans; YAML 1.2 core rules do not. Numeric-looking scalars can still become numbers. Quote values whose exact textual spelling matters and check the parser schema.
- Slower parsing — YAML's richer grammar can increase parsing work; no fixed cross-language speed ratio applies.
- Security concerns — Some YAML parsers support executable tags that can run arbitrary code during parsing. Always use safe-loading functions.
- Multiple valid representations — The same data can be written many different ways, which makes diffs inconsistent.
The Norway Problem: In YAML 1.1, the country code
NO is parsed as boolean false. The string 1.0 becomes a float. Always quote strings that might be ambiguous: "NO", "1.0", "yes".
When to Use JSON
- API request/response bodies — It's the standard. Libraries expect it.
- Data interchange between services — Unambiguous, fast, universally supported.
- Machine-generated config — If the file is written by code, JSON's strictness is a feature.
- Package metadata —
package.json,tsconfig.json,composer.json. - Browser environments — Native
JSON.parse()/JSON.stringify()with zero dependencies.
When to Use YAML
- Human-edited config files — Comments and clean syntax make YAML ideal when humans are the primary editors.
- CI/CD pipelines — GitHub Actions, GitLab CI, CircleCI, and Azure Pipelines all use YAML.
- Container orchestration — Docker Compose commonly uses YAML; Kubernetes accepts JSON as well as YAML manifests.
- Infrastructure as Code — Ansible playbooks use YAML; Terraform configuration normally uses HCL or its JSON representation.
- Documentation/static site configs — Jekyll, Hugo, MkDocs, and similar tools use YAML front matter.
Decision Cheat Sheet
API responses → JSON
Web app config → JSON (or JSONC if comments needed)
CI/CD pipelines → YAML (no choice — tools require it)
Kubernetes manifests → YAML (standard for K8s)
Docker Compose → YAML
Human-edited config → YAML (with quoted strings)
Data exchange → JSON
Database storage → JSON
Build tool config → Depends on tool (check docs)
Converting Between Formats
Need to convert? Use the JSON → YAML Converter to switch between formats instantly in your browser. Paste JSON, get YAML — or vice versa.