Getting Started

To use the JSON Utility, include the following source files in your web page with the script tag:

<!-- Dependencies --> <script src="http://yui.yahooapis.com/2.5.2/build/yahoo/yahoo-min.js"></script> <!-- Source file --> <script src="http://yui.yahooapis.com/2.5.2/build/json/json-min.js"></script>

YAHOO.lang.JSON is a static class that does not require instantiation. Simply access the methods you need from YAHOO.lang.JSON.

Using YAHOO.lang.JSON

The JSON Utility extends YAHOO.lang, providing two static methods used for transforming data to and from JSON string format. These methods are described in the following sections.

• Parsing JSON strings into JavaScript data
• Turn JavaScript data into a JSON string

Parsing JSON string data into JavaScript data

Pass a JSON string to YAHOO.lang.JSON.parse to convert the JSON string into live data. Optionally provide a second argument to filter or format the parsed object data en route.

var jsonString = '{"productId":1234,"price":24.5,"inStock":true,"bananas":null}'; // Parsing JSON strings can throw a SyntaxError exception, so we wrap the call // in a try catch block try { var prod = YAHOO.lang.JSON.parse(jsonString); } catch (e) { alert("Invalid product data"); } // We can now interact with the data if (prod.price < 25) { prod.price += 10; // Price increase! }

You can filter out data or format data during parse by passing a function as the second argument to parse. Values returned from the function will take the place of the original value. Return undefined to omit a key:value pair from the returned object.

var currencySymbol = "$" function myFilter(key,val) { // format price as a string if (key == "price") { var f_price = currencySymbol + (val % 1 ? val + "0" : val + ".00"); return f_price.substr(0,f_price.indexOf('.') + 3); } // omit keys by returning undefined if (key == "bananas") { return undefined; } } var formattedProd = YAHOO.lang.JSON.parse(jsonString, myFilter); // key "bananas" is not present in the formattedProd object if (YAHOO.lang.isUndefined(formattedProd.bananas)) { alert("We have no bananas today"); } // and the price is the formatted string "$24.50" alert("Your price: " + formattedProd.price)

A word of caution against using eval

JSON data format is a subset of JavaScript notation, meaning that it is possible to use JavaScript eval to transform JSON data to live data. However, it is unsafe practice to assume that data reaching your code is safe. eval is capable of executing JavaScript's full notation, including calling functions and accessing cookies with all the privileges of a <script>. To ensure that the data is safe, YAHOO.lang.JSON.parse inspects the incoming string (using methods derived from Douglas Crockford's json2.js) and verifies it as valid JSON before giving it the green light to parse.

// Potentially UNSAFE var data = eval('(' + shouldBeJsonData + ')'); // Safe var data = YAHOO.lang.JSON.parse(shouldBeJsonData);

Stringifying JavaScript data into a JSON string

To convert a JavaScript object (or any permissable value) to a JSON string, pass that object to YAHOO.lang.JSON.stringify and capture the returned string. Note that cyclical references will be converted to null.

var myData = { puppies : [ { name: "Ashley", age: 12 }, { name: "Abby", age:9 } ] }; var jsonStr = YAHOO.lang.JSON.stringify(myData); // jsonStr now contains the string (without the leading comment slashes) // {"puppies":[{"name":"Ashley","age":12},{"name":"Abby","age":9}]} // Create a cyclical reference myData["puppies"][0]["NEWKEY"] = myData; jsonStr = YAHOO.lang.JSON.stringify(myData); // jsonStr now contains the string (without the leading comment slashes) // {"puppies":[{"name":"Ashley","age":12,"NEWKEY":null},{"name":"Abby","age":9}]}

Additionally, stringify supports optional whitelist and depth-limit parameters.

// a detailed object record set var records = [ {id:1, name: "Bob", age: 47, favorite_color: "blue"}, {id:2, name: "Sally", age: 30, favorite_color: "mauve"}, {id:3, name: "Tommy", age: 13, favorite_color: "black"}, {id:4, name: "Chaz", age: 26, favorite_color: "plaid"} ]; // Use an array of acceptable object key names as a whitelist. // To create a JSON string with only age and id var jsonStr = YAHOO.lang.JSON.stringify(records,["id","age"]); // jsonStr now contains the string // [{"id":1,"age":47},{"id":2,"age":30},{"id":3,"age":13},{"id":4,"age":26}] // A deeply nested structure var deep = { name : "Level 1", children : { name : "Level 2", children : { name : "Level 3", children : { name : "Level 4", children : { name : "Level 5", children : {} } } }, enough : true } }; // Stop at Level 2 var jsonStr = YAHOO.lang.JSON.stringify(deep,null,2); // jsonStr contains no content for the children object at Level 2 // {"name":"Level 1","children":{"name":"Level 2","children":{},"enough":true}}

About the JSON format

JSON is a lightweight data format based on the object notation of the JavaScript language. It does not require JavaScript to read or write; it is easy to parse by any language and libraries and tools exist in many languages to handle JSON. You'll find several examples of support for JSON data in the YUI Library.

There is a wealth of good information about JSON and its distinction from XML as a data interchange format at Douglas Crockford's site, JSON.org.

JSON data is characterized as a collection of objects, arrays, booleans, strings, numbers, and null. The notation follows these guidelines:

• Objects begin and end with curly braces ({}).
• Object members consist of a string key and an associated value separated by a colon ( "key" : VALUE ).
• Objects may contain any number of members, separated by commas ({ "key1" : VALUE1, "key2" : VALUE2 }).
• Arrays begin and end with square braces and contain any number of values, separated by commas ([ VALUE1, VALUE2 ]).
• Values can be a string, a number, an object, an array, or the literals true, false, and null.
• Strings are surrounded by double quotes and can contain Unicode characters and common backslash escapes ("new\nline").

JSON.org has helpful format diagrams and specific information on allowable string characters.

Here is a simple example of a valid JSON string:

{ "Image": { "Width":800, "Height":600, "Title":"View from 15th Floor", "Thumbnail": { "Url":"http:\/\/scd.mm-b1.yimg.com\/image\/481989943", "Height": 125, "Width": "100" }, "IDs":[ 116, 943, 234, 38793 ] } }

This structure should look familiar to JavaScript programmers (for good reason). Note, however the solidus (forward slash) characters in the "Url" value are escaped.

YUI on Mobile: Using JSON Utility with "A-Grade" Mobile Browsers

There are no known concerns with the JSON Utility on mobile browsers at this time.

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.