# this is some TOML name = 'TOML' [created-by] name = 'Tom Preston-Werner' dob = 1979-05-27T07:32:00-08:00
At first, TOML looks like a simple, readable file format. If you use it infrequently on small, simple files, it's fine.
But as you use it more, you will start seeing the flaws of TOML.
Martin Vejnar, the creator of PyTOML, said the exact same thing. He initially built the parser out of enthusiasm for TOML, but eventually abandoned it:
TOML is a bad file format. It looks good at first glance, and for really really trivial things it is probably good. But once I started using it and the configuration schema became more complex, I found the syntax ugly and hard to read.
So, what's the problem with TOML?
This is a yaml document:
json: - rigid - better for data interchange yaml: - slim and flexible - better for configuration object: key: value array: - null_value: - boolean: true - integer: 1 - alias: &example aliases are like variables - alias: *example paragraph: > Blank lines denote paragraph breaks alias: &foo bar: baz alias_reuse: *foo
And here's the same thing in TOML:
json = [ "rigid", "better for data interchange" ] yaml = [ "slim and flexible", "better for configuration" ] paragraph = """ Blank lines denote paragraph breaks """ [object] key = "value" [[object.array]] [[object.array]] boolean = true [[object.array]] integer = 1 [[object.array]] alias = "aliases are like variables" [[object.array]] alias = "aliases are like variables" [alias] bar = "baz" [alias_reuse] bar = "baz"
The first YAML examples is 368 characters. The second is 455 characters. That's about 100 more characters you need to type. TOML re-introduces what human friendly languages are trying to get rid of: verbose syntax, the necessity to quote strings, and more.
The reasons are obvious:
- When you have an array, you need to repeat the key again and again (
- There's a lot of syntactic extras like square brackets and quotes which dominate TOML.
- There is no alias system.
Making programs smaller and DRYer significantly reduces the number of bugs. The same can apply for configuration files.
Hierarchy in TOML is determined by
.s. This is simple enough for parsers to understand, but this makes it difficult for us.
That's why many people have adopted this style:
[markup] [markup.tableOfContents] endLevel = 8 startLevel = 1 [markup.highlight] style = "solarized-dark"
While this makes it easier to understand, it would be much better if we could get rid of the dots (and brackets) and just use indent alone. This is why I love the Python syntax.
There are still debates about whether using indentation alone was a good idea, but it generally is, as discussed in this StackExchange question
TOML's creator criticizes YAML for having too many features and then does the same thing. Ironic.
For example, TOML has first class dates. If you have been programming for any amount of time, you know the problems associated with date and time (cough momentjs cough).
In my opinion there should only be 5 types: string, number, boolean, array, object. This is the approach JSON took, and it's a good decision.
Take a look at this:
str = "string" num = 42
TOML lets the users decide what type a thing is. But in most cases, this is not correct as the client should decide what type a thing should have. If the types are incorrect they should be coerced or an error should be thrown.
Most of TOML is obvious, but not all.
For example, the
[[syntax]] is confusing. It looks like a
[object] with an extra
 pair around it, but it's used to signify an array.
If you think I've missed any points (a lot!), or if you disagree with any points I've made, please leave a comment!
I actually have a lot more points to tell, and I'll write a longer article another day. Stay tuned!