fastify-zod-schema

fastify-zod-schema is a Fastify plugin that allows users to define request schemas using Zod v4, providing type safety and validation.

Zod versions support

• v1.x.x - Zod v3 (default)
• v2.x.x - Zod v4

Main branch is for latest version. v1 is supported and updated in separate branch.

Installation

To install the package, use npm:

1npm install fastify-zod-schema

Usage

First, register the plugin in your Fastify app:

1import fastify from 'fastify'
2import { zodSchemaPlugin } from 'fastify-zod-schema'
3
4const app = fastify()
5
6app.register(zodSchemaPlugin);

Defining Schemas

With fastify-zod-schema, you can define your request schemas using Zod. Below are some examples of usage with Fastify routes.

Example 1: Basic Route Validation

1import z from 'zod'
2
3const schema = {
4  body: z.object({
5    name: z.string(),
6    age: z.number().int().positive(),
7  }),
8};
9
10app.post('/user', { schema }, async (req, rep) => {
11  const { name, age } = req.body;
12  return { name, age };
13});

Example 2: Query Parameters Validation

1import z from 'zod'
2
3const schema = {
4  querystring: z.object({
5    search: z.string().min(1),
6    limit: z.number().int().positive().optional(),
7  }),
8};
9
10app.get('/search', { schema }, async (req, rep) => {
11  const { search, limit } = req.query;
12  return { search, limit };
13});

Example 3: Headers Validation

1import z from 'zod'
2
3const schema = {
4  headers: z.object({
5    'x-api-key': z.string().uuid(),
6  }),
7};
8
9app.get('/protected', { schema }, async (req, rep) => {
10  const apiKey = req.headers['x-api-key'];
11  return { apiKey };
12});

Example 4: Combining Body, Query, Headers and Response Validation

1import z from 'zod'
2
3const schema = {
4  body: z.object({
5    username: z.string().min(1),
6    password: z.string().min(6),
7  }),
8  querystring: z.object({
9    role: z.string().optional(),
10  }),
11  headers: z.object({
12    'x-api-key': z.string().min(1),
13  }),
14  response: {
15    200: z.object({
16      username: z.string().min(1),
17      role: z.string().optional(),
18    })
19  }
20};
21
22app.post('/login', { schema }, async (req, rep) => {
23  const { username, password } = req.body;
24  const { role } = req.query;
25  const apiKey = req.headers['x-api-key'];
26  return { username, role };
27});

Caveats

• Version 4 is using zod native toJSONSchema transformer so all its restrictions and limitations are expected here as well. See Zod Docs
• I plan to add plugin configuration to customize behaviour of the toJsonSchema method.

License

MIT