@agentuity/schema

A lightweight, type-safe schema validation library for the Agentuity platform. Supports the StandardSchema specification.

Features

• 🎯 Type-safe schema validation
• 📦 Lightweight with zero runtime dependencies
• 🔗 StandardSchema v1 compliant
• 🌐 Works in browser and server environments (Node.js, Bun)
• ⚡ Simple, fluent API

Installation

bun add @agentuity/schema

Usage

import { s, ValidationError } from '@agentuity/schema';

// Define a schema
const userSchema = s.object({
    name: s.string(),
    age: s.number(),
    email: s.string(),
    isActive: s.boolean(),
});

// Extract the inferred type (like zod's z.infer)
type User = s.infer<typeof userSchema>;

// Parse with validation (throws on error)
try {
    const user: User = userSchema.parse({
        name: 'John',
        age: 30,
        email: '[email protected]',
        isActive: true,
    });
    console.log('Valid user:', user);
} catch (error) {
    if (error instanceof ValidationError) {
        console.error('Validation failed:', error.message);
        console.error('Issues:', error.issues);
    }
}

// Safe parse (returns result object)
const result = userSchema.safeParse(data);
if (result.success) {
    console.log('Valid data:', result.data);
} else {
    console.error('Validation failed:', result.error.message);
}

// Optional and nullable
const optionalSchema = s.object({
    name: s.string(),
    nickname: s.optional(s.string()),
    age: s.nullable(s.number()),
});

// Arrays
const stringArraySchema = s.array(s.string());
const userArraySchema = s.array(userSchema);

// Unions
const statusSchema = s.union(s.literal('active'), s.literal('inactive'), s.literal('pending'));

// Enums (shorthand for union of literals)
const roleSchema = s.enum(['admin', 'user', 'guest']);
const prioritySchema = s.enum([1, 2, 3, 4, 5]);

// Literal values
const roleSchema = s.literal('admin');

API

Basic Types

• s.string() - String validation
• s.number() - Number validation
• s.boolean() - Boolean validation
• s.null() - Null validation
• s.undefined() - Undefined validation

Complex Types

• s.object(shape) - Object validation with typed properties
• s.array(schema) - Array validation with typed elements

Utility Types

• s.optional(schema) - Makes a schema optional
• s.nullable(schema) - Makes a schema nullable
• s.union(...schemas) - Union of multiple schemas
• s.literal(value) - Exact value matching
• s.enum([...values]) - Enum type (union of literals)

// Enum (shorthand for union of literals)
const roleSchema = s.enum(['admin', 'user', 'guest']);
const role = roleSchema.parse('admin'); // 'admin'

// Equivalent to:
const roleSchema2 = s.union(s.literal('admin'), s.literal('user'), s.literal('guest'));

Coercion

Automatically convert values to the correct type (like zod.coerce):

• s.coerce.string() - Coerce to string using String(value)
• s.coerce.number() - Coerce to number using Number(value)
• s.coerce.boolean() - Coerce to boolean using Boolean(value)
• s.coerce.date() - Coerce to Date using new Date(value)

// Parse form data where everything is a string
const formSchema = s.object({
    name: s.string(),
    age: s.coerce.number(), // "30" → 30
    newsletter: s.coerce.boolean(), // "on" → true
    createdAt: s.coerce.date(), // "2025-01-01" → Date
});

const formData = formSchema.parse({
    name: 'John',
    age: '30', // String coerced to number
    newsletter: 'on', // String coerced to boolean
    createdAt: '2025-01-01', // String coerced to Date
});

// Query parameters (always strings)
const querySchema = s.object({
    page: s.coerce.number(),
    limit: s.coerce.number(),
});

const params = querySchema.parse({
    page: '1', // "1" → 1
    limit: '20', // "20" → 20
});

Documentation

All schemas support a .describe(description: string) method for adding documentation:

const userSchema = s
    .object({
        id: s.string().describe('The unique identifier'),
        name: s.string().describe('The user full name'),
        age: s.number().describe('Age in years'),
    })
    .describe('User profile');

JSON Schema Conversion

Convert schemas to JSON Schema format:

const schema = s.object({
    name: s.string().describe('User name'),
    age: s.number().describe('User age'),
});

const jsonSchema = s.toJSONSchema(schema);
// {
//   "type": "object",
//   "properties": {
//     "name": { "type": "string", "description": "User name" },
//     "age": { "type": "number", "description": "User age" }
//   },
//   "required": ["name", "age"]
// }

Convert JSON Schema to schemas:

const jsonSchema = {
    type: 'object',
    properties: {
        firstName: {
            type: 'string',
            description: 'First name',
        },
        lastName: {
            type: 'string',
            description: 'Last name',
        },
        age: {
            type: 'number',
            description: 'Age',
        },
        hobbies: {
            type: 'array',
            items: { type: 'string' },
        },
    },
    required: ['firstName', 'lastName', 'age', 'hobbies'],
};

const schema = s.fromJSONSchema(jsonSchema);
// Now you can use schema for validation
const result = schema['~standard'].validate(data);

Round-trip conversion is supported:

const original = s.object({ name: s.string() });
const json = s.toJSONSchema(original);
const reconstructed = s.fromJSONSchema(json);
// reconstructed works exactly like original

Parsing & Validation

.parse(value) - Throws on validation error

try {
    const user = userSchema.parse(data);
    // user is typed and validated
} catch (error) {
    if (error instanceof ValidationError) {
        console.error(error.message); // Human-readable error
        console.error(error.issues); // Detailed issue array with paths
    }
}

.safeParse(value) - Returns result object

const result = userSchema.safeParse(data);

if (result.success) {
    console.log(result.data); // Typed data
} else {
    console.error(result.error); // ValidationError instance
}

Type Inference

Use s.infer to extract TypeScript types from schemas (like zod's z.infer):

import { s } from '@agentuity/schema';

const Player = s.object({
    username: s.string(),
    xp: s.number(),
    inventory: s.array(s.string()),
});

// Extract the inferred type (like zod's z.infer)
type Player = s.infer<typeof Player>;
// { username: string; xp: number; inventory: string[] }

const player: Player = Player.parse(data);

You can also import the Infer type directly if preferred:

import { s, type Infer } from '@agentuity/schema';

type Player = Infer<typeof Player>; // Alternative syntax

Error Handling

Validation errors are structured and include paths to the failed fields:

const profileSchema = s.object({
    user: s.object({
        name: s.string(),
        age: s.number(),
    }),
});

try {
    profileSchema.parse({ user: { name: 'John', age: 'thirty' } });
} catch (error) {
    if (error instanceof ValidationError) {
        console.log(error.message);
        // "[user.age]: Expected number, got string"

        console.log(error.issues);
        // [{ message: "Expected number, got string", path: ["user", "age"] }]
    }
}

StandardSchema Support

All schemas implement the StandardSchema v1 interface:

interface StandardSchemaV1<Input, Output> {
    readonly '~standard': {
        readonly version: 1;
        readonly vendor: string;
        readonly validate: (value: unknown) => Result<Output>;
        readonly types?: { input: Input; output: Output };
    };
}

License

Apache-2.0