Back to guides

JSON vs YAML: What's the Difference?

How JSON and YAML compare on syntax, readability, and use case — and what actually happens to comments and structure when you convert between them.

The same data, both ways

JSON:

{
  "service": "api",
  "replicas": 3,
  "env": ["staging", "production"]
}

The same thing in YAML:

service: api
replicas: 3
env:
  - staging
  - production

No braces, no brackets, no quotes on the simple values — YAML uses indentation and line breaks to express the structure that JSON expresses with punctuation.

Key differences

  • Comments — YAML supports # comments; JSON has no comment syntax at all.
  • Quoting — YAML only requires quotes when a string is ambiguous (contains a colon, starts with a special character, etc.); JSON always requires double quotes around strings and keys.
  • Whitespace —YAML's structure is defined by indentation, so inconsistent spacing is a parse error; JSON's structure comes from braces/brackets, so whitespace is cosmetic.
  • Ecosystem — JSON is the default for APIs and data interchange; YAML is common for hand-edited config (Docker Compose, Kubernetes manifests, GitHub Actions workflows) where comments and readability matter more than parse speed.

Converting between them

Converting JSON → YAML never loses anything, since YAML can express everything JSON can. Converting YAML → JSON drops anything JSON has no equivalent for — comments, in particular, are silently discarded, since JSON has no way to represent them. Use the YAML to JSON converter to convert either direction.

Sticking with JSON and want it readable instead of switching formats? See how to format (pretty-print) JSON.

Frequently Asked Questions

Can YAML represent everything JSON can?

Yes — YAML 1.2 is a superset of JSON, so any valid JSON document is also valid YAML. The reverse isn't true: YAML features like comments, anchors, and multi-line strings have no JSON equivalent and are dropped when you convert YAML to JSON.

Which is easier to read and write by hand?

YAML, generally — no braces or quotes for simple values, and comments are allowed. That's why it's common for hand-edited config files (Docker Compose, Kubernetes, GitHub Actions), while JSON dominates machine-to-machine formats like API responses.

Is JSON valid YAML?

Yes. Since YAML 1.2 is JSON-compatible, you can drop a .json file's contents into a .yaml file and it will parse correctly.

Which is faster to parse?

JSON, generally — its grammar is much smaller and simpler than YAML's, which is why it's the default choice for high-throughput APIs.

Related