# this is some TOML

name = 'TOML'

[created-by]
name = 'Tom Preston-Werner'
dob = 1979-05-27T07:32:00-08:00

TOML is a configuration file format designed like an "improved" INI file.

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?

1. It's verbose

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 ([[object.array]])
• 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.

2. TOML looks like it was designed for parsers.

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

3. TOML has too many features.

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.

4. Syntax typing

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.

4. TOML's rules aren't that obvious

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!

If you like the post, follow me on Twitter or here on DEV for more awesome posts and tips!