www.aleph1.co.uk Git - yaffs-website/blob - node_modules/is-my-json-valid/README.md

   1 # is-my-json-valid
   2
   3 A [JSONSchema](http://json-schema.org/) validator that uses code generation
   4 to be extremely fast
   5
   6 ```
   7 npm install is-my-json-valid
   8 ```
   9
  10 It passes the entire JSONSchema v4 test suite except for `remoteRefs` and `maxLength`/`minLength` when using unicode surrogate pairs.
  11
  12 [![build status](http://img.shields.io/travis/mafintosh/is-my-json-valid.svg?style=flat)](http://travis-ci.org/mafintosh/is-my-json-valid)
  13
  14 ## Usage
  15
  16 Simply pass a schema to compile it
  17
  18 ``` js
  19 var validator = require('is-my-json-valid')
  20
  21 var validate = validator({
  22   required: true,
  23   type: 'object',
  24   properties: {
  25     hello: {
  26       required: true,
  27       type: 'string'
  28     }
  29   }
  30 })
  31
  32 console.log('should be valid', validate({hello: 'world'}))
  33 console.log('should not be valid', validate({}))
  34
  35 // get the last list of errors by checking validate.errors
  36 // the following will print [{field: 'data.hello', message: 'is required'}]
  37 console.log(validate.errors)
  38 ```
  39
  40 You can also pass the schema as a string
  41
  42 ``` js
  43 var validate = validator('{"type": ... }')
  44 ```
  45
  46 Optionally you can use the require submodule to load a schema from `__dirname`
  47
  48 ``` js
  49 var validator = require('is-my-json-valid/require')
  50 var validate = validator('my-schema.json')
  51 ```
  52
  53 ## Custom formats
  54
  55 is-my-json-valid supports the formats specified in JSON schema v4 (such as date-time).
  56 If you want to add your own custom formats pass them as the formats options to the validator
  57
  58 ``` js
  59 var validate = validator({
  60   type: 'string',
  61   required: true,
  62   format: 'only-a'
  63 }, {
  64   formats: {
  65     'only-a': /^a+$/
  66   }
  67 })
  68
  69 console.log(validate('aa')) // true
  70 console.log(validate('ab')) // false
  71 ```
  72
  73 ## External schemas
  74
  75 You can pass in external schemas that you reference using the `$ref` attribute as the `schemas` option
  76
  77 ``` js
  78 var ext = {
  79   required: true,
  80   type: 'string'
  81 }
  82
  83 var schema = {
  84   $ref: '#ext' // references another schema called ext
  85 }
  86
  87 // pass the external schemas as an option
  88 var validate = validator(schema, {schemas: {ext: ext}})
  89
  90 validate('hello') // returns true
  91 validate(42) // return false
  92 ```
  93
  94 ## Filtering away additional properties
  95
  96 is-my-json-valid supports filtering away properties not in the schema
  97
  98 ``` js
  99 var filter = validator.filter({
 100   required: true,
 101   type: 'object',
 102   properties: {
 103     hello: {type: 'string', required: true}
 104   },
 105   additionalProperties: false
 106 })
 107
 108 var doc = {hello: 'world', notInSchema: true}
 109 console.log(filter(doc)) // {hello: 'world'}
 110 ```
 111
 112 ## Verbose mode outputs the value on errors
 113
 114 is-my-json-valid outputs the value causing an error when verbose is set to true
 115
 116 ``` js
 117 var validate = validator({
 118   required: true,
 119   type: 'object',
 120   properties: {
 121     hello: {
 122       required: true,
 123       type: 'string'
 124     }
 125   }
 126 }, {
 127   verbose: true
 128 })
 129
 130 validate({hello: 100});
 131 console.log(validate.errors) // {field: 'data.hello', message: 'is the wrong type', value: 100, type: 'string'}
 132 ```
 133
 134 ## Greedy mode tries to validate as much as possible
 135
 136 By default is-my-json-valid bails on first validation error but when greedy is
 137 set to true it tries to validate as much as possible:
 138
 139 ``` js
 140 var validate = validator({
 141   type: 'object',
 142   properties: {
 143     x: {
 144       type: 'number'
 145     }
 146   },
 147   required: ['x', 'y']
 148 }, {
 149   greedy: true
 150 });
 151
 152 validate({x: 'string'});
 153 console.log(validate.errors) // [{field: 'data.y', message: 'is required'},
 154                              //  {field: 'data.x', message: 'is the wrong type'}]
 155 ```
 156
 157 ## Error messages
 158
 159 Here is a list of possible `message` values for errors:
 160
 161 * `is required`
 162 * `is the wrong type`
 163 * `has additional items`
 164 * `must be FORMAT format` (FORMAT is the `format` property from the schema)
 165 * `must be unique`
 166 * `must be an enum value`
 167 * `dependencies not set`
 168 * `has additional properties`
 169 * `referenced schema does not match`
 170 * `negative schema matches`
 171 * `pattern mismatch`
 172 * `no schemas match`
 173 * `no (or more than one) schemas match`
 174 * `has a remainder`
 175 * `has more properties than allowed`
 176 * `has less properties than allowed`
 177 * `has more items than allowed`
 178 * `has less items than allowed`
 179 * `has longer length than allowed`
 180 * `has less length than allowed`
 181 * `is less than minimum`
 182 * `is more than maximum`
 183
 184 ## Performance
 185
 186 is-my-json-valid uses code generation to turn your JSON schema into basic javascript code that is easily optimizeable by v8.
 187
 188 At the time of writing, is-my-json-valid is the __fastest validator__ when running
 189
 190 * [json-schema-benchmark](https://github.com/Muscula/json-schema-benchmark)
 191 * [cosmicreals.com benchmark](http://cosmicrealms.com/blog/2014/08/29/benchmark-of-node-dot-js-json-validation-modules-part-3/)
 192 * [jsck benchmark](https://github.com/pandastrike/jsck/issues/72#issuecomment-70992684)
 193 * [themis benchmark](https://cdn.rawgit.com/playlyfe/themis/master/benchmark/results.html)
 194 * [z-schema benchmark](https://rawgit.com/zaggino/z-schema/master/benchmark/results.html)
 195
 196 If you know any other relevant benchmarks open a PR and I'll add them.
 197
 198 ## License
 199
 200 MIT