YAML vs JSON

The short answer

Use JSON for data that programs exchange: API requests and responses, files that a program writes and another reads, and anything that a browser or a JavaScript program parses. Use YAML for files that people write and read by hand, such as configuration, deployment files and pipelines, where comments and a light syntax matter. Many projects use both: YAML in the repository for people, JSON on the wire for machines.

The same data in both formats

YAML:

# web server config
server:
  host: localhost
  port: 8080
  debug: false
  tags: [api, internal]
database:
  url: postgres://db:5432/app
  pool: 10

JSON:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": false,
    "tags": ["api", "internal"]
  },
  "database": {
    "url": "postgres://db:5432/app",
    "pool": 10
  }
}

The YAML version is shorter, and it carries a comment. The JSON version has no comment, because JSON does not allow comments, and it needs quotes around every key and every string.

Side-by-side comparison

YAML is almost a superset of JSON

YAML 1.2 was designed so that nearly every JSON document is also a valid YAML document. A YAML parser can usually read a JSON file. The reverse is not true: YAML has features that JSON cannot express, such as comments, anchors and several documents in one file. That is why converting YAML to JSON can lose information (see below).

Where each format is used

• YAML: Kubernetes manifests, Docker Compose files, GitHub Actions and GitLab CI pipelines, Ansible playbooks, OpenAPI descriptions, Helm charts and many application config files.
• JSON: REST and GraphQL APIs, package.json, browser storage and messages, most NoSQL document stores, and data files that code generates.

Traps in YAML

• Types that guess. An unquoted value is read as a number, a boolean or a date if it looks like one. Older YAML 1.1 parsers, such as PyYAML, read NO, no, off and y as booleans, which is why the country code for Norway can turn into false. Quote values that must stay text.
• Numbers that lose digits. version: 1.10 is the number 1.1, not the text "1.10". A leading zero, as in 0755, is read by YAML 1.1 parsers as an octal number.
• Indentation is syntax. One wrong space changes the structure, and tabs are not allowed for indentation.
• A colon followed by a space inside an unquoted value ends the key. Quote values that contain : or start with special characters.
• Unsafe loading. Some YAML libraries can create arbitrary objects from tags when you use their default loader. Use the safe loader, such as yaml.safe_load in Python, for any file that you did not write yourself.
• Aliases can be abused. A small file with nested aliases can expand into a huge structure when it is loaded.

country: NO        # a YAML 1.1 parser reads this as false
version: 1.10      # read as the number 1.1
mode: 0755         # a YAML 1.1 parser reads this as octal 493
country: "NO"     # quoted: always the text NO

Traps in JSON

• No comments. Config files in JSON end up with fake keys such as "_comment". Some tools accept JSON with comments (often called JSONC), but it is not standard JSON.
• No trailing commas, and keys and strings must use double quotes. These are the most common syntax errors.
• Large integers. JavaScript reads every number as a double, so integers above 9007199254740991 lose precision. Send big IDs as strings.
• Duplicate keys. The standard does not say what to do. Parsers usually keep the last one and say nothing.
• Hard to read when deeply nested, because of the brackets and quotes.

Check a file with the JSON validator or the YAML validator, which show the line and column of each error.

How to choose

1. Will people edit the file by hand? Choose YAML, or JSON with comments if your tool allows it.
2. Will a program write the file, or will it travel over a network? Choose JSON.
3. Do you need comments? Choose YAML.
4. Do you need a strict format with the same result in every library? Choose JSON.
5. Does the tool you use decide? Kubernetes, Docker Compose and most CI services expect YAML. Browsers, most APIs and npm expect JSON. Follow the tool.

Converting between them

Converting JSON to YAML is lossless, because everything in JSON has a YAML form. Converting YAML to JSON can lose some things:

• Comments are dropped.
• Anchors and aliases are expanded into copies of the values.
• Several documents in one file must become an array or separate files.
• Key order is kept by most tools, but JSON does not promise it.
• Dates and special types become strings or numbers, depending on the tool.

Use the YAML to JSON converter and the JSON to YAML converter. For both directions in one place, with automatic detection, use the JSON YAML converter. Tidy a file with the YAML formatter or the JSON formatter.

On the command line

# YAML to JSON with yq (mikefarah/yq v4)
yq -o=json '.' config.yaml

# JSON to YAML
yq -P '.' config.json

# YAML to JSON with Python (safe loader)
python3 -c "import sys,json,yaml; print(json.dumps(yaml.safe_load(sys.stdin), indent=2))" < config.yaml

Keep reading

• The full syntax comparison, with comments, types and safety in detail: JSON vs YAML guide.
• The rules of YAML itself: YAML syntax guide.
• Other format comparisons: JSON vs XML and CSV vs JSON.