Why VS Code lets settings files break JSON rules
Try loading a VS Code settings.json file-complete with comments and trailing commas-into a strict JSON parser. The process stops cold. Those human-friendly touches that make configs readable are exactly what break compatibility outside the editor. Microsoft built this in on purpose, drawing a hard boundary between developer comfort and the rigid world of data interchange.
Since November 2017, VS Code has opened its config files in JSON with Comments (JSONC) mode. This lets users add // line comments, /* ... */ block comments, and trailing commas. RFC 8259, the official JSON standard, bans all three. Microsoft's logic is blunt: config files are for people. Comments explain settings, and trailing commas make edits less error-prone. But pass that file to Python's json module or PowerShell's ConvertFrom-Json and you hit a wall. Strict parsers reject anything outside the spec.
According to RFC 8259, any use of comments or trailing commas makes a file incompatible with strict JSON parsers, regardless of file extension.
Why Microsoft bends the rules
Microsoft's editors treat files like settings.json, tasks.json, launch.json, and tsconfig.json differently on purpose. The status bar tells you what's allowed: open a generic .json file and you get strict mode. Open a recognized config file and the label flips to JSON with Comments. That toggle decides if your notes and commas pass or get flagged. Parsing runs through Microsoft's open-source node-jsonc-parser library, a move that stands out given the ongoing debate over how open-source VS Code itself really is.
There's more nuance. Save a file as .jsonc and VS Code lets you use comments but warns about trailing commas. Save as settings.json or tsconfig.json and those commas slide by without complaint. The editor knows these files and quietly relaxes the rules, making life easier for anyone editing configs by hand. This approach matches the reality: config files get tweaked and annotated constantly.
The limits of flexibility
But this rule-bending only works inside VS Code. The moment a JSONC file leaves that ecosystem, its quirks become a liability. Standard parsers-like Python's json-fail on the first comment or stray comma, throwing a JSONDecodeError and stopping execution. Even inside VS Code, not every file gets this leeway. package.json, which npm reads, stays in strict mode. One comment triggers a red error. The same goes for app lists exported by Winget on Windows.
Strict JSON supporters point out that comments and trailing commas open the door to dialects like JSONC, JSON5, and HJSON. Each brings its own quirks. A file that works in one tool can break in another. Microsoft's answer is to keep this flexibility contained to a clearly labeled mode and a known set of files. The status bar is your warning: JSON with Comments means you're safe to add notes and commas. Anything else, expect strict enforcement.
The JSONC Draft specification, inspired by Microsoft's implementation, explicitly separates support for comments from optional support for trailing commas, meaning different tools may validate the same file differently.
What developers need to watch for
In practice, comment freely in files labeled JSON with Comments. But always strip comments and trailing commas before handing the file to scripts, APIs, or other tools. The rule-bending works because it's deliberate, contained, and clearly marked. Developers get clarity and context in their configs, and strict compatibility when data leaves the editor. Once your settings are set, it's worth checking which VS Code extensions can further streamline your workflow.
Microsoft's willingness to bend the rules for developer experience-while keeping strict JSON as the default for data interchange-shows a rare balance between pragmatism and discipline. According to the official RFC 8259 specification, JSON does not permit comments or trailing commas, and any file containing them is not valid JSON. This strictness ensures interoperability across platforms and programming languages, but also explains why VS Code's flexibility is intentionally limited to its own configuration ecosystem.
VS Code's documentation makes it clear: JSON with Comments mode is reserved for specific config files like settings.json, tasks.json, and launch.json. Comments are allowed and trailing commas are usually tolerated, sometimes with a warning. This distinction matters for anyone who needs to share or process these files outside VS Code.
