As developers we write a lot of code, but we also deal with a lot of configuration files.

The three major formats I tend to use day to day are:

• JSON
• YAML
• .env

And, they all kinda suck. JSON feels like it should never have become a format that people hand-write. So many quotes, and and configuration files need comments to tell users why certain decisions were made. .env has a specific purpose (and it’s ok at that), but it’s not a great universal format, and YAML has always been difficult to read and write to me. I can somehow never retain the syntax and end up copy-pasting things from examples.

Why YAML is difficult for me

A small example from Github workflows/actions:

steps:
  - uses: actions/checkout@v2
  - uses: actions/setup-node@v2
    with:
      node-version: 14
      registry-url: https://registry.npmjs.org/
  - run: npm ci
  - run: npm publish

I couldn’t tell you why uses has a dash in front, and node-version does not. If there’s a difference in how a YAML reader outputs them, I’m not sure how I would be able to retain this while writing YAML.

I also use/love home assistant, which lets you write some pretty cool automations using YAML. I wanted to play with this but it’s been a barrier I’ve not been able to overcome. I don’t know if it’s me. I’m been working as a programmer for 22 years. I’m decent at it, but when when I chat with some of my peers (hi mhum!) they did not share my sentiment.

YAML can also have very surprising behavior, with casting types:

From the linked article, this:

- country1: ca
- country2: no

Becomes:

- country1: ca
- country2: false

It’s a bit cherry picked, and I’m sure there’s YAML linters out there that help avoid the pitfalls, but in my mind configuration files should be simple.

There’s some configuration formats I like, such as TOML and JSON5. They strike the right balance to me with being easy to read and write, unambigious, supporting comments, strictness and not being incredibly hard to write a parser for.

TOML is like ini files on steroids, and JSON5 is JSON but with fewer quotes, comments and multi-line strings.

I could write my NPM configuration file as package.json5 and automatically convert it to package.json but that feels too surprising. My projects are already kind of eclectic, so I want the ‘plumbing’ to be unsurprising. Plus there’s the whole chicken and egg thing with needing a JSON5 parser before we have dependencies.

I’d love the NPM project to adopt JSON5. It seems like a great fit. JSON and YAML can’t be the final word for human-maintained data formats. It’s so obviously sub-optimal.

If NPM adopted JSON5, I would annotate so much in my package.json. I’d document why a dependency is needed, why we are stuck using a previous major version of a dependency and what the purpose is of each script.

I wouldn’t know what format would be ideal for Github Actions. Maybe the answer is ‘nothing’ and they need a good DSL.

And while we’re at it, stop polluting my projects root directory! Can’t we all agree on a .meta directory for finding configuration files?