1# JSON5 – JSON for Humans 2 3[![Build Status](https://travis-ci.org/json5/json5.svg)][Build Status] 4[![Coverage 5Status](https://coveralls.io/repos/github/json5/json5/badge.svg)][Coverage 6Status] 7 8The JSON5 Data Interchange Format (JSON5) is a superset of [JSON] that aims to 9alleviate some of the limitations of JSON by expanding its syntax to include 10some productions from [ECMAScript 5.1]. 11 12This JavaScript library is the official reference implementation for JSON5 13parsing and serialization libraries. 14 15[Build Status]: https://travis-ci.org/json5/json5 16 17[Coverage Status]: https://coveralls.io/github/json5/json5 18 19[JSON]: https://tools.ietf.org/html/rfc7159 20 21[ECMAScript 5.1]: https://www.ecma-international.org/ecma-262/5.1/ 22 23## Summary of Features 24The following ECMAScript 5.1 features, which are not supported in JSON, have 25been extended to JSON5. 26 27### Objects 28- Object keys may be an ECMAScript 5.1 _[IdentifierName]_. 29- Objects may have a single trailing comma. 30 31### Arrays 32- Arrays may have a single trailing comma. 33 34### Strings 35- Strings may be single quoted. 36- Strings may span multiple lines by escaping new line characters. 37- Strings may include character escapes. 38 39### Numbers 40- Numbers may be hexadecimal. 41- Numbers may have a leading or trailing decimal point. 42- Numbers may be [IEEE 754] positive infinity, negative infinity, and NaN. 43- Numbers may begin with an explicit plus sign. 44 45### Comments 46- Single and multi-line comments are allowed. 47 48### White Space 49- Additional white space characters are allowed. 50 51[IdentifierName]: https://www.ecma-international.org/ecma-262/5.1/#sec-7.6 52 53[IEEE 754]: http://ieeexplore.ieee.org/servlet/opac?punumber=4610933 54 55## Short Example 56```js 57{ 58 // comments 59 unquoted: 'and you can quote me on that', 60 singleQuotes: 'I can use "double quotes" here', 61 lineBreaks: "Look, Mom! \ 62No \\n's!", 63 hexadecimal: 0xdecaf, 64 leadingDecimalPoint: .8675309, andTrailing: 8675309., 65 positiveSign: +1, 66 trailingComma: 'in objects', andIn: ['arrays',], 67 "backwardsCompatible": "with JSON", 68} 69``` 70 71## Specification 72For a detailed explanation of the JSON5 format, please read the [official 73specification](https://json5.github.io/json5-spec/). 74 75## Installation 76### Node.js 77```sh 78npm install json5 79``` 80 81```js 82const JSON5 = require('json5') 83``` 84 85### Browsers 86```html 87<script src="https://unpkg.com/json5@^1.0.0"></script> 88``` 89 90This will create a global `JSON5` variable. 91 92## API 93The JSON5 API is compatible with the [JSON API]. 94 95[JSON API]: 96https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON 97 98### JSON5.parse() 99Parses a JSON5 string, constructing the JavaScript value or object described by 100the string. An optional reviver function can be provided to perform a 101transformation on the resulting object before it is returned. 102 103#### Syntax 104 JSON5.parse(text[, reviver]) 105 106#### Parameters 107- `text`: The string to parse as JSON5. 108- `reviver`: If a function, this prescribes how the value originally produced by 109 parsing is transformed, before being returned. 110 111#### Return value 112The object corresponding to the given JSON5 text. 113 114### JSON5.stringify() 115Converts a JavaScript value to a JSON5 string, optionally replacing values if a 116replacer function is specified, or optionally including only the specified 117properties if a replacer array is specified. 118 119#### Syntax 120 JSON5.stringify(value[, replacer[, space]]) 121 JSON5.stringify(value[, options]) 122 123#### Parameters 124- `value`: The value to convert to a JSON5 string. 125- `replacer`: A function that alters the behavior of the stringification 126 process, or an array of String and Number objects that serve as a whitelist 127 for selecting/filtering the properties of the value object to be included in 128 the JSON5 string. If this value is null or not provided, all properties of the 129 object are included in the resulting JSON5 string. 130- `space`: A String or Number object that's used to insert white space into the 131 output JSON5 string for readability purposes. If this is a Number, it 132 indicates the number of space characters to use as white space; this number is 133 capped at 10 (if it is greater, the value is just 10). Values less than 1 134 indicate that no space should be used. If this is a String, the string (or the 135 first 10 characters of the string, if it's longer than that) is used as white 136 space. If this parameter is not provided (or is null), no white space is used. 137 If white space is used, trailing commas will be used in objects and arrays. 138- `options`: An object with the following properties: 139 - `replacer`: Same as the `replacer` parameter. 140 - `space`: Same as the `space` parameter. 141 - `quote`: A String representing the quote character to use when serializing 142 strings. 143 144#### Return value 145A JSON5 string representing the value. 146 147### Node.js `require()` JSON5 files 148When using Node.js, you can `require()` JSON5 files by adding the following 149statement. 150 151```js 152require('json5/lib/register') 153``` 154 155Then you can load a JSON5 file with a Node.js `require()` statement. For 156example: 157 158```js 159const config = require('./config.json5') 160``` 161 162## CLI 163Since JSON is more widely used than JSON5, this package includes a CLI for 164converting JSON5 to JSON and for validating the syntax of JSON5 documents. 165 166### Installation 167```sh 168npm install --global json5 169``` 170 171### Usage 172```sh 173json5 [options] <file> 174``` 175 176If `<file>` is not provided, then STDIN is used. 177 178#### Options: 179- `-s`, `--space`: The number of spaces to indent or `t` for tabs 180- `-o`, `--out-file [file]`: Output to the specified file, otherwise STDOUT 181- `-v`, `--validate`: Validate JSON5 but do not output JSON 182- `-V`, `--version`: Output the version number 183- `-h`, `--help`: Output usage information 184 185## Contibuting 186### Development 187```sh 188git clone https://github.com/json5/json5 189cd json5 190npm install 191``` 192 193When contributing code, please write relevant tests and run `npm test` and `npm 194run lint` before submitting pull requests. Please use an editor that supports 195[EditorConfig](http://editorconfig.org/). 196 197### Issues 198To report bugs or request features regarding the JSON5 data format, please 199submit an issue to the [official specification 200repository](https://github.com/json5/json5-spec). 201 202To report bugs or request features regarding the JavaScript implentation of 203JSON5, please submit an issue to this repository. 204 205## License 206MIT. See [LICENSE.md](./LICENSE.md) for details. 207 208## Credits 209[Assem Kishore](https://github.com/aseemk) founded this project. 210 211[Michael Bolin](http://bolinfest.com/) independently arrived at and published 212some of these same ideas with awesome explanations and detail. Recommended 213reading: [Suggested Improvements to JSON](http://bolinfest.com/essays/json.html) 214 215[Douglas Crockford](http://www.crockford.com/) of course designed and built 216JSON, but his state machine diagrams on the [JSON website](http://json.org/), as 217cheesy as it may sound, gave us motivation and confidence that building a new 218parser to implement these ideas was within reach! The original 219implementation of JSON5 was also modeled directly off of Doug’s open-source 220[json_parse.js] parser. We’re grateful for that clean and well-documented 221code. 222 223[json_parse.js]: 224https://github.com/douglascrockford/JSON-js/blob/master/json_parse.js 225 226[Max Nanasy](https://github.com/MaxNanasy) has been an early and prolific 227supporter, contributing multiple patches and ideas. 228 229[Andrew Eisenberg](https://github.com/aeisenberg) contributed the original 230`stringify` method. 231 232[Jordan Tucker](https://github.com/jordanbtucker) has aligned JSON5 more closely 233with ES5, wrote the official JSON5 specification, completely rewrote the 234codebase from the ground up, and is actively maintaining this project. 235