JSON5 — JSON for Humans with Comments and Trailing Commas

Introduction

JSON5 is a data interchange format that extends JSON with syntax features from ECMAScript 5.1. It supports comments, trailing commas, unquoted property names, single-quoted strings, and other human-friendly features that standard JSON forbids. JSON5 is widely used for configuration files where developers need to annotate settings without resorting to separate documentation.

What JSON5 Does

• Parses and stringifies JSON5 data with a drop-in API matching JSON.parse() and JSON.stringify()
• Allows single-line and multi-line comments in data files
• Supports trailing commas in arrays and objects for cleaner diffs
• Permits unquoted object keys that are valid ECMAScript identifiers
• Accepts single-quoted strings, multi-line strings, hexadecimal numbers, and special float values

Architecture Overview

JSON5 implements a hand-written recursive descent parser that tokenizes input according to the JSON5 specification. The parser handles all ES5 identifier rules for unquoted keys and supports the full Unicode character set. The stringify function mirrors JSON.stringify with the same replacer and space arguments. The library is pure JavaScript with no dependencies and works in Node.js and browsers.

Self-Hosting & Configuration

• Install via npm: npm install json5
• Use JSON5.parse() and JSON5.stringify() as drop-in replacements for JSON methods
• A CLI tool is included for converting between JSON and JSON5: npx json5 config.json5
• Register a require hook for Node.js to load .json5 files directly: require('json5/lib/register')
• Works in Node.js 6+ and all modern browsers

Key Features

• Comments: both // single-line and /* */ multi-line comments are valid
• Trailing commas: arrays and objects can have a comma after the last element
• Unquoted keys: property names that are valid identifiers do not need quotes
• Flexible strings: single quotes, escaped newlines, and hexadecimal escapes are supported
• Extended numbers: hexadecimal literals, leading/trailing decimal points, Infinity, and NaN

Comparison with Similar Tools

• JSONC — JSON with Comments only; JSON5 adds trailing commas, unquoted keys, and more syntax features
• YAML — Full-featured human-readable format; JSON5 stays closer to JSON syntax with fewer surprises
• TOML — Configuration-focused format; JSON5 is familiar to JavaScript developers and has simpler nesting
• Hjson — Human JSON with multiline strings; JSON5 follows the ECMAScript spec more strictly
• Standard JSON — Strictest interchange format; JSON5 is not intended for machine-to-machine APIs

FAQ

Q: Should I use JSON5 for API responses? A: No. JSON5 is designed for human-authored files like configuration. For API interchange, standard JSON is the right choice because every language and tool supports it.

Q: Is JSON5 supported by TypeScript and bundlers? A: Many tools support JSON5 natively or via plugins. Webpack can load .json5 files with json5-loader. TypeScript does not parse JSON5 directly but you can use the library at runtime.

Q: How does JSON5 compare to JSONC used by VS Code? A: JSONC (JSON with Comments) only adds comment support. JSON5 is a broader superset that also adds trailing commas, unquoted keys, and other syntax relaxations.

Q: Can I convert JSON5 to standard JSON? A: Yes. Parse with JSON5.parse() and then JSON.stringify() the result. The CLI tool also supports this conversion.

Sources

• https://github.com/json5/json5
• https://json5.org/