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 BaseIssue = {
  // Required info
  kind: 'schema' | 'validation' | 'transformation';
  type: 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.

Kind

kind describes the kind of the problem. If an input does not match the data type, for example a number was passed instead of a string, kind has the value 'schema'. 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, kind has the value 'validation'.

Type

type describes which function did the validation. If the schema function array detects that the input is not an array, type has the value 'array'. If the minLength validation function detects that an array is too short, type 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 = {
  type: string;
  origin: 'key' | 'value';
  input: unknown;
  key?: unknown;
  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 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.'),
  }),
});

const result = v.safeParse(ObjectSchema, { nested: {} });

if (result.issues) {
  console.log(v.flatten<typeof ObjectSchema>(result.issues));
}

The result returned in the code sample above this text contains the following issues.

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

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.']
  }
}

Contributors

Thanks to all the contributors who helped make this page better!

  • GitHub profile picture of fabian-hiller

Partners

Thanks to our partners who support the project ideally and financially.

Sponsors

Thanks to our GitHub sponsors who support the project financially.

  • GitHub profile picture of dailydotdev
  • GitHub profile picture of KATT
  • GitHub profile picture of osdiab
  • GitHub profile picture of Thanaen
  • GitHub profile picture of ruiaraujo012
  • GitHub profile picture of hyunbinseo
  • GitHub profile picture of caegdeveloper
  • GitHub profile picture of seahindeniz