JSON vs JSON5 vs JSONC: What's the Difference?

Why JSON variants exist

JSON was designed for data interchange between programs — a machine-readable format where brevity and parsability matter most. Those goals make JSON strict: no comments, no trailing commas, no unquoted keys. This strictness is an asset for API communication, where any ambiguity would cause problems.

But JSON is also used heavily for configuration files — files that humans edit and maintain. In that context, the strictness becomes friction. Developers want to leave comments explaining why a setting is set a certain way, add trailing commas to make diffs cleaner when adding new entries, or write readable numbers. JSON5 and JSONC address this need.

Standard JSON (RFC 8259)

Standard JSON is defined by RFC 8259 (December 2017), which supersedes earlier ECMA-404 and RFC 4627 definitions. It specifies exactly six value types:

• String (must use double quotes)
• Number (decimal only — no hex, no Infinity, no NaN)
• Object (keys must be double-quoted strings)
• Array
• Boolean (true or false, lowercase)
• Null (null, lowercase)

No comments. No trailing commas. No unquoted keys. No hexadecimal. These limitations are intentional — they keep JSON unambiguous and trivial to parse correctly.

Use standard JSON for: all API request/response bodies, data stored in databases, message queues, any context where the consumer is a standard JSON parser.

JSON5

JSON5 is a superset of JSON that adds several features borrowed from ES5 JavaScript. All valid JSON is valid JSON5 — you can incrementally adopt JSON5 features in an existing JSON file without breaking anything.

What JSON5 adds over standard JSON:

• Comments — both // single-line and /* block */ comments
• Trailing commas — after the last array element or object member
• Single-quoted strings — 'value' is valid alongside "value"
• Unquoted keys — { name: "Alice" } is valid if the key is a valid ES5 identifier
• Hexadecimal numbers — 0xFF
• Leading/trailing decimal point — .5 and 5.
• Infinity and NaN — as numeric values
• Multi-line strings — using a backslash before a newline inside a string

// This is valid JSON5 but invalid JSON
{
  // Server configuration
  host: 'localhost',    // unquoted key, single-quoted value
  port: 8080,           // trailing comma
  timeout: 0xFF,        // hex number
  retries: 3,
}

JSON5 requires a dedicated parser: the json5 npm package for JavaScript/Node.js, or pip install json5 for Python. Standard JSON.parse() and Python's json.loads() will reject JSON5 syntax.

Use JSON5 for: application config files that developers edit by hand. It's especially common in build tool configuration, where a readable format with comments is more valuable than strict JSON compatibility.

JSONC (JSON with Comments)

JSONC is a minimal extension: it takes standard JSON and adds only one thing — // single-line and /* block */ comments. Everything else remains identical to standard JSON: double-quoted keys, no trailing commas, no unquoted keys.

JSONC is used by:

• VS Code for its user settings (settings.json), keyboard shortcuts (keybindings.json), and extensions
• TypeScript for tsconfig.json
• ESLint for .eslintrc.json (VS Code extension mode)

// tsconfig.json uses JSONC — comments are valid here
{
  "compilerOptions": {
    "target": "ES2020",    // ECMAScript target version
    "strict": true,
    "outDir": "./dist"     /* compiled output directory */
  }
}

Note that VS Code files like settings.json also permit trailing commas in many versions. This technically makes them JSON5 rather than strict JSONC, but the VS Code ecosystem calls them JSONC.

Use JSONC for: config files in tools that explicitly support it (VS Code, TypeScript). If you're writing a tool that reads config files, supporting JSONC (stripping comments before parsing) is a small addition that significantly improves developer experience.

Quick comparison table

Converting JSON5 or JSONC to standard JSON

If you need to use a JSON5 or JSONC file as input to a tool that only accepts standard JSON, you must strip the non-standard syntax first. In Node.js:

// Convert JSON5 to standard JSON
const JSON5 = require('json5');
const fs = require('fs');

const data = JSON5.parse(fs.readFileSync('config.json5', 'utf8'));
fs.writeFileSync('config.json', JSON.stringify(data, null, 2));

Note that converting to standard JSON strips all comments — they cannot be represented in the output.

Validate standard JSON — free

The json-indent.com validator follows RFC 8259 strictly — it will flag comments and trailing commas as errors (because they are invalid in standard JSON).

Frequently Asked Questions