Arrays

To validate arrays with a schema you can use array or tuple. You use tuple if your array has a specific shape and array if it has any number of uniform items.

Array schema

The first argument you pass to array is a schema, which is used to validate the items of the array.

import * as v from 'valibot';

const ArraySchema = v.array(v.number()); // number[]

Pipeline validation

To validate the length or contents of the array, you can use its pipeline.

import * as v from 'valibot';

const ArraySchema = v.array(v.string(), [
  v.minLength(1),
  v.maxLength(5),
  v.includes('foo'),
  v.excludes('bar'),
]);

Tuple schema

A tuple is an array with a specific shape. The first argument that you pass to the function is a tuple of schemas that defines its shape.

import * as v from 'valibot';

const TupleSchema = v.tuple([v.string(), v.number()]); // [string, number]

Rest argument

By default, tuple ignores and removes unknown items. This means that items that occur after the items defined by the first argument will not be validated and will not be added to the output. You can control this behavior with the rest argument.

By using never for the rest argument, you can make the validation strict and forbid unknown items completely. If unknown items are detected, an issue is returned for each entry.

import * as v from 'valibot';

const TupleSchema = v.tuple([v.string(), v.number()], v.never());

Alternatively, you can also allow unknown items with unknown and add them to the output. Instead of unknown, you can also use any other schema function, such as string, for a typed output.

import * as v from 'valibot';

const TupleSchema = v.tuple([v.string()], v.unknown()); // [string, ...unknown[]]

Pipeline validation

Similar to array, you can use the pipeline of tuple to validate its length and contents.

import * as v from 'valibot';

const TupleSchema = v.tuple([v.string()], v.string(), [
  v.maxLength(5),
  v.includes('foo'),
  v.excludes('bar'),
]);