Why comments are not permitted in JSON

Comments are not permitted in JSON because the JSON specification does not define any comment syntax. Actual // or /* */ comments outside quoted strings are not part of the JSON grammar, so a strict JSON parser rejects them and a conforming generator must not emit them (RFC 8259).

What the JSON specification actually says

JSON’s grammar lists structural characters, strings, numbers, and the literals true, false, and null. There are no comment tokens in that grammar, so actual comments outside quoted strings are invalid JSON (RFC 8259). The standard also sets clear roles for tools:

• Parsers may accept non-JSON extensions at their discretion, but they must accept all valid JSON texts.
• Generators must output text that strictly conforms to the JSON grammar.

In practice, this means a file that includes // or /* */ may still load in a lenient environment, but it is not valid JSON and can break in other tools or APIs expecting strict conformance (RFC 8259).

Why comments were left out

Interoperability and simplicity were the priorities. Allowing comments would add ambiguity and inconsistent behavior across implementations. Douglas Crockford, who standardized JSON, explicitly argued that comments were removed to prevent misuse as parsing directives, which would have harmed interoperability (JSON for Modern C++: Comments).

That design choice keeps the format small and predictable across languages and platforms.

What this means in practice

If you add // or /* */ to a JSON file, any strict validator or API that enforces the spec can reject the payload with a parse error. This is why production systems, CI checks, and public endpoints commonly fail on commented JSON (RFC 8259).

If you work with structured data on the web, it helps to build the habit of validating before you ship. For related guidance, see What are schema errors? A practical explainer and How to validate schema markup: a practical checklist.

Safe ways to keep annotations without breaking JSON

Use JSONC in development, then strip comments

JSONC is a non-standard extension of JSON that allows JavaScript-style single-line and block comments wherever insignificant whitespace is allowed. It is widely used for editor configuration (for example, VS Code’s settings and similar files). Comments are ignored by the parser and must not affect the data; trailing commas may be supported depending on parser settings (JSONC specification).

Because JSONC is not the JSON standard, only use it where all consumers support it, or add a preprocessing step to remove comments before handing the data to any strict JSON consumer (JSONC specification).

A URL such as {"url":"https://example.com"} is valid JSON: the two slashes are inside a quoted string, not a comment. Preserve those characters when converting a development file.

Rely on parsers that can ignore comments (dev-only)

Some libraries offer an option to treat // and /* */ as whitespace during parsing. For example, the JSON for Modern C++ library can ignore comments when configured, but keeps comment support off by default to remain spec-compliant (JSON for Modern C++: Comments).

Troubleshooting: when comments slip through

Symptoms usually include parser errors, failing linters, or rejected API requests at the first // or /* */ encountered. Remove the actual comments manually, or parse with a JSONC-aware parser and serialize the resulting data as strict JSON. Do not use a global text replacement or a simple regular expression: it can damage quoted strings, including URLs. To prevent recurrences, ensure your generator outputs only valid JSON and keep the strict-parse check enabled in CI (RFC 8259).

FAQ

Can I use comments if my tool seems to accept them?

Only if you control every consumer or you preprocess the file. Parsers may accept extensions, but generators and interoperable payloads must conform to JSON. Treat comments as a development-time convenience and deliver strict JSON to others (RFC 8259).

Is JSONC the same as JSON5?

No. JSONC adds comments (and, optionally, trailing commas) without changing core JSON syntax. JSON5 goes further with features like unquoted keys and single-quoted strings. Some JSON libraries explicitly distinguish these and do not support JSON5 syntax (JSON for Modern C++: Comments).