Man, same here. While at a previous employer where we had been using JSON for a variety of things, I discovered YAML and thought “hey cool, this is way better”, and so we migrated a bunch of stuff to it. While it did legitimately address a bunch of irritating JSON shortcomings (comments, 0x-prefixed hex notation, trailing comma support/general stream-friendliness, etc.), it drags in enough new problems of its own (oh neat, arbitrary code execution on load!) that whether or not it was actually a good idea is, in retrospect, pretty questionable.
BTW I’ve added Ruby-like blocks to Oil, which I think can be used to replace YAML in many circumstances. Shell is a natural place to put configuration because shell starts processes.
I didn’t document it fully but there’s a snippet here:
So, there’s three axes I look for in a replacement for either configuration or serialization.
One: What everyday problems do you run into.
For instance, can you encode every country code without no getting turned into false; can you include comments, can you read the damn thing or is it too much markup. Do common validation tools exist? Have they got useful error messages?
Two: What capabilities do you have at the language layer.
For instance, can you encode references? how about circular references? What kind of validation is possible? What is the range of types?
Three: Does anyone else know about the language. Is it supported in most languages?
Unfortunately, so far none of the languages that fare well on questions 1 and 2 also do well on question 3.
Dhall (for config) and ADL (Aspect Definition Language, for data serialization) come to mind as “solve 1 and 2 but not 3”.
Your point three is fixable, and Dhall is great tech. The community has been very responsive IME, to the point where I need to write a blog post about just how abnormally good they are.
Every time this page is posted here, I start reading, and inevitably give up. It’s a atrocious website. I just spent the last 5 minutes trying to follow one link, because you can’t click them and text selection isn’t working.
I get the idea. It’s a document in a text editor. However, the text editor is horrible, and it severely detracts from the point the article is trying to make.
Heck, if you just wrapped this text in a <pre> tag it would be so much more usable. Maybe add a button to open the document in an editor if you absolutely need the “document in an editor” gimmick.
No? People don’t read the words you put in front of them, why would you expect someone using yaml for the first time to write a country code to know that “no” is one of the accepted booleans
There’s so many rules of yaml, it was impossible to read all of them concisely for years
That’s just a snarky way of admitting it was a confusing mistake to make “yes” and “no” booleans. It was confusing enough that YAML 1.2 backtracked and booleans are now just “true” or “false”: https://yaml.org/spec/1.2/spec.html#id2803629
I also just generally disagree with the idea that everybody should learn every detail about every tool they use. Especially ridiculous for YAML when it claims to be a “human friendly data serialization standard”. Sorry, but having to memorize a 100 page spec first or getting bit by confusing, counterintuitive errors isn’t “human friendly”.
Because, in practice, people not reading (or remembering) stuff is an unavoidable property of the environment in which technologies like YAML must operate.
Sure, most people do. But then a year later, somebody (who’s not thinking about quirks of YAML) comes along and sees the country code list, adds a couple of entries, and somewhere else completely disconnected there’s an explosion because there’s a false in their list of strings, and the error message will almost certainly have nothing at all to do with “you need to quote ‘no’ in your yaml config”.
Do people not learn the tools they use before they use them?
Good designs are intuitive and can be used without a lot of understanding.
Users should fall into the pit of success; it should be easy to succeed and hard for them to fail.
If a technology requires a lot of study there are a few possible explanations:
It uses a completely different model, e.g. APL, Prolog, or Haskell.
The domain is essentially complex.
The design has some rough edges.
Every design has a few issues but they shouldn’t be a regular occurrence.
Thank you! There’s indeed a typo. Here is corrected text:
I’ve learned to reject languages which use whitespace for syntax, because of how ingrained whitespace ignoring is throughout most tooling, even something as basic as copy and paste.
I keep hoping to see edn make a wider appearance outside of Clojure realm but it is rare. Much nicer format, but I guess it doesn’t map too well into native data types in other languages?
I used it for a project; it was fine for that. I think mapping it to native datatypes is not an issue (used it for serialization between go and elm back then with no issues).
The main problem as I see it is that there’s a mismatch between the grandiose claims of the original announcement and the maintenance work that has gone into it since. The spec seems ot have been abandoned pretty much directly, check the github issues.
That, and it’s a bit too closely tied to clojure – the spec is incomplete, and the de facto reference implementation appears to be the clojure interpreter. That’s not really good enough for a cross-language format.
JSON is nearly valid YAML, so if you don’t like the YAML bits just write JSON and sprinkle on the YAML goodies you do enjoy like comments or datetime types.
At Notion I wrote a CircleCI config generator script in Typesscript that emits circleci.yml using JSON.stringify. Works great, plus there’s a comment at the top saying “machine generated, edit cli/commands/generate-circleci-config.ts instead”
This article is mostly about data serialisation, whereas TOML is intended for configuration files. Perhaps the biggest problem with YAML (and JSON) is that they’re used as a one-size-fits all tool.
I think it’s a reasonable incremental step in much the same way that golang is. I’d like to see people aim higher, but at least it seems to mostly work OK.
“This looks pretty reasonable,” I thought, some years ago, contemplating YAML for the first time.
I find myself reflecting on just how wrong I was once or twice a week, these last few years.
Man, same here. While at a previous employer where we had been using JSON for a variety of things, I discovered YAML and thought “hey cool, this is way better”, and so we migrated a bunch of stuff to it. While it did legitimately address a bunch of irritating JSON shortcomings (comments,
0x-prefixed hex notation, trailing comma support/general stream-friendliness, etc.), it drags in enough new problems of its own (oh neat, arbitrary code execution on load!) that whether or not it was actually a good idea is, in retrospect, pretty questionable.“yaml is better for config files because you can do inline comments”
I had this exact same experience. I don’t know where it all went wrong, but YAML is not my friend anymore either.
This is really hard to read on mobile.
Much like YAML!
BTW I’ve added Ruby-like blocks to Oil, which I think can be used to replace YAML in many circumstances. Shell is a natural place to put configuration because shell starts processes.
I didn’t document it fully but there’s a snippet here:
https://www.oilshell.org/release/0.8.1/doc/oil-proc-func-block.html#configuration-files
It looks a lot like HCL. Just like you have a block like
in Oil, you can also have
It still needs a user-facing API and I’m looking for help/feedback on that!
This looks like Nix’s attribute set syntax as well which is super nice to work with! Nice
Yes, it sucks.
But I’ll still take it over JSON any day, for defining infrastructure as code.
I just wish there was an human-workable alternative focused on minimalism. YAML is an unnecessarily complex clusterfuck.
HCL is a decent DSL.
Hmm. That one actually looks interesting.
Toml?
Ugh. Not a fan.
Why not?
So, there’s three axes I look for in a replacement for either configuration or serialization.
One: What everyday problems do you run into.
For instance, can you encode every country code without
nogetting turned intofalse; can you include comments, can you read the damn thing or is it too much markup. Do common validation tools exist? Have they got useful error messages?Two: What capabilities do you have at the language layer.
For instance, can you encode references? how about circular references? What kind of validation is possible? What is the range of types?
Three: Does anyone else know about the language. Is it supported in most languages?
Unfortunately, so far none of the languages that fare well on questions 1 and 2 also do well on question 3. Dhall (for config) and ADL (Aspect Definition Language, for data serialization) come to mind as “solve 1 and 2 but not 3”.
Your point three is fixable, and Dhall is great tech. The community has been very responsive IME, to the point where I need to write a blog post about just how abnormally good they are.
This is the kind of problems developers get when they stray from XML
Every time this page is posted here, I start reading, and inevitably give up. It’s a atrocious website. I just spent the last 5 minutes trying to follow one link, because you can’t click them and text selection isn’t working.
I get the idea. It’s a document in a text editor. However, the text editor is horrible, and it severely detracts from the point the article is trying to make.
Heck, if you just wrapped this text in a
<pre>tag it would be so much more usable. Maybe add a button to open the document in an editor if you absolutely need the “document in an editor” gimmick.I have never understood the complaint of “yes/no are true/false is surprising!”. Do people not learn the tools they use before they use them?
No? People don’t read the words you put in front of them, why would you expect someone using yaml for the first time to write a country code to know that “no” is one of the accepted booleans
There’s so many rules of yaml, it was impossible to read all of them concisely for years
“I’m writing Python|Java|JavaScript|Go|InsertLangHere, I know my job. Why do I need to learn YAML first, it’s just like JSON”
That’s just a snarky way of admitting it was a confusing mistake to make “yes” and “no” booleans. It was confusing enough that YAML 1.2 backtracked and booleans are now just “true” or “false”: https://yaml.org/spec/1.2/spec.html#id2803629
I also just generally disagree with the idea that everybody should learn every detail about every tool they use. Especially ridiculous for YAML when it claims to be a “human friendly data serialization standard”. Sorry, but having to memorize a 100 page spec first or getting bit by confusing, counterintuitive errors isn’t “human friendly”.
People want a JSON replacement, but the YAML spec is as big as the XML spec.
They are not prepared to spend that much effort on it, rightfully so in my opinion.
s/No/false
I’m just confused why “people don’t read the words you put in front of them” leads to an indictment of YAML, and not the people who refuse to read.
Because, in practice, people not reading (or remembering) stuff is an unavoidable property of the environment in which technologies like YAML must operate.
Sure, most people do. But then a year later, somebody (who’s not thinking about quirks of YAML) comes along and sees the country code list, adds a couple of entries, and somewhere else completely disconnected there’s an explosion because there’s a
falsein their list of strings, and the error message will almost certainly have nothing at all to do with “you need to quote ‘no’ in your yaml config”.Good designs are intuitive and can be used without a lot of understanding.
Users should fall into the pit of success; it should be easy to succeed and hard for them to fail.
If a technology requires a lot of study there are a few possible explanations:
Every design has a few issues but they shouldn’t be a regular occurrence.
I’d say YAML falls into the last category.
What would be the best document to learn YAML? Something more thorough than a tutorial but less comprehensive than a spec?
https://learnxinyminutes.com/docs/yaml/
Edit: Hmm, it doesn’t point out the yes/no thing. Disappointing.
I’ve learned to reject languages which use whitespace for syntax, because of how ingrained whitespace ignoring it throughout most tooling.
Is this sentence missing some important words?
Thank you! There’s indeed a typo. Here is corrected text:
I’ve learned to reject languages which use whitespace for syntax, because of how ingrained whitespace ignoring is throughout most tooling, even something as basic as copy and paste.
I keep hoping to see edn make a wider appearance outside of Clojure realm but it is rare. Much nicer format, but I guess it doesn’t map too well into native data types in other languages?
I used it for a project; it was fine for that. I think mapping it to native datatypes is not an issue (used it for serialization between go and elm back then with no issues).
The main problem as I see it is that there’s a mismatch between the grandiose claims of the original announcement and the maintenance work that has gone into it since. The spec seems ot have been abandoned pretty much directly, check the github issues.
That, and it’s a bit too closely tied to clojure – the spec is incomplete, and the de facto reference implementation appears to be the clojure interpreter. That’s not really good enough for a cross-language format.
No one likes YAML but it survives. I am definitely amused at such cryptic languages which thrives despite being kludgy.
“Good things come to an end, bad things have to be stopped.” ― Kim Newman
JSON is nearly valid YAML, so if you don’t like the YAML bits just write JSON and sprinkle on the YAML goodies you do enjoy like comments or datetime types.
At Notion I wrote a CircleCI config generator script in Typesscript that emits circleci.yml using JSON.stringify. Works great, plus there’s a comment at the top saying “machine generated, edit cli/commands/generate-circleci-config.ts instead”
What do you people think about TOML?
This article is mostly about data serialisation, whereas TOML is intended for configuration files. Perhaps the biggest problem with YAML (and JSON) is that they’re used as a one-size-fits all tool.
I think it’s a reasonable incremental step in much the same way that golang is. I’d like to see people aim higher, but at least it seems to mostly work OK.
Just out of curiosity, are there any other alternatives out there that you like better?
If I were adopting a new configuration file format, I’d strongly consider Dhall.
If I were adopting a new serialization format, I’d (less-strongly) consider ADL.
Downsides of ADL:
Advantages of ADL: