json5
Advanced tools
Package description
The json5 npm package is a JSON parser and serializer that allows for comments, trailing commas, single quotes, and more. It is designed to be a more user-friendly and flexible version of JSON.
Parsing JSON5 Strings
This feature allows you to parse JSON5 strings into JavaScript objects. It supports comments, single quotes, and additional syntax that is not available in standard JSON.
{"parse": "JSON5.parse('{/*comment*/\"key\": \"value\"}')"}Stringifying JavaScript Objects
This feature converts JavaScript objects into JSON5 strings. It can include features like trailing commas and unquoted keys, making the output more human-readable.
{"stringify": "JSON5.stringify({key: 'value'}, null, 2)"}YAML is a human-friendly data serialization standard that can be used as an alternative to JSON. It supports comments, complex data structures, and is often used in configuration files. It is more flexible than JSON5 but uses a different syntax.
TOML is a configuration file format that is easy to read due to its clear semantics. It is similar to JSON5 in that it aims to be more user-friendly, but it has its own syntax and is often used in applications where configuration files are written and maintained by humans.
Readme
JSON is an excellent data format, but we think it can be better.
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.
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.
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.
Object keys can be unquoted if they’re valid identifiers.
Yes, even reserved keywords (like default) are valid unquoted keys in ES5
[§11.1.5, §7.6].
(More info)
(TODO: Unicode characters and escape sequences aren’t yet supported in this implementation.)
Object keys can also be single-quoted.
Objects can have trailing commas.
Strings can be single-quoted.
Strings can be split across multiple lines; just prefix each newline with a backslash. [ES5 §7.8.4]
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.
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 comment
here: '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 implementation’s own package.json5 is more realistic:
// This file is written in JSON5 syntax, naturally, but npm needs a regular
// JSON file, so be sure to keep package.json and package.json5 in sync!
{
name: 'json5',
version: '0.5.1',
description: 'JSON for humans.',
main: 'lib/index.js',
bin: 'lib/cli.js',
browser: 'dist/index.js',
files: [
'lib/',
'dist/',
],
scripts: {
build: 'babel-node build/build.js && babel src -d lib && rollup -c',
lint: 'eslint --fix build src',
prepublishOnly: 'npm run lint && npm test && npm run production',
pretest: 'cross-env NODE_ENV=test npm run build',
preversion: 'npm run lint && npm test && npm run production',
production: 'cross-env NODE_ENV=production npm run build && babel-node build/check-package.js',
test: 'nyc --reporter=html --reporter=text mocha',
},
repository: {
type: 'git',
url: 'git+https://github.com/json5/json5.git',
},
keywords: [
'json',
'json5',
'es5',
'es2015',
'ecmascript',
],
author: 'Aseem Kishore <aseem.kishore@gmail.com>',
contributors: [
'Max Nanasy <max.nanasy@gmail.com>',
'Andrew Eisenberg <andrew@eisenberg.as>',
'Jordan Tucker <jordanbtucker@gmail.com>',
],
license: 'MIT',
bugs: {
url: 'https://github.com/json5/json5/issues',
},
homepage: 'http://json5.org/',
dependencies: {
minimist: '^1.2.0',
},
devDependencies: {
'babel-cli': '^6.26.0',
'babel-core': '^6.26.0',
'babel-plugin-add-module-exports': '^0.2.1',
'babel-plugin-external-helpers': '^6.22.0',
'babel-plugin-istanbul': '^4.1.5',
'babel-preset-env': '^1.6.0',
'babel-register': '^6.26.0',
'babelrc-rollup': '^3.0.0',
'cross-env': '^5.0.5',
'del': '^3.0.0',
'eslint': '^4.7.1',
'eslint-config-standard': '^10.2.1',
'eslint-plugin-import': '^2.7.0',
'eslint-plugin-node': '^5.1.1',
'eslint-plugin-promise': '^3.5.0',
'eslint-plugin-standard': '^3.0.1',
'mocha': '^3.5.3',
'nyc': '^11.2.1',
'regenerate': '^1.3.3',
'rollup': '^0.50.0',
'rollup-plugin-babel': '^3.0.2',
'rollup-plugin-commonjs': '^8.2.1',
'rollup-plugin-node-resolve': '^3.0.0',
'rollup-plugin-uglify': '^2.0.1',
'sinon': '^3.3.0',
'unicode-9.0.0': '^0.7.4',
},
}
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.
This JavaScript implementation of JSON5 simply provides a JSON5 object just
like the native ES5 JSON object.
To use from Node:
npm install json5
var JSON5 = 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:
var obj = JSON5.parse('{unquoted:"key",trailing:"comma",}');
var str = JSON5.stringify(obj);
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.)
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:
require('json5/lib/require');
require('./path/to/foo'); // tries foo.json5 after foo.js, foo.json, etc.
require('./path/to/bar.json5');
This module also provides a json5 executable (requires Node) for converting
JSON5 files to JSON:
json5 -c path/to/foo.json5 # generates path/to/foo.json
git clone https://github.com/json5/json5
cd json5
npm install
npm test
As the package.json5 file states, be sure to run npm run build on changes
to package.json5, since npm requires package.json.
Feel free to file issues and submit
pull requests — contributions are
welcome. If you do submit a pull request, please be sure to add or update the
tests, and ensure that npm test continues to pass.
MIT. See LICENSE.md for details.
Michael Bolin independently arrived at and published some of these same ideas with awesome explanations and detail. Recommended reading: Suggested Improvements to JSON
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!
Andrew Eisenberg has contributed the
stringify method.
Jordan Tucker has aligned JSON5 more closely with ES5 and is actively maintaining this project.
FAQs
JSON for Humans
The npm package json5 receives a total of 69,475,304 weekly downloads. As such, json5 popularity was classified as popular.
We found that json5 demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The Python Software Foundation has secured a 5-year sponsorship from Fastly that supports PSF's activities and events, most notably the security and reliability of the Python Package Index (PyPI).
Security News
LDAPjs, an LDAP Client and Server API for Node.js, was decommissioned after its maintainer received an abusive email from a user, raising concerns about this form of abuse as a potential attack vector.
Security News
CISA launched a new project called Vulnrichment to enrich CVEs with details that help prioritize patching and mitigation efforts, as the NVD backlog of unenriched CVEs awaiting analysis surpasses 10,000.