diff options
Diffstat (limited to 'node_modules/ajv-keywords/README.md')
| -rw-r--r-- | node_modules/ajv-keywords/README.md | 343 |
1 files changed, 278 insertions, 65 deletions
diff --git a/node_modules/ajv-keywords/README.md b/node_modules/ajv-keywords/README.md index e432391d6..9334531a0 100644 --- a/node_modules/ajv-keywords/README.md +++ b/node_modules/ajv-keywords/README.md @@ -1,11 +1,13 @@ # ajv-keywords -Custom JSON-Schema keywords for [ajv](https://github.com/epoberezkin/ajv) validator +Custom JSON-Schema keywords for [Ajv](https://github.com/epoberezkin/ajv) validator [](https://travis-ci.org/epoberezkin/ajv-keywords) [](https://www.npmjs.com/package/ajv-keywords) [](https://www.npmjs.com/package/ajv-keywords) [](https://coveralls.io/github/epoberezkin/ajv-keywords?branch=master) +[](https://greenkeeper.io/) +[](https://gitter.im/ajv-validator/ajv) ## Contents @@ -16,12 +18,16 @@ Custom JSON-Schema keywords for [ajv](https://github.com/epoberezkin/ajv) valida - [typeof](#typeof) - [instanceof](#instanceof) - [range and exclusiveRange](#range-and-exclusiverange) - - [propertyNames](#propertynames) - [if/then/else](#ifthenelse) + - [switch](#switch) + - [select/selectCases/selectDefault](#selectselectcasesselectdefault) (BETA) + - [patternRequired](#patternrequired) - [prohibited](#prohibited) - [deepProperties](#deepproperties) - [deepRequired](#deeprequired) + - [uniqueItemProperties](#uniqueitemproperties) - [regexp](#regexp) + - [formatMaximum / formatMinimum and formatExclusiveMaximum / formatExclusiveMinimum](#formatmaximum--formatminimum-and-formatexclusivemaximum--formatexclusiveminimum) - [dynamicDefaults](#dynamicdefaults) - [License](#license) @@ -93,7 +99,7 @@ To pass validation the result of `data instanceof ...` operation on the value sh ``` ajv.validate({ instanceof: 'Array' }, []); // true ajv.validate({ instanceof: 'Array' }, {}); // false -ajv.validate({ instanceof: ['Array', 'Function'] }, funciton(){}); // true +ajv.validate({ instanceof: ['Array', 'Function'] }, function(){}); // true ``` You can add your own constructor function to be recognised by this keyword: @@ -133,66 +139,200 @@ ajv.validate(schema, 3); // false ``` -### `propertyNames` +### `if`/`then`/`else` + +These keywords allow to implement conditional validation. Their values should be valid JSON-schemas. -This keyword allows to define the schema for the property names of the object. The value of this keyword should be a valid JSON schema (v5 schemas are supported with Ajv option `{v5: true}`). +If the data is valid according to the sub-schema in `if` keyword, then the result is equal to the result of data validation against the sub-schema in `then` keyword, otherwise - in `else` keyword (if `else` is absent, the validation succeeds). ```javascript +require('ajv-keywords')(ajv, 'if'); + var schema = { - type: 'object' - propertyNames: { - anyOf: [ - { format: ipv4 }, - { format: hostname } - ] + type: 'array', + items: { + type: 'integer', + minimum: 1, + if: { maximum: 10 }, + then: { multipleOf: 2 }, + else: { multipleOf: 5 } } }; -var validData = { - '192.128.0.1': {}, - 'test.example.com': {} -}; +var validItems = [ 2, 4, 6, 8, 10, 15, 20, 25 ]; // etc. -var invalidData = { - '1.2.3': {} -}; +var invalidItems = [ 1, 3, 5, 11, 12 ]; // etc. -ajv.validate(schema, validData); // true -ajv.validate(schema, invalidData); // false +ajv.validate(schema, validItems); // true +ajv.validate(schema, invalidItems); // false ``` -__Please note__: This keyword will be added to the next version of the JSON-Schema standard (draft-6), after it is published the keyword will be included in Ajv as standard validation keyword. +This keyword is [proposed](https://github.com/json-schema-org/json-schema-spec/issues/180) for the future version of JSON-Schema standard. -### `if`/`then`/`else` +### `switch` -These keywords allow to implement conditional validation. Their values should be valid JSON-schemas. At the moment it requires using Ajv with v5 option. +This keyword allows to perform advanced conditional validation. -If the data is valid according to the sub-schema in `if` keyword, then the result is equal to the result of data validation against the sub-schema in `then` keyword, otherwise - in `else` keyword (if `else` is absent, the validation succeeds). +The value of the keyword is the array of if/then clauses. Each clause is the object with the following properties: + +- `if` (optional) - the value is JSON-schema +- `then` (required) - the value is JSON-schema or boolean +- `continue` (optional) - the value is boolean + +The validation process is dynamic; all clauses are executed sequentially in the following way: + +1. `if`: + 1. `if` property is JSON-schema according to which the data is: + 1. valid => go to step 2. + 2. invalid => go to the NEXT clause, if this was the last clause the validation of `switch` SUCCEEDS. + 2. `if` property is absent => go to step 2. +2. `then`: + 1. `then` property is `true` or it is JSON-schema according to which the data is valid => go to step 3. + 2. `then` property is `false` or it is JSON-schema according to which the data is invalid => the validation of `switch` FAILS. +3. `continue`: + 1. `continue` property is `true` => go to the NEXT clause, if this was the last clause the validation of `switch` SUCCEEDS. + 2. `continue` property is `false` or absent => validation of `switch` SUCCEEDS. ```javascript -require('ajv-keywords')(ajv, 'if'); +require('ajv-keywords')(ajv, 'switch'); var schema = { type: 'array', items: { type: 'integer', - minimum: 1, - if: { maximum: 10 }, - then: { multipleOf: 2 }, - else: { multipleOf: 5 } + 'switch': [ + { if: { not: { minimum: 1 } }, then: false }, + { if: { maximum: 10 }, then: true }, + { if: { maximum: 100 }, then: { multipleOf: 10 } }, + { if: { maximum: 1000 }, then: { multipleOf: 100 } }, + { then: false } + ] } }; -var validItems = [ 2, 4, 6, 8, 10, 15, 20, 25 ]; // etc. +var validItems = [1, 5, 10, 20, 50, 100, 200, 500, 1000]; -var invalidItems = [ 1, 3, 5, 11, 12 ]; // etc. +var invalidItems = [1, 0, 2000, 11, 57, 123, 'foo']; +``` -ajv.validate(schema, validItems); // true -ajv.validate(schema, invalidItems); // false +__Please note__: this keyword is moved here from Ajv, mainly to preserve beckward compatibility. It is unlikely to become a standard. It's preferreable to use `if`/`then`/`else` keywords if possible, as they are likely to be added to the standard. The above schema is equivalent to (for example): + +```javascript +{ + type: 'array', + items: { + type: 'integer', + if: { minimum: 1, maximum: 10 }, + then: true, + else: { + if: { maximum: 100 }, + then: { multipleOf: 10 }, + else: { + if: { maximum: 1000 }, + then: { multipleOf: 100 }, + else: false + } + } + } +} ``` -This keyword is [proposed](https://github.com/json-schema-org/json-schema-spec/issues/180) for the future version of JSON-Schema standard. + +### `select`/`selectCases`/`selectDefault` + +These keywords allow to choose the schema to validate the data based on the value of some property in the validated data. + +These keywords must be present in the same schema object (`selectDefault` is optional). + +The value of `select` keyword should be a [$data reference](https://github.com/epoberezkin/ajv/tree/5.0.2-beta.0#data-reference) that points to any primitive JSON type (string, number, boolean or null) in the data that is validated. You can also use a constant of primitive type as the value of this keyword (e.g., for debugging purposes). + +The value of `selectCases` keyword must be an object where each property name is a possible string representation of the value of `select` keyword and each property value is a corresponding schema (from draft-06 it can be boolean) that must be used to validate the data. + +The value of `selectDefault` keyword is a schema (from draft-06 it can be boolean) that must be used to validate the data in case `selectCases` has no key equal to the stringified value of `select` keyword. + +The validation succeeds in one of the following cases: +- the validation of data using selected schema succeeds, +- none of the schemas is selected for validation, +- the value of select is undefined (no property in the data that the data reference points to). + +If `select` value (in data) is not a primitive type the validation fails. + +__Please note__: these keywords require Ajv `$data` option to support [$data reference](https://github.com/epoberezkin/ajv/tree/5.0.2-beta.0#data-reference). + + +```javascript +require('ajv-keywords')(ajv, 'select'); + +var schema = { + type: object, + required: ['kind'], + properties: { + kind: { type: 'string' } + }, + select: { $data: '0/kind' }, + selectCases: { + foo: { + required: ['foo'], + properties: { + kind: {}, + foo: { type: 'string' } + }, + additionalProperties: false + }, + bar: { + required: ['bar'], + properties: { + kind: {}, + bar: { type: 'number' } + }, + additionalProperties: false + } + }, + selectDefault: { + propertyNames: { + not: { enum: ['foo', 'bar'] } + } + } +}; + +var validDataList = [ + { kind: 'foo', foo: 'any' }, + { kind: 'bar', bar: 1 }, + { kind: 'anything_else', not_bar_or_foo: 'any value' } +]; + +var invalidDataList = [ + { kind: 'foo' }, // no propery foo + { kind: 'bar' }, // no propery bar + { kind: 'foo', foo: 'any', another: 'any value' }, // additional property + { kind: 'bar', bar: 1, another: 'any value' }, // additional property + { kind: 'anything_else', foo: 'any' } // property foo not allowed + { kind: 'anything_else', bar: 1 } // property bar not allowed +]; +``` + +__Please note__: the current implementation is BETA. It does not allow using relative URIs in $ref keywords in schemas in `selectCases` and `selectDefault` that point ouside of these schemas. The workaround is to use absolute URIs (that can point to any (sub-)schema added to Ajv, including those inside the current root schema where `select` is used). See [tests](https://github.com/epoberezkin/ajv-keywords/blob/v2.0.0/spec/tests/select.json#L314). + + +### `patternRequired` + +This keyword allows to require the presense of properties that match some pattern(s). + +This keyword applies only to objects. If the data is not an object, the validation succeeds. + +The value of this keyword should be an array of strings, each string being a regular expression. For data object to be valid each regular expression in this array should match at least one property name in the data object. + +If the array contains multiple regular expressions, more than one expression can match the same property name. + +```javascript +var schema = { patternRequired: [ 'f.*o', 'b.*r' ] }; + +var validData = { foo: 1, bar: 2 }; +var alsoValidData = { foobar: 3 }; + +var invalidDataList = [ {}, { foo: 1 }, { bar: 2 } ]; +``` ### `prohibited` @@ -217,14 +357,20 @@ var invalidDataList = [ ``` -### `deepRequired` +### `deepProperties` -This keyword allows to check that some deep properties (identified by JSON pointers) are available. The value should be an array of JSON pointers to the data, starting from the current position in data. +This keyword allows to validate deep properties (identified by JSON pointers). + +This keyword applies only to objects. If the data is not an object, the validation succeeds. + +The value should be an object, where keys are JSON pointers to the data, starting from the current position in data, and the values are JSON schemas. For data object to be valid the value of each JSON pointer should be valid according to the corresponding schema. ```javascript var schema = { type: 'object', - deepRequired: ["/users/1/role"] + deepProperties: { + "/users/1/role": { "enum": ["admin"] } + } }; var validData = { @@ -237,29 +383,48 @@ var validData = { ] }; +var alsoValidData = { + users: { + "1": { + id: 123, + role: 'admin' + } + } +}; + var invalidData = { users: [ {}, { - id: 123 + id: 123, + role: 'user' } ] }; + +var alsoInvalidData = { + users: { + "1": { + id: 123, + role: 'user' + } + } +}; ``` -See [json-schema-org/json-schema-spec#203](https://github.com/json-schema-org/json-schema-spec/issues/203#issue-197211916) for an example of the equivalent schema without `deepRequired` keyword. +### `deepRequired` + +This keyword allows to check that some deep properties (identified by JSON pointers) are available. -## `deepProperties` +This keyword applies only to objects. If the data is not an object, the validation succeeds. -This keyword allows to validate deep properties (identified by JSON pointers). The value should be an object, where keys are JSON pointers to the data, starting from the current position in data, and the values are corresponding schemas. +The value should be an array of JSON pointers to the data, starting from the current position in data. For data object to be valid each JSON pointer should be some existing part of the data. ```javascript var schema = { type: 'object', - deepProperties: { - "/users/1/role": { "enum": ["admin"] } - } + deepRequired: ["/users/1/role"] }; var validData = { @@ -272,39 +437,59 @@ var validData = { ] }; -var alsoValidData = { - users: { - "1": { - id: 123, - role: 'admin' - } - } -}; - var invalidData = { users: [ {}, { - id: 123, - role: 'user' + id: 123 } ] }; +``` -var alsoInvalidData = { - users: { - "1": { - id: 123, - role: 'user' - } - } -}; +See [json-schema-org/json-schema-spec#203](https://github.com/json-schema-org/json-schema-spec/issues/203#issue-197211916) for an example of the equivalent schema without `deepRequired` keyword. + + +### `uniqueItemProperties` + +The keyword allows to check that some properties in array items are unique. + +This keyword applies only to arrays. If the data is not an array, the validation succeeds. + +The value of this keyword must be an array of strings - property names that should have unique values accross all items. + +```javascript +var schema = { uniqueItemProperties: [ "id", "name" ] }; + +var validData = [ + { id: 1 }, + { id: 2 }, + { id: 3 } +]; + +var invalidData1 = [ + { id: 1 }, + { id: 1 }, + { id: 3 } +]; + +var invalidData2 = [ + { id: 1, name: "taco" }, + { id: 2, name: "taco" }, // duplicate "name" + { id: 3, name: "salsa" } +]; ``` +This keyword is contributed by [@blainesch](https://github.com/blainesch). + ### `regexp` -This keyword allows to use regular expressions with flags in schemas (the standard `pattern` keyword does not support flags). The value of this keyword can be either a string (the result of `regexp.toString()`) or an object with the properties `pattern` and `flags` (the same strings that should be passed to RegExp constructor). +This keyword allows to use regular expressions with flags in schemas (the standard `pattern` keyword does not support flags). + +This keyword applies only to strings. If the data is not a string, the validation succeeds. + +The value of this keyword can be either a string (the result of `regexp.toString()`) or an object with the properties `pattern` and `flags` (the same strings that should be passed to RegExp constructor). ```javascript var schema = { @@ -327,6 +512,34 @@ var invalidData = { ``` +### `formatMaximum` / `formatMinimum` and `formatExclusiveMaximum` / `formatExclusiveMinimum` + +These keywords allow to define minimum/maximum constraints when the format keyword defines ordering. + +These keywords apply only to strings. If the data is not a string, the validation succeeds. + +The value of keyword `formatMaximum` (`formatMinimum`) should be a string. This value is the maximum (minimum) allowed value for the data to be valid as determined by `format` keyword. + +When this keyword is added, it defines comparison rules for formats `"date"`, `"time"` and `"date-time". Custom formats also can have comparison rules. See [addFormat](https://github.com/epoberezkin/ajv#api-addformat) method. + +The value of keyword `formatExclusiveMaximum` (`formatExclusiveMinimum`) should be a boolean value. These keyword cannot be used without `formatMaximum` (`formatMinimum`). If this keyword value is equal to `true`, the data to be valid should not be equal to the value in `formatMaximum` (`formatMinimum`) keyword. + +```javascript +require('ajv-keywords')(ajv, ['formatMinimum', 'formatMaximum']); + +var schema = { + format: 'date', + formatMinimum: '2016-02-06', + formatMaximum: '2016-12-27', + formatExclusiveMaximum: true +} + +var validDataList = ['2016-02-06', '2016-12-26', 1]; + +var invalidDataList = ['2016-02-05', '2016-12-27', 'abc']; +``` + + ### `dynamicDefaults` This keyword allows to assign dynamic defaults to properties, such as timestamps, unique IDs etc. @@ -440,4 +653,4 @@ var schema = { ## License -[MIT](https://github.com/JSONScript/ajv-keywords/blob/master/LICENSE) +[MIT](https://github.com/epoberezkin/ajv-keywords/blob/master/LICENSE) |