JSON Toolkit

Can JSON have comments

Bottom line: RFC 8259 has no comment syntax, so // and block comments make JSON.parse throw. Use JSON5 or JSONC, a _comment field, a Schema description, or YAML instead.

Beginner~3 min readPublished 2026-10-30Updated 2026-10-30
Why JSON has no comments and what to use instead

Bottom line: never put comments in standard JSON; use JSONC or JSON5 for local config that only humans edit, move explanations into a JSON Schema description when the file crosses systems, and switch to YAML or TOML once annotation volume grows.

No.

Any standards-compliant parser rejects this:

{
  "port": 8080 // local development only
}

Chrome reports SyntaxError: Unexpected token }. The parser hit /, which cannot start any JSON value, and stopped.

Why the spec leaves comments out on purpose

RFC 8259 defines six values: object, array, number, string, true/false, null. There is no comment production.

Comments were proposed early and rejected for a concrete reason: once comments are legal, someone uses them to carry directives — conditional includes, template variables — and every parser grows its own dialect. Interoperability breaks at the first hop. JSON is deliberately data-only, with nothing executable inside it.

Four ways to keep your notes

1. Use a superset. JSON5 and JSONC accept both comment styles. VS Code's settings.json and tsconfig.json are JSONC. The cost is real: JSON.parse still rejects them, and APIs, log pipelines and message queues usually accept only standard JSON. Your comment gets silently dropped or throws somewhere downstream.

2. Put the note in the data.

{
  "_comment": "port assigned by ops, do not change",
  "port": 8080
}

Works everywhere, but pollutes the model: every consumer has to know which keys to ignore, and your type definition grows a field that is not really data.

3. Use a Schema description. description is meant for humans and tools. Validators surface it, editors show it on hover, and it never enters the payload. This is the only option that survives long-term maintenance without breaking compatibility.

4. Change the file format. If the file exists to be edited by hand, YAML or TOML support comments natively. Fighting JSON here is wasted effort.

Choosing

Situation Answer
Sent to another system, through an API or a queue No comments; document in Schema or external docs
Config read only by humans and editors JSONC, with a .jsonc extension
Needs universal tooling and inline explanation Standard JSON plus Schema description
Long config with lots of annotation Switch to YAML

FAQ

Why does a _comment field pollute the model?

Because it becomes part of the data. Every consumer has to know which keys to ignore, and the type definition gains a field that is not really business data.

Should the explanation live in a JSON Schema description?

Yes. description stays out of the payload, while validators surface it and editors show it on hover, so it is the only option that survives long-term maintenance without breaking compatibility.

Can JSONC or JSON5 be parsed by JSON.parse?

No. JSON.parse still rejects comments, and APIs, log pipelines and message queues usually accept only standard JSON, so the comment is dropped or throws somewhere downstream.

Tools

Further reading