Frequently Asked Questions

Q: What is JSON5?

JSON5 is a superset of JSON that adds human-friendly features from ECMAScript 5.1: comments (// and /* */), trailing commas, unquoted object keys, single-quoted strings, hexadecimal numbers, Infinity, NaN, and multi-line strings. Every valid JSON file is automatically valid JSON5.

Q: Is JSON5 backward compatible with JSON?

Yes, 100% backward compatible. JSON5 is a strict superset of JSON - every valid JSON document is also valid JSON5. You can rename .json files to .json5 without changes and gradually adopt JSON5 features.

Q: How do I add comments in JSON5?

JSON5 supports JavaScript-style comments: single-line comments with // and multi-line comments with /* */. Comments can appear anywhere in the file, including inline after values.

Q: How do I parse JSON5 in JavaScript/Node.js?

Install the official json5 npm package (npm install json5), then use JSON5.parse() to parse JSON5 strings and JSON5.stringify() to convert objects. The API mirrors native JSON methods.

Q: What's the difference between JSON5 and JSONC?

JSONC (JSON with Comments) only adds comment support. JSON5 includes comments plus: trailing commas, unquoted keys, single-quoted strings, multi-line strings, hex numbers, Infinity, and NaN. JSON5 is more feature-rich.

Q: Is JSON5 slower than JSON?

Yes, but negligibly for config files. Native JSON.parse() is faster since it's built into JavaScript engines. For configuration loaded once at startup, the difference is milliseconds. Use standard JSON for high-frequency API parsing.

Q: Should I use .json5 or .json file extension?

Use .json5 when using JSON5-specific features (comments, trailing commas) for proper syntax highlighting. Keep .json for compatibility with tools expecting standard JSON or when only using comment-style JSON5 (like tsconfig.json).

Q: Can I use JSON5 for package.json?

No, npm requires standard JSON. However, many config files support JSON5: tsconfig.json (comments), babel.config.json5, .eslintrc.json5, and any custom configs you parse with the json5 library.

Q: Is JSON5 an official standard?

JSON5 is not an ECMA or IETF standard, but has a well-defined specification at json5.org, a stable reference implementation with millions of weekly npm downloads, and wide adoption in TypeScript, Babel, ESLint, and other major tools.

Q: When should I NOT use JSON5?

Use standard JSON for: API responses (machine-to-machine), database storage, public interfaces expecting JSON, and performance-critical high-frequency parsing. JSON5 is best for human-edited files: configs, test fixtures, localization.

Question 1

What is JSON5?

Answer

JSON5 is an extension of JSON that aims to make it easier for humans to write and maintain by hand. It adds features from ECMAScript 5.1 including comments, trailing commas, unquoted object keys, single-quoted strings, hexadecimal numbers, and more.

JSON5 is a superset of JSON, meaning every valid JSON file is automatically valid JSON5. This makes adoption simple - you can start with existing JSON files and gradually add JSON5 features as needed.

Question 2

Is JSON5 backward compatible with JSON?

Answer

Yes, 100%. JSON5 is a strict superset of JSON. Every valid JSON document is also a valid JSON5 document. This means you can:

Rename your .json files to .json5 without any changes
Start using JSON5 features gradually
Mix JSON and JSON5 syntax in the same file

Question 3

How do I add comments in JSON5?

Answer

JSON5 supports both single-line and multi-line comments, just like JavaScript:

// This is a single-line comment { name: 'my-app', // Inline comment /* This is a multi-line comment */ version: '1.0.0', }

Question 4

What are trailing commas and why do they matter?

Answer

Trailing commas are commas after the last item in an array or object. In standard JSON, they cause a syntax error. In JSON5, they're allowed.

This matters because:

Cleaner git diffs - Adding a new item only shows one line changed
Easier editing - No need to fix commas when reordering items
Fewer errors - Copy-paste operations don't break syntax

Question 5

How do I parse JSON5 in JavaScript/Node.js?

Answer

Use the official json5 npm package:

// Install: npm install json5 import JSON5 from 'json5'; // Parse JSON5 const obj = JSON5.parse(`{ name: 'app', // comment allowed version: '1.0', }`); // Stringify (outputs standard JSON) const json = JSON5.stringify(obj, null, 2);

Question 6

Can I use JSON5 for package.json?

Answer

No, npm and Node.js require package.json to be standard JSON. However, you can use JSON5 for:

tsconfig.json - TypeScript supports comments (JSON5 subset)
babel.config.json5 - Babel has native JSON5 support
eslint.config.json5 - ESLint supports JSON5 configs
Custom config files - Any config you parse yourself

Question 7

What's the difference between JSON5 and JSONC?

Answer

JSONC (JSON with Comments) only adds comment support to JSON. JSON5 includes comments plus many more features:

Trailing commas in arrays and objects
Unquoted object keys
Single-quoted strings
Multi-line strings
Hexadecimal numbers, Infinity, and NaN

If you only need comments, JSONC is simpler. If you want a more human-friendly format overall, JSON5 is the better choice.

Question 8

Is JSON5 slower than JSON?

Answer

Yes, but typically it doesn't matter. Native JSON.parse() is faster because it's built into JavaScript engines. JSON5 parsing requires a JavaScript library.

For configuration files loaded once at startup, the difference is negligible (a few milliseconds). For high-frequency parsing (like API responses), stick with standard JSON.

Question 9

Should I use .json5 or .json extension?

Answer

Use .json5 when:

You want editor syntax highlighting
You're using JSON5-specific features
You want to make it clear the file uses JSON5

Keep .json when:

The consuming tool expects .json
You're only using comments (tsconfig.json style)
Backward compatibility is important

Question 10

Is JSON5 an official standard?

Answer

JSON5 is not an ECMA or IETF standard like JSON. However, it has:

A well-defined specification
A reference implementation with millions of weekly downloads
Wide adoption in popular tools (TypeScript, Babel, ESLint)

JSON5 has been stable since 2012 and is widely trusted for configuration files.

Question 11

When should I NOT use JSON5?

Answer

Stick with standard JSON for:

API responses - Machine-to-machine communication
Database storage - Data that won't be hand-edited
Public interfaces - When consumers expect JSON
Performance-critical parsing - High-frequency operations

Use JSON5 for human-facing files like configuration, test fixtures, and localization.

Question 12

How do I convert JSON5 to JSON?

Answer

Parse with JSON5, stringify with JSON:

import JSON5 from 'json5'; // JSON5 input (with comments, etc.) const json5String = `{ name: 'app', /* comment */ }`; // Parse as JSON5, output as JSON const obj = JSON5.parse(json5String); const jsonString = JSON.stringify(obj, null, 2); // Result: {"name": "app"}

You can also use online tools like transform.tools for quick conversions.