JSON vs YAML: Differences, Gotchas and When to Convert
YAML is a superset of JSON with indentation, comments and a few famous traps. Learn how the two map onto each other and what to check after converting.
By Redbison Dev · · Updated · 8 min read

JSON and YAML describe the same kinds of data: maps, lists, strings, numbers, booleans and null. They are used for different reasons. JSON is the language of APIs; YAML is the language of configuration files, from Kubernetes manifests to GitHub Actions workflows and docker-compose files. Sooner or later you need to move data between them.
This guide explains how the two formats relate, the YAML gotchas that bite teams in production, and what to check after converting. The JSON to YAML Converter handles quick conversions in your browser.
Origins
JSON was described by Douglas Crockford in the early 2000s and standardized as RFC 8259 and ECMA-404. Its design goal was minimalism.
YAML was started in 2001 by Clark Evans, Ingy döt Net and Oren Ben-Kiki. The name first stood for "Yet Another Markup Language", then became the recursive "YAML Ain't Markup Language" to emphasize that it is for data. Its design goal was human readability. YAML 1.2, released in 2009, was explicitly aligned so that every valid JSON document is also valid YAML.
The same data, two ways
{
"service": "api",
"replicas": 3,
"debug": false,
"ports": [80, 443],
"env": { "LOG_LEVEL": "info" }
}
service: api
replicas: 3
debug: false
ports:
- 80
- 443
env:
LOG_LEVEL: info
YAML drops the braces, brackets, commas and most quotes, and uses indentation for structure. It also allows comments with #, which is one of the main reasons people choose it for config.
Feature comparison
| Feature | JSON | YAML |
|---|---|---|
| Comments | No | Yes (#) |
| Structure | Brackets and braces | Indentation (spaces only) |
| Quotes on strings | Always required | Usually optional |
| Multi-line strings | Escaped \n only | Block scalars ` |
| Reusing values | No | Anchors and aliases (&, *) |
| Multiple documents per file | No | Yes (---) |
| Parsing speed | Very fast | Slower |
| Ambiguity | Almost none | Some, see below |
The YAML gotchas
YAML's flexibility comes from guessing types for unquoted values. That guessing is where the trouble starts.
The Norway problem
In YAML 1.1, these unquoted values are all booleans: yes, no, on, off, y, n, true, false, in various capitalizations. So this list of country codes:
countries:
- GB
- FR
- NO
parses as ["GB", "FR", false]. This became known as "the Norway problem". YAML 1.2 restricted booleans to true and false, but many widely used parsers, including PyYAML by default, still follow 1.1 rules. Quote the value: - "NO".
Numbers that are not numbers
version: 1.10becomes the float1.1.zip: 01234may be read as an octal number in YAML 1.1, or lose its leading zero.port: 22:22was historically read as a base-60 number (1342) by YAML 1.1 parsers, which is why docker-compose documentation tells you to quote port mappings.- Long numeric IDs can lose precision.
Indentation
YAML forbids tabs for indentation. A single misaligned space can silently move a key into a different parent object rather than causing an error. Editors with YAML support and a linter such as yamllint catch most of these.
Anchors and merge keys
Anchors (&default) and aliases (*default) let you reuse blocks, and <<: merges one map into another. They are handy, but they do not exist in JSON. Converting YAML that uses them to JSON expands them into duplicated data, and converting back will not recreate them.
Converting JSON to YAML
This direction is safe in principle, since JSON's types are explicit. A good converter will:
- Turn objects into indented maps and arrays into
-lists. - Quote strings that would otherwise be misread, such as
"no","1.10"or strings containing:or#. - Keep
null,trueandfalseas YAML's equivalents.
The RedBison converter uses a YAML library to handle nested objects, arrays, nulls and scalar values, quoting strings that would otherwise be read as another type. After converting, scan for string values that look like booleans or numbers and quote them if your YAML consumer uses 1.1 rules.
Converting YAML to JSON
This direction loses information:
- Comments disappear, because JSON has nowhere to put them.
- Anchors are expanded.
- Multiple documents in one file need to become an array or separate files.
- Type guesses become permanent. If the YAML parser turned
NOintofalse, the JSON will sayfalse.
The RedBison converter uses a YAML 1.2 parser for nested mappings, lists, anchors and multi-line strings. Anchors are expanded, while duplicate keys, cyclic aliases and non-finite numbers produce errors instead of silently losing information. Convert multi-document files one document at a time. For an automated pipeline, use a full parser such as the yaml library in JavaScript or ruamel.yaml in Python.
Which should you use?
- APIs and data exchange: JSON. It is unambiguous, fast and supported everywhere.
- Config written by humans: YAML, if comments and readability matter and you lint it. Some teams prefer TOML, which has explicit types and fewer surprises.
- Config written by programs: JSON. Generating YAML correctly is harder than it looks.
A pattern I have seen work well is to author config in YAML, validate it against a JSON Schema in CI, and convert it to JSON for the runtime. You get comments for humans and strict types for machines.
Checklist after converting
- Values like
yes,no,on,offand country codes are quoted. - Version numbers and codes with leading zeros are strings.
- Indentation uses spaces only.
- Comments you needed have been preserved somewhere.
- Validate the result with the tool that will read it, for example
kubectl apply --dry-run=client.
Related tools
- JSON Formatter to validate the JSON side
- YAML Beautifier to tidy YAML files
- CSV to JSON Converter for spreadsheet data
Frequently asked questions
Should I use JSON or YAML for configuration files?
Use YAML for configuration written by humans, if comments and readability matter and you lint it, and JSON for configuration written by programs, because generating YAML correctly is harder than it looks. JSON is the better choice for APIs and data exchange, since it is unambiguous, fast and supported everywhere. Some teams prefer TOML, which has explicit types.
Why does YAML turn version 1.10 into 1.1?
YAML guesses types for unquoted values, so version: 1.10 is read as the float 1.1. Other values suffer the same way: a zip code like 01234 may be read as octal in YAML 1.1 or lose its leading zero, and long numeric IDs can lose precision. Quote version numbers and codes with leading zeros so they stay strings.
Can YAML use tabs for indentation?
No. YAML forbids tabs for indentation and uses spaces only. A single misaligned space can also silently move a key into a different parent object rather than causing an error. Editors with YAML support and a linter such as yamllint catch most of these indentation mistakes.
What does YAML stand for?
YAML first stood for "Yet Another Markup Language", then became the recursive "YAML Ain't Markup Language" to emphasize that it is for data. It was started in 2001 by Clark Evans, Ingy döt Net and Oren Ben-Kiki with human readability as its design goal, and YAML 1.2, released in 2009, made every valid JSON document valid YAML.
What is lost when converting YAML to JSON?
Converting YAML to JSON loses comments, because JSON has nowhere to put them. Anchors and aliases are expanded into duplicated data and will not be recreated when converting back. Multiple documents in one file must become an array or separate files, and type guesses become permanent, so a NO that the parser read as false stays false.
Sources and further reading
- YAML Ain't Markup Language (YAML) revision 1.2.2, YAML Language Development Team. The current YAML specification, aligned with JSON.
- Boolean Language-Independent Type for YAML Version 1.1, YAML Language Development Team. The YAML 1.1 list of yes, no, on and off booleans.
- RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format, IETF.
- ECMA-404: The JSON data interchange syntax, Ecma International.
- Introducing JSON, Douglas Crockford. The format's original description and grammar.
Open the JSON to YAML Converter
More Data Conversion
Every tool in the Data Conversion section, free and in your browser.
- JSON Formatter
- JSON to TypeScript Generator
- Binary to Text Converter
- XML to JSON Converter
- Markdown to HTML Converter
- HTML to Markdown Converter
- CSV to JSON
- JSON to YAML
- Excel to JSON Converter
- Data Visualization Tool
- JSON Schema Validator & Generator
- TOML Converter
- cURL to Code Converter
- Markdown Table Generator