YAML vs JSON: Which Configuration Format Should You Use?
YAML and JSON are both widely used for storing configuration and structured data. You'll find JSON in REST API payloads and package manifests, while YAML dominates infrastructure tooling (Kubernetes, Docker Compose, Ansible, GitHub Actions). Understanding their differences will help you choose the right format and work confidently with both.
The Same Data, Two Formats
YAML
server:
host: api.example.com
port: 8080
ssl: true
allowed_origins:
- https://app.example.com
- https://admin.example.com
database:
host: db.internal
name: myapp
# Use env var for password
password: ${DB_PASSWORD}
JSON
{
"server": {
"host": "api.example.com",
"port": 8080,
"ssl": true,
"allowed_origins": [
"https://app.example.com",
"https://admin.example.com"
]
},
"database": {
"host": "db.internal",
"name": "myapp",
"password": "${DB_PASSWORD}"
}
}
The YAML version is noticeably shorter and includes a comment — neither of which is possible in standard JSON.
Key Differences
| Feature | YAML | JSON |
|---|---|---|
| Comments | Yes (#) | No |
| Quotes for strings | Usually optional | Always required |
| Trailing commas | N/A | Not allowed |
| Data types | Auto-inferred | Explicit (quoted = string) |
| Multi-line strings | Native support | Escape sequences only |
| Anchors & aliases | Yes (reuse values) | No |
| Whitespace sensitivity | Yes (indentation matters) | No |
| Parser complexity | High | Low |
| Machine parsing speed | Slower | Faster |
| Superset relationship | JSON is valid YAML (1.2) | — |
YAML Unique Features
Comments
JSON has no comment syntax — a deliberate design choice to keep it a pure data format. YAML supports comments with #, making it much better for hand-maintained config files where you need to explain values.
Multi-line Strings
# Literal block scalar (preserves newlines) description: | This is a long description that spans multiple lines. # Folded block scalar (newlines become spaces) summary: > This text will be folded into one line.
Anchors and Aliases
YAML lets you define a value once and reuse it, reducing repetition in large configs:
defaults: &defaults timeout: 30 retries: 3 production: <<: *defaults # merge defaults host: prod.api.com staging: <<: *defaults # merge defaults host: staging.api.com
Type Inference (and Its Dangers)
YAML automatically infers types from values — which can cause surprising behaviour:
version: 1.0 # parsed as float, not string! enabled: yes # parsed as boolean true country_code: NO # parsed as boolean false in YAML 1.1!
yes, no, on, off, true, false are all booleans. Quote strings that look like booleans: country: "NO". Also, bare numbers like 1.0 are floats — quote version strings: version: "1.0".
When to Choose YAML
- Infrastructure config — Kubernetes manifests, Docker Compose, Helm charts, Ansible playbooks
- CI/CD pipelines — GitHub Actions, GitLab CI, CircleCI
- Config files edited by humans — when comments and readability matter more than parse speed
- Complex nested structures — YAML's indentation-based syntax is easier to scan than deeply nested JSON braces
When to Choose JSON
- API payloads — JSON is the standard for REST APIs and is expected by most HTTP clients
- Machine-to-machine communication — no need for comments, faster parsing, simpler spec
- package.json, tsconfig.json, .eslintrc — JavaScript ecosystem config files use JSON
- NoSQL databases — MongoDB, Firestore, DynamoDB store and query JSON natively
- When data integrity matters — JSON's strict syntax (no type coercion) prevents the boolean/number gotchas that YAML has
Converting Between YAML and JSON
Since YAML 1.2 is a superset of JSON, converting between them is reliable. Use NeatJSON's YAML ⇄ JSON Converter to instantly convert in either direction — paste YAML, get JSON, or paste JSON, get clean YAML.
In code, Python makes this easy:
import yaml, json # JSON to YAML data = json.loads(json_string) yaml_output = yaml.dump(data, default_flow_style=False) # YAML to JSON data = yaml.safe_load(yaml_string) json_output = json.dumps(data, indent=2)
Frequently Asked Questions
Is YAML a superset of JSON?
Yes — in YAML 1.2, valid JSON is also valid YAML. You can parse a JSON file with a YAML parser. The reverse is not true: YAML features like comments and anchors have no JSON equivalent.
Why does Kubernetes use YAML instead of JSON?
Kubernetes supports both, but YAML is default in documentation because it's more readable for complex nested configs, supports comments for explanation, and is less verbose for humans to write. Most kubectl commands will accept JSON too.
Can JSON have comments?
No — standard JSON does not support comments. This was intentional: JSON is a data format, not a config format. If you need comments in JSON-like config, use JSONC (JSON with Comments) supported by VS Code and TypeScript, or switch to YAML.