Both look like braces and key-value pairs, yet tsconfig.json may contain comments while package.json may not, and .babelrc may leave keys unquoted while an API response never can. Behind the differences are three related but distinct formats: JSON, JSONC and JSON5. This article explains what each allows, gives a method for deciding which one a given file should use, and shows how to convert loose syntax into standard JSON that any parser accepts.
The one-sentence difference
- JSON: a strict data interchange format defined by ECMA-404 and RFC 8259. No comments, no trailing commas, no single quotes.
- JSONC: "JSON with Comments". It has no independent formal specification and is really a convention: JSON plus // and /* */ comments. Common implementations, such as VS Code settings and TypeScript tsconfig, usually tolerate trailing commas as well. Exactly what is tolerated depends on the program reading it.
- JSON5: a superset of JSON with a public specification (json5.org), borrowing ECMAScript 5 syntax: comments, trailing commas, single quotes, unquoted keys, extra number forms and more.
Syntax comparison table
| Feature | JSON | JSONC | JSON5 |
|---|---|---|---|
| // and /* */ comments | No | Yes | Yes |
| Trailing commas | No | Most implementations, depends on the reader | Yes |
| Single-quoted strings | No | Generally no | Yes |
| Unquoted keys | No | Generally no | Yes (must be a valid identifier) |
| Line continuation in strings (trailing backslash) | No | Generally no | Yes |
| Hexadecimal numbers like 0x1F | No | No | Yes |
| +1, .5, 5. number forms | No | No | Yes |
| Infinity, NaN | No | No | Yes |
| Specification status | ECMA-404 / RFC 8259 | Convention, no single spec | Public spec at json5.org |
| Common extension | .json | .jsonc or reuse .json | .json5 |
Where each format shows up
| Scenario | Typical file | Suggested format | Reason |
|---|---|---|---|
| HTTP APIs, databases, message queues | API responses, event payloads | Strict JSON | Cross-language interoperability, consistent parsers |
| npm package metadata | package.json | Strict JSON | Package managers read standard JSON; comments cause errors |
| Editor and compiler config | tsconfig.json, VS Code settings | JSONC | These tools explicitly support comments, handy for explaining options |
| Hand-written config that needs lots of comments | Toolchain config, rule files | JSON5 or YAML | More readable; confirm the reading program supports it first |
| Config shared by several languages or toolchains | Cross-team common config | Strict JSON | The looser the format, the likelier some consumer cannot read it |
The guiding principle: the writer wants leniency, but the reader decides. You may only use a syntax if every program that reads the file explicitly supports it.
Worked example: turning a tsconfig-style JSONC into standard JSON
This config has comments and trailing commas. Paste it into the JSON Formatter: the page tries standard parsing, and on failure parses as JSON5 and outputs standard JSON.
{
// compiler options
"compilerOptions": {
"target": "ES2020",
"strict": true, /* enable all strict checks */
"paths": { "@/*": ["./src/*"], },
},
"include": ["src"],
}Output (notice the comments and trailing commas are gone, with 2-space indentation):
{
"compilerOptions": {
"target": "ES2020",
"strict": true,
"paths": {
"@/*": [
"./src/*"
]
}
},
"include": [
"src"
]
}That means formatter and repair output is standard JSON, suitable for programs that only accept strict JSON, but comments are lost. If you want to keep maintaining the commented version, do not overwrite the original with the output. Save it as a separate release copy.
What changes when JSON5-only syntax is converted
Some JSON5 syntax changes meaning when converted to standard JSON, and this is the most overlooked part of a migration.
// JSON5 input
{
name: 'it\'s',
mask: 0x1F,
ratio: .5,
retries: +3,
ceiling: Infinity,
missing: NaN,
}// After conversion to standard JSON
{
"name": "it's",
"mask": 31,
"ratio": 0.5,
"retries": 3,
"ceiling": null,
"missing": null
}- Hex 0x1F becomes decimal 31. The readability of a bit mask is lost, so add a note in the field name or documentation.
- The plus sign in +3 and the omitted leading zero in .5 are normalized. The value is unchanged, only the spelling.
- Infinity and NaN have no standard JSON form, so they are written as null and information is lost. Replace such values at the source with an explicit null, a string or a concrete number.
- Escapes inside strings keep their meaning. Single-quoted strings become double-quoted strings, with inner double quotes escaped by a backslash.
A common trap: loose parsing forgives illegal escapes
Standard JSON requires backslashes to be paired. JSON5 is more lenient and treats an unknown escape as the character itself. The result: the Windows path C:\Users\bob raises an error under strict parsing but not under loose parsing, where it is read as CUsers plus a backspace character. The formatter reports success while the data has been altered. Whenever the content contains backslashes, verify string values after conversion and fix the source to C:\\Users\\bob.
How to migrate from JSON5 or JSONC to standard JSON in four steps
- Identify the readers: list every program that reads the file and check their documentation for comment and trailing comma support.
- Paste the original into JSON Repair to get standard JSON, and record what comments were removed, moving the meaning into documentation or field names if needed.
- Inspect numeric fields: were hex values, NaN or Infinity converted, and is the meaning still right?
- Validate with a JSON Schema or the real reader once before replacing the production file.
A simple decision flow
- Will the file be read by different languages or third-party programs? Use strict JSON.
- Is it editor or compiler config whose official documentation explicitly supports comments? Use JSONC, keeping .json or using .jsonc as the tool requires.
- Purely hand-written config that needs heavy explanation, with full control of the reader? Consider JSON5, or simply switch to YAML or TOML, which support comments natively.
- Must it be modified programmatically and written back? Prefer strict JSON, since most libraries drop comments on write.
One last practical test: if you cannot list every program that reads the file, assume one of them is a strict parser. For files whose readers you cannot pin down, do the extra conversion step rather than gamble. Putting comments in adjacent documentation and keeping the file itself plain JSON is the lowest long-term maintenance cost.
How different languages and tools treat loose syntax
"My editor opens it" does not mean "every program can read it". The table below organizes common readers to help you judge where a commented .json file will break.
| Reader | Attitude to comments and trailing commas | Notes |
|---|---|---|
| JSON.parse in browsers and Node.js | Rejects both | Standard implementation, throws on comments or trailing commas |
| Python standard library json | Rejects both | Such files must be cleaned first, or read with a third-party library that supports loose syntax |
| Command-line tools such as jq | Reject by default | Parse as strict JSON |
| TypeScript compiler reading tsconfig.json | Accepts | A special allowance for that config file, not applicable to other JSON files |
| VS Code settings and task files | Accept | These files are read as JSON with comments |
| npm reading package.json | Rejects | Read as standard JSON |
| Parsing libraries such as json5 | Accept (and more syntax) | You must opt in to them in code instead of calling JSON.parse |
The point of this table is not to memorize each row but to build a habit: whenever you want to add a comment to a .json file, first ask which programs read it. If even one is a strict parser, the comment will cause an error there, often in the environment where debugging is least convenient, such as CI or production.
Migration example: turning a JSON5-style config into strict JSON
Suppose a team has a legacy config that uses single quotes, bare keys and comments, and it must now be handed to a new service that only accepts strict JSON. The approach: move the information out of the comments, convert, then verify.
- Read the original and note the meaning of every comment, then put it in a README or separate notes file, for example "retries of 0 means no retry".
- Paste the original into JSON Repair to get standard JSON. Keys get double quotes and strings become double-quoted.
- Check numbers one by one: scientific notation such as timeout: 1e3 is normalized to 1000, so confirm it still matches your intent.
- Save the result as a new file for the new service, and keep the old file as the commented source, noting that it must be converted before release.
- If this will happen often, put the conversion into the build script using a JSON5 library that recognizes string boundaries instead of copy-pasting by hand.
The benefit is that comments always have a home while strict JSON stays clean. The cost is one extra conversion step that someone must maintain. If the team finds that cost too high, the config probably belongs in YAML or TOML to begin with.
When not to use a loose format
- Public APIs or open data: you do not control consumers, so emit strict JSON.
- Content that is signed, hashed or compared byte for byte: loose syntax allows many spellings of the same meaning, so hashes will differ.
- Security-related configuration: parser differences can make one side believe a field exists while another ignores it. Use the strictest, most widely supported format.
Why cleaning comments with a regex is not recommended
Many people write a regex that strips // comments before calling JSON.parse. The problem is that strings may legitimately contain // sequences, such as the URL https://example.com, and a naive regex cuts it in half. If you must do this in a script, use an approach that recognizes string boundaries. To quickly check whether a regex matches the fragment you want to delete, try it in the Regex Tester, but for one-off cleanup the repair page is simpler and less error-prone.