How to Validate

This page explains how to validate data against a schema.

validation provides:

• an async helper that works with both async and sync schemas
• a sync helper that only works with synchronous schemas
• reusable validator factories that accept the same throwOnError options

If you are new to schema validation, read Concepts first.

standardValidate

Use standardValidate as the default choice.

It works with:

• synchronous schemas
• asynchronous schemas

So one API covers both cases.

Both throwOnError modes exist so you can match different control-flow styles:

• throw immediately in imperative flows where invalid input should stop execution
• handle errors as data in functional or pipeline-based flows

Throwing on Error

import { standardValidate } from "@zap-studio/validation";

const user = await standardValidate(userSchema, input, {
  throwOnError: true,
});

• returns parsed value on success
• throws ValidationError on failure

Handle Errors Manually

Use this mode when you want full control over branching, logging, and error mapping without exceptions.

const result = await standardValidate(userSchema, input, {
  throwOnError: false,
});

if (result.issues) {
  // handle issues
} else {
  // use result.value
}

standardValidateSync

Use standardValidateSync only when validation must remain synchronous end-to-end.

Typical cases include limited or constrained runtimes where you explicitly need sync-only execution paths.

import { standardValidateSync } from "@zap-studio/validation";

const result = standardValidateSync(userSchema, input);

This is useful in sync-only code paths (e.g. deterministic in-memory checks).

Important behavior:

• if schema validation is async, standardValidateSync throws

Which One Should I Use?

• Use standardValidate by default for compatibility and simpler call sites.
• Use standardValidateSync only when synchronous behavior is a hard requirement.

Reusable Validators

If you reuse one schema across many calls, prefer:

• createStandardValidator
• createSyncStandardValidator

The returned validator functions support the same throwOnError modes as standardValidate and standardValidateSync.