From JSON5 to JSONC: Unlocking a More Forgiving JSON Formatting Experience

When strict JSON makes you debug into the night because of one missing comma, it might be time to meet its more forgiving cousins — JSON5 and JSON with Comments (JSONC).

Why We Need “Lenient” JSON

• Readability bottlenecks: Standard JSON forbids comments, trailing commas, single quotes, etc., which hurts clarity in configs and demos.
• Team collaboration pain: Massive JSON files with zero inline notes are hard to maintain; a minor edit can break the whole file.
• DevOps realities: Kubernetes and CI/CD pipelines frequently merge or generate JSON on the fly; forgiving syntax slashes manual fixes.

JSON5 vs. JSONC at a Glance

Feature	JSON (strict)	JSON5	JSONC
// single-line comments	No	Yes	Yes
/* */ multi-line comments	No	Yes	Yes
Trailing commas	No	Yes	Yes
Single-quoted strings	No	Yes	No
Unquoted keys	No	Yes	No
Numeric signs + / -	No	Yes	No
Hex / binary numbers	No	Yes	No
Spec maintainers	ECMA	Community (A. Rauschmayer)	Microsoft / VS Code

In one sentence: JSON5 feels like a JavaScript object literal, whereas JSONC is just standard JSON plus comments.

Syntax Examples

Vanilla JSON (strict)

{
  "name": "Go Tools",
  "features": ["Base64", "JSON Formatter"]
}

JSON5 Example

// Project config
{
  name: 'Go Tools',      // single quotes & unquoted keys
  features: [
    'Base64',
    'JSON Formatter',    // trailing comma
  ],
  version: 1.0,          // non-string number allowed
}

JSONC Example

{
  // Project name
  "name": "Go Tools",
  // Feature list
  "features": [
    "Base64",
    "JSON Formatter", // trailing comma
  ]
}

Formatting & Parsing Support

Scenario	JSON5	JSONC	Recommended libs / tools
Browser	JSON5.parse() polyfill, Prettier with built-in json5 parser (>= v1.13)	VS Code settings.json native support	—
Node.js	json5 npm package	comment-json, jsonc-parser	Support CLI formatting & AST parsing
IDE	VS Code, WebStorm extensions	VS Code native, WebStorm plugin	Prettier can unify formatting
CI / Lint	eslint-plugin-json5	eslint-plugin-jsonc	Integrate with Husky & lint-staged
Online tool	Go Tools JSON Formatter (beautifies & validates JSON5/JSONC)	Same	JSON Formatter

Quick VS Code Formatting

Add to settings.json:

"[jsonc]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Then hit Alt + Shift + F to beautify any JSONC file.

Practical Tips & Caveats

1. Convert before production

• Browsers still require strict JSON for JSON.parse.
• Use rollup-plugin-json5 or custom scripts in the build step to transpile JSON5/JSONC to pure JSON.

2. Security & reliability

• Leniency can hide rogue fields; validate with JSON Schema or zod before shipping APIs.

3. Team conventions

• Declare in README that *.json5 is for configs only; release packages should ship strict .json.
• Standardize Prettier rules to avoid noisy diffs.

4. Performance

• Parsing JSON5/JSONC adds dependencies and slight overhead — fine for CLI & dev tooling, but measure for prod.

Wrap-Up

Balancing readability and rigor is a classic dev struggle. JSON5 and JSONC improve the authoring experience, and with the right build & validation pipeline, you can enjoy the perks of “lenient JSON” safely.

References

• JSON5 GitHub
• JSONC spec (VS Code)
• Prettier parser docs
• comment-json