The DataSchema Utility applies a given schema against data of arbitrary formats, normalizing input such as JSON, XML, or delimited text into a JavaScript object with known properties. The value of the DataSchema Utility is in its ability to translate data from a variety of sources into a consistent format for consumption by components in a predictable manner.

{{>getting-started}}

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:

Property Type Description
`results` Array An array of data.
`meta` Object Arbitrary data values filtered from the input data.

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:

Property Type Description
`resultFields` Array Keys to assign to the values contained in the array.
``` 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:

Property Type Description
`metaFields` Object Key/locator pairs that point to arbitrary data values.
`resultListLocator` String Locator to an internal array of tabular data.
`resultFields` Array Keys to assign to the values contained in the array.
``` 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 542235629 Katy Perry Metro Station Leona Lewis ```

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:

Property Type Description
`metaFields` Object Key/locator pairs that point to arbitrary data values.
`resultListLocator` String Locator to an internal node list of tabular data.
`resultFields` Array Keys to assign to the values contained in the array. Locators may be defined to point to complex nested values or values held in attributes.
``` 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:

Property Type Description
`resultDelimiter` String Delimiter separating each row of tabular data
`fieldDelimiter` String Delimiter separating each column of tabular data
`resultFields` Array Keys to assign to the values contained in each field (column).
``` 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.