9 ms·
YAML document from hell (2023)
- timetraveller26 1y agolua could have been a good replacement for yaml configuration files, the tables syntax is really natural and being a full programming language (a small one) allows for more complex usage.
- al_borland 1y agoThe Norway problem drives me a bit nuts. In a lot of the Ansible documentation, yes/no are used instead of true/false. When seeing this in the official docs, I used it, figuring this was the preferred convention in Ansible. These days it now throws warnings or lint errors, so I’m updating it all over the places as I find it. Yet the Ansible documentation still commonly uses it.
- tgv 1y agoIt depends on how they parse/decode/unmarshal the file. If they use a "generic" yaml parser, no will be translated to false. But if the parser knows the types of the data structure, or can be instructed not to replace certain strings, or has hooks, it can treat no as a string. So it might be that the linter doesn't operate like the parser.
- maxbond 1y agoHalloween isn't for a few more weeks, but this framework for creating bespoke YAML dialects that can only be parsed by a specific implementation and with the correct type annotations will scare the pants off of your devops colleagues around the campfire. (In case I haven't succeeded in hitting the right tone, this is intended to be good-natured jest and not snark.)
- tgv 1y agoWell, JSON cannot represent dates (nor Sets, Maps, NaN, etc.), so quite a few applications with a JSON parser have their own conversion (e.g. seconds since epoch, string parsing, object with date fields). Is that a bespoke JSON dialect that scares the pants off? Now, JSON is more suited for machine-to-machine, but YAML works fairly well for humans. It's a pity, but a few domain specific don't really hurt, since you can't copy some bit of YAML and paste it in an entirely different config anyway. PS campfire story? "When we were still working in the old building, deep down in the cellar, there was a colleague who had been there since the early days. Nobody saw him arrive at work or leave. It was as if he was always there. One of the things he had written was a custom parser ... FOR YAML!"
- maxbond 1y agoI'd say that isn't a JSON dialect because that's postprocessing applied after parsing, versus hooking into a YAML parser to change the semantics of how `no` is parsed. But it is a good point. I did run into a project once with a very cool custom YAML parser to recommend how to recover from errors. I think you do have to type check all deserialization, and you should fail if you process a bool where you expect a string. Automatically fixing things can be very dangerous. But if you were going to do it, the way you described is the best way to do it. > Well, JSON cannot represent ... NaN ... Here's another horror story: >>> # Python >>> json.dumps({"foo": float("nan")}) '{"foo": NaN}' > // JavaScript > JSON.parse('{"foo": NaN}') Uncaught SyntaxError: Unexpected token 'N', "{"foo": NaN}" is not valid JSON
- gchamonlive 1y agoAnsible isn't a gold standard for docs. The docs are updated and maintained, but the underlying interfaces aren't consistent and that leaks to the docs. One can only wonder why, maybe different developers with different ideas for conventions without a style guide. Ansible is a wonderful tool though, if you can excuse these idiosyncrasies.
- sofixa 1y ago> Ansible is a wonderful tool though, if you can excuse these idiosyncrasies. The only advantage Ansible has is how easy it is to start with it - you don't need to deploy agents or even understand a lot about how it works. Trouble is, it doesn't really scale. It's pretty slow when running against a bunch of machines, and large configurations get unwieldily quickly (be it because of YAML when in large documents its impossible to orient/know what is where/at what level, or because of the structure of playbooks vs roles vs whatever, or because templating a whitespace-as-logic-"language" is just hell). It's also fun to debug "missing X at line A, but the error can be somewhere else". Cool, thanks for the tip. So it's pretty great to get started with, or at a home lab. Big organisations struggling with it is a bit weird.
- dreamcompiler 1y agoSeems like the right answer is "bootstrap your daemon installs with Ansible and then use something that scales better that runs on those daemons." What are the best practices along these lines? What's the "something better"?
- TheTaytay 1y agoCurious about this myself!
- onraglanroad 1y agoI tend to use Ansible to set up for Puppet. There's an Ansible provider for Terraform so you can do the whole thing in there.
- Y-bar 1y agoHas this really been a problem in the last ten years? Version 1.2 of the spec (if I recall) fixed it in 2009.
- Diti 1y agoOnly if you use Kubernetes, because it’s YAML 1.1 all the way.
- Diti 1y agoForgot to add a source: https://github.com/kubernetes/kubernetes/issues/34146#issuecomment-252692024 https://github.com/kubernetes/kubernetes/issues/34146#issuec...
- Y-bar 1y agoOh man. That issue is nine years old now and still open. And the referenced candiedyaml library was archived in 2022. Sometimes the tech world moves at warp speed, sometimes it just treads water.
- xenator 1y agoThis one is amazing, I almost pissed myself laughing reading it. So true about YAML. Another caveat is using --- as section separator in the file. It will starts new file inside your existing file. Still love it.
- BobbyTables2 1y agoI’m amazed how sane the “document from hell” looks. The author didn’t even get into the weird stuff GitLab does with YAML too!
- RedShift1 1y agoNot gonna lie, I use Google and copy paste the stanzas that do the thing I want it to do. Same for Maven, someone somewhere has already solved the same problem I have, all I need to do is copy paste and adjust to my situation.
- twelvechairs 1y agoAlmost all of this is solved by basically putting quotes around strings. Yaml has its uses cases where you want things json doesnt do like recursion or anchors/aliases/tags. Or at least it has had - perhaps cue/dhall/hcl solves things better. Jsonnet is another. I havent tried enough to test how much better they are.
- lillesvin 1y ago> Almost all of this is solved by basically putting quotes around strings. Yeah, that was my first thought as well. I personally don't mind YAML, but I've also made a habit out of quoting strings. And, I mean, you're quoting both keys and strings in JSON, so you're still saving approx. 2 double quotes per key/value pair in YAML if that's a metric that's important to you.
- montroser 1y agoAs the article points out with the `on` example, you really have to quote yaml keys as well, if you want the defense to work...
- lillesvin 1y agoThe argument was that most of the mentioned problems could be solved by quoting the values. I don't have a problem with avoiding "on" as a key, and I apparently haven't used it ever, because I've never run into this particular problem in my 15+ years using YAML. So, sure, if you want to play it super safe, quote keys as well. But I'm personally fine with the trade-off in not quoting keys.
- Dylan16807 1y agoIf you compare to JSON5 instead of JSON, you still get the benefit of unquoted keys, but you also get a guarantee the keys are strings, and it's harder to forget to quote a value.
- everforward 1y ago
- raincole 1y agoThe n, no, off thing is just sad. It's a 100% avoidable issue. But whoever put that into spec was just so clever that they overflew and became stupid.
- __alexs 1y agoThis is basically every problem in YAML. Someone couldn't resist adding more stuff and either didn't realise or didn't care about the ambiguities it created.
- kevincox 1y agoIt basically feels like overfitting. They saw some use case so they added it. But they didn't think about how this would generalize and now this nice use case is disproportionately supported at the cost of surprising everyone who doesn't need time-of-day fields in their file.
- baobrien 1y agoToo clever by half
- phpnode 1y agoWhoever thought supporting sexagesimal numbers was a good idea needs to spend some extended time away from their computer to reflect on what they’ve done
- chrisandchris 1y agoWe wanted a file format that's easy to read and less verbose than xml and all we got was something that is so full of pitfalls that it would be easier just not to use it.
- microtherion 1y agoPresumably that was to support time values.
- Ajedi32 1y ago
- rossant 1y agoWow, I wasn't aware there was so much magic and arcane features in yaml. Great post. Thanks.
- bertman 1y agoDiscussion from 3 years ago, when this was originally posted: https://news.ycombinator.com/item?id=34351503 https://news.ycombinator.com/item?id=34351503 , 566 points, 358 comments
- natebc 1y agoI think this article gets posted about every quarter.
- illusive4080 1y agoI think it shows that there is a persistent dislike of yaml. I would like to read about the history of why yaml became so popular, despite all its flaws.
- smartbit 1y agoArchive of sept 18, 2025 https://web.archive.org/web/20250918212908/https://ruudvanasseldonk.com/2023/01/11/the-yaml-document-from-hell https://web.archive.org/web/20250918212908/https://ruudvanas... as site seems down today.
- h1fra 1y agonot only is YAML a pain but JSON has native parser in major languages, while not yaml. I find it crazy some people are still actively choosing this over JSON (or alternatives)
- loudmax 1y agoThis is a case of the right tool for the right job. YAML is far easier to read and parse as a human than JSON. If you're passing data between processes, and you still want the data to be human readable, then JSON is a good choice. If you're writing a configuration file that's going to be edited by a human, then YAML is easier to look at and understand.
- feoren 1y ago> YAML is far easier to read and parse as a human than JSON. When you're on line 4000 of a YAML configuration file and the previous 70 lines have been at indentation level 6, and you see a blank line and another line at indentation level 4 (or is that 5? maybe 3?) then I strongly, strongly disagree that two '}' characters are more difficult to read than newlines, tabs, and spaces. YAML is one of a family of languages borne from the idea that punctuation is bad and therefore should be invisible. Not gone, because all of these languages still have punctuation. No, these characters that are critically important to the interpretation of the file must be invisible. Code and markup is easy to read when it is easy to predict what the computer will do when it parses it. Invisible punctuation makes the files harder to read, not easier. The only thing easier in YAML is writing it in the first place, and we all know that "write-only" is an insult.
- secondcoming 1y agoIt's honestly absurd how prevalent YAML is. It's clearly dumb.
- Kostarrr 1y agoSo... what are the good alternatives to yaml? For quite some time I thought toml, but the way you can spread e.g. lists all over the document can also cause some headaches. Dhall is exactly my kind of type fest but you can hit a hard brick wall because the type system is not as strong as you think.
- endgame 1y agoI wish I had a good answer for you. I've been dissatisfied with Dhall, Nickle, Cue, and possibly others. Dhall's type system is both too strong (you have to plumb type variables by hand if you want to do any kind of routine FP idioms) and too weak (you can't really _do_ much with record types - it's really hard to swizzle and rearrange deeply nested records). On top of that, the grammar is quite difficult to parse. You need a parser that can keep several candidate parses running in parallel (like the classic `Parser a = Parser (String -> [(a, String)])` type) to disambiguate some of the gnarlier constructs (maybe around file paths, URLs, and record accesses? I forget). The problem with this is that it makes the parse errors downright inscrutable, because it's hard to know when the parse you actually intended was rejected by the parser when the only error you get was "Unexpected ','". Oh, and you can't multiply integers together, only naturals. Maybe Nix in pure eval mode, absurd as that sounds? I think the best thing for tools to do is to take and return JSON (possible exception: tools whose format is simple enough for old-school UNIX-style stdin/stdout file formats). Someone will come up with a good functional abstraction over JSON eventually, and until then you can make do with Dhall, YAML, or whatever else.
- ruuda 1y ago> Maybe Nix in pure eval mode, absurd as that sounds? It doesn’t sound absurd, it’s pretty nice. What do you think about https://rcl-lang.org https://rcl-lang.org?
- rswail 1y agoJust been reading the docs, I like it :) Gonna have to set aside some time to play with it compared to HCL where I spend a lot of time.
- kzrdude 1y agoYaml is an interesting case study that we can (and have) learned a lot about. Mistakes to avoid. :)
- thomasfl 1y agoNot many know that the inventor of the YAML specification built a fully working pendulum clock as a teenager. With Lego bricks. YAML is a good standard for simple settings files. For more complex data structures, use JSON.
- vivzkestrel 1y agostupid question: why dont they announce a newer version of YAML that is not backwards compatible and allow only quoted strings in their parser?
- mystifyingpoi 1y ago> that is not backwards compatible This would be a massive breaking change for Kubernetes. There are piles and piles of YAML all around the opensource that would need updating. It would be very hard to adopt. Also, quoting strings 100% of the time just looks ugly in my opinion. Not a big deal with autogenerated YAML, or YAML that I do not maintain, but for anything handwritten it's annoying.
- phito 1y agohow is it annoying...? it's literally like that in almost every single language out there. IMO seeing unquoted strings in YAML feels weird.
- mystifyingpoi 1y agoAs I said, it's subjective. I like this image: my-repo.com/my-app:v1 imagePullPolicy: Always more than this image: "my-repo.com/my-app:v1" imagePullPolicy: "Always" That's all. Not sure about quoting keys though.
- vivzkestrel 1y agois it a massive change? yes, will it cause serious problems for existing apps in production? yes. but think of this as one of those python 2 to 3 moments. They could improve the spec dramatically and cut the parser down by a crazy amount to detect edge cases. It ll be a bright direction forward for YAML
- maweki 1y agoWe found yaml to be a great exchange format for electronic exam data. It allows us to put student submitted answers and source code into a yaml file and there is no weird escaping. It's very readable with a text editor. And then we just add notes and a score as a list below and then there's the next submission. For readability of large blocks of texts that may or may not contain various special characters and newlines the only other alternative we have seen was XML, but that is very verbose. So what the author finds as a negative, the many string formats, are exactly what drew us to yaml in the first place.
- privatelypublic 1y agoWhat is so verbose about a cdata directive? Everybody complains about XML being verbose, never once heard complains about HTML being too verbose.
- tpmoney 1y agoI’ll be that person then. HTML is too verbose for anything intended to be read as plaintext (and not the parsed marked up form) more than 25% of the time. A well formatted java doc comment full of HTML markup is difficult to read as plaintext, but without the markup loses out on the expressiveness converting javadoc to html can give. That’s why it’s nice that Java 25 will introduce markdown as a new option for javadoc (and presumably why Rust chose it for the same)
- dreamcompiler 1y agoSomebody in these discussions always correctly points out that s-expressions are as expressive as XML but without the excess line noise, so it might as well be me.
- aranw 1y agoI find it remarkable that YAML has become our goto for configuration when it is riddled with parsing traps and inconsistent behaviour that catches out even experienced developers
- mcdonje 1y agoIt's because other config formats aren't as expressive.
- foobarian 1y agoAnd furthermore I find it remarkable how much people like the visual format where you indent nested things with whitespace. I'm pretty sure it's the main reason Python took off as well.
- nucleardog 1y agoIt's the least-annoying option in a lot of cases. JSON is for computers. Writing and editing by hand is not great. Escaping things sucks. A simple multi line string or something gets really awkward. XML goes too far the other way... it's annoyingly verbose to write by hand. Escaping can get annoying. It often allows you to represent data structures that are not easily representable in various languages. INI sucks because it lacks a specification. It also sucks for nested data. TOML fixes this by essentially specifying a better INI file. Much like an INI file, this falls apart at any real level of nesting. EverythingElse is not widely supported. When it comes to basic configs and stuff humans need to work with, I usually start with a basic K=V format. Writing a "parser" in any language usually takes about one minute and has no dependencies so is an easy win. As soon as a use case grows beyond that (quoting, explicit typing, multiple lines, escapes, whatever) I just move to YAML. It's not the best, but it's easily available and the least bad from my point of view.
- raisaguys 1y ago[flagged]
- mavamaarten 1y agoI despise yaml. On top of the points from the article, I never know where to indent and how whitespace is handled on multiline fields. Just a yucky standard all-around
- al_borland 1y agoWhitespace gets weird with indenting code. I use block scalars constantly now, with liberal use of the trimming dashes all over the place. Any time I need to preserve some indentation in my result, I always hate the formatting I’m left with, especially if there is logic involved.
- seiferteric 1y agoI wonder if you could make a new standard something based on yaml where every value was prefixed by a type so there is no ambiguity.
- Titan2189 1y agoObligatory https://xkcd.com/927/ https://xkcd.com/927/
- psnehanshu 1y agoYup, author made RCL
- juliend2 1y agoWe'd need a "YAML, the good parts".
- speed_spread 1y agoIt's called StrictYAML.
- vjvjvjvjghv 1y agoIt's really interesting that after all these years we still don't have a document format that just works. They all suck in their own sweet ways and we still have culture wars over them.
- shadowgovt 1y agoPerfectly normal YAML document detected. More seriously: this is a good overview of the reasons I dislike YAML as a web configuration language. There's too much overlap between the "friendly" auto-type-determination in YAML and the symbols used in web tech, from colons to Norway having a TLD. It wouldn't be so bad if yaml parsers could use expected type of each value as a hint, but that's not a feature in any parser I've met, so I'd rather just not use yaml for anything that's going to end up describing a web service.
- privatelypublic 1y agoCan't take this seriously if XML isn't listed as an alternative.
- Someone 1y agoFTA: Xml is noisy and annoying to write by hand
- privatelypublic 1y agoSo, at what point does YAML needing magic incantations, wrapping everything in quotes, avoiding any form of templating, etc. stop being less verbose (oops, meant noisy), and "annoying?" Reality is, clunky XML is badly designed, or simply has no schema attached.
- simonask 1y agoI never really understood why nobody ever just forked YAML and took out the ugly bits. It’s not a very complicated parser. In the mean time, I’m very much enjoying KDL.
- esafak 1y agoTOML
- mcdonje 1y agoIMO, JSON, YAML, and TOML should all interpret all keys as strings, and only enforce quotes when syntactically necessary. So, `key1` is a string and doesn't need to be quoted. `12345` as a key is interpreted as a string (because keys are strings) and doesn't need to be quoted. `"key 1"` has a space, so it needs to be quoted.
- edoceo 1y agoWe'd have to change the spec and then all the core libs. Big task. Use more quotes, use yamllint. Like bash, more quotes and shellcheck.
- sceptic123 1y agoWhat does IMO configuration look like
- psnehanshu 1y agoIMO means "in my opinion", or if you were being sarcastic, putting /s helps.
- lerp-io 1y agothe problem is that yaml came from geeked out devops employees that used bash where as json came from javascript.
- YouWhy 1y agoI came to regard YAML as a kind of a syntactic HFC syrup, a bearable idea that was taken too far. Alas, YAML is just about everywhere, so the chances for a replacement that'll be both better behaved and as ubiquitous are unfortunately slim.
- bilekas 1y agoI have always thought that there is a place for YAML but I do tend to avoid it when I can. I will say while working with terraform I have absolutely falled in love with HCL. It makes a lot of sense to me and there are a lot of validating you can do along the way leading to much more confidence in larger setups. iAC in my case at least.
- wingi 1y agoThe norway problem is well known.
- rsynnott 1y agoBut, of course, _all_ yaml documents are from hell.
- tdkiran 1y agoI honestly don’t get how YAML became so popular and widely adopted. When compared to YAML, JSON is definitely my go-to format.
- apexalpha 1y agoUp until now I thought YAMl was just json with all the special characters like { } replace by \n and stuff to make it human readable. I had no idea it was even so opinionated. Mostly I use it for docker and k8s configuration, so I haven’t run into it yet I suppose
- lambdaone 1y agoWhat's needed is something that is simple for humans to read and write, has a stable definition, and a clear and unambiguous syntax and mapping to data objects. None of the systems I've seen achieve all those goals at once. YAML, while at first sight a good idea, is irredeemably broken and should be deprecated for further use. JSONC (https://jsonc.org/ https://jsonc.org/) is backwards-compatible with JSON, and a good target for long-term future migration. .INI format works well as a structured subject-predicate-object tuple store for simple use cases. We're probably going to have to live with that indifinitely, until someone comes up with a proposal that is better.
- gu009 1y agoTailscale also have HuJSON: https://github.com/tailscale/hujson https://github.com/tailscale/hujson
- telliott1984 1y agoI think I've tried to start using anchors at least once every year or so when I get annoyed with a particularly repetitive file. Never managed to get my head around it. Just seems so shoe-horned in and if anything makes the document harder to follow.
- jrmg 1y agoAmazed that there are no comments yet mentioning HUML: https://news.ycombinator.com/item?id=45335129 https://news.ycombinator.com/item?id=45335129 It was on the front page yesterday! Human-oriented Markup Language HUML is a simple, strict, serialization language for documents, datasets, and configuration. It prioritizes strict form for human-readability. It looks like YAML, but tries to avoid its complexity, ambiguity, and pitfalls.
- larkost 1y agoIf anyone wants to raid some code for simpler YAML, I wrote a version for the RethinkDB tests a long time ago: https://github.com/rethinkdb/rethinkdb/blob/main/test/common/parsePolyglot.py#L29 https://github.com/rethinkdb/rethinkdb/blob/main/test/common... The problem I was trying to solve was that our tests involved a lot of things that looked like dicts (in fact they were), so my YAML-like parser stops parsing things when it looks like we have hit test code. This took out so much escaping, and made it easy to copy-paste tests into a REPL when you were working on the test (and vise-versa). So it looks like YAML, but without most of the features, and without the footguns.
- xg15 1y ago> While keys in json are always strings, in yaml they can be any value, including booleans. TIL that yaml and json do not have the same data model and there are yaml documents that are not representable as json...
- xg15 1y ago> There exist various extensions of json that extend it just enough to make it a usable config format without introducing too much complexity. Json with comments is probably the most widespread, as it is used as the config format for Visual Studio Code. The main downside of these is that they haven’t really caught on (yet!), so they aren’t as widely supported as json or yaml. What blew my mind was learning that the entire JSON grammar is included as a subset in the YAML grammar. So every valid JSON document is automatically a valid YAML document. But you don't have to stop there. You could also mix and match the JSON grammar elements with the additional "proper YAML" ones - including comments. So this means any* software that accepts a YAML config would also accept the config as JSON or JSON-with-comments instead. No ecosystem bootstrapping necessary! (*or almost any, as long as they don't use dicts with non-string keys)
- jcgl 1y agoI often make use of that when dealing with unholiness of tempting yaml with jinja in Ansible; instead of faffing around with getting yaml whitespacing juuust right, you can dump whatever python object you have right into json inside your yaml template. Pretty-print the json if you want, or just stick a blob in there.