Unions

An union represents a logical OR relationship. You can apply this concept to your schemas with union and variant. For discriminated unions you use variant and in all other cases you use union.

Union schema

The schema function union creates an OR relationship between any number of schemas that you pass as the first argument in the form of an array. On validation, the schema returns the result of the first schema that was successfully validated.

import * as v from 'valibot';

// TypeScript
type Union = string | number;

// Valibot
const UnionSchema = v.union([v.string(), v.number()]);

If a bad input can be uniquely assigned to one of the schemas based on the data type, the result of that schema is returned. Otherwise, a general issue is returned that contains the issues of each schema as subissues. This is a special case within the library, as the issues of union can contradict each other.

The following issues are returned if the input is null instead of a string or number. Since the input cannot be associated with a schema in this case, the issues of both schemas are returned as subissues.

[
  {
    kind: 'schema',
    type: 'union',
    input: null,
    expected: 'string | number',
    received: 'null',
    message: 'Invalid type: Expected string | number but received null',
    issues: [
      {
        kind: 'schema',
        type: 'string',
        input: null,
        expected: 'string',
        received: 'null',
        message: 'Invalid type: Expected string but received null',
      },
      {
        kind: 'schema',
        type: 'number',
        input: null,
        expected: 'number',
        received: 'null',
        message: 'Invalid type: Expected number but received null',
      },
    ],
  },
];

Variant schema

For better performance, more type safety, and a more targeted output of issues, you can use variant for discriminated unions. Therefore, we recommend using variant over union whenever possible. A discriminated union is an OR relationship between objects that can be distinguished by a specific key.

When you call the schema function, you first specify the discriminator key. This is used to determine the schema to use for validation based on the input. The object schemas, in the form of an array, follow as the second argument.

import * as v from 'valibot';

const VariantScheme = v.variant('type', [
  v.object({
    type: v.literal('foo'),
    foo: v.string(),
  }),
  v.object({
    type: v.literal('bar'),
    bar: v.number(),
  }),
]);

For very complex datasets, multiple variant schemas can also be deeply nested within one another.