Can JSON Have Comments?

The short answer: no, standard JSON does not allow comments — not //, not /* */, not #. Adding any of them causes a parse error. There are good reasons behind the rule, plus several practical workarounds.

Why JSON has no comments

Douglas Crockford, who specified JSON, removed comments on purpose. People were using them to hold parsing directives, which broke interoperability. By stripping comments out, JSON stays a pure, unambiguous data format that every parser handles identically.

What happens if you add a comment

{
  "port": 8080,  // INVALID
  "host": "localhost"
}

This throws Unexpected token / because the parser does not recognize //.

Workaround 1: A comment field

{
  "_comment": "Port must match the firewall rule",
  "port": 8080
}

A regular key acting as a note — valid JSON, ignored by your code.

Workaround 2: JSONC

JSONC is a superset that allows // and /* */ comments. VS Code uses it for settings.json and tsconfig.json. It is not standard JSON — strip comments before sending data anywhere strict.

Workaround 3: JSON5

JSON5 allows comments, trailing commas, single quotes, and unquoted keys. Great for human-edited config, but never serve it from an API.

Workaround 4: Switch to YAML

If humans edit the file regularly and comments matter, YAML supports # comments natively:

# Server configuration
port: 8080   # must match firewall
host: localhost

Which should you use?

• API / data exchange: strict JSON, use a _comment field if needed.
• Project config: JSONC or JSON5 if your tooling supports it.
• Human-edited config with notes: YAML.