JSON5

JSON5 is a proposed extension to JSON that aims to make it easier for
humans to write and maintain by hand. It does this by adding some minimal
syntax features directly from ECMAScript 5.

JSON5 remains a strict subset of JavaScript, adds no new data types,
and works with all existing JSON content.

JSON5 is not an official successor to JSON, and JSON5 content may not
work with existing JSON parsers. For this reason, JSON5 files use a new .json5
extension. (TODO: new MIME type needed too.)

The code here is a reference JavaScript implementation for both Node.js
and all browsers. It's based directly off of Douglas Crockford's own JSON
implementation, and it's both robust and secure.

Why

JSON isn't the friendliest to write. Keys need to be quoted, objects and
arrays can't have trailing commas, and comments aren't allowed — even though
none of these are the case with regular JavaScript today.

That was fine when JSON's goal was to be a great data format, but JSON's usage
has expanded beyond machines. JSON is now used for writing configs,
manifests, even tests — all by humans.

There are other formats that are human-friendlier, like YAML, but changing
from JSON to a completely different format is undesirable in many cases.
JSON5’s aim is to remain close to JSON and JavaScript.

Features

The following is the exact list of additions to JSON's syntax introduced by
JSON5. All of these are optional, and all of these come from ES5.

Arrays

Strings

Strings can be split across multiple lines; just prefix each newline with a
backslash. [ES5 §7.8.4]

Numbers

Numbers can be hexadecimal (base 16).

Numbers can begin or end with a (leading or trailing) decimal point.

Numbers can include Infinity, -Infinity, NaN, and -NaN.

Numbers can begin with an explicit plus sign.

Comments

Both inline (single-line) and block (multi-line) comments are allowed.

Example

The following is a contrived example, but it illustrates most of the features:

{foo:'bar',while:true,this:'is a \multi-line string',// this is an inline commenthere:'is another',// inline comment/* this is a block comment that continues on another line */hex:0xDEADbeef,half:.5,delta:+10,to:Infinity,// and beyond!finally:'a trailing comma',oh:["we shouldn't forget",'arrays can have','trailing commas too',],}

// This file is written in JSON5 syntax, naturally, but npm needs a regular// JSON file, so compile via `npm run build`. Be sure to keep both in sync!{name:'json5',version:'0.4.0',description:'JSON for the ES5 era.',keywords:['json','es5'],author:'Aseem Kishore <aseem.kishore@gmail.com>',contributors:[// TODO: Should we remove this section in favor of GitHub's list?// https://github.com/aseemk/json5/contributors'Max Nanasy <max.nanasy@gmail.com>','Andrew Eisenberg <andrew@eisenberg.as>','Jordan Tucker <jordanbtucker@gmail.com>',],main:'lib/json5.js',bin:'lib/cli.js',dependencies:{},devDependencies:{mocha:'~1.0.3',// TODO: Look into Mocha v2.},scripts:{build:'./lib/cli.js -c package.json5',test:'mocha --ui exports --reporter spec',// TODO: Would it be better to define these in a mocha.opts file?},homepage:'http://json5.org/',license:'MIT',repository:{type:'git',url:'https://github.com/aseemk/json5.git',},}

Community

Join the Google Group if you're
interested in JSON5 news, updates, and general discussion.
Don't worry, it's very low-traffic.

The GitHub wiki is a good place to track
JSON5 support and usage. Contribute freely there!

GitHub Issues is the place to
formally propose feature requests and report bugs. Questions and general
feedback are better directed at the Google Group.

Usage

This JavaScript implementation of JSON5 simply provides a JSON5 object just
like the native ES5 JSON object.

To use from Node:

npm install json5

varJSON5=require('json5');

To use in the browser (adds the JSON5 object to the global namespace):

<script src="json5.js"></script>

Then in both cases, you can simply replace native JSON calls with JSON5:

JSON5.parse supports all of the JSON5 features listed above (TODO: except
Unicode), as well as the native reviver argument.

JSON5.stringify mainly avoids quoting keys where possible, but we hope to
keep expanding it in the future (e.g. to also output trailing commas).
It supports the native replacer and space arguments,
as well. (TODO: Any implemented toJSON methods aren't used today.)

Extras

If you're running this on Node, you can also register a JSON5 require() hook
to let you require().json5 files just like you can .json files:

Credits

Douglas Crockford of course designed and built
JSON, but his state machine diagrams on the JSON website,
as cheesy as it may sound, gave me motivation and confidence that building a
new parser to implement these ideas this was within my reach!
This code is also modeled directly off of Doug's open-source json_parse.js
parser. I'm super grateful for that clean and well-documented code.

Max Nanasy has been an early and prolific
supporter, contributing multiple patches and ideas. Thanks Max!