Specification
The complete JSON5 specification reference. Authoritative documentation for implementers and users.
TL;DR: JSON5 is an extension to JSON that aims to make it easier for humans to write and maintain by hand. It does this by adding minimal syntactic features directly from ECMAScript 5.1 while maintaining full backward compatibility with JSON.
Specification Overview
JSON5 (JSON5 Data Interchange Format) is a proposed extension to JSON that aims to make it easier for humans to write and maintain by hand. It accomplishes this by adding minimal syntactic features directly from ECMAScript 5.1, hence the name "JSON5."
The JSON5 specification was created to address the limitations of JSON when used as a configuration format. While JSON is excellent for machine-to-machine data interchange, it can be cumbersome for humans due to its strict syntax requirements: no comments, no trailing commas, and mandatory double-quoted strings.
Brief History
JSON5 was created by Aseem Kishore in 2012 and has since grown to become one of the most widely-used JSON extensions. The specification is maintained as an open-source project with contributions from the community.
- 2012: Initial release of JSON5
- 2018: Version 2.0 with modernized implementation
- Today: 65+ million weekly npm downloads
What JSON5 Adds to JSON
JSON5 extends JSON with the following features borrowed from ECMAScript 5.1:
Objects
- Unquoted property names
- Single-quoted strings
- Trailing commas
Arrays
- Trailing commas
Strings
- Single quotes
- Multi-line strings
- Escaped newlines
Numbers
- Hexadecimal literals
- Leading/trailing decimal points
- Infinity and NaN
- Explicit plus sign
Comments
- Single-line comments (
//) - Multi-line comments (
/* */)
Design Goals
The JSON5 specification was designed with specific goals in mind, balancing human readability with machine parseability.
Human-Friendly
The primary goal of JSON5 is to make configuration files easier to write and maintain by hand. Comments allow developers to document settings, trailing commas reduce diff noise, and flexible syntax reduces friction.
Backward Compatible
Every valid JSON document is automatically valid JSON5. This means existing JSON files work without modification, and teams can adopt JSON5 features gradually without breaking changes.
Minimal Extensions
JSON5 only adds features that are clearly useful and come directly from ECMAScript 5.1. It avoids adding features that would complicate parsing or introduce ambiguity. No new features are invented.
Deterministic Parsing
JSON5 maintains deterministic parsing behavior. The same input always produces the same output. There are no features that depend on implementation-specific behavior.
Subset of ECMAScript
All JSON5 syntax is valid ECMAScript 5.1 syntax. This means JSON5 documents can be evaluated as JavaScript objects (though this is not recommended for untrusted data for security reasons).
Complete Feature Summary
This section provides a complete summary of all JSON5 features with examples. For detailed syntax rules, see the Syntax Reference.
Comments
JSON5 supports both single-line and multi-line comments, matching JavaScript comment syntax.
{ // This is a single-line comment name: 'my-app', /* This is a multi-line comment that spans multiple lines */ version: '1.0.0', debug: true, // Inline comment }Object Keys
Object keys may be unquoted if they are valid ECMAScript 5.1 identifiers. Keys can also use single quotes.
{ unquoted: 'valid identifier', 'single-quoted': 'with special chars', "double-quoted": 'also valid', $dollar: 'starts with $', _underscore: 'starts with _', } Valid identifiers start with a letter, underscore (_), or dollar sign ($), followed by letters, digits, underscores, or dollar signs.
Strings
Strings can be single-quoted or double-quoted. Strings can span multiple lines using backslash escapes.
{ double: "double-quoted string", single: 'single-quoted string', nested: 'contains "double" quotes', multiline: 'line one \ line two \ line three', }Numbers
Numbers can be hexadecimal, can have leading or trailing decimal points, and can include Infinity and NaN.
{ integer: 42, negative: -17, decimal: 3.14159, hexadecimal: 0xFF, leadingDecimal: .5, trailingDecimal: 5., positiveSign: +10, infinity: Infinity, negativeInfinity: -Infinity, notANumber: NaN, }Trailing Commas
Arrays and objects can have trailing commas after the last element. This makes adding and removing items cleaner in version control.
{ array: [ 'one', 'two', 'three', // trailing comma ], object: { a: 1, b: 2, c: 3, // trailing comma }, }White Space
JSON5 allows additional white space characters beyond those permitted in JSON, matching ECMAScript 5.1.
| Character | Unicode | Name |
|---|---|---|
\t | U+0009 | Horizontal Tab |
\n | U+000A | Line Feed |
\v | U+000B | Vertical Tab |
\f | U+000C | Form Feed |
\r | U+000D | Carriage Return |
| (space) | U+0020 | Space |
| U+00A0 | No-Break Space | |
| U+2028 | Line Separator | |
| U+2029 | Paragraph Separator | |
| U+FEFF | Byte Order Mark |
Compatibility
JSON Compatibility
JSON5 is a strict superset of JSON. This means:
- Every valid JSON document is also a valid JSON5 document
- Existing JSON files can be renamed to
.json5and parsed without modification - JSON5 parsers can read all JSON content
Note: While JSON5 can parse JSON, JSON parsers cannot parse JSON5-specific syntax (comments, trailing commas, etc.). If you need to output data for a JSON consumer, use JSON.stringify().
ECMAScript Compatibility
All JSON5 syntax is valid ECMAScript 5.1 syntax. A JSON5 document can be evaluated as a JavaScript expression. However, this is not recommended for untrusted data due to security concerns.
Security Warning
Never use eval() to parse JSON5 from untrusted sources. Always use a proper JSON5 parser like the official json5 npm package.
Specification Sections
Explore detailed documentation for each aspect of the JSON5 specification.
Syntax Reference
Complete syntax rules for JSON5 including objects, arrays, strings, numbers, and literals.
Data Types
In-depth coverage of all JSON5 data types: objects, arrays, strings, numbers, booleans, and null.
Formal Grammar
The complete formal grammar specification in ABNF and railroad diagrams for implementers.
ECMAScript Relationship
How JSON5 relates to ECMAScript 5.1 and the rationale behind feature selection.
Ready to Implement?
Check out language-specific guides or dive into the syntax details.