Other

This guide explains other special schema functions such as literal, instance, custom and lazy that are not covered in the other guides.

Literal schema

You can use literal to define a schema that matches a specific string, number or boolean value. Therefore, this schema is perfect for representing literal types. Usage is simple, just pass the value you want to match as the first argument.

import * as v from 'valibot';

const StringLiteralSchema = v.literal('foo'); // 'foo'
const NumberLiteralSchema = v.literal(12345); // 12345
const BooleanLiteralSchema = v.literal(true); // true

Instance schema

With schema functions like blob, date, map and set Valibot already covers the most common JavaScript classes. However, there are many more classes that you may want to validate. For this purpose, you can use the instance schema function. It takes a class as its first argument and returns a schema that matches only instances of that class.

import * as v from 'valibot';

const ErrorSchema = v.instance(Error); // Error
const UrlSchema = v.instance(URL); // URL

Custom schema

The custom schema function is a bit more advanced. It allows you to define a schema that matches a value based on a custom function. Use it whenever you need to define a schema that cannot be expressed using any of the other schema functions.

The function receives the value to validate as its first argument and must return a boolean value. If the function returns true, the value is considered valid. Otherwise, it is considered invalid.

import * as v from 'valibot';

const PixelStringSchema = v.custom<`${number}px`>((input) =>
  typeof input === 'string' ? /^\d+px$/.test(input) : false
);

Lazy schema

The lazy schema function allows you to define recursive schemas. A recursive schema is a schema that references itself. For example, you can use it to define a schema for a tree-like data structure.

Due to a TypeScript limitation, the input and output types cannot be inferred automatically in this case. Therefore, you must explicitly specify these types using the GenericSchema type.

import * as v from 'valibot';

type BinaryTree = {
  element: string;
  left: BinaryTree | null;
  right: BinaryTree | null;
};

const BinaryTreeSchema: v.GenericSchema<BinaryTree> = v.object({
  element: v.string(),
  left: v.nullable(v.lazy(() => BinaryTreeSchema)),
  right: v.nullable(v.lazy(() => BinaryTreeSchema)),
});