VS Code JSON vs JSONC: Why settings.json Allows Comments and Python Fails

The short version​

VS Code has two JSON personalities:

• JSON, the default for ordinary .json files, follows the JSON specification.
• JSON with Comments (jsonc) is used for VS Code's own configuration files.

VS Code's documentation says the JSON with Comments mode is used for configuration files such as settings.json, tasks.json, or launch.json. In that mode you can use single-line (//) and block (/ /) comments, as in JavaScript.

Microsoft's release notes for VS Code 1.19 (November 2017) introduced the mode. They describe it as a way to tell apart JSON-like files that allow comments from files that follow the standard. In the same notes, .json files default to standard JSON mode, where comments are reported as errors. So "for years" is accurate: the distinction is almost nine years old.

Why standard JSON says no​

RFC 8259 defines JSON's grammar. It has no comment syntax, and it separates items with commas rather than allowing one after the last item. MakeUseOf's author notes that Douglas Crockford removed comments because people were using them for parsing directives, which threatened interoperability. An editor that accepts comments is therefore accepting something other than standard JSON.

That is the practical risk. VS Code's JSONC mode is a contained dialect, and it only works for tools that understand that dialect.

Trailing commas are a grey area​

Comments are a clean yes. Trailing commas are more nuanced.

• VS Code's documentation says the mode accepts trailing commas but discourages them, and the editor displays a warning.
• The author of the MakeUseOf piece reports that a generic .jsonc file produced trailing-comma warnings, while settings.json and tsconfig.json showed none.
• The draft JSONC specification explains why. Its appendix says VS Code's mode used to allow trailing commas without warnings, and later changed. The warning is skipped for VS Code's official configuration files because the schemas for those files explicitly allow trailing commas.

So a file that looks fine in settings.json may show warnings once you copy it into a generic JSONC file. The Problems panel is the reliable check.

Check the mode before you share a file​

The status bar at the bottom right shows the active language mode. Selecting the mode indicator lets you change the mode and configure how file extensions are associated with modes.

To get comments in a file that VS Code treats as strict JSON:

1. Open the file and click the language indicator (it reads JSON).
2. Choose the option to change the language mode and pick JSON with Comments.
3. For a permanent fix, add a mapping to settings.json. VS Code's documentation says the files.associations setting can associate file names or patterns with jsonc. A pattern such as *.config.json mapped to jsonc is one example.

A third-party guide from formatarc.com says the status-bar switch lasts only for the current editor session. I haven't verified that against Microsoft's documentation, so treat it as a reason to use files.associations for anything permanent.

What changing the mode doesn't do​

Changing the mode only silences the editor. As formatarc.com puts it, the file's consumers still decide what they accept. If a strict parser such as JSON.parse or Python's json.loads later reads the file, the runtime error remains, and the comments themselves have to go.

MakeUseOf's author reports exactly this in tests on VS Code 1.140 on Windows 11. Python's json module raised a JSONDecodeError at the first comment, and PowerShell's ConvertFrom-Json rejected the file too. I haven't reproduced those tests. They are the author's results on one version, not a guarantee for every setup.

Some files stay strict even inside VS Code. The author says package.json stays in strict JSON mode, so a comment there gets a red error. Don't assume every .json file in your project behaves like settings.json.

Practical rules​

• Comment freely in files VS Code labels JSON with Comments, such as settings.json, tasks.json and launch.json.
• Keep data files strict. That means anything a script, API or other application will parse, such as exports or machine-generated files.
• Remove comments and trailing commas before handing a file to a strict consumer. Microsoft's open-source node-jsonc-parser includes a stripComments utility. I haven't confirmed it handles trailing commas, so check the output against your target parser's requirements.
• Look at the status bar before copying a config into another tool.

Is JSONC becoming a standard?​

MakeUseOf suggests the community specification, in draft since September 2025, means other tools may eventually agree on the same rules. That is a reasonable hope but not a certainty.

The draft says JSONC was informally introduced by Microsoft for VS Code's configuration files. It aims to formalize what jsonc-parser accepts under its default configuration. The draft itself says it is subject to change. In that default configuration, trailing commas are not accepted, so the spec leaves them optional.

The VS Code JSON language server's own README is more modest. It describes JSONC as a VS Code-specific format for VS Code configuration files, "without any aspirations to define a new common file format."

So there is a community effort to document the dialect, but VS Code's own documentation doesn't present JSONC as a universal interchange format. Third-party guides also disagree on whether JSONC includes trailing commas, which shows how loose the label still is. Strict-JSON advocates have a fair point: comments invite dialects such as JSON5. VS Code's approach limits the damage by keeping JSONC to a named mode and a known set of files.

Bottom line​

VS Code isn't breaking JSON. It runs a separate, documented dialect for configuration files and keeps strict JSON as the default elsewhere. Comments in settings.json are safe and useful, since they record why you changed a setting. Just remember that the leniency belongs to VS Code and ends where a strict parser begins.