Open huge JSON files instantly. Free & private.๐Ÿ”’ Your data never leaves your browser

JSON vs YAML: Differences and When to Use Each

JSON and YAML can describe exactly the same data: objects, lists, strings, numbers, booleans and null. JSON is the language of APIs. YAML is the language of configuration files: Docker Compose, Kubernetes, GitHub Actions and many more. Here is how they differ and when to choose each.

The same data in both formats

{
  "name": "api",
  "version": 2,
  "env": ["dev", "prod"],
  "db": { "host": "localhost", "port": 5432 }
}
name: api
version: 2
env:
  - dev
  - prod
db:
  host: localhost
  port: 5432

YAML uses indentation instead of braces and brackets, and quotes are usually optional.

Try it: JSON โ‡„ YAMLConvert JSON to YAML or YAML to JSON instantly.
Open JSON โ‡„ YAML โ†’

Side-by-side comparison

JSONYAML
StructureBraces and bracketsIndentation (spaces only, no tabs)
CommentsNot allowed# like this
QuotesRequired for keys and stringsUsually optional
Multi-line textEscaped \nBlock styles | and >
Reuse a valueNoAnchors and aliases (&base, *base)
Several documents in one fileNoYes, separated by ---
Parsing speed and safetySimple, fast, built into every languageMore complex; use a safe loader for untrusted input
Best forAPIs, data exchange, machine-written filesHuman-edited configuration

YAML pitfalls to know

1. Unquoted values are guessed

YAML guesses the type of unquoted values, and the guess is sometimes wrong:

version: 3.10      # becomes the number 3.1, not "3.10"
zip: 01234         # may become a number and lose the zero
country: NO        # YAML 1.1 parsers read this as false (the "Norway problem")
time: 12:30        # YAML 1.1 can read this as a number of minutes

The "Norway problem" comes from the older YAML 1.1 rules, where yes, no, on and off are booleans. YAML 1.2 fixed this, but many tools still use 1.1 rules. When in doubt, quote it: country: "NO".

2. Indentation errors are silent

A wrong indent does not always cause an error. Sometimes it just moves a key to a different parent, and the config means something else. Use an editor that shows indentation guides, and never use tabs.

3. JSON is (almost) valid YAML

YAML 1.2 is designed as a superset of JSON, so most JSON files can be read by a YAML parser as they are. This is handy: you can paste JSON into a YAML config when you're in a hurry.

When to use which

  • Use JSON for API requests and responses, data stored or exchanged between programs, and anything generated by code. It is strict, so errors show up early.
  • Use YAML for configuration that people edit by hand, especially when comments help explain settings.
  • Use whatever your tool expects: Kubernetes, Docker Compose and GitHub Actions use YAML, and package.json is JSON.
๐Ÿ’ก A JSON file needs comments? Most of the time the answer is a YAML file, or a JSON file plus a README. Comments inside .json files break standard parsers. See common JSON errors.

Converting between them

Online: JSON โ‡„ YAML converts in both directions with a swap button. In code:

import json, yaml   # pip install pyyaml

data = yaml.safe_load(open("config.yaml"))
print(json.dumps(data, indent=2))

print(yaml.safe_dump(json.load(open("data.json")), sort_keys=False))
import { load, dump } from 'js-yaml'   // npm install js-yaml

const obj = load(yamlText)
const yamlOut = dump(JSON.parse(jsonText))

Note that comments are lost when converting YAML to JSON, because JSON has no place to put them.

Tools used in this guide

More guides