z-schema validator
JSON Schema validator for Node.js (draft4 version)
Coded according to:
json-schema documentation, json-schema-core, json-schema-validation, json-schema-hypermedia
Passing all tests here (even optional, except zeroTerminatedFloats and some URI tests, see more info in #18):
json-schema/JSON-Schema-Test-Suite
Will try to maintain this as much as possible, all bug reports welcome.
Grunt automatization
If you need to automatize validation of your schemas, there's a Grunt plugin grunt-z-schema by Petr Bela
How does it compare to others?
rawgithub.com/zaggino/z-schema/master/benchmark/results.html
Basic Usage
var ZSchema = require("z-schema");
ZSchema.validate(json, schema)
.then(function(report){
// successful validation
// there might be warnings: console.log(report.warnings)
})
.catch(function(err){
console.error(err.errors)
})
There is also support for sync mode like this:
var validator = new ZSchema({ sync: true });
var valid = validator.validate(json, schema);
if (!valid) {
var error = validator.getLastError();
}
Using traditional callback:
ZSchema.validate(json, schema, function(err, report){
if(err){
console.error(err.errors);
return;
}
// successful validation
// there might be warnings: console.log(report.warnings)
})
If you need just to validate your schema, you can do it like this:
var validator = new ZSchema();
validator.validateSchema(schema)
.then(function(report){
})
.catch(function(err){
})
Or with Node.js style callback:
var validator = new ZSchema();
validator.validateSchema(schema, function (err, report) {
if (err) ...
});
Remote references in schemas
Your schemas can include remote references that should be real URIs (more on that here) so validator can make a request and download the schema needed. Validator automatically caches these remote requests so they are not repeated with every validation.
In case you don't have a real server or you'd like to load files from different location, you can preload remote locations into the validator like this:
var fileContent = fs.readFileSync(__dirname + '/../json_schema_test_suite/remotes/integer.json', 'utf8');
ZSchema.setRemoteReference('http://localhost:1234/integer.json', fileContent);
http://localhost:1234/integer.json
doesn't have to be online now, all schemas
referencing it will validate against string
that was passed to the function.
Advanced Usage
You can pre-compile schemas (for example on your server startup) so your application is not bothered by schema compilation and validation when validating ingoing / outgoing objects.
Promises:
var validator = new ZSchema();
validator.compileSchema(schema)
.then(function(compiledSchema){
})
Or callback:
var validator = new ZSchema();
validator.compileSchema(schema, function (err, compiledSchema) {
assert.isUndefined(err);
...
});
Then you can re-use compiled schemas easily just the same way as non-compiled.
var validator = new ZSchema();
validator.validate(json, compiledSchema)
.then(function(report){
// ...
})
.catch(function(err){
console.error(err.errors)
})
Custom format validators
You can add validation for your own custom string formats like this: (these are added to all validator instances, because it would never make sense to have multiple functions to validate format with the same name)
var validator = new ZSchema();
ZSchema.registerFormat('xstring', function (str) {
return str === 'xxx'; // return true/false as a result of validation
});
validator.validate('xxx', {
'type': 'string',
'format': 'xstring'
})
.then(function(){})
.catch(function(err){})
Custom validators can also be async:
Using promises:
ZSchema.registerFormat('xstring', function (str) {
return Q.delay(1000).thenResolve(return str === 'xxx'); // return a promise for validation result
});
Using classic callback:
ZSchema.registerFormat('xstring', function (str, callback) {
setTimeout(function(){
callback(null, str === 'xxx');
// or return custom error: callback(new Error('Bad, bad value!'))
}, 2000)
});
Any exception thrown (or returned via classic callback) in custom validation function is written into validation error:
ZSchema.registerFormat('xstring', function (str) {
throw new Error('Bad, bad value!');
});
And then expect errors to contain something like this:
[{ code: 'FORMAT',
message: 'xstring format validation failed: Error: Bad, bad value!',
path: '#/test',
params: { format: 'xstring', error: [Error: Bad, bad value!] } } ]
Strict validation
When creating new instance of validator, you can specify some options that will alter the validator behaviour like this:
var validator = new ZSchema({
option: true
});
- noExtraKeywords:
true/false
when true, do not allow unknown keywords in schema
- noZeroLengthStrings:
true/false
when true, always adds minLength: 1 to schemas where type is string
- noTypeless:
true/false
when true, every schema must specify a type
- forceAdditional:
true/false
when true, forces not to leave out some keys on schemas (additionalProperties, additionalItems)
- forceProperties:
true/false
when true, forces not to leave out properties or patternProperties on type-object schemas
- forceItems:
true/false
when true, forces not to leave out items on array-type schemas
- forceMaxLength:
true/false
when true, forces not to leave out maxLength on string-type schemas, when format or enum is not specified
Alternatively, you can turn on all of the above options with:
var validator = new ZSchema({
strict: true
});
More options
- noSchemaCache:
true/false
when true, disables caching of compiled schemas - cache is used to resolve references to other schemas by their ID
- strictUris:
true/false
when true, uri's need to be in full rfc3986 format, by default checks for uri-fragment, more info in #18
Pull requests
Avoid JSHint errors - settings for the JSHint are specified in .jshintrc
.
You can check for errors using grunt
command which runs both jshint and mocha tests.
Please check for errors before opening any pull requests.
Credits
- Written by Martin Zagora, zaggino@gmail.com
- Thanks to Oleksiy Krivoshey, oleksiyk@gmail.com for refactoring and new API (version 2.x) and bugfixing