JSON has no comments because its designer took them out on purpose. Douglas Crockford, who formalised the JSON specification in the early 2000s, later explained the reasoning himself: he had watched people slip parsing directives into comments — instructions meant for one particular reader of the file, hidden inside what was supposed to be plain, interchangeable data. Once that starts, two programs reading the same document can legitimately disagree about what it means, which is the one thing a data-interchange format cannot afford. Removing comment syntax entirely was the blunt fix: with nowhere to put a directive, nobody can hide one.
What Crockford actually said, and what he suggested instead
The explanation comes from a public post of his, later quoted widely: "I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability." His follow-up was pragmatic rather than absolute — comments are fine to write, as long as they never reach the parser: "If you want comments in your JSON, knock yourself out — just strip them out before handing it over to your parser." That is the whole philosophy in one sentence. A build step, a preprocessor, a text editor's find-and-replace — anything that removes the comment before JSON.parse sees the file keeps the format's one guarantee: every conformant parser, in every language, reads the same bytes the same way.
Two dialects patched the gap back in, and they are not the same thing
JSON5 is the bigger of the two. It is a superset of JSON built to also be a workable subset of ECMAScript 5, so alongside comments it allows single-quoted strings, unquoted object keys, a trailing comma, hexadecimal numbers, and numbers with a leading or trailing decimal point. It is genuinely popular — as of 2022 its own project reported more than 65 million weekly npm downloads, putting it in the top 0.1% of most-depended-on packages, with Chromium, Next.js and Babel among the tools that read config files written in it.
JSONC — JSON with Comments — is narrower. It keeps JSON's grammar almost entirely intact and adds exactly two things: // and /* */ comments, plus a trailing comma that most JSONC readers tolerate with a warning rather than an error. It is not a general-purpose format so much as a house style: it exists because VS Code needed somewhere to put its own settings with notes attached, and it stayed narrow on purpose.
Neither one is JSON. A file written in either will fail the moment it reaches JSON.parse, or any other strict reader — including the one on this site.
Which of your config files are secretly which dialect
This is where the difference stops being trivia and starts explaining error messages. package.json is read by npm with a strict parser: a // anywhere in it is a syntax error, full stop, no exceptions for "just this once." tsconfig.json is the opposite case in the same ecosystem — the TypeScript compiler parses it as JSONC, so line and block comments and a trailing comma are not just tolerated, they are normal, and most editors will syntax-highlight the file accordingly. VS Code's own settings.json, tasks.json and launch.json are the same JSONC mode. Three files that all end in .json, sitting in the same repository, obeying three different rules depending entirely on which piece of software opens them next.
The extension never tells you which rule applies. The only reliable way to find out is to check what actually reads the file — and if you are not sure, assume strict JSON and leave comments out, because that assumption is never wrong.
What happens when you paste a commented file in here
The JSON formatter on this site is strict on purpose, the same as JSON.parse. Paste in a file with a // line and it reports a syntax error at the position where the comment starts, the same way it would for a stray trailing comma. That is not a bug to file — a formatter that quietly accepted JSON5 or JSONC would be lying about what your actual deployment target will do with the file, and the one thing worse than an error here is a false pass followed by a real one somewhere that matters more.
What to write instead of a comment
Three honest options, depending on what the comment was actually for. If it explained a single value, a sibling key such as "timeout_note" works, at the cost of being data your code now has to ignore rather than metadata a reader can skip. If the file is genuinely meant to be edited by a person and re-read by a program you control, and comments are one of several things you want back, the bigger move is to stop fighting JSON for it — the trade-off between YAML and JSON covers what else you gain and lose by switching. And if the target insists on strict JSON no matter what, writing the source file in JSON5 or JSONC and stripping it down to plain JSON in a build step gets you comments during development and a file that will not surprise anything downstream — which is close to what Crockford suggested from the start, just automated.
One case resolves itself without any of this: if the file you are staring at will not parse and you cannot tell why, and it turns out to have comments in it, that is not a new problem — it is the same near-miss covered in formatting minified JSON, where JSON5 and JSONC show up as one of the handful of reasons a file looks like JSON and is not.
The JSON formatter here will not read a commented file, and it will tell you exactly where it gave up rather than guessing — paste a tsconfig.json into it and the first // is where it stops. If what actually brought you here is a file that will not parse for some other reason entirely, how to format minified JSON works through the rest of the list: trailing commas, truncated responses, and the numbers that quietly lose precision on the way through.
Frequently asked questions
Can I add comments to a JSON file?
Not to standard JSON — there is no comment syntax, and JSON.parse and every other strict parser reject the file the moment they meet one. You can write comments in a JSON5 or JSONC file instead, or strip them out in a build step before the strict parser ever sees them.
What is the difference between JSON5 and JSONC?
JSON5 is the larger extension: comments plus unquoted keys, single-quoted strings, trailing commas and a few numeric formats JSON forbids, aimed at being a format people write by hand. JSONC only adds comments and a tolerated trailing comma, and exists mainly because Visual Studio Code needed somewhere to put its own commented settings files.
Does tsconfig.json support comments?
Yes. The TypeScript compiler reads tsconfig.json as JSONC, so // and /* */ comments and a trailing comma are normal there, even though the file has a .json extension. package.json, read by npm, does not get the same treatment and will fail on the same comment.
Why did Douglas Crockford remove comments from JSON?
By his own account, he had seen people use comments to carry parsing directives — instructions meant for one particular parser rather than data — which broke the guarantee that any conformant parser reads a JSON document the same way. Removing comment syntax entirely closed that door rather than trying to police how comments were used.
Will adding a comment break package.json?
Yes, immediately. npm parses package.json as strict JSON, so a // or /* */ anywhere in the file is a syntax error, and the install or script that reads it will fail before it does anything else. There is no supported way around it short of removing the comment.
Last updated September 25, 2026
