validator
Macros 1.1 custom derive to simplify struct validation inspired by marshmallow and
Django validators.
It relies on the proc_macro
feature which is stable since Rust 1.15.
By default all args to a validate
must be strings if you are using stable.
However, if you are using nightly, you can also activate the attr_literals
feature to be able to use int, float and boolean as well.
A short example:
#[macro_use]
extern crate validator_derive;
extern crate validator;
#[macro_use]
extern crate serde_derive;
extern crate serde_json;
// A trait that the Validate derive will impl
use validator::{Validate, ValidationError};
#[derive(Debug, Validate, Deserialize)]
struct SignupData {
#[validate(email)]
mail: String,
#[validate(phone)]
phone: String,
#[validate(url)]
site: String,
#[validate(length(min = "1"), custom = "validate_unique_username")]
#[serde(rename = "firstName")]
first_name: String,
#[validate(range(min = "18", max = "20"))]
age: u32,
}
fn validate_unique_username(username: &str) -> Result<(), ValidationError> {
if username == "xXxShad0wxXx" {
// the value of the username will automatically be added later
return Err(ValidationError::new("terrible_username"));
}
Ok(())
}
match signup_data.validate() {
Ok(_) => (),
Err(e) => return e;
};
An error has the following structure:
#[derive(Debug, PartialEq, Clone, Serialize, Deserialize)]
pub struct ValidationError {
pub code: Cow<'static, str>,
pub message: Option<Cow<'static, str>>,
pub params: HashMap<Cow<'static, str>, Value>,
}
The value of the field will automatically be added to the params with a key of value
.
Note that validator
works in conjunction with serde: in the example we can see that the first_name
field is renamed from/to firstName
. Any error on that field will be in the firstName
key of the hashmap,
not first_name
.
If you are adding a validation on a Option<..>
field, it will only be ran if there is a value. The exception
being must_match
that doesn't currently work with Option
due to me not finding a use case for it. If you have one,
please comment on Keats#7.
Usage
You will need to import the Validate
trait, and optionally use the attr_literals
feature.
The validator
crate can also be used without the custom derive as it exposes all the
validation functions and types.
Validators
The crate comes with some built-in validators and you can have several validators for a given field.
Tests whether the String is a valid email according to the HTML5 regex, which means it will mark
some esoteric emails as invalid that won't be valid in a email
input as well.
This validator doesn't take any arguments: #[validate(email)]
.
url
Tests whether the String is a valid URL.
This validator doesn't take any arguments: #[validate(url)]
;
length
Tests whether a String or a Vec match the length requirement given. length
has 3 integer arguments:
- min
- max
- equal
Using equal
excludes the min
or max
and will result in a compilation error if they are found.
At least one argument is required with a maximum of 2 (having min
and max
at the same time).
Examples:
#[validate(length(min = "1", max = "10"))]
#[validate(length(min = "1"))]
#[validate(length(max = "10"))]
#[validate(length(equal = "10"))]
range
Tests whether a number is in the given range. range
takes 2 number arguments: min
and max
.
Examples:
#[validate(range(min = "1", max = "10"))]
#[validate(range(min = "1", max = "10.8"))]
#[validate(range(min = "1.1", max = "10.8"))]
must_match
Tests whether the 2 fields are equal. must_match
takes 1 string argument. It will error if the field
mentioned is missing or has a different type than the field the attribute is on.
Examples:
#[validate(must_match = "password2"))]
contains
Tests whether the string contains the substring given or if a key is present in a hashmap. contains
takes
1 string argument.
Examples:
#[validate(contains = "gmail"))]
regex
Tests whether the string matchs the regex given. regex
takes
1 string argument: the path to a static Regex instance.
Examples:
#[validate(regex = "ALLOWED_USERNAMES_RE"))]
credit_card
Test whetever the string is a valid credit card number.
Examples:
#[validate(credit_card)]
phone
Tests whether the String is a valid phone number (in international format, ie.
containing the country indicator like +14152370800
for an US number — where 4152370800
is the national number equivalent, which is seen as invalid).
To use this validator, you must enable the phone
feature for the validator_derive
crate.
This validator doesn't take any arguments: #[validate(phone)]
;
custom
Calls one of your function to do a custom validation.
The field will be given as parameter and it should return a Option<String>
representing the error code,
if there was an error.
Examples:
#[validate(custom = "validate_something")]
#[validate(custom = "::utils::validate_something"]
Struct level validation
Often, some error validation can only be applied when looking at the full struct, here's how it works here:
#[derive(Debug, Validate, Deserialize)]
#[validate(schema(function = "validate_category", skip_on_field_errors = "false")]
struct CategoryData {
category: String,
name: String,
}
The function mentioned should return a Option<(String, String)>
where the tuple is (key error, error code)
and will be called after validation is done for all fields.
This means that the error can be reported on an existing field or on a new key.
The skip_on_field_errors
defaults to true
if not present and will ensure that the function is not called
if an error happened while validating the struct fields.
Any error on the schema level validation will appear in the key __all__
of the hashmap of errors.
Message and code
Each validator can take 2 optional arguments in addition to their own arguments:
message
: a message to go with the error, for example if you want to do i18ncode
: each validator has a default error code (for example theregex
validator code isregex
) but it can be overriden if necessary, mainly needed for thecustom
validator
For example, the following attributes all work:
#[validate(email)]
#[validate(email(code="mail"))]
#[validate(email(message="Email %s is not valid"))]
#[validate(email(code="mail", message="Email %s is not valid"))]
Changelogs
validator
0.7.0 (2018/05/29)
- Feature gate the card validator
0.6.2 (2017/11/08)
- Fix credit card validation being incorrect in enum
0.6.1 (2017/11/08)
- Add international phone number and credit card validation
0.6.0 (2017/08/12)
- Re-design
ValidationError
andValidate
trait
validator_derive
0.7.1 (2018/06/28)
- Update dependencies
0.7.0 (2018/05/29)
- Feature gate the card validator
0.6.5 (2018/04/14)
- Fix path for regex starting with
::
- Update syn and quote
0.6.4 (2018/03/20)
- Support
Option<Option<T>>
types
0.6.3 (2018/03/19)
- Fix path for custom validators starting with
::
0.6.2 (2018/03/17)
- Update syn and quote
0.6.1 (2017/11/08)
- Add international phone number and credit card derive
0.6.0 (2017/08/12)
- Change generated code to make the new design of errors work
Previous
0.5.0 (2017/05/22) > validator_derive only
- Fix range validator not working on Option
- Update to serde 1.0
0.4.1 (2017/02/14) > validator_derive only
- Fix potential conflicts with other attributes
0.4.0 (2017/01/30)
- Validators now work on
Option
field and struct/fields with lifetimes
0.3.0 (2017/01/17)
- Add
contains
andregex
validator - BREAKING: change
Errors
type to be a newtype in order to extend it
0.2.0 (2017/01/17)
- Remove need for
attr_literals
feature - Fix error when not having validation on each field
- Add struct level validation
- Add
must_match
validator