#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# 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.

- Index
- Methods

## Item Index

### Methods

- _getLocationValue static
- _getXPathResult static
- _parseField static
- _parseMeta static
- _parseResult static
- _parseResults static
- apply static
- parse

## Methods

### `_getLocationValue`

(

- `field`
- `context`

)
Object protected static

Defined in `dataschema/js/dataschema-xml.js:132`

Get an XPath-specified value for a given field from an XML node or document.

#### Parameters:

- `field` String | Object

  Field definition.

- `context` Object

  XML node or document to search within.

#### Returns:

Object: Data value or null.

### `_getXPathResult`

(

- `locator`
- `context`
- `xmldoc`

)
Object protected static

Defined in `dataschema/js/dataschema-xml.js:168`

Fetches the XPath-specified result for a given location in an XML node or document.

#### Parameters:

- `locator` String

  The XPath location.

- `context` Object

  XML node or document to search within.

- `xmldoc` Object

  XML document to resolve namespace.

#### Returns:

Object: Data collection or null.

### `_parseField`

(

- `field`
- `result`
- `context`

)
protected static

Defined in `dataschema/js/dataschema-xml.js:266`

Schema-parsed result field.

#### Parameters:

- `field` String | Object

  Required. Field definition.

- `result` Object

  Required. Schema parsed data object.

- `context` Object

  Required. XML node or document to search within.

### `_parseMeta`

(

- `xmldoc_in`
- `data_out`

)
Object protected static

Defined in `dataschema/js/dataschema-xml.js:290`

Parses results data according to schema

#### Parameters:

- `xmldoc_in` Object

  XML document parse.

- `data_out` Object

  In-progress schema-parsed data to update.

#### Returns:

Object: Schema-parsed data.

### `_parseResult`

(

- `fields`
- `context`

)
Object protected static

Defined in `dataschema/js/dataschema-xml.js:314`

Schema-parsed result to add to results list.

#### Parameters:

- `fields` Array

  Required. A collection of field definition.

- `context` Object

  Required. XML node or document to search within.

#### Returns:

Object: Schema-parsed data.

### `_parseResults`

(

- `schema`
- `context`
- `data_out`

)
Object protected static

Defined in `dataschema/js/dataschema-xml.js:335`

Schema-parsed list of results from full data

#### Parameters:

- `schema` Object

  Schema to parse against.

- `context` Object

  XML node or document to parse.

- `data_out` Object

  In-progress schema-parsed data to update.

#### Returns:

Object: Schema-parsed data.

### `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 `key`s, 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` XMLDoc

  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:

- `value` Object

  Original value.

- `field` Object

  Field.

#### Returns:

Object: Type-converted value.