Understanding JSON: Why Comments Aren't Supported and Alternatives

Introduction to JSON

JSON (JavaScript Object Notation) is a lightweight data-interchange format that’s easy for humans to read and write, as well as for machines to parse and generate. It is based on a subset of the JavaScript Programming Language Standard ECMA-262 3rd Edition – December 1999.

JSON is commonly used in web applications to transmit data between clients and servers. Its simplicity and effectiveness have made it a popular choice among developers worldwide. However, despite its utility, JSON has one notable limitation: it does not support comments.

Why Does JSON Not Support Comments?

The decision to exclude comments from the JSON specification was deliberate. Comments were removed by design for several reasons:

1. Interoperability: One of the main goals of JSON is to ensure interoperability across different systems and languages. Allowing comments could lead to inconsistencies in how they are interpreted, thus affecting compatibility between implementations.

2. Purity of Data: JSON was intended solely as a data format, not for configuration files or scripting. Including comments would blur this line, making it less clear that the content should be purely data.

3. Parsing Complexity: Supporting comments could complicate the parsing process. By keeping JSON simple and comment-free, parsers can be more straightforward and efficient.

Douglas Crockford, one of the creators of JSON, explicitly stated: "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." This suggests a workflow where comments are stripped out before parsing.

Alternatives for Adding Comments

If you need to add annotations or comments in a data format similar to JSON, consider the following alternatives:

1. Use a Dedicated Configuration Format: Formats like HJSON (Human-readable JSON) allow for more relaxed syntax and support comments. It’s designed specifically for configuration files where human readability is crucial.

2. Pre-Processing Tools: Before parsing your JSON, you can use tools or libraries to strip out comments. For example, JSON.minify() removes comments and whitespace from a JSON string, making it valid for parsing with standard JSON parsers.

3. Metadata Keys: As a workaround in pure JSON, you might include a reserved key (like _comment) to hold comment-like data. However, this is not standardized and should be used cautiously since such entries would be part of the actual data set.

Example: Using HJSON

Here’s how you could use HJSON for configuration files with comments:

# This is a configuration file example
title: "Example Glossary"
glossDiv {
  title: "S"

  glossList {
    glossEntry {
      ID: "SGML"
      SortAs: "SGML"
      # Standard Generalized Markup Language
      GlossTerm: "Standard Generalized Markup Language"
      Acronym: "SGML"
      Abbrev: "ISO 8879:1986"

      GlossDef {
        para: "A meta-markup language, used to create markup languages such as DocBook."
        GlossSeeAlso: ["GML", "XML"]
      }
      GlossSee: "markup"
    }
  }
}

Conclusion

While JSON’s lack of support for comments might seem like a limitation, it is by design to ensure simplicity and interoperability. For scenarios requiring annotations, consider using alternative formats like HJSON or preprocessing tools that allow you to include comments without affecting the integrity of your data format.