Can JSON have comments? JSONC, JSON5 and workarounds
Updated
No. Standard JSON has no comments: not //, not /* */, not #. Strict parsers reject them, and Visual Studio Code (VS Code) underlines them with “Comments are not permitted in JSON.” Below: why the format has none, what parsers say when they meet one, the two formats that allow them, JSONC and JSON5, and how to annotate or strip comments without breaking anything.
Why JSON has no comments
RFC 8259 allows four whitespace characters between tokens: space, tab, line feed and carriage return. Nothing else may appear outside a string, so / is simply an unexpected character. Douglas Crockford, who specified JSON, has explained that he left comments out on purpose: people were using them to carry parsing directives, which would have broken interoperability. His advice for annotated config files was to write the comments and strip them before the file reaches a JSON parser.
Section 9 of the RFC lets a parser accept “non-JSON forms or extensions”, which is why some do. But a file with comments is no longer JSON, and the next tool in the chain is free to refuse it.
{
// port for local development
"port": 8080
}What parsers say about this comment
The same four lines, fed to strict parsers. Each one stops at the /:
| Where | Message |
|---|---|
VS Code, a .json file | Comments are not permitted in JSON. (code 521) |
| Chrome, Node.js (V8) | Expected property name or '}' in JSON at position 4 (line 2 column 3) |
Python json | Expecting property name enclosed in double quotes: line 2 column 3 (char 4) |
Go encoding/json | invalid character '/' looking for beginning of object key string |
| Jackson | Unexpected character ('/' (code 47)): maybe a (non-standard) comment? (not recognized as one since Feature 'ALLOW_COMMENTS' not enabled for parser) |
| jq | jq: parse error: Invalid numeric literal at line 2, column 5 |
Checked with Node.js 25.1, Python 3.9, Go 1.25, Jackson 2.15 and jq 1.7.1; the VS Code text comes from its JSON language service. A comment in another place gives other messages: they are all listed, with fixes, on the comment error page.
JSONC: JSON with comments
JSONC is JSON plus // and /* */ comments. It has no formal specification; in practice it means what Microsoft’s jsonc-parser accepts, the parser that VS Code’s JSON support is built on. The editor opens settings.json, launch.json, tasks.json, keybindings.json, devcontainer.json, tsconfig.json, .eslintrc.json and any .jsonc file in JSON with Comments mode. There comments are fine, and a trailing comma gets a warning, “Trailing comma” (code 519), unless the file’s schema allows it, as the tsconfig schema does. In a plain .json file both are errors.
When VS Code complains about a comment, decide what the file is:
- Data, or a file read by a strict parser, such as
package.jsonor an API payload: remove the comment. npm andJSON.parsewon’t accept it. - A config whose program accepts comments: switch the language mode to “JSON with Comments” in the status bar, or map the file in your settings with
files.associations. - Not sure: check the program’s docs. The editor mode changes only the squiggles, not what the program accepts at run time.
{
"files.associations": {
"app.config.json": "jsonc"
}
}JSON5
JSON5 goes further. On top of comments it allows trailing commas, single-quoted strings, unquoted keys, hexadecimal numbers, leading and trailing decimal points, Infinity and NaN, and strings split across lines. Every JSON document is valid JSON5, so a JSON5 parser reads plain JSON too.
import JSON5 from 'json5';
JSON5.parse(`{
// port for local development
port: 8080,
hosts: ['localhost', '127.0.0.1',],
}`);
// { port: 8080, hosts: [ 'localhost', '127.0.0.1' ] }To turn JSON5 into JSON, parse it and stringify the result: JSON.stringify(JSON5.parse(text), null, 2). Two caveats: the comments are gone after that, and the json5 package reads numbers as doubles, so 12345678901234567890 becomes 12345678901234567000, the same big number problem as JSON.parse. Python has a json5 package built on the same idea, and Jackson reads comments once you enable JsonReadFeature.ALLOW_JAVA_COMMENTS.
How to annotate plain JSON
- A comment field:
"_comment": "…"or"//": "…". Every parser accepts it, but it is data: every consumer sees it, a schema withadditionalProperties: falserejects it, and a second"//"in the same object is a duplicate key, so most parsers keep only the last one. - The schema: a
descriptionfor each field in the file’s JSON Schema, which editors show on hover, or the$commentkeyword for notes inside the schema itself. - A commented source: keep
config.jsoncin the repository and generateconfig.jsonfrom it in the build. - A format made for people: if humans edit the file and comments matter, YAML has them built in. See JSON vs YAML and JSON to YAML.
{
"_comment": "port for local development",
"port": 8080
}Strip comments before parsing
When the source has to keep its comments and the reader is strict, remove them in a build or load step. Use a tokenizer such as strip-json-comments or jsonc-parser, not a regular expression: "https://example.com" has // inside a string, and a naive pattern cuts it in half.
import stripJsonComments from 'strip-json-comments';
import { parse } from 'jsonc-parser';
const text = '{\n // port for local development\n "url": "https://example.com", /* host */\n "port": 8080\n}';
JSON.parse(stripJsonComments(text)); // { url: 'https://example.com', port: 8080 }
parse(text); // the same: jsonc-parser skips commentsIn Go, the hujson package from Tailscale does the job: hujson.Standardize turns JSON with comments and trailing commas into plain JSON. In Python, json5.loads reads such files directly.
The Validator here is strict: a comment is an error with its own code, line and column, and nothing is stripped behind your back. A trailing comma gets the same treatment.
JSON comments FAQ
Does JSON support comments?
No. RFC 8259 has no comment syntax, and JSON.parse, Python’s json, Go’s encoding/json and Jackson with default settings reject // and /* */. JSONC and JSON5 are separate formats that allow them.
How do I comment out a line in JSON?
You can’t. Delete the line, keep the value under a key nobody reads (rename "port" to "_port"), or keep the file as JSONC and strip the comments before parsing. Watch the commas: removing the last member leaves a trailing comma.
What is the difference between JSONC and JSON5?
JSONC is JSON plus comments, with trailing commas tolerated by some tools. JSON5 also allows unquoted keys, single quotes, hex numbers, Infinity and NaN. Each needs its own parser.
Why does VS Code accept comments in settings.json but not in my file?
It opens settings.json as “JSON with Comments” and other .json files as strict JSON. Change the mode or use files.associations only if the program that reads the file accepts comments too.