JSON (JavaScript Object Notation) is a data-interchange format.  It closely resembles a subset of JavaScript syntax, although it is not a strict subset. (See JSON in the JavaScript Reference for full details.)  It is useful when writing any kind of JavaScript-based application, including websites and browser extensions.  For example, you might store user information in JSON format in a cookie, or you might store extension preferences in JSON in a string-valued browser preference.

JSON is capable of representing numbers, booleans, strings, null, and arrays (ordered sequences of values) and objects (string-value mappings) composed of these values (or of other arrays and objects).  It doesn't natively represent more complex data types like functions, regular expressions, dates, and so on.  (Date objects by default serialize as a string containing the date in ISO format, so while they don't round-trip, the information isn't completely lost.)  If you need to preserve such values, you can transform values as they are serialized, or prior to deserialization, to enable JSON to represent additional data types.

Using JSON through JavaScript's JSON object

The simplest, easiest way to use JSON is through the standard JSON object in JavaScript.  Use JSON.stringify to serialize a JSON value, and use JSON.parse to deserialize a JSON value.

For example, to serialize a JavaScript object, use the JSON.stringify() method:

var foo = {};
foo.bar = "new property";
foo.baz = 3;

var JSONfoo = JSON.stringify(foo);

JSONfoo now holds {"bar":"new property","baz":3}. To make JSONfoo back into a JavaScript object just do:

var backToJS = JSON.parse(JSONfoo);

For more information, see the JSON object documentation.

Using JSON through nsIJSON

Relatively old versions of Firefox don't natively support JSON, and the only way to access JSON functionality is through the nsIJSON component, implemented since Firefox 3.  Encoding and decoding are performed through nsIJSON's encode and decode methods.  These methods are not as powerful as JSON through the JSON object, and they only support values which are objects or arrays, not strings, booleans, numbers, or null.  (These values are only supported within arrays and objects: the plain number 5 will not work, but the object { "value": 5 } will.)

Because nsIJSON is not as powerful as the JSON object, its encode and decode methods have been removed from Firefox 7.  Developers should switch to using the JSON object instead.

The following code serializes a JavaScript object using nsIJSON:

var Ci = Components.interfaces;
var Cc = Components.classes;

var foo = {};
foo.bar = "new property";
foo.baz = 3;

var nativeJSON = Cc["@mozilla.org/dom/json;1"].createInstance(Ci.nsIJSON);
var JSONfoo = nativeJSON.encode(foo);

The JSONfoo variable now holds the string {"bar":"new property","baz":3}. To create an object corresponding to JSONfoo, just do:

var backToJS = nativeJSON.decode(JSONfoo);

Using JSON in other ways

While in theory it's possible to use JSON by using eval (but only to deserialize to an object, and not to serialize to a string) or by using json2.js, it's not a good idea.  It's not safe to parse JSON using eval because eval permits much more syntax than JSON does (up to arbitrary code execution).  As for json2.js, its problem is that it adds methods to built-in objects like Object.prototype, which is very likely to break code not specifically anticipating that possibility.  You should almost always use either of the former methods to use JSON in preference to any other way.  

See also