
TOML – Tom's Obvious, Minimal Language - pmoriarty
https://toml.io/en/
======
jiggawatts
TOML superficially looks clean, but it has many of the same problems other
similar languages have.

Such file formats are typically used for configuration files. Yet, a
substantial amount of effort was expended on data types not commonly seen in
configuration files, such as a date-time-offset. Meanwhile, _much_ more common
data types typically used in configuration files is missing, such as GUIDs, IP
Addresses, and byte arrays.

Most disappointingly, TOML has a "table" type, but unfortunately, just like
other "RPC as Config" formats, the column names need to be repeated for every
row, which is just crazy. It also makes _no sense_ to talk about "arrays of
tables", which are actually just "rows" in standard terminology. An array of
rows... is a table.

Here is a terse example of the type of thing that _does_ come up very often in
bulk provisioning of the type that needs config files full of data:

    
    
        @"
        Server,Subnet,IP
        db01,databases,10.1.2.3
        db02,databases,10.1.2.4
        user01,filers,10.3.10.1
        user02,filers,10.3.10.2
        "@ | ConvertFrom-Csv | New-VMBuildScript.ps1
    

I'm yet to see a config file format that can even approach this in terms of
its readability and terseness.

~~~
mikepurvis
I've been using TOML recently and what displeases me most is that almost all
string values need to be quoted.

~~~
megous
Otoh, I got plenty of support requests from people not understanding that the
space at the end of a line in an .ini file is part of the value. (app is using
glib ini parser)

Quoting at least makes it clear what's part of the value.

~~~
Sharlin
What sort of nightmare format from hell has significant whitespace _at end of
line?_

~~~
megous
ini file

------
jasonpeacock
Of configuration file formats, TOML is my favorite. It hits the right balance
of power and simplicity, it's been able to handle my needs with minimal effort
and fuss.

I tried Python's INI for configuration, but it was both too simple and too
complex at the same time, very frustrating.

YAML is a nightmare, the formatting is way too easy to get wrong and
accidentally break your configuration.

JSON is too strict/simple. You can't even have trailing commas in a list!

~~~
ghayes
I recently wrote a TOML parser in Idris2. It's a cool language, but has some
quirks. For me, it's that it's just a simple KV store with some sugar (that's
nice!) but it also means that a lot of information is lost forever in parsing.
For example, these two documents are strictly identical:

    
    
        [info]
        name = { first="bob", last="jones" }
    

and

    
    
        info.name.first="bob"
        info.name.first="jones"
    

This can be seen as a positive (it's a really simple document) or a negative
(it's hard to machine-generate nice TOML, and it's easy to think there's more
to the structure of a written document than there is).

~~~
alecbz
Can you expand on the negatives? I don't think I understand what you mean.

~~~
demurgos
I believe the main negative he is referring to is that there is no canonical
representation for a given document. The input file can be structured to share
common keys (in the example above it's `info`) or not. Since both inputs are
parsed into the same value it means that writing a printer is harder: you now
have the choice between different output representations.

As a comparison, there's not much choice when serializing to JSON - the only
variation is around whitespace. When serializing TOML you need more insight to
decide what's the best representation for a human. A contributing factor to
this issue is that TOML is mostly used for configuration files, so it often
matters that the output is readable.

------
dang
If curious see also

a bit from 5 months ago
[https://news.ycombinator.com/item?id=22707387](https://news.ycombinator.com/item?id=22707387)

2018
[https://news.ycombinator.com/item?id=17513770](https://news.ycombinator.com/item?id=17513770)

2013
[https://news.ycombinator.com/item?id=5272634](https://news.ycombinator.com/item?id=5272634)

[https://news.ycombinator.com/item?id=5274025](https://news.ycombinator.com/item?id=5274025)

Alternative formats to this alternative format:

2018
[https://news.ycombinator.com/item?id=17765426](https://news.ycombinator.com/item?id=17765426)

[https://news.ycombinator.com/item?id=18023105](https://news.ycombinator.com/item?id=18023105)

------
quotemstr
YAML and TOML wouldn't have been necessary if JSON had been _slightly_ more
expressive. If JSON had

    
    
      * comments
      * bareword (not double quoted) object key names
    

it'd be a much more suitable configuration file format for everything, and I
don't think we'd see the motivation to make things like TOML and YAML.

~~~
Anaminus
JSON5 pretty much addresses all the problems with JSON as a config format. I'd
love for it to just replace JSON entirely.

[https://json5.org/](https://json5.org/)

~~~
quotemstr
Generally looks good, but ugh, I dislike allowing single quotes. Allowing
single quotes has close to zero ergonomic value but increases the number of
ways to write the same fundamental thing.

But that's a minor quibble. If everyone adopted this thing instead of legacy
JSON, we'd be better-off.

~~~
gridlockd
Having two ways to quote is a useful feature, not just one way to do the same
thing.

Javascript already has this, so allowing single quotes simplifies copypasting
object literals, which is a common use case.

------
shean_massey
I had tons of headaches trying to get toml to do what's trivial in Json
(nested arrays of objects of arrays of ... etc). 1/10 would not try again. For
very simple, hear "flat" config it checks out. But then, so does yaml or even
ini files. Anything requiring composite types was just a nightmare. I'd even
prefer xlm before using toml again.

~~~
hoseja
I never had to work with it seriously but I still don't get why people hate
XML so much.

~~~
qayxc
XML is verbose, surprisingly complex, and first and foremost not designed to
be written and consumed by humans.

There's plenty of room for debate, e.g. element versus attribute and things
get unwieldy pretty quickly [1]

The "note"-example illustrates the issue quite well: the order of the elements
matters and you end up writing every element identifier twice.

Not to mention the bloat that comes with using an XML library that's actually
compliant with the standard and includes all the bells 'n whistles.

[1]
[https://www.w3schools.com/XML/xml_dtd_el_vs_attr.asp](https://www.w3schools.com/XML/xml_dtd_el_vs_attr.asp)

------
fbnlsr
I discovered TOML a couple of years ago when I started playing with Hugo, as
it was Hugo's format of choice for configuration files.

I honestly find TOML harder to read and more complicated to use than YAML. I
tried to look into it but frankly I still haven't found a use case where it
made more sense to use TOML.

~~~
darthrupert
Interesting how differently competent people can perceive things. To me, YAML
is a cruel joke, and I carry suspicions about the competence of anyone who
opts to use it out of all possible options. I think I've even grown to like
XML configuration over it.

~~~
m463
if json only allowed comments...

------
admax88q
I've always had a soft spot for the classic .INI style configuration.

Modding command and conquer through "rules.ini" was always an adventure.

~~~
csb6
I also like how it just does one thing: key/values. It doesn’t try to be a
complex serialization format or its own full language - it’s just keys and
their values. Granted, sometimes data needs to have more structure, but for
settings/flags INI is very good.

------
mixmastamyk
_Strict_ yaml claims to have fixed most of the problems of yaml and other
languages used for configuration. Basically it is yaml with only string as a
basic datatype, and other complexities removed. Handling of data types is done
on a higher schema layer.

[https://hitchdev.com/strictyaml/](https://hitchdev.com/strictyaml/)

It's a smaller project so probably could use some support.

------
flukus
Another one I've been partial too lately is recutils
([https://www.gnu.org/software/recutils/](https://www.gnu.org/software/recutils/)),
it's similar to sqlite but has the benefits of being minimalist and plain
text.

Generally I prefer actual code based configuration though, there's only a
small subset of people than can read and edit these config formats but would
be unable to configure something like DWM through real code
([https://git.suckless.org/dwm/file/config.def.h.html](https://git.suckless.org/dwm/file/config.def.h.html))
and this approach gives far more flexibility without code bloat. Once
customization through config is removed it's only machine-to-machine
configuration that changes and these are easily handled by TOML, INI or even
environment variables.

------
sepples
TOML is great if you think of it as JSON, but optimized for being written by
humans instead of machines. I hope no new first-class types or syntax features
ever get added after the 1.0 release so it can have the same stability that
makes JSON great. The vast majority of the proposals that I see in the repo's
issues would collectively destroy the value of TOML, and I'm glad the current
maintainer seems to have the sense and fortitude to resist such additions.

------
skywhopper
“Obvious” is subjective. I find TOML to be remarkably confusing and surprising
and UNobvious, whereas YAML makes perfect sense to me, even though plenty of
folks hate it. Essentially, the name is pretty obnoxious in multiple ways,
given that it’s basically just an extension of the long-established INI
format.

~~~
thayne
YAML makes perfect sense until one of its many, many edge cases bites you.

There is a subset of yaml that is almost good. But even then, there are cases
where yaml is interpreted differently the average human would expect.

------
throwaway4007
I still don't understand why the Python steering committee decided to switch
to this format for package configuration instead of the perfectly serviceable
and existing setup.cfg. Packaging is already a pain to setup, now you gotta
learn _three_ (3) different ways to do it (if only to translate from one to
the next) because everyone's split. The choice doesn't even matter very much,
just settle on _something_ whatever it is

~~~
RedShift1
There's not much to learn. It's basically .ini on steroids.

~~~
thayne
What confuses me is why there isn't a toml module in the standard library.

~~~
nuclear_eclipse
I think the general feeling in the community is that the standard library is
where packages go to die. Once something is in the standard library, it can't
get meaningful features/updates outside of the yearly release cycle. pip and
setuptools are already vendoring a TOML implementation, and once you have pip,
you can pick from multiple great toml implementations that are all under
active development. Maybe once the packages/standards for TOML are finalized
and the only thing left to do is fix bugs, maybe then we'll see a TOML
implementation in the standard library, but in the modern age where you can
fetch dependencies at any time, there's honestly not that much incentive for
CPython developers to take on more burden of maintenance and development for
the already-massive standard library.

~~~
thayne
> the standard library is where packages go to die

I totally understand that sentiment. But that does seem to contradict the
"batteries included" philosophy. Then again pip itself seems like one of the
batteries you would expect to be included, so maybe that philosophy is just no
longer as relevant to python.

~~~
afiori
my understanding is that the batteries included philosophy wasn't really
successful. probably it would have been better if they had a smaller standard
library providing core language-level functionality and then many blessed p
packages that with independent versioning

~~~
lmm
It was successful at the time. Remember Python is nearly 30 years old now, and
has always had the worst dependency management of any major language.

~~~
thayne
I don't know c++ dependency management is pretty terrible.

------
pornel
TOML used as an `.ini` file is nice, but it gets verbose and confusing pretty
quickly if you try to store more complex data in it.

`[[foo]]` syntax is not obvious at all. It's a bit weird that top-level
declarations use ini-like syntax, but values can use JSON-like syntax, and
there are multiple syntaxes to express the same data structure.

It doesn't strike me as very elegant, or obvious. Still, it is less
annoyingly-inflexible than JSON, less verbose than XML, and less footgunny
than YAML.

------
rco8786
Whoa cool. I remember seeing Tom’s initial proposal/spec for TOML on here
years ago. Like maybe a decade even. Glad to see it’s still out there and
actually been implemented

~~~
bvinc
It's used often in rust. Rust crates are configured with toml files.

------
gscho
Self plug: I wrote a simple web app in the same vain as jsonlint and yamllint
for toml files. [https://toml-lint.com](https://toml-lint.com)

------
rdlfo
I was constantly reading/writing config files and the structure and comments
were what convinced me TOML was worth to try. I did end up going back to JSON
for the schema validator bit, but I just found out that TOML is still working
on it: [https://github.com/toml-lang/toml/pull/116](https://github.com/toml-
lang/toml/pull/116)

~~~
tasubotadas
IF you need schema validation, you should probably be using XML

------
XorNot
I can't stand TOML. I find it's method of representing arrays and tables of
objects so much harder to read and reason about than YAML.

------
blaisio
TOML sucks in so many ways. It is about 8x better than YAML, INI, or JSON
though. It is good enough that I can ignore its flaws.

~~~
tasogare
JSON should be banned for configuration, if only for the fact it doesn’t
support comments.

~~~
dnautics
JSON is great, but not for config: It was never really meant to be written by
humans.

~~~
1_player
I agree totally with you, but designing a language that's not "meant for
humans" is an _incredibly_ stupid idea. Of course humans will try and write
any protocol by hand. Who's gonna stop me?

If it looks like text, make it as easy as possible for humans to consume and
write by hand. Period.

That's a small but very important reason why HTTP rules the world.

------
BiteCode_dev
People keep confusing program configuration files and program stdin and are
surprised that TOML is not a good fit for it.

If you are provisioning servers from a TOML files, you're doing it wrong.
That's your program main input, not config.

If you have deeply nested values, chances are you are again confusing
configuration vs main input.

JSON and CSV are great main input formats.

TOML is a great configuration format.

YAML and XML try to do both, and end up doing average on either, but being
abused for all of them (looking at you Ansible and Solr).

So you should use each format for the correct purpose, as usual.

A config file looks like ~/.ssh/config or /etc/nginx/nginx.conf, not like
~/.ssh/authorized_keys or /etc/nginx/site-available/default.conf.

Just because we love to put a lot of data input in config folders (.config and
/etc are full of input data) and call that configuration doesn't make it so.

How to know if something is configuration and something is input?

Conf data is usually only manually edited (authorized_keys changes with the
life cycle of the program) and doesn't contain logic (default.conf if full of
logic). Conf is also how the program is going to behave when performing its
main task, the boostraping state, not the data used for it's main task (so not
ip for provisioning servers, which is not meta, but the main course, or
default.conf, which nginx uses to perform the main task). Conf rarely changes,
main input often does. Conf is not piped or redirected to stdin.

------
bostonvaulter2
I hope this catches on some more. I'm tired of being bitten by all the issues
that I encounter with yaml configs.

~~~
MiroF
What are these issues? I've been using YAML comfortably for years

~~~
bostonvaulter2
This link has a decent overview: [https://www.arp242.net/yaml-
config.html](https://www.arp242.net/yaml-config.html)

There's also the NO/Norway problem (although it seems this instance of the
problem may be fixed if you're always using newer versions):
[https://allan.reyes.sh/programming/2018/06/20/The-YAML-
NOrwa...](https://allan.reyes.sh/programming/2018/06/20/The-YAML-NOrway-
Law.html)

------
wtf_is_up
I've always enjoyed using HOCON in Scala projects. I wish it saw more
adoption.

------
AlexandrB
And so the language churn continues. This time for configuration. TOML is
fine, I guess. It doesn't seem to offer much benefit over Yaml or JSON. In the
absence of those it would be great. But in a world where Yaml and JSON exist
it's _yet another_ structured data format you have to learn.

~~~
metalliqaz
It's not like TOML is new. I'm familiar with it because of Python's pip tool,
and InfluxDB/Telegraf. Apparently it's also used in Rust's Cargo.

------
02020202
I use only yaml for humans and json for machines. i see many projects that use
toml but i just hate it. maybe toml is not bad itself but i have never seen
project that would have toml config really human-friendly. it always loks like
a retard-child of some ini monstrosity. yaml all the way, hands down.

------
_jal
I'm personally sick of yet-another-config-formats. Why did designing
metaformats become cool?

They all have warts because using the same symbolic notation for data and
structure leads to encoding issues that have cognitive overhead.

So instead of getting used to the pratfalls involved in making mistakes in one
format/library set, we can do it in a whole bunch of different ones. And of
course if anyone uses the new format much much, we'll get multiple, slightly
incompatible versions, all with different bugs.

Thanks?

~~~
JadeNB
> I'm personally sick of yet-another-config-formats. Why did designing
> metaformats become cool?

I can't seem to find a date for it, but I think TOML is pretty old, so
probably predates a lot of these YACFs.

I think that the problem is that it's such an easy workflow:

1\. No existing config format is perfect. Look at this should-be easy thing I
want to do that isn't easy!

2\. Create a new format that makes the desired should-be easy thing actually
easy.

If you have one or two pain points, then it's really easy to address them, and
your life gets so much better for a little while. If you're lucky and you're a
good YACF designer, then your life gets so much better for quite a while—and,
by the time you realise why the design isn't perfect, you're already invested
in it.

~~~
shakna
> I can't seem to find a date for it, but I think TOML is pretty old, so
> probably predates a lot of these YACFs.

Not _that_ old. TOML's first release was in 2013.

But as a testament to the config format, it was only about a year old when
Rust's cargo adopted it fully.

------
peter_d_sherman
Unicode handling seems nice:

>"

\uXXXX - unicode (U+XXXX)

\UXXXXXXXX - unicode (U+XXXXXXXX) "

------
brundolf
[https://xkcd.com/927/](https://xkcd.com/927/)

