JSON Comments: Complete Guide to Adding Comments

According to the official JSON specification (RFC 8259), comments are not allowed in JSON files. The JSON format was intentionally designed to be a lightweight data interchange format without support for comments in order to maintain simplicity and ensure reliable parsing by all implementations. However, there are several workarounds and alternative formats that do support comments if you need this functionality.

Contents

• Official JSON Specification Stance
• Why JSON Doesn’t Support Comments
• Alternative Formats with Comment Support
• Libraries That Parse Comments
• Practical Recommendations

Official JSON Specification Stance

The current official JSON specification, RFC 8259, explicitly does not include support for comments. According to the specification, any text outside the defined JSON syntax is considered invalid. This means that standard JSON parsers will reject files that contain comments, whether they’re single-line comments (//) or multi-line comments (/* */).

JSON was derived from the ECMAScript Programming Language Standard, but intentionally omits comments to maintain simplicity and ensure reliable parsing across all implementations.

The specification states that JSON defines “a small set of formatting rules for the portable representation of structured data,” and comments were deliberately excluded from this design. This decision was made to keep the format minimal and to ensure that any JSON text could be parsed by any compliant parser without ambiguity.

Why JSON Doesn’t Support Comments

The absence of comment support in JSON stems from several design principles:

1. Simplicity and Minimalism: JSON was designed to be as simple as possible. Comments would add complexity to both the specification and parsing logic.

2. Reliable Parsing: Without comments, JSON parsers can be simpler and more reliable. Comments could potentially introduce parsing ambiguities or edge cases.

3. Data Interchange Focus: JSON is primarily a data interchange format, not a configuration format. The philosophy is that comments are metadata about the data structure, not part of the data itself.

4. Interoperability: By excluding comments, JSON ensures that all implementations can handle the same format without special handling for comment syntax.

As noted in the RFC 8259 specification, the JSON format was designed to remove inconsistencies with other specifications and to offer experience-based improvements while maintaining the core simplicity that made JSON popular.

Alternative Formats with Comment Support

If you need comment support in your JSON-like files, there are several alternatives to standard JSON:

JSON5

JSON5 is an extension of JSON that adds support for comments, among other human-friendly features. JSON5 allows:

• Single-line comments using //
• Multi-line comments using /* */
• Trailing commas
• Unquoted keys
• Strings that can use single quotes

// This is a single-line comment
{
  /* This is a multi-line comment */
  name: "John Doe", // inline comment
  age: 30,
  // trailing comma is allowed
}

HJSON

HJSON (Human-JSON) is another format designed to be more human-readable, supporting comments and other features that make it easier to write by hand.

YAML

YAML is a superset of JSON that includes support for comments and is often used as a configuration format when comments are needed.

CSON

CSON (CoffeeScript JSON) is another JSON variant that supports comments and additional syntax features.

Libraries That Parse Comments

While standard JSON doesn’t support comments, some libraries can parse JSON files that contain comments, though this is non-standard behavior:

nlohmann/json

The popular C++ JSON library nlohmann/json has optional support for ignoring comments during parsing. This feature must be explicitly enabled and is not part of the standard JSON specification.

Python Libraries

Some Python JSON libraries can handle comments:

• json5 - specifically designed to parse JSON5 format
• demjson - a library that can parse JSON with JavaScript-style comments
• commentjson - a library that specifically handles JSON with comments

JavaScript Libraries

In JavaScript, you can use libraries like:

• json5 - for parsing JSON5 format
• JSON5 - the reference implementation for JSON5

It’s important to note that using these libraries makes your code dependent on non-standard behavior, which could cause issues if you need to exchange JSON data with systems that expect strict compliance with the official specification.

Practical Recommendations

When working with JSON files, consider these recommendations regarding comments:

For Configuration Files

If you’re working with configuration files and need comments, consider using:

• JSON5 - if you want JSON-like syntax with comment support
• YAML - for more complex configuration with rich comment support
• TOML - another configuration format that supports comments

For Data Interchange

When exchanging data between systems:

• Avoid comments in JSON files meant for data interchange
• Use separate documentation files to explain the data structure
• Consider using schema definitions (JSON Schema) to provide metadata about the data structure

For Development Environments

In development contexts where readability is important:

• Use JSON5 or other comment-supported formats during development
• Convert to standard JSON before deployment or distribution
• Use build tools to automatically strip comments from JSON files

Sources

1. RFC 8259 - The JavaScript Object Notation (JSON) Data Interchange Format
2. RFC 8259 - Information on RFC 8259 » RFC Editor
3. Can comments be used in JSON? - Stack Overflow
4. Why JSON comments are not allowed and what to do about it | Indepth
5. Comments Inside JSON – Commenting in a JSON File
6. JSON Comments - Tutorialkart
7. JSON - Wikipedia
8. JSON5 – JSON for Humans

Conclusion

The official JSON specification (RFC 8259) does not support comments, as this was a deliberate design choice to maintain simplicity and ensure reliable parsing across all implementations. While this limitation can be frustrating, especially for configuration files, there are several alternatives available. For development scenarios requiring comments, JSON5 provides a JSON-compatible format with comment support, while formats like YAML offer more extensive features. When working with data interchange, it’s best to avoid comments and use separate documentation or schema definitions instead. The choice ultimately depends on your specific use case and whether you prioritize strict JSON compliance or enhanced readability and documentation capabilities.