Does JSON support comments? No. Standard JSON, as defined by RFC 8259 and ECMA-404, has no comment syntax at all. A // line comment or a /* */ block comment makes the document invalid, and a strict parser such as JSON.parse throws a SyntaxError.
Plenty of files that end in .json still contain comments, though. This guide explains why JSON left them out, which tools accept them anyway, and the practical ways to document a JSON file without breaking the code that reads it.
Can you put comments in JSON?
No. The JSON grammar only allows objects, arrays, strings, numbers, true, false, null and whitespace between tokens. There is no token for a comment, so a parser treats // or /* as an unexpected character.
{
// the API base URL
"baseUrl": "https://api.example.com"
}Parsers report it the same way they report any other stray character:
- Chrome, Edge and Node.js:
Expected property name or '}' in JSON at position 4 (line 2 column 3). - Python:
Expecting property name enclosed in double quotes: line 2 column 3 (char 4). - A comment after a value, as in
"a": 1 // note, givesExpected ',' or '}' after property valuein V8.
If you see one of these errors in a file that looks fine, search it for // and /*. See How to fix JSON syntax errors for the full list of messages.
Why JSON has no comments
Douglas Crockford, who specified JSON, has said he removed comments on purpose. People had started using them to hold parsing directives, instructions that only some parsers understood. That would have split JSON into incompatible dialects, which defeats the point of a data interchange format.
The result is a format that every language parses the same way. The cost is that config files written in JSON cannot explain themselves. That gap is why JSONC and JSON5 exist.
Four ways to keep notes in JSON
1. Add a comment field
Store the note as data. A key such as "_comment" or "//" is valid JSON, and programs that do not know the key ignore it. The downside is that the note travels with the data and can clash with a strict schema that sets additionalProperties: false.
{
"_comment": "Timeout is in seconds",
"timeout": 30
}2. Use JSONC (JSON with comments)
JSONC is JSON plus // and /* */ comments. VS Code uses it for settings.json, keybindings.json and devcontainer.json, and TypeScript reads tsconfig.json the same way, which also tolerates trailing commas. These files only work with parsers that expect JSONC.
3. Use JSON5
JSON5 goes further. It allows comments, trailing commas, single-quoted strings, unquoted keys, hexadecimal numbers and Infinity. Babel's .babelrc files are read as JSON5. You need a JSON5 parser library to read it.
4. Switch the file to YAML
If people edit the file by hand, YAML may fit better. It has # comments, and every JSON document is also valid YAML 1.2, so the move can be gradual. See YAML vs JSON.
Which .json files accept comments
| File | Comments allowed? | Why |
|---|---|---|
| package.json | No | npm parses it as strict JSON. |
| tsconfig.json | Yes | TypeScript reads it as JSONC, with trailing commas. |
| VS Code settings.json | Yes | VS Code opens it in JSON with Comments mode. |
| devcontainer.json | Yes | The Dev Containers spec uses JSONC. |
| .babelrc | Yes | Babel parses it as JSON5. |
| API payloads | No | Clients parse them with JSON.parse or an equivalent. |
When in doubt, assume strict JSON. A file that only works with a forgiving parser breaks as soon as another tool reads it.
How to comment out multiple lines in JSON
Strict JSON has no way to comment out a block. You have three options:
- In a JSONC file, wrap the lines in
/* */, or select them in VS Code and press Ctrl+/ (Cmd+/ on macOS) to add//to each line. - In strict JSON, move the settings under a key the program ignores, such as
"_disabled": { ... }. - Keep the original in version control and delete the lines. Git keeps the old version for you.
Strip comments to get valid JSON
When a tool only accepts strict JSON, remove the comments first. The JSON5 to JSON converter strips // and /* */ comments and trailing commas, and also converts single quotes and other JSON5 syntax, so the result parses everywhere.
Then run the result through the JSON validator to confirm that it parses.