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 · · Updated · 8 min read

Illustration for the JSON to YAML Converter guide

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

FeatureJSONYAML
CommentsNoYes (#)
StructureBrackets and bracesIndentation (spaces only)
Quotes on stringsAlways requiredUsually optional
Multi-line stringsEscaped \n onlyBlock scalars `
Reusing valuesNoAnchors and aliases (&, *)
Multiple documents per fileNoYes (---)
Parsing speedVery fastSlower
AmbiguityAlmost noneSome, 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: under YAML 1.1 rules the unquoted country code NO becomes false, under both YAML 1.1 and 1.2 version 1.10 becomes the number 1.1, and quoting keeps every value a string
The Norway problem: under YAML 1.1 rules the unquoted country code NO becomes false, under both YAML 1.1 and 1.2 version 1.10 becomes the number 1.1, and quoting keeps every value a string

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.10 becomes the float 1.1.
  • zip: 01234 may be read as an octal number in YAML 1.1, or lose its leading zero.
  • port: 22:22 was 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, true and false as 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 NO into false, the JSON will say false.

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

  1. Values like yes, no, on, off and country codes are quoted.
  2. Version numbers and codes with leading zeros are strings.
  3. Indentation uses spaces only.
  4. Comments you needed have been preserved somewhere.
  5. Validate the result with the tool that will read it, for example kubectl apply --dry-run=client.

Related tools

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

Open the JSON to YAML Converter

More Data Conversion

Every tool in the Data Conversion section, free and in your browser.