Schema API
Generated public TypeScript reference for relkit/schema.
Common APIs
For configuration and examples, read Runtime schemas, requests, uploads.
For a complete workflow, follow upload product images.
Most-used APIs
These entries carry each API’s contract and example. The complete reference follows.
z
Signature
declare const z: ZBuilder;
validate
Validates with a Standard Schema v1 compatible validator.
Throws
TypeError when the validator does not implement Standard Schema v1.
Example
import { validate, z } from "relkit/schema";
const result = await validate(z.string(), "ready");
if (!("value" in result)) throw new Error("validation failed");
Signature
declare const validate: <S extends StandardSchemaV1>(
schema: S,
value: InferInput<S>,
) => StandardResult<InferOutput<S>> | Promise<StandardResult<InferOutput<S>>>;
Since v0.1.0
Complete reference
Public imports
relkit/schema— 62 exports
All exported APIs
Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API’s inline sample, a maintained repository usage, or the shared module walkthrough.
builder-composites.ts
arraySchema
Builds an array validator from one item schema.
Example
arraySchema(z.number());
Signature
declare const arraySchema: <S extends AnySchema>(schema: S) => Schema<InputOf<S>[], OutputOf<S>[]>;
objectSchema
Builds an object validator from named child schemas.
Example
objectSchema({ id: z.string() });
Signature
declare const objectSchema: <S extends Shape>(shape: S) => Schema<ObjectInput<S>, ObjectOutput<S>>;
unionSchema
Builds a nonempty union with first-success precedence.
Example
unionSchema([z.string(), z.number()]);
Signature
declare const unionSchema: <S extends SchemaTuple>(
schemas: S,
) => Schema<InputOf<S[number]>, OutputOf<S[number]>>;
builder-composites.types.ts
AnySchema (type alias)
Any compatible validator accepted by a composite builder.
Example
const child: AnySchema = z.string();
Signature
type AnySchema = StandardSchemaV1;
InputOf (type alias)
Accepted input of a child validator.
Example
type Input = InputOf<typeof schema>;
Signature
type InputOf<S extends AnySchema> = InferInput<S>;
ObjectInput (type alias)
Object input with optional keys inferred from child schemas.
Example
type Input = ObjectInput<{ id: typeof idSchema }>;
Signature
type ObjectInput<S extends Shape> = {
[K in RequiredInputKeys<S>]: InputOf<S[K]>;
} & {
[K in OptionalInputKeys<S>]?: Exclude<InputOf<S[K]>, undefined>;
};
ObjectOutput (type alias)
Object output with optional keys inferred from child schemas.
Example
type Output = ObjectOutput<{ id: typeof idSchema }>;
Signature
type ObjectOutput<S extends Shape> = {
[K in RequiredOutputKeys<S>]: OutputOf<S[K]>;
} & {
[K in OptionalOutputKeys<S>]?: Exclude<OutputOf<S[K]>, undefined>;
};
OutputOf (type alias)
Validated output of a child validator.
Example
type Output = OutputOf<typeof schema>;
Signature
type OutputOf<S extends AnySchema> = InferOutput<S>;
SchemaTuple (type alias)
Nonempty tuple of union members, preserving declaration order.
Example
const members: SchemaTuple = [z.string(), z.number()];
Signature
type SchemaTuple = readonly [AnySchema, ...AnySchema[]];
Shape (type alias)
Named child validators for an object schema.
Example
const shape: Shape = { id: z.string() };
Signature
type Shape = Record<string, AnySchema>;
builder-effect.ts
SchemaBuilderError (class)
Tagged failure when a schema builder rejects options or its dependencies throw.
The original exception remains available in cause.
Example
Effect.catchTag("SchemaBuilderError", (error) => Effect.succeed(error.cause));
Signature
declare class SchemaBuilderError
buildSchema
Runs a synchronous schema builder and preserves its original error.
Throws
The original construction error.
Example
buildSchema("builder.string", () => z.string());
Signature
declare const buildSchema: <A>(operation: SchemaOperation, build: () => A) => A;
buildSchemaEffect
Constructs a schema inside an observed Effect.
Example
Effect.runSync(buildSchemaEffect("builder.string", () => z.string()));
Signature
declare const buildSchemaEffect: <A>(
operation: SchemaOperation,
build: () => A,
) => Effect.Effect<A, SchemaBuilderError>;
builder-refinements.ts
numberSchema
Builds a finite-number schema with numeric refinements.
Example
numberSchema().int().parse(2);
Signature
declare const numberSchema: () => NumberSchema;
stringSchema
Builds a string schema with format and length refinements.
Example
stringSchema().min(2).parse("ok");
Signature
declare const stringSchema: () => StringSchema;
builder-refinements.types.ts
NumberSchema (interface)
Finite-number schema with range and integer refinement methods.
Example
const schema: NumberSchema = z.number().int();
Signature
export interface NumberSchema extends Schema<number, number> {
/**
* Requires an inclusive minimum.
* @param value - Minimum value.
* @param message - Optional issue text.
* @returns A refined number schema.
* @example z.number().min(1);
*/
min(value: number, message?: string): NumberSchema;
/**
* Requires an inclusive maximum.
* @param value - Maximum value.
* @param message - Optional issue text.
* @returns A refined number schema.
* @example z.number().max(10);
*/
max(value: number, message?: string): NumberSchema;
/**
* Requires an integer.
* @param message - Optional issue text.
* @returns An integer schema.
* @example z.number().int();
*/
int(message?: string): NumberSchema;
/**
* Requires a value above zero.
* @param message - Optional issue text.
* @returns A positive number schema.
* @example z.number().positive();
*/
positive(message?: string): NumberSchema;
/**
* Requires a value of zero or greater.
* @param message - Optional issue text.
* @returns A nonnegative number schema.
* @example z.number().nonnegative();
*/
nonnegative(message?: string): NumberSchema;
}
StringSchema (interface)
String schema with length and format refinement methods.
Example
const schema: StringSchema = z.string().min(1);
Signature
export interface StringSchema extends Schema<string, string> {
/**
* Requires a minimum string length.
* @param length - Minimum length.
* @param message - Optional issue text.
* @returns A refined string schema.
* @example z.string().min(2);
*/
min(length: number, message?: string): StringSchema;
/**
* Requires a maximum string length.
* @param length - Maximum length.
* @param message - Optional issue text.
* @returns A refined string schema.
* @example z.string().max(8);
*/
max(length: number, message?: string): StringSchema;
/**
* Requires a UUID string.
* @param message - Optional issue text.
* @returns A UUID string schema.
* @example z.string().uuid();
*/
uuid(message?: string): StringSchema;
/**
* Requires a parseable datetime string.
* @param message - Optional issue text.
* @returns A datetime string schema.
* @example z.string().datetime();
*/
datetime(message?: string): StringSchema;
/**
* Requires an email address string.
* @param message - Optional issue text.
* @returns An email string schema.
* @example z.string().email();
*/
email(message?: string): StringSchema;
}
builder.ts
s
Builds RelKit Standard Schema validators with familiar composition helpers.
Example
import { s } from "relkit/schema";
const order = s.object({ id: s.string(), quantity: s.number().int().positive() });
order.parse({ id: "order-1", quantity: 2 });
Signature
declare const s: ZBuilder;
Since v0.9.0
z
The built-in schema builder’s former name; z and s are the same builder. relkit migrate
rewrites z to s.
Example
import { z } from "relkit/schema";
const order = z.object({ id: z.string(), quantity: z.number().int().positive() });
order.parse({ id: "order-1", quantity: 2 });
Signature
declare const z: ZBuilder;
Since v0.1.0
AnySchema
Any compatible validator accepted by a composite builder.
Example
const child: AnySchema = z.string();
Signature
type AnySchema = StandardSchemaV1;
InputOf
Accepted input of a child validator.
Example
type Input = InputOf<typeof schema>;
Signature
type InputOf<S extends AnySchema> = InferInput<S>;
NumberSchema
Finite-number schema with range and integer refinement methods.
Example
const schema: NumberSchema = z.number().int();
Signature
export interface NumberSchema extends Schema<number, number> {
/**
* Requires an inclusive minimum.
* @param value - Minimum value.
* @param message - Optional issue text.
* @returns A refined number schema.
* @example z.number().min(1);
*/
min(value: number, message?: string): NumberSchema;
/**
* Requires an inclusive maximum.
* @param value - Maximum value.
* @param message - Optional issue text.
* @returns A refined number schema.
* @example z.number().max(10);
*/
max(value: number, message?: string): NumberSchema;
/**
* Requires an integer.
* @param message - Optional issue text.
* @returns An integer schema.
* @example z.number().int();
*/
int(message?: string): NumberSchema;
/**
* Requires a value above zero.
* @param message - Optional issue text.
* @returns A positive number schema.
* @example z.number().positive();
*/
positive(message?: string): NumberSchema;
/**
* Requires a value of zero or greater.
* @param message - Optional issue text.
* @returns A nonnegative number schema.
* @example z.number().nonnegative();
*/
nonnegative(message?: string): NumberSchema;
}
ObjectInput
Object input with optional keys inferred from child schemas.
Example
type Input = ObjectInput<{ id: typeof idSchema }>;
Signature
type ObjectInput<S extends Shape> = {
[K in RequiredInputKeys<S>]: InputOf<S[K]>;
} & {
[K in OptionalInputKeys<S>]?: Exclude<InputOf<S[K]>, undefined>;
};
ObjectOutput
Object output with optional keys inferred from child schemas.
Example
type Output = ObjectOutput<{ id: typeof idSchema }>;
Signature
type ObjectOutput<S extends Shape> = {
[K in RequiredOutputKeys<S>]: OutputOf<S[K]>;
} & {
[K in OptionalOutputKeys<S>]?: Exclude<OutputOf<S[K]>, undefined>;
};
OutputOf
Validated output of a child validator.
Example
type Output = OutputOf<typeof schema>;
Signature
type OutputOf<S extends AnySchema> = InferOutput<S>;
SchemaTuple
Nonempty tuple of union members, preserving declaration order.
Example
const members: SchemaTuple = [z.string(), z.number()];
Signature
type SchemaTuple = readonly [AnySchema, ...AnySchema[]];
Shape
Named child validators for an object schema.
Example
const shape: Shape = { id: z.string() };
Signature
type Shape = Record<string, AnySchema>;
StringSchema
String schema with length and format refinement methods.
Example
const schema: StringSchema = z.string().