variant

Creates a variant schema.

const Schema = v.variant<TKey, TOptions, TMessage>(key, options, message);

Generics

• TKey extends string
• TOptions extends VariantOptions<TKey>
• TMessage extends ErrorMessage<VariantIssue> | undefined

Parameters

• key TKey
• options TOptions
• message TMessage

Explanation

With variant you can validate if the input matches one of the given object options. The object schema to be used for the validation is determined by the discriminator key. If the input does not match a schema and cannot be clearly assigned to one of the options, you can use message to customize the error message.

It is allowed to specify the exact same or a similar discriminator multiple times. However, in such cases variant will only return the output of the first untyped or typed variant option result. Typed results take precedence over untyped ones.

Returns

• Schema VariantSchema<TKey, TOptions, TMessage>

Examples

The following examples show how variant can be used.

Variant schema

Schema to validate an email, URL or date variant.

const VariantSchema = v.variant('type', [
  v.object({
    type: v.literal('email'),
    email: v.pipe(v.string(), v.email()),
  }),
  v.object({
    type: v.literal('url'),
    url: v.pipe(v.string(), v.url()),
  }),
  v.object({
    type: v.literal('date'),
    date: v.pipe(v.string(), v.isoDate()),
  }),
]);

Nested variant schema

You can also nest variant schemas.

const NestedVariantSchema = v.variant('type', [
  VariantSchema,
  v.object({
    type: v.literal('color'),
    date: v.pipe(v.string(), v.hexColor()),
  }),
]);

Related

The following APIs can be combined with variant.

Schemas

• object

Methods

• config,
• fallback,
• getDefault,
• getDefaults,
• getFallback,
• getFallbacks,
• is,
• parse,
• parser,
• pipe,
• safeParse,
• safeParser

Actions

• check,
• brand,
• partialCheck,
• rawCheck,
• rawTransform,
• readonly,
• transform

Utils

• entriesFromList,
• isOfKind,
• isOfType