Validators

Options#

All validators accept as their final argument the same set of options (optional):

{
    name?: string; // the "type" of error in a ValidationError
    params? object; // any parameters that can be interpolated into the message
    message?: string | (params) => string; // the error message in the ValidationError
}

name#

By default, name is the name of the validator you are calling - i.e. the name for the oneOf validator is oneOf.

params#

params differ from validator to validator and are provided to the string/message function for convenience. label is the only common parameter always available for interpolation. For more information about error messages see error messages.

message#

message is a string or a function used to define the error message for this specific validator. If a string the appropriate parameters will be interpolated using ${interpolationparam}.

ast
functional

const schema = {
    schema:'string',
    label:'first name',
    tests: [['includes','fred',{ message:'The value of ${label} should include ${value}' }]
}

getErrorsSync(createSchema(schema),'jim'); // The value of first name should include fred

Validators#

Validators aren't always applicable to all schemas (min is not relevant for a boolean schema, for instance) This is accomplished via a pre-validation hook which verifies that the current ValidatorDefinition is applicable to the current schema.

Note: undefined is considered a valid value for all validators except required.

required#

required(options: ValidatorOptions)

Applicable to schemas: ALL

Most of the time undefined is not validated. This is accomplished via the pre-validation check function that determines if a validator is applicable given a schema type/value.

required does validate the value of undefined and it returns false if the value being validated is undefined or null.

In the case of an array, it also requires at least 1 element and in the case of a string it requires the string be non-empty (not "").

ast
functional

matches({schema:'string', tests: ['required']}, null); // false
matches({schema:'string', tests: ['required']}, undefined); // false
matches({schema:'string', tests: ['required']}, ''); // false
matches({schema:'string', tests: ['required']}, 'a string!'); // true

matches({schema:'array', tests: ['required']}, []); // false
matches({schema:'array', tests: ['required']}, ['not empty']); // true

is#

is(value: any | Ref, options: ValidatorOptions)

Applicable to schemas: ALL

Value being validated must equal (===) the value/ref.

Note: This validator is equivalent to oneOf([value: any | Ref]), except the ValidationError type is is.

ast
functional

const schema = {
    schema: 'object',
    shape: {
        fieldB: {
            tests: [['is', { ref: 'fieldA' }]]
        }
    }
};

matches(schema, { fieldA: 'jim', fieldB: 'jim'}); // true
matches(schema, { fieldA: 'fred', fieldB: 'jim'}); // false
matches(schema, { fieldB: 'jim'}); // false

not#

not(value: any | Ref, options: ValidatorOptions)

Applicable to schemas: ALL

negate-d form of is

ast
functional

const schema = {
    schema:'object',
    shape: {
        fieldB: {
            tests: [['not', { ref:'fieldA' }]]
        }
    }
};

matches(schema, { fieldA: 'jim', fieldB: 'jim' }); // false
matches(schema, { fieldA: 'fred', fieldB: 'jim' }); // true
matches(schema, { fieldB: 'jim' }); // true

oneOf#

oneOf(value: Ref | Array<any | Ref>, options: ValidatorOptions)

Applicable to schemas: ALL

Value being validated must be one of the values given to oneOf OR if value is a ref then the value being validated must be one of the values in the reference.

Note: Just a reminder that undefined is considered a valid value. If you need to test for undefined use required.

ast
functional

const schema = {
    schema:'object',
    shape: {
        fieldB: {
            tests: [['oneOf', ['a', 9, { ref: 'fieldA' }]]]
        },
        fieldC: {
            tests: [['oneOf', { ref: 'fieldD' }]]
        }
    }
};

matches(schema, { fieldA: 'jim', fieldB: 'jim'}); // true
matches(schema, { fieldA: 'fred', fieldB: 'a'}); // true
matches(schema, { fieldB: 'jim'}); // false
matches(schema, { fieldC: 'jim', fieldD: ['joe','fred' ]}); // false
matches(schema, { fieldC: 'joe', fieldD: ['joe','fred' ]}); // true

notOneOf#

notOneOf(value: Array<any | Ref>, options: ValidatorOptions)

Applicable to schemas: ALL

negate-d form of oneOf

ast
functional

const schema = {
    schema:'object',
    shape: {
        fieldB: {
            tests: [['notOneOf', ['a', 9, ref:{ 'fieldA' }]]]
        }
    }
};

matches(schema, { fieldA: 'jim', fieldB: 'jim'}); // false
matches(schema, { fieldA: 'fred', fieldB: 'a'}); // false
matches(schema, { fieldB: 'jim'}); // true

same#

same(value: string, options: ValidatorOptions)

Applicable to schemas: ALL

Validation-sugar for is(ref(value)).

ast
functional

const schema = {
    schema: 'string',
    tests: [['same', '$ctxValue']]
}

const context = { ctxValue: 'someVal' };

matches(schema, 'someVal', { context }); // true
matches(schema, 'not some val', { context }); // false
matches(schema, 'someVal'); // false

different#

different(value: string, options: ValidatorOptions)

Applicable to schemas: ALL

negate-d form of same

ast
functional

const schema = {
    schema: 'string',
    tests: [['different', '$ctxValue']]
}

const context = { ctxValue: 'someVal' };

matches(schema, 'someVal', { context }); // false
matches(schema, 'not some val', { context }); // true
matches(schema, 'someVal'); // true

matches#

matches(value: string | RegExp | Array<string | RegExp>, options = { validateEmpty: boolean, ...ValidatorOptions })

Applicable to schemas: STRING

Validates that the value being validated matches the provided string/regexp. In the case of an array, the value being validated must match one of the provided string/regexp.

Empty strings always return true unless validateEmpty: true is passed as an option.

ast
functional

matches({schema:'string', tests: [['matches', 'rick']]}, ''); // true
matches({schema:'string', tests: [['matches', 'rick', { validateEmpty: true }]}, ''); // false
matches({schema:'string', tests: [['matches', 'rick']]}, 'frederick'); // true
matches({schema:'string', tests: [['matches', ['rick', 'joe']]] }, 'fredeoe'); // false
matches({schema:'string', tests: [['matches', ['rick', 'joe']]] }, 'fred and joe'); // true

email#

email(options = { validateEmpty: boolean, ...ValidatorOptions })

Applicable to schemas: STRINGS

Validates that the value is a valid e-mail address

ast
functional

matches({schema:'string', tests: ['email']}, ''); // true
matches({schema:'string', tests: ['email', { validateEmpty:true }]}, ''); // false
matches({schema:'string', tests: ['email']}, 'me@you.com'); // true

min#

min(value: number | Ref, options = { inclusive: boolean, ...ValidatorOptions})

Applicable to schemas: DATE, STRING, NUMBER, ARRAY

Validates a date, string, number, or array is no less than the given number or ref. inclusive is true by default, if passed as false, then the value must be more than min

ast
functional

matches({schema: 'string', tests: [['min', 10]]}, 'short'); // false
matches({schema: 'string', tests: [['min', 5]]}, 'short'); // true
matches({schema: 'string', tests: [['min', 5, { inclusive: false }]]}, 'short'); // false

max#

max(value: number | Ref, options = { inclusive: boolean = true, ...ValidatorOptions})

Applicable to schemas: DATE, STRING, NUMBER, ARRAY

Validates a date, string, number, or array is no more than the given number or ref. inclusive is true by default, if passed as false, then the value must be less than max.

ast
functional

matches({schema: 'string', tests: [['max', 5]]}, 'not short'); // false
matches({schema: 'string', tests: [['max', 5]]}, 'short'); // true
matches({schema: 'string', tests: [['max', 5, { inclusive: false }]]}, 'short'); // false

includes#

includes(value: any | Ref, options: ValidatorOptions)

Applicable to schemas: STRING, ARRAY

Validates a string or array value includes the value (or ref):

ast
functional

const schema = {
    schema: 'string',
    tests: [['includes', 'rick']]
};

matches(schema, 'frederick'); // true
matches(schema, 'frederoe'); // false

const arr = {
    schema: 'array',
    tests: [['includes', 'rick']]
};

matches(arr, ['joe', 'jim', 'frederick']); // false
matches(arr, ['joe', 'jim', 'rick']); // false

oneOfType#

oneOfType(schemas: Schema[], options: ValidatorOptions)

Applicable to schemas: MIXED

This is a special validator (similar to joi's alternatives) that validates a value to be one of a schema type.

ast
functional

const schema = {
    schema: 'mixed',
    tests: ['oneOfType',[
        {
            schema: 'number',
            tests: ['required',['min',5]]
        },
        {
            schema: 'string',
            tests: ['required','email']
        }        
    ]]
};

Combination#

There are certain utility validators that can be used to combine/alter validators in certain ways.

negate#

Inverts the logic for any validator. This validator is used internally for validator pairs like same/different, is/not and oneOf/notOneOf.

ast
functional

const schema = {
    schema:'string',
    // field must NOT be oneOf a, b, or c
    tests: [['negate',['oneOf',['a','b','c']]]
}

matches(schema,'f'); // true
matches(schema,'a'); // false

combine#

Combines multiple validators into a new validator. Used internally to create the between validator.

ast
functional

const schema = {
    schema:'string',
    tests: [['combine',[['min',5],['max',15]]]
}

matches(schema,'at least 5'); // true
matches(schema,'no'); // false
matches(schema,'this is way longer than 15'); // false

serial#

Essentially a "real" abortEarly:true for async validators.

ast
functional

const firstAsync = async val => {
    // do something async
    // const result = await someAsyncFunc(val)
    return val === 'bad';
}

const secondAsync = async val => {
    // do something async
    // const result = await someAsyncFunc(val)
    return val === 'good';
}


const schema = createSchema(
    {
        schema:'string',
        tests: [
            [
                'serial',
                [
                    ['firstAsync',{message:'Failed Async 1'}],
                    ['secondAsync',{message:'Failed Async 2'}]
                ]
            ]
        ]
    },
    // supply custom validators when compiling AST
    {
        validators: { firstAsync,secondAsync }
    }
);

validate(createSchema(schema),'good'); // Promise<ValidationError> - Failed Async 1
validate(createSchema(schema),'bad'); // Promise<ValidationError> - Failed Async 2