fastify-type-provider-zod

To avoid duplicating schemas in your OpenAPI document and instead use $ref, register your schemas with the global Zod registry using z.globalRegistry.add(schema, { id: 'Name' }). Then, configure @fastify/swagger with both transform: jsonSchemaTransform and transformObject: jsonSchemaTransformObject.

import fastifySwagger from '@fastify/swagger';
import fastifySwaggerUI from '@fastify/swagger-ui';
import fastify from 'fastify';
import { z } from 'zod/v4';
import type { ZodTypeProvider } from 'fastify-type-provider-zod';
import {
  jsonSchemaTransformObject,
  jsonSchemaTransform,
  serializerCompiler,
  validatorCompiler,
} from 'fastify-type-provider-zod';

const USER_SCHEMA = z.object({
  id: z.number().int().positive(),
  name: z.string().describe('The name of the user'),
});

// Register schema with a global ID for referencing
z.globalRegistry.add(USER_SCHEMA, { id: 'User' });

const app = fastify();
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);

app.register(fastifySwagger, {
  openapi: {
    info: { title: 'SampleApi', version: '1.0.0' },
    servers: [],
  },
  transform: jsonSchemaTransform,
  transformObject: jsonSchemaTransformObject,
});

app.register(fastifySwaggerUI, { routePrefix: '/documentation' });

app.after(() => {
  app.withTypeProvider<ZodTypeProvider>().route({
    method: 'GET',
    url: '/users',
    schema: {
      response: {
        200: USER_SCHEMA.array(),
      },
    },
    handler: (req, res) => {
      res.send([]);
    },
  });
});

To generate OpenAPI documentation from your Zod schemas, register @fastify/swagger and use the jsonSchemaTransform provided by this library. This allows the Swagger UI to correctly interpret your Zod-defined schemas.

import fastify from 'fastify';
import fastifySwagger from '@fastify/swagger';
import fastifySwaggerUI from '@fastify/swagger-ui';
import { z } from 'zod/v4';
import type { ZodTypeProvider } from 'fastify-type-provider-zod';
import {
  jsonSchemaTransform,
  serializerCompiler,
  validatorCompiler,
} from 'fastify-type-provider-zod';

const app = fastify();
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);

app.register(fastifySwagger, {
  openapi: {
    info: {
      title: 'SampleApi',
      description: 'Sample backend service',
      version: '1.0.0',
    },
    servers: [],
  },
  transform: jsonSchemaTransform,
});

app.register(fastifySwaggerUI, {
  routePrefix: '/documentation',
});

// ... routes using app.withTypeProvider<ZodTypeProvider>()

To use Zod for schema validation and serialization in Fastify, you must register the validatorCompiler and serializerCompiler. Use app.withTypeProvider<ZodTypeProvider>() to enable type safety for your routes.

Important (v7+): Response serialization is now based on z.output<T> instead of z.input<T>. Fastify serializers expect the post-transformation output type of your Zod schemas.

import Fastify from 'fastify';
import type { ZodTypeProvider } from 'fastify-type-provider-zod';
import { serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';
import { z } from 'zod/v4';

const app = Fastify();

// Add schema validator and serializer
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);

app.withTypeProvider<ZodTypeProvider>().route({
  method: 'GET',
  url: '/',
  schema: {
    querystring: z.object({
      name: z.string().min(4),
    }),
    response: {
      200: z.string(),
    },
  },
  handler: (req, res) => {
    res.send(req.query.name);
  },
});

app.listen({ port: 4949 });

You can define multiple content types for a single response status following the OpenAPI 3.x format. jsonSchemaTransform will handle these correctly. To select the appropriate schema during execution, set the Content-Type header in your handler.

import { z } from 'zod/v4';
import type { ZodTypeProvider } from 'fastify-type-provider-zod';

app.withTypeProvider<ZodTypeProvider>().route({
  method: 'GET',
  url: '/items',
  schema: {
    response: {
      200: {
        description: 'Successful response',
        content: {
          'application/json': { schema: z.object({ id: z.number(), name: z.string() }) },
          'application/vnd.v1+json': { schema: z.array(z.object({ id: z.number(), name: z.string() })) },
        },
      },
      default: {
        content: {
          '*/*': { schema: z.object({ message: z.string() }) },
        },
      },
    },
  },
  handler: (req, res) => {
    // Set header to select which schema validates the response
    res.header('Content-Type', 'application/vnd.v1+json');
    res.send([{ id: 1, name: 'item' }]);
  },
});

Use hasZodFastifySchemaValidationErrors to detect request validation errors and isResponseSerializationError to detect errors where the response does not match the defined Zod schema. This allows you to return structured error responses.

import { hasZodFastifySchemaValidationErrors, isResponseSerializationError } from 'fastify-type-provider-zod';

fastifyApp.setErrorHandler((err, req, reply) => {
  if (hasZodFastifySchemaValidationErrors(err)) {
    return reply.code(400).send({
      error: 'Response Validation Error',
      message: "Request doesn't match the schema",
      statusCode: 400,
      details: {
        issues: err.validation,
        method: req.method,
        url: req.url,
      },
    });
  }

  if (isResponseSerializationError(err)) {
    return reply.code(500).send({
      error: 'Internal Server Error',
      message: "Response doesn't match the schema",
      statusCode: 500,
      details: {
        issues: err.cause.issues,
        method: err.method,
        url: err.url,
      },
    });
  }
});