Getting Started

To include the source files for DataSchema and its dependencies, first load the YUI seed file if you haven't already loaded it.

<script src="http://yui.yahooapis.com/3.18.1/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify.

<script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('dataschema', function (Y) {
    // DataSchema is available and ready for use. Add implementation
    // code here.
});
</script>

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

Using the DataSchema

This section describes how to use the DataSchema in further detail.

DataSchema basics

DataSchema classes are standalone static utilities that accept data input plus a schema definition and return a JavaScript object with the following properties:

Note that the schema you define will depend on which subclass of DataSchema is being used.

DataSchema.Array

Use DataSchema.Array when working with JavaScript arrays. These arrays may contain JavaScript objects, other arrays, or primitive values.

// A sample array of objects
[
    {make:"Chevrolet",model:"Bel Air",year:1957},
    {make:"Dodge",model:"Dart",year:1964},
    {make:"Ford",model:"Mustang",year:1968}
];

// A sample array of arrays
[
    ["Chevrolet", "Bel Air", 1957],
    ["Dodge", "Dart", 1964],
    ["Ford", "Mustang", 1968]
];

// A sample array of primitives
[
    "1957 Chevrolet Bel Air", "1964 Dodge Dart", "1968 Ford Mustang"
];

Define a schema with the following properties for your array data:

var mySchema = {
        resultFields: [{key:"make"}, {key:"model"}, {key:"year"}]
};

// Returns an object with the properties "results" and "meta"
var myOutput = Y.DataSchema.Array.apply(mySchema, myData);

DataSchema.JSON

Use DataSchema.JSON when working with JavaScript objects or JSON data. Typically, your data will hold meta values as well as an internal array of tabular data.

// Sample JSON data
{
    "profile":{
        "current":160,
        "target":150
    },
    "program": [
        {
            "category":"exercise",
            "weekly schedule":[
                {"day":"sunday", "activity":"swimming"},
                {"day":"monday", "activity":"running"},
                {"day":"tuesday", "activity":"biking"},
                {"day":"wednesday", "activity":"running"},
                {"day":"thursday", "activity":"swimming"},
                {"day":"friday", "activity":"running"},
                {"day":"saturday", "activity":"golf"}
            ]
        }
    ]
};

Locators are string values in your schema that use dot notation or bracket syntax to point to data values within the object. Define a schema with the following properties for your object data:

var mySchema = {
    metaFields: {current:"profile.current", target:"profile.target"},
    resultListLocator: "program[0]['weekly schedule']",
    resultFields: [{key:"day"}, {key:"activity"}]
};

// Returns an object with the properties "results" and "meta"
var myOutput = Y.DataSchema.JSON.apply(mySchema, myData);

DataSchema.XML

Note: XML parsing currently has known issues on the Android WebKit browser.

Use DataSchema.XML when working with XML data. As with JSON data, your XML data may hold meta values as well as an internal node list of tabular data.

// Sample XML data
<Response>
    <Session>542235629</Session>
    <Tracks start="1" count="10" total="98" errorCount="0"
        defaultSort="popularity+" description="Top 100 Tracks"
        name="Top 100 Tracks">
        <Track id="59672468" rating="-1" title="I Kissed A Girl">
            <Artist id="30326214" rating="-1">Katy Perry</Artist>
            <ItemInfo><ChartPosition last="26" this="1"/></ItemInfo>
        </Track>
        <Track id="47973564" rating="-1" title="Shake It">
            <Artist id="45575683" rating="-1">Metro Station</Artist>
            <ItemInfo><ChartPosition last="27" this="2"/></ItemInfo>
        </Track>
        <Track id="52207363" rating="-1" title="Bleeding Love">
            <Artist id="37956508" rating="-1">Leona Lewis</Artist>
            <ItemInfo><ChartPosition last="28" this="3"/></ItemInfo>
        </Track>
    </Tracks>
</Response>

Locators are XPath string values in your schema that point to data values within the XML. Define a schema with the following properties for your XML data:

var mySchema = {
    metaFields: {session:"//Session", total:"//Tracks/@total"},
    resultListLocator: "Track", // node name or XPath
    resultFields: [{key:"song", locator:"@title"}, {key:"artist", locator:"Artist"}, {key:"rank", locator:"ItemInfo/ChartPosition/@this"}]
};

// Returns an object with the properties "results" and "meta"
var myOutput = Y.DataSchema.XML.apply(mySchema, myData);

DataSchema.Text

Use DataSchema.Text when working with delimited textual data. Typically, your data will not contain meta values.

// Sample text data
notebooks, 100, spiral-bound
pencils, 300, #2 erasers
pens, 500, blue ink

Define a schema with the following properties for your text data:

var mySchema = {
    resultDelimiter: "\\n",
    fieldDelimiter: ",",
    resultFields: [{key:"product"}, {key:"quantity"}, {key:"detail"}];

// Returns an object with the properties "results" and "meta"
var myOutput = Y.DataSchema.Text.apply(mySchema, myData);

DataSchema as a DataSource plugin

DataSchema plugins integrate DataSource's retrieval functionality with schema-based normalization of the retrieved data for further consumption by another component. There are currently four available DataSource plugins: DataSourceArraySchema, DataSourceJSONSchema, DataSourceXMLSchema, and DataSourceTextSchema.

myDataSource.plug({fn: Y.Plugin.DataSourceJSONSchema, cfg: {
    schema: {
        resultListLocator: "ResultSet.Result",
        resultFields: ["Title"]
    }
}});

// myCallback functions will receive the schema-normalized response object
myDataSource.sendRequest({
    request: myRequest,
    callback: myCallback
});

Known Issues

Known Android issues (bugs 2529621, 2529758, 2529775): XML parsing is currently buggy on the Android WebKit browser.