YAML vs JSON

Compare YAML and JSON: syntax, comments, data types, readability and pitfalls like the Norway problem, plus when to use each and how to convert between them.

Two formats for the same data

JSON and YAML both describe structured data: objects (also called maps or dictionaries), lists, strings, numbers, booleans and null. JSON is strict and minimal, designed to be easy for programs to produce and parse. YAML is designed to be easy for people to read and write by hand. Since YAML 1.2, almost every valid JSON document is also valid YAML, so the two are closely related.

The same data side by side

In JSON: {"name": "web", "replicas": 3, "ports": [80, 443], "debug": false}

In YAML, written over several lines: name: web, then replicas: 3, then ports: followed by the indented list items - 80 and - 443, then debug: false. YAML uses indentation and line breaks where JSON uses braces, brackets, commas and quotes.

Key differences

• Comments: YAML supports comments starting with #. JSON has none.
• Structure: JSON uses braces and brackets; YAML uses indentation, which must be spaces, never tabs.
• Quotes: JSON requires double quotes on every string and key. YAML usually lets you omit them.
• Multi-line strings: YAML has block styles, | to keep line breaks and > to fold them. JSON needs \n escapes.
• Reuse: YAML anchors (&name) and aliases (*name) let you repeat a block without copying it. JSON has no equivalent.
• Multiple documents: a YAML file can hold several documents separated by ---. A JSON file holds one value.
• Parsing: JSON parsers are fast, small and built into every language. YAML parsers are larger and more complex.

YAML pitfalls to watch for

Implicit types

YAML guesses types from unquoted values. In YAML 1.1, which some popular parsers still follow, yes, no, on and off become booleans. The classic example is a list of country codes where NO, for Norway, turns into false. YAML 1.2 parsers only treat true and false as booleans, but you cannot always control which parser reads your file.

Numbers cause similar surprises. A version like 1.10 becomes the number 1.1, a ZIP code like 01234 may lose its leading zero, and 1e3 becomes 1000. Quote any value that must stay a string: version: "1.10".

Indentation

A single misplaced space can move a key into the wrong object without causing an error. Tabs for indentation are not allowed at all. Use an editor that shows whitespace, and validate files in CI.

Loading untrusted YAML

Some YAML libraries can create arbitrary objects from tags, which is dangerous with untrusted input. Use safe loading functions, such as yaml.safe_load in PyYAML. Deeply nested aliases can also expand into huge structures, an attack known as billion laughs, so limits on alias expansion matter.

YAML syntax quick reference

• key: value creates a field. A space after the colon is required.
• A line starting with - inside an indented block is a list item.
• [a, b] and {x: 1} are inline (flow) forms, which look like JSON.
• # starts a comment that runs to the end of the line.
• ~ or null means null; true and false are booleans.
• Quotes are optional for most strings, but single or double quotes make the type explicit.
• --- starts a new document, and ... can end one.

JSON pitfalls to watch for

• No comments, so configuration files cannot explain themselves.
• Trailing commas and single quotes are syntax errors.
• Large files are hard to edit by hand because of nested brackets.
• Very large integers may lose precision in JavaScript-based parsers.

When to use each

Use JSON for machine-to-machine data: REST and GraphQL APIs, browser storage, logs, data exports and anything generated by code. Its strictness is a strength there, because there is only one way to read a file.

Use YAML for configuration that people write and review: Kubernetes manifests, GitHub Actions and GitLab CI workflows, Docker Compose files, Ansible playbooks and many application settings. Comments, less punctuation and multi-line strings make these files easier to maintain.

When a tool accepts both, such as OpenAPI specifications, choose based on who edits the file. Teams that generate specs from code often use JSON; teams that hand-write them often prefer YAML.

How to convert YAML to JSON

1. Open YAML to JSON.
2. Paste your YAML.
3. Choose 2 spaces, 4 spaces or tabs for the JSON indentation.
4. Copy or download the .json result.

If the YAML is invalid, the tool reports the line and column of the first error. A file with several documents separated by --- becomes a JSON array with one item per document. Comments are dropped, because JSON cannot hold them, and anchors and aliases are expanded into full copies. The converter follows YAML 1.2, so no stays the string "no" and an unquoted date such as 2026-01-01 stays a string.

How to convert JSON to YAML

Paste valid JSON into JSON to YAML and choose 2 or 4 spaces of indentation. The output is YAML 1.2. Strings that would be read as numbers or booleans, such as "123" or "true", are quoted automatically. Words like yes, no, on and off are not quoted because they are plain strings in YAML 1.2; if the file will be read by a YAML 1.1 parser, add quotes to them by hand.

A practical workflow

Write configuration in YAML with comments, keep it in version control, and validate it in CI. When something behaves unexpectedly, convert it to JSON to see exactly what types and structure the parser produced; hidden booleans and numbers become obvious. For JSON you receive from APIs, a formatter and validator make it readable and point to syntax errors.