JSON vs YAML
JSON and YAML are both in wide use and are chosen for different reasons. This page sets them against each other on the things that decide between them, and links to the converters for both directions — every one of which runs in your browser, with the file never uploaded.
The short answer
These express the same shapes — the same nesting, the same values — and differ in how they are written and who has to read them. YAML drops the braces and quotes and lets indentation do the work, which makes a configuration file far more pleasant to edit by hand. It also allows comments, which JSON does not, and for a config file that is often the deciding argument.
JSON's advantage is that it is boring. There is one way to write it, every language parses it identically, and no whitespace change can alter its meaning. YAML has enough subtlety in its rules — indentation, implicit typing, values like `no` and `on` — that a file can mean something other than it appears to.
A common arrangement is to write YAML and generate JSON from it, keeping the comments and the readability where humans work and handing programs the unambiguous version. That works well as long as the YAML remains the source of truth: converting back the other way produces a file with the shape intact and every comment gone.
Side by side
| Property | JSON | YAML |
|---|---|---|
| Stored as | Plain text, readable in any editor | Plain text, readable in any editor |
| What it can hold | Values nested inside values | Values nested inside values |
| Numbers stay numbers | Yes | Yes |
| Comments | No | Yes |
| Several in one file | No | Yes |
| Published | 2001 | 2001 |
Where they actually differ
- Only YAML has a syntax for comments. Converting away from it loses every explanation in the file while keeping all of the data.
- Only YAML can hold several documents in one file, which matters when a conversion has more than one thing to write.
- They are near contemporaries, which is why they overlap as much as they do.
What people get wrong
- Comments do not survive into a format with no syntax for them. The data arrives intact and every explanation of it is gone, which makes that direction effectively one-way.
Which to choose
- Choose JSON when
- Choose JSON for anything a program writes or reads, for APIs, and wherever unambiguous parsing matters more than readability.
- Choose YAML when
- Choose YAML for configuration a person will edit, where comments and a lack of punctuation are worth more than strictness.
Converting between them
Common questions
- Are comments lost converting YAML to JSON?
- Yes, and there is no way around it: JSON has no syntax for a comment, so there is nowhere for them to go. That makes the conversion one-way in practice — the data survives, the explanation of it does not. Keep the YAML if the comments matter.
- Which of JSON and YAML is better?
- Neither, in general — if one were simply better the other would have disappeared. They are good at different things, and the short answer above says which is which. The useful question is what the file has to do next: be edited, be published, be opened by somebody else, or fit inside a size limit.
- Does converting between them lose anything?
- It depends on the direction. Converting into a format that stores everything loses nothing but does not recover anything either; converting into one that discards detail loses a little each time. The table above says which of these two does which.
- Can I convert back afterwards?
- The file will convert back, but whether it comes back unchanged depends on the direction. Between two formats that store everything, a round trip is lossless. Where one of them discards detail, that detail is gone and the return journey cannot invent it.
- Can I use both?
- On a web page, often yes, and it is usually the right answer: serve the smaller modern format and list an older one as a fallback so each browser takes what it understands. For a file you are handing to a person, pick one — the one they can open.
- Which one does my software support?
- The side-by-side table above says which browsers read each, which is the part that varies most. Desktop support is harder to state in general and tends to lag browsers by years, so if the file is going to somebody else, the older and more widely read of the two is the safer choice.
- Is converting between them free?
- Yes, with no account and no limit on how many files you convert. Every converter linked from this page runs in your browser: the file is read from your device, converted by code running on it, and handed back as a download.
- Is my file uploaded?
- No. There is no conversion server here to upload it to, and no third-party service is involved. You can confirm it yourself: open your browser's developer tools, switch to the Network panel with no filter, and run a conversion — no request carries your file.