Specification
The complete JSON6 specification reference. Authoritative documentation for implementers and users.
TL;DR: JSON6 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
JSON6 (JSON6 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 "JSON6."
The JSON6 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
JSON6 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 JSON6
- 2018: Version 2.0 with modernized implementation
- Today: 65+ million weekly npm downloads
What JSON6 Adds to JSON
JSON6 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 JSON6 specification was designed with specific goals in mind, balancing human readability with machine parseability.
Human-Friendly
The primary goal of JSON6 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 JSON6. This means existing JSON files work without modification, and teams can adopt JSON6 features gradually without breaking changes.
Minimal Extensions
JSON6 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
JSON6 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 JSON6 syntax is valid ECMAScript 5.1 syntax. This means JSON6 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 JSON6 features with examples. For detailed syntax rules, see the Syntax Reference.
Comments
JSON6 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
JSON6 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
JSON6 is a strict superset of JSON. This means:
- Every valid JSON document is also a valid JSON6 document
- Existing JSON files can be renamed to
.json6and parsed without modification - JSON6 parsers can read all JSON content
Note: While JSON6 can parse JSON, JSON parsers cannot parse JSON6-specific syntax (comments, trailing commas, etc.). If you need to output data for a JSON consumer, use JSON.stringify().
ECMAScript Compatibility
All JSON6 syntax is valid ECMAScript 5.1 syntax. A JSON6 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 JSON6 from untrusted sources. Always use a proper JSON6 parser like the official json6 npm package.
Specification Sections
Explore detailed documentation for each aspect of the JSON6 specification.
Syntax Reference
Complete syntax rules for JSON6 including objects, arrays, strings, numbers, and literals.
Data Types
In-depth coverage of all JSON6 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 JSON6 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.