API Docs for: 3.8.0
Show:

DataSchema.JSON Class

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

See the apply method for usage.

Item Index

Methods

Methods

_getFieldValues

(
  • fields
  • array_in
  • data_out
)
Object protected static

Get field data values out of list of full results

Parameters:

  • fields Array

    Fields to find.

  • array_in Array

    Results to parse.

  • data_out Object

    In-progress parsed data to update.

Returns:

Object: Parsed data object.

_parseMeta

(
  • metaFields
  • json_in
  • data_out
)
Object protected static

Parses results data according to schema

Parameters:

  • metaFields Object

    Metafields definitions.

  • json_in Object

    JSON to parse.

  • data_out Object

    In-progress parsed data to update.

Returns:

Object: Schema-parsed meta data.

_parseResults

(
  • schema
  • json_in
  • data_out
)
Object protected static

Schema-parsed list of results from full data

Parameters:

  • schema Object

    Schema to parse against.

  • json_in Object

    JSON to parse.

  • data_out Object

    In-progress parsed data to update.

Returns:

Object: Parsed data object.

apply

(
  • [schema]
  • data
)
Object static

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

The input data is expected to be an object or array. If it is a string, it will be passed through Y.JSON.parse().

If data contains an array of data records to normalize, specify the schema.resultListLocator as a dot separated path string just as you would reference it in JavaScript. So if your data object has a record array at data.response.results, use schema.resultListLocator = "response.results". Bracket notation can also be used for array indices or object properties (e.g. "response['results']"); This is called a "path locator"

Field data in the result list is extracted with field identifiers in schema.resultFields. Field identifiers are objects with the following properties:

  • key : (required) The path locator (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.

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

If no processing of the result list array is needed, schema.resultFields can be omitted; the response.results will point directly to the array.

If the result list contains arrays, response.results will contain an array of objects with key:value pairs assuming the fields in schema.resultFields are ordered in accordance with the data array values.

If the result list contains objects, the identified schema.resultFields will be used to extract a value from those objects for the output result.

To extract additional information from the JSON, include an array of path locators in schema.metaFields. The collected values will be stored in response.meta.

Parameters:

  • [schema] Object optional

    Schema to apply. Supported configuration properties are:

    • [resultListLocator] String optional

      Path locator for the location of the array of records 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

      Path locators to extract extra non-record related information from the data object.

  • data Object | Array | String

    JSON data or its string serialization.

Returns:

Object: An Object with properties results and meta

Example:

// Process array of arrays
var schema = {
        resultListLocator: 'produce.fruit',
        resultFields: [ 'name', 'color' ]
    },
    data = {
        produce: {
            fruit: [
                [ 'Banana', 'yellow' ],
                [ 'Orange', 'orange' ],
                [ 'Eggplant', 'purple' ]
            ]
        }
    };

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

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


// Process array of objects + some metadata
schema.metaFields = [ 'lastInventory' ];

data = {
    produce: {
        fruit: [
            { name: 'Banana', color: 'yellow', price: '1.96' },
            { name: 'Orange', color: 'orange', price: '2.04' },
            { name: 'Eggplant', color: 'purple', price: '4.31' }
        ]
    },
    lastInventory: '2011-07-19'
};

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

// response.results[0] is { name: "Banana", color: "yellow" }
// response.meta.lastInventory is '2001-07-19'


// Use parsers
schema.resultFields = [
    {
        key: 'name',
        parser: function (val) { return val.toUpperCase(); }
    },
    {
        key: 'price',
        parser: 'number' // Uses Y.Parsers.number
    }
];

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

// Note price was converted from a numeric string to a number
// response.results[0] looks like { fruit: "BANANA", price: 1.96 }

getLocationValue

(
  • path
  • data
)
Object static

Utility function to walk a path and return the value located there.

Parameters:

Returns:

Object: Data value at location.

getPath

(
  • locator
)
String[] static

Utility function converts JSON locator strings into walkable paths

Parameters:

  • locator String

    JSON value locator.

Returns:

String[]: Walkable path to data value.

parse

(
  • value
  • field
)
Object

Applies field parser, if defined

Parameters:

Returns:

Object: Type-converted value.