Validation rules
The standard rules of the specification. 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.
Rules marked 2.5 were added in LIVR 2.5. Implementations of LIVR 2.0 do not have them, the conformance table shows which implementations pass the 2.5 test suite.
68 rules
Common rulesCheck that a value is present, or that it is an object or a boolean.
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_ERRORrequired_if2.5Makes the field required when other fields have the given values.{ required_if: { type: 'company' } }REQUIREDany2.5Accepts any JSON value, including objects and lists, and returns it unchanged.'any'no errorsboolean2.5Checks that the value is a boolean, 1, 0, or one of the strings "1", "0", "true" and "false", and returns a real boolean.'boolean'NOT_BOOLEANString 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: '^[0-9]+$' }WRONG_FORMATnot_one_of2.5Checks that the value is not equal to any of the given values. Values are compared as strings, and the output is the value unchanged.{ not_one_of: ['admin', 'root'] }NOT_ALLOWED_VALUEdigits2.5Checks that the value consists of ASCII digits 0-9 only. Unlike positive_integer, leading zeros are kept and the output is a string.'digits'NOT_DIGITSstarts_with2.5Checks that the value starts with one of the given strings.{ starts_with: 'https://' }WRONG_FORMATends_with2.5Checks that the value ends with one of the given strings.{ ends_with: '.pdf' }WRONG_FORMATcontains2.5Checks that the value contains at least one of the given strings.{ contains: '@' }WRONG_FORMATNumeric 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_NUMBERmax_decimals2.5Checks that the number has at most the given number of digits after the decimal point, and returns it as a number.{ max_decimals: 2 }TOO_MANY_DECIMALSNOT_NUMBERSpecial rulesEmails, URLs, dates and times, 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_DATEiso_datetime2.5Checks that the value is an ISO 8601 date and time with an offset, and returns it in UTC, for example "2026-10-29T08:00:00.000Z".'iso_datetime', { iso_datetime: { min: 'today' } }WRONG_DATETIMEDATETIME_TOO_EARLYDATETIME_TOO_LATEequal_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_EQUALiso_time2.5Checks that the value is a time of day without a date and an offset: HH:MM, HH:MM:SS, or HH:MM:SS with a fraction of a second.'iso_time', { iso_time: { min: '09:00', max: '18:00' } }WRONG_TIMETIME_TOO_EARLYTIME_TOO_LATEMetarulesDescribe nested objects, lists, conditions 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 errorswhen2.5Applies rules to the field depending on the value of another field.{ when: ['type', { eq: 'company' }, 'required'] }NOT_ALLOWED_VALUEvalues2.5Validates every value of an object with the same rules, as list_of validates every item of a list. The keys can be any.{ values: 'positive_integer' }FORMAT_ERRORkeys2.5Validates every key of an object as a string with the given rules. The rules only check: the keys do not change.{ keys: { one_of: ['uk', 'en'] } }WRONG_KEYList rulesCheck the length of a list and that its items are unique.
Format rulesIdentifiers, network addresses, encodings and other common string formats.
uuid2.5Checks that the value is a UUID (RFC 9562), of any version or of the given versions.'uuid', { uuid: 'v4' }WRONG_UUIDip2.5Checks that the value is an IPv4 or an IPv6 address.'ip', { ip: 'v4' }WRONG_IPcidr2.5Checks that the value is an IP address with a prefix length, for example 192.0.2.0/24.'cidr', { cidr: 'v4' }WRONG_CIDRhostname2.5Checks that the value is a hostname (RFC 1123), for example api.example.com or localhost.'hostname'WRONG_HOSTNAMEbase642.5Checks that the value is a Base64 string (RFC 4648).'base64'FORMAT_ERRORhex2.5Checks that the value is a string of hex digits 0-9a-fA-F, without the 0x prefix.'hex'WRONG_HEXdigest2.5Checks that the value is a hex digest of one of the given hash algorithms.{ digest: 'sha256' }WRONG_DIGESTmongo_id2.5Checks that the value is a BSON ObjectId: 24 hex digits.'mongo_id'WRONG_MONGO_IDhex_color2.5Checks that the value is a hex color: # and 3, 4, 6 or 8 hex digits, for example #f80 or #FF8800.'hex_color'WRONG_HEX_COLORmac2.5Checks that the value is a MAC address: six pairs of hex digits separated by : or by -. { mac: 64 } checks a 64-bit EUI-64 identifier: eight pairs.'mac', { mac: 64 }WRONG_MACe1642.5Checks that the value is a phone number in the E.164 format: +, then 7–15 digits, the first of which is not 0.'e164'FORMAT_ERRORsemver2.5Checks that the value is a semantic version, for example 1.2.3 or 2.0.0-rc.1+build.5.'semver'WRONG_SEMVERjwt2.5Checks that the value has the structure of a JSON Web Token: header.payload.signature in base64url, the JWS compact serialization (RFC 7515, section 7.1). The token is not decoded or verified.'jwt'WRONG_JWTChecksum rulesNumbers with a check digit: Luhn, payment cards and IBANs.
luhn2.5Checks that the value is at least 2 ASCII digits and that its Luhn mod 10 checksum is 0.'luhn'WRONG_CHECKSUMcredit_card2.5Checks that the value is a payment card number: 12–19 ASCII digits (ISO/IEC 7812) with a valid Luhn checksum.'credit_card'WRONG_CREDIT_CARD_NUMBERiban2.5Checks that the value is an IBAN (ISO 13616) with valid check digits.'iban'WRONG_IBANModifiersChange 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 errorssplit2.5Splits a string into a list at every separator. The separator is a non-empty string, not a regular expression.{ split: ',' }no errorsEmpty 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 (in LIVR 2.5 also required_if). So the same rules work for optional fields:
js
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 longRules 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.