Available Constraints

Below are all the currently supported constraints. If you need more you can create your own Custom validators as well.

propertyName = {
        // The field under validation must be yes, on, 1, or true. This is useful for validating "Terms of Service" acceptance.
        accepted : any value
        
        // The field under validation must be a date after the set targetDate
        after : targetDate
        
        // The field under validation must be a date after or equal the set targetDate
        afterOrEqual : targetDate

        // The field must be alpha ONLY
        alpha : any value
        
        // The field under validation is an array and all items must pass this validation as well
        arrayItem : {
            // All the constraints to validate the items with
        }
        
        // The field under validation must be a date before the set targetDate
        before : targetDate
        
        // The field under validation must be a date before or equal the set targetDate
        beforeOrEqual : targetDate
        
        // The field under validation is a struct and all nested validation rules must pass
        constraints: {
           // All the constraints for the nested struct
        }
        
        // The field under validation must be a date that is equal the set targetDate
        dateEquals : targetDate
        
        // discrete math modifiers
        discrete : (gt,gte,lt,lte,eq,neq):value
        
        // the field must or must not be an empty value
        // needed because `required` counts empty strings as valid
        // and `type` ignores empty strings as "not required"
        empty : boolean [false]

        // value in list
        inList : list
        
        // An alias for arrayItem
        items : {
            // All the constraints to validate the items with
        }

        // max value
        max : value

        // Validation method to use in the target object must return boolean accept the incoming value and target object 
        method : methodName

        // min value
        min : value
        
        // An alias for constraints
        nestedConstraints: {
           // All the constraints for the nested struct
        }

        // range is a range of values the property value should exist in
        range : eg: 1..10 or 5..-5

        // regex validation
        regex : valid no case regex

        // required field or not, includes null values
        required : boolean [false]

        // The field under validation must be present and not empty if the `anotherfield` field is equal to the passed `value`.
        requiredIf : {
            anotherfield:value, anotherfield:value
        }

        // The field under validation must be present and not empty unless the `anotherfield` field is equal to the passed 
        requiredUnless : {
            anotherfield:value, anotherfield:value
        }

        // same as but with no case
        sameAsNoCase : propertyName

        // same as another property
        sameAs : propertyName

        // size or length of the value which can be a (struct,string,array,query)
        size  : numeric or range, eg: 10 or 6..8

        // specific type constraint, one in the list.
        type  : (alpha,array,binary,boolean,component,creditcard,date,email,eurodate,float,GUID,integer,ipaddress,json,numeric,query,ssn,string,struct,telephone,url,usdate,UUID,xml,zipcode),

        // UDF to use for validation, must return boolean accept the incoming value and target object, validate(value,target,metadata):boolean
        udf = variables.UDF or this.UDF or a closure.

        // Check if a column is unique in the database
        unique = {
            table : The table name,
            column : The column to check, defaults to the property field in check
        }

        // Custom validator, must implement coldbox.system.validation.validators.IValidator
        validator : path or wirebox id, example: 'mypath.MyValidator' or 'id:MyValidator'
}

accepted

The field must be yes, on, 1, or true. This is useful for validating "Terms of Service" acceptance.

terms = { accepted = true }

after

The field under validation must be a value after a given date. The dates will be passed into the dateCompare() function in order to be converted and tested.

startDate : { required:true, type:"date", after: dateAdd( "d", 1, now() ) }

Instead of passing a date, you may specify another field to compare against the date as well:

endDate : { required:true, type:"date", after: "startDate" }

afterOrEqual

The field under validation must be a value after or equal a given date. The dates will be passed into the dateCompare() function in order to be converted and tested.

startDate : { required:true, type:"date", afterOrEqual: dateAdd( "d", 1, now() ) }

alpha

The field must be alphabetical ONLY

terms = { alpha = true }

arrayItem

This validator is used to validate an array's items. It will iterate through each of the array's items and validate each item against the validationData constraints you pass in.

luckyNumbers = {
    required : true,
    type : "array",
    arrayItem : {
        required : true,
        type : "numeric"
    }
}

You may also specify items as an alias to arrayItem.

luckyNumbers = {
    required : true,
    type : "array",
    items : {
        required : true,
        type : "numeric"
    }
}

Any validation errors found will be named using the parent field name and array index.

var validationResult = validate(
    target = {
        "luckyNumbers": [ 7, 11, "not a number", 21 ]
    },
    constraints = {
        required : true,
        type : "array",
        items : {
            required : true,
            type : "numeric"
        }
    }
);

// validationResult.getAllErrorsAsJson()
{
    "luckyNumbers[3]": ["The 'item' has an invalid type, expected type is numeric"]
}

You can validate nested structs by nesting a constraints validator.

invoiceItems = {
    required : true,
    type : "array",
    arrayItem : {
        type : "struct",
        constraints : {
            logDate : { required : true, type : "date" },
            isBilled : { required: true, type : "boolean" },
            notes : { required: true }
        }
    }
}

There is a shortcut notation available for arrayItem that uses a specialized field name to skip nesting the constraints.

before

The field under validation must be a value before a given date. The dates will be passed into the dateCompare() function in order to be converted and tested.

endDate : { required:true, type:"date", before: "01/01/2022" }

Instead of passing a date, you may specify another field to compare against the date as well:

startDate : { required:true, type:"date", before: "endDate" }

beforeOrEqual

The field under validation must be a value before or equal a given date. The dates will be passed into the dateCompare() function in order to be converted and tested.

endDate : { required:true, type:"date", beforeOrEqual: "01/01/2022" }

constraints

This validator is used to validate a nested struct. The value of this validator are the constraints for the nested struct.

address = {
    "required": true,
    "type": "struct",
    "constraints": {
        "streetOne": { "required": true, "type": "string" },
        "streetTwo": { "required": false, "type": "string" },
        "city": { "required": true, "type": "string" },
        "state": { "required": true, "type": "string", "size": 2 },
        "zip": { "required": true, "type": "numeric", "size": 5 }
    }
}

Any validation errors found will be named using the parent field name and the child field name.

var validationResult = validate(
    target = {
        "address": {
            "streetOne" : "123 Elm Street",
            "streetTwo" : "",
            "city"      : "Anytown",
            "zip"       : "60606"
        }
    },
    constraints = {
        "address": {
            "required": true,
            "type": "struct",
            "constraints": {
                "streetOne": { "required": true, "type": "string" },
                "streetTwo": { "required": false, "type": "string" },
                "city": { "required": true, "type": "string" },
                "state": { "required": true, "type": "string", "size": 2 },
                "zip": { "required": true, "type": "numeric", "size": 5 }
            }
        }
    }
);

// validationResult.getAllErrorsAsJson()
{
    "address.state": ["The 'state' field is required"]
}

constraints can be used as many levels deep as you need to go.

owner = {
    "firstName": { "required": true, "type": "string" },
    "lastName": { "required": true, "type": "string" },
    "address": {
        "required": true,
        "type": "struct",
        "constraints": {
            "streetOne": { "required": true, "type": "string" },
            "streetTwo": { "required": false, "type": "string" },
            "city": { "required": true, "type": "string" },
            "state": { "required": true, "type": "string", "size": 2 },
            "zip": { "required": true, "type": "numeric", "size": 5 }
        }
    }
}

constraints can also be combined with items to validate an array of structs.

invoiceItems = {
    required : true,
    type : "array",
    arrayItem : {
        type : "struct",
        constraints : {
            logDate : { required : true, type : "date" },
            isBilled : { required: true, type : "boolean" },
            notes : { required: true }
        }
    }
}

There is a shortcut notation available for constraints that uses a specialized field name to skip nesting the constraints.

dateEquals

The field under validation must be a value that is the same as the given date. The dates will be passed into the dateCompare() function in order to be converted and tested.

endDate : { required:true, type:"date", dateEquals: "01/01/2022" }

Instead of passing a date, you may specify another field to compare against the date as well:

startDate : { required:true, type:"date", dateEquals: "createdDate" }

discrete

The field must pass certain discrete math operations using the format: operator:value

• gt - Greater than the value

• gte - Greater than or equal to the value

• lt - Less than the value

• lte - Less than or equal to the value

• eq - Equal to the value

• neq - Not equal to the value

myField = { discrete = "gt:4" }
myField = { discrete = "eq:luis" }
myField = { discrete = "lte:1" }

empty

The field is not required but if it exists it cannot be empty.

myField = { empty = false }

This is needed since required validators allow empty strings when false while type validators ignore empty values as valid. This means we can have a situation as follows:

{
    "startDate": {
        "required": false,
        "type": "date"
    }
}

With these validation rules passing in startDate = "" would pass the validation! The empty validator helps us ensure that the value passed in is not empty (and, in this case, a date).

{
    "startDate": {
        "required": false,
        "empty": false,
        "type": "date"
    }
}

The field still isn't required, but if it is passed the value must be a non-empty value and it must be parseable as a date.

inList

The field must be in the included list

myField = { inList = "red,green,blue" }

items

See arrayItem.

max

The field must be less than or equal to the defined value

myField = { max = 25 }

method

The methodName will be called on the target object and it will pass in validationData, targetValue, and metadata. It must return a boolean response: true = pass, false = fail.

Any data you place in the metadata structure will be set in the validation result object for later retrieval.

myField = { method = "methodName" }

function methodName( validationData, targetValue, metadata ){
    metadata[ "customMessage" ] = "I am a custom message set via metadata.";
    return false;
}

min

The field must be greater than or equal to the defined value

myField = { min = 8 }

nestedConstraints

See constraints.

range

The field must be within the range values and the validation data must follow the range pattern: min..max

myField = { range = "1..5" }
myField = { range = "5..-5" }

regex

The field must pass the regular expression match with no case sensitivity

myField = { regex = "^(sick|vacation|disability)$" }

required

The field must have some type of value and not null.

myField = { required=true }
myField = { required=false }

requiredIf

The field under validation must be present and not empty if the anotherfield field is equal to the passed value. The validation data can be a struct or a string representing the field to check.

// Struct based
myField = { 
 // myField is required if field2 = test and field3 = hello
 requiredIf = {
  field2 = "test",
  field3 = "hello"
 }
}

// String Based
myField = {
 // myField is required if field3 exists and has a value.
 requiredIf = "field3"
}

requiredUnless

The field under validation must be present and not empty unless the anotherfield field is equal to the passed value. The validation data can be a struct or a string representing the field to check.

myField = { 
 // myField is required unless field2 = test and field3 = hello
 requiredUnless = {
  field2 = "test",
  field3 = "hello"
 }
}

// String Based
myField = {
 // myField is required unless field3 exists and has a value.
 requiredUnless = "field3"
}

sameAsNoCase

The field must be the same as another field with no case sensitivity

myField = { sameAs = "otherField" }

sameAs

The field must be the same as another field with case sensitivity

myField = { sameAs = "otherField" }

size

The field value size must be within the range values and the validation data must follow the range pattern: min..max. Value can be a (struct,string,array,query)

myField = { size : 10 }
myFiedl = { size : "8..20" }

type

One of the most versatile validators. It can test if the value is of the following specific types:

• alpha

• array

• binary

• boolean

• component

• creditcard

• date

• email

• eurodate

• float

• GUID

• integer

• ipaddress

• json

• numeric

• query

• ssn

• string

• struct

• telephone

• url

• usdate

• UUID

• xml

• zipcode

myField = { type : "float" }
myField = { type : "json" }
myField = { type : "xml" }

udf

The field value, the target object, and an empty metadata structure will be passed to the declared closure/lambda to use for validation. The UDF must return boolean, validate( value, target, metadata ):boolean. NOTE: The target object passed in is actually an instance of "GenericObject", not a struct. To access the underlying struct, use the getMemento() function and perfom any comparisons on that. See the example below.

Any data you place in the metadata structure will be set in the validation result object for later retrieval.

myField = { udf = function( value, target, metadata ) { return true; } }
myField = { udf = (value ,target, metadata ) => true }
myField = { udf = function( value, target, metadata ) { 
    metadata[ "customMessage" ] = "This is a custom error message from within the udf";
    return false; 
}
myField = { udf = function( value, target, metadata ) {
    var myData = target.getMemento();
    return myData["blah"] == something && value > someNumber;
}

unique

The field must be a unique value in a specific database table. The validation data is a struct with the following keys:

• table : The name of the table to check

• column : The column to check, defaults to the property field in check

myField = { unique = { table : "users", column : "username" } }

validator

The field value will be passed to the validator CFC to be used for validation. Please see Custom Validators

myField = { validator = "UniqueValidator@cborm" }