How to Comment in JSON (and Why You Can't)

Sooner or later everyone tries to add a // comment to a JSON file and watches their parser choke. JSON genuinely has no comment syntax. Here's why, and what to do instead.

Why JSON has no comments

Douglas Crockford, who specified JSON, removed comments deliberately — people were using them to hold parsing directives, which broke interoperability. By removing them, JSON stayed a pure data format. The spec is final: standard parsers reject comments.

Workaround 1: JSONC

JSONC ("JSON with Comments") is a superset that allows // and block comments. VS Code uses it for its settings files. Many tools accept it, but standard parsers do not — only use it where the consuming tool explicitly supports it.

{
  // this works in JSONC, not plain JSON
  "port": 8080
}

Workaround 2: JSON5

JSON5 is a larger superset adding comments, trailing commas, and unquoted keys. It needs a JSON5 parser. Great for hand-edited config, not for data interchange. See JSON vs JSON5 vs JSONC.

Workaround 3: comment keys

A portable trick is a real key that holds your note:

{
  "_comment": "port must match the load balancer",
  "port": 8080
}

Valid JSON everywhere, though your app should ignore underscore-prefixed keys.

Workaround 4: switch formats

YAML and TOML both support # comments natively. For human-edited config, that alone is a good reason to choose them. See JSON vs YAML vs TOML.

Workaround 5: strip before parsing

Some build pipelines strip comments from JSONC into plain JSON at build time, giving you the best of both — at the cost of extra tooling.

Bottom line

You can't comment in plain JSON. Use JSONC or JSON5 where supported, a _comment key for portability, or switch to YAML/TOML. Need to clean a JSONC file into valid JSON? Paste it into the validator — it flags comments so you can spot and remove them.