Using JSON as a configuration format is a mistake.
Yes, a mistake. Not a preference. Not a style choice. An architectural mistake
That sentence tends to bother people because JSON works. And when something works, the industry has a strong tendency to stop questioning whether it actually makes sense.
JSON is a massive success as a transport format. It is predictable, deterministic, easy to parse, and practically universal. Between machines, it is excellent. The problem starts when we decide that those same qualities somehow qualify it to be written, read, versioned, and maintained by humans.
They don’t.
This article is about that mismatch: JSON is excellent at what it was designed to do, and deeply uncomfortable when we insist on using it everywhere else.
Why JSON Won
JSON did not win because it is elegant, expressive, or pleasant to work with. It won because it is boring, limited, and predictable — and those are powerful qualities when the problem is communication between systems.
It is a small, closed format with very few syntactic ambiguities. It is easy to implement, hard to misinterpret, and extremely cheap to support across languages and platforms. It drastically reduces the space for creativity, and that is exactly what you want when two processes that do not know each other need to exchange data without discussing intent, context, or meaning.
From a machine-to-machine communication perspective, JSON is close to ideal. It enforces simple structures, avoids clever shortcuts, carries no implicit semantics, and refuses to be smart. It is essentially a predictable envelope of primitive data. Machines love it. Compilers love it. Infrastructure loves it.
When someone says “my API speaks JSON”, everyone immediately understands what that implies. There are no surprises, no creative interpretations, no “well, in this case…”. There is a contract. And rigid contracts are very good when nobody wants to negotiate at runtime.
As a transport format, JSON fully deserves the status it has.
Where Things Start to Go Wrong
The problem begins when someone looks at that same format — clearly designed for machine-to-machine communication — and decides it is also a good idea for human authorship.
This usually does not come from malice. It comes from architectural laziness. The reasoning is simple: if the system consumes JSON, then humans should write JSON. It sounds logical. It is also a terrible idea.
JSON demands absolute syntactic precision to express even the smallest intent. A missing comma, a forgotten quote, a mismatched bracket, and everything breaks. There is no partial failure. There is no graceful degradation. There is only a parse error and the end of the conversation.
That behavior is perfectly acceptable for machines. For humans, it is hostile — and that is coming from someone who genuinely likes strong typing and explicit contracts.
JSON Is Structurally Hostile to Humans
This is not a matter of taste. It is structural.
JSON does not allow comments. JSON does not allow trailing commas in its canonical form. JSON does not allow shortcuts. JSON does not allow relaxed syntax. JSON does not provide context. JSON does not communicate intent — only structure.
As a result, anyone writing JSON is forced to think constantly about syntax instead of meaning. Instead of reasoning about the domain, you are mentally validating brackets, quotes, commas, and nesting levels. That is a high cognitive tax for a task that is already complex by nature.
When you see a large JSON file written by hand, it rarely communicates clarity. It communicates resistance. It communicates that someone suffered while writing it.
JSON Configuration Is a Normalized Mistake
Configuration files written in JSON are probably the most common example of this dysfunction. They are everywhere, they work, and everyone accepts them as “just how things are”. That does not make them a good solution.
Configuration is, by definition, something that will be read, written, reviewed, versioned, and discussed by humans. It carries intent, context, and often requires explanatory comments. JSON offers none of that.
The result is verbose files that are painful to review in pull requests, impossible to annotate properly, and full of external conventions like “this field is optional, but only in this scenario, explained somewhere in a README you will forget exists”.
It works. But it works fueled by quiet resentment.
The Pro-JSON Argument
“But JSON is simple. Everyone knows it.”
Yes, everyone knows it. That does not make it appropriate.
Everyone knows assembly as well. That does not mean we should write business rules in it. Familiarity is not a criterion for tool choice. Suitability to the problem is.
JSON is simple to consume, not to produce. And that difference matters far more than it initially appears.
Authoring Formats Exist for a Reason
When you use TypeScript, YAML, TOML, HCL, or any minimally decent DSL to define complex structures, the difference is immediate. These formats were designed to be written, read, and maintained by people.
They allow comments. They offer some flexibility. They communicate intent more clearly. They reduce the cognitive cost of writing. Most importantly, they allow the human to think about the problem first and the representation second.
The fact that many of these formats are eventually converted into JSON internally is not an accident. It is healthy architecture.
The Pipeline That Avoids Unnecessary Suffering
In well-designed systems, the flow is usually simple and predictable:
A human writes something expressive, validatable, and comfortable (often typed).
A machine validates, transforms, and normalizes that structure.
JSON appears only when it needs to travel or be persisted as a contract between systems.
This separation is not bureaucracy. It is respect for human limitations.
If you are writing strongly typed settings for a system, TypeScript works extremely well.
If you are writing a configuration structure meant to be read and maintained, YAML or a similar format makes sense.
If one machine needs to send data to another machine, JSON is the perfect choice.
When you write an API, for example, you work with objects, types, validations, and abstractions. JSON is generated at the edge, sent over the network, parsed on the other side, and immediately disappears from human concern. Nobody manually touched that JSON — and that is exactly the point.
This pattern shows up repeatedly in modern tools because it works. It respects human constraints and leverages machine strengths. Forcing JSON from the very beginning skips this step and pushes all the cost onto the people who should be paying it the least.
Hater or Fan?
I still love JSON where it makes sense: transport, contracts, serialization, system-to-system communication. And I still hate JSON when someone expects me to write, review, and maintain complex structures in it as if that were a reasonable experience.
This is not stubbornness.
It is not trend-chasing.
It is not technical elitism.
It is basic respect for the people who have to deal with the code.
JSON does not need to be everywhere to remain valuable. It just needs to stay in the right place.
And that place is definitely not between you and your keyboard at two in the morning.