Upgrade Notes

As of version 2.8.0, browser native JSON.parse and JSON.stringify will be used if present. The native implementations are much faster and safer than any implementation done in JavaScript.

In versions prior to 2.8, the signature and behavior of YAHOO.lang.JSON.stringify differed slightly from the reference implementation at JSON.org and the ECMAScript version 5 specification that grew from that. In order to leverage native methods as browsers adopt the ECMAScript 5 spec, the YUI implementation of stringify had to change so the behavior would be consistent across browsers with and without native JSON support.

Specifically, the stringify behavior that has changed from 2.7.0 to 2.8.0 is:

• Cyclical object references are no longer replaced with null, but now throw an Error. It is therefore recommended to wrap both parse and stringify calls in try/catch blocks.
• The third parameter no longer limits the depth of object serialization, but is now used to trigger formatted output.
• Objects with a toJSON method will be first transformed using this method.
• Object keys are no longer sorted alphabetically. This is possible to do with a replacer function.
• Overriding YAHOO.lang.JSON.dateToString is no longer recommended because the default ISO 8601 serialization is defined in the spec. If Dates must be formatted differently, either preprocess the data or set useNativeStringify to false after overriding dateToString.

The implementation of YAHOO.lang.JSON.parse has not changed in a few versions and remains a safe approximation of the spec. If your application requires specific functionality from 2.7.0 or prior, you can continue to use prior versions. They should correctly parse and produce valid JSON.

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.9.0/build/yahoo/yahoo-min.js"></script>
 
<!-- Source file -->
<script src="http://yui.yahooapis.com/2.9.0/build/json/json-min.js"></script>
 

<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo/yahoo-min.js"></script>
 
<!-- Source file -->
<script src="http://yui.yahooapis.com/2.9.0/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 it into live data. Optionally provide a second argument to filter or format the parsed object data during deserialization.

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);
 
    // We can now interact with the data
    if (prod.price < 25) {
        prod.price += 10; // Price increase!
    }
}
catch (e) {
    alert("Invalid product data");
}
 

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);
 
    // We can now interact with the data
    if (prod.price < 25) {
        prod.price += 10; // Price increase!
    }
}
catch (e) {
    alert("Invalid product data");
}
 

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.toFixed(2);
    }
 
    // 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)
 

var currencySymbol = "$"
function myFilter(key,val) {
    // format price as a string
    if (key == "price") {
        var f_price = currencySymbol + val.toFixed(2);
    }
 
    // 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 in browsers that don't yet support native JSON functionality, YAHOO.lang.JSON.parse inspects the incoming string for potentially malevolent content (using methods derived from Douglas Crockford's json2.js) before giving it the green light to parse.

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

// 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.

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}]}
 

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}]}
 

Stringify's full signature is

YAHOO.lang.JSON.stringify = function (data, filter, indent) { ... };
 

YAHOO.lang.JSON.stringify = function (data, filter, indent) { ... };
 

The following sections will discuss the second and third arguments.

Filtering data before serialization

The optional second argument to stringify accepts either an array of strings or a function. Array values become a whitelist of object properties that should be serialized. A function value is known as a "replacer", and will be called for each object property:value pair, allowing you to modify the values or object structure as the input object is stringified.

// 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}]
 
// OR use a replacer function to modify the object en route
function replacer(key, value) {
    if (key === 'age') {
        return value > 35 ? '36-' :
               value > 25 ? '26-35' :
               value > 15 ? '16-25' :
               'under 16';
    } else if (key === 'name') {
        return value;     // also accept the name property
    } else {
        return undefined; // This will filter any other keys
    }
}
var jsonStr = YAHOO.lang.JSON.stringify(records, replacer);
 
// jsonStr now contains the string
// [{"name":"Bob","age":"36-"},{"name":"Sally","age":"26-35"},...
 

// 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}]
 
// OR use a replacer function to modify the object en route
function replacer(key, value) {
    if (key === 'age') {
        return value > 35 ? '36-' :
               value > 25 ? '26-35' :
               value > 15 ? '16-25' :
               'under 16';
    } else if (key === 'name') {
        return value;     // also accept the name property
    } else {
        return undefined; // This will filter any other keys
    }
}
var jsonStr = YAHOO.lang.JSON.stringify(records, replacer);
 
// jsonStr now contains the string
// [{"name":"Bob","age":"36-"},{"name":"Sally","age":"26-35"},...
 

Using toJSON to customize object serialization

Another option for including a special serialization strategy for your objects and classes is to assign a toJSON method. The return value of yourObject.toJSON() will be used in place of the object itself, and before the replacer is executed on that value.

function Student(first, last, level, grades) {
    this.firstName = first;
    this.lastName = last;
    this.gradeLevel = level;
    this.grades = grades;
}
 
// Offer a different object structure for JSON serialization
Student.prototype.toJSON = function () {
    var gpa = 0,
        i = this.grades.length;
 
    while (i--) {
        gpa += this.grades[i];
    }
 
    return {
        name: this.lastName + ', ' + this.firstName,
        gpa: ((gpa / this.grades.length) / 25).toFixed(1)
    };
};
 
var students = [];
students.push( new Student("John", "Schmidt", 1, [95,90,92,87,100,100]) );
students.push( new Student("Irene", "Gamel", 1, [72,70,88,76,100,95]) );
students.push( new Student("Francis", "Yeh", 1, [53,67,100,0,78,88]) );
 
var studentJSON = YAHOO.lang.JSON.stringify(students);
 
// studentsJSON now contains the string
// [{"name":"Schmidt, John","gpa":"3.8"},{"name":"Gamel, Irene","gpa":"3.3"},{"name":"Yeh, Francis","gpa":"2.6"}]
 

function Student(first, last, level, grades) {
    this.firstName = first;
    this.lastName = last;
    this.gradeLevel = level;
    this.grades = grades;
}
 
// Offer a different object structure for JSON serialization
Student.prototype.toJSON = function () {
    var gpa = 0,
        i = this.grades.length;
 
    while (i--) {
        gpa += this.grades[i];
    }
 
    return {
        name: this.lastName + ', ' + this.firstName,
        gpa: ((gpa / this.grades.length) / 25).toFixed(1)
    };
};
 
var students = [];
students.push( new Student("John", "Schmidt", 1, [95,90,92,87,100,100]) );
students.push( new Student("Irene", "Gamel", 1, [72,70,88,76,100,95]) );
students.push( new Student("Francis", "Yeh", 1, [53,67,100,0,78,88]) );
 
var studentJSON = YAHOO.lang.JSON.stringify(students);
 
// studentsJSON now contains the string
// [{"name":"Schmidt, John","gpa":"3.8"},{"name":"Gamel, Irene","gpa":"3.3"},{"name":"Yeh, Francis","gpa":"2.6"}]
 

Some native objects include a toJSON method. For the most part, they do what you'd expect. new Boolean(true) => true, for example. One notable exception are Date instances, which serialize into an ISO 8601 format that looks like "1987-12-25T21:04:32Z".

Formatting the JSON output

To have stringify output JSON that's more human readable, pass either a string or number as the third parameter. Numbers will be translated into that number of spaces. Including the third parameter will trigger the output to be formatted with carriage returns and indentation using the specified string.

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"}
];
 
var formattedJsonStr = YAHOO.lang.JSON.stringify(records,["name","age"],4);
 
/* formattedJsonStr now contains the string
[
    {
        "name": "Bob",
        "age": 47
    },
    {
        "name": "Sally",
        "age": 30
    },
    {
        "name": "Tommy",
        "age": 13
    },
    {
        "name": "Chaz",
        "age": 26
    }
]
*/
 

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"}
];
 
var formattedJsonStr = YAHOO.lang.JSON.stringify(records,["name","age"],4);
 
/* formattedJsonStr now contains the string
[
    {
        "name": "Bob",
        "age": 47
    },
    {
        "name": "Sally",
        "age": 30
    },
    {
        "name": "Tommy",
        "age": 13
    },
    {
        "name": "Chaz",
        "age": 26
    }
]
*/
 

Native implementations may differ slightly in their formatted output, but it should continue to be readable.

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 ]
  }
}
 

{
  "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.

Notes about current native JSON support

Native JSON support in JavaScript is defined in the ECMAScript 5 specification (still in draft as of August 2009). However, most of the major browser vendors have already implemented this feature in recent versions of their JavaScript engines. Because the feature is new and the specification was still in draft while they were implementing the JSON API, there are gotchas involved in leveraging the disparate native behaviors.

In general, it is preferable to use the native behavior for JSON.parse as it is much faster and safer than any JavaScript implementation. There are also very few known critical issues with supporting browsers.

Stringify has more pitfalls and inconsistencies, but they may not affect your use cases. As with parse, the native implementation of stringify is faster, but only marginally so with reasonably sized input. In most cases, choosing the JavaScript implementation will not affect performance and may be preferable for its cross browser consistency.

As noted above, YUI's JSON Utility will leverage native behavior in implementing browsers by default. However, as of version 2.8.0, you can choose to use the JavaScript implementation of parse or stringify or both, by setting some new static properties.

// Always use the JavaScript implementation for parsing
YAHOO.lang.JSON.useNativeParse = false;
 
// Always use the JavaScript implementation for stringifying
YAHOO.lang.JSON.useNativeStringify = false;
 

// Always use the JavaScript implementation for parsing
YAHOO.lang.JSON.useNativeParse = false;
 
// Always use the JavaScript implementation for stringifying
YAHOO.lang.JSON.useNativeStringify = false;
 

Known Issues

Older versions of PrototypeJS, and possibly other libraries, add several toJSON methods to native prototypes. Most harmful is the Array.prototype.toJSON method which behaves differently than the ES5 specification recommends for toJSON implementations. The result is that stringifying objects that contain arrays will result in incorrect output. The array will be double serialized. For example:

var obj = {
    property: "value",
    boom: ["this", "is", "the", "bug"]
};
 
var output = YAHOO.lang.JSON.stringify(obj);
 
// output should look like
// {"property":"value","boom":["this","is","the","bug"]}
 
// but with Array.prototype.toJSON added, results in
// {"property":"value","boom":"[\"this\",\"is\",\"the\",\"bug\"]"}
 
// Note the value of the "boom" property is a string, not an array
 

var obj = {
    property: "value",
    boom: ["this", "is", "the", "bug"]
};
 
var output = YAHOO.lang.JSON.stringify(obj);
 
// output should look like
// {"property":"value","boom":["this","is","the","bug"]}
 
// but with Array.prototype.toJSON added, results in
// {"property":"value","boom":"[\"this\",\"is\",\"the\",\"bug\"]"}
 
// Note the value of the "boom" property is a string, not an array
 

This is the result from both the JavaScript implementation of stringify as well as the native implementation in modern browsers.

The workaround for this recommended by Tobie Langel (maintainer of PrototypeJS) is:

delete Number.prototype.toJSON;
delete Boolean.prototype.toJSON;
delete String.prototype.toJSON;
delete Array.prototype.toJSON;
 
Hash.prototype.toJSON = function() {
    return this.toObject();
};
 
Object.toJSON = YAHOO.lang.JSON.stringify;

delete Number.prototype.toJSON;
delete Boolean.prototype.toJSON;
delete String.prototype.toJSON;
delete Array.prototype.toJSON;
 
Hash.prototype.toJSON = function() {
    return this.toObject();
};
 
Object.toJSON = YAHOO.lang.JSON.stringify;

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 YUILibrary.com forums.

Also be sure to check out 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 YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.