Yaml, JSON, Toml

A great bit of technical writing from Ruud van Asseldonk: The yaml document from hell. Ruud shows one bit of yaml configuration and then shows off many problems that arise all over it. It is mind-blowing to me how nuanced and tricky it all is, to the point that I’m nearly convinced nobody should use yaml.

Yaml exists because…

I think the main reason that yaml is so prevalent despite its pitfalls, is that for a long time it was the only viable configuration format. Often we need lists and nested data, which rules out flat formats like ini. Xml is noisy and annoying to write by hand. But most of all, we need comments, which rules out json.

JSON is way better. It’s completely un-versioned, for one thing. Unlike yaml, which releases breaking changes. Versus:

Json is simple. The entire json spec consists of six railroad diagrams. It’s a simple data format with a simple syntax and that’s all there is to it. […] Json is so obvious that Douglas Crockford claims to have discovered it — not invented.

Well, JSON is way better, except for the lack of comments. It is truly obnoxious not having comments in JSON. I regularly wish that someone had left comments as to why a certain package included a package.json file, for example, and why a specific version is listed. There are 3 reasons JSON ultimately didn’t go with comments. I’d argue they are all moot now, and it would be nice to have them in there. But I could be wrong. The success of JSON might just be rooted in that strict adherence to simplicity.

The lack of comments is such a bugbear that there is a decent amount of momentum toward JSON versions that do support comments. json-c for instance is literally just JSON with comments. We use it at CodePen for internal JSON stuff. Perhaps most famously… you ever edit your VS Code Settings as JSON? That’s json-c.

screenshot of vs code settings

Further straying from the original JSON is JSON5, which brings a bunch of new features:

  // comments
  unquoted: 'and you can quote me on that',
  singleQuotes: 'I can use "double quotes" here',
  lineBreaks: "Look, Mom! \
No \\n's!",
  hexadecimal: 0xdecaf,
  leadingDecimalPoint: .8675309, andTrailing: 8675309.,
  positiveSign: +1,
  trailingComma: 'in objects', andIn: ['arrays',],
  "backwardsCompatible": "with JSON",
}Code language: JavaScript (javascript)

That’s essentially as lenient as a JavaScript object is. Looks friggin fantastic to me. It looks like it essentially doesn’t need any parsing at all for use in JavaScript, but I wonder if that makes it then harder to parse in other languages (probably).

Evert Pot loves it.

Both Evert and Ruud also point to TOML as a nicer configuration format than yaml.

Interesting tidbit, Netlify configuration files are TOML, and at one point were working on yaml additionally but scraped it. Probably a good call.

It’s unfortunate that GitHub Actions is yaml only. I wonder if TOML would have been a better call there. But I look at those workflow files and can’t help but think that they would look awfully cluttered and more difficult to scan/edit as JSON.


I work on CodePen! I'd highly suggest you have a PRO account on CodePen, as it buys you private Pens, media uploads, realtime collaboration, and more.

Get CodePen Pro

5 responses to “Yaml, JSON, Toml”

  1. Blake Watson says:

    There are 3 reasons JSON ultimately didn’t go with comments…

    Wait, what were the 3 reasons?

  2. Ben says:

    Some clever folks have adopted double-slash comment-keys as a convention for JSON comments. As long as the code that consumes the JSON expects them and can handle them, the parser doesn’t care. It’s ugly, but it’s better than nothing.

    E.g., { "//": "a comment", "//": "another comment", "foo": "bar" }

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to Top ⬆️