Node.js – Adding comments to JSON files

Due to its tight coupling and interoperability with JavaScript, JSON has become the standard data transfer format for most JavaScript and Node.js applications. As opposed to its primary competitor format XML, JSON is much more compact and efficient for data transfer, and has a direct one-to-one mapping with the memory structures in the code. What JSON doesn’t enable, however, are comments in the JSON files.

Although the topic of JSON comments has spawned multitudes of theoretical discussions between the naysayers and yaysayers, the fact is that there are many instances where comments in JSON would be helpful. When JSON is used in configuration files, for example, comments can add in-line documentation to the files, and explain exactly what each parameter does and what the options are. This is primarily useful in situations where the JSON files are hand-edited, as opposed to system-generated. Additionally, comments can be used to encode meta-level information, such as last modification date, author, and revision data.

Simple JSON Comments

There are two primary methods to adding comments to JSON. The first, and easiest method is to simply add the comments as JSON attributes to the file. Be sure to prefix the comments with an underscore or other distinct character to make it simpler to ignore when parsed by the reader:

{
  "_comment":"Sample comment",
  "key":"value"
}

The drawback of this method is that it requires the reader to consciously ignore the comments when handling the file. These types of comments can cause unexpected errors, or possibly send sensitive information into the wrong hands. If possible, it is much better to use the following pre-parsing method.

JavaScript-Style Single-Line Comments

The second method for adding comments to JSON files is to pre-parse the files before loading them into the system. This method is ideal for handling configuration files:

function JSONstrip(txt){
  var re = new RegExp("\/\/(.*)","g");
  return txt.replace(re,'');
}
 
var jsontxt = fs.readFileSync(filename,'utf8');
jsontxt = this.JSONstrip(jsontxt);
var obj = JSON.parse(jsontxt);

The program first reads the configuration file and stores it into a variable. Next, it runs a regular expression to delete any comments from the file, and finally parses the JSON syntax. This method currently only works on single-line “//” comments, however it could be extended to multi-line “/* … */” comments with another regular expression.

Note, using this method will cause an error if the actual data contains “//”. As a result, it is recommended to use this only in instances where the files are manually edited, or generated through a manual process. Automated use of this technique would require escaping the “//” characters through additional handlers.

Within the Node.js environment, this method has both benefits and drawbacks. The primary drawback is that the JSON files cannot be simply “required” by the code, and included in-line. The commented JSON files will need to be processed by a reader. The benefit, on the other hand, is that the JSON files are not cached using this method, so development work is simpler and does not require a server restart upon each edit. When switched to production mode, however, it is recommended to implement a memory-based cache to reduce file I/O.

Deciding which commenting method to use will depend on the application. In the end, if neither method works, for example in situations where commented files will need to be auto-generated based on dynamic data, it would be beneficial to switch to a different file format such as XML for the application’s data storage needs.

Written by Andrew Palczewski

About the Author
Andrew Palczewski is CEO of apHarmony, a Chicago software development company. He holds a Master's degree in Computer Engineering from the University of Illinois at Urbana-Champaign and has over ten years' experience in managing development of software projects.
Google+