8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<div class="intro">
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith The DataSchema Utility applies a given schema against data of arbitrary
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith formats, normalizing input such as JSON, XML, or delimited text into a
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith JavaScript object with known properties. The value of the DataSchema
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Utility is in its ability to translate data from a variety of sources
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith into a consistent format for consumption by components in a predictable
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly{{>getting-started}}
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h2 id="using">Using the DataSchema</h2>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p>This section describes how to use the DataSchema in further detail.</p>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h3 id="basics">DataSchema basics</h3>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith DataSchema classes are standalone static utilities that accept data input
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith plus a schema definition and return a JavaScript object with the following
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Property</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Type</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Description</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>`results`</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Array</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>An array of data.</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>`meta`</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Object</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Arbitrary data values filtered from the input data.</td>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Note that the schema you define will depend on which subclass of DataSchema
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith is being used.
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h4 id="array">DataSchema.Array</h4>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Use DataSchema.Array when working with JavaScript arrays. These arrays may
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith contain JavaScript objects, other arrays, or primitive values.
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly// A sample array of objects
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly {make:"Chevrolet",model:"Bel Air",year:1957},
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly {make:"Dodge",model:"Dart",year:1964},
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly {make:"Ford",model:"Mustang",year:1968}
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly// A sample array of arrays
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly ["Chevrolet", "Bel Air", 1957],
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly ["Dodge", "Dart", 1964],
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly ["Ford", "Mustang", 1968]
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly// A sample array of primitives
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly "1957 Chevrolet Bel Air", "1964 Dodge Dart", "1968 Ford Mustang"
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith<p>Define a schema with the following properties for your array data:</p>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Property</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Type</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Description</th>
4a0bd0d85804a9eeb025a19001abc5159ad6aee3Luke Smith <td>`resultFields`</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Array</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Keys to assign to the values contained in the array.</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnellyvar mySchema = {
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly resultFields: [{key:"make"}, {key:"model"}, {key:"year"}]
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly// Returns an object with the properties "results" and "meta"
0829c34e7d91947d02158c197cfbe13d4addb2acLuke Smithvar myOutput = Y.DataSchema.Array.apply(mySchema, myData);
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h4 id="json">DataSchema.JSON</h4>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Use DataSchema.JSON when working with JavaScript objects or JSON data.
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Typically, your data will hold meta values as well as an internal array of
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith tabular data.
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly// Sample JSON data
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly "current":160,
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly "category":"exercise",
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly "weekly schedule":[
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly {"day":"sunday", "activity":"swimming"},
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly {"day":"monday", "activity":"running"},
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly {"day":"tuesday", "activity":"biking"},
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly {"day":"wednesday", "activity":"running"},
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly {"day":"thursday", "activity":"swimming"},
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly {"day":"friday", "activity":"running"},
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly {"day":"saturday", "activity":"golf"}
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Locators are string values in your schema that use dot notation or bracket
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith syntax to point to data values within the object. Define a schema with the
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith following properties for your object data:
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Property</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Type</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Description</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>`metaFields`</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Object</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Key/locator pairs that point to arbitrary data values.</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>`resultListLocator`</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>String</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Locator to an internal array of tabular data.</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>`resultFields`</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Array</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Keys to assign to the values contained in the array.</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnellyvar mySchema = {
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly metaFields: {current:"profile.current", target:"profile.target"},
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly resultListLocator: "program[0]['weekly schedule']",
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly resultFields: [{key:"day"}, {key:"activity"}]
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly// Returns an object with the properties "results" and "meta"
0829c34e7d91947d02158c197cfbe13d4addb2acLuke Smithvar myOutput = Y.DataSchema.JSON.apply(mySchema, myData);
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h4 id="xml">DataSchema.XML</h4>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <strong>Note:</strong> XML parsing currently has known issues on the
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Android WebKit browser.
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Use DataSchema.XML when working with XML data. As with JSON data, your XML
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith data may hold meta values as well as an internal node list of tabular
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly// Sample XML data
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <Session>542235629</Session>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <Tracks start="1" count="10" total="98" errorCount="0"
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly defaultSort="popularity+" description="Top 100 Tracks"
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly name="Top 100 Tracks">
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <Track id="59672468" rating="-1" title="I Kissed A Girl">
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <Artist id="30326214" rating="-1">Katy Perry</Artist>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <ItemInfo><ChartPosition last="26" this="1"/></ItemInfo>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <Track id="47973564" rating="-1" title="Shake It">
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <Artist id="45575683" rating="-1">Metro Station</Artist>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <ItemInfo><ChartPosition last="27" this="2"/></ItemInfo>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <Track id="52207363" rating="-1" title="Bleeding Love">
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <Artist id="37956508" rating="-1">Leona Lewis</Artist>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <ItemInfo><ChartPosition last="28" this="3"/></ItemInfo>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Locators are XPath string values in your schema that point to data values
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith within the XML. Define a schema with the following properties for your XML
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Property</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Type</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Description</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>`metaFields`</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Object</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Key/locator pairs that point to arbitrary data values.</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>`resultListLocator`</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>String</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Locator to an internal node list of tabular data.</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>`resultFields`</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Array</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>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.</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnellyvar mySchema = {
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly metaFields: {session:"//Session", total:"//Tracks/@total"},
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly resultListLocator: "Track", // node name or XPath
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly resultFields: [{key:"song", locator:"@title"}, {key:"artist", locator:"Artist"}, {key:"rank", locator:"ItemInfo/ChartPosition/@this"}]
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly// Returns an object with the properties "results" and "meta"
0829c34e7d91947d02158c197cfbe13d4addb2acLuke Smithvar myOutput = Y.DataSchema.XML.apply(mySchema, myData);
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h4 id="text">DataSchema.Text</h4>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith Use DataSchema.Text when working with delimited textual data. Typically,
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith your data will not contain meta values.
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly// Sample text data
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnellynotebooks, 100, spiral-bound
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnellypencils, 300, #2 erasers
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnellypens, 500, blue ink
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p>Define a schema with the following properties for your text data:</p>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Property</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Type</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Description</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>`resultDelimiter`</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>String</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Delimiter separating each row of tabular data</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>`fieldDelimiter`</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>String</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Delimiter separating each column of tabular data</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>`resultFields`</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Array</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>Keys to assign to the values contained in each field (column).</td>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnellyvar mySchema = {
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly resultDelimiter: "\\n",
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly fieldDelimiter: ",",
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly resultFields: [{key:"product"}, {key:"quantity"}, {key:"detail"}];
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly// Returns an object with the properties "results" and "meta"
0829c34e7d91947d02158c197cfbe13d4addb2acLuke Smithvar myOutput = Y.DataSchema.Text.apply(mySchema, myData);
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h3 id="plugin">DataSchema as a DataSource plugin</h3>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith DataSchema plugins integrate DataSource's retrieval functionality with
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith schema-based normalization of the retrieved data for further consumption by
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith another component. There are currently four available DataSource plugins:
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith DataSourceArraySchema, DataSourceJSONSchema, DataSourceXMLSchema, and
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith DataSourceTextSchema.
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny DonnellymyDataSource.plug({fn: Y.Plugin.DataSourceJSONSchema, cfg: {
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly resultListLocator: "ResultSet.Result",
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly resultFields: ["Title"]
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly// myCallback functions will receive the schema-normalized response object
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly request: myRequest,
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly callback: myCallback
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h2 id="knownissues">Known Issues</h2>
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith <strong>Known Android issues (bugs 2529621, 2529758, 2529775):</strong> XML
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith parsing is currently buggy on the Android WebKit browser.