cbValidation
Search…
Available Constraints
Below are all the currently supported constraints. If you need more you can create your own Custom validators as well.
1
propertyName = {
2
// The field under validation must be yes, on, 1, or true. This is useful for validating "Terms of Service" acceptance.
3
accepted : any value
4
5
// The field under validation must be a date after the set targetDate
6
after : targetDate
7
8
// The field under validation must be a date after or equal the set targetDate
9
afterOrEqual : targetDate
10
11
// The field must be alpha ONLY
12
alpha : any value
13
14
// The field under validation is an array and all items must pass this validation as well
15
arrayItem : {
16
// All the constraints to validate the items with
17
}
18
19
// The field under validation must be a date before the set targetDate
20
before : targetDate
21
22
// The field under validation must be a date before or equal the set targetDate
23
beforeOrEqual : targetDate
24
25
// The field under validation is a struct and all nested validation rules must pass
26
constraints: {
27
// All the constraints for the nested struct
28
}
29
30
// The field under validation must be a date that is equal the set targetDate
31
dateEquals : targetDate
32
33
// discrete math modifiers
34
discrete : (gt,gte,lt,lte,eq,neq):value
35
36
// the field must or must not be an empty value
37
// needed because `required` counts empty strings as valid
38
// and `type` ignores empty strings as "not required"
39
empty : boolean [false]
40
41
// value in list
42
inList : list
43
44
// An alias for arrayItem
45
items : {
46
// All the constraints to validate the items with
47
}
48
49
// max value
50
max : value
51
52
// Validation method to use in the target object must return boolean accept the incoming value and target object
53
method : methodName
54
55
// min value
56
min : value
57
58
// An alias for constraints
59
nestedConstraints: {
60
// All the constraints for the nested struct
61
}
62
63
// range is a range of values the property value should exist in
64
range : eg: 1..10 or 5..-5
65
66
// regex validation
67
regex : valid no case regex
68
69
// required field or not, includes null values
70
required : boolean [false]
71
72
// The field under validation must be present and not empty if the `anotherfield` field is equal to the passed `value`.
73
requiredIf : {
74
anotherfield:value, anotherfield:value
75
}
76
77
// The field under validation must be present and not empty unless the `anotherfield` field is equal to the passed
78
requiredUnless : {
79
anotherfield:value, anotherfield:value
80
}
81
82
// same as but with no case
83
sameAsNoCase : propertyName
84
85
// same as another property
86
sameAs : propertyName
87
88
// size or length of the value which can be a (struct,string,array,query)
89
size : numeric or range, eg: 10 or 6..8
90
91
// specific type constraint, one in the list.
92
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),
93
94
// UDF to use for validation, must return boolean accept the incoming value and target object, validate(value,target,metadata):boolean
95
udf = variables.UDF or this.UDF or a closure.
96
97
// Check if a column is unique in the database
98
unique = {
99
table : The table name,
100
column : The column to check, defaults to the property field in check
101
}
102
103
// Custom validator, must implement coldbox.system.validation.validators.IValidator
104
validator : path or wirebox id, example: 'mypath.MyValidator' or 'id:MyValidator'
105
}
Copied!

accepted

The field must be yes, on, 1, or true. This is useful for validating "Terms of Service" acceptance.
1
terms = { accepted = true }
Copied!

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.
1
startDate : { required:true, type:"date", after: dateAdd( "d", 1, now() ) }
Copied!
Instead of passing a date, you may specify another field to compare against the date as well:
1
endDate : { required:true, type:"date", after: "startDate" }
Copied!

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.
1
startDate : { required:true, type:"date", afterOrEqual: dateAdd( "d", 1, now() ) }
Copied!

alpha

The field must be alphabetical ONLY
1
terms = { alpha = true }
Copied!

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.
1
luckyNumbers = {
2
required : true,
3
type : "array",
4
arrayItem : {
5
required : true,
6
type : "numeric"
7
}
8
}
Copied!
You may also specify items as an alias to arrayItem.
1
luckyNumbers = {
2
required : true,
3
type : "array",
4
items : {
5
required : true,
6
type : "numeric"
7
}
8
}
Copied!
Any validation errors found will be named using the parent field name and array index.
1
var validationResult = validate(
2
target = {
3
"luckyNumbers": [ 7, 11, "not a number", 21 ]
4
},
5
constraints = {
6
required : true,
7
type : "array",
8
items : {
9
required : true,
10
type : "numeric"
11
}
12
}
13
);
Copied!
1
// validationResult.getAllErrorsAsJson()
2
{
3
"luckyNumbers[3]": ["The 'item' has an invalid type, expected type is numeric"]
4
}
Copied!
You can validate nested structs by nesting a constraints validator.
1
invoiceItems = {
2
required : true,
3
type : "array",
4
arrayItem : {
5
type : "struct",
6
constraints : {
7
logDate : { required : true, type : "date" },
8
isBilled : { required: true, type : "boolean" },
9
notes : { required: true }
10
}
11
}
12
}
Copied!
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.
1
endDate : { required:true, type:"date", before: "01/01/2022" }
Copied!
Instead of passing a date, you may specify another field to compare against the date as well:
1
startDate : { required:true, type:"date", before: "endDate" }
Copied!

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.
1
endDate : { required:true, type:"date", beforeOrEqual: "01/01/2022" }
Copied!

constraints

This validator is used to validate a nested struct. The value of this validator are the constraints for the nested struct.
1
address = {
2
"required": true,
3
"type": "struct",
4
"constraints": {
5
"streetOne": { "required": true, "type": "string" },
6
"streetTwo": { "required": false, "type": "string" },
7
"city": { "required": true, "type": "string" },
8
"state": { "required": true, "type": "string", "size": 2 },
9
"zip": { "required": true, "type": "numeric", "size": 5 }
10
}
11
}
Copied!
Any validation errors found will be named using the parent field name and the child field name.
1
var validationResult = validate(
2
target = {
3
"address": {
4
"streetOne" : "123 Elm Street",
5
"streetTwo" : "",
6
"city" : "Anytown",
7
"zip" : "60606"
8
}
9
},
10
constraints = {
11
"address": {
12
"required": true,
13
"type": "struct",
14
"constraints": {
15
"streetOne": { "required": true, "type": "string" },
16
"streetTwo": { "required": false, "type": "string" },
17
"city": { "required": true, "type": "string" },
18
"state": { "required": true, "type": "string", "size": 2 },
19
"zip": { "required": true, "type": "numeric", "size": 5 }
20
}
21
}
22
}
23
);
Copied!
1
// validationResult.getAllErrorsAsJson()
2
{
3
"address.state": ["The 'state' field is required"]
4
}
Copied!
constraints can be used as many levels deep as you need to go.
1
owner = {
2
"firstName": { "required": true, "type": "string" },
3
"lastName": { "required": true, "type": "string" },
4
"address": {
5
"required": true,
6
"type": "struct",
7
"constraints": {
8
"streetOne": { "required": true, "type": "string" },
9
"streetTwo": { "required": false, "type": "string" },
10
"city": { "required": true, "type": "string" },
11
"state": { "required": true, "type": "string", "size": 2 },
12
"zip": { "required": true, "type": "numeric", "size": 5 }
13
}
14
}
15
}
Copied!
constraints can also be combined with items to validate an array of structs.
1
invoiceItems = {
2
required : true,
3
type : "array",
4
arrayItem : {
5
type : "struct",
6
constraints : {
7
logDate : { required : true, type : "date" },
8
isBilled : { required: true, type : "boolean" },
9
notes : { required: true }
10
}
11
}
12
}
Copied!
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.
1
endDate : { required:true, type:"date", dateEquals: "01/01/2022" }
Copied!
Instead of passing a date, you may specify another field to compare against the date as well:
1
startDate : { required:true, type:"date", dateEquals: "createdDate" }
Copied!

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
1
myField = { discrete = "gt:4" }
2
myField = { discrete = "eq:luis" }
3
myField = { discrete = "lte:1" }
Copied!

empty

The field is not required but if it exists it cannot be empty.
1
myField = { empty = false }
Copied!
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:
1
{
2
"startDate": {
3
"required": false,
4
"type": "date"
5
}
6
}
Copied!
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).
1
{
2
"startDate": {
3
"required": false,
4
"empty": false,
5
"type": "date"
6
}
7
}
Copied!
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
1
myField = { inList = "red,green,blue" }
Copied!

items

max

The field must be less than or equal to the defined value
1
myField = { max = 25 }
Copied!

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.
1
myField = { method = "methodName" }
2
3
function methodName( validationData, targetValue, metadata ){
4
metadata[ "customMessage" ] = "I am a custom message set via metadata.";
5
return false;
6
}
Copied!

min

The field must be greater than or equal to the defined value
1
myField = { min = 8 }
Copied!

nestedConstraints

range

The field must be within the range values and the validation data must follow the range pattern: min..max
1
myField = { range = "1..5" }
2
myField = { range = "5..-5" }
Copied!

regex

The field must pass the regular expression match with no case sensitivity
1
myField = { regex = "^(sick|vacation|disability)quot; }
Copied!

required

The field must have some type of value and not null.
1
myField = { required=true }
2
myField = { required=false }
Copied!

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.
1
// Struct based
2
myField = {
3
// myField is required if field2 = test and field3 = hello
4
requiredIf = {
5
field2 = "test",
6
field3 = "hello"
7
}
8
}
9
10
// String Based
11
myField = {
12
// myField is required if field3 exists and has a value.
13
requiredIf = "field3"
14
}
Copied!

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.
1
myField = {
2
// myField is required unless field2 = test and field3 = hello
3
requiredUnless = {
4
field2 = "test",
5
field3 = "hello"
6
}
7
}
8
9
// String Based
10
myField = {
11
// myField is required unless field3 exists and has a value.
12
requiredUnless = "field3"
13
}
Copied!

sameAsNoCase

The field must be the same as another field with no case sensitivity
1
myField = { sameAs = "otherField" }
Copied!

sameAs

The field must be the same as another field with case sensitivity
1
myField = { sameAs = "otherField" }
Copied!

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)
1
myField = { size : 10 }
2
myFiedl = { size : "8..20" }
Copied!

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
1
myField = { type : "float" }
2
myField = { type : "json" }
3
myField = { type : "xml" }
Copied!

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
Any data you place in the metadata structure will be set in the validation result object for later retrieval.
1
myField = { udf = function( value, target, metadata ) { return true; } }
2
myField = { udf = (value ,target, metadata ) => true }
3
myField = { udf = function( value, target, metadata ) {
4
metadata[ "customMessage" ] = "This is a custom error message from within the udf";
5
return false;
6
}
Copied!

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
1
myField = { unique = { table : "users", column : "username" } }
Copied!

validator

The field value will be passed to the validator CFC to be used for validation. Please see Custom Validators
1
myField = { validator = "[email protected]" }
Copied!