Sooner or later everyone tries to put a comment in a JSON file, and the parser refuses it. JSON deliberately has no comment syntax. A family of look-alike formats exists to fill the gap, and it is worth knowing which is which, because a file named .json may not be what it seems.
Why standard JSON has no comments
Douglas Crockford, who popularised JSON, has said he removed comments from the format because people were using them to carry parsing directives, which would have undermined interoperability. Whatever the history, the result is that RFC 8259 and ECMA-404 define no comment syntax, and a strict parser must reject // and /* */.
JSONC: JSON with comments
JSONC is not a formal standard but a widely used convention: JSON that also allows // line comments and /* */ block comments, and in some tools trailing commas. Visual Studio Code uses it for its settings and several configuration files, and TypeScript's tsconfig.json accepts comments too. Tools that support it parse the file with a lenient parser. A strict JSON parser given the same file will fail.
Practical implication: a file may carry the .json extension and still contain comments. Check the documentation of the tool that reads it before assuming standard JSON.
JSON5
JSON5 extends JSON with features from modern JavaScript: comments, unquoted keys, single-quoted strings, trailing commas, hex numbers, multiline strings and a few more. It has its own specification and file extension, .json5. It is more comfortable to hand-write, but needs a JSON5-aware parser.
JSON Lines (NDJSON)
JSON Lines, also called newline-delimited JSON, is a different thing: one complete JSON value per line, usually an object, with no enclosing array and no commas between lines:
{"id": 1, "event": "login"}
{"id": 2, "event": "logout"}
Each line is valid JSON on its own, but the file as a whole is not a single valid JSON document. It suits logs and streaming data because you can append a line at a time and process the file record by record without loading it entirely. Extensions are usually .jsonl or .ndjson.
Which parser accepts what
| Feature | JSON | JSONC | JSON5 | JSON Lines |
|---|---|---|---|---|
| Comments | No | Yes | Yes | No |
| Trailing commas | No | Often | Yes | No |
| Unquoted keys | No | No | Yes | No |
| Single quotes | No | No | Yes | No |
| Multiple records per file | No | No | No | One per line |
How to add comments safely
If you must stay with standard JSON:
- Use a dedicated field, such as
"_comment": "explain here", and make sure the consuming program ignores unknown keys. - Document the file in a separate README.
- Move to a format designed for comments, like YAML or TOML, if the file is mainly for people.
Stripping comments
Some tools accept JSONC but others expect pure JSON. Before passing a commented file to a strict program, remove the comments and any trailing commas. A syntax checker helps you confirm the result: in Docento's Text & Markdown Editor, a .json file with comments will show a syntax error at the first comment, which is the right answer for standard JSON.
Practical advice
- Do not assume a
.jsonfile is strict; read the tool's documentation. - Do not hand-write JSON Lines as a single array or vice versa.
- Use strict JSON for data you send to other systems.
Takeaway
Standard JSON has no comments. JSONC and JSON5 allow them but only with parsers that expect it, and JSON Lines is a one-object-per-line format. Know which one your tool reads before you edit the file.
