Objects

To validate objects with a schema, you can use object or record. You use object for an object with a specific shape and record for objects with any number of uniform entries.

Object schema

The first argument is used to define the specific structure of the object. Each entry consists of a key and a schema as the value. The entries are then validated against the key and schema.

import * as v from 'valibot';

const ObjectSchema = v.object({
  key1: v.string(),
  key2: v.number(),
});

Rest argument

By default, object ignores and removes unknown entries. This means that entries that you have not defined in 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 entries completely. If unknown entries are detected, an issue is returned for each entry.

import * as v from 'valibot';

const ObjectSchema = v.object(
  {
    key1: v.string(),
    key2: v.number(),
  },
  v.never()
);

Alternatively, you can also allow unknown entries 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 ObjectSchema = v.object(
  {
    key1: v.string(),
    key2: v.number(),
  },
  v.unknown()
);

Pipeline validation

To validate the value of an entry based on another entry, you can use custom in the object's pipeline. You can also use forward to assign the issue to a specific object key in the event of an error.

import * as v from 'valibot';

const CalculationSchema = v.object(
  {
    a: v.number(),
    b: v.number(),
    sum: v.number(),
  },
  [
    v.forward(
      v.custom(
        ({ a, b, sum }) => a + b === sum,
        'The calculation is incorrect.'
      ),
      ['sum']
    ),
  ]
);

Record schema

For an object with any number of uniform entries, record is the right choice. If you pass only one schema as an argument to the function, this will be used to validate the values of the record. In this case, the keys are automatically validated with string.

import * as v from 'valibot';

const RecordSchema = v.record(v.number()); // Record<string, number>

Key argument

To explicitly define the schema of the keys, you can pass two schemas to record. The first schema will be used for the keys and the second schema for the values.

import * as v from 'valibot';

const RecordSchema = v.record(v.string(), v.number()); // Record<string, number>

Instead of string, you can also use enum_, picklist, special or union to validate the keys.

import * as v from 'valibot';

const RecordSchema = v.record(v.picklist(['key1', 'key2']), v.number()); // { key1?: number; key2?: number }

Pipeline validation

To validate the value of an entry based on another entry, you can use custom in the records's pipeline. You can also use forward to assign the issue to a specific record key in the event of an error.

import * as v from 'valibot';

const CalculationSchema = v.record(v.picklist(['a', 'b', 'sum']), v.number(), [
  v.forward(
    v.custom(
      ({ a, b, sum }) => (a || 0) + (b || 0) === (sum || 0),
      'The calculation is incorrect.'
    ),
    ['sum']
  ),
]);