To YAML or not to YAML, that is the question

In Defense of YAML :: Posit Open Source

Blog

May 21, 2026

Best Practices

In Defense of YAML

A common refrain among developers: YAML is bad and TOML is good. This post argues otherwise, tracing the history of configuration formats, examining what YAML 1.2 actually fixed, and introducing py-yaml12, a new Rust-backed Python library for working with the modern spec

Rich Iannone,Tomasz Kalinowski

Every programmer has opinions about configuration files. These opinions tend to be strongly held and inversely proportional to the stakes involved. In the last few years, the consensus view has shifted: YAML is bad, TOML is good, and enthusiastic users of YAML just might be plainly uninformed. This post takes a different view. We intend to present an argument for YAML which is grounded in history, its specification, and the state of tooling in 2026.

The case against YAML was, for a long time, a reasonable one. The format attracted its critics for real reasons, through years of surprising behavior that burned even careful users. But the specification evolved, and the tooling is finally catching up. To understand why the current consensus is outdated, we need to trace the lineage of configuration formats themselves, because this sort of argument has played out before.

A brief history of configuration formats#

The INI file emerged in the early 1980s alongside MS-DOS and the first versions of Windows.1 It was the simplest thing that could possibly work: key-value pairs, grouped into sections denoted by square brackets, with semicolons for comments. They are flat, readable, and human-editable. For the needs of that era (like configuring device drivers, specifying font paths, or setting application preferences) it was entirely adequate. Its only real limitation was structural: you could not nest deeper than one level, and there was no formal specification, which meant every parser implemented its own dialect. But for two decades, this was fine.

[boot] shell=COMMAND.COM device=HIMEM.SYS

[display] resolution=640x480 colors=256

Then came XML. In the late 1990s, the enterprise software world adopted angle brackets broadly. XML could represent arbitrary hierarchy. It had schemas, namespaces, transformations. It was self-describing. For a while it seemed as though the debate was settled. But XML configuration files grew large in practice. Anyone who maintained a Java web.xml or an Ant build file in 2003 knows what it was like to edit dozens of nested elements just to change a database connection string. The verbosity made the files difficult to maintain by hand, which is precisely what configuration files demand.

myServlet com.example.MyServlet

database.url jdbc:postgresql://localhost/mydb

JSON appeared as the lightweight reaction. Douglas Crockford, who claims to have discovered rather than invented the format,2 offered the simplicity of the JavaScript object literal: curly braces, square brackets, quoted strings, and a tiny set of types. JSON displaced XML in web APIs through the late 2000s and early 2010s. But as people began using it for configuration (rather than machine-to-machine data exchange), its limitations became apparent. JSON has no comments. It has no multiline strings. Trailing commas are illegal. These are reasonable constraints for a serialization format, but they make JSON miserable for files that humans must author and maintain. The removal of comments from JSON’s spec was, according to Crockford himself, motivated by people abusing them for parsing directives.3 It was the right call for data interchange, but it left a gap.

YAML (2001) and TOML (2013) each arose to fill that gap, and both positioned themselves explicitly against what came before. YAML offered the full expressive power of a serialization language (including arbitrary nesting, multiple documents, references, and custom types) with a syntax built on indentation rather than brackets. TOML, created by Tom Preston-Werner a dozen years later, was a reaction to YAML’s complexity: it aimed to be a “standardized INI” with explicit typing, obvious semantics, and a formal specification.4 The pattern repeats in each generation: the previous format’s excess becomes the new format’s founding grievance. What is interesting about the current moment is that YAML’s problems were not inherent to the format’s design. They were artifacts of a particular specification version and the parsers frozen on it.

The case against YAML (as it was)#

The criticisms of YAML are not fabricated. They reflect real experiences that real programmers had over many years.

The most infamous problem is the Norway incident, which has become shorthand for YAML’s implicit typing behavior. In YAML 1.1, the bare scalar NO was interpreted as the boolean value false. This meant that a list of country codes would silently transform Norway into a falsehood:

# What you wrote: countries: - dk - fi - is - no -...

To YAML or not to YAML, that is the question

Related Articles

Amazon, Facebook, FBI have access to a private intelligence-sharing network

SpaceX not the behemoth everyone thought

The Mirror Is Part of the Machine

Elevated error rates on requests to multiple models

Donald Trump and sons to be 'forever' exempt from tax audits