Schema Validation

Vest introduces optional schema validation using n4s (enforce).

Why use a Schema?

Validating data structure is often the first step in any validation pipeline. Before checking if a username is available, you want to know that the username field actually exists and is a string.

Vest's schema support gives you:

1. Type Safety: Automatically infers TypeScript types for your data, so you get autocomplete and error checking in your suite.
2. Structural Integrity: Ensures your data matches the expected shape before running more complex validations.
3. Fail Fast: If the data structure is wrong, Vest fails immediately, saving resources.

Defining a Schema

Use enforce.shape, enforce.loose, or enforce.partial to define your data structure.

import { create, test, enforce } from 'vest';

const userSchema = enforce.shape({
  username: enforce.isString(),
  age: enforce.isNumber(),
  email: enforce.optional(enforce.isString()), // Optional field
});

const suite = create(data => {
  // `data` is typed: { username: string, age: number, email?: string | undefined }

  test('username', 'Must be at least 3 chars', () => {
    enforce(data.username).longerThan(2);
  });
}, userSchema);

How it works

When you pass a schema to create:

1. Vest implicitly runs the schema validation before your tests.
2. If the data structure doesn't match the schema (e.g., age is a string instead of a number), the suite run fails immediately for those fields.
3. Your tests run assuming the data types are correct.

Focused runs

When you focus the suite with focus({ only }), schema validation is skipped for fields outside the focus scope. This lets you validate a single field even if the full payload does not satisfy the schema.

Schema Types

• enforce.shape({}): Strict shape. No extra keys allowed.
• enforce.loose({}): Loose shape. Extra keys are ignored.
• enforce.partial({}): Partial shape. All keys are optional, but if present must match the type. No extra keys.
• enforce.isArrayOf(rule): Validates an array where every item matches the rule.

Inspecting schema results

The suite result includes a types object that captures the validated input and coerced output from the schema run. This is useful for debugging and type-safe consumers.