Comments in JSON

JavaScript Object Notation (JSON) is a standard text-based format based on JavaScript object syntax. This format is easy and readable to users as its syntax uses human-readable text to hold and transmit data objects comprising attribute-value arrays and pairs. JSON is a language-independent data format.

It supports nearly any type of framework, language, or library. Like other programming languages, users can use comments in JSON to make their documentation more readable and understandable.

But they cannot directly write comments in a JSON file as it does not allow comments. In this article, we will discuss why JSON does not support comments and the alternative way to add comments in a JSON file.

What are comments in JSON?

As per the rules of the Standard JSON, there is no official record that tells JSON support comments. According to the standard rules, JSON includes keys and values, and different parsers can parse these using programming libraries.

But, users need to retain support for the parse() method that parses a JSON string and reads and understands the comments even if JSON allows comments.

Syntax of a JSON file:

const a = '{"result": false, "count": 12}';
const b = JSON.parse(a);
console.log(b.count);
console.log(b.result);

Output:

Explanation:

JSON file takes key-value pair for data. Here, we used the curly brackets that hold the objects, and a colon follows after each name. The comma separates the key-value pair.

Comments as Data:

Since the JSON file does not directly support comments, we will have to choose alternatives to put comments in the JSON file.

For example:

{
"key": "value" // JSON files does not allows comments
}

It is an invalid syntax in the JSON file.

Code Snippet:

{
    "//field1": "Note, we are using the 'double quote' and 'double quote' are used as comments because JSON does not allow comment",
    "field1": {},
    "#field2": "Another comment",
    "field2": {},
    "/*a": "We should be careful while using them when we have full control of the content ",
    "a": [],
    "b": "bla"
}

Output:

Explanation:

Here, we used comments inside the JSON file by adding data to the JSON file that functions as comments.

Another example of the JSON comment is as follows:

Code Snippet:

{
    "//field1": "Note, we are using the 'double quote' and 'double quote' are used as comments because JSON does not allow comment",
    "field1": {},
    "#field2": "Another comment",
    "field2": {},
    "/*a": "We should be careful while using them when we have full control of the content ",
    "a": [],
    " __comment2__": "It is a comment"
}

Output:

Explanation:

In the above program, we have used underscores to help distinguish the comment from other data in the JSON file.

Note: It is a must to notice that a comment is only a comment in the eyes of a programmer, not the computer.

Another example of using multiline comments in a JSON file is as follows:

Code Snippet:

{
  "Name": "A",
  "//first_comment":  "This is the first JSON comment.",
  "//second_comment": "This is the second JSON comment.",
  "//third comment": "This is the last comment"
}

Output:

Explanation:

Here, we have used multiple comments in the JSON file.

Adding comments to a nested JSON file:

In the above examples, we have learned to add single-line comments and multiple comments in single elements of the JSON file. We can also use more than one element with single and multiple comments.

Code Snippet:

{
  "A": 1,
  "//comment1":  "This is a comment.",
  "B": {
    "Name": "Item",
    "//comment1":  "This is another comment of the second element."
  }
}

Output:

Another example with multi-line comments is as follows:

Code Snippet:

{
  "A": 1,
  "//comment1":  "This is the first comment.",
  "//commen2t":  "This is the second comment.",
  "B": {
    "Name": "Item",
    "//comment3":  "This is the first comment of the second element.",
    "//comment4":  "This is the second comment of the second element."
  }
}

Output:

Why does JSON file not allow comments?

There are many reasons why JSON file does not support comments. These are as follows:

• JSON is an open, lightweight data-interchange format between client and server that contains data in only keys and values format.
• The server generates the JSON data, and clients or customers take that JSON data from the server. So, there is no need for any explanation about "what JSON data is" or any other documents in a text that are not applicable in the program in the form of comments.
• One of the significant reasons why programmers should not use comments is that if they add comments to a JSON file, it creates difficulty for the human and library parser to read the JSON data.
• Generally, users add comments to source code to explain lines of code. But when it comes to JSON, it is purely about data format and the data transfer between server and client. Hence, it is not viable to add comments in JSON files.

Conclusion:

Though JSON file does not support comments, there are other options for programmers to add single and multiple comments in a JSON file. We hope this article has provided all the ways to add comments in JSON files. Also, this article brings up the reasons why JSON does not support comments.