I never got this stance; JSON sucks for config files, because as a user, if there is anywhere that I need and am more thankful for comments, is in a configuration file. And TOML is maybe a good substitute for INI formats, but it doesn't really support nested data like JSON would, so suggesting to use TOML instead of JSON is misleading except for the simplest and most basic needs.

If replacing JSON is the objective, I'd very much rather recommend HJSON [1] than TOML.

[1]: https://hjson.github.io/faq.html

What about HOCON? https://github.com/lightbend/config/blob/master/HOCON.md

I guess why not? I mean, there are lots of options here. I prefer HJSON, also it helps a lot that its website does a very good job at convincing other fellow devs to try it...

But there is also JSON5, among the most popular alternatives. Then HOCON you mention, and probably a myriad more.

> it doesn't really support nested data like JSON would

This is just plain wrong. It supports exactly the same kind of nesting as JSON.

Could your problem be partially resolved by having a key called description or comments where you could provide some clarification?

But now that's part of the data and the parser doesn't know any better. Comments are more useful if they are close to the thing being talked about.

The human readable part is a bit subjective. I find YAML more human readable than TOML.

Readable, maybe? I mean as long as the YAML is correctly quoted, sure, it looks fine. But that's a big if. But writeable, hell no. I have been writing YAML for years and still have no idea how the quoting works, and not for lacking of looking it up in the past.