Developer tools · JSON formatter & validator
Why JSON has no comments: the design decision and its workarounds
· Background
json standards validation
Comments were removed from JSON deliberately. This post explains the reasoning, why every attempt to add them back created a new format, and what your options are when a config file really needs a note.
The comment that broke the build
The comment that broke the build — a helpful note added to a JSON config and a parser that stopped at the first slash. The author may have copied a pattern from JavaScript or a JSONC-aware editor, while the deployment tool uses strict JSON. Syntax highlighting can make the note look legitimate even though the consumer rejects the first comment marker.
Comments are rejected because slash is not a JSON token where the scanner expects a value or member. ToolAcre does not silently strip JSONC or JSON5 syntax. A conventional comment-shaped property is ordinary data and may violate an application schema even though strict JSON syntax accepts it. Unsupported historical claims about JSON’s design are omitted or corrected rather than presented as established fact without primary evidence or a traceable standards source available for verification.
Crockford's reason for removing comments
Crockford's reason for removing comments — a later explanation says comments had been used to carry parsing directives, undermining interoperability between implementations. The relevant design consequence is that standard JSON has no comment token. Claims about private motivations, exact chronology or universal industry response require historical sources not supplied by this repository.
Accordingly, unsupported historical claims are omitted or corrected here. The observable standard and parser behavior are sufficient: strict JSON exchanges data through six value types and two containers, without an annotation channel. That constraint prevents one recipient from assigning operational meaning to text another recipient ignores, but it also makes JSON less comfortable for hand-maintained configuration.
What a validator reports on a comment
What a validator reports on a comment — `//` and `/* */` are not in the grammar, so the error lands on the first slash with a line and column. The scanner is not objecting to the words in the note. It cannot begin any valid JSON value, member name or separator with `/` at that position.
For `{"port":8080, // local only "secure":false}`, the comma is valid and the next legal token should be a quoted property name or the closing brace. The slash violates that expectation. Removing only the note leaves a valid separator and next member; deleting nearby punctuation can create a second error. Revalidate the exact strict output after every edit.
The formats that added comments back
The formats that added comments back — JSONC permits comments around otherwise familiar JSON syntax, while JSON5 adds conveniences such as unquoted identifier keys and trailing commas. Hjson emphasizes human editing with additional relaxed syntax. YAML has its own grammar, including comments, and is not merely JSON with annotations added.
Acceptance is consumer-specific: editor settings and TypeScript configuration may use comment-tolerant parsers, whereas a package manifest or API body can require strict JSON. Kubernetes commonly consumes YAML or JSON according to its tooling. Name the actual format in documentation and file handling; stripping extensions or calling every object notation “JSON” hides compatibility boundaries.
Workarounds inside strict JSON
Workarounds inside strict JSON — a conventional `_comment` or `//` key stores explanation as an ordinary string member. It survives strict parsing because both the key and value use standard tokens. Multiple notes need unique keys or an array, since duplicate member names are unreliable and may be collapsed by parsers.
The workaround changes the data model. A schema with `additionalProperties: false` can reject the annotation, and an application may persist or transmit it as real configuration. External documentation, a neighboring README or a schema `description` often provides a safer explanation channel. Use comment-shaped members only when every consumer explicitly permits and ignores them.
Worked example: an annotated settings file
Worked example: an annotated settings file — begin with a JSONC source containing `// seconds before retry` above `"timeout":30`. If the destination accepts only JSON, use a parser that understands JSONC to produce data and then serialize that data as strict JSON. The deployed artifact becomes `{"timeout":30}` while the maintained source retains its explanation.
Do not remove comments with a regular expression. Slash sequences can appear legitimately inside strings such as URLs, and block-comment patterns can span lines in ways textual replacement mishandles. Keep source and generated artifact distinct, validate the strict result and arrange regeneration in the build. This preserves author notes without pretending the receiving parser supports them.
What this does not cover
What this does not cover — how to configure individual parsers to accept comments, which is tool-specific and changes often. A permissive option in one library does not alter JSON grammar or guarantee that another service will accept the same text. Check the parser, version and destination rather than relying on an editor’s display.
This article also avoids unsupported claims about precisely when comments were removed, who adopted each workaround first or whether one design decision alone caused JSON’s popularity. Such historical assertions need independent primary sources. Here they are omitted or corrected; the supported conclusion is limited to current strict syntax, repository behavior and the operational differences among named formats.
Takeaway: JSON is a data interchange format, not a config language
Takeaway: JSON is a data interchange format, not a comment-rich configuration language — and the validator shows exactly where a note breaks strict grammar. When humans need annotations, choose a format the consuming tool officially supports or maintain an annotated source that generates a separate strict artifact. Do not assume comments will be harmlessly ignored.
If strict JSON is mandatory, move explanation to documentation or use schema-approved metadata, then validate the final document. ToolAcre intentionally reports the first slash instead of silently deleting material, because silent conversion could change strings or conceal a format mismatch. Historical context should remain equally disciplined: unsupported claims are omitted or corrected, while observable syntax and parser behavior carry the conclusion.