Can JSON Have Comments? JSONC, JSON5, and Workarounds

No. Standard JSON can't have comments. The spec has no syntax for them, so // and /* */ make a strict parser fail. If you need comments, you have three ways out: use a JSON superset like JSONC or JSON5, strip the comments before you parse, or put the note inside the data as a normal key.

This post shows what each choice costs, with real parser errors and the exact rules from each spec. It also covers where notes about data should live when the JSON sits in a CMS. That part ties into how we think about content modeling at Draftbase.

Can JSON have comments?

JSON can't have comments. RFC 8259, the current JSON standard, defines whitespace as four characters: space, tab, line feed, and carriage return. There is no rule for a comment. Anything else between tokens is an error.

Here's what that looks like in practice. Take this file:

{
  // port for local dev
  "port": 3000
}

Node 24 throws on it:

SyntaxError: Expected property name or '}' in JSON at position 4 (line 2 column 3)

Python's json module fails at the same spot:

JSONDecodeError: Expecting property name enclosed in double quotes: line 2 column 3 (char 4)

Both parsers see the / and stop. They're doing what the spec says.

Why doesn't JSON allow comments?

JSON was built as a data format for machines to swap, not a config format for people to edit. Keeping the grammar tiny makes every parser simple and every parser agree. That's the whole point of the format.

Comments would add drift. If one parser read a hint inside a comment and another skipped it, the same file would mean two things. A strict grammar shuts that door.

The RFC does leave a small gap. Section 9 says a parser "MAY accept non-JSON forms or extensions." So some tools take comments anyway. But a file with comments is no longer JSON. It's a superset that only some tools read.

What is JSONC?

JSONC means "JSON with Comments." It's plain JSON plus two comment styles: // line comments and /* */ block comments. Nothing else changes. Keys still need double quotes. Strings still use double quotes.

You've likely used it already. VS Code has a "JSON with Comments" mode, and it uses that mode for settings.json, tasks.json, and launch.json. That's why you can leave notes in your editor settings but not in a package.json.

TypeScript reads tsconfig.json the same way. We checked this with tsc 7.0.2: a tsconfig.json with // comments and a trailing comma compiled with no errors.

There's now a draft spec at jsonc.org. It's MIT licensed and written down from what Microsoft's jsonc-parser package accepts. A few details from it:

• The file extension is .jsonc and the media type is application/jsonc.
• # comments are not allowed. Only // and /* */.
• Trailing commas are a "MAY," not a must. The reference parser turns them off by default.

That last point trips people up. VS Code accepts a trailing comma in settings.json but shows a warning. Another JSONC parser may reject it. If you want a file that works everywhere JSONC is read, skip trailing commas.

What is JSON5?

JSON5 goes further. Its 1.0.0 spec came out in March 2018, and it aims to make JSON easier for people to write by hand. It takes ideas from ES5 JavaScript.

On top of comments, JSON5 adds:

• trailing commas in objects and arrays
• unquoted keys, as long as they're valid identifiers
• single-quoted strings
• strings split across lines with a backslash
• hex numbers like 0xFF
• a leading or trailing decimal point, like .5 or 5.
• Infinity, -Infinity, and NaN
• a plus sign on numbers

So this is valid JSON5:

{
  // unquoted key, single quotes, trailing comma
  name: 'draftbase',
  retries: 3,
}

JSON5 is great for files people edit often. The cost is reach. You need the json5 package to read it, and JSON.parse won't touch it. Some JSON5 values, like NaN, have no JSON form at all. Convert a JSON5 file to JSON and those values have nowhere to go.

JSON vs JSONC vs JSON5: which should you use?

Pick by who reads the file.

Format	Comments	Trailing commas	Unquoted keys	Parsed by JSON.parse
JSON	No	No	No	Yes
JSONC	// and /* */	Parser choice	No	No
JSON5	// and /* */	Yes	Yes	No

Use plain JSON when a program writes the file or reads it over the wire. API bodies, webhook payloads, and stored data all belong here. Every language reads it with no extra package.

Use JSONC for config files your tools already treat as JSONC. That's tsconfig.json and VS Code settings. Don't invent a new one. A teammate's tool might read it as plain JSON and crash.

Use JSON5 for hand-edited config you own end to end. If you control the code that loads the file, the extra syntax is worth it. If other tools read it too, check that each one supports JSON5 first.

How do you add comments to a JSON file anyway?

Sometimes the format is fixed and you still need a note. Here are the common workarounds, from safest to riskiest.

Add a comment key

Put the note in the data as a normal string field:

{
  "_comment": "port for local dev only",
  "port": 3000
}

This is valid JSON, so every parser accepts it. The catch is that the key is real data. Code that loops over keys will see it. A strict schema with additionalProperties: false will reject it. Pick a name your code knows to skip, and use it the same way everywhere.

Strip comments before parsing

Packages like strip-json-comments remove comments and leave the rest. You read the file as text, strip it, then call JSON.parse:

import stripJsonComments from 'strip-json-comments';

const config = JSON.parse(stripJsonComments(text));

This keeps your parser strict and lets people write notes. It only works when your own code loads the file. Any other tool that reads the same file still sees the comments and fails.

Use a real JSONC or JSON5 parser

If the file is JSONC, read it with jsonc-parser. If it's JSON5, use json5. Then name the file .jsonc or .json5 so editors and teammates know what it is. A .json name on a file with comments is a bug waiting for the next tool.

Switch to YAML

YAML has # comments built in. YAML 1.2 was also designed as a strict superset of JSON. For config that people edit a lot, that's often the cleaner move. We cover the tradeoffs in a separate post on JSON vs YAML.

Where should notes about JSON data live?

Most comments in JSON explain what a field means. "Port for local dev." "Must be a URL." "Shown in the card title." That's not a note about one file. It's a rule about the shape of the data.

Rules about shape belong in a schema. JSON Schema has title and description keywords for this. They travel with the schema and every validator reads them. So the note stays with the rule instead of getting lost in one file.

A CMS works the same way. In Draftbase, each field on a template has a label, a type, a required flag, and an optional helpText. That help text shows up next to the field in the editor. So the "what is this for" note sits with the field, and the stored JSON stays plain. Our post on schema-driven content modeling goes deeper on that split.

Long notes for people go somewhere else again. A paragraph of "how to set this up" is prose, not data. Write it in Markdown or MDX next to the content it explains.

What breaks when JSON has comments?

The failures are boring, which is why they ship.

A tool reads JSONC as JSON. Your editor is fine with comments in a config file. Then a CI script calls JSON.parse on it and the build dies. The fix is to name the file .jsonc, or to load it with a JSONC parser in every place.

Trailing commas pass in one parser and fail in another. VS Code warns, the reference JSONC parser rejects them by default, and JSON5 accepts them. Same file, three results.

A JSON field in your app gets a comment pasted in. Someone copies a snippet from a JSONC config into a form that stores JSON. The save fails, or worse, the app saves a string instead of an object. Validate on the way in, and show the parser error to the person who typed it.

Comment keys leak into output. A _comment key ends up in an API response or a rendered page. Strip known comment keys before you send data out, or don't use them in data that leaves your system.

How do JSON comments affect APIs and LLM prompts?

Over the wire, comments are dead weight. An API should send plain JSON. Clients in every language can read it, and nobody has to guess which superset you meant.

The same goes for data you hand to a model. A comment in a prompt costs tokens and adds a second kind of syntax the model has to track. If the model needs to know what a field means, a schema or a short line of prose does that job better. We cover this more in structured content for LLMs.

Draftbase's delivery API returns plain JSON for this reason. Rich text comes back as an MDX string inside that JSON, not a nested tree you have to walk. If you've fought vendor rich text formats before, why rich text JSON is painful for React developers covers what goes wrong.

Conclusion

Can JSON have comments? Not in the standard. RFC 8259 has no comment syntax, and strict parsers like JSON.parse reject them. JSONC adds // and /* */ and fits tool config like tsconfig.json. JSON5 adds comments plus friendlier syntax for hand-edited files. When the format is locked, a comment key or a strip step gets you by.

For data that lives in a CMS, skip the comments and put the meaning in the schema. Draftbase templates give every field a type and help text, and the API sends plain JSON your code can trust. The Hobby plan is free. See pricing to start.