Home
Blog
JSON vs YAML: Differences, When to Use Each, and How to Convert

JSON vs YAML: Differences, When to Use Each, and How to Convert

Published 30 October 2026 · 6 min read

JSON and YAML are two ways to write the same kind of data: names with values, lists and nested groups. JSON is what APIs and web apps exchange. YAML is what people edit by hand in configuration files: Docker Compose, Kubernetes, GitHub Actions, OpenAPI specs and many more. Knowing both, and how to move between them, saves a lot of trial and error.

The same data in both formats

Here is a small settings file in JSON:

{
  "name": "devitools",
  "version": "1.10",
  "enabled": true,
  "port": 8080,
  "country": "NO",
  "zip": "007",
  "tags": ["web", "tools"],
  "database": { "host": "localhost", "user": "admin" },
  "note": ""
}

And the same data as YAML, converted with the free JSON to YAML converter:

name: devitools
version: "1.10"
enabled: true
port: 8080
country: "NO"
zip: "007"
tags:
  - web
  - tools
database:
  host: localhost
  user: admin
note: ""

YAML drops the braces, most quotes and the commas, and uses indentation to show what belongs together.

The main differences

Structure: JSON uses braces, brackets and commas; YAML uses indentation and dashes. Indentation matters in YAML, and tabs aren’t allowed for it, only spaces.
Comments: YAML allows comments with #; JSON has no comments at all. That alone is why most config files are YAML.
Readability: YAML is easier for people to read and edit; JSON is easier for programs to produce and check, and harder to get subtly wrong.
Strictness: JSON has one way to write each thing. YAML has many (several string styles, anchors, multi-line text), which is flexible but has surprises.
Compatibility: YAML 1.2 was designed so that valid JSON is also valid YAML, so most YAML tools can read JSON files directly.

When to use which

Use JSON for data that programs send to each other: APIs, web apps, stored data, anything generated automatically.
Use YAML for files people write and maintain: configuration, deployment and CI files, documentation front matter, especially when comments help.
Follow the tool: if a program expects one format, use that one. Kubernetes and GitHub Actions examples are YAML; npm’s package.json is JSON.

The YAML traps that break configs

YAML guesses the type of unquoted values, and older YAML 1.1 readers, still common, guess aggressively:

country: NO      # read as false by many YAML readers
version: 1.10    # read as the number 1.1
zip: 007         # may lose its zeros

This is known as the “Norway problem”, because the country code for Norway turns into false. Words like yes, no, on and off, version numbers and values with leading zeros are all at risk. The fix is simple: quote them. The JSON to YAML converter does this automatically. In the example above, "NO", "1.10", "007" and the empty note stay quoted, while real true/false values and numbers like 8080 are written as they are.

How to convert JSON to YAML, step by step

Open JSON to YAML and paste your JSON into JSON input, click Open file, or drop a .json file onto the box. Sample loads an example.
Choose the Indentation: 2 spaces (the most common, used in Kubernetes and GitHub Actions examples) or 4 spaces.
Click Convert to YAML, then Copy or Download the result.

If the JSON has a mistake, the converter shows the exact line and column. See how to format and validate JSON for the usual culprits. After converting, you can add # comments to the YAML to explain your settings.

More JSON tools

JSON Formatter: make JSON readable and find errors.
JSON to CSV and JSON to XML: other formats for spreadsheets and older systems. See also how to convert JSON to CSV.

Is my JSON uploaded?

No. The conversion runs in your browser, so your data never leaves your device. Our server only records that one conversion happened, for the daily limit.

Frequently asked questions

Is YAML a superset of JSON?

Almost. YAML 1.2 was designed so that JSON documents are valid YAML, and in practice YAML tools read ordinary JSON files without changes.

Can I convert YAML back to JSON here?

Not yet. This tool converts from JSON to YAML only.

Why are some values in quotes in the YAML?

Because without quotes YAML could read them as something else: NO as false, 1.10 as 1.1, 007 as 7. The quotes keep them exactly as they were in the JSON.

← All articles