The JSON6 Specification

JSON6 is a data format that extends JSON in the same spirit as JSON5, but further. It is not an RFC, an ECMA standard or a W3C recommendation, and it makes no claim to be. The project README says so directly: JSON6 is "not an official successor to JSON", and JSON6 content "may not work with existing JSON parsers", which is why files use their own extension, .json6. The README also lists a new MIME type as a to-do, so there is no registered media type for JSON6 today.

The practical consequence is that "the spec" is a living pair of artifacts: the feature list in the README.md of the json-6 npm package, and the parser source in lib/json6.js. This reference follows a simple rule that the README itself would endorse. When the two disagree, the code wins, because the code is what actually accepts or rejects your file. Every claim on the six specification pages was checked by running json-6 1.1.7 under Node.js, and every place where the code differs from the documentation or from what you might expect is called out in a note.

JSON6 adds no new data types. A JSON6 document still produces the same six kinds of value as JSON (object, array, string, number, boolean, null) plus the JavaScript undefined value, and numbers are still IEEE 754 double-precision floats. All of the additions are about how those values are written down, not about what they can hold. That is the main difference from its sibling format JSOX, covered below.

How this specification is organized

• Syntax: whitespace, comments, keywords, document structure and a grammar summary.
• Strings: the three quote styles, multi-line strings, every escape sequence, and what happens to unknown escapes.
• Numbers: decimal, hexadecimal, octal, binary, underscores, signs, Infinity, NaN and precision limits.
• Objects and arrays: key forms, keyword keys, duplicate keys, trailing commas and empty array members.
• JSON5 differences: an exhaustive comparison and what breaks when you move files between the two formats.

The README states the motivation plainly: JSON is a good data format, but it is not friendly to write. Keys need quotes, objects and arrays cannot have trailing commas, and comments are forbidden, "even though none of these are the case with regular JavaScript today." JSON has grown from a machine format into one that humans edit: configuration files, manifests and test fixtures. The goals that follow from that are visible all through the grammar.

• Stay close to JSON and JavaScript. The README contrasts JSON6 with YAML: moving to a completely different format is undesirable in many cases, so JSON6 aims to "remain close to JSON and JavaScript." The README says JSON6 "works with all existing JSON content", and the differences page lists the few places where the reverse is not true.
• Be forgiving to humans. Leading zeros that align columns, literal newlines inside quoted strings, punctuation in unquoted keys such as content-type, and stray signs are all accepted by default. The README has a section titled "Why the default is not strict" that defends each one.
• Mean what Number() means. The README's rule for numbers is that "a numeric token means what Number() says it means," which is why 0123 is 123 and not octal 83.
• Add no new data types. The additions are syntax only.
• Offer an opt-in strict mode. Since 1.1.6 the esStrictCompatible option narrows the grammar to a subset of ECMAScript strict mode, so a document that parses can be pasted into a module unchanged.

The json-6 package exports a JSON6 object that mirrors the native JSON object. The module object exposes exactly these members, verified by listing its keys: parse, stringify, escape, begin, stringifier, stringifierActive and version.

The four parse options are all off by default, which means that out of the box the parser accepts the full historical grammar. They are esStrictCompatible, forbidTemplateSubstitution, normalizeNumericKeys and warnWithCommentWithoutEOL. Each is covered where it matters: on the strings, numbers and objects and arrays pages. An option name that json-6 does not know is silently ignored, so a typo in an option name disables the check without any error.

For Node.js there is a require('json-6/lib/require') hook that registers the .json6 extension, an ES module loader started with node --import json-6/lib/register.mjs (Node 20.6 or newer), an older --experimental-loader json-6/lib/import.mjs form, and a json-6 -c file.json6 command-line converter that writes a sibling .json file. TypeScript declarations ship in the package. Task-oriented guides are on the Node.js, TypeScript and CLI pages.

Running the parser against the README turned up behavior that the documentation does not mention or only partly describes. None of these is a reason to avoid JSON6, but each is worth knowing before you build on it. They are repeated on the relevant pages.

• parse() ignores everything after the first value. JSON6.parse("1 2") returns 1, JSON6.parse("[1] x") returns [1] and JSON6.parse("[1,2]]") returns [1,2] with no error. JSON5 throws for all three. Use JSON6.begin to read several values.
• The key __proto__ changes the result's prototype. JSON6.parse("{__proto__:{x:1}}") returns an object with no own keys whose inherited x is 1. JSON5 creates an ordinary own property instead. This affects only the parsed object, not Object.prototype, but do not merge untrusted JSON6 into other objects without a guard.
• A bare backslash plus carriage return continuation is mis-parsed. A backslash followed by a lone CR (no LF) and then a letter treats that letter as an escape, so "a\<CR>b" gives a backspace character. Backslash plus LF or CRLF works correctly.
• stringify drops toJSON. JSON6.stringify({d: new Date(0)}) gives {d:{}}. Dates, Maps and Sets all become empty objects, unlike native JSON.stringify and JSON5.stringify.
• stringify output is not JSON. It emits unquoted keys, escapes the single quote, back-tick and so on, writes literal newlines inside strings, and sorts keys by default. Never send it to a consumer that expects JSON. Use JSON.stringify for that.
• Unquoted-key escapes are not decoded. {a\u0062: 1} produces the key a\u0062, not ab. JSON5 would decode it.
• Only some Unicode spaces count as whitespace. NBSP, BOM, VT, FF, U+2028 and U+2029 are accepted, but the em space U+2003 and the ideographic space U+3000 are rejected, although JSON5 and ECMAScript accept them.

See Also