How to Convert JSON to YAML and YAML to JSON (Without Breaking Your Values)
Convert JSON to YAML or YAML to JSON for Kubernetes, Docker Compose and CI files. Learn the Norway problem, tab and indentation traps, and what is lost.
Updated November 7, 20269 min read
To convert JSON to YAML, paste the JSON into the JSON to YAML converter, pick the parser your YAML is for, and press Convert to YAML. To go the other way, paste YAML into the YAML to JSON converter. Both take seconds. The part worth reading is what can go wrong: YAML guesses types from unquoted words, so a country code of no can turn into false, a file permission can turn into a different number, and a date can stop being text. This guide covers both directions, those traps, and what is lost along the way.
Two directions, two tools
JSON and YAML describe the same kinds of data: objects, lists, text, numbers, true or false, and null. JSON is strict and noisy, with braces, brackets and quotes everywhere. YAML drops most of that and uses indentation instead, which is why people prefer it for files they edit by hand. Each direction has its own tool, with its own limits.
| You have | You want | Tool | Free limit |
|---|---|---|---|
| JSON, an API response or an export | YAML | JSON to YAML | One file up to 10 MB |
| A YAML config or manifest | JSON | YAML to JSON | One file up to 25 MB |
| JSON that will not parse | Fixed JSON | JSON Validator | See the tool page |
| Messy JSON on one line | Readable JSON | JSON Formatter | See the tool page |
The limits differ because the work differs. Turning JSON into YAML means holding the whole document as live objects while the YAML is written, so that tool stops at 10 MB. Reading YAML scans the text, so it has room for 25 MB.
Converting JSON to YAML, step by step
Add your JSON
Open the JSON to YAML converter. Paste JSON into the editor and press Use this JSON, or drop a .json, .ndjson or .jsonl file onto the page.
Choose the Target parser
The default is Portable, which quotes every value that an older or date-aware YAML reader would read as a different type. YAML 1.2 quotes only what a modern parser needs. Quote all wraps every string in quotes when you do not know what will read the file.
Set the layout
Pick an Indent from 1 to 8 spaces (2 is the default), a Null style of null, ~ or empty, and whether the file starts with ---.
Convert and read the badge
Press Convert to YAML. With Verify the result on, the YAML is read back with an independent parser and compared with your JSON. The badge says Verified, or names the first path where a value came back different.
Download or copy
Use Download YAML or Copy. The preview shows the first lines for large files, but the download is the whole result.
Converting YAML to JSON
Paste YAML into the YAML to JSON converter or drop a .yaml or .yml file. Sample buttons for Kubernetes, Docker Compose and GitHub Actions load a typical file so you can see the result first. The output settings are all free:
- Indent: 2 spaces, 4 spaces, Tabs, or Minified (one line, no whitespace).
- Documents: Auto (one document becomes an object, several become an array), Always array, First only, or Separate files, one .json per document.
- Sort keys: puts every object's keys in a stable order so two conversions diff cleanly.
- Duplicate keys: Refuse, which names the line, or Keep last.
- NaN and Infinity: Write null, Write as text, or Stop. JSON has no value for .nan or .inf.
- Timestamps: As written, or ISO 8601.
Anchors and aliases are expanded wherever they are used, and merge keys such as <<: *common are resolved, with keys written directly on a mapping overriding the merged ones. Tags such as !Ref are dropped to the value underneath, and the tag names are listed under the result.
Pick the parser, convert, and get a verified result. Free: one file up to 10 MB, with every setting that affects correctness included. Pro: up to 50 files as one ZIP, plus output styling. It all runs on your device, not our servers.
Convert JSON to YAMLThe Norway problem and other quiet type changes
In YAML 1.1, the version still used by PyYAML, Ansible and Ruby's Psych, the plain words yes, no, on, off, y and n are booleans. A list of country codes containing NO (Norway) therefore comes back with false in its place. Nothing reports an error; the data is just wrong. YAML 1.2 removed that rule, so some parsers read the same file differently from others. That disagreement is what the Target parser setting exists for.
| Value in your JSON | What an older YAML reader may make of it | Portable target |
|---|---|---|
| "no", "yes", "on", "off" | Booleans, so "no" becomes false | Quoted |
| "0755" | An octal number, 493 | Quoted |
| "1:30" | A base-60 number, 90 | Quoted |
| "2024-01-01" | A date object, not text | Quoted |
| "true", "null", "12" | A boolean, null or a number, in every YAML version | Quoted (in every mode) |
| "hello" | Text | Left plain |
Portable quotes exactly the values in that table and leaves ordinary words alone, so the file stays readable. YAML 1.2 mode quotes less, and is correct only if whatever reads the file is a 1.2 parser with no date handling; the tool still counts how many values an older reader would change and tells you. Keys are quoted by the same rules, since an unquoted n or yes key becomes a boolean in a 1.1 reader. Going the other way, YAML to JSON follows the YAML 1.2 rules: yes, no, on and off stay strings, and a timestamp such as 2001-12-14 stays the text you typed unless you choose ISO 8601.
Indentation, tabs and empty values
YAML structure is indentation. Two spaces more means a child; the same indentation means a sibling. A single line indented one space too far changes the shape of the data or stops the parse. Tabs are the classic failure: YAML forbids them for indentation, and a file that looks aligned in an editor with tab stops can refuse to load. The YAML to JSON converter reports the line and column of the fault, with a few lines of your own source and a caret under it. Replace the tab with spaces and convert again.
JSON to YAML has no such risk, because the tool writes the indentation for you. Empty containers are written as {} and [] instead of being left blank, because a blank value reads back as null. Text that contains newlines becomes a readable | block, so a script or certificate stays in lines. If a block cannot represent the text exactly, for example when the first line is blank or indented, or it contains a carriage return, the text is quoted instead. Silent changes are worse than ugly output.
What is lost going to JSON: comments and shared nodes
JSON has no comments. When you convert YAML to JSON, every # comment is dropped, and so is any documentation they carried. Keep the YAML as your source of truth and treat the JSON as a build output. Going from JSON to YAML you gain the ability to write comments, but you start with none, so add them after converting.
Aliases are also flattened. Two places that referred to one anchor become two identical copies in the JSON, because JSON cannot say they were the same node. Converting back gives you YAML that is longer than the original. A circular alias, where an anchor refers to itself, is legal YAML but impossible in JSON, and the converter reports it with the path rather than failing silently.
Typical uses: Kubernetes, Docker Compose and CI files
- Kubernetes: a manifest separated by --- is several documents. Use Auto or Always array to get them as JSON for a tool that expects it, or Separate files for one .json each. Going to YAML, set the layout, then check the badge, because a version label such as "1.20" must stay text.
- Docker Compose: a service defined with <<: *common comes out with the shared keys merged in. Port mappings such as "22:22" are the 1.1 trap in practice, since a bare 22:22 can be read as a base-60 number. Portable quotes them.
- CI files such as GitHub Actions workflows: the key on stays the string "on", not true. That is the right reading for a 1.2 parser. To diff two workflow files, convert both with Sort keys on; it changes order, not meaning.
- API payloads: turn a JSON response into a starting YAML config, or turn a YAML settings file into a body for a service that has no YAML reader.
To see how two configs differ, convert both, sort the keys and compare the JSON; ordering and comment changes then stop showing up as differences. For tidying JSON first, see formatting JSON online, and for XML sources, converting XML to JSON.
When the conversion fails
If JSON cannot be parsed, the converter shows the line and column, a caret under the exact character, and what was expected there. The usual causes are a trailing comma, single quotes instead of double quotes, a comment, or an unquoted key. The JSON Validator lists faults in one pass, and the JSON Formatter makes the structure easier to see. Fix the syntax, then convert again.
- File too big: the free limits are 10 MB for JSON to YAML and 25 MB for YAML to JSON. Split the file, or use Pro.
- Several files at once: Free converts one at a time. Pro queues up to 50 and downloads them as a single ZIP; YAML to JSON can also fold every document from every file into one array.
- Duplicate keys in YAML: the default is to refuse and name the second key. JSON cannot hold both, so choose Keep last only when you know which value you want.
- A different value after converting: the Verification failed message names the path and both types, for example a string that came back as a date. Change the Target parser to Portable.
Frequently asked questions
How do I convert JSON to YAML?
Paste your JSON into the JSON to YAML converter, choose a Target parser (Portable is the default), and press Convert to YAML. Then download the .yaml file or copy it. Free handles one file up to 10 MB.
How do I convert YAML to JSON?
Paste YAML or drop a .yaml or .yml file into the YAML to JSON converter. Choose an indent, how to treat several documents, and whether to sort keys, then download the result. Free handles one file up to 25 MB.
What is the Norway problem in YAML?
In YAML 1.1 the unquoted word no is a boolean, so the country code NO for Norway is read as false. Quoting the value fixes it. The JSON to YAML converter does this for you when the Target parser is Portable.
Are comments kept when I convert YAML to JSON?
No. JSON has no comments, so every # comment is dropped. Keep the YAML as the source and generate the JSON from it, rather than editing the JSON by hand.
Why does my YAML fail with a tab error?
YAML does not allow tabs for indentation, even if the file looks aligned in your editor. Replace the tabs with spaces. The YAML to JSON converter names the line and column where it stopped.
Can I convert Kubernetes or Docker Compose files?
Yes. A manifest with several documents separated by --- converts to an array, its first document, or one file per document. Anchors, aliases and merge keys are resolved. Everything runs on your device, not our servers, so hostnames and image names are not uploaded.