JSON is the strict standard: no comments, no trailing commas, double-quoted keys and strings only. JSONC ("JSON with Comments") is JSON plus // and /* */ comments, and most parsers also accept trailing commas. JSON5 is a bigger superset with a written spec that also allows unquoted keys, single quotes, hex numbers and multi-line strings.
The quick comparison
| Feature | JSON | JSONC | JSON5 |
|---|---|---|---|
// and /* */ comments |
No | Yes | Yes |
| Trailing commas | No | Often, depends on the parser | Yes |
| Unquoted keys | No | No | Yes |
| Single-quoted strings | No | No | Yes |
Hex numbers, leading +, .5 |
No | No | Yes |
| Formal spec | RFC 8259 | Community draft | JSON5 1.0.0 |
| Typical file names | .json |
.jsonc, sometimes .json |
.json5 |
JSON.parse reads it |
Yes | No | No |
JSON: the strict baseline
RFC 8259 defines JSON as "a lightweight, text-based, language-independent data interchange format". It is deliberately small. Between tokens, it allows only four whitespace characters, and there's no comment syntax at all. That's why a pasted // note breaks JSON.parse (details in Can JSON have comments?), why a trailing comma is a syntax error (the reason is here), and why single quotes fail (see why JSON requires double quotes).
That strictness is the point. Every JSON parser in every language reads the same file the same way.
JSONC: JSON plus comments
JSONC is what you're writing when you edit VS Code's settings. The VS Code docs say its JSON with Comments mode "is used for the VS Code configuration files such as settings.json, tasks.json, or launch.json". It also "accepts trailing commas, but they are discouraged and the editor will display a warning".
It looks like JSON with notes in it:
{
// Format on save, but only for files I own
"editor.formatOnSave": true,
/* Turned off while the linter config is broken */
"eslint.enable": false
}
JSONC has no official standard. The Common JSONC Specification is a community attempt to write down "the most common variant", and it says plainly that "there are multiple differing implementations of JSONC, so not all features might be available in all of them". Trailing commas are the main disagreement. That spec was marked as a draft as of 2025-09-01 because the role of trailing commas was still under discussion, and it notes that some JSONC dialects don't allow them at all.
The most used implementation is Microsoft's node-jsonc-parser, which describes itself as "a scanner and fault tolerant parser that can process JSONC but is also useful for standard JSON". Its parse options include disallowComments and allowTrailingComma. Even inside one library, the dialect is a setting.
JSONC files also often keep the .json extension. A tsconfig.json or settings.json may contain comments that a strict JSON parser in your own script will reject. VS Code lets you map file patterns to JSONC with files.associations. Your build scripts won't know about that.
JSON5: JSON for humans
According to its spec (version 1.0.0, March 2018), it is "a superset of JSON that aims to alleviate some of the limitations of JSON" by borrowing syntax from ECMAScript 5.1. On top of comments and trailing commas, it allows:
- object keys without quotes, as long as they are valid identifiers;
- strings in single quotes, and strings that continue across lines with an escaped newline;
- hexadecimal numbers, a leading or trailing decimal point, and an explicit plus sign;
- extra whitespace characters.
From the reference library's own example:
{
// comments
unquoted: 'and you can quote me on that',
hexadecimal: 0xdecaf,
}
The JSON5 site says it's "easier to write and maintain by hand (e.g. for config files)" and "not intended to be used for machine-to-machine communication". It lists Chromium, Next.js, Babel, Retool and WebStorm among the projects that have adopted it. In Node, you read it with the json5 package (npm install json5), whose JSON5.parse works like JSON.parse but accepts the extra syntax.
Which one should you use?
Most of the time the choice is made for you. If the tool reads tsconfig.json or VS Code settings, you're writing JSONC. If it reads .json5, you're writing JSON5. If it reads plain .json with a standard parser, comments will break it no matter how it looks in your editor.
When you do get to choose, use plain JSON for data that programs exchange, such as API bodies or files another team parses. Everyone can read it, and there's one spec. For a config file where you only want comments, JSONC is the smallest step from JSON, and existing JSON stays valid. If people edit the file all day and you're happy to add the json5 dependency, JSON5's unquoted keys and trailing commas make hand edits less fiddly.
When I control the parser, I pick JSON5 over JSONC. JSON5 has a versioned spec, so "does this parser allow trailing commas?" has one answer. With JSONC, it depends on the library and sometimes on a flag. I use JSONC only when the ecosystem already does, as with VS Code and TypeScript config. If YAML is also on your list, I compared it in JSON vs YAML for config files.
Checking which one you have
Run the file through a strict JSON parser. If it passes, it's plain JSON. If it fails on a /, it's JSONC or JSON5. If it fails on an unquoted key or a single quote, it's JSON5, or a mistake.
The JSON validator on this site runs that check in your browser and shows the JSON.parse error. It only validates standard JSON. There is no JSONC or JSON5 mode, so it reports every comment as an error, even in a file your editor accepts.
FAQ
Is JSONC the same as JSON5?
No. JSONC is JSON plus // and /* */ comments, and in many parsers trailing commas. JSON5 goes further: unquoted keys, single-quoted strings, hexadecimal numbers, multi-line strings and more, and it has a published 1.0.0 spec.
Can JSON.parse read JSONC or JSON5?
No. JSON.parse only accepts standard JSON, so a comment, trailing comma or single quote makes it throw. Use a JSONC parser such as node-jsonc-parser, or the json5 package's JSON5.parse.
Is valid JSON also valid JSONC and JSON5?
Yes. Both are supersets of JSON, so any valid JSON document is also valid JSONC and valid JSON5. The reverse is not true.
Which one should I use for config files?
Use whatever the tool reading the file expects. If you control the parser and want only comments, JSONC is the smaller step; if you want hand-friendly syntax throughout, JSON5. Keep plain JSON for anything machines exchange.