ajv-formats
ajv-formats copied to clipboard
JSON Schema format validation for Ajv v8+
ajv-formats
JSON Schema formats for Ajv
Usage
// ESM/TypeScript import
import Ajv from "ajv"
import addFormats from "ajv-formats"
// Node.js require:
const Ajv = require("ajv")
const addFormats = require("ajv-formats")
const ajv = new Ajv()
addFormats(ajv)
Formats
The package defines these formats:
- date: full-date according to RFC3339.
- time: time (time-zone is mandatory).
- date-time: date-time (time-zone is mandatory).
- iso-time: time with optional time-zone.
- iso-date-time: date-time with optional time-zone.
- duration: duration from RFC3339
- uri: full URI.
- uri-reference: URI reference, including full and relative URIs.
- uri-template: URI template according to RFC6570
- url (deprecated): URL record.
- email: email address.
- hostname: host name according to RFC1034.
- ipv4: IP address v4.
- ipv6: IP address v6.
- regex: tests whether a string is a valid regular expression by passing it to RegExp constructor.
- uuid: Universally Unique IDentifier according to RFC4122.
- json-pointer: JSON-pointer according to RFC6901.
- relative-json-pointer: relative JSON-pointer according to this draft.
- byte: base64 encoded data according to the openApi 3.0.0 specification
- int32: signed 32 bits integer according to the openApi 3.0.0 specification
- int64: signed 64 bits according to the openApi 3.0.0 specification
- float: float according to the openApi 3.0.0 specification
- double: double according to the openApi 3.0.0 specification
- password: password string according to the openApi 3.0.0 specification
- binary: binary string according to the openApi 3.0.0 specification
See regular expressions used for format validation and the sources that were used in formats.ts.
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 plugin.
Keywords to compare values: formatMaximum
/ formatMinimum
and formatExclusiveMaximum
/ formatExclusiveMinimum
These keywords allow to define minimum/maximum constraints when the format keyword defines ordering (compare
function in format definition).
These keywords are added to ajv instance when ajv-formats is used without options or with option keywords: true
.
These keywords apply only to strings. If the data is not a string, the validation succeeds.
The value of keywords formatMaximum
/formatMinimum
and formatExclusiveMaximum
/formatExclusiveMinimum
should be a string or $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.
When 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 method.
require("ajv-formats")(ajv)
const schema = {
type: "string",
format: "date",
formatMinimum: "2016-02-06",
formatExclusiveMaximum: "2016-12-27",
}
const validDataList = ["2016-02-06", "2016-12-26"]
const invalidDataList = ["2016-02-05", "2016-12-27", "abc"]
Options
Options can be passed via the second parameter. Options value can be
- The list of format names that will be added to ajv instance:
addFormats(ajv, ["date", "time"])
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:
const ajv = new Ajv((formats: {date: true, time: true})) // to ignore "date" and "time" formats in schemas.
- Format validation mode (default is
"full"
) with optional list of format names andkeywords
option to add additional format comparison keywords:
addFormats(ajv, {mode: "fast"})
or
addFormats(ajv, {mode: "fast", formats: ["date", "time"], keywords: true})
In "fast"
mode the following formats are simplified: "date"
, "time"
, "date-time"
, "iso-time"
, "iso-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.
Tests
npm install
git submodule update --init
npm test