How to Comment Out in JSON: Complete Guide

JSON (JavaScript Object Notation) is a lightweight data-interchange format that's easy for humans to read and write. However, one limitation of standard JSON is that it doesn't support comments natively. This can be frustrating when you need to document your JSON structure or temporarily disable parts of your configuration. In this comprehensive guide, we'll explore why JSON doesn't support comments, various workarounds, and best practices for documenting your JSON files.

Why JSON Doesn't Support Comments by Default

JSON was designed to be a minimal and simple data format. The creators deliberately excluded comments to keep the specification small and parsing fast. The official JSON specification only allows for strings, numbers, booleans, null, objects, and arrays. Adding comments would increase complexity and potentially introduce parsing ambiguities.

This design choice means that standard JSON parsers will throw an error if they encounter what looks like a comment. For example, these would all be invalid in standard JSON:

{"name":"John","age":30,"//comment":true}
{"name":"John","age":30,"/*comment*/":true}
{"name":"John","age":30,"#comment":true}

Workarounds for JSON Comments

Using String Values as Comments

One simple workaround is to use string values that you ignore in your application logic. This approach keeps your file valid JSON while providing documentation:

{"name":"John","age":30,"_comment":"This field is deprecated and will be removed in v2.0"}

While this works, it has drawbacks: the "comment" becomes part of your data structure and may need special handling in your code.

Using an Adjacent Property

Another approach is to use a separate property for comments that mirrors the structure of your data:

{"name":"John","age":30,"comment":"This field is deprecated and will be removed in v2.0"}

External Documentation

For complex JSON structures, consider maintaining documentation separately. Tools like Swagger for API documentation or inline comments in your code that generates the JSON can be effective solutions.

Using JSON5 for Comment Support

JSON5 is a superset of JSON that extends the syntax to include comments, trailing commas, and other features. It's designed to be a more human-friendly version of JSON while maintaining compatibility with JSON parsers.

Here's how JSON5 handles comments:

// Single-line comment
{"name":"John","age":30,"//comment":true}

/* Multi-line
comment */
{"name":"John","age":30,"/*comment*/":true}

To use JSON5, you'll need a JSON5 parser instead of a standard JSON parser. Many popular programming languages have JSON5 libraries available. For example, in JavaScript, you can use the json5 package with npm.

Best Practices for JSON Documentation

While comments aren't natively supported in JSON, here are some best practices for documenting your JSON files:

1. Use meaningful property names that describe their purpose
2. Consider using a separate documentation file (like README.md) to explain complex structures
3. If using JSON5, be consistent with your commenting style
4. Document your JSON schema separately using tools like Swagger or OpenAPI
5. Use version control (Git) to track changes to your JSON files

For developers working with JSON frequently, having the right tools can make a significant difference. Try out our JSON Pretty Print tool to format your JSON files for better readability. Proper formatting can make your JSON structure clearer even without comments.