JSON Schema Validation

Use Fastify's built-in JSON Schema for request validation and compiled response serialization.

Recipe

Quick-reference recipe card - copy-paste ready.

import Fastify from "fastify";
 
const app = Fastify();
 
const userSchema = {
  type: "object",
  required: ["name", "email"],
  properties: {
    name: { type: "string", minLength: 1, maxLength: 100 },
    email: { type: "string", format: "email" },
  },
} as const;
 
app.post("/users", {
  schema: {
    body: userSchema,
    response: {
      201: {
        type: "object",
        properties: {
          id: { type: "string", format: "uuid" },
          name: { type: "string" },
          email: { type: "string" },
        },
      },
    },
  },
}, async (req, reply) => {
  const body = req.body as { name: string; email: string };
  return reply.status(201).send({ id: crypto.randomUUID(), ...body });
});

When to reach for this: Every public API endpoint. Schema validation is Fastify's primary advantage over Express.

Working Example

import Fastify from "fastify";
import { Type } from "@sinclair/typebox";
import { TypeBoxTypeProvider } from "@fastify/type-provider-typebox";
 
const app = Fastify().withTypeProvider<TypeBoxTypeProvider>();
 
const CreateUser = Type.Object({
  name: Type.String({ minLength: 1 }),
  email: Type.String({ format: "email" }),
});
 
const UserResponse = Type.Object({
  id: Type.String({ format: "uuid" }),
  name: Type.String(),
  email: Type.String(),
});
 
app.post("/users", {
  schema: {
    body: CreateUser,
    response: { 201: UserResponse },
  },
}, async (req, reply) => {
  const { name, email } = req.body;
  return reply.status(201).send({ id: crypto.randomUUID(), name, email });
});
 
app.setErrorHandler((err, _req, reply) => {
  if (err.validation) {
    return reply.status(400).send({ error: "Validation failed", details: err.validation });
  }
  reply.status(500).send({ error: "Internal server error" });
});

What this demonstrates:

• TypeBox schemas with TypeScript type inference
• Automatic 400 on validation failure
• Custom error handler for validation error shape
• Response schema compiles serializer for speed

Deep Dive

How It Works

• Fastify uses Ajv for request validation at route registration time
• Response schemas compile to fast serialization functions (fast-json-stringify)
• Validation runs in preValidation hook before the handler
• Invalid responses in development log warnings; in production they are stripped to match schema

Schema Coverage

Reusable Schemas

app.addSchema({ $id: "User", type: "object", properties: { id: { type: "string" } } });
 
app.get("/users/:id", {
  schema: {
    params: { $ref: "User#" },
    response: { 200: { $ref: "User#" } },
  },
}, async (req) => ({ id: req.params.id }));

Gotchas

• No response schema - lose serialization speed benefit. Fix: define response schemas for all public endpoints.
• Overly permissive additionalProperties - accepts unexpected fields. Fix: set additionalProperties: false on objects.
• Schema and TypeScript types diverge - runtime validates one shape, TS assumes another. Fix: use TypeBox or Zod type provider.
• Complex nested schemas slow compilation - startup time grows. Fix: reuse schemas with $ref and addSchema.
• Returning fields not in response schema - stripped silently in production. Fix: match handler output to schema exactly.
• Validating with Zod AND JSON Schema - duplicate validation cost. Fix: pick one; use fastify-type-provider-zod.

Alternatives

FAQs

Related

• Fastify Basics - getting started
• Fastify Plugins - shared schema registration
• Zod at Boundaries - Zod alternative
• OpenAPI and Swagger - API documentation
• Fastify Best Practices - section checklist

External Related Links

• Fastify - High-performance web framework docs.
• Node.js API Documentation - Complete reference for core modules and APIs.
• Node.js Best Practices (GitHub) - Curated production best practices.
• Node.js Design Patterns, 4th Edition - Production-grade application patterns.
• Node.js Cookbook, 5th Edition - Practical server-side recipes.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.