One of my problems with YAML is its sheer complexity

May 1, 2019

YAML is unarguably a language, with both syntax (how you write and format it) and semantics (what it means when you write things in particular ways). This is not unusual for configuration files; in fact, you could say that it's absolutely required to represent a configuration in text in any way. However, most configuration file languages are very simple ones, with very little syntax and not much semantics.

YAML is not a simple language. YAML is a complex language, with both a lot of syntax to know and a lot of semantics attached to that syntax. For example, there are nine different ways to write multi-line strings (via), with subtle differences between each one. Like Markdown and even HTML, this complexity might be okay if everything used YAML, but of course this isn't the case. Even in our small Prometheus environment, Prometheus uses YAML but Grafana uses a .ini file (and sometimes JSON, if we were to use provisioning).

The problem with a complex configuration file language is that it is not the only thing in the picture. Specifying the configuration itself has its own syntax and semantics, often complex ones; it is just that they are not at the lexical level of 'what is a string' and 'what is a block' and 'how do you define names and attach values to them'. This is actually something that using YAML makes quite clear; your YAML describes a structure, but it doesn't say anything about what the structure means or how you write it so that it means the things you want. That's all up to the system reading the YAML, and it can be as complicated as the program involved wants to make it. Often this is pretty complicated, because the program needs to let you express a bunch of complicated concepts.

Since specifying the configuration is often intrinsically complex, a complex configuration file language on top of that is adding an extra layer of pain. Now instead of one complex thing to learn and become decently capable at, you have two. Dealing with two complex things slows you down, increases the chances of problems, and probably means that you will lose familiarity with the overall system faster once you stop actively working on it (since there is more you need to remember to do so).

Complexity also invites writing your YAML based partly on superstitions. If you don't fully understand YAML because it's so complex, your best approach is to copy what works and modify it only if you have to. This will probably not give you the right or the best YAML, but it will give you YAML that works, which is your real goal. Your goal is not to write perfect YAML, your goal is to configure your system; YAML (and the entire configuration file) is an obstacle in the way that you need to climb over.

(Do I write superstitious YAML? Yes, absolutely.)

Ultimately that is my biggest objection to the complexity of YAML; it puts a substantial obstacle in the way of getting to what you want, an obstacle that is generally unnecessary. Very few configuration languages need the complexity and generality in their configuration files that YAML provides, so almost all of them would be better served by a simpler configuration file language.

(This entry is informed by YAML: probably not so great after all, which covers a number of other problems and traps in YAML that don't concern me as much, partly because I don't think I'm likely to run into them. Via, itself via.)

Written on 01 May 2019.
« My problem with YAML's use of whitespace
Some implications of using offset instead of delta() in Prometheus »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Wed May 1 21:46:42 2019
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.