JSON is a strict data format for programs: braces, brackets, double-quoted strings and no comments. YAML expresses the same data with indentation, allows comments and multi-line text, and version 1.2 was designed as a superset of JSON. Pick JSON for APIs and machine output, YAML for files people edit by hand.
| Feature | JSON | YAML 1.2 |
|---|---|---|
| Structure | Braces and brackets | Indentation (spaces only), or JSON-style flow |
| Comments | Not allowed | # to the end of the line |
| Strings | Always in double quotes | Plain, single-quoted or double-quoted |
| Multi-line text | Escaped \n inside one string | Block scalars with | or > |
| Reuse a value | No | Anchors (&) and aliases (*) |
| Several documents in one file | No | Yes, separated by --- |
| Media type | application/json | application/yaml |
Updated
Both formats describe the same things: maps, lists, strings, numbers, booleans and null. The real differences are who reads the file and how forgiving the parser is. Try the value checker below to see how an unquoted value gets typed, then read the side-by-side examples and the pitfalls that catch people moving between the two.
Type a value the way it would appear after a colon in a YAML file, without quotes. The checker applies the YAML 1.2 core schema rules, the YAML 1.1 boolean list and the JSON grammar.
The same site settings in both formats. YAML drops the quotes and braces and adds a comment; JSON spells out every string and nesting level.
Two-space indentation, a comment, a list and a quoted version string so it stays text.
# Settings for the marketing site
name: Harbour Bakery
version: "2.10"
launch: 2026-11-02
features:
- menu
- online-orders
contact:
email: [email protected]
phone: "+1 555 0100"No comment is possible, and every key and string carries double quotes.
{
"name": "Harbour Bakery",
"version": "2.10",
"launch": "2026-11-02",
"features": ["menu", "online-orders"],
"contact": {
"email": "[email protected]",
"phone": "+1 555 0100"
}
}| You wrote | YAML 1.2 core schema reads | Safer |
|---|---|---|
| version: 2.10 | float 2.1 (the trailing zero is lost) | version: "2.10" |
| country: NO | string under 1.2, boolean false under 1.1 | country: "NO" |
| port: 0x1F90 | integer 8080 | port: 8080 |
| mode: 0o755 | integer 493 | mode: "0o755" |
| value: ~ | null | value: null |
| ratio: .inf | float infinity (no JSON form) | ratio: "inf" |
APIs, browser storage, logs and anything one program writes for another program to read. The grammar is tiny, every language has a strict parser, and there is only one way to write each value, so diffs stay predictable.
JSON also has no implicit typing. A string is a string because it has quotes, which removes a whole class of surprises.
Configuration that people read and edit: CI workflows, container setups, site front matter and deployment manifests. Comments let you explain why a setting exists, and block scalars keep shell scripts and long messages readable.
The cost is that whitespace carries meaning and unquoted values get guessed. Keep files short, quote anything ambiguous and run a linter in CI.
YAML 1.2 was written so that it is a strict superset of JSON, so in practice a JSON document loads in a YAML 1.2 parser. Edge cases exist, such as duplicate keys, which JSON parsers often tolerate but YAML forbids.
Use .yaml. RFC 9512, which registers the application/yaml media type, calls .yaml the preferred extension and notes that .yml is still used. Both work in tools such as GitHub Actions, so the choice is about consistency within one project.
YAML 1.1 treated words like yes, no, on, off, y and n as booleans. YAML 1.2's core schema only accepts true and false in three casings, but older parsers are still common. Quoting the value removes the doubt.
No. RFC 8259 lists the tokens JSON may contain and comments are not among them. Some tools accept a relaxed JSON with comments, but a strict parser will reject the file.
JSON's grammar is much smaller, and browsers ship a native parser for it, so it is usually the quicker and safer choice for data sent over the network. YAML parsers have far more rules to apply, from indentation to implicit typing.
Related: YAML to JSON converter, JSON formatter, TOML vs YAML, YAML multiline strings, YAML comments.
Start for free or see all free tools. We.Inc is free to start, with no card needed. AI building is on paid plans from $20 a month.
We.Inc is an AI-powered website builder you can resell under your own brand. Launch a branded client dashboard, bill on Stripe Connect, and deliver AI-generated websites in minutes. White-label plans start at $99 a month for 25 client sites, with a 7-day free trial and no per-site fees.