Can you use comments in JSON? No, and here is what to do

No. Standard JSON has no comment syntax at all. Not //, not /* */, not #. Any of them makes the document invalid, and a strict parser rejects it, usually with an error like Unexpected token '/'. This is not an oversight: comments were in early JSON and were deliberately removed. What you do about it depends on where the JSON lives, and there are four honest options.

Why doesn't JSON support comments?

Douglas Crockford, who specified JSON, removed comments early and has explained the decision publicly: people were using comments to hold parsing directives, instructions to specific parsers embedded in comments, which would have destroyed the format's interoperability. A secondary benefit was simplicity: no comment syntax means every JSON parser in every language agrees on exactly what a document means, with no grammar corners to disagree over.

The cost of that purity lands on configuration files. JSON was designed as a data interchange format, machines talking to machines, where comments have no role. It then got adopted everywhere as a config format, package.json, tsconfig.json, editor settings, where humans desperately want to write "do not touch this, it breaks the build" next to a value. The mismatch between what JSON is for and what it gets used for is the entire story of this problem. If your file fails to parse for a subtler reason than a comment, our JSON error guide walks the usual suspects, and the JSON Formatter points at the exact line and column.

What happens if you try?

{
  // this breaks
  "name": "my-app"
}

JSON.parse throws SyntaxError: Unexpected token '/'. Python's json.loads raises Expecting property name enclosed in double quotes. Some permissive parsers accept it anyway, which is worse than failing: a file that works in one tool and explodes in another is a trap for whoever touches it next.

The four real options

1. JSONC or JSON5, if your tool supports it. Several ecosystems standardized on JSON supersets that allow comments:

• JSONC (JSON with Comments) allows // and /* */. VS Code uses it for settings.json, and TypeScript's tsconfig.json accepts comments and trailing commas.
• JSON5 goes further: comments, trailing commas, unquoted keys, single quotes.

The critical caveat: these are only valid where the consuming tool explicitly supports them. Comments in tsconfig.json are fine because TypeScript's parser reads them; comments in package.json break npm, because npm reads strict JSON. The file extension will not warn you. Know your parser.

2. A dummy key, for strict JSON you control.

{
  "_comment": "Ports below 1024 require root; keep this at 8080",
  "port": 8080
}

Ugly but universal: every parser accepts it, and the note travels with the data. Conventions vary, _comment, // as a key, $comment (which JSON Schema formalizes). The drawbacks are real: the key is data, so it survives into whatever consumes the file, and nothing stops it drifting out of date. Some programs also reject unknown keys, so this only works where the schema tolerates extras.

3. Comments outside the file. Documentation, a README next to the config, or version control history. For files parsed by tools you do not control, this is often the only clean answer: explain the why in the commit message that changed the value.

4. A format designed for configuration. If you control the choice, the honest fix is that JSON was never the right config format. YAML and TOML both support real comments with #, and both exist substantially because of this gap. The tradeoffs run in both directions, YAML has its own foot guns, and the comparison is mapped in JSON vs TOML and YAML to JSON, with the YAML converter handy for moving between them.

Which should you pick?

One last trap: if you strip comments from a JSONC file with a quick regex before parsing, remember // can legally appear inside string values ("url": "https://example.com"). Use a real JSONC parser or a battle tested strip library, not replace(/\/\/.*/g, ''). The JSON Formatter validates the strict result in your browser, with nothing uploaded, and tells you the precise character where a stray comment or trailing comma broke the parse.