JSON vs YAML: Differences, Gotchas and a Free Converter

JSON vs YAML comes down to who reads the file. YAML is built for people: no brackets or quotes needed, and comments allowed, which is why it's used for config files like Docker Compose, Kubernetes and CI pipelines. JSON is built for programs: strict, unambiguous and supported everywhere, which is why APIs use it. Every JSON document is also valid YAML 1.2, so you can move between them easily with the free YAML to JSON converter.

The same config in both

YAML:

# Staging settings
app: everyapp
port: 8080
debug: false
regions:
  - ap-south-1
  - eu-west-2
database:
  host: db.internal
  pool: 10

JSON:

{
  "app": "everyapp",
  "port": 8080,
  "debug": false,
  "regions": ["ap-south-1", "eu-west-2"],
  "database": {
    "host": "db.internal",
    "pool": 10
  }
}

Same data. The YAML has no braces, no quotes and a comment. The JSON shows its structure with punctuation, so indentation doesn't matter to the parser at all.

JSON vs YAML side by side

	JSON	YAML
Structure shown by	Braces, brackets, commas	Indentation
Comments	No	Yes, with #
Quotes on strings	Always required	Usually optional
Multi-line text	\n inside one string	Block styles | and >
Reuse a block	No	Anchors and aliases (&base, *base)
Several documents per file	No	Yes, separated by ---
Types guessed from text	No: "8080" and 8080 are clearly different	Yes: unquoted 8080 is a number
Parsing speed and safety	Simple, fast, predictable	Complex spec; some parsers can run code if misused
Typical use	APIs, data exchange, package.json	Config files, CI, Kubernetes, Ansible

The Norway problem, and other type surprises

YAML's convenience comes from guessing types for unquoted values. That's also its biggest source of bugs.

The famous case: a list of country codes.

countries:
  - GB
  - NO
  - IN

In YAML 1.1 parsers, NO is read as the boolean false (along with yes, no, on, off, y and n in various cases). So Norway vanishes from your list. Many popular libraries, including PyYAML in Python, still follow 1.1 rules by default.

YAML 1.2, the current version, fixed this: only true and false are booleans. Our converter uses a 1.2 parser, so it returns ["GB", "NO", "IN"] correctly. But that also means a file that looks fine in our tool may still break in a 1.1-based program. The safe habit: quote anything that isn't meant to be a number or boolean.

Surprises that even YAML 1.2 produces, which we confirmed in the converter:

You write	You get in JSON	What you probably meant
version: 1.10	1.1	"1.10"
zip: 007	7	"007"
phone: +919876543210	919876543210 (a number)	"+919876543210"
colour: #fff	null (the # starts a comment)	"#fff"
hex: 0x1F	31	depends
id: 12345678901234567890	12345678901234567000 (precision lost)	"12345678901234567890"

JSON avoids all of these because strings are always in quotes. That strictness is exactly why machines prefer it.

Where each one is used

YAML is the norm for:

• Kubernetes manifests and Helm charts
• Docker Compose files
• CI/CD pipelines (GitHub Actions, GitLab CI and others)
• Ansible playbooks
• OpenAPI specs (also allowed as JSON)
• Static-site front matter (the block at the top of many Markdown files)

JSON is the norm for:

• REST APIs and webhooks
• package.json, tsconfig.json (often with comments allowed as an extension), and many tool configs
• Browser storage and logs
• Data passed between services

A rule of thumb: if a human edits it by hand regularly and wants comments, YAML. If a program writes it or reads it from someone else, JSON.

Indentation: YAML's other sharp edge

YAML forbids tabs for indentation and cares about every space. One misaligned line changes the structure or fails to parse. The guide to YAML indentation errors lists the common messages and fixes. JSON doesn't care about whitespace at all; the free JSON formatter can re-indent any valid JSON.

Converting between them

1. Open the free YAML to JSON converter.
2. Choose YAML to JSON or JSON to YAML, and an Indent of 2 or 4 spaces.
3. Paste your data or use Open a file.
4. Copy or Download the result.

What to expect:

• Comments are dropped going to JSON, because JSON has none.
• Anchors and aliases are expanded: the shared block is copied into each place it's used.
• Multiple documents separated by --- become a JSON list, one item per document.
• Going to YAML, strings that would be misread are quoted for you: "1.10" stays "1.10". Values such as yes or on aren't quoted, because they're plain strings in YAML 1.2. If a 1.1-based tool will read the file, quote those yourself.

Converting YAML to JSON is also a handy check: the JSON shows exactly what the parser understood, so a lost leading zero or a surprise null is obvious. To explore a large result, open it in the JSON visualizer. For the third big format, see JSON vs XML.

Convert and check yours

Paste your YAML into the free YAML to JSON converter and read the JSON to see how every value was typed. It runs in your browser, so configs with internal hostnames and settings stay on your device.