The same data in both formats
Here is a small configuration in JSON: {"name": "shop", "port": 8080, "debug": false, "hosts": ["a.example.com", "b.example.com"]}. In YAML the same data is written with indentation instead of braces: name: shop on one line, port: 8080 on the next, debug: false, and hosts: followed by two indented lines that start with a hyphen.
Both load into exactly the same object in any programming language. The difference is in how they are written and in what else each format allows.
| JSON | YAML | |
|---|---|---|
| Structure | Braces and brackets | Indentation, or braces if you like |
| Text | Always in double quotes | Quotes usually optional |
| Comments | Not allowed | Lines starting with # |
| Multi line text | Only with \n inside a string | Blocks with | or > |
| Reusing parts | Not possible | Anchors (&name) and aliases (*name) |
| Several documents in one file | No | Yes, separated by a line of three hyphens |
| Typical use | APIs, data exchange, browsers | Configuration: Docker Compose, Kubernetes, CI |
Try it here: YAML to JSON
Open the full tool pageWhy YAML is pleasant to write
YAML needs fewer characters. There are no closing braces to count, no commas to forget between items and no quotes around most text. Comments let you explain why a setting exists, which is why tools that people edit every day, such as Docker Compose, Kubernetes, GitHub Actions and Ansible, chose it.
Anchors avoid repetition: you define a block once with &defaults and reuse it with *defaults, or merge it into another block with <<: *defaults and override single keys. Block text keeps line breaks, which makes scripts and long messages readable inside the file.
YAML traps that change your data
The freedom to leave out quotes comes at a price: YAML guesses the type of every unquoted value, and the guess is not always what you meant. Most of these problems disappear when text is in quotes.
- The Norway problem: in YAML 1.1, which many tools still use, NO, no, yes, on and off are booleans. A list of country codes with NO for Norway turns into false.
- Version numbers: 1.10 is the number 1.1, and 3.0 may become 3. Write "1.10" to keep it as text.
- Leading zeros: postal codes and product codes like 0123 can become numbers, and YAML 1.1 reads them as octal, so 0123 becomes 83.
- Times: in YAML 1.1, 12:30 is a base 60 number, 750.
- Colons and hashes: a value containing ": " or " #" ends the value early or starts a comment. Put such text in quotes.
- Tabs: YAML does not allow tabs for indentation, and a key that is indented one space too far ends up in the wrong block without any error in some editors.
Why JSON is better for programs
JSON has one way to write each thing and no guessing: text is always quoted, so "NO" stays text and 1.10 is clearly a number. Parsers are small, fast and available in every language, and browsers read JSON natively. That makes JSON the safer choice whenever data is produced and read by software, such as API responses, logs, caches and data files.
The lack of comments is the most common complaint. Some tools accept JSON with comments (often called JSONC), but standard parsers reject it, so it is not a good format for files that other programs must read.
Converting between YAML and JSON safely
YAML 1.2 was designed as a superset of JSON, so almost any JSON document is also valid YAML. The other direction needs a real parser, because YAML features must be resolved: anchors and merge keys are expanded, block text becomes a string with \n, and several documents become a list. Comments cannot be carried over, since JSON has no place for them.
When you convert JSON to YAML, every value that a YAML reader could misread must be quoted. The converter on this page checks each text value against both YAML 1.1 and YAML 1.2 rules and quotes it only when needed, so yes, NO, 0123 and 1.10 come back unchanged. Converting the result back with Swap is a quick way to prove that nothing changed.
Which one should you use?
- Use YAML for configuration that people write and review by hand, especially when comments help.
- Use JSON for data that programs exchange, store or send over the network.
- Use JSON when the file is generated by code, even if a person reads it later.
- If a tool accepts both, as many do, keep the format your team already uses: consistency matters more than the small differences.
- If you stay with YAML, quote text values that look like numbers, dates or yes/no, and check files with a parser before you deploy them.