response-schema-validation

Response Schema Validation

Core Rule

Every API response must be validated against a declared schema before it leaves the server. Returning raw database objects or unvalidated data is a data leakage vector and a contract violation.

Why This Matters

Risk	What Happens Without Schema Validation
Data leakage	Internal fields (password_hash, internal_notes, admin_flag) accidentally returned to clients
Contract drift	Frontend expects { user_id } but backend returns { userId } after a refactor — no error, silent failure
Over-fetching	Entire database rows returned when the client needs 3 fields — bandwidth waste and attack surface expansion
Type mismatches	null where a string is expected, number-as-string, missing required fields — client crashes

Implementation Patterns

TypeScript (Zod)

Define response schemas alongside request schemas. Validate before sending:

// BAD — returning raw database row (leaks internal fields)
app.get('/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  res.json(user); // exposes passwordHash, internalNotes, loginAttempts
});

// GOOD — validate through a declared response schema
// schemas/user.ts
import { z } from 'zod';

export const UserResponse = z.object({
  id: z.string().uuid(),
  name: z.string(),
  email: z.string().email(),
  role: z.enum(['user', 'admin']),
  createdAt: z.string().datetime(),
});

// NEVER include: passwordHash, internalNotes, loginAttempts
export type UserResponse = z.infer<typeof UserResponse>;

// routes/users.ts
import { UserResponse } from '../schemas/user';

app.get('/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) return res.status(404).json({ error: 'Not found' });

  // Validate and strip — only declared fields pass through
  const response = UserResponse.parse(user);
  res.json(response);
});