Data Validation - Input Sanitisation & Schema Patterns

Validation patterns ensuring all data entering the system is validated at boundaries: user input via Zod (frontend), API requests via Pydantic (backend). No unvalidated data crosses a trust boundary.

Description

Defines Zod and Pydantic validation patterns for all data entering the system at trust boundaries. Covers form validation, API request schemas, type-safe contracts, Australian-specific validators (ABN, phone, postcode), and schema composition strategies.

When to Apply

Positive Triggers

Creating or modifying form inputs with user data
Defining API request/response schemas (Pydantic models)
Adding Zod schemas for frontend validation
Reviewing code for missing input validation
Building new API endpoints that accept POST/PUT/PATCH data
User mentions: "validation", "Zod", "Pydantic", "schema", "sanitise", "input"

Negative Triggers

Implementing authentication logic (use auth patterns directly)
Designing error response formats (use error-taxonomy instead)
Working on database model definitions (that is ORM schema, not input validation)

Core Directives

Validate at Boundaries, Trust Internally

[User Input] --Zod--> [Frontend] --fetch--> [API] --Pydantic--> [Service Layer]
     ^                                         ^
     |                                         |
  VALIDATE HERE                          VALIDATE HERE

Frontend boundary: Every form field validated with Zod before submission
API boundary: Every request body validated with Pydantic before processing
Internal code: Trust validated data — no redundant re-validation inside services

Naming Conventions

Layer	Convention	Example
Frontend Zod schema	`camelCase` + `Schema` suffix	`loginFormSchema`
Frontend inferred type	`PascalCase` via `z.infer`	`type LoginForm = z.infer<typeof loginFormSchema>`
Backend Pydantic model	`PascalCase` + purpose suffix	`DocumentCreateRequest`
Shared contract	Same field names both sides	`email`, `password`, `title`

Frontend Patterns (Zod + react-hook-form)

Basic Form Schema

The project already uses this pattern in apps/web/components/auth/login-form.tsx:

import * as z from 'zod';
import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';

// 1. Define schema
const loginFormSchema = z.object({
  email: z.string().email('Please enter a valid email address'),
  password: z.string().min(6, 'Password must be at least 6 characters'),
});

// 2. Infer type (never define manually)
type LoginForm = z.infer<typeof loginFormSchema>;

// 3. Use with react-hook-form
const form = useForm<LoginForm>({
  resolver: zodResolver(loginFormSchema),
  defaultValues: { email: '', password: '' },
});

Schema Composition

Build complex schemas from reusable parts:

// Base schemas (reusable)
const emailSchema = z.string().email('Please enter a valid email address');
const passwordSchema = z.string().min(6, 'Password must be at least 6 characters');
const abnSchema = z.string().regex(/^\d{11}$/, 'ABN must be 11 digits');

// Composed schemas
const registerFormSchema = z
  .object({
    email: emailSchema,
    password: passwordSchema,
    confirmPassword: z.string(),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: 'Passwords do not match',
    path: ['confirmPassword'],
  });

API Request Validation

Validate data before sending to the backend:

const documentCreateSchema = z.object({
  title: z.string().min(1, 'Title is required').max(255),
  content: z.string().min(1, 'Content is required'),
  metadata: z.record(z.unknown()).optional(),
});

async function createDocument(input: unknown): Promise<Document> {
  // Validate before sending — fail fast on the client
  const validated = documentCreateSchema.parse(input);
  return apiClient.post('/api/documents', validated);
}

Australian-Specific Validators

// Australian Business Number (ABN) with checksum
const abnSchema = z.string().refine(
  (val) => {
    if (!/^\d{11}$/.test(val)) return false;
    const weights = [10, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19];
    const digits = val.split('').map(Number);
    digits[0] -= 1;
    const sum = digits.reduce((acc, d, i) => acc + d * weights[i], 0);
    return sum % 89 === 0;
  },
  { message: 'Invalid ABN' }
);

// Australian phone number
const auPhoneSchema = z.string().regex(
  /^(\+61|0)[2-478]\d{8}$/,
  'Please enter a valid Australian phone number'
);

// Australian postcode
const postcodeSchema = z.string().regex(/^\d{4}$/, 'Postcode must be 4 digits');

// Date in DD/MM/YYYY format
const auDateSchema = z.string().regex(
  /^\d{2}\/\d{2}\/\d{4}$/,
  'Date must be in DD/MM/YYYY format'
);

Backend Patterns (Pydantic)

Request Model Convention

The project defines request models in route files or apps/backend/src/api/schemas/:

from pydantic import BaseModel, Field, field_validator
from typing import Optional


class DocumentCreateRequest(BaseModel):
    """Validated input for document creation."""

    title: str = Field(
        ...,
        min_length=1,
        max_length=255,
        description="Document title"
    )
    content: str = Field(
        ...,
        min_length=1,
        description="Document content"
    )
    metadata: Optional[dict] = Field(
        None,
        description="Additional metadata"
    )

    @field_validator("title")
    @classmethod
    def strip_title(cls, v: str) -> str:
        return v.strip()

Constrained Types

Use Pydantic's built-in constraints instead of custom validators where possible:

from pydantic import BaseModel, Field, EmailStr
from typing import Annotated


# Constrained types (prefer over custom validators)
PositiveInt = Annotated[int, Field(gt=0)]
PageSize = Annotated[int, Field(ge=1, le=100)]
ShortString = Annotated[str, Field(min_length=1, max_length=255)]


class PaginationParams(BaseModel):
    """Reusable pagination parameters."""

    page: PositiveInt = 1
    page_size: PageSize = 20


class SearchRequest(BaseModel):
    """Validated search input."""

    query: ShortString
    pagination: PaginationParams = PaginationParams()

Route Integration

from fastapi import APIRouter

router = APIRouter(prefix="/api/documents", tags=["documents"])


@router.post("/", status_code=201)
async def create_document(
    request: DocumentCreateRequest,  # Pydantic validates automatically
    user: User = Depends(get_current_user),
) -> DocumentResponse:
    """Create a new document. Input is validated by Pydantic."""
    # request is already validated — trust it here
    return await document_service.create(request, user)

Schema Location Convention

Schema Type	Location	When to Use
Route-specific	Inline in route file	Simple schemas used by one endpoint
Shared across routes	`apps/backend/src/api/schemas/`	Schemas used by multiple endpoints
Domain models	`apps/backend/src/models/`	Core business models (not request schemas)

Validation Checklist

When adding a new feature, verify:

Every form has a Zod schema with zodResolver
Form types are inferred via z.infer, not manually defined
Every POST/PUT/PATCH endpoint has a Pydantic request model
Error messages are user-friendly, not technical
Australian formats validated where applicable (ABN, phone, postcode, date)
Schema field names match between frontend Zod and backend Pydantic

Anti-Patterns

Pattern	Problem	Correct Approach
Validation logic inside route handlers	Mixes concerns, hard to reuse or test	Define Zod/Pydantic schemas separately and reference them
No error messages on validation failure	Users see raw Pydantic/Zod errors	Provide human-readable messages in en-AU on every field
Type coercion without validation (`Number(input)`)	`NaN` and unexpected values slip through	Use Zod `.coerce.number()` or Pydantic `field_validator`
Optional fields without defaults	Downstream code must null-check everywhere	Set sensible defaults via `Field(default=...)` or `.default()`
Manually defining types instead of inferring	Types drift out of sync with schemas	Use `z.infer<typeof schema>` and Pydantic model exports

Checklist

Zod schemas defined for all frontend form and API inputs
Pydantic models defined for all backend request bodies
Error messages written in en-AU (e.g., "Please enter a valid email address")
Validation occurs at system boundaries (frontend forms, API entry points)
Schema field names match between frontend Zod and backend Pydantic

Response Format

[AGENT_ACTIVATED]: Data Validation
[PHASE]: {Schema Design | Implementation | Review}
[STATUS]: {in_progress | complete}

{validation analysis or schema output}

[NEXT_ACTION]: {what to do next}

Integration Points

Error Taxonomy

Validation failures should use DATA_VALIDATION_* error codes from the error-taxonomy skill:

# Backend: structured validation error
raise HTTPException(
    status_code=422,
    detail={
        "detail": "Email format is invalid",
        "error_code": "DATA_VALIDATION_INVALID_FORMAT",
        "field": "email",
    },
)

Council of Logic (Shannon Check)

Schemas should be minimal — only validate what the endpoint actually uses
Avoid duplicating the same schema across files — compose from base schemas
Prefer built-in constraints (min_length, gt) over custom validators

API Contract

When api-contract skill is installed, Zod and Pydantic schemas should mirror each other to form a typed contract between frontend and backend.

Australian Localisation (en-AU)

Date Format: DD/MM/YYYY (not MM/DD/YYYY)
Phone: +61 or 0X XXXX XXXX
ABN: 11-digit with checksum validation
Postcode: 4 digits (0200–9999)
Currency: AUD ($) — validate as positive decimal
Spelling: sanitisation, organisation, analyse, centre, colour

data-validation