Validation Logic & Schema Integration

Production form bugs rarely come from incorrect field rules — they come from the gaps between rules: async responses that resolve after a reset, cross-field constraints that fire in the wrong order, error messages that never reach screen readers, and cancellation logic that leaks memory across route changes. This page covers the architecture that closes those gaps.

Problem Framing

The failure modes this architecture prevents are specific:

• Race conditions — two async responses resolve out of order; the first-issued (stale) response overwrites the second (fresh) one.
• Memory leaks — AbortController instances accumulate on the heap because no cleanup path calls abort() before garbage collection.
• Accessibility regressions — validation state changes but aria-invalid and aria-describedby are updated a render cycle too late, leaving screen readers reading stale information.
• Hydration mismatches — server-rendered forms carry pre-populated error markup that the client-side validator immediately disagrees with, causing a visible error flash.
• Cross-field cascade failures — a change to field A should invalidate field B, but the re-validation fires for the entire form, creating unnecessary network round-trips and UI flicker.

Understanding these failure modes makes every architectural decision below readable as a direct countermeasure, not a convention to memorize.

State Model Overview

Every field participates in a validation lifecycle. Encode it as a discriminated union so the TypeScript compiler rejects impossible state combinations:

// The validation lifecycle for a single field.
// Discriminated on 'status' so impossible combinations (e.g.
// status:'valid' with errors present) are caught at compile time.
type FieldStatus =
  | 'pristine'      // never focused, never changed
  | 'dirty'         // user has typed; sync rules haven't run yet
  | 'validating'    // async check in-flight
  | 'valid'         // all rules passed, errors is empty
  | 'invalid';      // at least one rule failed

interface FieldState {
  value: string;
  status: FieldStatus;
  errors: string[];       // localized, display-ready messages
  touched: boolean;       // focused at least once (drives blur validation)
}

// The aggregate form state. Each field key maps to its own lifecycle.
type FormStatus =
  | 'idle'
  | 'validating'    // at least one field is 'validating'
  | 'submitting'
  | 'success'
  | 'error';        // server-side rejection after submit

interface FormState<T extends Record<string, unknown>> {
  fields: { [K in keyof T]: FieldState };
  status: FormStatus;
  submitError: string | null;
}

The FormStatus rolls up individual FieldStatus values: the form enters validating if any field is validating, and only enters submitting once all fields are valid. This avoids the common mistake of letting a submit proceed while an async uniqueness check is still in-flight.

The relationship between field lifecycle and dirty and pristine state tracking matters here: dirty and pristine are not validation outcomes — they are user-intent signals that determine when validation should run, not what it should check.

Architecture & Design Principles

Four principles make this architecture predictable under production conditions:

1. Decoupled validation pipelines. The component that renders an input should not own the validation logic. Pass a validate function reference into the field handler; the handler invokes it and writes results to state. This lets you swap Zod for a custom schema library without touching any JSX.

2. Normalized flat error state. Store errors as Record<string, string[]> keyed by field name — never as a nested schema-library object. This keeps the render layer simple: any component can read errors['email'] without knowing which library produced the error.

3. Immutable state updates. Every transition produces a new state object. This is what allows time-travel debugging, cheap equality checks in React.memo / computed, and reliable snapshot comparison on reset.

4. AbortController as a first-class citizen. Every async validation request must be paired with an AbortController stored in a field-level WeakMap (so the GC can reclaim controllers whose fields have been removed from the DOM). The controller is aborted before any new request for the same field starts.

// WeakMap keyed by a field descriptor object — NOT by field name string —
// so entries are automatically eligible for GC when the field is removed.
const pendingControllers = new WeakMap<FieldDescriptor, AbortController>();

interface FieldDescriptor {
  name: string;
  // A plain object reference; kept alive by the form state tree.
}

function cancelPending(descriptor: FieldDescriptor): void {
  const prev = pendingControllers.get(descriptor);
  if (prev) {
    prev.abort(); // discard any in-flight response for this field
  }
}

function registerController(
  descriptor: FieldDescriptor,
  controller: AbortController
): void {
  cancelPending(descriptor);
  // Store the new controller; the old one is already aborted above.
  pendingControllers.set(descriptor, controller);
}

Subsystem: Synchronous Schema Validation

Synchronous validation patterns are the backbone of the pipeline. They run inline — on blur, on change when a field has already been touched, and always on submit — producing errors within the same microtask that processes the input event.

Integrating Zod for schema validation makes this declarative. A z.object schema defines the entire form’s contract; safeParse returns a typed result without throwing, and Zod’s ZodError.flatten() produces the flat field-keyed structure the render layer expects directly:

import { z } from 'zod';

const CheckoutSchema = z.object({
  email: z.string().email('Enter a valid email address'),
  password: z
    .string()
    .min(8, 'Password must be at least 8 characters')
    .regex(/[A-Z]/, 'Include at least one uppercase letter'),
  confirmPassword: z.string()
}).refine(
  data => data.password === data.confirmPassword,
  { message: 'Passwords do not match', path: ['confirmPassword'] }
);

type CheckoutValues = z.infer<typeof CheckoutSchema>;

function runSyncValidation(
  values: Partial<CheckoutValues>
): Record<string, string[]> {
  const result = CheckoutSchema.safeParse(values);

  if (result.success) return {};

  // flatten() gives { fieldErrors: { email: ['...'], password: ['...'] } }
  // — exactly the shape the render layer needs.
  return result.error.flatten().fieldErrors as Record<string, string[]>;
}

Note that cross-field rules (confirmPassword refinement) live inside the schema, not scattered across field handlers. That keeps the source of truth in one place and makes the rule testable without a browser.

Subsystem: Asynchronous & Network-Aware Validation

Asynchronous validation strategies introduce three failure modes not present in synchronous checks: stale responses, abandoned requests that keep connections open, and pending UI state that blocks submit before the check resolves.

The full pipeline for a single async field check:

// Debounce delay before issuing a network request.
// Balances responsiveness against unnecessary server load.
const ASYNC_DEBOUNCE_MS = 350;

interface AsyncFieldResult {
  valid: boolean;
  message: string | null;
}

function createAsyncValidator(
  descriptor: FieldDescriptor,
  checkFn: (value: string, signal: AbortSignal) => Promise<AsyncFieldResult>,
  onResult: (result: AsyncFieldResult) => void,
  onStatusChange: (status: 'validating' | 'idle') => void
) {
  let debounceTimer: ReturnType<typeof setTimeout> | null = null;

  return function validate(value: string): void {
    // Clear any pending debounce from the previous keystroke.
    if (debounceTimer !== null) {
      clearTimeout(debounceTimer);
    }

    debounceTimer = setTimeout(async () => {
      // Cancel the previously in-flight request for this descriptor.
      // registerController calls abort() on the old controller first.
      const controller = new AbortController();
      registerController(descriptor, controller);

      onStatusChange('validating');

      try {
        const result = await checkFn(value, controller.signal);
        // Only update state if this request was not aborted.
        // An aborted fetch throws DOMException with name 'AbortError'.
        onResult(result);
      } catch (err) {
        if (err instanceof DOMException && err.name === 'AbortError') {
          // Silently discard — a newer request superseded this one.
          return;
        }
        // Surface unexpected errors as a validation failure, not an uncaught exception.
        onResult({ valid: false, message: 'Validation check failed. Please try again.' });
      } finally {
        onStatusChange('idle');
      }
    }, ASYNC_DEBOUNCE_MS);
  };
}

The signal is passed directly into fetch() as fetch(url, { signal }), which causes the browser to cancel the TCP connection when abort() fires — no dangling sockets.

Subsystem: Cross-Field Dependency Orchestration

Cross-field dependency logic is necessary whenever changing one field’s value must trigger re-validation of another. A flat re-run of the whole schema on every change is correct but expensive for large forms — and causes cascading async re-checks that compound the race condition problem.

Model dependencies explicitly as a directed acyclic graph:

// A DAG entry: when 'source' changes, re-validate each item in 'dependants'.
interface FieldDependency {
  source: string;
  dependants: string[];
}

// Example: 'password' change must re-check 'confirmPassword'.
const dependencies: FieldDependency[] = [
  { source: 'password', dependants: ['confirmPassword'] },
  { source: 'country', dependants: ['stateProvince', 'postalCode'] }
];

// Build a lookup map for O(1) access during input events.
function buildDependencyMap(
  deps: FieldDependency[]
): Map<string, string[]> {
  const map = new Map<string, string[]>();
  for (const { source, dependants } of deps) {
    map.set(source, dependants);
  }
  return map;
}

const dependencyMap = buildDependencyMap(dependencies);

function getFieldsToRevalidate(changedField: string): string[] {
  // Always re-validate the changed field itself, plus any dependants.
  return [changedField, ...(dependencyMap.get(changedField) ?? [])];
}

The DAG approach means a password change re-validates confirmPassword, but does not re-trigger the async uniqueness check on email. Without this, multi-step forms with async validators make far more network requests than necessary.

Subsystem: Choosing and Isolating the Schema Layer

The three subsystems above assume a schema library exists and produces issues. Which library, and how tightly the rest of the form is bound to it, is a separate decision — and one worth making deliberately, because it is the piece most likely to be replaced within the lifetime of the code around it.

Choosing a schema validation library works through the comparison in full. The architectural point is narrower: almost every property teams compare on is cheap to change later, and the two that are expensive are rarely on the list. Bundle size and parse throughput belong to the library, so swapping it changes them wholesale. The refinement model — how you express “this field is required only when that one is set” — belongs to your schemas, and it is spread across every form you own. So is the set of ecosystem bindings you have adopted.

The way to keep the expensive properties cheap is a boundary, not a benchmark. Define the call your form makes and the shape it gets back, and let exactly one module know which library sits behind it:

// The entire surface the form knows about. Everything library-specific lives
// behind this one function, which is also the only thing that needs rewriting
// if the library is replaced.
export type Validate<T> = (values: T) => FieldErrorMap;

// The adapter: schema in, normalized map out. ~30 lines, fully unit-testable
// against a table of inputs and expected maps — a suite that survives the swap.
export function makeValidator<T>(schema: Schema<T>): Validate<T> {
  return (values) => {
    const result = schema.safeParse(values);
    // A pass produces no entries at all, not an empty-string entry per field:
    // downstream code tests presence, and "" is present.
    return result.success ? {} : toFieldErrorMap(result.error.issues);
  };
}

Two things are deliberate here. The adapter returns a normalized FieldErrorMap rather than the library’s own issue list, so nothing downstream — rendering, ARIA wiring, the error summary, analytics — ever imports the library. And a successful parse returns an empty object rather than a map of empty strings, because every consumer tests for the presence of an error and an empty string is present.

What should not be abstracted is the schema DSL itself. Wrapping z.string().email() in a house field.email() produces a second, worse library that has to track the first, and it usually loses the type inference that made the original worth adopting. Abstract the call and the error shape; write the schemas in the library’s own idiom.

The same boundary pays for itself the first time a rule has to run in two places. A schema that lives behind an adapter can be imported by a server route as easily as by a form, so the browser and the API enforce one definition instead of two that drift. That is worth more than any figure in a bundle-size comparison: a rule the client enforces and the server does not is a bug, and a rule the server enforces and the client does not is a wasted round trip.

Error Propagation & Accessibility

Validation state that does not reach assistive technology is a WCAG 2.1 failure, not an edge case. The wiring is straightforward but must be synchronous with the state update — a separate useEffect that sets ARIA attributes a render later is too slow.

// Apply ARIA state to an input immediately when validation results are written.
// Call this in the same update handler that writes errors to form state.
function syncAriaValidation(
  inputEl: HTMLInputElement,
  fieldName: string,
  errors: string[]
): void {
  if (errors.length > 0) {
    // aria-invalid tells screen readers the field has failed validation.
    inputEl.setAttribute('aria-invalid', 'true');
    // aria-describedby points to the element that contains the error text.
    // The error container must have id="${fieldName}-error" in the markup.
    inputEl.setAttribute('aria-describedby', `${fieldName}-error`);
  } else {
    inputEl.removeAttribute('aria-invalid');
    inputEl.removeAttribute('aria-describedby');
  }
}

The matching error container in markup:

<input id="email" name="email" type="email" aria-describedby="email-error" />
<p id="email-error" role="alert" aria-live="polite"></p>

role="alert" on the error container triggers an implicit live region. Use aria-live="polite" for field-level errors (announced after the user pauses) and aria-live="assertive" only for submit-level failures that require immediate attention.

Never rely solely on color to communicate invalid state. Always pair border-color: red with a visible text message and the aria-invalid attribute.

See error state mapping patterns for the full normalization layer that translates raw schema errors into display-ready messages with severity levels.

Lifecycle Teardown

Failing to clean up is how validation logic creates memory leaks and ghost state updates. Expose a destroy() method as part of your validator API so callers have a deterministic cleanup path:

interface ValidatorCleanup {
  (): void; // call this on component unmount or route change
}

function createFormValidator<T extends Record<string, unknown>>(
  descriptors: Record<keyof T, FieldDescriptor>
): { destroy: ValidatorCleanup } {
  // Track all debounce timers so they can be cleared on teardown.
  const debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();

  function destroy(): void {
    // 1. Clear every pending debounce timer to stop deferred async checks.
    for (const timer of debounceTimers.values()) {
      clearTimeout(timer);
    }
    debounceTimers.clear();

    // 2. Abort every in-flight network request.
    // WeakMap entries are keyed by descriptor objects; iterate via
    // the descriptors record to reach each one.
    for (const descriptor of Object.values(descriptors)) {
      cancelPending(descriptor as FieldDescriptor);
    }

    // 3. Any reactive subscriptions (e.g. MobX reactions, Vue watchers,
    // Svelte store unsubscribers) must also be called here.
    // Store their cleanup functions in an array and iterate.
  }

  return { destroy };
}

Call destroy() in React’s useEffect cleanup, Vue’s onUnmounted, Svelte’s onDestroy, or an Angular ngOnDestroy hook. Without this, navigating away from a multi-step form can leave async checks resolving into state that no longer has a mounted consumer.

Common Pitfalls

1. Running sync and async checks in the same execution path without a priority queue. Async checks should only start after sync rules pass. If safeParse returns errors, skip the network round-trip entirely — there is nothing useful to check remotely on a malformed value.

2. Storing AbortController instances in component-local variables instead of a stable WeakMap. Local variables are re-created on every render in React function components, making the previous controller unreachable and its abort() method uncallable. Use a useRef or a module-scoped WeakMap keyed by a stable descriptor object.

3. Updating ARIA attributes in a separate effect or microtask after state writes. Screen readers observe attribute changes synchronously; a delayed write means the reader announces the previous state. Set aria-invalid and aria-describedby in the same operation that writes errors to field state.

4. Re-validating the entire form on every field change instead of using a dependency graph. In forms with async validators, this multiplies network requests linearly with field count. Build the dependency graph once at initialization and only re-trigger the fields it maps.

5. Returning raw library error objects to the render layer. Zod’s ZodIssue, Yup’s ValidationError, and Valibot’s error objects all have different shapes. Normalize to Record<string, string[]> at the schema boundary so the render layer is library-agnostic.

6. Not resetting async_pending / validating status on unmount. If a validating field is removed from the DOM (conditional rendering, multi-step navigation), the status flag stays validating in state, which can block submit logic that checks fields[name].status.

7. Bypassing the state machine with direct setState calls for programmatic resets. A reset must go through the same transition logic as user input — clearing errors, aborting pending checks, and restoring pristine flags atomically. Direct mutation skips these side effects and leaves the form in an inconsistent state.

Frequently Asked Questions

Related

• Synchronous Validation Patterns — immediate feedback on blur and change events without blocking the main thread
• Integrating Zod for Schema Validation — runtime type parsing, schema composition, and typed error extraction
• Asynchronous Validation Strategies — AbortController lifecycle, debounce coordination, and retry logic for network-bound checks
• Cross-Field Dependency Logic — DAG-based re-validation triggers for interdependent fields

← Home