Fastify Schema‑Driven Validation and Serialization as an API Boundary

Requirements

Each route must declare a JSON Schema that describes:

• Allowed shape of query string, route parameters, body, and headers.
• Exact structure of the successful response (including status code).

The schema is the single source of truth for both inbound validation and outbound serialization.

Smallest Suitable Design

A single Fastify instance loads a route plugin that registers:

1. A preValidation hook that runs fastify.validate(schema, data) on the combined request payload (query, params, body, headers). If validation fails, the hook throws an error with status code 400.
2. The route handler that contains only business‑logic code, trusting that its inputs conform to the schema.
3. A preSerialization hook that runs after the handler, removes any properties not defined in the response schema, and then lets Fastify serialize the cleaned object.

Example plugin (Node.js, Fastify v4.x):

const fp = require('fastify-plugin');

function routeWithSchema(fastify, opts, done) {
  const schema = {
    body: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
    response: {
      200: { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' } }, required: ['id', 'name'] }
    }
  };

  fastify.addHook('preValidation', (request, reply, done) => {
    const err = fastify.validate(schema, request);
    if (err) {
      request.log.error({ validationError: err }, 'Schema validation failed');
      return reply.code(400).send({ error: 'ValidationFailed', details: err });
    }
    done();
  });

  fastify.post('/users', schema, async (request, reply) => {
    // business logic – assume request.body is valid
    const user = { id: crypto.randomUUID(), name: request.body.name };
    return user;
  });

  fastify.addHook('preSerialization', (request, reply, payload, done) => {
    // strip unknown properties according to schema.response[200]
    const allowed = schema.response['200'].properties;
    const clean = {};
    for (const key in payload) {
      if (allowed[key]) clean[key] = payload[key];
    }
    done(null, clean);
  });

  done();
}

module.exports = fp(routeWithSchema);

Trust/Data Boundaries

Validation occurs in the preValidation hook, which runs before any user‑defined handler. This creates a clear edge: only data that passes the JSON Schema enters the trusted zone where business logic executes. Serialization happens after the handler, guaranteeing that the outbound payload cannot contain fields that were not declared in the response schema, thus protecting consumers from accidental data leaks.

Operational Checks

• Error handling – Register a global error handler to log validation failures:

  fastify.setErrorHandler((error, request, reply) => {
    if (error.validation) {
      request.log.info({ validationError: error.validation }, 'Client sent invalid data');
      return reply.code(400).send({ error: 'BadRequest', details: error.validation });
    }
    reply.send(error);
  });
  

• Route change detection – Use onRoute to emit a metric whenever a new route is added, allowing you to detect schema drift in CI/CD pipelines.

  fastify.addHook('onRoute', (routeOptions) => {
    // increment a counter or emit to a monitoring system
    metrics.inc('fastify_routes_total', { path: routeOptions.path });
  });
  

• Metrics – Export validation error rates and latency via Fastify’s built‑in metrics plugin or a custom implementation; watch for spikes that could indicate malicious input or a mis‑configured schema.

Failure Modes

• Malformed input – Triggers the preValidation hook, resulting in a 400 Bad Request with a structured error payload (as shown in the error handler).
• Serialization error – If the handler returns an object missing a required response property, the preSerialization hook will strip nothing but the missing field will cause Fastify’s serializer to throw; unless caught, this becomes a 500 Internal Server Error.
• Plugin misordering – Adding the route handler before the validation hook (or placing the serialization hook before the handler) can bypass validation. The design assumes the hooks are registered in the order shown.

Conditions That Would Change the Design

• Moving to a micro‑gateway where validation is delegated to a sidecar or service mesh would remove the need for per‑route hooks; the Fastify instance would become a thin pass‑through.
• Adopting GraphQL replaces per‑endpoint JSON Schema with a single schema language; validation and serialization are handled by the GraphQL engine.
• Need for dynamic schema generation at runtime (e.g., schema pulled from a database) would require replacing the static fastify.validate call with a schema‑compilation service that caches and updates schemas without restarting the service.

Limitations and Practical Verification

While the approach works well for static schemas, deeply nested or format‑heavy schemas can increase validation latency and GC pressure. To verify that the hooks behave as expected:

1. Write a test that uses fastify.inject() to send an invalid payload (e.g., missing required field). Assert that the response status is 400 and the body contains a validationError type.
2. Send a valid payload and assert that the response body matches the response schema exactly (no extra properties, all required fields present).
3. Run a load test with a mix of valid and invalid requests using a tool like autocannon, and observe the metrics for validation error rate and average latency; ensure they stay within acceptable bounds.
4. Check the Fastify changelog for the targeted version line (v4.x) to confirm that preValidation and preSerialization hooks execute as described.

These steps give confidence that the edge validation and contract enforcement are working without claiming any specific measured outcome.