Migrating from ajv

Your JSON Schemas stay as they are: schiva reads draft-04, draft-06, draft-07, 2019-09 and 2020-12, and passes the whole JSON-Schema-Test-Suite of each. What changes is the code around them: how you compile, what the function returns and how errors look. This page goes through all of it, with the few differences that can change a result.

Three ways to move

schiva is not a drop-in replacement: the schemas are the same, the API is not. Pick the path that fits:

In every case, run both libraries on your schemas and test data first: it takes a few lines and shows whether anything behaves differently for you.

Why move

• Speed. About twice as fast as ajv validating (2.1× on the JSON Schema test suite, 2.2× on realistic payloads), and 44× faster compiling. See the benchmarks.
• Correctness. schiva passes all 4,950 tests of the JSON-Schema-Test-Suite; ajv passes 4,836. Most of ajv's failures are in 2019-09 and 2020-12 (unevaluatedProperties, $dynamicRef, references).
• Readable errors. Messages name the field: lines[0].price must be at least 0 instead of must be >= 0 next to an instancePath.
• One package. Formats, ajv-keywords, draft-04, discriminator with OpenAPI's mapping, and standalone code are built in. No dependencies.

Install

npm install schiva
npm uninstall ajv ajv-formats ajv-keywords ajv-draft-04   # once nothing uses them

What changes

• No instance. ajv compiles through an Ajv object that holds options, formats and schemas. schiva compiles with a function, compileJsonSchema(schema, options), and the options go with each call. See Replacing the instance.
• Errors are returned. An ajv function returns true or false and leaves the errors in validate.errors. A schiva function returns the errors: messages by default, objects with errors: 'objects', or true/false with errors: false. Nothing is kept between calls, so it is safe with concurrent code.
• Every error by default. ajv stops at the first error unless allErrors: true. schiva reports every error unless allErrors: false.
• The draft comes from $schema, else draft-07. Ajv2019 and Ajv2020 assume their draft; with schiva, schemas without $schema need draft: '2020-12' (or '2019-09').
• Strict. An unknown keyword throws when compiling, as in ajv's strict mode, and so does a keyword the type excludes (ajv only warns with strictTypes). Declare your own annotations with keywords, or ignore them with strict: false.
• The data is not changed unless you ask: useDefaults, removeAdditional and coerceTypes work as in ajv.

Side by side

const Ajv2020 = require('ajv/dist/2020');
const addFormats = require('ajv-formats');

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);
ajv.addSchema(addressSchema, 'https://example.com/address.json');

const validate = ajv.compile(orderSchema);

app.post('/orders', (req, res) => {
  if (!validate(req.body)) {
    return res.status(400).json({ errors: validate.errors });
  }
  // ...
});

const { compileJsonSchema } = require('schiva');

const validate = compileJsonSchema(orderSchema, {
  draft: '2020-12', // or "$schema" in the schema
  formats: true,
  schemas: { 'https://example.com/address.json': addressSchema },
  errors: 'objects', // leave it out for messages
});

app.post('/orders', (req, res) => {
  const errors = validate(req.body);
  if (errors.length > 0) {
    return res.status(400).json({ errors });
  }
  // ...
});

Replacing the instance

An Ajv instance does three things: it holds shared options and schemas, it caches compiled functions, and it finds schemas by $id. A few lines of your own do the same:

// validation.js: shared by the whole application
const { compileJsonSchema } = require('schiva');

const options = { draft: '2020-12', formats: true, schemas: [addressSchema, productSchema] };

// Like ajv.compile(): compiled once per schema object, then reused.
const cache = new WeakMap();
function compile(schema) {
  if (!cache.has(schema)) {
    cache.set(schema, compileJsonSchema(schema, options));
  }
  return cache.get(schema);
}

// Like ajv.getSchema(id): a schema that only references the one with that "$id".
const getSchema = (id) => compileJsonSchema({ $ref: id }, options);

module.exports = { compile, getSchema };

The cache matters if your code called ajv.compile() or ajv.validate() on each request and relied on ajv's cache: compileJsonSchema() compiles every time it is called. Compile when the program starts, or cache as above.

API

ajv checks every schema against its meta-schema when compiling (validateSchema: true). schiva checks keywords and types (an unknown keyword or { "type": 5 } throws), but not every value against the meta-schema: { "minimum": "1" } compiles. To check schemas as ajv did, for example in a test, use the meta-schema that ajv ships:

const metaSchema = require('ajv/dist/refs/json-schema-draft-07.json');
const validateSchema = compileJsonSchema({ $ref: 'http://json-schema.org/draft-07/schema#' }, { schemas: [metaSchema] });
validateSchema({ type: 5 }); // ['type must be one of: array, boolean, ...', ...]

Options

Differences in results

On valid schemas, schiva and ajv agree on which values are valid, except in these cases. Most come from ajv and schiva reading the standard differently where ajv chose to depart from it; check the ones that apply to you.

Errors

By default a schiva function returns messages that start with the path of the field, ready for logs and HTTP responses: 'lines[0].price must be at least 0'. For code that reads the errors, as with validate.errors, use errors: 'objects':

const validate = compileJsonSchema(schema, { errors: 'objects' });
validate({ lines: [{ price: -1 }] });
// [{ path: ['lines', 0, 'price'], pointer: '/lines/0/price', keyword: 'minimum', params: { limit: 0 },
//    message: 'lines[0].price must be at least 0' }]

Other differences, for code that reads the errors closely:

• anyOf: both give the errors of each subschema; ajv adds one more, with the keyword anyOf. contains: ajv gives the errors of each element and one contains error; schiva gives only the contains error.
• oneOf matching several schemas: params.passing (how many) instead of params.passingSchemas (which).
• minimum, maximum and the exclusive ones have no params.comparison: the keyword says it. uniqueItems has no params.i and params.j.
• A value that is not a number where an integer is expected gives params.type: 'number' (must be a number); a number with decimals gives 'integer'. ajv gives 'integer' for both.
• null where the type does not allow it has the keyword nullable and the message cannot be null; ajv gives a type error.

Messages

If tests or code compare messages, they change. The messages of the most common keywords, for a property a:

The value itself is called Value: Value must be a string. For messages of your own, see Custom messages.

Formats

schiva checks the formats itself, without a plugin:

schiva also checks idn-hostname and idn-email. Following the RFCs, it can disagree with ajv-formats on unusual values: it accepts an email with a quoted local part ("john doe"@example.com), which ajv rejects, and rejects 2026-02-30, which ajv's fast mode accepts. Run your test data through both if formats matter to you.

Several documents

Documents that $ref points to go in the option schemas, by URI or with their $id. Relative ids work as in ajv and Fastify: a document with "$id": "address" is reached by "$ref": "address#". To load documents as ajv's compileAsync() does, use compileJsonSchemaAsync() with the same loadSchema function: it is called once for each document the schema reaches and schemas does not have.

compileJsonSchema(orderSchema, { schemas: [addressSchema, countrySchema] }); // schemas with "$id"
await compileJsonSchemaAsync(orderSchema, { loadSchema }); // loads them

A reference that does not resolve throws when compiling. Each document is read in the draft its own $schema names, so a 2020-12 schema can reference draft-07 documents.

An ajv-compatible adapter

When much code reads validate.errors, this adapter gives it what it expects while the validation runs on schiva. Copy it into your project, replace new Ajv(options) with createAjvLike(options), and move the code to schiva's own API when convenient.

// ajv-like.js: ajv's compile(), validate.errors and error objects, on schiva.
const { compileJsonSchema } = require('schiva');

// Errors that ajv reports at the object, with the key in params.
const AT_OBJECT = {
  required: 'missingProperty',
  dependentRequired: 'missingProperty',
  additionalProperties: 'additionalProperty',
  unevaluatedProperties: 'unevaluatedProperty',
};
const COMPARISONS = { minimum: '>=', maximum: '<=', exclusiveMinimum: '>', exclusiveMaximum: '<' };

function toAjvError(error) {
  const parent = error.pointer.slice(0, error.pointer.lastIndexOf('/'));
  const key = error.path[error.path.length - 1];
  const base = { schemaPath: '', keyword: error.keyword, message: error.message };
  if (AT_OBJECT[error.keyword]) {
    const params = error.keyword === 'dependentRequired' ? error.params : {};
    return { ...base, instancePath: parent, params: { ...params, [AT_OBJECT[error.keyword]]: key } };
  }
  if (error.propertyName) {
    return { ...base, instancePath: parent, keyword: 'propertyNames', params: { propertyName: key } };
  }
  const comparison = COMPARISONS[error.keyword];
  return { ...base, instancePath: error.pointer, params: comparison ? { comparison, ...error.params } : error.params };
}

// Like new Ajv(options), with schiva's options (formats, schemas, draft...).
function createAjvLike(options = {}) {
  const cache = new WeakMap();
  // ajv stops at the first error unless allErrors: true.
  const compileOptions = { ...options, allErrors: options.allErrors === true, errors: 'objects' };
  return {
    compile(schema) {
      if (!cache.has(schema)) {
        const check = compileJsonSchema(schema, compileOptions);
        const validate = (data) => {
          const errors = check(data);
          validate.errors = errors.length === 0 ? null : errors.map(toAjvError);
          return errors.length === 0;
        };
        cache.set(schema, validate);
      }
      return cache.get(schema);
    },
    errorsText(errors) {
      return errors ? errors.map((error) => error.message).join(', ') : 'No errors';
    },
  };
}

module.exports = { createAjvLike };

instancePath, keyword and params then match ajv's for the common keywords (schemaPath is empty); the messages are schiva's, and the remaining differences are listed in Errors.

Comparing both

Before switching, validate your test data (or a sample of production data) with both libraries and look at the values where they disagree. It takes a few lines, for example in a test:

const Ajv2020 = require('ajv/dist/2020');
const addFormats = require('ajv-formats');
const { compileJsonSchema } = require('schiva');

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);

function compareOn(schema, values) {
  const withAjv = ajv.compile(schema);
  const withSchiva = compileJsonSchema(schema, { draft: '2020-12', formats: true, errors: false });
  return values.filter((value) => withAjv(value) !== withSchiva(value));
}

// [] when both agree on every value.
console.log(compareOn(orderSchema, orderSamples));

With useDefaults, removeAdditional or coerceTypes, give each library its own copy of each value (structuredClone(value)), as both change it.

Fastify

Fastify validates with ajv, with the options coerceTypes: 'array', useDefaults: true, removeAdditional: true and allErrors: false. schiva has the same options, so a validator compiler keeps the behavior of your routes:

const Fastify = require('fastify');
const { compileJsonSchema } = require('schiva');

// The schemas you gave to fastify.addSchema(), which a custom compiler does not see.
const shared = [{ $id: 'address', type: 'object', required: ['city'], properties: { city: { type: 'string' } } }];

const app = Fastify();
app.setValidatorCompiler(({ schema }) => {
  const validate = compileJsonSchema(schema, {
    schemas: shared,
    // Fastify's defaults with ajv:
    coerceTypes: 'array',
    useDefaults: true,
    removeAdditional: true,
    allErrors: false,
  });
  return (data) => {
    const errors = validate(data);
    return errors.length === 0 ? { value: data } : { error: new Error(errors.join(', ')) };
  };
});

app.post('/orders', {
  schema: {
    body: {
      type: 'object',
      required: ['qty', 'address'],
      properties: { qty: { type: 'integer', minimum: 1 }, address: { $ref: 'address#' } },
    },
  },
}, async (req) => req.body);
// POST { "qty": 0, "address": {} } -> 400 { "message": "qty must be at least 1", ... }

Response schemas are serialized by fast-json-stringify, not validated, so they are not affected. Add formats: true if your schemas use format, as Fastify includes ajv-formats.

OpenAPI

OpenAPI 3.1 schemas are JSON Schema 2020-12: pass draft: '2020-12'. OpenAPI 3.0 schemas are an older dialect, which reads like draft-04 (exclusiveMinimum is a boolean) with a few more keywords:

const validate = compileJsonSchema(openApi30Schema, {
  draft: 'draft-04',
  // OpenAPI's formats that are not checked, besides the built-in ones.
  formats: { ...builtInFormats(), int32: false, int64: false, float: false, double: false, byte: false, binary: false, password: false },
  // OpenAPI's annotations, and your extensions: or strict: false to ignore every unknown keyword.
  keywords: ['example', 'xml', 'externalDocs', 'x-internal'],
});

• nullable: true is supported, as in ajv: it allows null.
• discriminator is supported without an option, with mapping and implicit names, which ajv rejects. See Discriminator.
• readOnly, writeOnly, deprecated, title and description are annotations and need nothing.
• References between components (#/components/schemas/Pet): compile a schema that references the component, with the whole document in schemas: compileJsonSchema({ $ref: 'openapi.json#/components/schemas/Pet' }, { schemas: { 'openapi.json': document } }).

Custom messages

ajv-errors (errorMessage) and ajv-i18n change messages. With schiva, build them from the keyword and params of error objects, in one place:

const validate = compileJsonSchema(schema, { errors: 'objects' });

const MESSAGES = {
  required: () => 'es obligatorio',
  minimum: (params) => `debe ser como mínimo ${params.limit}`,
  format: (params) => `no es un ${params.format} válido`,
};

function messagesOf(errors) {
  return errors.map((error) => {
    const message = MESSAGES[error.keyword];
    return message ? `${error.path.join('.')} ${message(error.params)}` : error.message;
  });
}

messagesOf(validate({ age: 3 })); // ['name es obligatorio', 'age debe ser como mínimo 18']

For a message per field, as errorMessage gives, key the table by error.pointer instead. Keep errorMessage out of the schemas (it throws as an unknown keyword), or declare it with keywords: ['errorMessage'] to leave it as an annotation.

Standalone code

standaloneJsonSchema(schema, options) gives the source of a module to write to a file when building, as ajv's standaloneCode() and ajv-cli do. There is no instance to create, the options are those of compileJsonSchema() with format: 'commonjs' or 'esm', and the module needs nothing else, not even schiva:

// build-validators.js, run when building (in place of ajv-cli compile)
const fs = require('fs');
const { standaloneJsonSchema } = require('schiva');

fs.writeFileSync('validate-order.mjs', standaloneJsonSchema(orderSchema, { formats: true, format: 'esm' }));

See Standalone code for several validators in one module.

TypeScript

What schiva does not do

Checklist

1. Run both libraries on your schemas and test data, and look at any disagreement.
2. Replace ajv.compile(schema) with compileJsonSchema(schema, options), compiled once, when the program starts (or cached, see Replacing the instance).
3. If you used Ajv2019 or Ajv2020 with schemas without $schema, pass draft.
4. Move addSchema() documents to the option schemas, ajv-formats to formats: true, and ajv-keywords to keywords: ajvKeywords().
5. Pick the result: messages (default), errors: 'objects' in place of validate.errors, or errors: false for true/false.
6. If you relied on ajv stopping at the first error, add allErrors: false.
7. Compile every schema once: an unknown keyword, or one the type excludes, throws and shows what to change (or use strict: false).
8. Look for $data, $async, errorMessage and transform, which need changes; useDefaults, removeAdditional and coerceTypes are the same options.
9. Where error objects are read, map instancePath to pointer, and required and additionalProperties errors to their new paths, or use the adapter.
10. Update tests that compare messages (see Messages).
11. Uninstall ajv and its plugins.