5+ Ways and Tools for Adding Comments in JSON

In this article, we’ll learn how to use comments in JSON files. We’ll see workarounds and methods used by developers to add single-line and multiple-line comments to their JSON files, the external libraries and packages for stripping comments from your files before feeding them to the regular JSON.parse() method in JavaScript and Node.js and we'll also see simple JavaScript code for removing comments without external libraries. Finally, we'll see the alternative formats to JSON that support comments such as JSON5 and JSONC.

JSON Doesn’t Support Comments!

As you might be aware of, JSON doesn’t support comments! But as programmers, we are used to add comments so in this article, we’ll see the possible ways that we have to use comments in our JSON files even if they are natively supported by the format.

In fact, comments were not always missing in JSON but were removed later.

This is the reason of removing comments from JSON as stated by Douglas Crockford.

I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability.

JSON can be mostly needed if you use JSON for your configuration files even if JSON in the first place wasn’t designed for this purpose but for exchanging data but, we see it nowadays used as a configuration format in many apps.

For example the tsconfig.json file which is the configuration file for TypeScript does allow comments, see microsoft/TypeScript#4987.

You also can use comments to comment out values in your data files when testing instead of removing them.

As developers we tend always to find a solution for our problems and in case of JSON comments, we also have solutions, let’s explore it.

In nutshell, these are the available ways and tools to add comments in JSON:

• You can add comments as JSON data,
• Google’s GYP supports #-style comments,
• JSON.minify will help you discard C/C++ style comments with JavaScript/Node.js,
• JSMin is a minification tool for JavaScript that removes comments and unnecessary whitespace from JavaScript files but can be used for JSON files,
• Hjson: a user interface for JSON that allows you to use comments to document your data inline. You can also use them to comment out values when testing,
• strip-json-comments: It will replace single-line comments // and multi-line comments /**/ with whitespace. This allows JSON error positions to remain as close as possible to the original source. Also available as a Gulp/Grunt/Broccoli plugin,
• comment-json: Parse and stringify JSON with comments in JavaScript/Node.js. It will retain comments even after saved!
• nlohmann/json: A JSON parser for modern C++ that provides optional support for ignoring comments on parsing. As stated by the creator of JSON, it’s okay to add comments to your JSON data as long as you use a tool to strip them before parsing the file.

For a detailed explanation, check out how to add comments to JSON.