Reach Schema
Functional schema-driven JavaScript object validation library.
Motivation
It happens that JavaScript Object validation libraries are often class-based and operate using via a chain of operators. With Reach Schema I would like to take an alternative approach, making validation functional.
Main concepts of React Schema:
- Validation result is a function from schema and data.
- Validation result is not coupled with the error messages logic.
Reach Schema works great together with functional programming libraries like lodash or ramda. They allow to make validation declaration shorter and make your life easier. Consider those.
Validation schema
Data validity is described using a validation schema. It's a plain Object which keys represent the actual data keys hierarhcy, and values equal to resolver functions that return the validation verdict.
// A plain resolver function that returns a boolean verdict. // A named resolver function that returns a Record of rules.
Applying a validation schema to the actual data returns the validation result.
Resolver
Resolver is a function that determines a value's validity. A simple resolver accepts a value and returns a boolean verdict. Reach Schema supports more complex resolvers, such as grouped resolver, which allows to provide multiple independent criteria to a single value.
Basic resolver
Grouped resolver
Nested schema
Resolver may also return an Object, if validating an Object type value, which would be treated as a nested Validation schema.
Errors
Each validation error has the following structure:
API
useSchema: (schema: Schema, data: Object): ValidationError[]
Basic example
Each key in a schema corresponds to same property in the actual data. Each schema value is a resolver function that accepts an actual data value and returns a Boolean
verdict.
Nested properties
If a schema key equals an Object literal, that nested Object is expected in the data. This allows to validate deeply nested structures.
Multiple criteria
A resolver function may also return a map of rules that apply to the corresponding nested properties. By default, the actual value must satisfy all the rules in order to be valid (see Optional validation). Each resolver corresponding to a validation criteria is called named resolver.
Error messages
Reach Schema does not provide any error messages directly. Instead, it treats an error message as an artifact derived from the validation result. To achieve that it provides all the relevant information in the validation result to construct an error message.
However, there is a common logic that can be integrated into such error messages construction (i.e. resolving due to priority, fallback messages). Declaring such logic each time would be lengthy, time-consuming, and prone to human error.
Recipes
Property existence
To check that a property exists in the actual data provide a resolver function that always returns true
. Ideologically it marks the property as "always valid", but since the default validation behavior asserts all the keys present in the Validation Schema, it also implies that the property must be present.
Optional validation
To apply an optional (weak) validation to a property wrap its resolver in the optional
helper function. This way the property's value will be validated only if present in the actual data. If the property is missing in the actual data it's never validated and considered as valid.
Usage with TypeScript
useSchema
will infer the type of the given data automatically. However, to type guard the data itself it's useful to describe the data separately and provide to schema:
useSchema , ,