JSON

  • Revision slug: JSON
  • Revision title: JSON
  • Revision id: 16784
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment 119 words added

Revision Content

JSON (JavaScript Object Notation) is a data-interchange format, based on a subset of JavaScript syntax. It is useful when writing any kind of JavaScript-based application, including extensions. See http://json.org/ for details.

Native JSON support is anticipated in one of future versions of JavaScript ({{ Bug("340987") }}).

One great use of JSON is to easily store objects in preferences as char preferences. {{ Note("The rest of this article is tailored towards extension and XUL application developers.") }}

JSON in Firefox 2

No JSON support is included in Firefox 2. Using the code from json.org can be problematic and raise variations on {{ Bug("397595") }}. You should adapt the code from json.org or from JSON.jsm, which provides a JSON object which can be used to serialize to JSON and parse JSON.

JSON in Firefox 3

Firefox 3 introduced the {{ Interface("nsIJSON") }} interface, which provides easy to use support for encoding and decoding JSON strings from JavaScript code. Firefox 3 also includes a JavaScript code module for JSON encoding and decoding, JSON.jsm. The code module can be imported using Components.utils.import.

JSON in Firefox 3.5

Firefox 3.5 dropped support for the JSON.jsm JavaScript module in favor of native JSON object support, as specified in the ECMAScript 3.1 draft specification.  See Using JSON in Firefox for details.

Note: The {{ interface("nsIJSON") }} interface still exists in Firefox 3.5, and is expected to do so for the foreseeable future; the native JSON support is based on nsIJSON.  You can continue to directly access nsIJSON if you wish.

JSON via JavaScript module for Firefox 3 and 3.5

Myk Melez has created a JavaScript module that wraps the incompatible Firefox 3 and Firefox 3.5 JSON APIs so that you can write to a single API to support both versions of Firefox.  Simply import his JSON.js module, like this:

let MyExtension = {
  JSON: null,
  ...
};
Components.utils.import("chrome://myextension/modules/JSON.js", MyExtension);

Having done this, MyExtension.JSON can now be used for the Firefox 3.5 JSON API, even on Firefox 3.

This also works in Thunderbird 3, which also uses the Firefox 3.5 JSON API.

Using JSON

Quick Warning

When writing privileged code, such as extensions, be careful to not just eval JSON strings (any strings, actually) from untrusted source. Either use a JSON decoder (best), Components.utils.evalInSandbox, or JSON.stringify from json.org. See Downloading JSON and JavaScript in extensions.

Using JSON.jsm

To serialize a JavaScript object:

Components.utils.import("resource://gre/modules/JSON.jsm");

var foo = {};
foo.bar = "new property";
foo.baz = 3;
var JSONfoo = JSON.toString(foo);

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

var backToJS = JSON.fromString(JSONfoo);

Using nsIJSON

To serialize a JavaScript object:

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 now holds {"bar":"new property","baz":3}. To make JSONfoo back into a JavaScript object just do:

var backToJS = nativeJSON.decode(JSONfoo);

Using native JSON

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);

Limitations

You cannot serialize an object that has members which are functions. The JSON specification does not allow it. For example:

foo.qwerty = function(){alert('foobar');};
foo.qwerty()
var JSONfoo = JSON.toString(foo);

will raise a TypeError on line XXX: No JSON representation for this object!

See also

{{ languages( { "ja": "ja/JSON", "zh-cn": "cn/JSON" } ) }}

Revision Source

<p><strong>JSON</strong> (<strong>JavaScript Object Notation</strong>) is a data-interchange format, based on a subset of <a href="/en/JavaScript" title="en/JavaScript">JavaScript</a> syntax. It is useful when writing any kind of JavaScript-based application, including extensions. See <a class=" external" href="http://json.org/" rel="freelink">http://json.org/</a> for details.</p>
<p>Native JSON support is anticipated in one of future versions of JavaScript ({{ Bug("340987") }}).</p>
<p><span class="comment">One great use of JSON is to easily store objects in preferences as char preferences.</span> {{ Note("The rest of this article is tailored towards extension and XUL application developers.") }}</p>
<h2 name="JSON_in_Firefox_2">JSON in Firefox 2</h2>
<p>No JSON support is included in Firefox 2. Using the code from <a class="external" href="http://json.org">json.org</a> can be problematic and raise variations on {{ Bug("397595") }}. You should adapt the code from json.org or from <a class="external" href="http://mxr.mozilla.org/mozilla/source/js/src/xpconnect/loader/JSON.jsm">JSON.jsm</a>, which provides a JSON object which can be used to serialize to JSON and parse JSON.</p>
<h2 name="JSON_in_Firefox_3">JSON in Firefox 3</h2>
<p>Firefox 3 introduced the {{ Interface("nsIJSON") }} interface, which provides easy to use support for encoding and decoding JSON strings from JavaScript code. Firefox 3 also includes a <a href="/en/Using_JavaScript_code_modules" title="en/Using_JavaScript_code_modules">JavaScript code module</a> for JSON encoding and decoding, <code>JSON.jsm</code>. The code module can be imported using <code><a href="/en/Components.utils.import" title="en/Components.utils.import">Components.utils.import</a></code>.</p>
<h2>JSON in Firefox 3.5</h2>
<p>Firefox 3.5 dropped support for the JSON.jsm JavaScript module in favor of native JSON object support, as specified in the <a class="external" href="http://wiki.ecmascript.org/doku.php?id=es3.1:json_support" title="http://wiki.ecmascript.org/doku.php?id=es3.1:json_support">ECMAScript 3.1 draft specification</a>.  See <a class="internal" href="/En/Using_JSON_in_Firefox" title="/en/Using JSON in Firefox">Using JSON in Firefox</a> for details.</p>
<div class="note"><strong>Note:</strong> The {{ interface("nsIJSON") }} interface still exists in Firefox 3.5, and is expected to do so for the foreseeable future; the native JSON support is based on <code>nsIJSON</code>.  You can continue to directly access <code>nsIJSON</code> if you wish.</div>
<h2 name="Using_JSON">JSON via JavaScript module for Firefox 3 and 3.5</h2>
<p>Myk Melez has created a JavaScript module that wraps the incompatible Firefox 3 and Firefox 3.5 JSON APIs so that you can write to a single API to support both versions of Firefox.  Simply import his <a class="external" href="http://hg.mozdev.org/jsmodules/file/tip/JSON.js" title="http://hg.mozdev.org/jsmodules/file/tip/JSON.js">JSON.js</a> module, like this:</p>
<pre class="brush: js">let MyExtension = {
  JSON: null,
  ...
};
Components.utils.import("chrome://myextension/modules/JSON.js", MyExtension);
</pre>
<p>Having done this, <code>MyExtension.JSON</code> can now be used for the <a class="internal" href="/en/Using%20JSON%20in%20Firefox" title="en/Using JSON in Firefox">Firefox 3.5 JSON API</a>, even on Firefox 3.</p>
<p>This also works in Thunderbird 3, which also uses the Firefox 3.5 JSON API.</p>
<h2 name="Using_JSON">Using JSON</h2>
<h3 name="Quick_Warning">Quick Warning</h3>
<div class="warning">When writing privileged code, such as extensions, be careful to not just <a href="/en/Core_JavaScript_1.5_Reference/Global_Functions/eval" title="en/Core_JavaScript_1.5_Reference/Global_Functions/eval">eval</a> JSON strings (any strings, actually) from untrusted source. Either use a JSON decoder (best), <a href="/en/Components.utils.evalInSandbox" title="en/Components.utils.evalInSandbox">Components.utils.evalInSandbox</a>, or JSON.stringify from json.org. See <a href="/en/Downloading_JSON_and_JavaScript_in_extensions" title="en/Downloading_JSON_and_JavaScript_in_extensions">Downloading JSON and JavaScript in extensions</a>.</div>
<h3 name="Using_JSON.jsm">Using JSON.jsm</h3>
<p>To serialize a JavaScript object:</p>
<pre class="eval">Components.utils.import("<a class=" external" href="resource://gre/modules/JSON.jsm" rel="freelink">resource://gre/modules/JSON.jsm</a>");

var foo = {};
foo.bar = "new property";
foo.baz = 3;
var JSONfoo = JSON.toString(foo);
</pre>
<p>The <code>JSONfoo</code> now holds <code>{"bar":"new property","baz":3}</code>. To make <code>JSONfoo</code> back into a JavaScript object just do:</p>
<pre class="eval">var backToJS = JSON.fromString(JSONfoo);
</pre>
<h3 name="Using_nsIJSON">Using nsIJSON</h3>
<p>To serialize a JavaScript object:</p>
<pre class="eval">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);
</pre>
<p>The <code>JSONfoo</code> now holds <code>{"bar":"new property","baz":3}</code>. To make <code>JSONfoo</code> back into a JavaScript object just do:</p>
<pre class="eval">var backToJS = nativeJSON.decode(JSONfoo);
</pre>
<h3>Using native JSON</h3>
<p>To serialize a JavaScript object, use the <code>JSON.stringify()</code> method:</p>
<pre class="eval">var foo = {};
foo.bar = "new property";
foo.baz = 3;

var JSONfoo = JSON.stringify(foo);
</pre>
<p><code>JSONfoo</code> now holds <code>{"bar":"new property","baz":3}</code>. To make <code>JSONfoo</code> back into a JavaScript object just do:</p>
<pre>var backToJS = JSON.parse(JSONfoo);
</pre>
<h3 name="Limitations">Limitations</h3>
<p>You cannot serialize an object that has members which are functions. The JSON specification does not allow it. For example:</p>
<pre class="eval">foo.qwerty = function(){alert('foobar');};
foo.qwerty()
var JSONfoo = JSON.toString(foo);
</pre>
<p>will raise a <code>TypeError on line XXX: No JSON representation for this object!</code></p>
<h3 name="See_also">See also</h3>
<ul> <li><a href="/en/JSON/JSONPath" title="en/JSON/JSONPath">JSONPath</a></li> <li><a class="internal" href="/En/Using_JSON_in_Firefox" title="/en/Using JSON in Firefox">Using JSON in Firefox</a></li> <li>{{ interface("nsIJSON") }}</li>
</ul>
<p>{{ languages( { "ja": "ja/JSON", "zh-cn": "cn/JSON" } ) }}</p>
Revert to this revision