Developers can define custom validation logic beyond basic type checks, giving more control over how data is validated.
Declaring Filters
Filters are declared using the Schema.filter function. This function requires two arguments: the schema to be validated and a predicate function. The predicate function is user-defined and determines whether the data satisfies the condition. If the data fails the validation, an error message can be provided.
Example
Note that the filter does not modify the schema’s Type:
Filters add additional validation constraints but do not alter the schema’s underlying type.
The Predicate Function
The predicate function in a filter follows this structure:
where
The filter’s predicate can return several types of values, each affecting validation in a different way:
Return Type
Behavior
true
The data satisfies the filter’s condition and passes validation.
false or undefined
The data does not meet the condition, and no specific error message is provided.
string
The validation fails, and the provided string is used as the error message.
ParseResult.ParseIssue
The validation fails with a detailed error structure, specifying where and why it failed.
FilterIssue
Allows for more detailed error messages with specific paths, providing enhanced error reporting.
ReadonlyArray<FilterOutput>
An array of issues can be returned if multiple validation errors need to be reported.
Adding Annotations
It’s beneficial to embed as much metadata as possible within the schema. This metadata can include identifiers, JSON schema specifications, and descriptive text to facilitate later analysis and understanding of the schema’s purpose and constraints.
Example
Specifying Error Paths
When validating forms or structured data, it’s possible to associate specific error messages with particular fields or paths. This enhances error reporting and is especially useful when integrating with libraries like react-hook-form.
Example (Match Passwords)
In this example, we define a MyForm schema with two password fields (password and confirm_password). We use Schema.filter to check that both passwords match. If they don’t, an error message is returned, specifically associated with the confirm_password field. This makes it easier to pinpoint the exact location of the validation failure.
The error is formatted in a structured way using ArrayFormatter, allowing for easier post-processing and integration with form libraries.
Multiple Error Reporting
The Schema.filter API supports reporting multiple validation issues at once, which is especially useful in scenarios like form validation where several checks might fail simultaneously.
Example (Reporting Multiple Validation Errors)
In this example, we define a MyForm schema with fields for password validation and optional name/surname fields. The Schema.filter function checks if the passwords match and ensures that either a name or surname is provided. If either validation fails, the corresponding error message is associated with the relevant field and both errors are returned in a structured format.
Exposed Values
When working with schemas that have filters, you can access the base schema (the schema before the filter was applied) using the from property: