> Why do so many tools have JSON config files‽ Commenting why options have been set the way they have is just such a basic thing to want to do… Why do tech people have such an aversion to writing things down⁇
That's the whole post. First I don't know why this is posted on HN. Second I don't see how "JSON config" and "writing things down" are the two opposite options.
> That's the whole post. First I don't know why this is posted on HN. Second I don't see how "JSON config" and "writing things down" are the two opposite options.
The "writing things down bit" is in the context of commenting. I mean, it's literally in the same paragraph.
Which is better than the all too common middle ground: writing something once and then not maintaining it. I've been burned many times reading some documentation and thinking I understood until I discovered the code has changed since and the documentation is now wrong.
I'm in favor of documentation. I write it. I get people pointing at what I've written as examples of what everybody should do. However it is a lot of work. I'm constantly looking things over to be sure it still makes sense. I often wonder if it is really worth it. I hope you follow my example and write documentation, but it better feel like a lot of work.
I don't agree with "readable," though. For a simple set of key-values, yes. Once you get into complicated structures, other file formats express the semantics much better.
If you have a complex configuration you are doing it wrong... Spend some time thinking about you really want and turn it into a simple key-value setup. JSON should feel like it is overpowered and bloated for your needs. (I'd still use JSON because you can find a parser and editor that can handle it, but it should feel overpowered for your needs)
1: Because JSON is a very easy serialization format to work with. I suspect these tools all have configuration classes / objects that are deserialized straight from the config file.
2: I suspect a lot of these tools are written in Javascript, and in Javascript JSON is very easy to work with.
In C#, I find "binary serialization" much easier to program with than JSON.
Then again, the resulting blobs require specialized tooling to read, and they're very hard to work with in other programming languages.
---
But, jokes aside:
I find CSV is great for "rows" because it doesn't repeat field names for every object.
I really like XML when each tag is an object, and fields are attributes. Most people don't understand this and end up making a hug mess; and some serializers do this by default too. IMO, this is why JSON became much more popular.
For Caddy we chose JSON because it's fairly universal, maps nearly 1:1 with Go structs (useful for initializing an extensible server), and nearly everything else compiles to JSON one way or another, so you can choose your own config format, really: https://caddyserver.com/docs/config-adapters
In my opinion, JSON is not the best format and has some problems. Lack of comments is one of the reasons, as they mention in there. Another is the lack of trailing commas (optional trailing commas would be useful for manually written files). However, these are problems with the syntax, and there are also problems with the data, such as a lack of a proper integer type, lack of Infinity and NaN, lack of support for character sets other than Unicode (and ASCII), lack of proper octet string type, etc.
because JSON is in the following sense "universal":
every format/structure that has numbers, strings, booleans, null/none, finite lists of items, and string-indexed records of items already contains JSON
and that's pretty much the barebones you need for a configuration language
JSON still a very simple and useful format and being natively supported on the web and by javascript basically guarantees its universality. Native comments would be nice though. But to be fair even Douglas Crockford suggested using comments in JSON was fine as long as you stripped them out before parsing.
<whispers>but Lua tables are even better.</whispers>
That is not quite true, because you have to define "numbers" and "strings" more specifically; JSON uses Unicode strings, and how numbers work depends on the implementation (but are generally finite 64-bit IEEE floating point; JSON does not have Infinity and NaN).
ASN.1 is almost a superset, but lacks a key/value list type; I had made some nonstadard extensions called ASN.1X and one of my new types is a key/value list type, so that makes the data types of ASN.1X a superset of JSON (although the format is different, it makes that all JSON data can be represented using DER if the nonstandard key/value list type of ASN.1X is used).
I don't like JSON that much because of its many problems (some are problems with syntax, others are problems with the data), so I use ASN.1X instead (with the DER format), for my own stuff (but I also deal with JSON because it is common enough).
For our internal tooling we use something similar to a bash profile config file with name/value pairs separated by linebreaks. So, our configs look something like:
I really like the EDN[1][2] (extensible data notation) format that is used mostly by Clojure for config and data transfer/exchange. It is so much more expressive than JSON and supports a well thought-out set of elements for the most common data structures.
I wish everyone would embrace Amazon's Ion format. Of the data serialization formats it seems the most reasonable with the exception that it can encode S-expressions (so like having data serialization within your data serialization), so it is a bit excessive.
At a previous employer we tried using Ion, but when they stopped supporting our QLDB it was obvious that nothing else really used it and it was a dead end.
TOML is a better format for configuration files IMO, if not for many reasons, primarily because TOML accepts comments.
However, one annoying thing for TOML was the lack of schema, and the reliance on JSON Schema for that. Which I decided to tackle years ago when I started the TOML Schema project. In the past few months I leveraged code agents to take to the finish line and got something compelling: tomlschema.org
Interesting. The website says that it's "validation-focused". I don't know how that plays out for TOML, but the lack of focus in json schema to define an interface in addition to validation can be very frustrating. Most of the time I would rather trade off some expressitivity in terms of validation in favor of having a defined typed interface into the validated data.
I'd argue that for code, yes, JSON is vastly closer to computer structures.
I think this is the real "why do so many tools have JSON config files": because it's just a literal notation, for basic data structures, that looks a lot like what many programming languages natively do, what their data structures natively are. The answer to the post is: it's mechanistic sympathy.
For humans, I do find TOML to be a lot easier to manage. Even if you have a really good editor that takes care of all the quoting/nesting/comma concerns for you, even if you have jsonc or json5 with comments, it's still not as easy/friendly as a big flat file with sections in it.
Let me guess... if they're a form of Lisp, did someone add jndi support, then made it possible to print to the console while the string gets read and finally made it executable because who wouldn't want a LISP for-loop in an Oracle connection string? On to the next RCE...
Nah, they are pretty constrained data description. AFAIK, you can't even substitute environment variables.
They are also apparently very hard to use, to the point that many people can't and several web sites exist that will take your database server, username, and password and assemble a connection string for you. (I can see no issues with that! None!)
SQLite is a tiny relational db that essentially runs right in the same folder as your application. No connection other than connecting from the app itself to the SQLite.db sitting next to it.
You're missing the point: Why are your config files so complicated that you need SQLite?
I've shipped a product that used SQLite, and we actively removed configuration from SQLite. It was a lot easier to diagnose issues when configuration was in text files, because non-programmers could kinda-sorta understand them without needing to learn how to use SQL.
1. JSON parsers are available at your corner convenience store.
2. The format is too simple to have ambiguous behavior. No weird “yes” means true, 0 means false, odd rules about comments, blah blah blah. It’s hard to fuck up JSON (but obviously not impossible if you get creative).
3. It errors out early in the parsing if you mess it up.
4. Its data types are present in more or less any language.
5. Most configs are just key/value. JSON does this reasonably well.
6. It is easy to generate and validate JSON documents. For some use cases you don’t need a library (though you should use one).
7. There is only one way to do anything (sane).
8. Everyone is familiar with it.
9. It is dynamic. You do not need to pre-define your sections or keys ahead of time.
10. It can easily be auto formatted to look good with zero risk of changing semantics.
11. Data stores often natively support storing and querying JSON objects.
12. If you are old enough to remember the era when every tool invented its own, often very buggy, config format and parser you will also remember the moment you first saw a JSON config file that was parsed with a standard library parser and thought “finally, this is the modern way”, you will understand why JSON continues being popular. It was the first thing that unambiguously worked compared to what came before it.
This is like asking why people use their keys to open packages: it might not be the right tool for the job but it’s hard to mess up, is the closest thing to you that can get the job done, and everyone (with functioning hands/fingers) can do it with little issue.
I am also certain there is some small but non-zero percentage of people who do it simply because everyone else moralizes about not doing it. Spite is a powerful thing.
It would be too easy to have every option in a config file documented in comments in the default config file. Think of the poor tutorial industry. It may even make chatbots less useful.
I don't know about others, but I use JSON because it's in the standard Go library, and most of the times, I rather use something weird than add a dependency.
JSON is obviously a poor choice. It's job is to interchange data, produced and parsed by computers.
ESR had the idea of writing configuration in English. It didn't gain traction at the time, but we have LLMs now. It might be a good idea to revisit the idea of accepting plain english. The LLM output could then be any format that's easy and unambiguous to parse.
Using an LLM to parse your application's config is a bit like using an F1 racecar to drive from your house to the bicycle in your attached garage. Getting config into the application should to be fast, light (lighter than the rest of the application), and deterministic. And if the LLM's output is easy and unambiguous to parse, it's easier to simply use that as the original config file.
I totally get that. The application shouldn't use an LLM to parse the config file, but it would be useful to write one. An LLM could supply a diff to make the changes you want without learning the config-language-du-jour.
I'm not sure why there's a problem before even trying.
Say for instance you have a program that keeps recipes. In your configuration file, there's settings such as metric/imperical units, allergies, diets, type of stove in your kitchen, and some theming (font, size, color...). You put them all in a file that you can parse, but aunt tillie messes up the formatting and the program breaks.
Instead of changing the config by hand, an LLM could supply the diff according to instructions in English. I really don't see why this would be "Terrible for prod". If the LLM screws up, you're simply back to square 1 and aunt tillie will call you just like she would before she had an LLM to fix her computer.
> Why do so many tools have JSON config files‽ Commenting why options have been set the way they have is just such a basic thing to want to do… Why do tech people have such an aversion to writing things down⁇
That's the whole post. First I don't know why this is posted on HN. Second I don't see how "JSON config" and "writing things down" are the two opposite options.
> That's the whole post. First I don't know why this is posted on HN. Second I don't see how "JSON config" and "writing things down" are the two opposite options.
The "writing things down bit" is in the context of commenting. I mean, it's literally in the same paragraph.
> A lot of tech folks resist documentation because they think it provides them with job security.
No, we're just lazy.
Which is better than the all too common middle ground: writing something once and then not maintaining it. I've been burned many times reading some documentation and thinking I understood until I discovered the code has changed since and the documentation is now wrong.
I'm in favor of documentation. I write it. I get people pointing at what I've written as examples of what everybody should do. However it is a lot of work. I'm constantly looking things over to be sure it still makes sense. I often wonder if it is really worth it. I hope you follow my example and write documentation, but it better feel like a lot of work.
Occam's Razor at it's finest. I'm not trying to screw others over. I just want to not write sometimes.
It's readable, it's easy, it gets the job done.
I don't think that's necessarily lazy, it's just efficient
I don't agree with "readable," though. For a simple set of key-values, yes. Once you get into complicated structures, other file formats express the semantics much better.
If you have a complex configuration you are doing it wrong... Spend some time thinking about you really want and turn it into a simple key-value setup. JSON should feel like it is overpowered and bloated for your needs. (I'd still use JSON because you can find a parser and editor that can handle it, but it should feel overpowered for your needs)
> It's readable, it's easy
That's what I am saying about my ruby codes as well. Still my boss wanted proper commit messages
Something has gone awry if the config files have a readability and difficulty analogous to that of the codebase.
> Why do so many tools have JSON config files‽
1: Because JSON is a very easy serialization format to work with. I suspect these tools all have configuration classes / objects that are deserialized straight from the config file.
2: I suspect a lot of these tools are written in Javascript, and in Javascript JSON is very easy to work with.
JSON is probably the easiest format to work with regardless of language.
Pedantic response:
In C#, I find "binary serialization" much easier to program with than JSON.
Then again, the resulting blobs require specialized tooling to read, and they're very hard to work with in other programming languages.
---
But, jokes aside:
I find CSV is great for "rows" because it doesn't repeat field names for every object.
I really like XML when each tag is an object, and fields are attributes. Most people don't understand this and end up making a hug mess; and some serializers do this by default too. IMO, this is why JSON became much more popular.
Mostly because it is so common (web) it doesn't matter what language you use there is a good maintained tool to read and write JSON.
For Caddy we chose JSON because it's fairly universal, maps nearly 1:1 with Go structs (useful for initializing an extensible server), and nearly everything else compiles to JSON one way or another, so you can choose your own config format, really: https://caddyserver.com/docs/config-adapters
Hey, thanks for Caddy! It's awesome :).
In my opinion, JSON is not the best format and has some problems. Lack of comments is one of the reasons, as they mention in there. Another is the lack of trailing commas (optional trailing commas would be useful for manually written files). However, these are problems with the syntax, and there are also problems with the data, such as a lack of a proper integer type, lack of Infinity and NaN, lack of support for character sets other than Unicode (and ASCII), lack of proper octet string type, etc.
because JSON is in the following sense "universal":
every format/structure that has numbers, strings, booleans, null/none, finite lists of items, and string-indexed records of items already contains JSON
and that's pretty much the barebones you need for a configuration language
(of course you can argue about the syntax)
Lack of comments is pretty big though for a human editable config.
It’s just one person’s opinion, but I think two things are true enough, here…
1) JSON is pretty darn good for storing configuration. Everything speaks it, and a pretty printed one is very readable/tweakable in a pinch.
2) If you insist that someone manually edit a significant amount of it, you kinda fucked up.
Just my opinion, but it feels like two separate things.
You can always use JSONC or JSON5.
I just put them in as values. In a GUI I sometimes render them as a editable textarea.
JSON still a very simple and useful format and being natively supported on the web and by javascript basically guarantees its universality. Native comments would be nice though. But to be fair even Douglas Crockford suggested using comments in JSON was fine as long as you stripped them out before parsing.
<whispers>but Lua tables are even better.</whispers>
That is not quite true, because you have to define "numbers" and "strings" more specifically; JSON uses Unicode strings, and how numbers work depends on the implementation (but are generally finite 64-bit IEEE floating point; JSON does not have Infinity and NaN).
ASN.1 is almost a superset, but lacks a key/value list type; I had made some nonstadard extensions called ASN.1X and one of my new types is a key/value list type, so that makes the data types of ASN.1X a superset of JSON (although the format is different, it makes that all JSON data can be represented using DER if the nonstandard key/value list type of ASN.1X is used).
I don't like JSON that much because of its many problems (some are problems with syntax, others are problems with the data), so I use ASN.1X instead (with the DER format), for my own stuff (but I also deal with JSON because it is common enough).
It's so simple and straightforward, and that's why Douglas Crockford claims he "discovered" it, rather than invented it.
For our internal tooling we use something similar to a bash profile config file with name/value pairs separated by linebreaks. So, our configs look something like:
env=staging
db=0.0.0.0
#descriptive comment
etc=true
ini file format is pretty much this
[section_name]
key=value
key=value
I really like the EDN[1][2] (extensible data notation) format that is used mostly by Clojure for config and data transfer/exchange. It is so much more expressive than JSON and supports a well thought-out set of elements for the most common data structures.
[1]: https://github.com/edn-format/edn
[2]: https://en.wikipedia.org/wiki/Clojure#Extensible_Data_Notati...
I wish everyone would embrace Amazon's Ion format. Of the data serialization formats it seems the most reasonable with the exception that it can encode S-expressions (so like having data serialization within your data serialization), so it is a bit excessive.
https://en.wikipedia.org/wiki/Ion_(serialization_format)
At a previous employer we tried using Ion, but when they stopped supporting our QLDB it was obvious that nothing else really used it and it was a dead end.
Shame.
> Why do so many tools have JSON config files‽
Because XML hasn't been cool for about two decades. And suggesting .ini would you laughed out of the room into retirement.
TOML is a better format for configuration files IMO, if not for many reasons, primarily because TOML accepts comments.
However, one annoying thing for TOML was the lack of schema, and the reliance on JSON Schema for that. Which I decided to tackle years ago when I started the TOML Schema project. In the past few months I leveraged code agents to take to the finish line and got something compelling: tomlschema.org
Interesting. The website says that it's "validation-focused". I don't know how that plays out for TOML, but the lack of focus in json schema to define an interface in addition to validation can be very frustrating. Most of the time I would rather trade off some expressitivity in terms of validation in favor of having a defined typed interface into the validated data.
Reading and writing json is so much easier than reading or writing toml imo
I'd argue that for code, yes, JSON is vastly closer to computer structures.
I think this is the real "why do so many tools have JSON config files": because it's just a literal notation, for basic data structures, that looks a lot like what many programming languages natively do, what their data structures natively are. The answer to the post is: it's mechanistic sympathy.
For humans, I do find TOML to be a lot easier to manage. Even if you have a really good editor that takes care of all the quoting/nesting/comma concerns for you, even if you have jsonc or json5 with comments, it's still not as easy/friendly as a big flat file with sections in it.
TOML is quite ridiculous. There are always an infinity of ways one can write the same values.
It should really define sections as something different from dot-separated identifier groups.
I find TOML is nowhere near as good as YAML. I'd even rather use jsonc.
Yeah, I just use JSON5, it solves all the issues with normal json
Somewhat off topic, but Oracle database connection strings seem to be a form of Lisp. It makes me wonder why they would choose that.
Let me guess... if they're a form of Lisp, did someone add jndi support, then made it possible to print to the console while the string gets read and finally made it executable because who wouldn't want a LISP for-loop in an Oracle connection string? On to the next RCE...
Nah, they are pretty constrained data description. AFAIK, you can't even substitute environment variables.
They are also apparently very hard to use, to the point that many people can't and several web sites exist that will take your database server, username, and password and assemble a connection string for you. (I can see no issues with that! None!)
Because JSON is native to the lingua franca of the internet: Java-/Ecmascript.
It fits into the poor choices we made, <-- Parse error
JSON just works, everywhere, all the time. Sometimes I'll use SQLite if there is a particular need.
Can you show an example of how you use SQLite for _config_ files?
SQLite is a tiny relational db that essentially runs right in the same folder as your application. No connection other than connecting from the app itself to the SQLite.db sitting next to it.
You're missing the point: Why are your config files so complicated that you need SQLite?
I've shipped a product that used SQLite, and we actively removed configuration from SQLite. It was a lot easier to diagnose issues when configuration was in text files, because non-programmers could kinda-sorta understand them without needing to learn how to use SQL.
I think your emphasis might be in the wrong place...SQLite for config makes enough sense, but as a config _file_?
Not entirely. Because where would I configure the location of the SQLite location/connection then?
Given what I know about it (single file, no auth, and such by default) I sort of understand the ”file” part I think. But not the ”config” part.
1. JSON parsers are available at your corner convenience store.
2. The format is too simple to have ambiguous behavior. No weird “yes” means true, 0 means false, odd rules about comments, blah blah blah. It’s hard to fuck up JSON (but obviously not impossible if you get creative).
3. It errors out early in the parsing if you mess it up.
4. Its data types are present in more or less any language.
5. Most configs are just key/value. JSON does this reasonably well.
6. It is easy to generate and validate JSON documents. For some use cases you don’t need a library (though you should use one).
7. There is only one way to do anything (sane).
8. Everyone is familiar with it.
9. It is dynamic. You do not need to pre-define your sections or keys ahead of time.
10. It can easily be auto formatted to look good with zero risk of changing semantics.
11. Data stores often natively support storing and querying JSON objects.
12. If you are old enough to remember the era when every tool invented its own, often very buggy, config format and parser you will also remember the moment you first saw a JSON config file that was parsed with a standard library parser and thought “finally, this is the modern way”, you will understand why JSON continues being popular. It was the first thing that unambiguously worked compared to what came before it.
This is like asking why people use their keys to open packages: it might not be the right tool for the job but it’s hard to mess up, is the closest thing to you that can get the job done, and everyone (with functioning hands/fingers) can do it with little issue.
I am also certain there is some small but non-zero percentage of people who do it simply because everyone else moralizes about not doing it. Spite is a powerful thing.
It would be too easy to have every option in a config file documented in comments in the default config file. Think of the poor tutorial industry. It may even make chatbots less useful.
I don't know about others, but I use JSON because it's in the standard Go library, and most of the times, I rather use something weird than add a dependency.
[dead]
JSON is obviously a poor choice. It's job is to interchange data, produced and parsed by computers.
ESR had the idea of writing configuration in English. It didn't gain traction at the time, but we have LLMs now. It might be a good idea to revisit the idea of accepting plain english. The LLM output could then be any format that's easy and unambiguous to parse.
Using an LLM to parse your application's config is a bit like using an F1 racecar to drive from your house to the bicycle in your attached garage. Getting config into the application should to be fast, light (lighter than the rest of the application), and deterministic. And if the LLM's output is easy and unambiguous to parse, it's easier to simply use that as the original config file.
I totally get that. The application shouldn't use an LLM to parse the config file, but it would be useful to write one. An LLM could supply a diff to make the changes you want without learning the config-language-du-jour.
Absolutely not. We do not want a stochastic program without any actual understanding of the schema to be interpreting config data.
> The LLM output could then be any format that's easy and unambiguous to parse.
Thats the problem isnt it? LLMs arent deterministic. Terrible for prod
I'm not sure why there's a problem before even trying.
Say for instance you have a program that keeps recipes. In your configuration file, there's settings such as metric/imperical units, allergies, diets, type of stove in your kitchen, and some theming (font, size, color...). You put them all in a file that you can parse, but aunt tillie messes up the formatting and the program breaks.
Instead of changing the config by hand, an LLM could supply the diff according to instructions in English. I really don't see why this would be "Terrible for prod". If the LLM screws up, you're simply back to square 1 and aunt tillie will call you just like she would before she had an LLM to fix her computer.
Llms are absolutely deterministic if you want them to be.
Still a terrible idea for config
Don't you need the same model, on the same hardware, with the same prompt, and temperature set to 0 to make it deterministic?
[dead]