Frequently Asked Questions

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.

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

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

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

Use the official json5 npm package:

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

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.

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.

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

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.

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.

Parse with JSON5, stringify with JSON:

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

JSON5 allows object keys without quotes if they are valid ECMAScript 5.1 identifiers:

Keys must start with a letter, underscore, or dollar sign, followed by letters, digits, underscores, or dollar signs.

Yes! JSON5 supports multi-line strings using a backslash at the end of each line:

The backslash and newline are removed from the resulting string. This is useful for long text that would be hard to read on a single line.

JSON5 supports hexadecimal number literals using the 0x prefix, just like JavaScript:

Hex values are parsed as regular numbers. This is especially useful for color codes, bit flags, and permissions.

JSON5 supports JavaScript's special number values that standard JSON cannot represent:

• Infinity and -Infinity - For unbounded values
• NaN - "Not a Number" for invalid calculations
• Leading/trailing decimals - .5 and 5. are valid
• Positive sign - +1 is explicitly positive

the json5 package includes TypeScript type definitions. Install and use it with full type safety:

Note: tsconfig.json already supports JSON5 comments natively - no extra setup needed for TypeScript config files.

No, browsers only have native support for standard JSON via JSON.parse(). To use JSON5 in browsers, you need to include the json5 library:

• NPM + bundler - npm install json5 then import
• CDN - Include via unpkg or jsDelivr
• ES modules - Import directly in modern browsers

The library is small (~8KB minified) and has no dependencies, making it suitable for browser use.

Yes! JSON5 works with all JavaScript frameworks. Common use cases:

• Configuration files - Many bundlers support JSON5 configs
• Static data - Import JSON5 files with appropriate loaders
• Runtime parsing - Use the json5 library in your code

For webpack, use json5-loader. Vite and other modern bundlers often have JSON5 support built-in or via plugins.

Several options for validating JSON5:

• Editor extensions - VS Code with JSON5 extension provides live validation
• Online tools - Use transform.tools to check syntax
• Programmatic - Wrap JSON5.parse() in try/catch
• CLI - Use the json5 CLI tool: npx json5 --validate file.json5

JSON5 files are typically the same size or slightly smaller than equivalent JSON:

• Unquoted keys - Save 2 characters per key
• Single quotes - Same size as double quotes
• Comments - Add size but improve maintainability

The json5 library itself is ~8KB minified, ~3KB gzipped. For config files loaded once at startup, this is negligible.

Yes, JSON5 is excellent for environment configs. Benefits over .env files:

• Nested structures - Organize related settings
• Comments - Document each setting's purpose
• Type preservation - Numbers and booleans stay typed
• Arrays - List values without string splitting

Many projects use config.json5 for local development with environment-specific overrides.

Migration is simple since JSON5 is a superset of JSON:

1. Rename - Change extension from .json to .json5 (optional)
2. Update parser - Use JSON5.parse() instead of JSON.parse()
3. Add features gradually - Start adding comments, trailing commas as needed

Your existing JSON files work immediately - no conversion needed. Add JSON5 features only where they improve readability.

No, JSON5 does not have a native date type - same as standard JSON. Dates should be represented as:

• ISO 8601 strings - "2026-01-15T10:30:00Z"
• Unix timestamps - 1736937000 (seconds or milliseconds)

Use a reviver function with JSON5.parse() to automatically convert date strings to Date objects if needed.

Unquoted keys must be valid ECMAScript 5.1 identifiers:

• Start with - Letter (a-z, A-Z), underscore (_), or dollar sign ($)
• Followed by - Letters, digits (0-9), underscores, or dollar signs
• Unicode - Unicode letters and escape sequences are allowed

Keys with hyphens, spaces, or starting with numbers must be quoted: "my-key", "with spaces", "123start"

Use JSON5.stringify() with the space parameter:

Note: JSON5.stringify() outputs valid JSON by default. Use the quote option for single quotes.

JSON5 is as safe as JSON - it's a data format, not executable code:

• No code execution - Unlike eval(), JSON5.parse() cannot run code
• No prototype pollution - The official library is safe from __proto__ attacks
• Comments are stripped - They don't affect the parsed data

Never use eval() to parse JSON5. Always use the json5 library's parse() method for untrusted input.