AJVstrictMode.md

August 19, 2025 · View on GitHub

fastify-openapi-glue

AJV strict mode

Fastify uses AJV to check JSONschemas that are used for validation and serialization.

The OpenApi specification allows for additions to the schema specification that do not match JSON schema , e.g:

"responses": {
    "200": {
      "description": "Did something",
      "schema": {
        "type": "string",
        "example": "Done"
      }
    },
    "404": {
      "description": "Didnt do something",
      "schema": {
        "type": "string",
        "example": "Failed"
      }
    }
  }

In this case the example attribute is not part of JSON schema and Fastify (actually AJV) will throw an error along the lines of:

Error while starting the application: Error: Could not initiate module due to error: FastifyError: Failed building the validation schema for POST: /api/v1/user/{userId}/something, due to error strict mode: unknown keyword: "example"

This error can be prevented by telling Fastify to use AJV in non-strict mode. This does not change the actual validation but it does allow for extra attributes in the schema. See: https://ajv.js.org/options.html#strict for more details.

There are 2 ways to achieve this:

Fastify start

If your code is a Fastify plug-in then adding:

export const options = {
  ajv: {
    customOptions: {
      strict: false,
    },
  },
};

Will tell fastify start to apply this option. See: examples/petstore/index.js

Make sure that you start your plugin using --options, e.g.: fastify start --options <your plugin>, or else the options won't be loaded.

Fastify factory

If you are setting up fastify in your own code then you can pass the non-strict option to AJV:

import Fastify from "fastify";
const fastify = Fastify(
  {
    ajv: {
      customOptions: {
        strict: false,
      },
    },
  },
);