A respected senior engineer once told me "all configuration is code, if it modifies the behaviour of software, it needs to be testable"
Yaml is huge unintuitive PITA, I recently spent multiple hours figuring out the best way pass CLI arguments to a k8s cronjob via yaml. I only managed to solve the weird error messages after I stumbled upon the stackoverflow post linked in the webpage https://stackoverflow.com/a/21699210
> There are NINE (or 63*, depending how you count) different ways to write multi-line strings in YAML.
>> There are NINE (or 63*, depending how you count) different ways to write multi-line strings in YAML.
I hate to be the YAML defender, but I strongly believe that all of YAML's block and flow scalar types are necessary and that YAML's string handling is one of its killer features. Sometimes you need C-style string escaping with "" and sometimes you need verbatim strings with '' (same use-cases as verbatim string literals in programming languages, eg. for regexp.) Sometimes you need collapsed newlines and stripped trailing newlines (writing a description for your blog post in YAML frontmatter) and sometimes you need preserved newlines (embedding other languages like Markdown or Bash in a YAML document.)
A language like YAML should let you represent different types of strings in a way that's still human readable.
What do you mean by “arbitrary”? If you don’t want it to access the network or whatever, that’s definitely possible. If you don’t want it to be able to loop forever, though, Turing-incomplete languages like Dhall exist, but that doesn’t stop them from expressing “loop for a trillion years” — but you can always say “we’ll execute this config file for a second and then halt with an error if it isn’t already done”. (You can also pipe an infinite stream into a FIFO and trick your program even if it uses a dumb config language.)
The problem with turing-complete config languages, is not that it might take long to evaluate them. The problem is they are hard to modify by programs. A purely data-driven configuration, e.g. an ini-style config file, json, or xml is relatively easy to parse, transform and unparse again. Doing that with a config file written in a Turing-complete language is substantially harder, theoretically even impossible. But in practice most configuration are evaluated from a subset of all programs. A language like Dhall tries to formalize that subset and and thereby enables better processing of such programs.
Is json code, too? Yaml, or json, can be used to describe programming instructions, in which case I could see maybe calling it code. In an informal setting. If you are, for example, writing documentation, please refrain from doing so.
But that's entirely situational. A yaml snippet containing my list of groceries is not code.
Yaml doesn't have to be classified as code to be testable. "We should have tests for our configuration files" is perfectly reasonable.
I’m amazed this is even a question. Of course it is! It’s explicitly defined as an interchange format. Its only purpose is as code.
> In an informal setting.
What formal settings are we supposed to be satisfying?
> If you are, for example, writing documentation, please refrain from doing so.
I respectfully decline this request.
> But that's entirely situational. A yaml snippet containing my list of groceries is not code.
> Yaml doesn't have to be classified as code to be testable. "We should have tests for our configuration files" is perfectly reasonable.
I mean this with kindness and sincerity, if a little incredulity: maybe your definition of code is ambiguous and warrants some clarification. To me, this isn’t a holistic definition but it certainly seems like a relevant starting point: if it has a syntax specification that machines can use, it’s code.
The most useful definition (for engineering) is that "code" changes/defines how the program executes. Your YAML shopping list changes your path through the shop, so it is code.
For non-trivial programs the configuration space is so large that it's impractical to test every single configuration during development, so instead the operators are expected to test before putting into production.
A python script could be a text doc if you open it in a markdown editor. A yaml file could execute web call if run through a program with a parser.
It is all up to the interpreter you give the code too. Your program that takes yaml config is an interpreter, though probably a very limited one and hopefully a safe one (though that needs to be tested / checked for to be more sure of)
When I observe the world, I come to a different conclusion. I see people including non-programmers talk about HTML as code. I see software packages like editors that say they deal with code, and it's not about T-c languages. Encyclopedias and dictionaries record the definition of code very broadly as interpretation of information, not T-c languages specifically.
So without engaging the ongoing absurd debate about HTML or CSS… can you really say that SVG isn’t code? Forget what “most” would say. In your heart of hearts, can you write <path d="…anything at all"/> and not consider it code? What a disappointing pissing contest.
I know it is unpopular nowadays, but it really helps understanding between people if we stop redefining terms all the time. So, let's have a look at what a dictionary definition (taken from [1]) of code is:
1. a systematic statement of a body of law
2. a system of principles or rules moral code
3. a. a system of signals or symbols for communication
b. a system of symbols (such as letters or numbers) used to represent assigned and often secret meanings
c. coded language : a word or phrase chosen in place of another word or phrase in order to communicate an attitude or meaning without stating it explicitly
4. genetic code
5. instructions for a computer
Relevant to the discussion here are points 3 and 5. I would argue json, yaml, and xml, would be called code under points 3 as well as 5.
They are hard-core descriptivists; if they can find an attestation for some usage, however contradictory or plain wrong, they will list it in their lexicon. E.g. "literally":
"In a completely accurate way; a story that is basically true even if not literally true".
"In effect, virtually; used in an exaggerated way to emphasize a statement or description that is not literally true or possible"
So according to M-W, "literally" means the same as "not literally". Merriam-Webster debauch the English language.
Interesting points. Because English is not my mother-tongue, I wasn't aware of perceived quality of that dictionary. I chose Merriam-Webster simply because it was the first hit in my online search. Which English dictionary do you consider better?
But, I still find it important to look at definitions that are actually used out there. Some scientific papers I've read just redefined everything to fit their purpose. There is a fine line between making it practically impossible to communicate ideas based on common understanding of terms, and allowing those terms to evolve. Anyway, I am convinced it is a bad idea to try to "feel" or "impulsively answer" the question is json or yaml code. To answer such a question every intelligent person should, IMHO, remember or lookup the relevant definitions and then try to find a conclusive argument why something answers the question. It might also be important to reflect on the quality of the used definitions. Sometimes, definitions should be changed. But changing a definition should always consider many different use-cases and perspectives, otherwise it becomes a single-use tool. And such a definition is not worth it.
> Which English dictionary do you consider better?
I generally rely on the OED; my bookshelf dictionary is the Concise Oxford Dictionary (it's not "concise"). But the OED is also descriptivist. In the full version of the OED, they give multiple attestations for each meaning (citations, dates, author and so on). That means you can form a judgement about how to use or interpret a word, quite independently of the definitions the lexicon proposes.
I don't know of any English dictionary that isn't basically descriptivist. But I think M-W is pretty far along the descriptivist scale.
I used to have a copy of the Chambers Etymological Dictionary. That was good, because it provided an explanation of every definition it gave. Even if the definition was dubious, you knew why they were offering it.
I don't hate on descriptivism; usage needs to be described. It just pisses me off when a dictionary defines "literally" to mean "not literally", in the very words of their definition of "literally".
You seem to have pretty good mastery of English, if it's not your mother tongue.
Configuration and code: you could argue that code is simply configuration for a processor. I certainly wouldn't want to have to make the case that there's a difference.
> They are hard-core descriptivists; if they can find an attestation for some usage, however contradictory or plain wrong, they will list it in their lexicon.
AKA their dictionary accurately reflects language usage; the opposite being prescriptivism, wherein you reflect the language as you wish it was rather than actual usage.
For all of its warts, YAML hits the sweet spot between readability, writability, commentability, and (mostly) intuitive syntax. It's easy to serialize complex objects to, and comes bundled with Ruby's runtime.
There are a lot of valid complaints about YAML, but I still reach for it when I really only need a barebones configuration file.
> For all of its warts, YAML hits the sweet spot between readability, writability, commentability, and (mostly) intuitive syntax.
Could not disagree more strongly and it seems many others in software agree, based on this comment section and the original article.
> It's easy to serialize complex objects to, and comes bundled with Ruby's runtime.
I don't know that Ruby support is why it's widely adopted. Ruby is common in some spaces, but not a wildly popular language at all.
I honestly think some popular project (maybe Docker Compose or something from HashiCorp?) used it for a config file and then everyone else started doing it too.
> Could not disagree more strongly and it seems many others in software agree, based on this comment section and the original article.
They sure do! But lots of people also agree, as evidenced by people continuing to use it. The world keeps turning, and we engineers keep using suboptimal things.
> I don't know that Ruby support is why it's widely adopted. Ruby is common in some spaces, but not a wildly popular language at all.
Ruby’s now gone out of fashion, but it was the most popular web development language (especially among startups) for the better part of a decade. It’s conjecture, but I wouldn’t be remotely surprised if Ruby brought YAML into a lot of shops by virtue of bundling it. Docker (and Docker Compose) came into full force a few years into Ruby’s peak, so it’s the egg to Ruby’s chicken. And we’ve all forgotten that Hashicorp was originally a Ruby shop!
> I honestly think some popular project (maybe Docker Compose or something from HashiCorp?) used it for a config file and then everyone else started doing it too.
Kubernetes maybe? It also supports JSON but JSON is less friendly to manual editing and source control IMO.
Anyway, sure, a lot of people in software disagree. For almost any opinion you might have, you could find many to agree, and many to disagree.
Travis CI predates Gitlab CI by several years, and uses YAML. Definitely a big source of peoples’ YAML experiences these days, but not one of the original ones.
If you've ever tried managing complex, human-centric configuration in JSON, XML, ini, or most any other format, you realize it ticks a lot of the checkboxes that are necessary for a good human-readable configuration format:
Requires some amount of legibility out of the box due to whitespace requirements.
Can store complex data structures (and even direct JSON).
I like TOML a lot, but it still misses a few of the checkboxes: it’s not actually bundled with Rust, and the table syntax is pretty unintuitive (IMO) compared to YAML’s array-of-dictionary syntax.
It has no big boobytrap for beginners, on simple enough patterns it looks very clean and simple, it allows comments while being easy to convert to JSON.
I think these are the main things that push yaml. In particular, being clean and simple for straightforward data is a big plus: configurations are often just key-value lists of ver small strings, having something that is readable and looks simple helps a lot.
And for anything that needs more finesse, switching to XML or JSON is often supported.
The same reason visual programming languages keep making a comeback: people keep thinking they could make programming easy if they could just get rid of that pesky "code" part.
Really I think what the popularity of YAML is saying is that we need a vastly simpler programming language.
Most programming languages are written to impress other programmers. We need a programming language which is trivial to learn, which you couldn't ever use to write a webserver, but you would use it to configure one.
On the contrary, I think the popularity of YAML says that most people want a horribly complicated language that will guess what they mean and so feel simple to write, rather than a language that's simple to understand. It's the language equivalent of tag soup, or Perl.
Something like Dhall is much better for long-term maintainability. But people don't want a language that makes them write consistent, maintainable code. They'd rather have a language where you can leave the quotes off your strings and it will work most of the time except when it doesn't.
that's what i'm talking about. people don't want to know about first class functions, closures, immutability, monads, object orientation, polymorphism, inheritance, generics, contravariance, covariance, threading, concurrency, race conditions, memory safety or package managers. they just want to whip up some shit and have it work.
and you're right they don't care about long-term maintainability at all. that leads to all the conceptual overhead though. they'd rather have a horribly bolted together language than be forced to worry about the concepts that lead to long-term maintainability.
No, I don't think so. That is still aimed at programmers and looks like it has decent threading support and you could write a webserver in it.
I'm thinking more like an actual shell scripting language where you have control flow, some modularity, good support for dealing with unstructured data and the ability (for software developers) to plug DSLs into the back end of the language and expose them to end users to use, and that's about it. First class functions, closures, immutability, object orientation, etc would not be in the language to keep it conceptually simple. This would render the language pretty useless for building applications out of it, but the point would be to gear it more towards people who didn't know those kinds of compsci concepts at all.
The goal would be the least amount of conceptual overhead possible and therefore the most amount of accessibility.
There are parsers for it in every language, and it's more capable than JSON.
Here's what I want. Something that is more readable than JSON, so either TOML-like or YAML-like, but without executable code or any of that nonsense. On top of that, a schema definition file (think XSD) that asserts facts about the structure of the config, using a theorem prover like Coq or Idris.
This way, we get nice configs, but within a restricted space.
Sure. That’s not a YAML problem as it’s not part of the spec. Someone could to the exact same thing with JSON and use a custom spec that is a string starting with a bang and executes it.
I think the reason people don’t is that JSON is terrible for writing my hand and YAML isn’t.
I think the main idea is to have a config file standard that can be used across different project regardless of the language / tool used?
A benefit is that knowing yaml may at least give you the ability to configure the system, even if a project is built using an unfamiliar programming language.
Sometimes people that can read code, like most of us here, don't get bothered by tokens like "{" or some of the more complex hierarchical structures but for someone that doesn't want to learn/understand code YAML is much more appetizing.
IMO "configuration languages are bad" and "YAML is bad" are two very different discussions. Mixing them up takes away from both.
Most of the complaints against YAML are really complaints against complex systems (Kubernetes, CI pipelines) which use it as their interface. The rest of the problems can be solved by quoting your strings.
YAML works perfectly well if it is (1) used for the right use cases rather than as a substitute for code and (2) paired with a linter or parser which handles its quirks.
> The rest of the problems can be solved by quoting your strings.
How do I get all of YAML's millions of other users to quote all of their strings?
What about programmatically generated YAML?
Also, you're entirely ignoring two other major issues: meaningful whitespace (making YAML hard to read and write) and multiple ways of doing the same thing (making it confusing).
- For your own projects use yamllint, put it in your CI pipeline, and your pre-commit hooks. You can forbid the use of flow sequences like [ and {, require quotes, and forbid truthy values for bools.
- USE JSON-SCHEMA. It works on YAML.
- For programmatically generated YAML just generate JSON and call it day.
- If you have a tool that for some reason requires YAML but not JSON then don't write YAML. Write your config in $programming_language and only dump the YAML at the end. Troposphere is a Python library for CloudFormation JSON that embraces this idea.
- Don't template YAML files (or JSON for that matter). Again just use variables in your programming language of choice and then dump. Helm is an abomination and the authors should be ashamed of themselves. Ansible had the common sense to only allow templates in the values instead of at the file level.
That link is from more than 10 years ago and is no longer accurate as of YAML 1.2[1].
Perfect JSON compatibility has always been a stated goal of YAML and is something they consider to be a bug when it's found to be broken at the spec level.
If you read the linked document carefully, then you will notice that YAML 1.2 existed twelve years ago, the incompatibility has not been addressed as suggested and remains still a problem for the end users.
Developers seem to complain about anything that takes a little bit of memory and care. To a limited extent, that's not a bad thing--our brains have limits. However, when the benefits outweigh the costs, complaining about it is a bad thing.
Regular expressions are a good example. Developers seem to hate them. I find them easy and intuitive, and I'm not the sharpest tool in the shed. However, I will take some care to commit some stuff to memory and make some notes. That's it. When you know what characters are magic, know what the special characters mean, they're extremely straight-forward except when they're very complex.
Same thing with YAML. It's got a couple of rough edges, but the complexity carries its weight, and most of the difficulties go away if you bite the bullet and memorize it. Just commit those block chomping operators to memory, it doesn't hurt that much, then you can get on with your life and quit complaining about YAML and make it work for you.
Writing it is not the only problem though, you should also be able to read it. What if the person who wrote it was not using your conventions? There are numerous, subtly different ways to accomplish the same end result in YAML.
YAML's not bad if you couple it with strong types. I used YAML _heavily_ and wasn't aware of any of the issues that the author mentioned because of the types. It doesn't let YAML automatically parse dates because the destination structure is either a date or a string or whatever, and that controls the parsing. It doesn't have the Norway problem because it knows whether a field is a boolean or not. I don't think it had the octal problem, not 100% sure though.
It's very good for non-technical people to edit because they are allergic to symbols and quotes and brackets and making sure things match. YAML's syntax let you write like you're a CEO sending agenda notes to a subordinate. You can easily switch between line-per-item and brackets-style and you do so whenever the readability is improved by doing so. It's highly intuitive somehow. You can pretty much turn someone into a config-editor just by showing them an example file, especially with syntax highlighting.
I strongly disagree. Being whitespace sensitive it's stupidly bad for non-technical people.
I don't like YAML for several reasons, to be honest I'd prefer an .ini based config setup or BSD styled "option=variable" config file paradigm. But I hate/despise/loathe the fact that YAML files are whitespace sensitive. That's a horrible choice. I hate python for it too, and avoid it's use whenever possible.
Maybe my people were special in some way, but it seemed like the idea of lining things up vertically just immediately clicked with them. It seems like it's something that folks do in their regular lives when writing (hand-written) notes or on a whiteboard.
People have strange trouble with delimeters. They put commas inside the closing quote, (e.g. ["hello," "there"]) because I guess that's how they were taught in English class somehow. They forget a bracket and then can't figure out how to fix it because the tools are no help. They start putting in excess braces like they're some type of Simon Says: [{"hello"}]. I guess I can't be critical -- this is a lot like how I write CSS. But whitespace makes more sense to a lot of folks because it just "looks right".
TOML is a decent format because it does use whitespace for delimiting -- but only newlines. It gets verbose if you want to represent large amounts of deeply-nested data, though.
It used an off-the-shelf library, I don't remember which one anymore. I don't think it really matters though -- YAML is a format, not a parser.
Per the YAML docs [0], "Creating a fully compliant parser has proven almost impossible." Pretty much every YAML parser out there is going to have its own idiosyncratic subset that it handles. That doesn't make the _files_ not-YAML.
(This does make YAML a horrible data exchange format. No argument there!)
I strongly believe that if Crockford hadn't refused to add comments to JSON that YAML, TOML, and other generally bad configuration languages wouldn't exist.
There are other things that make JSON a bad configuration language with poor human readability and writability. Lack of multi-line strings is a big one. The requirement to put a comma after every array item and object member except the last has made me write more syntax errors in JSON than I've ever written in YAML. Also, JSON is unsuitable for config files with lots of Windows-format paths, since backslash is its escape character.
I don't hate yaml. It's a bit overcomplicated, a bit too cute, but it works. It doesn't leave a lot of room for additional complexity, though.
I've been using Ansible a lot recently. I like it a lot, most of the time. Its configuration files are YAML + Jinja2 templates + Python expressions. It works fine for the basics but when you push it quickly devolves into madness.
e.g. I had a task like this:
- set_fact:
foo_bar: >
{{ item | map(attribute="something") | rejectattr("bar", "none") | flatten | select is any }}
Can you spot the error? The block scalar header `>` was missing the hyphen `>-`. YAML helpfully added a newline to the end of the template output. Python helpfully interpreted "False\n" as `true`.
I'm starting to think I should write Python modules for anything complex.
This is exactly why I love Ansible. It has libraries to handle most of what I need, and most of what I need to do is just simple YAML expressions. When it gets complex though, it's first-class supported to drop into Python (or anything else which works as an executable script language) to get more control.
For cases where the query is truly static, I prefer to just write SQL.
Building SQL queries by concatenations strings, however, should get you arrested for negligence. If you need a query builder, then you need a query builder.
The points in this post reminds me of the “configuration clock”[1]. Hardcoded -> configure file -> rules -> DSL -> Hardcoded. Maybe it should be the “configuration ouroboros”. Provides one explanation for why this config becoming code situation occurs over and over and what to watch out for.
This came up in a recent podcast. They thought that the plain clock model doesn't account for real progress being made, and that a better model is the "configuration spiral": it looks like the clock when viewed from above but shifting your perspective a bit reveals that it's actually a spiral that describes how to build abstraction layers. Not that we hit the mark every time, but that a clock is too reductionist.
Precisely. In a case at work, I’ve found that some YAML is complicated because the abstraction level at which it’s describing things is too low; the fix is to move a most of the logic into code and keep some minimal flexibility in the YAML (or use SQL instead, though that choice is more about who we want to empower to edit it).
I think it has the right take on configuration vs code but being a new language it's lacking a lot of basic things like package management, lot's of bugs and in my case - scaling issues.
Been using it for the docker compose that builds my entire homelab (~30 services, fairly complex config) and I love it. It's saved me from some really nasty bugs a handful of times.
So what should one use for configuration? I am not going to use JSON because of lack of comments. A configuration file needs comments. TOML does the job for this well, I think.
I've taken a massive liking to JSON5[1] recently for configs, but I've never really seen anyone else using it. Sucks, because I think it's really easy to read and write.
I find YAML, for all its flaws, to strike a lot better balance between usability and clarity than the alternatives. But whatever, people have their own preferences.
Ultimately, I don’t think it would be possible to avoid the sorts of problems people run into in any configuration language unless you have a strict type system on the config itself. But strict type systems on config have been tried and end up causing their own distinctive problems.
In the end people will complain about whatever their interface is to a complex system. They will always make errors in configuration and that will always be annoying.
I don't think the point is another configuration language, much as it is to use real programming languages where appropriate. By using TOML you'd make the tasks where YAML is used even more cumbersome to write...
If I have to choose one, I’d choose the first one. It really does fix most of the warts. But there’s probably a fundamentally better approach somewhere out there if you can find it.
Yes, it lists alternatives, but none of them is "see, use this, it's better". They all have different tradeoffs, otherwise there wouldn't be that many :)
After evaluating several config file formats, I settled on JSON5 for work projects. Only issue for me is that sublime text doesn't have highlighting for it, though the hjson highlighting from package control works well enough. I should write one for JSON5...
Ironically the file format for sublime highlighting plugins is in YAML.
Is there really a better alternative? JSON is a horrible format for configuration, KDL is a cute idea in theory but in practice it makes me want to gouge my own eyes out, CUE is... weird, XML and INI should've been dead for years and TOML is just INI on meth...
At least JSON and YAML are somewhat interoperable (JSON is valid YAML* and converting YAML to JSON is trivial) and have native support in most modern languages...
Taking a step back; this website is a piece of Art.
Its message stirs passions, it is written in the very formalism it talks about, and presented in a so unusually cumbersome way that it triggers the same kind of response (or questions) a surrealist setup do (essentially boiling down to: "why the f...?").
It's so strange that they did this because YAML looks nothing like JSON. The entire point of a standard is to impose constraints to ensure that different people will do things in the same way... That's how you achieve compatibility between different systems.
When you have a flexible standard which allows people to do something in many different ways, it defeats the entire point of there being a standard...
I got introduced to YAML back when I first got into Ruby on Rails. At first it seemed really cool, nice to read and write
Then I tried to use it in one of my own projects and immediatly ran into issues. Mostly that it was difficult to judge what data structures you would get.
Massively different syntax could result in the exact same structre, slight changes could make it something completely different. I just really didn't like it :/
Unity uses a subset of YAML as its serialization format, and dear god that is one of the worst choices they’ve made. Very hard to decipher, very hard to resolve merge conflicts, and god awful slow.
YAML is good as a concise configuration description language, but using it as a serialization format for general data should be avoided at all costs.
Yaml is huge unintuitive PITA, I recently spent multiple hours figuring out the best way pass CLI arguments to a k8s cronjob via yaml. I only managed to solve the weird error messages after I stumbled upon the stackoverflow post linked in the webpage https://stackoverflow.com/a/21699210
> There are NINE (or 63*, depending how you count) different ways to write multi-line strings in YAML.