HRB Validator

Hierarchical Rule-Based Validator is a simple yet powerful data validation engine. Unlike schema-based validation libraries, this framework allows you to compose validation rules in higher order rules to validate complex data structures.

Major Features

• Both browsers and NodeJS supported
• Validators defined either in code or using JSON/YAML syntax in a declarative way
• Rich set of leaf validators (most from validator and the others implemented internally) to check field values and types
• Branch validators to compose validators in a hierarchical way through:
  • Iterative validation over array elements, object properties and string characters
  • Recursive validation
  • Logical operators
  • Conditional validation
• Widespread support for references in validator arguments and variables:
  • Value references allow you to use variables (in fact constants at the current state of the art) and paths (for instance, to ensure that maxAge property has a value greater than the value of minAge property)
  • Validator references allow you to reuse user-defined validators, making amongst other things recursion possible

Upcoming Features

• User-defined validators with arguments: user-defined validators will have the same expressive power of built-in validators.
• Read/write variables, not just constants: with adequate support of special setter validators this will make possible even more in-depth validations. For instance, consider the following two scenarios:
  • An object representing a person has an array of relatives and each relative has a flag indicating whether he's a parent or not. You want to check if at most two of the relatives are parents.
  • An object representing an email has an array of attachments and each attachment has a base64 encoded content string. You want to check if the overall size of the attachments is less than a certain threshold.
• Validation error reporting improvements: currently, if a validator does not work as expected it's not that easy to identify the actual problem.

Table of Contents

• HRB Validator
  • Major Features
  • Upcoming Features
  • Table of Contents
  • Usage
    • Hard-coded validators
    • Loading validators from file
    • YAML vs JSON
    • How to use references
      • Value reference
      • Validator reference
    • Shortcut for optional paths
    • Union types
  • Leaf Validators
  • Branch Validators
• License

Usage

Suppose you have the simple object below

let toBeValidated = {
  a: {
    b: 1,
    c: true,
    d: ["foo", "bar"]
  }
};

and you want to validate it like that:

1. All next rules must be satisfied (logical and)
2. The value at path a is an object
3. Paths a.b and a.c are mutually exclusive (logical xor)
4. The value at path a.b is a number (whenever set)
5. The value at path a.c is a boolean (whenever set)
6. The value at path a.d is an array of strings

By the way, such a validator is expected to fail against the object above, because both paths a.b and a.c are set, thus breaking rule 3 which in turn breaks rule 1.

Notice that you can easily represent previous rules with the following tree:

To create this validator you can choose one of the two approaches described in the following:

• Hard-coded Validators
• Loading Validators from File

Hard-coded validators

This sample code programmatically creates the validator for the previous rules.

const V = require("@davebaol/hrb-validator");

// Hard-coded validator
let validator = V.and(              // Rule 1
  V.isType("a", "object"),          //   Rule 2
  V.xor(                            //   Rule 3
    V.isSet("a.b"),                 //     Rule 3.1
    V.isSet("a.c"),                 //     Rule 3.2
  ),
  V.optIsType("a.b", "number"),     //   Rule 4
  V.optIsType("a.c", "boolean"),    //   Rule 5
  V.isArrayOf("a.d", "string")      //   Rule 6
);

// Validate
let vError = validator(toBeValidated);

Notice that this is a tree-like structure whereand and xor are branch validators made of children that, in turn, are validators. The others are leaf validators with no children.

Loading validators from file

You use a simple tree-like DSL to define your validator. For instance, our sample validator becomes the YAML file below:

and:
  - isType: [a, object]
  - xor:
    - isSet: [a.b]
    - isSet: [a.c]
  - optIsType: [a.b, number]
  - optIsType: [a.c, boolean]
  - isArrayOf: [a.d, string]

Here each validator is an object with exactly one property where the key is its name and the value is the array of its arguments. They look like, and in fact they are, regular function calls.

For convenience, leaf validators are represented as an in-line object, while branch validators span multiple lines in a tree-like structure.

To load the validator you can use the sample code below:

const fs = require("fs");
const yaml = require("js-yaml");
const ensureValidator = require("@davebaol/hrb-validator/lib/ensure-validator");

// Load validator from file
let vObj = yaml.safeLoad(fs.readFileSync("/path/to/validator/file", 'utf8'));
let validator = ensureValidator(vObj);

// Validate
let vError = validator(toBeValidated);

YAML vs JSON

The choice between YAML and JSON formats depends on your scenario.

When human-readability is important for you, it's recommended to use YAML instead of JSON. For instance, previous YAML file converted to JSON, while keeping similar formatting, becomes like this:

{"and": [
	{"isType": ["a", "object"]},
	{"xor": [
		{"isSet": ["a.b"]},
		{"isSet": ["a.c"]}
	]},
	{"optIsType": ["a.b", "number"]},
	{"optIsType": ["a.c", "boolean"]},
	{"isArrayOf": ["a.d", "string"]}
]}

So many braces, double quotes and commas! 😲 Imagine what would happen for a larger real-world validator. 😵

On the other hand, for machine to machine communication JSON is likely a more appropriate format. For instance, think of a REST API centralizing configurations and their validators.

How to use references

A reference is an object with exactly one key amongst $path and $var whose value is respectively a path to a property of the object to validate and a path to a property of a variable in nested scopes. Notice that reference keys start with $ to avoid confusion with built-in validators.

There are 2 types of references:

Value reference

Value references can be used in any place where a value is expected, for instance a validator argument or a variable definition. A value reference is either a path reference or a variable reference.

• A path reference has the form {"$path": "path.to.property.of.object.to.validate"} and returns the value at the specified path for the object under validation
• A variable reference has the form {"$var": "path.to.property.of.variable.in.nested.scopes"} and returns the value at the specified path for the first variable with the specified name found in nested scopes from inner to outer. For instance, {"$var": "record.fields.0"} returns the value of the first field of the variable with name record from nested scopes.

A value reference can be embedded in obect properties and array items. When it's not embedded is called root reference.

For instance, suppose you have the object below representing a table with an header and an array of rows, where each row is an array of fields.

{
  "header": ["id", "description", "available"],
  "rows": [
    [123, "item 1", true],
    [456, "item 1", false],
    [789, "item 3", true]
  ]
}

You want to make sure that each row is an array with a number of fields not greater than the number of fields in the header.

def:
  - header: {$path: header} # root reference to the header in the object to validate
    firstFieldName: {$var: header.0}  # root reference (not used, just for the sake of example)

  - every:
    - 'rows'
    - and:
      - isType: [value, array]
      - isLength: [value, {max: {$var: header.length}}]  # embedded reference for the property max

Validator reference

Validator references can be used only in branch validators for any argument that is expected to be a validator i.e. a child. A validator reference has the form {"$var": "$validator_name"} (It's just a variable whose name starts with $) and returns the first validator with the specified name found in nested scopes from inner to outer.

We can rewrite the example above by using a user-defined validator to check each row:

def:
  - header: {$path: header} # root reference to the header in the object to validate
    firstFieldName: {$var: header.0}  # root reference (not used, just for the sake of example)
    $checkRow:       # user-defined validator
      and:
        - isType: ['', array]
        - isLength: ['', {max: {$var: header.length}}]  # embedded reference for the property max
  - every:
    - 'rows'
    - call:
      - value
      - {$var: $checkRow}  # validator reference

Shortcut for optional paths

Each validator xyz(path, ...args), no matter whether it is leaf or branch, that takes a path as the first argument has a counterpart validator optXyz(path, ...args):

• optXyz(path, ...args): Check if the value at path is not set or passes validator xyz.

This shortcut is equivalent to the composite validator

  V.or(
    V.not(V.isSet(path)),
    V.xyz(path, ...args)
  )

Notice that for a couple of validators the shortcut is somewhat redundant. For instance,

• V.optIsSet("a") is always valid, since that path a cannot be set and null at the same time
• V.optIsType("a", "string") is equivalent to V.isType("a", ["null", "string"])

Union types

Union types are types whose set of values is the union of the value spaces of its member types. For instance:

• the union type string|integer|boolean is the set of all strings, integer numbers and boolean values.
• the union type null|array represents an optional array (i.e. array or null)

The second example shows that optional types are union types. This can be done for any type T. You can syntactically represent this as T? or null|T

Of course for any type T1 and T2 the union types T1|T2 is equivalent to T2|T1.

In practice, union types can be specified in two ways:

• as a pipe separated string, e.g. "null|array"
• as an array of strings, e.g. ["null", "array"]

At the moment, you can use union types in validators isType and isArrayOf. For instance, in YAML

and:
  - isType: [a.b.c, [integer, string]]
  - isArrayOf: [s.p.q, integer|string]

In the next major release, user-defined validators will support typed arguments. You'll be able to use union types in the declaration of your own validators by specifying name and type of each argument. Also, validator reference will be suppressed and user-defined validators will be invoked just like regular validators.

Leaf Validators

Here is a list of the leaf validators currently available.

📌 All leaf validators, without exception, have their shortcut opt (not reported in the table below).

📌 All arguments marked with ♦️ allow you to use a value reference.

📌 All leaf validators marked with ✋ are not implemented yet, but probably will in the near future.

Branch Validators

Here is a list of the branch validators currently available.

📌 Only branch validators taking a path as first argument, i.e. the ones not having a ✖️ in the second column, have a shortcut opt (not reported in the table below).

📌 All arguments marked with ♣️ allow you to use a validator reference.

📌 All arguments marked with ♦️ allow you to use a value reference.

Branch Validator	Expected Type at path	Description
alter(res1♦️, res2♦️, child♣️)	✖️	If child child is valid res1 is returned; res2 otherwise. Note: Any null result is mapped to undefined, i.e. success. This allows you to force success also from JSON where undefined is not supported.
and(...children♣️)	✖️	Check if all its children are valid. Validation fails at the first non valid child and succeeds if all children are valid.
call(path♦️, child️️️♣️)	any	Validate child against the value at the specified path.
def(scope️️, child️️️♣️)	any	Define a scope containing variables and validators (the latter ones having a name that starts with $) that the child and all his descendants can reach via a $var reference. See How to use references
every(path♦️, child♣️)	object array string	Validate child for the items of the value at path, which must be an array, an object or a string. Validation fails at the first non valid item and succeeds if all items are valid. The object against which child is validated depends on the type of the value at path: • array -> {index: <iteration_index>, value: <item_at_index>, original: <original_object>} • object -> {index: <iteration_index>, key: <property_key>, value: <property_value>, original: <original_object>} • string -> {index: <iteration_index>, value: <char_at_index>, original: <original_object>}
if(cond♣️, then♣️ [, else♣️])	✖️	If cond child is valid validates then child; else child otherwise (if present). It always succeeds when cond child is not valid and else child is not specified. This validator is useful, for instance, when the value of a property depends on the value of another property.
not(child♣️)	✖️	Check if the negation of its child is valid.
onError(result♦️, child♣️)	✖️	Force the specified result if its child is non valid. Note: A null result is mapped to undefined, i.e. success. This allows you to force success also from JSON where undefined is not supported.
or(...children♣️)	✖️	Check if at least one child is valid. Validation succeeds at the first valid child and fails if all children are non valid.
some(path♦️, child♣️)	object array string	Validate child for the items of the value at path, which must be either an array or an object. Validation succeeds at the first valid item and fails if all items are non valid. The object aginst with child is validated depends on the type of the value at path: • array -> {index: <iteration_index>, value: <item_at_index>, original: <original_object>} • object -> {index: <iteration_index>, key: <property_key>, value: <property_value>, original: <original_object>} • string -> {index: <iteration_index>, value: <char_at_index>, original: <original_object>}
while(path♦️, cond♣️, do♣️)	object array string	Validate cond and do children for the items of the value at path, which must be an array, an object or a string. Validation fails as soon as the condition fails and succeeds if the condition succeeds for all items. At each iteration do child is validated only after cond child succeeds. After each do validation, either success or failure counter is increased accordingly. The object against which cond and do children are validated depends on the type of the value at path: • array -> {index: <iteration_index>, value: <item_at_index>, succeeded: <how_many_times_do_succeeded>, failed: <how_many_times_do_failed>, original: <original_object>} • object -> {index: <iteration_index>, key: <property_key>, value: <property_value>, succeeded: <how_many_times_do_succeeded>, failed: <how_many_times_do_failed>, original: <original_object>} • string -> {index: <iteration_index>, value: <char_at_index>, succeeded: <how_many_times_do_succeeded>, failed: <how_many_times_do_failed>, original: <original_object>}
xor(...children♣️)	✖️	Check if exactly one child is valid. Validation fails at the second valid child or when all children are processed an no child was valid. Validation succeeds when all children are processed and exactly one child was valid.

License

MIT © Davide Sessi