source: trip-planner-front/node_modules/ajv-formats/README.md@ 6a3a178

Last change on this file since 6a3a178 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 5.9 KB
Line 
1# ajv-formats
2
3JSON Schema formats for Ajv
4
5[![Build Status](https://travis-ci.org/ajv-validator/ajv-formats.svg?branch=master)](https://travis-ci.org/ajv-validator/ajv-formats)
6[![npm](https://img.shields.io/npm/v/ajv-formats.svg)](https://www.npmjs.com/package/ajv-formats)
7[![Gitter](https://img.shields.io/gitter/room/ajv-validator/ajv.svg)](https://gitter.im/ajv-validator/ajv)
8[![GitHub Sponsors](https://img.shields.io/badge/$-sponsors-brightgreen)](https://github.com/sponsors/epoberezkin)
9
10## Usage
11
12```javascript
13// ESM/TypeScript import
14import Ajv from "ajv"
15import addFormats from "ajv-formats"
16// Node.js require:
17const Ajv = require("ajv")
18const addFormats = require("ajv-formats")
19
20const ajv = new Ajv()
21addFormats(ajv)
22```
23
24## Formats
25
26The package defines these formats:
27
28- _date_: full-date according to [RFC3339](http://tools.ietf.org/html/rfc3339#section-5.6).
29- _time_: time with optional time-zone.
30- _date-time_: date-time from the same source (time-zone is mandatory).
31- _duration_: duration from [RFC3339](https://tools.ietf.org/html/rfc3339#appendix-A)
32- _uri_: full URI.
33- _uri-reference_: URI reference, including full and relative URIs.
34- _uri-template_: URI template according to [RFC6570](https://tools.ietf.org/html/rfc6570)
35- _url_ (deprecated): [URL record](https://url.spec.whatwg.org/#concept-url).
36- _email_: email address.
37- _hostname_: host name according to [RFC1034](http://tools.ietf.org/html/rfc1034#section-3.5).
38- _ipv4_: IP address v4.
39- _ipv6_: IP address v6.
40- _regex_: tests whether a string is a valid regular expression by passing it to RegExp constructor.
41- _uuid_: Universally Unique IDentifier according to [RFC4122](http://tools.ietf.org/html/rfc4122).
42- _json-pointer_: JSON-pointer according to [RFC6901](https://tools.ietf.org/html/rfc6901).
43- _relative-json-pointer_: relative JSON-pointer according to [this draft](http://tools.ietf.org/html/draft-luff-relative-json-pointer-00).
44- _byte_: base64 encoded data according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
45- _int32_: signed 32 bits integer according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
46- _int64_: signed 64 bits according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
47- _float_: float according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
48- _double_: double according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
49- _password_: password string according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
50- _binary_: binary string according to the [openApi 3.0.0 specification](https://spec.openapis.org/oas/v3.0.0#data-types)
51
52See regular expressions used for format validation and the sources that were used in [formats.ts](https://github.com/ajv-validator/ajv-formats/blob/master/src/formats.ts).
53
54**Please note**: JSON Schema draft-07 also defines formats `iri`, `iri-reference`, `idn-hostname` and `idn-email` for URLs, hostnames and emails with international characters. These formats are available in [ajv-formats-draft2019](https://github.com/luzlab/ajv-formats-draft2019) plugin.
55
56## Keywords to compare values: `formatMaximum` / `formatMinimum` and `formatExclusiveMaximum` / `formatExclusiveMinimum`
57
58These keywords allow to define minimum/maximum constraints when the format keyword defines ordering (`compare` function in format definition).
59
60These keywords are added to ajv instance when ajv-formats is used without options or with option `keywords: true`.
61
62These keywords apply only to strings. If the data is not a string, the validation succeeds.
63
64The value of keywords `formatMaximum`/`formatMinimum` and `formatExclusiveMaximum`/`formatExclusiveMinimum` should be a string or [\$data reference](https://github.com/ajv-validator/ajv/blob/master/docs/validation.md#data-reference). This value is the maximum (minimum) allowed value for the data to be valid as determined by `format` keyword. If `format` keyword is not present schema compilation will throw exception.
65
66When these keyword are added, they also add comparison functions to formats `"date"`, `"time"` and `"date-time"`. User-defined formats also can have comparison functions. See [addFormat](https://github.com/ajv-validator/ajv/blob/master/docs/api.md#api-addformat) method.
67
68```javascript
69require("ajv-formats")(ajv)
70
71const schema = {
72 type: "string",
73 format: "date",
74 formatMinimum: "2016-02-06",
75 formatExclusiveMaximum: "2016-12-27",
76}
77
78const validDataList = ["2016-02-06", "2016-12-26"]
79
80const invalidDataList = ["2016-02-05", "2016-12-27", "abc"]
81```
82
83## Options
84
85Options can be passed via the second parameter. Options value can be
86
871. The list of format names that will be added to ajv instance:
88
89```javascript
90addFormats(ajv, ["date", "time"])
91```
92
93**Please note**: when ajv encounters an undefined format it throws exception (unless ajv instance was configured with `strict: false` option). To allow specific undefined formats they have to be passed to ajv instance via `formats` option with `true` value:
94
95```javascript
96const ajv = new Ajv((formats: {date: true, time: true})) // to ignore "date" and "time" formats in schemas.
97```
98
992. Format validation mode (default is `"full"`) with optional list of format names and `keywords` option to add additional format comparison keywords:
100
101```javascript
102addFormats(ajv, {mode: "fast"})
103```
104
105or
106
107```javascript
108addFormats(ajv, {mode: "fast", formats: ["date", "time"], keywords: true})
109```
110
111In `"fast"` mode the following formats are simplified: `"date"`, `"time"`, `"date-time"`, `"uri"`, `"uri-reference"`, `"email"`. For example `"date"`, `"time"` and `"date-time"` do not validate ranges in `"fast"` mode, only string structure, and other formats have simplified regular expressions.
112
113## Tests
114
115```bash
116npm install
117git submodule update --init
118npm test
119```
120
121## License
122
123[MIT](https://github.com/ajv-validator/ajv-formats/blob/master/LICENSE)
Note: See TracBrowser for help on using the repository browser.