Can JSON have comments?

Why JSON can’t have comments

The RFC 8259 grammar allows objects, arrays, strings, numbers, true, false, null and whitespace. Nothing else, so a parser that meets // stops.

Douglas Crockford, who specified JSON, explained in 2012 that he removed comments from JSON because people used them to hold parsing directives, “a practice which would have destroyed interoperability.”

What parsers say

Most errors never mention comments; they report the first character that breaks the grammar. Given this file:

{
  // where the app sends webhooks
  "webhookUrl": "https://hooks.example.com/orders",
  /* seconds before a retry */
  "retryDelay": 30
}

Only the editors name the problem. For the VS Code message, see Comments are not permitted in JSON. JetBrains IDEs give a related warning for other non-standard syntax: JSON standard does not allow such tokens.

Option 1: JSONC

JSONC (“JSON with Comments”) is JSON plus // and /* */ comments. It works where the reader supports it:

• VS Code config files: settings.json, keybindings.json, launch.json, tasks.json, extensions.json, mcp.json, devcontainer.json and .code-workspace files.
• TypeScript: tsconfig.json. tsc --init writes one full of commented-out options.
• PowerShell 6 and later: ConvertFrom-Json reads comments and drops them. Windows PowerShell 5.1 fails, as the table shows.

Trailing commas vary. The draft JSONC specification makes them optional, and VS Code accepts them with a warning.

To allow comments in your own .json file in VS Code, choose JSON with Comments from the language indicator in the status bar, or map the file name in your settings:

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

This changes the editor only. The program that loads the file still needs a parser that accepts comments (Option 4). More editor setup is in how to format JSON in VS Code.

Option 2: JSON5

JSON5 adds comments, trailing commas, single quotes, unquoted keys, hex numbers, Infinity and NaN:

{
  // retries back off exponentially
  maxRetries: 5,
  baseDelay: 0.25,
  regions: ['eu-west', 'us-east',],
  hexMask: 0xFF,
}

Use the .json5 extension. json5.org lists Chromium, Next.js and Babel as users. Pick JSON5 for files people edit by hand a lot, and JSONC when comments are all you need.

Option 3: a “_comment” key

When the file must stay strict JSON (an API payload, package.json, a file another team parses), put the note in the data:

{
  "_comment": "retryDelay is in seconds, not milliseconds",
  "webhookUrl": "https://hooks.example.com/orders",
  "retryDelay": 30
}

Every parser accepts it, and it survives formatting and round trips. The costs:

• It is data, so it ends up in your objects, database rows and API responses.
• A JSON Schema with "additionalProperties": false rejects it.
• Each object holds one. JSON.parse and Python’s json keep only the last duplicate key, so name extra notes "_comment_retry" and so on.

Option 4: strip comments before parsing

Don’t use a regular expression: // also appears inside strings. Stripping //.* from the file above cuts the URL in half:

SyntaxError: Bad control character in string literal in JSON at position 28 (line 3 column 24)

In Node.js, strip-json-comments leaves strings alone and can remove trailing commas too:

// npm install strip-json-comments
import { readFileSync } from 'node:fs';
import stripJsonComments from 'strip-json-comments';

const text = readFileSync('config.jsonc', 'utf8');
const config = JSON.parse(stripJsonComments(text, { trailingCommas: true }));

Microsoft’s jsonc-parser, which powers VS Code’s JSON support, parses JSONC directly: parse(text, errors, { allowTrailingComma: true }).

In Python, json5 (pip install json5) reads both JSONC and JSON5:

import json5

with open("config.jsonc", encoding="utf-8") as f:
    config = json5.load(f)

For a one-off file, JSON Repair removes comments and trailing commas and keeps the URL intact:

{
  "webhookUrl": "https://hooks.example.com/orders",
  "retryDelay": 30
}

The JSON validator leaves the text alone and points at the first comment and its line.

Comments rarely survive a rewrite

A program that parses the file and writes it back drops the comments: ConvertFrom-Json, json5.load followed by json.dump, and any formatter that re-serializes. VS Code keeps them because its formatter only moves whitespace. To change a value in a commented file from code, use jsonc-parser’s modify(text, ['retryDelay'], 60, options): it edits the text and leaves both comments in place. Other editors and languages are covered in the JSON guides.