Validation

The @talosjs/validation component is a type-safe validation layer built on ArkType, TypeScript’s 1:1 runtime validator. You describe the shape of your data once with Assert({...}), and the same schema both narrows your TypeScript types and validates values at runtime. The package provides Assert, scope, union, and intersection, adds a set of ready-made constraints (email, URL, port, country code, and more), and exposes an abstract Validation class for building your own reusable validators. When a schema is attached to a route, the framework runs it for you before the controller is reached.

What the validation layer gives you

An Assert({...}) definition does two jobs at once: it is a runtime validator and a static TypeScript type, so there are no duplicate interfaces to keep in sync. The syntax is string-based and compact — it is ArkType’s definition syntax, so anything ArkType understands works here. Assert, scope, union, and intersection cover expressions like string.email, number >= 0, 'a' | 'b', and optional keys marked with ?. When a schema is attached to a route as params, queries, or payload, the framework runs it before the controller, and an invalid request produces an error response on its own. A set of ready-made constraints covers the shapes you hit most often (email, URL, port, hostname, locale, currency, country code, hex color, names, IDs), so you aren’t re-writing the same rules. For anything those don’t cover, extend the abstract Validation class with getConstraint and getErrorMessage to package a rule and its message as a reusable class.

How it works

A schema is a function. Calling it with data returns either the validated value or an Assert.errors object. The Validation class wraps that flow into a { isValid, message } result, and the routing layer applies your schemas to incoming requests automatically.

Stage	What happens
Define	`Assert({...})` builds a schema that is both a runtime validator and a static type.
Validate	Calling the schema returns the parsed value, or an instance of `Assert.errors` with a `.summary` describing the failure.
Route input	Schemas on `@Route.http` (`params`, `queries`, `payload`) run before the controller; a failure yields an error response and the controller is skipped.
Custom rule	A `Validation` subclass turns a schema and an optional message into a `validate(data)` method returning `{ isValid, message? }`.

Defining schemas

Use Assert to describe an object. Each value is a schema expression: a primitive, a constrained primitive, a numeric range, a literal union, or an array. Mark a key optional by suffixing it with ?.

import { Assert } from "@talosjs/validation";

const UserSchema = Assert({
  name: "string > 0", // non-empty string
  email: "string.email", // valid email
  age: "number.integer >= 0", // non-negative integer
  "phone?": "string", // optional
  role: "'admin' | 'user'", // literal union
  tags: "string[]", // array of strings
});

const result = UserSchema({
  name: "John",
  email: "john@example.com",
  age: 30,
  role: "user",
  tags: [],
});

if (result instanceof Assert.errors) {
  console.error(result.summary); // human-readable failure description
} else {
  console.log(result); // fully typed, validated value
}

For related types, group them in a scope and export() the result; combine schemas with union and intersection.

import { scope } from "@talosjs/validation";

const $ = scope({
  profile: {
    firstName: "string > 0",
    lastName: "string > 0",
    bio: "string | null",
  },
  user: {
    id: "string.uuid",
    email: "string.email",
    profile: "profile",
  },
}).export();

const user = $.user({
  id: crypto.randomUUID(),
  email: "a@b.com",
  profile: { firstName: "Jane", lastName: "Doe", bio: null },
});

Validation in routing

The most common place you use validation is on a route. Pass schemas to @Route.http and the framework validates the request before your controller’s index runs, so inside the controller the data is already guaranteed to match.

import { Route } from "@talosjs/routing";
import { Assert } from "@talosjs/validation";
import type { ContextType, IController } from "@talosjs/controller";

const CreateUserPayload = Assert({
  name: "string > 0",
  email: "string.email",
  password: "string >= 8",
});

@Route.http({
  name: "api.users.create",
  path: "/api/users",
  method: "POST",
  payload: CreateUserPayload,
})
export class UserCreateController implements IController {
  public async index(context: ContextType) {
    // Already validated — invalid requests never reach here
    const { name, email } = context.payload;
    return context.response.json({ user: { name, email } });
  }
}

params validates path parameters (e.g. :id in the path).
queries validates the query string.
payload validates the request body.

If any of them fail, the request is rejected with an error response and the controller is never invoked. See Routing for the full route options, Request for how input reaches the context, and Response for the shape of the returned errors.

Built-in constraints

Import these from @talosjs/validation/constraints. Each is a Validation subclass: construct it and call validate(data) to get a { isValid, message? } result.

import { AssertEmail, AssertPort } from "@talosjs/validation/constraints";

const result = new AssertEmail().validate("user@example.com");
console.log(result.isValid); // true

Constraint	Validates
`AssertEmail`	A valid email address.
`AssertUrl`	A URL (1–2083 chars, `http`/`https`, no `..` or trailing dots); also offers `validateStrict` requiring a protocol.
`AssertYoutubeUrl`	A YouTube watch URL (`youtube.com/watch?v=…` or `youtu.be/…`).
`AssertHostname`	A hostname or IPv4 address (also accepts an empty string).
`AssertPort`	An integer port between 1 and 65535.
`AssertHexaColor`	A 3- or 6-digit hex color (e.g. `#fff`, `#A1B2C3`).
`AssertCountryCode`	A 2-letter uppercase ISO 3166-1 alpha-2 code.
`AssertCurrency`	A valid ISO 4217 currency code (3 uppercase letters).
`AssertLocale`	A supported locale code from `@talosjs/translation`.
`AssertAppEnv`	A valid application environment value.
`AssertName`	A name (1–50 chars, letters/numbers/spaces/`-'.`, trimmed).
`AssertFirstName`	A first name (1–50 chars, letters, spaces, hyphens, apostrophes).
`AssertLastName`	A last name (1–50 chars, letters, spaces, hyphens, apostrophes).
`AssertId`	A 25-character lowercase hexadecimal ID.
`AssertDescription`	Free text between 1 and 5000 characters.
`AssertChatQuery`	Chat text (1–2000 chars) with no HTML, scripts, or unsafe protocols.

Custom validators

To package a rule of your own, extend the abstract Validation class. It requires two methods and gives you validate for free.

public abstract getConstraint(): AssertType;       // the schema to check against
public abstract getErrorMessage(): string | null;  // custom message, or null for the default summary

validate(data, constraint?) calls the schema; on failure it returns your getErrorMessage() (falling back to the schema’s summary), otherwise { isValid: true }.

import { Validation, Assert } from "@talosjs/validation";
import type { AssertType } from "@talosjs/validation";

class PositiveNumberValidator extends Validation {
  public getConstraint(): AssertType {
    return Assert("number > 0");
  }

  public getErrorMessage(): string | null {
    return "Value must be a positive number";
  }
}

const result = new PositiveNumberValidator().validate(42);
console.log(result.isValid); // true

This is the same pattern the built-in constraints use, and the same one you reach for when validating Entity fields with a shared, named rule.

Inline assertions and utilities

Assert builds a schema you can call immediately to check a value, which is handy for one-off assertions without defining a named schema.

import { Assert } from "@talosjs/validation";

const out = Assert("string.email")("john@example.com");
const isInvalid = out instanceof Assert.errors;

jsonSchemaToTypeString(schema) converts a JSON Schema object into a readable TypeScript-style type string, handling primitives, arrays, objects with required/optional keys, and anyOf/oneOf/allOf unions and intersections. Pair it with a schema’s toJsonSchema() for documentation or AI-output descriptions.

import { Assert, jsonSchemaToTypeString } from "@talosjs/validation";

const ProductSchema = Assert({ name: "string", price: "number" });
console.log(jsonSchemaToTypeString(ProductSchema.toJsonSchema())); // "{ name: string; price: number }"

Types

AssertType: alias for the schema Type; the return type of getConstraint and the type of any schema.
IAssert: the interface implemented by every validator (getConstraint, getErrorMessage, and validate).
ValidationResultType: the result of validate, { isValid: boolean; message?: string }.

Getting the most from schemas

Attach schemas to @Route.http (params, queries, payload) so bad input is rejected before any business logic runs. Export a schema once and reuse it for routing, custom validators, and JSON Schema generation rather than re-describing the same shape in several places. Reach for AssertEmail, AssertPort, and the other ready-made constraints before writing your own, and extend Validation only for rules that genuinely don’t exist yet. When you do write a custom rule, return a clear getErrorMessage() so a failure explains what was expected instead of leaning on the raw summary. Mark optional fields with the ? key suffix so the static type and the runtime check stay in agreement. See Routing, Request, Response, and Entity for the surfaces that consume these schemas.

Getting Started

AI

Framework

Command Line

What the validation layer gives you

How it works

Defining schemas

Validation in routing

Built-in constraints

Custom validators

Inline assertions and utilities

Types

Getting the most from schemas

​What the validation layer gives you

​How it works

​Defining schemas

​Validation in routing

​Built-in constraints

​Custom validators

​Inline assertions and utilities

​Types

​Getting the most from schemas

What the validation layer gives you

How it works

Defining schemas

Validation in routing

Built-in constraints

Custom validators

Inline assertions and utilities

Types

Getting the most from schemas