fastify-schemas-validation

Fastify Schemas, Validation & Serialization

Core Philosophy: Schema-First

Fastify rejects implicit behavior. You MUST define explicit JSON Schema contracts for ALL routes. Schemas are not optional documentation — they are the mechanism that unlocks pre-compiled validation via Ajv and JIT serialization via fast-json-stringify. Never execute business logic on unknown or invalid data. Fail fast: if a request does not match the contract, reject it before it reaches your handler.

Every route you write must have schemas defined for both request validation and response serialization. Treat schema omission as a bug, not a convenience tradeoff.

Request Validation with Ajv

Schema Locations

You can attach validation schemas to four locations on a route:

• body — Use for POST, PUT, and PATCH request bodies. This is the most common validation target. Define the shape of the incoming JSON payload here.
• querystring (or the alias query) — Use for URL query parameters. Define expected parameter names, types, and constraints. Remember that all query values arrive as strings, so rely on Ajv coercion or define types accordingly.
• params — Use for URL path parameters (e.g., /users/:id). Always define the expected type. A common pattern is { type: 'object', properties: { id: { type: 'integer' } }, required: ['id'] }.
• headers — Use for request headers. This is rarely needed, but useful when you must enforce a specific header value or presence (e.g., X-API-Key). Remember that header names are lowercased by Node.js.

How Validation Works Internally

Schemas are compiled into optimized JavaScript functions at startup, not at request time. This means the first request is fast — there is no cold-start penalty per route. Ajv automatically coerces types when the schema specifies a type that differs from the incoming value. For example, the string "42" becomes the number 42 when the schema declares type: "number". This coercion is enabled by default in Fastify's Ajv configuration.