JSON vs YAML

JSONStrict, explicit, machine-firstYAMLReadable, forgiving, human-first

Short answer

Use JSON for data moving between programs — APIs, storage, anything parsed more often than it is read. Use YAML for configuration a person edits by hand, where comments and readability genuinely matter. YAML's type inference is its main hazard, so quote anything that could be mistaken for a number, a boolean or a date.

Side by side

	JSON	YAML
Comments	Not supported	Supported with #
Type inference	None — types are explicit	Yes, and it causes real bugs
Syntax weight	Braces, brackets, quotes, commas	Indentation only
Whitespace significant	No	Yes — tabs are invalid
Trailing commas	Invalid, a common error	Not applicable
Multi-line strings	Escaped \n only	Block scalars with \| and >
References and reuse	No	Yes, via anchors and aliases
Parser complexity	Small and predictable	Large — a much bigger attack surface
Best for	APIs, data interchange, storage	Config files, CI pipelines, manifests

When to use each

Use JSON when…

API request and response bodies, data written and read by programs, anything stored at scale, and any context where an unambiguous parse matters more than a comfortable edit.

Use YAML when…

Configuration humans maintain — CI pipelines, Kubernetes manifests, application config. The ability to comment a setting and explain why it exists is worth a great deal in a file people return to.

Comments are the reason YAML won configuration

JSON has no comment syntax. That was deliberate — comments invite parsers to disagree — but it makes JSON genuinely poor for configuration, because a config file's most valuable content is often the explanation of why a setting has an unusual value.

The workarounds are all bad: a fake "_comment" key, a separate README that drifts out of date, or a build step that strips comments before parsing. None survives contact with a real team.

YAML supports comments natively, and that single capability explains most of its adoption for CI pipelines, container orchestration and application config.

Type inference is YAML's real cost

YAML tries to work out what you meant from an unquoted value, and the guesses cause a well-documented category of bug. The famous case is the Norway problem: in a list of country codes, an unquoted NO is read as the boolean false, and Norway silently disappears.

It goes beyond booleans. version: 1.2 parses as a number and loses a trailing zero, so 1.10 becomes 1.1 — a different version. A value like 0755 may be read as octal. A time such as 09:30 can be interpreted as a number in older parsers.

JSON has none of this, because every string is explicitly quoted and a number is unambiguously a number. That verbosity is exactly what makes JSON safe. The mitigation in YAML is to quote anything that could be read as something else, and quoting is never wrong even where it is unnecessary.

JSON is valid YAML

YAML is a superset of JSON, so any YAML parser accepts JSON input. That is genuinely useful: a tool that asks for YAML will take JSON you already have, and you can move incrementally rather than converting everything at once.

The reverse is not true, so YAML must be converted before a JSON parser will read it.

There is also a security dimension worth knowing. YAML's specification is far larger than JSON's, and some language bindings historically allowed a document to instantiate arbitrary objects — the reason Python's yaml.safe_load exists as a distinct function. Never parse untrusted YAML with a full-featured loader.

Frequently asked questions

Why does YAML forbid tabs?

Because a tab's visual width varies between editors, so tab-indented YAML would nest differently depending on who opened it. Requiring spaces makes the structure unambiguous. This is the most common cause of a YAML file that looks correct but will not parse.

Is YAML slower to parse than JSON?

Yes, typically several times slower, because the grammar is far more complex. It rarely matters for a config file read once at startup, and it matters a great deal for data parsed on every request — which is part of why APIs standardised on JSON.

What about TOML?

TOML aims for YAML's readability with JSON's lack of ambiguity: comments are supported, types are explicit, and indentation is not significant. It is excellent for flat-to-moderate configuration and gets unwieldy for deeply nested structures, which is why Rust and Python packaging adopted it while Kubernetes did not.

Can I use comments in JSON if my parser allows it?

Some parsers accept JSON with comments, often called JSONC, and editors such as VS Code use it for their own config. It is not standard JSON, so a file relying on it will fail in any strict parser — fine for a local config, risky for anything shared.

Try the YAML to JSON Converter

Convert YAML into JSON or JSON back into YAML, covering nested maps, lists, quoted strings and comments.

Open tool

More comparisons