YAML and JSON are two of the most widely used data serialization formats in modern development. Whether you're writing configuration files, exchanging API data, or managing infrastructure as code, you've likely encountered both. But which one should you use, and what are the practical differences between them?
This guide breaks down the syntax, trade-offs, and real-world use cases for each format so you can make an informed decision.
Syntax Comparison
The most visible difference between YAML and JSON is how they represent data. Let's look at a practical example: a configuration for a web server.
JSON Version
{
"server": {
"host": "localhost",
"port": 8080,
"ssl_enabled": true,
"timeout": 30,
"allowed_methods": ["GET", "POST", "PUT"],
"database": {
"url": "postgresql://db.example.com",
"pool_size": 10
}
}
}
YAML Version
server:
host: localhost
port: 8080
ssl_enabled: true
timeout: 30
allowed_methods:
- GET
- POST
- PUT
database:
url: postgresql://db.example.com
pool_size: 10
Notice that YAML removes the braces, brackets, commas, and quotation marks. It uses indentation (whitespace) to define structure instead. This makes YAML more human-readable at first glance, but it also introduces strict formatting rules.
Key Syntax Differences
Objects and Nesting
JSON uses curly braces and requires colons and commas:
{
"name": "Alice",
"age": 30,
"city": "New York"
}
YAML uses indentation:
name: Alice
age: 30
city: New York
Arrays and Lists
JSON uses square brackets:
{
"tools": ["hammer", "screwdriver", "wrench"]
}
YAML uses dashes or flow syntax:
tools:
- hammer
- screwdriver
- wrench
# Or inline (flow syntax)
tools: [hammer, screwdriver, wrench]
Strings and Quotes
JSON requires double quotes for all strings:
{
"message": "Hello World",
"path": "C:\\Users\\example"
}
YAML allows unquoted strings in many cases:
message: Hello World
path: C:\Users\example
YAML only requires quotes when ambiguity could occur (like when a value looks like a boolean or number).
Multiline Strings
YAML has powerful multiline string support that JSON lacks:
# Literal block (preserves newlines)
description: |
This is a multiline string.
Each line is preserved exactly.
Useful for long text content.
# Folded block (folds long lines)
summary: >
This is a long description that spans
multiple lines but will be folded into
a single line when parsed.
JSON requires escaping or string concatenation:
{
"description": "This is a multiline string.\nEach line needs manual escaping.\nNot ideal for long content."
}
Comments
YAML supports comments:
# This is a comment
server:
host: localhost # Server hostname
port: 8080
JSON does not support comments natively. This is a critical limitation for configuration files.
Data Type Support
Both YAML and JSON support the same fundamental data types:
- Strings:
"hello"orhello(YAML) - Numbers:
42,3.14,-17 - Booleans:
true,false,yes,no(YAML accepts more variants) - Null:
null - Objects/Dictionaries: Key-value pairs
- Arrays: Ordered lists
However, YAML is more flexible with boolean representation. It accepts true, false, yes, no, on, off, which can lead to unexpected parsing behavior if you're not careful.
YAML-Specific Features
Anchors and Aliases
YAML supports powerful reference features that JSON lacks:
defaults: &defaults
timeout: 30
retries: 3
log_level: info
production:
<<: *defaults
host: prod.example.com
development:
<<: *defaults
host: localhost
timeout: 5 # Override the default
This allows you to reuse configurations without duplication. JSON has no equivalent mechanism.
Type Inference
YAML automatically infers data types:
string_value: hello # String
number_value: 42 # Integer
decimal_value: 3.14 # Float
boolean_value: true # Boolean
null_value: null # Null
JSON requires explicit type markers (quotes for strings, numbers without quotes).
Parsing Speed and Performance
JSON has a critical advantage in performance. JSON parsers are simple because the format is strict and unambiguous. Every JSON file follows the same rules, making parsing fast and predictable.
YAML parsing is more complex. The whitespace-sensitive syntax and type inference require more sophisticated parsing logic. For large files or high-throughput systems, JSON will parse noticeably faster.
This matters in:
- High-frequency API requests
- Large data files (megabytes or larger)
- Real-time data processing pipelines
For configuration files or occasional use, the difference is negligible.
Strictness and Reliability
JSON is strictly defined by RFC 7159. Every JSON parser must behave identically. This predictability is valuable for APIs and data exchange.
YAML has more ambiguity. Different YAML parsers may handle edge cases differently. For example, some might accept unquoted strings that others reject. This can lead to subtle bugs when configurations work locally but fail in production.
Common Use Cases
When to Use YAML
YAML shines in human-written configuration files:
- Docker Compose: Define multi-container setups
- Kubernetes manifests: Configure cloud infrastructure
- GitHub Actions: Define CI/CD workflows
- Ansible playbooks: Infrastructure automation
- Application config files: Settings and parameters
YAML is chosen here because:
- Humans edit these files directly
- Comments are essential for documentation
- Readability reduces configuration errors
- Complex nested structures benefit from indentation
When to Use JSON
JSON is the standard for machine-to-machine communication:
- REST APIs: Client-server data exchange
- Package managers: npm package.json, Python requirements.json
- Data stores: MongoDB, Elasticsearch
- Configuration in APIs: Accept config as JSON request bodies
- Web standards: JavaScript native format
JSON is chosen here because:
- Machines generate and parse it
- Strict format ensures consistency
- Fast parsing is critical
- Interoperability across languages is essential
Common Pitfalls
YAML Pitfalls
Indentation sensitivity: A single misaligned space breaks parsing.
# Wrong - creates unexpected structure
servers:
- name: web1
port: 8080 # Extra space breaks the array
Unexpected type conversion: Unquoted values can be misinterpreted.
# This is a boolean, not a string
enabled: yes
# This is a number, not a string
version: 1.0
# Quote to force strings
version: "1.0"
Ambiguous multiline strings: Different block styles behave differently.
# | preserves newlines
# > folds newlines
# - and + control trailing newlines
JSON Pitfalls
No comments: You must use workarounds or separate documentation.
{
"_comment": "This is a comment workaround",
"actual_key": "actual_value"
}
No trailing commas: This is a common source of errors.
{
"key1": "value1",
"key2": "value2", // ERROR: trailing comma not allowed
}
Escaping requirements: Special characters must be escaped.
{
"path": "C:\\Users\\example",
"json_string": "{\"nested\": \"value\"}"
}
Converting Between Formats
If you need to convert between YAML and JSON, several approaches exist:
Command-line tools:
# YAML to JSON
yq -o=json eval config.yaml
# JSON to YAML
yq -P config.json
Python:
import json
import yaml
# JSON to YAML
with open('data.json') as f:
data = json.load(f)
with open('data.yaml', 'w') as f:
yaml.dump(data, f)
# YAML to JSON
with open('data.yaml') as f:
data = yaml.safe_load(f)
with open('data.json', 'w') as f:
json.dump(data, f)
Making the Choice
Ask yourself these questions:
- Who writes this file? Humans prefer YAML's readability. Machines prefer JSON's strictness.
- Do you need comments? YAML supports them; JSON doesn't.
- Is parsing speed critical? Choose JSON for high-throughput systems.
- Do you need advanced features? YAML offers anchors and aliases; JSON is simpler.
- What's the industry standard? Use what your ecosystem expects (Docker uses YAML, REST APIs use JSON).
Conclusion
YAML and JSON serve different purposes. YAML is a developer-friendly format for configuration files, while JSON is the standard for APIs and data exchange. Understanding the trade-offs helps you choose the right tool for your use case.
For most applications, you'll use both: YAML for configuration, JSON for APIs. Neither is universally "better"—they're optimized for different problems.
The best format is the one that fits your workflow and integrates well with your existing tools. When in doubt, follow what your framework or platform recommends.