Comments in JSON

JSON files are often used for configuration. It’s convenient and widely supported format. Practically any programming language supports it.

In Node.js, it’s even possible to require it and get immediate access to the data contained.

An example:

{
  "test": {
    "value": 42
  }
}

And then:

const config = require('./config.json');

console.log(config.test.value);

Problem with JSON as config

But there’s one problem with JSON as a configuration file. It’s very common to include comments to explain what exactly each setting does. Especially in example configurations, that’s very helpful for someone who is just starting.

Because JSON was originally conceived as a data interchange format, the lack of comments is understandable. Nonetheless, it’s limiting when used for configuration purposes.

Simple solution

Fortunately, there’s a simple solution. One can add additional keys which will contain required description. That way there’s no need to detach the configuration file itself from the documentation. And additional data will be ignored by the application requiring it.

{
  "test_description": "object holding important data",
  "test": {
    "value_description": "the value to print",
    "value": 42
  }
}

By convention, I use _description keys, so they are easily associated with the thing they are described.