What is wrong with TOML? (2019)

Scheme lacks most syntactic affordances that imply semantics. Even if some of those implications are dead wrong, they're still useful.

Personally I think the right answer for configuration files is to define them in terms of a generic object model. A program could even support multiple formats (TOML+JSON+YAML). If a user dislikes all the supported formats or the file is generated with something like NixOS, it can be handled with straightforward conversion.

Some do, using s-expr as config files is pretty common in the ocaml ecosystem (ie dune).

...or more famously, Makefiles

It's kinda crazy we have 2 kinds of whitespace.

Even the customizability argument makes less sense now, IDEs could just change the width of leading spaces, I'm not sure why they don't.

Isn’t the whole premise behind this article that, coming from Python where indentation is program structure, that TOML confuses the reader with syntax foreign to the reader?

Like a C++ developer crying foul because inheritance doesn’t exist in YAML.

> I think the primary limitation with TOML is the restriction that in-line tables cannot cross multiple lines. This is not done for technical reasons, it's an aesthetic choice on the part of the designer.

I'm sure you'll be happy to know this is getting relaxed in toml 1.1, wherever that comes out (and the implementations adopt it): https://github.com/toml-lang/toml/issues/516

Though the difficulty will then be knowing whether a given piece of software uses 1.0 (and single-line tables) or 1.1 (and more flexible tables).

YAML has a big problem in that you can't work with it in standard tools.

Most every common GCedlanguage these days supports native JSONlike object, YAML can represent things outside of strings, lists, dicts, bools, numbers, and null.

Lack of nested structure is a positive in some applications. Flat is better than nested. I've seen way too many config files where someone says "add foo=3" to the file and you can't even figure out where in the structure it goes.

And worse, sometimes people reorganize things into options. They'll move all the stuff for one subcomponent into its own nested thing, and you can't configure it without knowing the full architecture.

With flat stuff you get an obvious single way to represent any given config options. Maybe not the nicest way, but it's obvious and unique.

> However, syntactic noise of the form of lots of [s, ]s and equal signs isn't necessarily relevant.

I don't know that ': ' is any better than ' = '. I get being opinionated about it but this feels squarely in the realm of the subjective to me. Further, adding an errant '-' and accidentally creating another object is real common in YAML, which is something you can't do with TOML's lists. I think this washes out, tbh.

I don't find TOML files easy to read/understand.

Especially when I'm scrolling through a file, I encounter myself backtracking to understand again its structure.

> A YAML file can exhibit identical information with fewer characters and that makes the files easier to read and maintain - especially if they are information dense.

I don't think this is a particularly good yardstick. Code without comments is shorter than code with comments, but I wouldn't call comment-less code easier to read; the more information dense, the worse, really.

Thanks for your work!

I first encountered strictyaml years ago and have used it, happily. I especially appreciate that you made clear arguments for what ought to be excluded from a configuration format itself, and how proper validation ultimately requires real code anyway.

I was always disappointed however that your project didn't amount to a formal specification (at least at the time, unsure if that's changed).

More recently I came to know and love NestedText, which seems very close to what a strictyaml spec could be/have been. I'm curious if you've engaged with that project/format, and what you think of it.

Doesn't YAML have the unfortunate issue of ambiguity in the variety of parsing and versions? (Edit: I see you're advocating for a new subset... never mind. :) )

If you want a "language" for expressing data (like configuration data), you might be interesting in having a look at EDN. https://github.com/edn-format/edn

> A YAML file can exhibit identical information with fewer characters and that makes the files easier to read and maintain

According to that logic, binary files would be easiest to maintain and read, which is obviously bogus.

The problem with that is that indentations within indentations are just obnoxious. It is far from uncommon to add an item at the wrong level in a large config file. Worst is when you have a large file that is showing several meaningful lines of indentation on one screen, where the roots of several of those levels is not visible.

There is nothing for this, which is probably fine. Previous thread on this: https://news.ycombinator.com/item?id=36023321

In that specific example not too much, but obviously there's a whole bunch of differences between TOML and JSON, starting with the fact that you can add comments as has already been discussed, and many more.

I would expect so, yes.

It already supports inline tables

Hi, I'm the author of hitchstory.

With the stories in YAML two new use cases (which are demonstrated in the example projects) are enabled:

* Automatically updated how-to docs. I used to write these types of docs manually and if they existed at all they would ALWAYS get out of sync with the code and were painful to maintain manually. Now I have YAML files and a simple jinja2 template I can push out new markdown how-to docs on each new build - with snippets of JSON, screenshots from the app, whatever.

* Tests that rewrite themselves. E.g. if I have a REST API test of the form "call API x and expect y blob of json", I don't have to actually write that blob of json into the test, I just write the code that produces it and run the test in rewrite mode so it updates the "expected JSON" field with actual json. I can then eyeball it and 20 seconds later it's part of the test and part of the docs.

The productivity improvements from doing both of these things means that writing tests is cheaper so I do more of them. Having how-to docs for all scenarios is way cheaper so I now always have them.

These use cases are impossible with pytest. They are impossible with cucumber.

They would be too painful to maintain with regular (i.e. not type-safe) YAML and those stories have enough indents that they would be an epic unreadable mess of syntactic noise if they were built in something like TOML or JSON.

> TOML could be extended to support it.

Seems doubtful as that's specifically something TOML was created not to support. If you want unityped ini files you can define that dialect of ini files.

I especially love the Integrant[1] version which uses the E from EDN (extensible) to add references:

    {:adapter/jetty {:port 8080,
                     :handler #ig/ref :handler/greet}
     :handler/greet {:name "Alice"}}

I like edn but I’m not convinced it’s great for configuration.

First off, it shares the desire for extensibility with yaml (in the form of tags), which is a giant trap. And then it’s quite syntactically noisy.

Too many features that can't be represented in standard programming language constructs..

JSON-alikes are opinionated. They don't let you do stuff that requires a plugin for the parser to work with

Thanks for that, it is interesting.

Is this actually something I want to see in a configuration script? Why not just use a scripting langauge and be done with it? I wonder if the safety features can't be replicated with rigorous testing of say python as config scripts instead of learning yet another programming language?

https://prelude.dhall-lang.org/Text/concatSep.dhall

I think this is the key fulcrum for me: "config is code", sure, but not the same kind of "code".

It -is- compelling to argue for statistically deterministic config code but my practical objection here is 'can we arrive at same safety using testing with a known language?'

Writing this has made consider whether configuration should be conceptually looked at as a database instead of "code". How many people even know how e.g. postgres stores its tables and why would modulo some performance niche would you care anyway?

It seems configuration management is a graph db query and update matter. Standardize on configuration query language (if necessary) and stop worrying how the damn thing is represented by the config management tool.

At this point, I‘d rather just use a proper language.

I use KDL in a (not too complicated, yet) config file of a project and I like it a lot. Tree structure with attributes like XML but with less syntax than JSON. Nothing redundant but has basics like comments.

INI files are toml

I interned at a company that used an s-expression format as an alternative to JSON and it was great—much better than any mainstream format for config files and human-readable representations for API data. It was great at representing structured data (including tagged variants, so full algebraic data types) and even pretty good for text markup.

It also has best-in-class editor support thanks to paredit :)

The only real downside is the hassle of convincing people to use something weird and non-standard, which is really more a problem with people than with the format.

That page is such a gem.

> "make it easier to enter dates. For example, 12/2 changes to 2-Dec"

12/2 is obviously the 12th of February in my locale. But I need to keep Excel in English as a company policy, so this is not only unhelpful, it's outright wrong.

> Unfortunately there is no way to turn this off.

How does Microsoft justify this choice?

Underrated technique. I’ve used it similarly to generate scripts and it works great when used with care (error checking generally must happen at a different stage).

The big difference is that every Windows computer (in a professional environment) comes with a very nice GUI tool for easily editing Excel files. A tool that basically everybody know how to use. The same cannot be said for SQLite.

SQLite is great for storing application state and config options set from within the app, but it is a pretty terrible format for end users to edit.

Well, that's a complete apples-to-oranges proposal with completely different requirements.

With the original solution, you have an autocontained file that virtually any user knows how to edit, structure, expand, version, email, compare, discuss...

The level of user knowledge that you need for a similar solution based on a standalone SQLite file that you can version is another different world, e.g. to relate two values you would need to perhaps create a view or a trigger. And even with the most knowledgeable user you would still lack functionality such as simply pasting an image as a means of documentation and be able to see it, or WYSIWYG colors.

Now I just want a spreadsheet style front end to SQLite and I'm nerd sniped into trying to figure out how to do formulas (triggers I suppose).

Once you got used to it, honestly not really, other than needing Excel (not a huge deal since it was a Windows only application). I've no idea what the config parsing code looked like, but with the right library I doubt it was worse than any other non-trivial config parsing code. Mainly it just felt very wrong to my Unix, everything must be a text file, brain.

For better or worse I created a very similar system, but using Google Sheets instead of Excel files and fetched with the GSheets API. In that case the configuration was gigantic (many of the configuration values were product-decisions, and it ran in hundreds of different environments with different tweaks), so the tabular structure made navigating things very natural. It also had the advantage of structurally highlighting how environments differed. Doing it with Google Sheets came with some extra nice benefits: online sharing, versioning, access control down to specific ranges, etc.

Basically every engineer who joined the team thought it was a unforgivable blemish on the system, yet it survived a few years with no major issues, long enough for the team to build an internal backoffice and port the whole sheet structure into a proper CRUD API.

Biggest downside I've discovered by doing this is that there's not a very good way to diff separate versions of one sheet. Best I've done is export to CSV and use a generic text diff.

You're missing the point. Power came not from Excel the file format, but Excel the GUI tool for editing Excel files. You cannot have drop-downs and colour pickers and separate tabs and embedded images in a single python file without writing a a whole custom GUI config tool.

Having a visual way to configure this makes it much more accessible to non-programmers, with error checking available through the host (Excel, in this case), while also reducing the eng effort in building this.

At Google, many internal tools use Sheets as their source of truth for config data, and it works really well.

I think the difference there though is that an Excel file is a lot more approachable to non-technical folks (even superficially). Depends on what's being configured and by whom though.

A horrible workaround I use is a blank redundant key and a leading // in my string to draw my eye to it. This only preserves the last comment in my python dictionary but I only use comments to work in the json file.

    {
        “”:”// comment here”,
        “Entry”:[-1,0,2],
        “”:”// next comment”,
        “Flag”:true
    }

And trailing commas on final list elements and object properties.

JSONC is exactly that, JSON with comments. Works fine, eg typescript’s tsconfig file is JSONC and I’ve yet to find a problem with it.

https://json5.org

This is theoretically possible, and I actually toyed with the idea.

I didn't do it in my deserializer because of the big value you have in Rust in being compatible with serde and that wouldn't be. But this would be interesting, probably as an side library.

Roundtrips without destroying comments or formatting is supported in the JavaScript, Go and C++ implementations of Hjson, but not in the other implementations (I think).

A lot of formats are Hjson compatible, notably JSON, and also what users wrote thinking it was JSON but they forgot some quotes or had a trailing comma so the JSON parser refuses it while the Hjson one is perfectly happy.