JSON vs YAML: Which Should You Use for Config Files?
XUtilHub Team ·
If you work with Docker, Kubernetes, GitHub Actions or most modern tools, you'll edit both JSON and YAML. They can represent the same data, but they feel very different, and YAML has a few traps worth knowing.
The same config in both
JSON:
{
"name": "web",
"replicas": 3,
"ports": [80, 443],
"env": { "NODE_ENV": "production" }
}
YAML:
name: web
replicas: 3
ports:
- 80
- 443
env:
NODE_ENV: production
Comparison
| JSON | YAML | |
|---|---|---|
| Structure | Braces and brackets | Indentation |
| Comments | Not allowed | # like this |
| Quotes | Required around strings | Usually optional |
| Readability | Good | Very good for humans |
| Strictness | Strict and predictable | Flexible, with surprises |
| Typical use | APIs, data exchange, package files | Config files, CI pipelines, Kubernetes |
Any valid JSON is also valid YAML 1.2, so YAML parsers can usually read JSON directly.
YAML's common traps
Indentation must use spaces. Tabs are not allowed, and one wrong space changes the structure.
Unquoted values get guessed. In older YAML 1.1 parsers, no, yes, on and off become booleans. The famous "Norway problem": a list of country codes where NO turns into false.
Numbers that aren't numbers. A version like 1.10 becomes the number 1.1, and a phone number with a leading zero may lose it. Quote them.
Colons in values. title: Note: important confuses parsers. Quote the value.
When in doubt, quote strings in YAML.
Which to choose?
- Data sent between programs, APIs: JSON. It's unambiguous and every language parses it.
- Config files humans edit: YAML, because comments and less punctuation help, or a tool's own format if it has one.
- Package files such as package.json and composer.json: follow the ecosystem, which means JSON.
Converting and validating
Convert with JSON to YAML or YAML to JSON, and check your files with the YAML validator before deploying. It catches tab characters and indentation mistakes that would otherwise fail your pipeline.
Tools mentioned in this article
JSON to YAML
Convert JSON to YAML instantly. Clean, readable YAML output for Kubernetes, Docker Compose, CI configs and more.
YAML ValidatorNEW
Validate YAML and find syntax errors with line and column numbers, then reformat it with consistent indentation. Great for Docker Compose, Kubernetes and CI files.
YAML to JSONNEW
Convert YAML to JSON instantly, including multi-document YAML files. Choose pretty-printed or minified JSON output.