Issues

When validating unknown data against a schema, I collect information about each issue and at the end, if there is at least one issue, I return them in an array. Each issue provides detailed information for you or your users to fix the problem.

Issue info

The issues are an array of objects. In the following I will explain you exactly what information an issue contains and how this information can help you.

type SchemaIssue = {
  // Required info
  reason: IssueReason;
  context: string;
  input: unknown;
  expected: string | null;
  received: string;
  message: string;

  // Optional info
  requirement?: unknown;
  path?: IssuePath;
  issues?: Issues;
  lang?: string;
  abortEarly?: boolean;
  abortPipeEarly?: boolean;
  skipPipe?: boolean;
};

Required info

Each issue contains the following required information.

Reason

reason describes the reason of the problem. If an input does not match the data type, for example a number was passed instead of a string, reason has the value 'type'. In all other cases the reason is not the datatype but the actual content of the data. For example, if a string is invalid because it does not match a regex, reason has the value 'string'.

Context

context describes which function did the validation. If the schema function array detects that the input is not an array, context has the value 'array'. If the minLength validation function detects that an array is too short, context has the value 'min_length'.

Input

input contains the input data where the issue was found. For complex data, for example objects, input contains the value of the respective key that does not match the schema.

Expected

expected is a language-neutral string that describes the data property that was expected. It can be used to create useful error messages. If your users aren't developers, you can replace the language-neutral symbols with language-specific words.

Received

received is a language-neutral string that describes the data property that was received. It can be used to create useful error messages. If your users aren't developers, you can replace the language-neutral symbols with language-specific words.

Message

message contains a human-understandable error message that can be fully customized as described in our schemas and internationalization guide.

Optional info

Some issues contain further optional information.

Requirement

requirement can contain further validation information. For example, if the minLength validation function detects that a string is too short, requirement contains the minimum length that the string should have.

Path

path is an array of objects that describes where an issue is located within complex data. Each path item contains the following information.

type PathItem = {
  schema: string;
  origin: 'key' | 'value';
  input: unknown;
  key: string | number | symbol;
  value: unknown;
};

For example, you can use the following code to create a dot path.

const dotPath = issue.path.map((item) => item.key).join('.');

Issues

issues currently only occur when using union and contains all issues of the schemas of an union type.

Config

lang can be used as part of our i18n feature to define the required language. abortEarly and abortPipeEarly gives you an info that the validation was aborted prematurely. You can find more info about this in the parse data guide. skipPipe indicates that the pipeline validation was skipped. These are all configurations that you can control yourself.

Formatting

For common use cases like forms, I can help you with small functions to format issues. However, once you understand how they work, you can easily format them yourself and put them in the right form for your use case.

Flatten errors

If you are only interested in the error messages of each issue to show them to your users, you can convert an array of issues or a ValiError to a flat object with flatten. Below is an example.

import * as v from 'valibot';

const ObjectSchema = v.object({
  key: v.string('Value of "key" is missing.'),
  nested: v.object({
    key: v.string('Value of "nested.key" is missing.'),
  }),
});

try {
  v.parse(ObjectSchema, { nested: {} }); // Throws an error
} catch (error) {
  console.log(v.flatten<typeof ObjectSchema>(error));
}

The ValiError thrown in the code sample above this text contains the following issues.

[
  {
    reason: 'type',
    context: 'string',
    input: undefined,
    expected: 'string',
    received: 'undefined',
    message: 'Value of "key" is missing.',
    path: [
      {
        schema: 'object',
        origin: 'value',
        input: { nested: {} },
        key: 'key',
        value: undefined,
      },
    ],
  },
  {
    reason: 'type',
    context: 'string',
    input: undefined,
    expected: 'string',
    received: 'undefined',
    message: 'Value of "nested.key" is missing.',
    path: [
      {
        schema: 'object',
        origin: 'value',
        input: { nested: {} },
        key: 'nested',
        value: {},
      },
      {
        schema: 'object',
        origin: 'value',
        input: {},
        key: 'key',
        value: undefined,
      },
    ],
  },
];

However, with the help of flatten the issues were converted to the following object.

{
  nested: {
    key: ['Value of "key" is missing.'],
    'nested.key': ['Value of "nested.key" is missing.']
  }
}