JSON with Comments (JSONC): What It Is and How to Handle It

Your VS Code settings.json has comments in it, and it works fine. So why does JSON.parse explode on the exact same text? Welcome to JSONC.

I learned about JSONC the annoying way: a script that read a VS Code settings.json file and fed it to JSON.parse blew up on a file that VS Code itself had written. The file was fine. My parser was just stricter than VS Code's. That mismatch is the whole story of JSONC.

What JSONC actually is

JSONC means "JSON with Comments." It is strict JSON's grammar plus two things: // line comments and /* */ block comments. That is it. Most flavors also tolerate trailing commas, but the core idea is just comments.

{
  // Local development port
  "port": 3000,
  /* temporarily disabled:
  "debug": true */
}

JSONC is not a new data model and it is not a standard. Nobody published an RFC for it. It is a tolerance that certain tools adopted, most famously VS Code, which reads settings.json, keybindings.json, and tsconfig.json as JSONC. TypeScript's own config files follow the same convention.

Where JSONC is safe and where it breaks

Situation	JSONC okay?	Why
VS Code settings, tsconfig, devcontainer.json	Yes	These tools parse JSONC natively
Config files only your own code reads	Yes, if you control the parser	You can strip comments before parsing
API requests or responses	No	Shared data interchange must be strict JSON
Files with a `.json` extension read by other tools	No	A plain `jq` or `JSON.parse` will refuse it

The rule of thumb: JSONC is fine for configuration you control end to end. It is wrong for anything shared. Sending JSONC in an application/json response, or saving it with a .json extension and assuming every parser accepts it, will break someone's pipeline. I have watched CI workflows fail for exactly this reason: a workflow validated devcontainer.json with jq, which does not tolerate comments, and the build went red on a file the developers swore was fine.

How to strip comments without breaking your data

The naive approach is a regex that deletes everything after //. Do not do this. Comment-like text can legally appear inside strings, and the most common case is URLs:

{ "proxy": "https://example.com/api" }

A careless s|//.*||g turns that URL into "https:" and your config is now broken in a way that is much harder to debug than a parse error. The strip must be string-aware: it has to track whether it is inside a quoted string before deciding that // is a comment.

In JavaScript, the safe options are:

strip-json-comments, a small library that removes comments while respecting strings: JSON.parse(stripJsonComments(jsonc)).
jsonc-parser, which parses JSONC directly and can also report errors with positions.
npx jsonc-parser or the dasel -p jsonc CLI for shell scripts.

If you are writing your own stripper (I have, more than once), process the text character by character, track in-string state with escape handling, and only treat // and /* */ as comments when outside a string. Run block comments before line comments so a // inside a block comment gets removed as part of the block.

The _comment property trap. Some people fake comments by adding a "_comment" field. That works until the data is validated with a schema that sets additionalProperties: false, at which point your "comment" becomes a validation error. For human-edited config, prefer a format that genuinely supports comments.

JSONC vs JSON5: do not confuse them

JSON5 is a bigger superset: it allows unquoted keys, single-quoted strings, trailing commas, and more. JSONC is just comments (and, in practice, trailing commas). If a file has unquoted keys, stripping comments will not be enough, and you need a JSON5 parser instead. Know which flavor you are dealing with before you pick the tool.

My recommendation

Use JSONC for editor and tooling configs where the tool expects it. For anything else human-maintained, pick YAML or TOML, both of which support comments as first-class citizens. And for anything shared between systems, stay with strict JSON and put the documentation in a README next to the file. Comments are for humans; JSON is for machines. JSONC is the awkward middle ground, and it works best when you are honest about which side of the line you are on.

Pasted JSON with comments that will not parse? Strip them and repair the rest automatically.

Fix My JSON Now

Frequently asked questions

Is JSONC the same as JSON?

No. JSONC is strict JSON plus comments (and usually trailing commas). Standard parsers like JSON.parse and jq reject it. It is a tolerance adopted by specific tools, not a standard.

Can I use a regex to remove JSON comments?

Only if the regex is string-aware. A naive pattern will destroy URLs and any other // inside string values. Use a dedicated library like strip-json-comments or a proper JSONC parser.

Should I send JSONC in an API response?

No. Public APIs and shared data interchange should use strict JSON. Use JSONC only for configuration where you control both the writer and the reader.