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).

What Is JSON5?

JSON5 is an extension of JSON that incorporates features from ECMAScript 5.1, including unquoted keys, trailing commas, single-quoted strings, comments, and hexadecimal numbers. It is maintained by the community and designed to make hand-written configuration files more readable and forgiving than strict JSON.

What Is JSONC?

JSONC (JSON with Comments) is a minimal extension of standard JSON that adds support for single-line (//) and multi-line (/* */) comments, plus trailing commas. Maintained by Microsoft, it is the native format for VS Code settings, tsconfig.json, and other TypeScript configuration files.

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.

Real-World Configuration Files

JSON5 and JSONC are already widely used in configuration files you encounter daily. Here are concrete examples:

TypeScript (tsconfig.json — JSONC)

{
  // Strict mode catches more bugs at compile time
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "outDir": "./dist",
    // Path aliases for cleaner imports
    "paths": {
      "@/*": ["./src/*"],
      "@tests/*": ["./tests/*"],
    },
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
}

TypeScript’s tsconfig.json uses JSONC natively — comments and trailing commas work out of the box. This is one of the most common JSONC files in any JavaScript/TypeScript project.

ESLint Flat Config (eslint.config.json — JSONC)

{
  "rules": {
    // Warn on console.log, but allow console.error
    "no-console": ["warn", { "allow": ["error", "warn"] }],
    "semi": ["error", "always"],
    "quotes": ["error", "double"],
  }
}

Babel (babel.config.json5 — JSON5)

{
  // Single quotes and unquoted keys make it more readable
  presets: [
    ['@babel/preset-env', {
      targets: '> 0.25%, not dead',
      modules: false,  // Let bundler handle modules
    }],
  ],
  plugins: [
    '@babel/plugin-transform-runtime',
  ],
}

VS Code Workspace Settings (.vscode/settings.json — JSONC)

{
  // Editor preferences
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,

  // Language-specific overrides
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
  },
}

Practical Tips & Caveats

1. Convert before production

Browsers still require strict JSON for JSON.parse. Use build-step tooling to strip comments and trailing commas:

// Node.js build script: convert JSON5 config to strict JSON
import JSON5 from 'json5';
import { readFileSync, writeFileSync } from 'fs';

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

For bundlers, use rollup-plugin-json5 or vite-plugin-json5 to handle the conversion automatically during the build.

2. Security & reliability

Leniency can hide rogue fields. Always validate configuration with JSON Schema or zod before consuming it:

// Validate config shape with zod after parsing
import { z } from 'zod';
import JSON5 from 'json5';

const ConfigSchema = z.object({
  port: z.number().min(1).max(65535),
  host: z.string(),
  debug: z.boolean().default(false),
});

const raw = JSON5.parse(readFileSync('config.json5', 'utf8'));
const config = ConfigSchema.parse(raw); // Throws if invalid

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.
Use .editorconfig to enforce consistent indentation across JSON, JSON5, and JSONC files.

4. Performance

Parsing JSON5/JSONC adds dependencies and slight overhead — fine for CLI & dev tooling, but measure for prod. The json5 npm package is ~8 KB minified, and parsing is roughly 2-5x slower than native JSON.parse. For configuration files loaded once at startup, this is negligible. For hot paths parsing thousands of objects per second, stick to strict JSON.

Frequently Asked Questions

What is the difference between JSON5 and JSONC?

JSON5 extends JSON with JavaScript-like syntax: unquoted keys, trailing commas, single-line and block comments, hex numbers, and multiline strings. JSONC is simpler — it only adds single-line (//) and block (/* */) comments to standard JSON. Choose JSONC for config files where comments suffice; choose JSON5 when you need richer syntax.

Can I use JSON5 or JSONC in production APIs?

No — JSON5 and JSONC are designed for configuration files, not data interchange. APIs should use standard JSON (RFC 8259) for maximum interoperability. Reserve JSON5/JSONC for local config files like tsconfig.json, .vscode/settings.json, or environment configuration where human readability matters more than machine parsing.

Does VS Code support JSON5 natively?

VS Code supports JSONC natively (its own settings files use JSONC), but does not support JSON5 out of the box. For JSON5, install a dedicated extension like “JSON5 syntax” from the VS Code marketplace. You can also associate .json5 files with the JSON5 language mode in your settings.

How do I convert JSON5 to standard JSON?

Use the json5 npm package: JSON5.parse() reads JSON5, then JSON.stringify() outputs standard JSON. For CLI usage, run npx json5 < input.json5 > output.json. Online tools like our JSON Formatter can also validate the converted output to ensure correctness.

Is JSONC the same as JSON with Comments?

Yes — JSONC stands for “JSON with Comments” and is the format used by VS Code, TypeScript (tsconfig.json), and other Microsoft tools. It follows the standard JSON spec with the sole addition of // and /* */ comments. Parsers strip comments before processing, so the resulting data structure is identical to standard JSON.

For more browser-based developer tools including Base64 encoding, hash generation, and timestamp conversion, see our Essential Developer Tools Guide.

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.

From JSON5 to JSONC: A More Forgiving JSON Formatting Guide