Home Weblog index

JSON as configuration files: please don’t

Written on 7 Feb 2016 − last updated on 17 Dec 2016

Writing the config in JSON was a huge mistake lol. Wish I’d paid for attention beforehand.

I’ve recently witnessed the rather disturbing trend of using JSON for configuration files.

Please don’t. Ever. Not even once. It’s a really bad idea.

It’s just not what JSON was designed to do, and consequently not what it’s good at. JSON is intended to be a “lightweight data-interchange format”, and claims that it is “easy for humans to read and write” and “easy for machines to parse and generate”.

As a data interchange format JSON is pretty okay. A human can read and write it comparatively easily, and it’s also pretty easy to parse for machines (although there are problems). It’s a good trade-off between machine-readable and human-readable and a huge improvement on what it intended to replace: XML, which I consider to be unreadable by both machines and humans.
But using it for other purposes is somewhat akin to saying “hey, this hammer works really really well for driving in nails! I love it! Why not hammer in this screw with it!” Sure, it sort of works, but it’s very much the wrong tool for the job.

Specific shortcomings

Lack of comments

This is by far the biggest problem: you can’t add comments in JSON files. The occasional JSON parser supports it, but most don’t and it’s not in the standard, in fact, comment support was explicitly removed from JSON for good reasons.

This is very problematic.

One suggested workaround is to use a new key, e.g.:

	"__comment": "Something to comment about",
	"actual_data": "Hello, world"

But this is just damn ugly.

Other people have pointed out that you can use the commit log, but this is an even worse idea. Consider something like bower:

// Please be VERY CAREFUL when updating this, since this library often
// makes incompatible changes even in minor bugfix releases (e.g. when
// updating from 1.1.1 to 1.1.2).
'some_stupid_lib': '1.1.1'

So, are you going to dig though the entire commit history in search for some important message?

Of course not.


It’s just not that readable. Sure, it’s readable for a data-interchange format, but not readable for a configuration file.

Readability counts.


The JSON standard is fairly strict − this is good, it allows for concise and fast parsers that don’t have to muck about with different formats − but it also means it’s more difficult to write.

For example a trailing comma in objects or arrays is an error, and something that has bitten me more than once. And having to escape all instances or " can be pretty annoying if your string contains a lot of "s.

Lack of programmability

Not always an issue, but sometimes it is, especially when JSON is used to configure some piece of code.

For example, consider:

# This works much better on BritOS
if ($uname === 'BritOS')
	$wear = 'trousers';
	$wear = 'pants';

This is an issue for example in MediaWiki’s skin.json file. What I wanted to do is not include some CSS if a certain plugin is loaded, and we can’t do this − we can (probably) work around it in the PHP file, but “working around” things is never good (and remember, we can’t leave a comment in the JSON file to inform people that we’re working around things!)

The old way of doing things in MediaWiki (declaring class variables) was a lot better and provided much more features.



Name and shame :-)



You can mail me at martin@arp242.net for feedback etc. No, I don’t have Twitter, but you can use this form to send me an email if you want.

Copyright © 2010-2016 Martin Tournoij <martin@arp242.net>
This document is licensed under a cc-by 4.0 license.