Why JSON Has No Comments (And 4 Workarounds That Do)

No, standard JSON does not allow comments. The spec has no syntax for them, and every strict parser (JSON.parse in JavaScript, json.loads in Python) will throw an error the moment it hits a // or /* */. If you need notes inside your data, you have four solid workarounds, and the right one depends on whether the file is a config file or an API payload.

Can you put comments in JSON? The short answer

You cannot, at least not in JSON as defined by the standard. Try this in a browser console:

JSON.parse('{ "port": 8080 // the server port\n}')

You get SyntaxError: Unexpected token / in JSON at position 20. The parser reaches the slash, finds nothing in the grammar that permits it, and stops.

That is the honest answer to “can you comment in JSON”: not in the raw format. But the question people really mean is “how do I leave a note next to a value without breaking the parser,” and there are several ways to do that. The four below cover almost every real case, from a quick hack that works everywhere to full comment-friendly dialects like JSONC and JSON5.

Why Douglas Crockford removed comments from JSON

Comments were in early JSON. Douglas Crockford, who specified the format, took them out on purpose. His reasoning, posted publicly in 2012, is worth quoting in spirit: he had seen people abuse comments to hold parsing directives, which would have broken interoperability and turned a simple data format into something each tool interpreted differently.

His fix was blunt. Strip comments before handing the text to a JSON parser. As he put it, you could pipe your data through a program like JSMin to remove comments, which also keeps them from being used to smuggle in behavior.

So the missing feature is a deliberate design choice, not an oversight. JSON was meant to be a minimal data-interchange format, the kind of thing two machines exchange without argument. A comment is a human affordance, and Crockford decided the data layer was the wrong place for it. Whether you agree or not, that decision is why you are reading a workarounds article instead of a syntax reference. If you want the fuller picture of what the format does and does not include, see our guide on what JSON actually is.

Workaround 1: a dummy comment key

The most portable trick needs no special parser. Add a normal key whose only job is to hold a note:

{
  "_comment": "port must match the value in nginx.conf",
  "port": 8080,
  "host": "0.0.0.0"
}

This is valid, standard JSON. Any parser reads it fine because _comment is just a string field. The leading underscore is a convention to signal “ignore me,” and some teams use // as the key name instead:

{
  "//": "staging only, do not deploy",
  "env": "staging"
}

The catch: a key like // can only appear once per object, since JSON object keys should be unique. Duplicate keys are technically allowed by the grammar but most parsers keep only the last one, so two // notes in the same object will silently lose one. This approach works great for a top-level note or two. It gets clumsy when you want a comment on every third line. It also ships the note to production, so anyone reading the API response sees it too.

Workaround 2: JSONC (JSON with Comments)

JSONC is JSON plus // line comments and /* */ block comments. It is not an official standard, but it is everywhere you edit config. Visual Studio Code uses it for settings.json, tsconfig.json, and launch.json:

{
  // the port your dev server listens on
  "port": 8080,
  /* the interface to bind:
     0.0.0.0 exposes it on the network */
  "host": "0.0.0.0"
}

The important detail is that JSONC is not JSON. A file with comments will crash JSON.parse. You need a parser that understands the dialect, such as the jsonc-parser npm package or the built-in support in editors and TypeScript tooling. TypeScript’s own tsconfig.json is JSONC, which is why you can comment it freely while a plain package.json (parsed as strict JSON by npm) cannot take a single //.

Use JSONC when the file is read by a tool you control that already speaks it. Do not use it for data you hand to a generic JSON parser or send over an API.

Workaround 3: JSON5

JSON5 goes further than JSONC. It is a superset of JSON aimed at hand-written files, and comments are just one of its conveniences. A JSON5 file can look like this:

{
  // comments, both line and block
  port: 8080,          // unquoted keys
  host: '0.0.0.0',     // single quotes
  tags: ['dev', 'local',],  // trailing comma allowed
  ratio: .5,           // leading decimal point
  hex: 0xFF,           // hex numbers
}

Unquoted keys, single quotes, trailing commas, and comments all become legal. That makes JSON5 pleasant to write by hand, which is exactly its stated goal. The trade is a heavier departure from standard JSON, so you need the json5 package (JSON5.parse) to read it, and fewer tools support it than support plain JSON or JSONC.

Reach for JSON5 when humans author the file often and the ergonomics matter more than universal tool support, for example a build config or a seed-data file in a JavaScript project. For anything a stranger’s parser will touch, stay closer to the standard. The stricter your data has to travel, the fewer of these conveniences you can afford, which is really a question about JSON’s syntax rules and who has to obey them.

Workaround 4: strip comments before parsing

This is Crockford’s own recommendation, and it keeps your stored file readable while feeding clean JSON to the parser. Write the file with comments, then remove them at load time:

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

const raw = readFileSync('config.jsonc', 'utf8');
const config = JSON.parse(stripJsonComments(raw));

The strip-json-comments package deletes // and /* */ while leaving anything that looks like a comment inside a string alone, so a URL like "https://nelenga.com" survives. You get commented source and standard parsing with no dialect lock-in.

The downside is one extra step and one extra dependency. If you forget to strip before parsing somewhere in your pipeline, you get the same SyntaxError from the top of this article. Keep the strip call in one place, ideally a small loader function every part of your app goes through.

Which approach to pick for config files vs APIs

The split is clean once you separate config from data on the wire.

For config files that humans edit: use JSONC if your tool already supports it (editors, TypeScript, VS Code do), or JSON5 if you want the extra hand-writing comforts and control the parser. Strip-before-parse is the neutral choice when you want commented source but standard JSON semantics and no new dialect.

For API payloads and data you send between services: use none of the dialects. Keep it strict, standard JSON. An API response is read by clients you do not control, and half of them run plain JSON.parse. If a value genuinely needs explanation, either put it in your API docs or add a real documented field like "note" (Workaround 1) that clients can choose to read. Comments do not belong in transit, which is part of why teams comparing formats sometimes look at alternatives, covered in JSON vs YAML vs XML where YAML’s native comments are a real selling point.

A quick way to sanity-check any of this: paste your file into our JSON formatter. It parses with strict rules, so if a stray comment or trailing comma is breaking your config, the formatter points at the exact line the same way your production parser would.

FAQ

Can you comment in JSON at all?

Not in standard JSON. The grammar has no comment syntax, so // and /* */ both cause a parse error. You can only fake it with a dummy key, or switch to a comment-friendly dialect like JSONC or JSON5 and use a matching parser.

Is JSONC valid JSON?

No. JSONC is a superset. Every valid JSON file is valid JSONC, but a JSONC file with comments is not valid JSON and will fail JSON.parse. You need a JSONC-aware parser (or strip the comments first) to read it.

What is the difference between JSONC and JSON5?

JSONC adds only comments to JSON. JSON5 adds comments plus unquoted keys, single quotes, trailing commas, hex numbers, and more, so it is a bigger departure from the standard. JSONC is closer to plain JSON; JSON5 is friendlier to write by hand.

How do I add a comment to package.json?

You cannot directly, because npm parses package.json as strict JSON and rejects comments. The common workaround is a top-level string field, since npm ignores keys it does not recognize. Some projects add a "//" key, though only one such key per object survives parsing.