Validation rules

The standard rules that every implementation supports. Open a rule to see how it works and to try it live, or filter the list by an error code to find the rule that returns it.

35 rules

Common rulesCheck that a value is present, or that it is an object.

requiredChecks that the value is present: not missing, not null and not an empty string. Note that 0 and false are valid values.'required'REQUIREDnot_emptyChecks that the value is not an empty string, if the field is passed at all. Unlike required, a missing field is valid.'not_empty'CANNOT_BE_EMPTYnot_empty_listChecks that the value is a list with at least one element.'not_empty_list'CANNOT_BE_EMPTYany_objectChecks that the value is a plain object (a hash, a dictionary). The content of the object is not validated, use nested_object for that.'any_object'FORMAT_ERROR

String rulesCompare and measure strings. Numbers are validated as strings.

stringChecks that the value is a primitive type and converts it to a string, for example 25 becomes "25". Prefer stricter rules where possible.'string'FORMAT_ERROReqChecks that the value is equal to the given one. Values are compared as strings, and the output is the value from the rule.{ eq: 'Anton' }NOT_ALLOWED_VALUEone_ofChecks that the value is one of the allowed values. Values are compared as strings, and the output is the value from the rule.{ one_of: ['a', 'b'] }NOT_ALLOWED_VALUEmax_lengthChecks that the string is not longer than the given number of characters.{ max_length: 10 }TOO_LONGmin_lengthChecks that the string is at least the given number of characters long.{ min_length: 2 }TOO_SHORTlength_betweenChecks that the length of the string is between the two values, inclusive.{ length_between: [2, 10] }TOO_LONGTOO_SHORTlength_equalChecks that the string is exactly the given number of characters long.{ length_equal: 2 }TOO_LONGTOO_SHORTlikeChecks that the value matches a regular expression.{ like: '^\\d+$' }WRONG_FORMAT

Numeric rulesCheck numbers and strings that look like numbers, and return them as numbers.

integerChecks that the value is an integer. Strings that look like integers are accepted and returned as numbers.'integer'NOT_INTEGERpositive_integerChecks that the value is an integer greater than zero.'positive_integer'NOT_POSITIVE_INTEGERdecimalChecks that the value is a number, an integer or a decimal. Strings that look like numbers are accepted and returned as numbers.'decimal'NOT_DECIMALpositive_decimalChecks that the value is a number greater than zero.'positive_decimal'NOT_POSITIVE_DECIMALmax_numberChecks that the number is not greater than the given value.{ max_number: 95 }TOO_HIGHNOT_NUMBERmin_numberChecks that the number is not less than the given value.{ min_number: 18 }TOO_LOWNOT_NUMBERnumber_betweenChecks that the number is between the two values, inclusive.{ number_between: [18, 95] }TOO_HIGHTOO_LOWNOT_NUMBER

Special rulesEmails, URLs, dates, and comparison with another field.

emailChecks that the value is an email address.'email'WRONG_EMAILurlChecks that the value is a URL. Only the http and https protocols are allowed, and the protocol is required.'url'WRONG_URLiso_dateChecks that the value is an ISO 8601 date without time, for example "2014-08-14".'iso_date'WRONG_DATEequal_to_fieldChecks that the value is equal to the value of another field, for example a password confirmation. Values are compared as strings: "10" and 10 are equal, while "10" and "1e1" are not. A missing field is not equal to any value.{ equal_to_field: 'password' }FIELDS_NOT_EQUAL

MetarulesDescribe nested objects, lists and alternatives with other rules.

nested_objectDescribes validation rules for a nested object.{ nested_object: { … } }FORMAT_ERRORvariable_objectDescribes validation rules for a field that can contain different kinds of objects. The value of the selector field (product_type in the example) chooses the set of rules.{ variable_object: ['type', { … }] }FORMAT_ERRORlist_ofDescribes validation rules for a list. The rules are applied to every element.{ list_of: 'positive_integer' }FORMAT_ERRORlist_of_objectsDescribes validation rules for a list of objects. The rules are applied to every element.{ list_of_objects: { … } }FORMAT_ERRORlist_of_different_objectsDescribes validation rules for a list of different objects. For every element, the value of the selector field chooses the set of rules, like in variable_object.{ list_of_different_objects: ['type', { … }] }FORMAT_ERRORorTakes several sets of rules and applies them one after another until one of them succeeds.{ or: ['email', 'positive_integer'] }no errors

ModifiersChange the data. Modifiers never return errors.

trimRemoves leading and trailing whitespace.'trim'no errorsto_lcConverts the string to lower case.'to_lc'no errorsto_ucConverts the string to upper case.'to_uc'no errorsremoveRemoves the given characters from the string.{ remove: '-() ' }no errorsleave_onlyRemoves all characters except the given ones.{ leave_only: '0123456789' }no errorsdefaultSets the value if it is empty: missing, null or an empty string. Other values, including 0, are kept.{ default: 18 }no errors

Empty values are skipped

All standard rules skip empty values: a missing field, null and an empty string "". Only required, not_empty and not_empty_list check that a value is present. So the same rules work for optional fields:

first_name: { min_length: 10 }               // optional: the length is checked only if "first_name" is passed
first_name: ['required', { min_length: 10 }] // the name must be present and at least 10 characters long

Rules that expect a primitive value (a string, a number or a boolean) return FORMAT_ERROR when they receive an object or a list. See Error codes.

Learn more

• How it works: the syntax of rules and how they are combined.
• Types coercing: what the rules return.
• Rules aliasing and Create own plugins: projects usually add a few rules of their own.