# Can JSON have comments? JSONC, JSON5 and workarounds

> Learn whether JSON can have comments, why VS Code says “Comments are not permitted in JSON”, and when to use JSONC, JSON5 or a workaround.

- URL: https://jsonstatham.dev/guides/json-comments/
- Language: English (en)
- Russian version: https://jsonstatham.dev/ru/guides/json-comments.md
- Updated: 2026-11-08

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](https://www.rfc-editor.org/rfc/rfc8259#section-2) 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](https://www.rfc-editor.org/rfc/rfc8259#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.

```json
{
  // 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](https://jsonstatham.dev/errors/comments/).

## JSONC: JSON with comments

JSONC is JSON plus `//` and `/* */` comments. It has no formal specification; in practice it means what Microsoft’s [jsonc-parser](https://github.com/microsoft/node-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](https://code.visualstudio.com/docs/languages/json#_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.json` or an API payload: remove the comment. npm and `JSON.parse` won’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.

```json
{
  "files.associations": {
    "app.config.json": "jsonc"
  }
}
```

## JSON5

[JSON5](https://json5.org/) 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.

```js
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](https://jsonstatham.dev/guides/json-big-numbers/) 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 with `additionalProperties: false` rejects it, and a second `"//"` in the same object is a duplicate key, so most parsers keep only the last one.
- **The schema:** a `description` for each field in the file’s JSON Schema, which editors show on hover, or the `$comment` keyword for notes inside the schema itself.
- **A commented source:** keep `config.jsonc` in the repository and generate `config.json` from 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](https://jsonstatham.dev/guides/json-vs-yaml/) and [JSON to YAML](https://jsonstatham.dev/json-to-yaml/).

```json
{
  "_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](https://github.com/sindresorhus/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.

```js
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 comments
```

In Go, the [hujson](https://github.com/tailscale/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](https://jsonstatham.dev/validator/?sample=comment) 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](https://jsonstatham.dev/errors/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](https://jsonstatham.dev/errors/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.
