JSON5 vs JSON: what's the difference and when to use which

json developer-tools

JSON5 vs JSON: what's the difference and when to use which

JSON is the lingua franca of the web, but it has annoying limitations: no comments, no trailing commas, keys must be quoted, and you cannot even put a newline in a string without escaping it. JSON5 is a superset of JSON that fixes all of these — at the cost of compatibility.

This guide covers the syntax differences, the compatibility tradeoffs, and a decision tree for picking the right format.

Want to format or validate JSON right now? Use the free JSON Formatter — handles large files, syntax highlighting, and tree view.

What JSON5 adds

JSON5 is a strict superset of JSON. Every valid JSON document is also a valid JSON5 document. JSON5 adds these features:

1. Comments

{
  // This is a line comment
  / This is a block comment /
  "name": "RuMystic",
}

JSON does not allow comments. This is the single most common reason people reach for JSON5 — config files need comments.

2. Trailing commas

{
  "a": 1,
  "b": 2,
  "c": 3,  // ← trailing comma is fine
}

JSON rejects trailing commas. This is the second most common reason — diff churn when you add or remove the last item in a list.

3. Unquoted keys

{
  name: "RuMystic",       // unquoted key
  "tool-count": 39,       // quoted because of the hyphen
  "valid?": true,         // quoted because of the ?
}

JSON requires all keys to be double-quoted. JSON5 allows unquoted keys if they are valid JavaScript identifiers (letters, digits, $, _, no starting digit).

4. Single-quoted strings

{
  "double": "quoted",
  'single': 'quoted',     // ← single quotes allowed
}

JSON only allows double quotes. JSON5 allows both.

5. Multi-line strings

{
  "description": "This is \
a multi-line string",
  "poem": Line 1
Line 2
Line 3,                // ← template literal
}

JSON strings must be on a single line (with \n for newlines). JSON5 allows line continuations with backslash and template literals with backticks.

6. Hex numbers, leading/trailing dots, +/- signs

{
  "hex": 0xFF,
  "decimal": .5,           // leading dot
  "big": 1e10,             // exponential
  "negative": -0,
  "positive": +42,         // explicit positive sign
  "infinity": Infinity,
  "nan": NaN,
  "not-a-thing": null,
}

JSON numbers are restrictive: no hex, no leading dot, no Infinity or NaN. JSON5 allows all of these.

7. More whitespace

JSON5 allows additional whitespace characters that JSON does not: tab, vertical tab, form feed, non-breaking space, and more.

Compatibility

ParserJSONJSON5
Native JSON.parse() (all browsers)✓✗
Node.js require('./file.json')✓✗ (unless you install json5)
Python json.loads()✓✗
Go encoding/json✓✗
json5 npm package✓✓
json5 Python package✓✓
Most online validators✓✗

The rule: JSON5 requires a JSON5-aware parser. If you are not sure the consumer has one, use JSON.

When to use JSON5

Use JSON5 when:

  • Config files — .json5 config files are common in modern tooling (Babel, Jest, TypeScript compiler options historically). Comments are essential for documenting why each setting exists.
  • Human-authored data — if a person is writing or editing the file, JSON5's quality-of-life features matter.
  • Internal tooling — if you control both the producer and the consumer, JSON5 is fine.

    • Use JSON when:

  • APIs — every HTTP API should return JSON, not JSON5. Clients cannot be expected to have a JSON5 parser.
  • Inter-system communication — if data flows between systems in different languages, JSON is the lowest common denominator.
  • Storage — if you are writing data to a file that another tool might read, JSON is safer.
  • Browser APIs — localStorage, IndexedDB, postMessage all expect JSON.

    • Use JSONC when:

    JSONC (JSON with Comments) is a Microsoft invention used in VS Code settings. It is JSON plus // and / / comments, nothing else. If you only need comments and nothing else, JSONC is a smaller extension than JSON5.

    The decision tree

  • Will this file be consumed by a system you do not control? (an API client, a third-party tool, a database)
    • - Yes → use JSON. - No → continue.

  • Will this file be edited by humans? (config, fixtures, test data)
    • - Yes → continue. - No → use JSON (it is the simplest and most universal).

  • Do you only need comments, nothing else?
    • - Yes → use JSONC (smaller surface area, supported by VS Code). - No → continue.

  • Do you need trailing commas, unquoted keys, multi-line strings, or other conveniences?
    • - Yes → use JSON5. - No → use JSONC.

    Converting between JSON and JSON5

    JSON5 → JSON

    Strip the JSON5-only features:

    import JSON5 from 'json5';
const json5String = fs.readFileSync('config.json5', 'utf8');
const data = JSON5.parse(json5String);
const jsonString = JSON.stringify(data, null, 2);

    This works because every JSON5 value is also a valid JavaScript value, and JSON.stringify produces standard JSON.

    JSON → JSON5

    Standard JSON is already valid JSON5 — no conversion needed. You can optionally add comments or unquote keys, but that is a manual step.

    Parsing JSON5 in JavaScript

    // Install: npm install json5
import JSON5 from 'json5';
    const data = JSON5.parse(json5String);
const string = JSON5.stringify(data, null, 2);

    The json5 package's API mirrors the native JSON object, so it is a drop-in replacement.

    Parsing JSON5 in Python

    # Install: pip install json5
import json5
    data = json5.loads(json5_string)
string = json5.dumps(data, indent=2)

    Parsing JSON5 in Node.js config files

    If you want require('./config.json5') to work, install the json5 register hook:

    require('json5/lib/register');
const config = require('./config.json5');

    Or use a build tool that supports JSON5 natively (Vite, esbuild, webpack with a loader).

    Common mistakes

    Mistake 1: Putting JSON5 in an API response

    HTTP/1.1 200 OK
Content-Type: application/json
    {
  // comment
  "name": "RuMystic",
}

    The Content-Type: application/json header promises standard JSON. The comment makes this invalid JSON. Many clients will fail to parse it. Use application/json5 if you must, but expect poor support.

    Mistake 2: Using JSON5 for localStorage

    localStorage.setItem('settings', JSON5.stringify(settings));
// later
const settings = JSON5.parse(localStorage.getItem('settings'));

    This works if you always include the json5 library, but it adds weight. Use JSON.stringify and JSON.parse for storage — they are native and fast.

    Mistake 3: Assuming JSON.parse accepts comments

    It does not. JSON.parse('{"a":1,/ comment /"b":2}') throws SyntaxError: Unexpected token /. If you have a JSON string with comments, you must strip them before parsing, or use a JSONC/JSON5 parser.

    The history

    JSON was specified by Douglas Crockford in the early 2000s as a minimal data interchange format. He deliberately omitted comments to prevent people from using JSON as a config format (he wanted config to use YAML or a dedicated format). The web ignored this advice and used JSON for config anyway, which led to JSONC, JSON5, and other extensions.

    JSON5 was created by Aseem Kishore in 2012 and is now maintained as an open-source project. It is widely used in the JavaScript ecosystem, particularly for config files.

    Try it yourself

    Open the free RuMystic JSON Formatter:

    • Paste JSON (or JSON-like) input.
    • Format, minify, syntax-highlight, tree view.
    • No upload — your data stays in your browser.
    • No size limit beyond your browser's memory.
    Format away.