Predicates

Most users should start with builder methods. They create predicate IR for you.

Predicate IR

Predicates are the boolean evaluation units inside constraints. A constraint pairs a predicate with error metadata:

{
  "pred": { "type": "call", "name": "is_email" },
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Enter a valid email address"
  }
}

Work with predicate IR directly for advanced rules, schema tooling, and tests.

Predicate Types

PredicateRegistry

Most code does not create a registry. validate(...) uses wellformed's built-in predicates automatically:

import { validate } from "wellformed-ts";

const result = validate(schema, data);

Use PredicateRegistry.withBuiltins() only when you need to add custom predicates and keep the built-ins:

import { PredicateRegistry, createEvalContext, validate } from "wellformed-ts";

const registry = PredicateRegistry.withBuiltins();
registry.register("acme:is_member_id", (value) => {
  return typeof value === "string" && value.startsWith("M-");
});

const context = createEvalContext(registry);
const result = validate(schema, data, { context });

new PredicateRegistry() starts empty. Use it for isolated tests or specialized runtimes that intentionally do not want built-ins.

Named predicates use the call type and are resolved through the active registry at runtime.

Predicate Evolution

A predicate name is a contract. is_email can get a faster implementation, but it should not silently become a different validator.

Examples:

{ "type": "call", "name": "acme:is_member_id_v2" }

{ "type": "call", "name": "is_uuid", "args": { "version": 4 } }

The IR does not include a hidden predicate implementation version. That is intentional. If a schema needs different behavior, the difference should be visible in the schema.

For audit-sensitive systems, store the application schema id or hash with each submission. If exact historical behavior matters, also record the wellformed-ts package version or Rust crate version that evaluated it.

Custom predicate implementations are not serialized. Every runtime that evaluates a schema must register equivalent behavior for each custom predicate name it uses. Put app predicates under an app namespace, such as acme:is_member_id, to avoid colliding with future built-ins.

Common Questions

Built-In Predicates

Taxpayer Identifiers

Financial, Payment, and Product Identifiers

Dates and Times

Amounts and Numeric Values

Reference Data

Contact and Network Fields

Text and String Shape

Aviation

Healthcare and Insurance

Color, Encoding, and Crypto Shape

Custom Predicates

Register custom predicates for organization-specific validation:

const registry = PredicateRegistry.withBuiltins();

registry.register("is_even", (value) => {
  return typeof value === "number" && value % 2 === 0;
});

registry.register("divisible_by", (value, args) => {
  if (typeof value !== "number") return false;
  const divisor = (args as { value: number }).value;
  return value % divisor === 0;
});

withBuiltins() matters here because the registry still needs to know about built-ins such as is_email and is_uuid when the same schema uses them.

Use custom predicates through call predicates:

const schema = w.object({
  count: w.integer(),
}).rule(
  { type: "call", name: "divisible_by", args: { value: 5 } },
  "NOT_DIVISIBLE_BY_5",
  "Count must be divisible by 5",
);

If divisible_by changes meaning later, publish that behavior under a new name or an explicit args option so old schemas keep their original meaning.

Direct Evaluation

For advanced tooling, you can evaluate predicate IR directly:

import { createEvalContext, evaluate } from "wellformed-ts";

const ctx = createEvalContext();

evaluate({ type: "regex", pattern: "^\\d+$" }, "123", ctx); // true
evaluate({ type: "range", min: 0, max: 100 }, 50, ctx); // true
evaluate({ type: "exists", path: "/name" }, { name: "Alice" }, ctx); // true

Direct evaluation is useful for schema tooling, tests, and custom rule builders. Application validation should usually go through validate(...) so transforms, type checks, object rules, and error metadata are handled together.