JSONSchemaParse ā€” API

Document parsing

parse(text)

Parses text and turns it into a native value.

For reading a Uint8Array/Buffer, specify charset in the options (see the parse(text, options) form below).

parse(text, reviver)

Parses text and turns it into a native value. The reviver argument is applied to each value, compatible with ECMAScript JSON.parse.

Equivalent to ECMAScript JSON.parse(text, reviver).

parse(text, schema)

Parses text while validating it against the Schema instance in the schema argument. Parsing will terminate at the first validation error.

try {
	const schema = new lib.Schema({ type: 'string' });
	const value = lib.parse(jsonText, schema);
}catch(e){
	// handle SchemaError or ValidationError
}

parse(text, options)

Parses text, and accepts an object options as found in StreamParser, except for the "parse" options, which are called with the following values: parseValue:true, parseAnnotations:false, parseInfo:false.

try {
	const value = lib.parse(jsonText, {
		schema: { type: 'string' },
		charset: 'UTF-8',
	});
}catch(e){
	// handle SchemaError or ValidationError
}

parseInfo(text, options)

Parses text and returns an Instance instance. Use it when you need to know additional information about the JSON document, including JSON Schema annotations on each value, or the line/character position information of each value.

options is an object with any of the following properties:

The returned object will have the following properties:

Stream Parsing

new StreamParser(options)

StreamParser is a writable stream that accepts a byte stream or string stream, and outputs events.

It outputs an "end" event when the document has been fully parsed.

options is an object with any of the following properties:

Values for "bigNumber" (all these options are performed after JSON Schema validation):

var parser = new StreamParser(new Schema('http://localhost/schema.json', {type: 'array'}), {parseValue:true});

fs.createReadStream('file.json')
	.pipe(parser)
	.on('finish', function(err, res){
		console.log(parser.errors);
		console.log(parser.value);
	});

StreamParser#done

A Promise that resolves to the StreamParser when it parses and validates a document.

StreamParser#errors

An Array of ValidationError instances representing accumulated validation errors. Parsing will end when an error is detected, not all errors in the document may be listed.

StreamParser#value

If parseValue: true was passed in options, the parsed value will be available here.

StreamParser#on('startObject', function() )

Emitted when an object is opened (when { is observed).

StreamParser#on('endObject', function() )

Emitted when an object is closed (when } is observed).

StreamParser#on('startArray', function() )

Emitted when an array is opened (when [ is observed).

StreamParser#on('endArray', function() )

Emitted when an array is closed (when ] is observed).

StreamParser#on('key', function(name) )

Emitted inside an object when a key is fully parsed.

StreamParser#on('string', function(value) )

Emitted when a string value is parsed.

StreamParser#on('boolean', function(value) )

Emitted when a boolean value is parsed.

StreamParser#on('null', function(value) )

Emitted when a null is parsed.

StreamParser#on('end', function() )

Emitted when the incoming stream been fully consumed, parsed, and a final result is available.

JSON Schema

new Schema(baseURI, schemaObject)

var schema = new Schema('http://localhost/schema.json', { type: 'array' });
var parser = schema.createParser({parseValue:true});

fs.createReadStream('file.json')
	.pipe(parser)
	.on('finish', function(err, res){
		console.log(parser.errors);
		console.log(parser.value);
	});

class: SchemaRegistry

Use SchemaRegistry if one schema references another.

SchemaRegistry#import(uri, schema)

Import a schema so that it may be referenced by its given URI by other schemas.

var registry = new SchemaRegistry();
var baseSchema = registry.import('http://localhost/schema.json', {
	type: 'array',
	items: {$ref:'http://localhost/item.json'},
});
var stringSchema = registry.import('http://localhost/item.json', { type: 'string' });
// Alternatively:
// var schema = new Schema('http://localhost/schema.json', { type: 'array' }, registry);
var parser = baseSchema.createParser({parseValue:true});

fs.createReadStream('file.json')
	.pipe(parser)
	.on('finish', function(err, res){
		console.log(parser.errors);
		console.log(parser.value);
	});

Results

ValidationError

Stores information about a failed validation of a keyword against an instance. Contains the following properties:

Interface: Validator

A Validator is the paradigm used to validate information from the JSON parser as it is streaming. It validates a single instance against a single schema by reading SAX events from the parser, as well as listening to results from subordinate validators (Validator instances for child instances and subschemas), and comparing them to the range of events permitted by the schema.

It is an ECMAScript object that consumes information about a single layer in the parser stack as it tokenizes input. A validator only evaluates over a single layer in the stack (like an object or a string), it is not notified of events that happen in children or grandchildren layers. Instead, when a child is encountered (like an array item), a function is called requesting a list of validators that can process that sub-instance. When the child finishes parsing, the validator can then examine the return value and act on it.

A new validator does not yet know the type of incoming value, and may not know until e.g. all whitespace is consumed. You must wait for a start{type} call.

new Validator(options, errors)

Called to create a validator, whenever a new layer in the parsing stack is entered.

Optionally pass an outside array that errors will be pushed to. Normally, this will be the instance of StreamParser#errors, so that errors from all validators get gathered together at the parser. Otherwise, a local array will be created.

The parser will call the following methods, depending on the tokens it encounters during parsing: