Why JSON Has No Comments — And Why That Was the Right Call

The Complaint

If you have worked with JSON configuration files — tsconfig.json, package.json, appsettings.json, AWS CloudFormation templates — you have likely encountered the frustration: you cannot add a comment explaining why a value is set to a specific number, what a configuration option does, or which settings should be changed for a specific deployment environment. Standard JSON rejects comments entirely — a parser error, not a warning.

This is one of the most consistent complaints in the history of web development. Stack Overflow questions about JSON comments have millions of views. Tools that use JSON for configuration have invented workarounds: VS Code accepts JSONC (JSON with Comments); TypeScript's tsconfig.json accepts comments; many tools implement their own pre-processing step to strip comments before parsing.

Crockford's Reason

Douglas Crockford has explained his decision to remove comments from JSON clearly, in a 2012 Google+ post (widely reproduced since the platform's shutdown):

"I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't."

"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."

The "parsing directives" Crockford refers to are instructions embedded in comments that change how the parser interprets the file — a practice seen in other formats. For example, an XML processing instruction tells a parser how to handle the document. If JSON allowed comments, some implementations would inevitably begin using comments for similar directives, causing incompatibilities between parsers. JSON's strength is that any conformant parser produces identical results for any valid JSON input. Comments would have broken this guarantee.

The Interoperability Argument

Crockford's core argument is about interoperability — the ability for any two systems using JSON to exchange data without format-specific negotiation. This is JSON's primary design goal as a data interchange format.

Consider what happens if comments existed in JSON:

• Some parsers would strip comments and parse the remaining content
• Some parsers would treat comments as errors
• Some parsers would attempt to interpret comments as metadata
• Some parsers would expose comments to application code; others would discard them

A JSON file with comments could not be reliably exchanged between systems using different parsers. The format would fragment: "standard JSON" would become ambiguous, with different parsers making different choices about comment handling. The result would be the same kind of fragmentation that made XML complex — implementations that were "almost compatible" but not quite.

By excluding comments entirely, Crockford preserved the property that JSON data can cross any system boundary and be parsed identically by any conformant implementation. This is not a comfortable property for the developer writing a configuration file by hand — but it is essential for a format whose primary purpose is machine-to-machine data interchange.

The Wrong Use Case Argument

The other component of Crockford's position — less explicitly stated but implied — is that developers who want comments in JSON are using JSON for the wrong purpose. JSON is a data interchange format, not a configuration file format. Configuration files are written and maintained by humans; they benefit from comments, documentation, and readability features. JSON was designed for data that machines generate and consume, where comments are irrelevant.

When developers use JSON as a configuration file format — as many tools do — they are applying a data interchange format to a use case it was not designed for. The lack of comments is not a bug in JSON; it is a signal that a different format might be more appropriate for this use case. TOML, YAML, and HCL (Hashicorp Configuration Language) are all configuration file formats designed with human authoring in mind; they support comments, multi-line values, and other features that make hand-authored files more maintainable.

The tools that chose JSON for configuration did so partly for convenience (JSON parsers are universally available) and partly because JSON's strictness appealed to developers who wanted a format that would catch errors. The resulting complaint about missing comments is a consequence of a use-case mismatch, not a deficiency in JSON itself.

The Workarounds

Developers who need comments in JSON have several options:

• Use a comment-supporting variant: JSONC (JSON with Comments) or JSON5 add comments while remaining parseable with minimal tool support
• Use a dedicated configuration format: TOML, YAML, or HCL are designed for human-authored configuration and support comments natively
• Use a "_comment" convention: Some teams add a key like "_comment": "explanation here" to JSON objects. This is valid JSON, processes silently through most parsers, and achieves the annotation function at the cost of adding a data key to the object
• Use adjacent documentation: A README or schema document explains the configuration structure, leaving the JSON file itself unannotated
• Pre-process the file: Strip comments (using a tool like jsmin or a simple script) before passing to a standard JSON parser — Crockford's own suggestion

The Decision Was Correct

Crockford's decision to exclude comments was correct for JSON as a data interchange format. It preserved interoperability, prevented format fragmentation, and maintained the simplicity that made JSON easy to implement across every programming language and platform.

The fact that developers complain about it reflects not a flaw in the decision but a mismatch between the format's design goals and the use cases developers have applied it to. JSON for configuration files is a common pattern; it is also a slight misuse of a format designed for something else. The variants — JSONC, JSON5, TOML, YAML — exist to serve these use cases properly.

Format your JSON →