API reference

Every export of schiva, with its options. The guide explains how to use them together; this page is the list to come back to. Everything is exported from schiva, with require and with import.

compileJsonSchema(json, options)

Compiles a JSON Schema (draft-04 to 2020-12) into a validation function. The function returns the errors of a value: [] when it is valid. What it returns depends on the compile options; the JSON Schema options choose how the schema is read. It throws when the schema is not supported (an unknown keyword, a reference that does not resolve...), with the place in the schema.

const validate = compileJsonSchema({ type: 'object', properties: { age: { type: 'integer', minimum: 0 } } });
validate({ age: -1 }); // ['age must be at least 0']

const isValid = compileJsonSchema(schema, { errors: false }); // (value) => true or false
const firstError = compileJsonSchema(schema, { allErrors: false }); // [] or [the first error]
const withObjects = compileJsonSchema(schema, { errors: 'objects' }); // error objects

In TypeScript, compileJsonSchema<T>(json, { errors: false }) is a type guard for T.

compileJsonSchemaAsync(json, options)

The same, for a schema that references documents to load first: a promise of the validation function. It calls options.loadSchema(uri), an async function you write, for each document the schema reaches and options.schemas does not have, and for the ones those reference in turn, once each. A reference relative to a schema without $id is not loaded; an error of loadSchema rejects the promise.

const validate = await compileJsonSchemaAsync(schema, {
  loadSchema: async (uri) => (await fetch(uri)).json(),
});

loadJsonSchemas(json, options)

Loads the same documents without compiling: a promise of options.schemas with them added, as { uri: schema }, to pass to compileJsonSchema() or standaloneJsonSchema() later.

fromJsonSchema(json, options)

Converts a JSON Schema into schiva types, with the same JSON Schema options, without compiling: the result has validate(value), isValid(value) and compile(options) like any type. compileJsonSchema(json, options) is compileType(fromJsonSchema(json, options), options).

type.compile(options) and compileType(type, options)

Compile a DSL schema or any type into a validation function, with the compile options: type.compile(options) and compileType(type, options) are the same. Compile once, when the program starts, and keep the function. Three older functions compile one mode each:

Compile options

JSON Schema options

For compileJsonSchema(), compileJsonSchemaAsync(), loadJsonSchemas(), fromJsonSchema() and standaloneJsonSchema(), next to the compile options:

standaloneJsonSchema, standaloneCode and standaloneModule

Write validators out as the source of a JavaScript module, to save to a file when building: loading it generates no code, so it runs under a strict Content Security Policy, and it needs nothing else, not even schiva. Each one takes the compile options, and format: 'commonjs' (default) or 'esm'.

fs.writeFileSync('validate-order.js', standaloneJsonSchema(orderSchema, { format: 'esm', formats: true }));
fs.writeFileSync('validators.cjs', standaloneModule({ order, customer }, { errors: 'objects' }));

Everything the schema needs is written into the module: the built-in formats, error objects, defaults and the keywords that are macros or regular expressions. Functions of your own cannot be written out: types of your own, keywords with validate or compile, and formats given as functions throw a message naming them.

inferJsonSchema(samples, options) and inferSchemaCode(samples, options)

The schema of a list of sample values (a single value goes in a list), merged from all of them: a key is required when every object at that place has it, null makes a value nullable, integers and numbers make a number, array elements are merged, and strings get a format every one of them matches (see Schemas from samples, or try Schema from JSON). inferJsonSchema() returns a JSON Schema object; inferSchemaCode() returns the source of a module that builds the same schema with the DSL.

Values that are not JSON (functions, Date objects, NaN) throw, naming where they are; keys whose value is undefined are taken as absent.

Common options and methods of the types

Every DSL type takes these options and has these methods:

Wherever a type is expected, a plain object stands for new Schema(object) (an open schema). A value that is neither a type nor an object of types throws when the type is built.

new Schema(shape, options) and new ClosedSchema(shape, options)

A schema for objects: each key of shape is an expected property with its type. Declared keys are read as own properties only. ClosedSchema is a Schema with isOpen: false.

const config = new ClosedSchema(
  { name: String(), port: Integer({ min: 1, max: 65535 }), tls: Boolean().optional(), cert: String().optional() },
  { patternTypes: [{ pattern: /^x-/, type: Any() }], dependencies: [{ key: 'tls', required: ['cert'] }] }
);
config.compile()({ name: 'api', port: 443, tls: true, 'x-team': 'a', debug: true });
// ['Unexpected key: debug', 'cert is mandatory when tls is present']

String, Integer, Float and Boolean

Enum, Values and Const

ArrayOf(options)

ArrayOf({ type: [String(), Integer()], additionalType: Boolean(), min: 2 }); // ['a', 1, true, false]

AnyOf, AllOf, OneOf and Not

Conditional and When

Conditional({
  ifType: { country: Const('US') },
  thenType: { zip: String({ pattern: /^\d{5}$/ }) },
  elseType: { zip: String() },
});

Any, Never, Obj and Ref

Short helpers

Functions with positional arguments, for short schemas. Each has an optional version starting with o (isMandatory defaults to false).

ValidateType

The base class of every type. Extend it (or a built-in type) with your own validate(value, fieldName) returning undefined or a message, and optionally a faster isValid(value); the compiled code calls them for their part of a schema. super.validate(value, fieldName) checks isMandatory and isNullable. checkPresence(value) gives the verdict for undefined and null (undefined for other values). See Types of your own.

Keyword definitions

Items of the JSON Schema option keywords that check values:

A definition has exactly one of validate, compile and macro. Compiled, a keyword becomes a KeywordType ({ keyword, check, message, jsonTypes }), which can also be used in the DSL.

ajvKeywords(names)

Definitions of the keywords of ajv-keywords, with the same results: all of them, or the ones named (a name or a list). transform, dynamicDefaults and select throw, with the reason.

Formats of your own

In the JSON Schema option formats, a name maps to true (a built-in format), false (a format that is known but not checked, as OpenAPI's int32), a regular expression, a function (string) => boolean, or { validate, compare }, whose compare(a, b) gives a negative number, 0 or a positive number, so that formatMinimum, formatMaximum, formatExclusiveMinimum and formatExclusiveMaximum can limit its values.

compileJsonSchema(schema, {
  formats: {
    date: true,
    sku: /^SKU-\d+$/,
    version: { validate: /^\d+\.\d+$/, compare: (a, b) => a.localeCompare(b, 'en', { numeric: true }) },
  },
});

builtInFormats() gives every built-in format as { date: true, ... }, to check them all and add others: formats: { ...builtInFormats(), int32: false, sku: /^SKU-\d+$/ }. With strict (the default), a format the option does not name throws when compiling.

validate() results, toErrors and hasErrors

type.validate(value) (without compiling) returns undefined when the value is valid, a message, or a list that may nest lists (combinations collect the errors of their parts). toErrors(result) gives its messages as a flat list, each once, as the compiled function gives them; hasErrors(result) tells whether it has any.

toErrors(schema.validate(value)); // ['name is mandatory', ...]
hasErrors(schema.validate(value)); // true

Error objects

With errors: 'objects', each error is an object:

Messages and keywords

Every message starts with the name of the value (lines[0].price, or Value for the value itself). The keyword and params are the ones of error objects.

TypeScript types