JSON5 — The Relaxed JSON Format That Allows Comments and Trailing Commas

Strict JSON is deliberately minimal — no comments, no trailing commas, quoted keys only. That minimalism makes it an excellent wire format, but a frustrating one to hand-edit. JSON5 is a community-driven superset of JSON that relaxes exactly those restrictions, aimed squarely at files humans write and maintain by hand: configuration files, build manifests, and data humans read.

What JSON5 Adds on Top of JSON

JSON5 is a strict superset — every valid JSON document is also valid JSON5. It adds:

• Comments — both // single-line and /* */ block comments
• Trailing commas — in objects and arrays, so diffs stay clean when you add a line
• Unquoted object keys — as long as they're valid JavaScript identifiers
• Single-quoted strings — in addition to double-quoted
• Multi-line strings — using a backslash line continuation
• Extra numeric forms — leading/trailing decimal points, hexadecimal, Infinity, NaN, and a leading + sign

Here's the same configuration written first as strict JSON, then as JSON5:

// Strict JSON — no comments allowed, this is illustrative only
{
  "name": "my-app",
  "port": 8080,
  "features": ["auth", "logging"],
  "debug": false
}

// JSON5 — comments and trailing commas are fine
{
  // Server configuration
  name: 'my-app',
  port: 8080,
  features: [
    'auth',
    'logging', // trailing comma is OK
  ],
  debug: false, // also OK here
}

The JSON5 version is shorter to type, easier to diff in version control (trailing commas mean adding a line doesn't touch the line above it), and self-documenting via comments — none of which strict JSON supports.

Where JSON5 Is Actually Used

JSON5 rarely appears on the wire between client and server — strict JSON remains the standard for APIs. Its real home is configuration:

• Babel accepts .babelrc as JSON5 as well as strict JSON
• ESLint config files support JSON5-style comments
• VS Code's settings.json and tasks.json use a JSON-with-comments variant in the same spirit
• WebStorm/IntelliJ run configurations and various build tool manifests

The pattern is consistent: any file a human is expected to open, read, and edit by hand is a good JSON5 candidate. Any file exchanged purely between programs should stay as strict JSON, because strict JSON has near-universal, zero-ambiguity parser support.

Parsing JSON5 in Node.js

Node's built-in JSON.parse only accepts strict JSON — comments and trailing commas throw a SyntaxError. Use the json5 npm package instead:

npm install json5

const JSON5 = require('json5');
const fs = require('fs');

const raw = fs.readFileSync('config.json5', 'utf8');
const config = JSON5.parse(raw);

console.log(config.name); // 'my-app'

// JSON5 can also stringify back out, optionally without quoting keys
const text = JSON5.stringify(config, null, 2);

The API deliberately mirrors the built-in JSON object (JSON5.parse, JSON5.stringify), so swapping strict JSON parsing for JSON5 parsing in an existing codebase is usually a one-line change.

Parsing JSON5 in Python

Python's standard library json module is strict as well. The json5 PyPI package fills the same gap:

pip install json5

import json5

with open('config.json5') as f:
    config = json5.load(f)

print(config['name'])  # 'my-app'

An alternative worth knowing about: Python's own json module already tolerates some non-strict input if you pass parse_constant, but it does not support comments or trailing commas — for those you still need the dedicated json5 package.

JSON5 vs YAML vs TOML for Config Files

JSON5 isn't the only human-friendly config format. Here's how the three most common options compare:

• JSON5 — closest to JSON, easiest to generate programmatically and to parse with existing JSON-shaped tooling, but less readable for deeply nested structures than YAML
• YAML — most human-readable for deep nesting, supports comments and anchors/references, but whitespace-sensitivity is a common source of subtle bugs
• TOML — favored by Rust (Cargo.toml) and Python (pyproject.toml) tooling, explicit and unambiguous, but more verbose for deeply nested data

If your project's config already round-trips through JSON elsewhere (build tools, IDE integrations, JSON Schema validation), JSON5 is usually the path of least resistance since your existing JSON tooling largely still applies. If deep nesting and human authorship are the priority, YAML tends to win.

Things to Watch Out For

JSON5's flexibility comes with a few sharp edges:

• Not a wire format — don't send JSON5 over HTTP APIs; strict JSON is universally supported, JSON5 parsers are not guaranteed to exist on the receiving end
• Unquoted keys follow JS identifier rules — a key like "content-type" (with a hyphen) still needs quotes
• NaN and Infinity aren't valid JSON — if you round-trip a JSON5 file that uses them through a strict JSON parser elsewhere in your pipeline, it will fail
• Tooling support varies — always confirm the specific library or CLI tool you're feeding a JSON5 file into actually documents JSON5 support, rather than assuming a lenient JSON parser handles the full spec

Summary

JSON5 keeps JSON's simple, JavaScript-object-literal-like structure while removing the friction of hand-editing: comments explain intent, trailing commas keep diffs clean, and unquoted keys reduce visual noise. It's the right choice for configuration files that developers read and edit directly — Babel configs, build manifests, editor settings — but it should stay out of your network API responses, where strict JSON remains the universal, unambiguous standard.

Need to convert a JSON5 config down to strict JSON, or just validate the underlying structure? JSON Formatter Hub formats and validates entirely in your browser — free, no uploads (strip comments and trailing commas first, since it validates strict JSON).