Apologies for the somewhat off-topic remark, but ... Can we please stop creating new JSON-based config files? Sane config file formats must support comments.
I wouldn't apologize for that, you're addressing the elephant in the room here. JSON has turned into the new XML. There seems to be a pervasive undercurrent that if it looks website-ish, it's got to be good. So it seems to be used quite a bit in lieu of looking carefully at the problem and figuring out the best structured format. Configuration files tend to have a lot of ambiguity in them, going to a format that makes it all that much harder to pull out the why part of settings does nothing to improve on that.
Honestly, I don't think JSON config files are a big problem. What's shitty is when humans are expected to manually create and edit plain JSON, but what's stopping us from using whatever tools we want to generate those JSON configs?
There are some very nice tools out there for this; I have taken to using jsonnet (http://jsonnet.org/), which is excellent as a configuration language. It's pretty comparable to Hashicorp's HCL, but it's a standalone thing.
Summary: Write your config files in a language of your choice. Render them to JSON for your apps to consume. Be thankful that every app doesn't have its own special snowflake config format like they used to.
Unfortunately, it suffers from the huge problem of not having any comments, which was what the original poster was pointing out. Configuration is code that happens to be interpreted at runtime. Having to dig through uncommented code at two in the morning sucks, especially when you're trying to figure out why your automated code and/or config generator just failed. Yes, having to write a config file by hand sucks, however, there are still enough cases out there where you end up having to do just that, and JSON makes the problem of keeping them lucid all the more difficult.
My suggestion, in general, is to use a static language like jsonnet to write config files. It's rather hard for them to break, because the language just isn't capable of talking to the network or various other things that config files shouldn't do. I do agree with you, and I would really prefer to have apps use formats that allow some sort of commenting, but I can live with json - by letting the computer deal with it.
What I hate is that good tools for this like UCL go ignored or forgotten while JSON formats grow like weeds, and even excellent people like Hashicorp wind up contributing to this serious problem.
> There seems to be a pervasive undercurrent that if it looks website-ish, it's got to be good.
I don't get that from the article. There's a stated reason, that it's a stricter format with much less risk of type confusion, which sounds plausible enough to me. There's also the benefit that tool support is good. Why does the web need to be relevant at all?
Doesn't YAML fill the same slot, allow comments, and allow much saner human interaction? And as a bonus it's 100% (?) convertible to JSON (minus comments of course)
You'd have to add a validator to disallow some of the weirder YAML syntaxes. And once you have such a validator, you have neither JSON (it won't parse) nor YAML (it's dangerous to parse the file as YAML without running it through the validator first).
YAML isn't a particularly good config format either, since it has a lot of unnecessary complexity. For example, bare words are strings, but some bare words, such as "true" are booleans. Which wouldn't be so bad, but did you know that "yes" and "no" are also booleans? I've gotten YAML files from an i18n-system that screwed this up in a pretty bad way.
In fact, YAML is a superset of JSON, and any valid JSON is also valid YAML. This becomes more obvious when you realize you can put any JSON objects inside of your YAML document and any YAML parser will correctly deserialize it.
At long as an app isn't strictly validating the JSON, you should be able to add keys like { "comment": "this does xxx" } to a JSON configuration object.
I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.
Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser."
The idea that one would install node + npm + some linter + linter configs + some method of automatically running the linter against the config before sending it to the thing being configured seems pretty insane and unnecessary to me. At the end of the day, it can suck, but being able to look at a config on a running system with inline comments makes debugging infra problems much easier. What the heck was wrong with # comments and the types of configs Apache et al. Have been using for decades?
Nothing, but then you get to write your own parser for whatever bespoke configuration DSL you want to implement. Some people would rather focus on other aspects of functionality.
I (original commenter) second TOML. It is very simple, is instantly familiar to anyone who has used ini files or many Unix-style config files, and has many good implementations available.
The [[array]] notation mentioned below is a tad weird, but I've never had an occasion to use it.
No, you're got upvoted by me. XML is great and has all kinds of well-tested tools - query language, schema validation, namespaces, etc.! Not sure why people think it's worse than JSON, TOML or the likes. Less readable? Not really. Plus, more people know HTML than JSON and so it should be less easy to learn than even JSON for people who already know HTML. Maybe the only improvement would be to make it more relaxed like HTML5.