diff options
Diffstat (limited to 'node_modules/is-my-json-valid/README.md')
-rw-r--r-- | node_modules/is-my-json-valid/README.md | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/node_modules/is-my-json-valid/README.md b/node_modules/is-my-json-valid/README.md new file mode 100644 index 000000000..47350d84f --- /dev/null +++ b/node_modules/is-my-json-valid/README.md @@ -0,0 +1,173 @@ +# is-my-json-valid + +A [JSONSchema](http://json-schema.org/) validator that uses code generation +to be extremely fast + +``` +npm install is-my-json-valid +``` + +It passes the entire JSONSchema v4 test suite except for `remoteRefs` and `maxLength`/`minLength` when using unicode surrogate pairs. + +[![build status](http://img.shields.io/travis/mafintosh/is-my-json-valid.svg?style=flat)](http://travis-ci.org/mafintosh/is-my-json-valid) + +## Usage + +Simply pass a schema to compile it + +``` js +var validator = require('is-my-json-valid') + +var validate = validator({ + required: true, + type: 'object', + properties: { + hello: { + required: true, + type: 'string' + } + } +}) + +console.log('should be valid', validate({hello: 'world'})) +console.log('should not be valid', validate({})) + +// get the last list of errors by checking validate.errors +// the following will print [{field: 'data.hello', message: 'is required'}] +console.log(validate.errors) +``` + +You can also pass the schema as a string + +``` js +var validate = validate('{"type": ... }') +``` + +Optionally you can use the require submodule to load a schema from `__dirname` + +``` js +var validator = require('is-my-json-valid/require') +var validate = validator('my-schema.json') +``` + +## Custom formats + +is-my-json-valid supports the formats specified in JSON schema v4 (such as date-time). +If you want to add your own custom formats pass them as the formats options to the validator + +``` js +var validate = validator({ + type: 'string', + required: true, + format: 'only-a' +}, { + formats: { + 'only-a': /^a+$/ + } +}) + +console.log(validate('aa')) // true +console.log(validate('ab')) // false +``` + +## External schemas + +You can pass in external schemas that you reference using the `$ref` attribute as the `schemas` option + +``` js +var ext = { + required: true, + type: 'string' +} + +var schema = { + $ref: '#ext' // references another schema called ext +} + +// pass the external schemas as an option +var validate = validate(schema, {schemas: {ext: ext}}) + +validate('hello') // returns true +validate(42) // return false +``` + +## Filtering away additional properties + +is-my-json-valid supports filtering away properties not in the schema + +``` js +var filter = validator.filter({ + required: true, + type: 'object', + properties: { + hello: {type: 'string', required: true} + }, + additionalProperties: false +}) + +var doc = {hello: 'world', notInSchema: true} +console.log(filter(doc)) // {hello: 'world'} +``` + +## Verbose mode outputs the value on errors + +is-my-json-valid outputs the value causing an error when verbose is set to true + +``` js +var validate = validator({ + required: true, + type: 'object', + properties: { + hello: { + required: true, + type: 'string' + } + } +}, { + verbose: true +}) + +validate({hello: 100}); +console.log(validate.errors) // {field: 'data.hello', message: 'is the wrong type', value: 100} +``` + +## Greedy mode tries to validate as much as possible + +By default is-my-json-valid bails on first validation error but when greedy is +set to true it tries to validate as much as possible: + +``` js +var validate = validator({ + type: 'object', + properties: { + x: { + type: 'number' + } + }, + required: ['x', 'y'] +}, { + greedy: true +}); + +validate({x: 'string'}); +console.log(validate.errors) // [{field: 'data.y', message: 'is required'}, + // {field: 'data.x', message: 'is the wrong type'}] +``` + +## Performance + +is-my-json-valid uses code generation to turn your JSON schema into basic javascript code that is easily optimizeable by v8. + +At the time of writing, is-my-json-valid is the __fastest validator__ when running + +* [json-schema-benchmark](https://github.com/Muscula/json-schema-benchmark) +* [cosmicreals.com benchmark](http://cosmicrealms.com/blog/2014/08/29/benchmark-of-node-dot-js-json-validation-modules-part-3/) +* [jsck benchmark](https://github.com/pandastrike/jsck/issues/72#issuecomment-70992684) +* [themis benchmark](https://cdn.rawgit.com/playlyfe/themis/master/benchmark/results.html) +* [z-schema benchmark](https://rawgit.com/zaggino/z-schema/master/benchmark/results.html) + +If you know any other relevant benchmarks open a PR and I'll add them. + +## License + +MIT |