API Docs for: 3.18.1

DataSchema.XML Class

Extends DataSchema.Base
Defined in: dataschema/js/dataschema-xml.js:8
Module: dataschema-xml
Parent Module: dataschema

Provides a DataSchema implementation which can be used to work with XML data.

See the apply method for usage.

Item Index

Methods

Methods

apply

(
  • schema
  • data
)
Object static

Defined in dataschema/js/dataschema-xml.js:34

Applies a schema to an XML data tree, returning a normalized object with results in the results property. Additional information can be parsed out of the XML for inclusion in the meta property of the response object. If an error is encountered during processing, an error property will be added.

Field data in the nodes captured by the XPath in schema.resultListLocator is extracted with the field identifiers described in schema.resultFields. Field identifiers are objects with the following properties:

  • key : (required) The desired property name to use
    store the retrieved value in the result object.  If locator is
not specified, key is also used as the XPath locator (String)
  • locator: The XPath locator to the node or attribute within each
    result node found by _schema.resultListLocator_ containing the
desired field data (String)
  • parser : A function or the name of a function on Y.Parsers used
    to convert the input value into a normalized type.  Parser
functions are passed the value as input and are expected to
return a value.
  • schema : Used to retrieve nested field data into an array for
    assignment as the result field value.  This object follows the same
conventions as _schema_.

If no value parsing or nested parsing is needed, you can use XPath locators (strings) instead of field identifiers (objects) -- see example below.

response.results will contain an array of objects with key:value pairs. The keys are the field identifier keys, and the values are the data values extracted from the nodes or attributes found by the field locator (or key fallback).

To extract additional information from the XML, include an array of XPath locators in schema.metaFields. The collected values will be stored in response.meta with the XPath locator as keys.

Parameters:

  • schema Object

    Schema to apply. Supported configuration properties are:

    • [resultListLocator] String optional

      XPath locator for the XML nodes that contain the data to flatten into response.results

    • [resultFields] Array optional

      Field identifiers to locate/assign values in the response records. See above for details.

    • [metaFields] Array optional

      XPath locators to extract extra non-record related information from the XML data

  • data XMLDocument

    XML data to parse

Returns:

Object:

An Object with properties results and meta

Example:

var schema = {
        resultListLocator: '//produce/item',
        resultFields: [
            {
                locator: 'name',
                key: 'name'
            },
            {
                locator: 'color',
                key: 'color',
                parser: function (val) { return val.toUpperCase(); }
            }
        ]
    };

// Assumes data like
// <inventory>
//   <produce>
//     <item><name>Banana</name><color>yellow</color></item>
//     <item><name>Orange</name><color>orange</color></item>
//     <item><name>Eggplant</name><color>purple</color></item>
//   </produce>
// </inventory>

var response = Y.DataSchema.JSON.apply(schema, data);

// response.results[0] is { name: "Banana", color: "YELLOW" }

parse

(
  • value
  • field
)
Object

Inherited from DataSchema.Base: dataschema/js/dataschema-base.js:38

Applies field parser, if defined

Parameters:

Returns:

Object:

Type-converted value.