Can JSON have comments?
No. The JSON specification (RFC 8259 and ECMA-404) has no comment syntax at all: no // line comments, no /* */ block comments and no #. A file that contains any of them is not valid JSON, and JSON.parse, Python's json, Go's encoding/json, jq and every other standards-compliant parser reject it.
This was deliberate. Douglas Crockford, who specified JSON, has explained that he removed comments because people were using them to hold parsing directives, which would have broken interoperability between parsers. His suggested workaround is to keep comments in your source file and run it through a minifier or comment stripper before handing it to a JSON parser. That is still the practical answer today.
JSON comments syntax: what tools accept
Several JSON-like formats and tools do accept comments. They are not JSON, but the syntax is what people mean by "JSON comments":
| Comment syntax | Example | Accepted by |
|---|---|---|
Line comment // | "port": 8080, // dev only | JSONC (VS Code settings, tsconfig.json), JSON5, Jackson with ALLOW_JAVA_COMMENTS |
Block comment /* */ | /* Feature flags */ | JSONC, JSON5, Jackson with ALLOW_JAVA_COMMENTS |
Hash comment # | # generated file | Not JSONC or JSON5. Jackson with ALLOW_YAML_COMMENTS; YAML and TOML use # |
| Comment as data | "_comment": "why this exists" | Every JSON parser (it is an ordinary key) |
JSONC: JSON with Comments
JSONC is JSON plus // and /* */ comments. VS Code uses it for settings.json, keybindings.json, launch.json and tasks.json, and also for tsconfig.json, jsconfig.json and devcontainer.json. TypeScript's own config reader accepts comments (and trailing commas) in tsconfig.json, which is why tsc --init writes a file full of /* */ comments. In VS Code, files are shown as "JSON with Comments" in the status bar; to treat your own files the same way, add "files.associations": { "*.myconfig.json": "jsonc" } to your settings. JSONC only works where the program that reads the file uses a JSONC parser.
JSON5
JSON5 accepts // and /* */ comments, trailing commas, single-quoted strings, unquoted keys and hex numbers. It is used for hand-edited configs, such as Babel's .babelrc.json5. Check a file with the JSON5 validator.
JSON line comments and the errors they cause
A // comment in a JSON file produces a different message depending on where it is. For a comment on its own line inside an object:
{
// comment
"a": 1
}
| Language / parser | Message |
|---|---|
| JavaScript, current V8 (Chrome, Node.js 20+) | Expected property name or '}' in JSON at position 4 |
| JavaScript, older V8 (Node 18 and earlier) | Unexpected token / in JSON at position 4 |
| Firefox | JSON.parse: expected property name or '}' at line 2 column 3 of the JSON data |
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 |
| Java (Jackson) | Unexpected character ('/' (code 47)): maybe a (non-standard) comment? (not recognized as one since Feature 'ALLOW_COMMENTS' not enabled for parser) |
| jq 1.7 | jq: parse error: Invalid numeric literal at line 2, column 5 |
PHP json_last_error_msg() | Syntax error |
A comment after a value ("a": 1, // note) gives Expected double-quoted property name or Expected ',' or '}' after property value in V8, and Python's Expecting ',' delimiter if there is no comma. A comment at the very start of the file gives Unexpected token '/' in V8 and Expecting value: line 1 column 1 (char 0) in Python. Whatever the wording, if the reported column points at / or #, it is a comment. See also Unexpected token in JSON.
package.json comments
package.json is strict JSON: npm, Yarn, pnpm and Node.js itself parse it with a standard JSON parser, so a // comment breaks npm install. The usual workaround is a key named "//", which npm treats as an ordinary unknown field and leaves alone:
{
"name": "my-app",
"//": "build runs in CI, keep the script names stable",
"scripts": {
"//": "use npm run dev for local work",
"dev": "vite",
"build": "vite build"
}
}
Keys must be unique within one object, so use one "//" per object, or an array of strings for longer notes: "//": ["line one", "line two"]. The fourth example above is this pattern; Find the error reports it as valid JSON.
Comment workarounds that keep the file valid JSON
- A
"_comment"or"//"key. Valid everywhere. The downside is that it is data: your code receives it, a schema withadditionalProperties: falserejects it, and tools that sort or rewrite the file keep it as a normal field. - A
"description"field in the schema. If the file has a JSON Schema, document the fields there instead, and editors such as VS Code show the description on hover. See the JSON Schema validator. - A README next to the file. Unexciting, but it works with every tool.
- A different format. If people need to comment a config heavily, YAML or TOML support
#comments natively.
How to strip comments before parsing
If you want comments in the source file, remove them before parsing with a tool that understands strings. A naive regex such as /\/\/.*$/gm breaks any string that contains //, for example "https://example.com" becomes "https:.
// Node.js: npm install strip-json-comments
import stripJsonComments from 'strip-json-comments';
const config = JSON.parse(stripJsonComments(text));
// Node.js: npm install json5 (also allows trailing commas)
const config = JSON5.parse(text);
# Python: pip install json5
import json5
config = json5.loads(text)
// Go: github.com/tailscale/hujson
b, err := hujson.Standardize(src) // removes comments and trailing commas
err = json.Unmarshal(b, &config)
// Java (Jackson)
JsonMapper mapper = JsonMapper.builder()
.enable(JsonReadFeature.ALLOW_JAVA_COMMENTS)
.build();
strip-json-comments replaces comments with whitespace by default, so error positions in the result still match the original file. Note that none of these handle # comments except Jackson with JsonReadFeature.ALLOW_YAML_COMMENTS.
How the NeatJSON repair removes //, /* */ and #
Repair JSON above does not use regular expressions. It reads the text with a parser, so it always knows whether it is inside a string, and only treats //, /* and # as comments when they appear between values:
// ...and# ...are removed up to the end of the line./* ... */is removed up to the closing*/, across any number of lines. An unclosed/*removes the rest of the file, so check the output.- Inside strings nothing is touched:
"https://example.com"and"#ff0000"are kept exactly. - Trailing commas, which are common in JSONC files, are removed in the same pass (see JSON trailing comma), and large numbers are kept digit for digit.
The result is strict JSON that any parser accepts, plus a list of what was changed and where. Keep the commented file as your source and use the stripped version as the build output, so you do not lose the comments.
Frequently asked questions
Can JSON have comments?
No. Standard JSON, defined by RFC 8259 and ECMA-404, has no comment syntax, so // , /* */ and # comments all cause a syntax error in JSON.parse and other strict parsers. Formats such as JSONC and JSON5, and tools such as VS Code and TypeScript, accept comments in their own config files.
What is the JSON comment syntax?
There is none in standard JSON. JSONC and JSON5 accept JavaScript-style // line comments and /* block */ comments. If the file must stay valid JSON, add a key such as "_comment" or "//" with the note as its string value.
How do I add comments to package.json?
package.json must be strict JSON, so real comments break npm install. Add a key named "//" with your note as a string, for example "//": "build runs in CI". npm leaves unknown fields like this alone. Use at most one "//" key per object, or an array of strings for several lines.
Why does tsconfig.json allow comments?
TypeScript reads tsconfig.json with its own tolerant parser, which accepts comments and trailing commas, and VS Code treats it as JSON with Comments. This only works because those tools use that parser. Other tools that read the file with JSON.parse will fail on the comments.
What is the difference between JSONC and JSON5?
JSONC is JSON plus // and /* */ comments, and is used by VS Code and TypeScript config files. JSON5 is a larger extension that also allows trailing commas, single-quoted strings, unquoted keys, hexadecimal numbers and more. Neither is accepted by JSON.parse.
How do I remove comments from JSON?
Paste the JSON on this page and click Repair JSON. It removes //, /* */ and # comments with a parser, so // inside strings such as URLs is kept, and also removes trailing commas. In code, use strip-json-comments or json5 in Node.js, json5 in Python, or hujson in Go.
Is my JSON uploaded?
No. Finding and removing comments happens in your browser, and nothing is sent to a server.