index.mustache revision 8f9d94fb7812612dff92ce14a37dbcad4ff02c1c
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<div class="intro">
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <p>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.</p>
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>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p>DataSchema classes are standalone static utilities that accept data input plus a schema definition and return a JavaScript object with the following properties:</p>
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>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p>Note that the schema you define will depend on which subclass of DataSchema is being used.</p>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h4 id="array">DataSchema.Array</h4>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p>Use DataSchema.Array when working with JavaScript arrays. These arrays may contain JavaScript objects, other arrays, or primitive values.</p>
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"
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p>Define a schema with the following properties for your array data:
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Property</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Type</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <th>Description</th>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly <td>`resultsField`</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"
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnellyvar myOutput = Y.DataSchema.Array.apply(mySchema, myData));
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h4 id="json">DataSchema.JSON</h4>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p>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.</p>
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"}
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p>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:</p>
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"
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnellyvar myOutput = Y.DataSchema.JSON.apply(mySchema, myData));
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h4 id="xml">DataSchema.XML</h4>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p><strong>Note:</strong> XML parsing currently has known issues on the Android WebKit browser.
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p>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.</p>
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>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p>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:</p>
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"
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnellyvar myOutput = Y.DataSchema.XML.apply(mySchema, myData));
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h4 id="text">DataSchema.Text</h4>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p>Use DataSchema.Text when working with delimited textual data. Typically, your data will not contain meta values.</p>
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"
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnellyvar myOutput = Y.DataSchema.Text.apply(mySchema, myData));
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<h3 id="plugin">DataSchema as a DataSource plugin</h3>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p>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.</p>
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>
8f9d94fb7812612dff92ce14a37dbcad4ff02c1cJenny Donnelly<p><strong>Known Android issues (bugs 2529621, 2529758, 2529775):</strong> XML parsing is currently buggy on the Android WebKit browser.</p>