Comments in JSON Files

Standard JSON does not support comments in any form. There is no syntax for single-line comments (//), block comments (/* */), or hash comments (#). Any attempt to include comments in a JSON document will cause a parse error with any compliant JSON parser.

Why JSON excludes comments:

Douglas Crockford, the creator of JSON, has explained that he removed comments from JSON to prevent them from being used as parsing directives, which would have fragmented the format and reduced interoperability. His design philosophy was that JSON is a data interchange format, not a source code format. Data being exchanged between systems does not need human annotations — the schema and documentation serve that purpose.

The developer frustration:

This design decision is one of the most frequently debated aspects of JSON. Configuration files like package.json, tsconfig.json, and .eslintrc.json are written and maintained by humans, and the inability to explain why certain settings exist, document deprecated options, or leave TODO notes is a genuine productivity issue. This frustration has led to the creation of comment-supporting alternatives.

Workaround: the _comment key convention:

Some developers add documentation using a conventional key name:

{
  "_comment": "Timeout is in milliseconds",
  "timeout": 5000
}

This is technically valid JSON because the key is just a regular string property. However, it pollutes the data model, and applications consuming the JSON must ignore these keys or they may cause unexpected behavior.

Alternatives that support comments:

• JSONC: Allows // and /* */ comments and trailing commas. Used by VS Code, TypeScript, and other Microsoft tools.
• JSON5: A broader superset allowing comments, trailing commas, unquoted keys, single-quoted strings, and more.
• YAML: A completely different format that supports comments with # and is often used for configuration where JSON's limitations are too restrictive.
• TOML: Another configuration format with comment support, used by Rust (Cargo.toml) and Python (pyproject.toml).

Common mistakes developers make:

The most frequent mistake is adding // comments to standard JSON files and being confused when the parser fails. Another mistake is using a preprocessing step to strip comments but failing to handle edge cases like comment-like sequences inside string values (e.g., "url": "https://example.com" contains // inside a string). Always use a purpose-built JSONC parser rather than regex-based stripping.

Best practices:

If your tool supports JSONC, use it and name the file with a .jsonc extension when possible. For strict JSON, keep documentation in separate files or use descriptive key names. Never add comments to JSON files that will be consumed by standard parsers.