Schema validation with Valibot, the modular and type-safe schema library. Use when the user needs to validate data, create schemas, parse inputs, or work with Valibot in their project. Also use when migrating from Zod to Valibot.

Valibot This skill helps you work effectively with [Valibot](https://valibot.dev), the modular and type safe schema library for validating structural data. When to use this skill When the user asks about schema validation with Valibot When creating or modifying Valibot schemas When parsing or validating user input When the user mentions Valibot, schema, or validation When migrating from Zod to Valibot CRITICAL: Valibot vs Zod — Do Not Confuse! Valibot and Zod have different APIs. Never mix them up! Key Differences Feature Zod ❌ Valibot ✅ Import import { z } from 'zod' import as v from 'valibot' Validations Chained methods: .email().min(5) Pipeline: v.pipe(v.string(), v.email(), v.minLength(5)) Parsing schema.parse(data) v.parse(schema, data) Safe parsing schema.safeParse(data) v.safeParse(schema, data) Optional z.string().optional() v.optional(v.string()) Nullable z.string().nullable() v.nullable(v.string()) Default z.string().default('x') v.optional(v.string(), 'x') Transform z.string().transform(fn) v.pipe(v.string(), v.transform(fn)) Refine/Check z.string().refine(fn) v.pipe(v.string(), v.check(fn)) Enum z.enum(['a', 'b']) v.picklist(['a', 'b']) Native enum z.nativeEnum(MyEnum) v.enum(MyEnum) Union z.union([a, b]) v.union([a, b]) Discriminated union z.discriminatedUnion('type', [...]) v.variant('type', [...]) Intersection z.intersection(a, b) v.intersect([a, b]) Min/max length .min(5).max(10) v.minLength(5), v.maxLength(10) Min/max value .gte(5).lte(10) v.minValue(5), v.maxValue(10) Infer type z.infer<typeof Schema v.InferOutput<typeof Schema Infer input z.input<typeof Schema v.InferInput<typeof Schema Common Mistakes to Avoid Installation Import with a wildcard (recommended): Or with individual imports: Mental Model Valibot's API is divided into three main concepts: 1. Schemas Schemas define the expected data type. They are the starting point. 2. Methods Methods help you use or modify schemas. The schema is always the first argument. 3. Actions Actions validate or transform data within a pipe() . They MUST be used inside pipelines. Pipelines Pipelines extend schemas with validation and transformation actions. A pipeline always starts with a schema, followed by actions. Common Validation Actions String validations: v.email() — Valid email format v.url() — Valid URL format v.uuid() — Valid UUID format v.regex(pattern) — Match regex pattern v.minLength(n) — Minimum length v.maxLength(n) — Maximum length v.length(n) — Exact length v.nonEmpty() — Not empty string v.startsWith(str) — Starts with string v.endsWith(str) — Ends with string v.includes(str) — Contains string Number validations: v.minValue(n) — Minimum value ( =) v.maxValue(n) — Maximum value (<=) v.gtValue(n) — Greater than ( ) v.ltValue(n) — Less than (<) v.integer() — Must be integer v.finite() — Must be finite v.safeInteger() — Safe integer range v.multipleOf(n) — Must be multiple of n Array validations: v.minLength(n) — Minimum items v.maxLength(n) — Maximum items v.length(n) — Exact item count v.nonEmpty() — At least one item v.includes(item) — Contains item v.excludes(item) — Does not contain item Custom Validation with check() Value Transformations These actions modify the value without changing its type: String transformations: v.trim() — Remove leading/trailing whitespace v.trimStart() — Remove leading whitespace v.trimEnd() — Remove trailing whitespace v.toLowerCase() — Convert to lowercase v.toUpperCase() — Convert to uppercase Number transformations: v.toMinValue(n) — Clamp to minimum value (if less than n, set to n) v.toMaxValue(n) — Clamp to maximum value (if greater than n, set to n) Type Transformations For converting between data types, use these built in transformation actions: v.toNumber() — Convert to number v.toString() — Convert to string v.toBoolean() — Convert to boolean v.toBigint() — Convert to bigint v.toDate() — Convert to Date Custom Transformations For custom transformations, use v.transform() : Object Schemas Basic Object Object Variants Optional and Nullable Fields Object Methods Cross Field Validation Arrays and Tuples Arrays Tuples Unions and Variants Union Picklist (for string/number literals) Variant (discriminated union) Use variant for better performance with discriminated unions: Parsing Data parse() — Throws on Error safeParse() — Returns Result Object is() — Type Guard Configuration Options Type Inference Error Handling Custom Error Messages Flattening Errors Issue Structure Each issue contains: kind : 'schema' 'validation' 'transformation' type : Function name (e.g., 'string', 'email', 'min length') input : The problematic input expected : What was expected received : What was received message : Human readable message path : Array of path items for nested issues Fallback Values Recursive Schemas Async Validation For async operations (e.g., database checks), use async variants: JSON Schema Conversion Naming Conventions Convention 1: Same Name (Recommended for simplicity) Convention 2: With Suffixes (Recommended when input/output differ) Common Patterns Login Form API Response Environment Variables Date Handling Additional Resources [Valibot Documentation](https://valibot.dev) [Valibot GitHub](https://github.com/open circle/valibot) [API Reference](https://valibot.dev/api/) [Migration from Zod](https://valibot.dev/guides/migrate from zod/)