Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A modern JSON implementation compatible with nearly all JavaScript platforms.
Branch: gh-pages
Pull request Compare This branch is 178 commits behind bestiejs:gh-pages.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
test
vendor
.gitmodules
LICENSE
README.md
Rakefile
index.html
jsl.conf
package.json
page.css

README.md

JSON 3

JSON 3 is an ECMAScript 5-compliant JSON implementation. Its objective is to provide a reasonably fast library compatible with a variety of older environments, including Internet Explorer 6, Opera 7, Safari 2, and Netscape 6.

JSON is a language-independent data interchange format based on a loose subset of the JavaScript grammar. Originally popularized by Douglas Crockford, JSON was standardized in the fifth edition of the ECMAScript specification. The 5.1 edition, ratified in June 2011, incorporates several modifications to the grammar pertaining to the serialization of dates.

The JSON 3 parser does not use eval or regular expressions. This provides security and performance benefits in obsolete and mobile environments, where the margin is particularly significant. Informal benchmarks have shown that JSON 3 is slower than Crockford's recursive descent parser and Mike Samuel's json-sans-eval, but approximates the speed of the eval-based JSON 2 parser.

JSON 3 exposes two functions: stringify() for serializing a JavaScript value to JSON, and parse() for parsing a JSON source string into a JavaScript value. The functions behave exactly as described in the spec, except for the date serialization deviation noted below.

The project is hosted on GitHub, along with the unit tests. It is part of the BestieJS family, a collection of "best in class" JavaScript libraries that promote cross-platform support, specification precedents, unit testing, and plenty of documentation.

Usage

JSON 3 is a drop-in replacement for JSON 2. You can include it in your HTML source like so:

<script src="http://bestiejs.github.com/json3/lib/json3.min.js"></script>
<script>
  JSON.stringify({"Hello": 123});
  // => '{"Hello":123}'
</script>

You can also use JSON 3 as a CommonJS module, though most CommonJS environments natively support JSON serialization and parsing:

var JSON3 = require("path/to/json3");
JSON3.parse("[1, 2, 3]");
// => [1, 2, 3]

Finally, you can load it directly in Mozilla Rhino, SpiderMonkey, or another JavaScript engine:

load("path/to/json3");
JSON.stringify([1, 2, 3]);
// => "[1,2,3]"

Downloads

The development version is commented and uncompressed; the production version has been compressed using Closure Compiler.

Current Version: 3.1

Changes from JSON 2

JSON 3...

  • Correctly serializes primitive wrapper objects (Issue #28).
  • Throws a TypeError for cyclic structures (JSON 2 will recurse until the stack overflows).
  • Utilizes feature tests to detect broken or incomplete native JSON implementations (JSON 2 only checks for the presence of the native functions). The tests are only executed once, so there is no runtime delay when parsing or serializing values.

In contrast to JSON 2, JSON 3 does not...

  • Add toJSON() methods to the Boolean, Number, and String prototypes. These are not part of any standard, and are made redundant by the design of the stringify() implementation.
  • Add Date#toJSON() or Date#toISOString(). See the note about date serialization below.

Date Serialization

JSON 3 deviates from the specification in one important way: it does not define Date#toISOString() or Date#toJSON(). This is to preserve CommonJS compatibility, as well as avoid polluting native prototypes. Instead, date serialization is performed internally by the stringify() function: if a date object does not directly define a toJSON() method, it is serialized as a simplified ISO 8601 date-time string.

Several native Date#toJSON() implementations produce date time strings that do not conform to the grammar outlined in the spec. For example, all versions of Safari 4, as well as JSON 2, fail to serialize extended years correctly. Furthermore, JSON 2 and older implementations omit the milliseconds from the date-time string (optional in ES 5, but required in 5.1). Finally, in all versions of Safari 4 and 5, serializing an invalid date will produce the string "Invalid Date", rather than null. Because these environments exhibit other serialization bugs, however, JSON 3 will override the native stringify() implementation.

Compatibility

JSON 3 has been tested with the following web browsers, CommonJS environments, and JavaScript engines.

Web Browsers

JavaScript Engines

  • Mozilla Rhino 1.5R5 and higher
  • WebKit JSC

Known Incompatibilities

  • JSON 3 is not compatible with Prototype 1.6.1 and older. If you must use this version of Prototype, please use Object.toJSON() and String#evalJSON(true) instead of JSON.stringify and JSON.parse, respectively. This is not a JSON 3 bug; because Prototype adds several non-standard toJSON() methods that return serialized values instead of objects, using the native JSON implementation will yield identical results.

  • Attempting to serialize the arguments object may produce inconsistent results due to specification and environment differences. As a workaround, please convert the arguments object to an array first: JSON.stringify([].slice.call(arguments)).

  • The four date serialization unit tests may fail if the system clock is set incorrectly.

Required Native Methods

JSON 3 assumes that the following methods exist and function as described in the ECMAScript specification:

  • The Number, String, Array, Object, SyntaxError, and TypeError constructors.
  • String.fromCharCode
  • Function#call
  • String.prototype: indexOf, charAt, slice.
  • Object.prototype: toString, hasOwnProperty (a fallback is provided for Safari 2).
  • Date.prototype: getUTC{FullYear, Month, Date, Hours, Minutes, Seconds, Milliseconds}.
  • Array.prototype: push, pop, join.

Contributing

Check out a working copy of the JSON 3 source code with Git:

$ git clone git://github.com/bestiejs/json3.git
$ cd json3
$ git submodule update --init

If you'd like to contribute a feature or bug fix, you can fork JSON 3, commit your changes, and send a pull request. Please make sure to update the unit tests in the test directory as well.

Alternatively, you can use the GitHub issue tracker to submit bug reports and feature requests.

JSON 3 is released under the MIT License.

Something went wrong with that request. Please try again.