A commonly asked question regarding JSON is “How do I add comments to a JSON file?”. The short answer is simple: JSON comments are not supported. This is a limitation that many developers feel like is a serious mistake and a point of frustration. Adding comments in code is very useful to explain what’s going on, or toggle settings on or off.
Suppose you want to add a comment to explain an issue with the scores of a user:
{
"name": "Joe",
"age": 42,
// warning: the scores are incomplete! The data isn't updated since 2022-11-05
"scores": [31.4, 29.9, 35.7],
"winner": false
}
This makes the JSON invalid. Now what?
Why JSON comments are not allowed
So, why are JSON comments not allowed? To learn about that, we need to listen to Douglas Crockford, who discovered JSON. He explains the reason for not supporting comments in a post on Google Plus (the website doesn’t exist anymore, but is still referenced in a HackerNews discussion):
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.
You can say what you want, but an important reason for JSON being so ubiquitous and reliable as it is today is because the data format is so simple and straightforward. That is thanks to Douglas Crockford restricting the format to not support things like comments, single quotes, optional quotes, and more advanced data structures. The reason behind it is keeping the format simple on purpose, applying the rule of least power. JSON is the intersection of the common data structures of all programming languages, not the union.
Note that you can find documentation on the exact JSON syntax on https://json.org.
Why do we want comments in JSON in the first place?
Most frustration comes from hitting the limits when using JSON for configuration files instead of data. JSON is a generic data format, not a configuration format. It was not specifically intended to be used for configuration files.
A configuration format has different needs than a data format, and this mismatch is behind most of these frustrations. As a data format, JSON also has its limitations like not supporting dates, but most frustration originates from using it for configuration files.
In the JavaScript ecosystem, JSON is often used for configuration files. It is for example the format that npm uses for package.json. And tools like TypeScript, ESLint, Prettier, and Mocha can be configured using JSON files such as tsconfig.json, .eslintrc.json, .prettierrc, and .mocharc.json respectively.
When you use JSON for configuration, and you hit its limitations, it is best to look around and see if it is possible to use another format instead, better suitable for configuration. Many JavaScript tools support alternative formats. You can often use plain JavaScript itself. And there are formats like TOML, YAML and JSON5 which are more flexible and suitable for configuration.
For example, JSON5 and YAML are supported by pnpm, and YAML is supported by yarn, two alternatives to npm. ESLint supports YAML too. I personally find YAML hard to write, I always have issues with indentation in nested objects and lists, but that may be just me. In the article The 3 Best Config File Fomats you can read more on what makes a good format for config files and find some good advice. Most important for a good configuration format is that it is concise and easy to read and write for humans.
Is there a workaround, so I can use comments in JSON?
First: writing comments inside your JSON may not be a problem! You may notice that IDE’s Webstorm or VS Code do not complain about it when typing comments in a known configuration file such as tsconfig.json (whilst it will complain when adding a comment in a random .json file). A configuration file with comments is not strictly valid JSON. But it can be fine in practice. Alternatively, if supported by the tool, you can change the file extension explicitly to .json5 or .yaml to make it a different and valid format.
If you need to parse the JSON file yourself though, you’ll need to convert the file into plain JSON before you can use it. You can for example use the free tool JSON Editor Online to remove comments from a JSON-like document: open the file in the editor, and then click “Auto repair”. When using the file programmatically, you can first use a library like jsonrepair or jsmin to clean up the comments.
Now, there is a way to put comments in JSON whilst keeping the file strictly valid JSON. You can insert a new line with a key/value pair in the object holding a comment, like:
{
"compilerOptions": {
"module": "system",
"_comment": "we temporarily allow 'any' during the migration",
"noImplicitAny": false,
"preserveConstEnums": true,
"outFile": "../../built/local/tsc.js",
"sourceMap": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "**/*.spec.ts"]
}
But: in more and more cases, your IDE will complain about the comment field. When the config file is validated against a schema and known properties, the IDE will warn about unknown fields like _comment.
JSON Conclusion
Can comments be used in JSON? No, JSON does not support comments. This issue mostly pops up when using JSON for configuration files, whereas JSON is a data format. However, in practice you may be able to just use comments in configuration files without a problem: if both the tool and the IDE know about the configuration file, like TypeScript’s tsconfig.json, they will allow comments in the file even though it is formally invalid JSON. Another solution is to use a different configuration format instead, such as TOML, JSON5, or YAML. This will only work if the tool supports the format. If you have a JSON-like document, you can always use JSON Editor Online to remove comments and turn it into strictly valid JSON.