toolgarden.xyz
中文
JSONJSON5JSONCconfiguration

JSON vs JSONC vs JSON5: Differences and How to Choose for Config Files

Compare JSON, JSONC and JSON5 item by item, from comments, trailing commas and quotes to number syntax and parser compatibility, then learn how to pick one for config files and convert to standard JSON.

ToolGarden tools prioritize browser-local processing, so files and text do not need to be uploaded to a server.

Published July 2, 2026Updated October 14, 202610 min readBy ToolGarden

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

FeatureJSONJSONCJSON5
// and /* */ commentsNoYesYes
Trailing commasNoMost implementations, depends on the readerYes
Single-quoted stringsNoGenerally noYes
Unquoted keysNoGenerally noYes (must be a valid identifier)
Line continuation in strings (trailing backslash)NoGenerally noYes
Hexadecimal numbers like 0x1FNoNoYes
+1, .5, 5. number formsNoNoYes
Infinity, NaNNoNoYes
Specification statusECMA-404 / RFC 8259Convention, no single specPublic spec at json5.org
Common extension.json.jsonc or reuse .json.json5

Where each format shows up

ScenarioTypical fileSuggested formatReason
HTTP APIs, databases, message queuesAPI responses, event payloadsStrict JSONCross-language interoperability, consistent parsers
npm package metadatapackage.jsonStrict JSONPackage managers read standard JSON; comments cause errors
Editor and compiler configtsconfig.json, VS Code settingsJSONCThese tools explicitly support comments, handy for explaining options
Hand-written config that needs lots of commentsToolchain config, rule filesJSON5 or YAMLMore readable; confirm the reading program supports it first
Config shared by several languages or toolchainsCross-team common configStrict JSONThe 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

  1. Identify the readers: list every program that reads the file and check their documentation for comment and trailing comma support.
  2. 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.
  3. Inspect numeric fields: were hex values, NaN or Infinity converted, and is the meaning still right?
  4. 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.

ReaderAttitude to comments and trailing commasNotes
JSON.parse in browsers and Node.jsRejects bothStandard implementation, throws on comments or trailing commas
Python standard library jsonRejects bothSuch files must be cleaned first, or read with a third-party library that supports loose syntax
Command-line tools such as jqReject by defaultParse as strict JSON
TypeScript compiler reading tsconfig.jsonAcceptsA special allowance for that config file, not applicable to other JSON files
VS Code settings and task filesAcceptThese files are read as JSON with comments
npm reading package.jsonRejectsRead as standard JSON
Parsing libraries such as json5Accept (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.

  1. 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".
  2. Paste the original into JSON Repair to get standard JSON. Keys get double quotes and strings become double-quoted.
  3. Check numbers one by one: scientific notation such as timeout: 1e3 is normalized to 1000, so confirm it still matches your intent.
  4. 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.
  5. 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.

Frequently asked questions

Q.Is JSONC an official standard?

No. JSONC is a general name for JSON with Comments and has no independent official specification. Tools such as VS Code and TypeScript each define the syntax they accept, which usually includes comments and sometimes trailing commas. Follow the documentation of the program that reads the file.

Q.Can package.json contain comments?

No. Package managers such as npm read package.json as standard JSON, and comments or trailing commas make parsing fail. Put explanations in a README or other documentation.

Q.Is JSON5 better than JSON?

It depends. JSON5 is friendlier for hand-written config but is not supported by default in every language and tool. For data exchange, strict JSON has better compatibility.

Q.What is lost when converting to standard JSON?

Comments are lost, hex and similar numbers are written in decimal, Infinity and NaN become null, and quote and indentation styles are normalized. Structure and ordinary strings, numbers and booleans are unchanged.

Q.Which syntax does the ToolGarden formatter accept?

The page parses standard JSON first and falls back to JSON5, so comments, trailing commas, single quotes and unquoted keys are all read, and the output is always standard JSON.

Q.What is the risk of adding comments to a .json file?

The main risk is that some tool cannot read it. Your editor may be perfectly happy while a CI script, third-party service or backend parser fails outright. Validate once with something that only accepts standard JSON before shipping.