TOML vs YAML

gistfile1.md

EDIT from 2019: Hi folks. I wrote this gist for myself and some friends, and it seems like it's gotten posted somewhere that's generated some (ahem, heated) discussion. The whitespace was correct when it was posted, and since then GitHub changed how it formats <pre> tags. Look at the raw text if you care about this. I'm sure someone could tell me how to fix it, but (thank you @anzdaddy for suggesting a formatting workaround) honestly this is a random throwaway gist from 2015, and someone more knowledgable about this comparison should just write a proper blog post about it. If you comment here I'll hopefully see it and stick a link to it up here. Cheers. @oconnor663

Here's the canonical TOML example from the TOML README, and a YAML version of the same.

title = "TOML Example"   [owner] name = "Tom Preston-Werner" dob = 1979-05-27T07:32:00-08:00   [database] server = "192.168.1.1" ports = [ 8001, 8001, 8002 ] connection_max = 5000 enabled = true   [servers]   [servers.alpha] ip = "10.0.0.1" dc = "eqdc10"   [servers.beta] ip = "10.0.0.2" dc = "eqdc10"   [clients] data = [ ["gamma", "delta"], [1, 2] ]   hosts = [ "alpha", "omega" ]

title: YAML Example   owner: name: Tom Preston-Werner dob: 1979-05-27T07:32:00-08:00   database: server: 192.168.1.1 ports: [ 8001, 8001, 8002 ] connection_max: 5000 enabled: true   servers:   alpha: ip: 10.0.0.1 dc: eqdc10   beta: ip: 10.0.0.2 dc: eqdc10   clients: data: [ [gamma, delta], [1, 2] ]   hosts: - alpha - omega

It frankly blows my mind that anyone can look at this…

[servers]

[servers.alpha]
ip = "10.0.0.1"
dc = "eqdc10"

[servers.beta]
ip = "10.0.0.2"
dc = "eqdc10"

…and conclude that TOML is even a good idea, let alone better than YAML. And don't even get me started on Arrays of Tables. Wtf? For a fair bake-off, the comparable YAML should have been:

servers:
    alpha:
        ip: 10.0.0.1
        dc: eqdc10
    beta:
        ip: 10.0.0.2
        dc: eqdc10

To be clear, I am no fan of YAML for all the reasons cited by others and would be much happier if everyone moved towards Jsonnet…

{
    servers: {
        alpha: {
            ip: "10.0.0.1",
            dc: "eqdc10",
        },
        beta: {
            ip: "10.0.0.2",
            dc: "eqdc10",
        },
    },
}

…which provides stronger safety guarantees while further enhancing readability. Jsonnet is cleaner than JSON, more consistent than YAML, easier to read than TOML, and much more powerful than all three…

// dcs.libsonnet
{
    eqdc10: { dc: "eqdc10", subnet:: "10.0.0" },
    eqdc11: { dc: "eqdc11", subnet:: "10.1.0" },
    ⋮
}

// config.jsonnet
local dcs = import "dcs.libsonnet";
{
     servers: {
        alpha: dcs.eqdc10 { ip: super.subnet + ".1" },
        beta: dcs.eqdc10 { ip: super.subnet + ".2" },
    },
}

But if the choice is between TOML and YAML, there is no contest.

well, the following is a valid toml

[servers]
alpha = {ip = "10.0.0.1",dc = "eqdc10"}
beta = {ip = "10.0.0.2", dc = "eqdc10"}

Skip to the bottom, just to vote for YAML for it's simplicity

TOML is way better than YAML! And if you disagree with me, you're an idiot!

Also:

YAML is way better than TOML! And if you disagree with me, you're an idiot!

well, the following is a valid toml

[servers]
alpha = {ip = "10.0.0.1",dc = "eqdc10"}
beta = {ip = "10.0.0.2", dc = "eqdc10"}

@ahmubashshir Have you seen any TOML actually written that way? I don't care about hypothetical usage, only real-world usage. Plus, this is a necessarily simplistic example. Real-world configs are often deeply structured, with objects of arrays of objects of arrays all over the place. Consider even basic GitHub Actions or k8s deployments. You could argue for TOML for simple cases and YAML for complex cases, but now you have to deal with two config languages for no particular reason and it'll be even more painful if you start with TOML and the schema's complexity later grows beyond what's reasonable for TOML.

@anzdaddy Machine-generated TOML is an example of where that is useful. For example a file starts as hand-edited configuration but then there is a UI tool that needs to read that file, make some changes to the data and then write it back out. In this case there might be a deeply nested and complex object that is convenient to emit in that longer form using {...}. It seems to be a sensible way to keep simple configuration simple but also allow these deeply nested things to exist in a succinct-but-ugly form as needed.