JSON Comments: Complete Guide with Examples

What is JSON?

JSON (JavaScript Object Notation) is a lightweight text format for storing and transmitting data over a network. JSON is used when sending data to or from the server and making API calls. The MIME type for JSON is application/json. JSON file names use the .json file extension.

Can I add a comment in JSON?

No, JSON is a data-only format. Comments in the form //, #, or /* */, which are used in popular programming languages, are not allowed in JSON. You can add comments to JSON as custom JSON elements that will hold your comments, but these elements will still be data.

Why doesn't JSON support comments?

Douglas Crockford, who popularized the JSON data format, deliberately removed comments from JSON to prevent misuse of the JSON format and keep it as a data-only format. He describes why he removed the comments from the JSON as follows: I removed comments from JSON because I saw people using them to store parsing directives, which would break compatibility.

Therefore, the only option for adding comments to JSON is a workaround to use custom elements to store comments in a JSON file. Unlike JSON comments, XML comments are supported out of the box.

Adding JSON comments as custom JSON elements

Since JSON is a textual format for storing and exchanging data using key-value pairs, we can add comments as data pairs in JSON. We added the comment as a custom "_comment" element to this JSON comment example. The underscore is used as a convention to distinguish comments from the rest of the data. This custom comment element will be received and processed in the same way as any other data in JSON on the server-side. Therefore, your server should ignore this element when processing the received JSON.

{
  "Id": 1,
  "_comment": "Put your JSON comment here"
}

How to add multiple comments to a JSON file?

JSON does not allow duplicate object keys, so to have multiple comments in a JSON file, you need to add a unique letter or number to your comment element to make it valid. To make it easier for other developers to read your comments in the JSON file and to make it easier to programmatically process that JSON file, we recommend using the "//" convention. As a basis for comment titles.

{
  "Id": 1,
  "//first_comment":  "The first JSON comment.",
  "//second_comment": "The second JSON comment."
}

How do I add comments to nested JSON elements?

Since JSON comments are the same elements as any other, you can add comments to nested elements in the same way as for root elements. In addition, adding comments to nested elements avoids the problem of duplicate element names since element names in JSON can be the same if they are located at different levels of nesting. The example below shows JSON comments for nested elements.

{
  "Id": 1,
  "//first_comment":  "First comment.",
  "//second_comment": "Second comment.",
  "item": {
    "Name": "Item",
    "//first_comment":  "First comment.",
    "//second_comment": "Second comment.",  
  }
}

Adding Comments to JSON Using External Tools

We can also use special tools that preprocess JSON files and strip comments from JSON before passing those files to JSON parsing libraries. These tools help us avoid parsing errors, use comments in any form, and avoid treating them as data. Let's take a look at popular tools that help remove comments from JSON files before parsing them:

• JSON.minify will help you discard C/C++ style comments with JavaScript and Node.js.
• JSMin is a minification tool for JavaScript that removes comments and unnecessary whitespace from JavaScript files that can be used for JSON files.
• strip-json-comments will replace single-line comments "//" and multi-line comments /* */ with spaces. Also available as a Gulp/Grunt plugin.

How to remove JSON comments using Node.js?

To remove comments in a JSON file without using external libraries, you can preload the file from the disk and remove all comments from it before parsing. For example, with this simple Node.js code:

const removeJSONComments = (json) => {
  let re = new RegExp("\/\/(.*)","g");
  return json.replace(re,'');
}
    
let json = fs.readFileSync('file.json','utf8');
json = removeJSONComments(json);
let data = JSON.parse(json);

What is JSONC?

JSONC format (stands for JSON with comments) was created by Microsoft and is supported by Visual Studio Code. JSONC is a lightweight JSON format that allows JavaScript-style comments to be added to JSON.

{ /*
   This is a multi-line
   comment in a JSONC.
   */

   "Id":1 // This is a single-line comment in JSONC.
}

Conclusion

JSON does not support comments by design. However, we can still use comments in JSON files as custom elements or use various tools that preprocess JSON files and remove comments from them before parsing. Alternative JSON file formats, such as the Microsoft JSONC format, have built-in support for comments.

See also

• Test JSON API
• REST API Example
• JSON Payload Example
• How do I use JSON pagination?
• What is the correct Content Type for JSON?
• How do I post JSON to a REST API endpoint?
• POST JSON String With Basic Authentication