Can JSON Have Comments? The Answer and 4 Workarounds
Standard JSON does not support comments — write one and parsing fails. That was a deliberate design decision. This guide explains why, and gives four practical workarounds when your config really needs notes.
What happens if you write one
The snippet above fails in virtually every standard parser. Douglas Crockford removed comments deliberately: partly to keep the format minimal, and partly because he saw people stuffing parsing directives into comments, forking the format into dialects and breaking interoperability.
{
// this comment breaks JSON.parse
"name": "app"
}Workaround 1: switch to a commented dialect
Much of the toolchain already understands JSONC (JSON with Comments) or JSON5: VS Code settings and tsconfig are JSONC; JSON5 additionally allows trailing commas, single quotes and bare keys. If you control the parsing side of your config, switching dialects is the most comfortable fix.
Workaround 2: dialect in development, strip before shipping
Write comments freely in JSON5 / JSONC during development and strip to standard JSON before delivery — that is exactly what the on-site "JSON5 to JSON" tool does, counting the comments it removes instead of silently swallowing content.
{
// JSON5 / JSONC: comments allowed
"name": "app", // trailing comma is fine too in JSON5
}Workaround 3: a field as a comment
Put a conventional field in the data itself (commonly _comment or description). The drawbacks are real: it is genuine data that gets transmitted and stored, it can collide with business fields, and every consumer must agree to ignore it. Fine for the occasional note, nothing more.
{
"_comment": "workaround: a plain field used as a note",
"name": "app"
}Workaround 4: change the format
If the file is truly a human-written config, YAML and TOML support comments natively and may be a better fit than patching JSON — see the on-site JSON to YAML / TOML converters and the comparison guides.