DataSchema.JSON Class
yui3/src/dataschema/js/dataschema-json.js:8
Parent Module: dataschema
Provides a DataSchema implementation which can be used to work with JSON data.
See the apply
method for usage.
Index
Methods
- _getFieldValues static
- _parseMeta static
- _parseResults static
- apply static
- getLocationValue static
- getPath static
- parse
Methods
_getFieldValues
-
fields
-
array_in
-
data_out
Get field data values out of list of full results
Parameters:
-
fields
ArrayFields to find.
-
array_in
ArrayResults to parse.
-
data_out
ObjectIn-progress parsed data to update.
Returns:
Parsed data object.
_parseMeta
-
metaFields
-
json_in
-
data_out
Parses results data according to schema
Parameters:
-
metaFields
ObjectMetafields definitions.
-
json_in
ObjectJSON to parse.
-
data_out
ObjectIn-progress parsed data to update.
Returns:
Schema-parsed meta data.
_parseResults
-
schema
-
json_in
-
data_out
Schema-parsed list of results from full data
Parameters:
-
schema
ObjectSchema to parse against.
-
json_in
ObjectJSON to parse.
-
data_out
ObjectIn-progress parsed data to update.
Returns:
Parsed data object.
apply
-
[schema]
-
data
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
: <strong>(required)</strong> The path locator (String)parser
: A function or the name of a function onY.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 optionalSchema to apply. Supported configuration properties are:
-
[resultListLocator]
String optionalPath locator for the location of the array of records to flatten into
response.results
-
[resultFields]
Array optionalField identifiers to locate/assign values in the response records. See above for details.
-
[metaFields]
Array optionalPath locators to extract extra non-record related information from the data object.
-
-
data
Object | Array | StringJSON data or its string serialization.
Returns:
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
Utility function to walk a path and return the value located there.
Parameters:
-
path
StringLocator path.
-
data
StringData to traverse.
Returns:
Data value at location.
getPath
-
locator
Utility function converts JSON locator strings into walkable paths
Parameters:
-
locator
StringJSON value locator.
Returns:
Walkable path to data value.
parse
-
value
-
field
<p>Applies field parser, if defined</p>
Parameters:
-
value
Object<p><p>Original value.</p></p>
-
field
Object<p><p>Field.</p></p>
Returns:
<p><p>Type-converted value.</p></p>