JSON vs YAML: Differences, When to Use Each and Common Pitfalls

JSON and YAML both describe structured data, but they are built for different readers. JSON is a strict, compact format designed for programs to exchange data, which is why APIs use it. YAML is designed to be easy for people to read and edit, with comments and less punctuation, which is why configuration files use it. YAML 1.2 was designed as a superset of JSON.

In practice you will meet both every week: JSON in API responses and package.json, YAML in GitHub Actions workflows, Docker Compose files and Kubernetes manifests. This guide compares the two side by side, explains when to pick each, and covers the pitfalls that cause most YAML and JSON errors.

The same data in both formats

Here is a small configuration in JSON:

{
  "name": "shop-api",
  "version": "2.1",
  "debug": false,
  "ports": [8080, 8443],
  "database": {
    "host": "db.internal",
    "pool": 10
  }
}

And the same data in YAML:

# Service settings
name: shop-api
version: "2.1"   # quoted so it stays a string
debug: false
ports:
  - 8080
  - 8443
database:
  host: db.internal
  pool: 10

The YAML version uses indentation instead of braces, drops most quotes and allows comments. The JSON version is more verbose but completely unambiguous.

Key differences at a glance

What JSON is

JSON is defined in RFC 8259, published in December 2017 as an Internet Standard. A JSON value "MUST be an object, array, number, or string", or one of the literals false, null or true, which must be lowercase.

A few rules from the standard explain most JSON errors:

• Strings use double quotes. Single quotes are invalid.
• No comments. The grammar simply has no place for them.
• UTF-8 for exchange. JSON exchanged between systems that are not part of a closed ecosystem "MUST be encoded using UTF-8".
• Duplicate keys are risky. The RFC says names within an object "SHOULD be unique", and when they are not, software behaves unpredictably: some parsers keep the last value, others raise an error.
• Large numbers lose precision. Implementations that expect IEEE 754 double precision interoperate well, and integers are only guaranteed exact between -(2^53)+1 and (2^53)-1. Send very large IDs as strings.

That strictness is the point. Any language can parse JSON the same way, which makes it ideal for APIs, logs, browser storage and data files.

Our guide to formatting JSON and fixing validation errors covers the most common mistakes, such as trailing commas.

What YAML is

The current specification, YAML 1.2.2, was published in October 2021. YAML 1.2 aimed at "making YAML a strict superset of JSON", so most valid JSON is also valid YAML.

YAML adds features designed for people:

• Comments start with # and "must be separated from other tokens by white space characters."
• Indentation defines structure. The spec says "tab characters must not be used in indentation", so use spaces only.
• Anchors and aliases let you define a block once with &name and reuse it with *name, handy for repeated settings.
• Multiple documents can live in one file, separated by ---.

YAML's flexibility is also its weakness. Because most values do not need quotes, the parser has to guess their type, and different parser versions guess differently.

Where each one is used

JSON

• REST and GraphQL API requests and responses
• Package manifests such as package.json and composer.json
• Structured data on web pages (JSON-LD schema markup)
• Data stored or exported by applications

YAML

• GitHub Actions. GitHub's documentation says workflows "are defined by a YAML file" in the .github/workflows directory.
• Docker Compose. Docker says the default path for a Compose file is compose.yaml (preferred) or compose.yml.
• Kubernetes. The Kubernetes docs note that "by convention, manifests are YAML (you could also use JSON format)."
• Many CI/CD, static site and application configuration files

The Kubernetes example shows the relationship nicely: you write YAML because it is easier to read, and the tooling converts it to JSON before sending it to the API.

The pitfalls that cause most YAML bugs

1. The yes/no/on/off problem

In YAML 1.2's core schema, only true, True, TRUE, false, False and FALSE are booleans. But the older YAML 1.1 boolean type also treats y, n, yes, no, on and off (in various capitalizations) as booleans, and some parsers and tools can still follow 1.1 rules.

That leads to classic bugs: a list of country codes where Norway's NO becomes false, or a setting like mode: on becoming true. The fix is simple: quote any value that should stay a string.

countries: ["GB", "US", "NO"]
mode: "on"

2. Numbers that should be strings

version: 2.10 is parsed as the number 2.1, losing the trailing zero. Quote version numbers, phone numbers, ZIP and postal codes with leading zeros, and long IDs.

3. Tabs and inconsistent indentation

A single tab, or one line indented with three spaces where the rest use two, changes the structure or fails to parse. Configure your editor to insert spaces in YAML files and show whitespace.

4. Null vs empty string

In the YAML core schema, null, Null, NULL, ~ and an empty value all mean null. The spec notes that "a null is different from an empty string", so if you mean an empty string, write "".

5. Colons and special characters in strings

A value containing : or starting with characters such as *, &, !, { or [ may be misread. Quote strings that contain punctuation, URLs with ports, or anything that looks like YAML syntax.

When to use JSON and when to use YAML

If a tool accepts both, follow its documentation and your team's convention. Consistency matters more than the format.

Converting between JSON and YAML

Because YAML 1.2 is designed as a JSON superset, converting JSON to YAML is usually safe. Going from YAML to JSON loses comments and anchors, which are expanded into repeated data, and exposes any type-guessing surprises.

Our free JSON to YAML converter converts in both directions in your browser and reports errors with the exact line and column. To tidy or validate a JSON file first, use the JSON formatter. If your data starts life in a spreadsheet, our guide to converting CSV to JSON covers the quirks of that step. If it arrives as XML, such as from an older API, use the XML to JSON converter.

A safe workflow for config files

1. Validate before you commit. Run YAML and JSON through a parser or linter in your editor or CI.
2. Quote anything ambiguous: versions, codes, yes/no-style words, values with colons.
3. Use spaces, never tabs, and keep indentation consistent.
4. Keep secrets out of both. Config files end up in repositories and logs, so use your platform's secret store instead. Our guide to exposed .env and .git files shows how leaked config files get found.
5. Test in a non-production environment after changing deployment or CI files.

A single misplaced space in a config file can stop a deployment or a scheduled job. If your team is automating workflows across tools, Make It Flow can help design them with validation steps built in.

Frequently asked questions

Is YAML better than JSON?

Neither is better overall. YAML is easier for people to read and edit and supports comments, which suits configuration. JSON is stricter and simpler to parse consistently, which suits APIs and data exchange. Many projects use both: JSON for data, YAML for settings.

Is all JSON valid YAML?

YAML 1.2 was designed to be a strict superset of JSON, so in practice most JSON documents parse as YAML 1.2. Edge cases exist, and older YAML 1.1 parsers are less compatible, so test with the parser your tool actually uses rather than assuming.

Can JSON have comments?

Standard JSON, as defined in RFC 8259, has no comment syntax, and strict parsers reject comments. Some tools accept variants such as JSONC or JSON5 that allow them. If you need comments in a standard JSON file, a common workaround is a dedicated field such as "_comment".

Why does YAML turn NO into false?

YAML 1.1 treats words like yes, no, on and off as booleans, and some parsers still follow those rules. YAML 1.2's core schema only treats true and false (in a few capitalizations) as booleans. Quoting the value, for example "NO", keeps it a string in every version.

Which is faster to parse, JSON or YAML?

JSON has a much smaller grammar, with no type guessing, anchors or multiple documents, so there is less work and less ambiguity for a parser. For configuration files read once at startup, speed is rarely the deciding factor; readability and correctness matter more.

Related reading

• How to Format JSON and Fix Common JSON Validation Errors: How to format JSON so it's readable, validate it, and fix the most common JSON errors: trailing commas, single quotes, comments, unescaped characters and more.
• How to Convert CSV to JSON Without Losing Leading Zeros or £ Signs: How to convert CSV to JSON reliably: header rows, quoted fields, Excel's semicolon and UTF-8 BOM quirks, and keeping leading zeros on phone numbers and IDs.
• Automate Broken Link Checks: Scheduled Crawls and GitHub Actions: How to run broken link checks automatically with lychee or linkinator on a GitHub Actions schedule, check external links politely and fix them in bulk.

Sources

• IETF RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• YAML Ain't Markup Language, version 1.2.2 (October 2021)
• YAML 1.1 Boolean Language-Independent Type
• GitHub Docs: Workflows
• Docker Docs: The Compose application model
• Kubernetes: Objects in Kubernetes