Expand description
§valid8r
Validate Rust structs with #[derive(Validate)] and receive structured field,
nested, and schema errors. Use it for form input, API payloads, and partial
updates.
This crate builds on validator by
Vincent Prouillet and its contributors. It adds conditional presence and
prohibition rules, phone and consent validation, PATCH semantics.
§Contents
- Quick Start
- Feature Flags
- Error Handling
- Optional Fields
- Sensitive Values
- PATCH Semantics
- Nested Validation
- Custom Validators
- Schema Validation
- Validation Context
- Custom Error Messages and Codes
- Skipping Fields
- Request Validation
- Validator Reference
- License
§Quick Start
Requires Rust 1.94 or later. Add this to Cargo.toml:
[dependencies]
valid8r = "0.2"The Validate import brings both the derive macro and the trait into scope.
Annotate fields with rules, then call .validate():
use valid8r::Validate;
#[derive(Validate)]
struct SignUp {
#[validate(email)]
email: String,
#[validate(length(min = 8), sensitive)]
password: String,
#[validate(accepted)]
accepted_terms: bool,
}
let mut signup = SignUp {
email: "person@example.com".into(),
password: "long-enough-password".into(),
accepted_terms: true,
};
assert!(signup.validate().is_ok());
signup.email = "invalid".into();
let errors = signup.validate().unwrap_err();
assert_eq!(errors.field_errors()["email"][0].code, "email");Validation returns Ok(()) when all rules pass and Err(ValidationErrors)
when they fail. It checks the values without changing them. You must call
.validate() yourself after constructing or deserializing the struct.
§Feature Flags
The derive macro is always available. No optional features are enabled by default. Basic email, length, range, IP, presence, consent, and custom rules work with the dependency above.
Enable email when you need email domain syntax checks. Without this
feature, email checks the local part and lengths but can accept an empty
or malformed domain, such as "person@".
| Feature | What it adds |
|---|---|
email | Email domain validation through idna; basic email validation is already available |
url | HTTP/HTTPS URL validation |
phone_number | Phone validation through phonenumber |
cards | Credit-card validation through card-validate |
indexmap | length validation for IndexMap and IndexSet |
full | All optional features above |
Enable the features your fields need:
[dependencies]
valid8r = { version = "0.2", features = ["url", "phone_number"] }For all optional validators, use features = ["full"]. A rule such as
#[validate(url)] needs its feature enabled in Cargo.toml.
§Error Handling
Each ValidationError has a machine-readable code, an optional message,
and a params map with details such as the submitted value and rule bounds.
The default code is usually the validator name, for example "email" or
"length". Messages are only present when supplied by an attribute or a
custom validator.
Use .field_errors() to inspect direct field errors:
use valid8r::Validate;
#[derive(Validate)]
struct Contact {
#[validate(email(message = "Enter a valid email address"))]
email: String,
}
let contact = Contact {
email: "invalid".into(),
};
let errors = contact.validate().unwrap_err();
let error = &errors.field_errors()["email"][0];
assert_eq!(error.code, "email");
assert_eq!(
error.message.as_deref(),
Some("Enter a valid email address")
);
assert_eq!(error.params["value"], "invalid");
// Serialize the whole error tree for an API response.
let json = serde_json::to_value(&errors).unwrap();
assert_eq!(json["email"][0]["code"], "email");Add serde_json = "1" to your application’s dependencies for serialization.
The JSON representation of the error above is:
{
"email": [
{
"code": "email",
"message": "Enter a valid email address",
"params": { "value": "invalid" }
}
]
}.field_errors() includes only direct field errors. Use .errors() or
serialize the whole ValidationErrors to retain nested errors. Entries are
ValidationErrorsKind::Field (a list of errors), Struct (child fields), or
List (child errors indexed by position). Schema errors use the __all__
key. See Nested Validation and
Schema Validation.
When scalar field errors and nested errors share a key, the nested errors take precedence and the scalar errors under that key are discarded.
§Optional Fields
Value rules such as email, length, range, and custom check the inner
value of Some(value) and skip None. Add required when the value must be
present (or just don’t make it Option):
use valid8r::Validate;
#[derive(Validate)]
struct Profile {
#[validate(email)]
backup_email: Option<String>,
#[validate(required, length(min = 3))]
display_name: Option<String>,
}
let missing = Profile {
backup_email: None,
display_name: None,
};
assert_eq!(
missing.validate().unwrap_err().field_errors()["display_name"][0].code,
"required"
);
let present = Profile {
backup_email: None,
display_name: Some("Ada".into()),
};
assert!(present.validate().is_ok());required checks presence, rather than string length: Some("") satisfies
required, but fails length(min = 1). Presence and prohibition rules still
check absent fields; they do not behave like value rules.
§Empty Strings
email(nullable), url(nullable), and phone_number(nullable) accept an
empty string as well as a valid value. They leave the empty string unchanged;
conversion to
None or a database null belongs to your application.
use valid8r::Validate;
#[derive(Validate)]
struct Contact {
#[validate(email(nullable))]
email: String,
}
let empty = Contact { email: String::new() };
let invalid = Contact { email: "invalid".into() };
assert!(empty.validate().is_ok());
assert!(invalid.validate().is_err());Enable the corresponding url or phone_number feature for those rules.
Whitespace is not an empty string, and nullable does not bypass other
rules on the field.
§Sensitive Values
Value validators normally include the submitted value in error parameters.
Add sensitive to a field to remove its value parameter. When must_match
compares against a sensitive field, it also omits that field’s other
parameter:
use valid8r::Validate;
#[derive(Validate)]
struct PasswordChange {
#[validate(length(min = 8), sensitive)]
password: String,
#[validate(must_match(other = "password"), sensitive)]
confirmation: String,
}
let change = PasswordChange {
password: "short".into(),
confirmation: "different".into(),
};
let errors = change.validate().unwrap_err();
assert!(
!errors.field_errors()["password"][0]
.params
.contains_key("value")
);
assert!(
!errors.field_errors()["confirmation"][0]
.params
.contains_key("value")
);
assert!(
!errors.field_errors()["confirmation"][0]
.params
.contains_key("other")
);Codes, messages, and non-value parameters such as min remain available.
Custom validators control their other parameters and messages, so keep
credentials out of those too. Annotate sensitive fields inside nested structs
as well; an annotation on a parent field does not redact its children’s
errors.
§PATCH Semantics
Partial updates need three states: leave a field unchanged, clear it, or set
it to a value. valid8r recognizes both Option<Option<T>> and
Delta<T>.
| Request state | Option<Option<T>> | Delta<T> | Value rules run? | Counts as present? |
|---|---|---|---|---|
| Omitted | None | Delta::Unchanged | No | No |
Explicit null | Some(None) | Delta::Clear | No | No |
| Value | Some(Some(value)) | Delta::Set(value) | Yes | Yes |
Presence rules still run. For example, required rejects both omitted and
cleared fields, while required_with becomes active only when a referenced
field has an actual value. valid8r validates the incoming update; applying
it to stored data is your application’s responsibility.
§Using Option<Option<T>>
Serde’s default handling of nested Options treats both a missing field and
JSON null as None. Use default together with a custom deserializer to
preserve explicit nulls. For the example below, add:
[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"use serde::{Deserialize, Deserializer};
use valid8r::Validate;
fn deserialize_patch_field<'de, D, T>(deserializer: D) -> Result<Option<Option<T>>, D::Error>
where
D: Deserializer<'de>,
T: Deserialize<'de>,
{
Option::<T>::deserialize(deserializer).map(Some)
}
#[derive(Deserialize, Validate)]
struct UpdateUser {
#[serde(default, deserialize_with = "deserialize_patch_field")]
#[validate(required_with(other_fields("area_id")))]
country_id: Option<Option<i32>>,
#[serde(default, deserialize_with = "deserialize_patch_field")]
area_id: Option<Option<i32>>,
#[serde(default, deserialize_with = "deserialize_patch_field")]
#[validate(range(min = 0, max = 100))]
score: Option<Option<i32>>,
}
let omitted: UpdateUser = serde_json::from_str("{}").unwrap();
assert_eq!(omitted.area_id, None);
assert!(omitted.validate().is_ok());
let cleared: UpdateUser = serde_json::from_str(r#"{"area_id": null}"#).unwrap();
assert_eq!(cleared.area_id, Some(None));
assert!(cleared.validate().is_ok());
// Setting area_id requires a value for country_id too.
let missing_country: UpdateUser = serde_json::from_str(r#"{"area_id": 123}"#).unwrap();
assert!(missing_country.validate().is_err());
let valid: UpdateUser =
serde_json::from_str(r#"{"area_id": 123, "country_id": 1, "score": 50}"#).unwrap();
assert!(valid.validate().is_ok());§Using Delta<T>
Delta<T> models the same states directly and requires only
#[serde(default)] for missing fields. Use the delta repository below;
the unrelated crate with the same name on crates.io does not provide this
type:
[dependencies]
delta = { git = "https://github.com/musajingo/delta", tag = "v0.1.0" }
serde = { version = "1", features = ["derive"] }
serde_json = "1"use delta::Delta;
use serde::Deserialize;
use valid8r::Validate;
#[derive(Deserialize, Validate)]
struct UpdateUser {
#[serde(default)]
#[validate(email)]
email: Delta<String>,
#[serde(default)]
#[validate(required_with(other_fields("area_id")))]
country_id: Delta<i32>,
#[serde(default)]
area_id: Delta<i32>,
}
let cleared: UpdateUser = serde_json::from_str(r#"{"area_id": null}"#).unwrap();
assert!(matches!(cleared.area_id, Delta::Clear));
assert!(cleared.validate().is_ok());
let invalid: UpdateUser = serde_json::from_str(r#"{"area_id": 123}"#).unwrap();
assert!(invalid.validate().is_err());§Nested Validation
Validate nested structs using the nested attribute:
use valid8r::Validate;
#[derive(Validate)]
struct Address {
#[validate(length(min = 1))]
street: String,
#[validate(length(min = 1))]
city: String,
}
#[derive(Validate)]
struct User {
#[validate(email)]
email: String,
#[validate(nested)]
address: Address,
// Optional nested validation
#[validate(nested)]
billing_address: Option<Address>,
}Use nest_all_fields when every field should receive nested validation. Each
field must support .validate() after unwrapping any optional values:
use valid8r::Validate;
#[derive(Validate)]
#[validate(nest_all_fields)]
struct Company {
address: Address, // Automatically nested
mailing: Address, // Automatically nested
}Use #[validate(nested)] on Vec<T> to validate its elements. Child errors
remain under the parent field; collection errors are indexed by element
position. Optional nested values are skipped when absent. For example:
use valid8r::{Validate, ValidationErrorsKind};
#[derive(Validate)]
struct Address {
#[validate(length(min = 1))]
street: String,
}
#[derive(Validate)]
struct Order {
#[validate(nested)]
addresses: Vec<Address>,
}
let order = Order {
addresses: vec![Address {
street: String::new(),
}],
};
let errors = order.validate().unwrap_err();
let ValidationErrorsKind::List(children) = &errors.errors()["addresses"] else {
panic!("expected indexed child errors");
};
assert_eq!(children[&0].field_errors()["street"][0].code, "length");§Custom Validators
Use a custom function for validation. Multiple custom validators can be applied.
use valid8r::{Validate, ValidationError};
fn validate_username(username: &str) -> Result<(), ValidationError> {
if username.chars().next().is_some_and(|c| c.is_numeric()) {
return Err(ValidationError::new("username_starts_with_number")
.with_message("Username cannot start with a number".into()));
}
Ok(())
}
fn validate_not_reserved(username: &str) -> Result<(), ValidationError> {
let reserved = ["admin", "root", "system"];
if reserved.contains(&username.to_lowercase().as_str()) {
return Err(ValidationError::new("reserved_username")
.with_message("This username is reserved".into()));
}
Ok(())
}
#[derive(Validate)]
struct User {
#[validate(custom(function = validate_username))]
#[validate(custom(function = validate_not_reserved))]
username: String,
}The function returns Ok(()) for a valid value or a ValidationError for an
invalid value. Optional fields pass their inner value when present. Numeric
primitives written as i32, f64, etc. are passed by value; aliases and
qualified spellings can instead require references. Strings and collections
can use borrowed arguments such as &str and &[T]. Values passed to custom
field validators must support Serde serialization so they can be recorded
in error parameters.
§Schema Validation
Use a schema function for a rule involving the whole struct. It receives
&Struct and returns Result<(), ValidationError>:
use valid8r::{Validate, ValidationError};
fn check_date_range(form: &DateForm) -> Result<(), ValidationError> {
if form.start_day > form.end_day {
return Err(ValidationError::new("invalid_date_range")
.with_message("Start day must not be after end day".into()));
}
Ok(())
}
#[derive(Validate)]
#[validate(schema(function = check_date_range))]
struct DateForm {
#[validate(range(min = 1))]
start_day: i32,
#[validate(range(min = 1))]
end_day: i32,
}
let invalid = DateForm {
start_day: 10,
end_day: 5,
};
let errors = invalid.validate().unwrap_err();
assert_eq!(
errors.field_errors()["__all__"][0].code,
"invalid_date_range"
);
// Field errors skip this schema function by default.
let invalid_field = DateForm {
start_day: 0,
end_day: 5,
};
assert!(
!invalid_field
.validate()
.unwrap_err()
.errors()
.contains_key("__all__")
);Schema errors are stored under __all__. By default, schema functions run
only when field validation, including nested validation, passes. Add
skip_on_field_errors = false to the schema attribute to run it despite
field errors:
#[validate(schema(function = check_date_range, skip_on_field_errors = false))].
You can repeat the #[validate(schema(...))] attribute to run multiple
functions. An earlier schema failure does not suppress later schemas when
all fields were valid. Use use_context to pass a
validation context along with the struct.
§Validation Context
Use ValidateArgs to pass application data into a custom field or schema
validator. Declare its type on the struct and add use_context to each
function that needs it:
use valid8r::{Validate, ValidateArgs, ValidationError};
struct ValidationContext {
max_items: usize,
}
fn check_item_limit(items: &[String], ctx: &ValidationContext) -> Result<(), ValidationError> {
if items.len() > ctx.max_items {
Err(ValidationError::new("too_many_items"))
} else {
Ok(())
}
}
#[derive(Validate)]
#[validate(context = ValidationContext)]
struct Order {
#[validate(custom(function = check_item_limit, use_context))]
items: Vec<String>,
}
let ctx = ValidationContext { max_items: 1 };
let order = Order {
items: vec!["first".into(), "second".into()],
};
let errors = order.validate_with_args(&ctx).unwrap_err();
assert_eq!(errors.field_errors()["items"][0].code, "too_many_items");A struct with context uses .validate_with_args(&ctx) instead of generating
an argument-free .validate(). Schema functions with use_context receive
(&Struct, &Context). For a context type containing borrowed data, use the
lifetime 'v_a in its attribute path, for example
#[validate(context = "ValidationContext<'v_a>")]. Add mutable at the struct
level when the context must be passed as &mut Context.
Nested validation calls each child’s .validate(); it does not forward
the parent’s context automatically.
§Custom Error Messages and Codes
Value, presence, consent, custom, and schema rules accept code and
message. Keep codes stable for callers; use messages for display:
use valid8r::Validate;
#[derive(Validate)]
struct Login {
#[validate(email(code = "INVALID_EMAIL", message = "Please enter a valid email address"))]
email: String,
#[validate(length(
min = 8,
code = "PASSWORD_TOO_SHORT",
message = "Password must be at least 8 characters"
))]
password: String,
}§Skipping Fields
Skip validation for specific fields:
use valid8r::Validate;
#[derive(Validate)]
struct Data {
#[validate(skip)]
internal_id: String, // Never validated
#[validate(email)]
email: String,
}Fields without validation attributes are otherwise left alone. skip is
useful when opting out of struct-wide nest_all_fields validation.
§Request Validation
In a web handler, deserialize the payload, validate it, and then perform the
operation. Deserialization and validation report different failures: JSON
parsing checks types and syntax, while .validate() checks your rules.
The following function can be called from a handler in any web framework.
For this example, add serde with its derive feature and serde_json as
shown in PATCH Semantics.
use serde::Deserialize;
use valid8r::{Validate, ValidationErrors};
#[derive(Debug, Deserialize, Validate)]
struct CreateUser {
#[validate(email)]
email: String,
#[validate(length(min = 8), sensitive)]
password: String,
}
#[derive(Debug)]
enum RequestError {
InvalidJson(serde_json::Error),
InvalidFields(ValidationErrors),
}
fn parse_user(body: &str) -> Result<CreateUser, RequestError> {
let user: CreateUser = serde_json::from_str(body).map_err(RequestError::InvalidJson)?;
user.validate().map_err(RequestError::InvalidFields)?;
Ok(user)
}
assert!(parse_user(r#"{"email":"person@example.com","password":"long-enough"}"#).is_ok());
assert!(matches!(
parse_user(r#"{"email":"invalid","password":"long-enough"}"#),
Err(RequestError::InvalidFields(_)),
));
assert!(matches!(
parse_user("not JSON"),
Err(RequestError::InvalidJson(_))
));Map InvalidJson and InvalidFields to your framework’s error responses.
Serialize the ValidationErrors in InvalidFields when returning field
feedback to a client.
§Validator Reference
Rules can share a single attribute, such as
#[validate(required, email)], or use separate attributes on the same field.
custom can be repeated to call multiple functions.
Presence and prohibition rules interpret Some(_) as present for Option<T>,
and only actual inner values as present for PATCH types. With an empty
string, an Option<String> is still present. Fields named in other_fields
must be optional (Option<T>, nested Option, or Delta<T>). Predicate
functions for required_if and prohibited_if receive &Struct and return
bool.
§String/Format Validators
§email
Checks for an @, a nonempty local part matching the supported character
pattern, and length limits of 64 Unicode scalar values for the local part
and 255 for the domain. The email feature additionally checks domain
syntax, including internationalized domains and supported IP literals.
It does not verify that a mailbox or domain exists.
use valid8r::Validate;
#[derive(Validate)]
struct Newsletter {
#[validate(email)]
email: String,
// With custom error
#[validate(email(message = "Please provide a valid email", code = "invalid_email"))]
contact_email: String,
}
let newsletter = Newsletter {
email: "person@example.com".into(),
contact_email: "person@example.com".into(),
};
assert!(newsletter.validate().is_ok());
let invalid = Newsletter {
email: "invalid".into(),
..newsletter
};
assert!(invalid.validate().is_err());Supported types: String, &str, Cow<str>, Option<T> where T implements ValidateEmail
§url
Validates an absolute HTTP or HTTPS URL. Other schemes, including ftp:,
javascript:, and data:, are rejected.
use valid8r::Validate;
#[derive(Validate)]
struct Website {
#[validate(url)]
homepage: String,
#[validate(url(message = "Invalid website URL"))]
blog: Option<String>,
}
let mut website = Website {
homepage: "https://example.com".into(),
blog: None,
};
assert!(website.validate().is_ok());
website.homepage = "ftp://example.com".into();
assert!(website.validate().is_err());Requires: the url cargo feature (not in the default set)
§phone_number
Parses phone numbers and checks their validity using phonenumber. The
optional country is a parsing hint for national-format numbers, not a
restriction on international numbers with an explicit country prefix.
use valid8r::Validate;
#[derive(Validate)]
struct Contact {
// International format (auto-detect country)
#[validate(phone_number)]
phone: String,
// Country hint for national-format numbers
#[validate(phone_number(country = "US"))]
us_phone: String,
#[validate(phone_number(country = "GB", message = "Invalid phone number"))]
uk_phone: Option<String>,
}
let contact = Contact {
phone: "+447911123456".into(),
// An explicit international prefix takes precedence over the US hint.
us_phone: "+447911123456".into(),
uk_phone: Some("07911123456".into()),
};
assert!(contact.validate().is_ok());
#[derive(Validate)]
struct OptionalPhone {
#[validate(phone_number(nullable))]
phone: String,
}
assert!(OptionalPhone { phone: String::new() }.validate().is_ok());
assert!(OptionalPhone { phone: "invalid".into() }.validate().is_err());Requires: the phone_number cargo feature (not in the default set)
Country codes: Use ISO 3166-1 alpha-2 codes (e.g., “US”, “GB”, “DE”, “FR”)
§credit_card
Checks credit-card format and checksum through card-validate. Passing
validation does not establish that a card is active or can be charged.
use valid8r::Validate;
#[derive(Validate)]
struct Payment {
#[validate(credit_card)]
card_number: String,
}
assert!(Payment { card_number: "4539571147647251".into() }.validate().is_ok());
assert!(Payment { card_number: "4539571147647252".into() }.validate().is_err());Requires: the cards cargo feature (not in the default set)
§ip
Validates IP addresses (v4, v6, or both).
use valid8r::Validate;
#[derive(Validate)]
struct Server {
// Any IP (v4 or v6)
#[validate(ip)]
address: String,
// IPv4 only
#[validate(ip(v4))]
ipv4_address: String,
// IPv6 only
#[validate(ip(v6))]
ipv6_address: String,
}§regex
Validates against a regular expression pattern.
use regex::Regex;
use std::sync::LazyLock;
use valid8r::Validate;
// Define regex as a static for efficiency
static USERNAME_RE: LazyLock<Regex> =
LazyLock::new(|| Regex::new(r"^[a-zA-Z][a-zA-Z0-9_]{2,29}$").unwrap());
#[derive(Validate)]
struct User {
#[validate(regex(path = *USERNAME_RE))]
username: String,
}Add regex = "1" to your dependencies. A LazyLock compiles the pattern once
and reuses it for each validation.
§non_control_character
Validates that a string contains no control characters.
use valid8r::Validate;
#[derive(Validate)]
struct Input {
#[validate(non_control_character)]
user_input: String,
}§Numeric and Length Validators
§range
Validates that a number falls within a specified range.
Inclusive bounds alone do not reject floating-point NaN. Use a custom
validator that checks .is_finite() when non-finite values must be rejected.
use valid8r::Validate;
#[derive(Validate)]
struct Product {
// Inclusive min and max
#[validate(range(min = 0, max = 100))]
quantity: i32,
// Min only
#[validate(range(min = 0.01))]
price: f64,
// Max only
#[validate(range(max = 1000000))]
budget: Option<i64>,
// Exclusive bounds
#[validate(range(exclusive_min = 0.0, exclusive_max = 1.0))]
probability: f64,
}
let mut product = Product {
quantity: 50,
price: 1.0,
budget: None,
probability: 0.5,
};
assert!(product.validate().is_ok());
product.probability = 1.0;
assert!(product.validate().is_err());Supported types: All numeric primitives (u8-u128, i8-i128, usize, isize, f32, f64),
rust_decimal::Decimal, Option<T>, Option<Option<T>>
§length
Checks the number of Unicode scalar values in a string, or the number of
items in a collection or array. Bounds are inclusive. Use equal on its own;
it cannot be combined with min or max in a derive attribute.
use valid8r::Validate;
#[derive(Validate)]
struct Form {
// Min and max length
#[validate(length(min = 3, max = 50))]
username: String,
// Exact length
#[validate(length(equal = 6))]
pin_code: String,
// Collection length
#[validate(length(min = 1, max = 10))]
tags: Vec<String>,
// Array length
#[validate(length(equal = 3))]
rgb: [u8; 3],
}Supported types: String, &str, Vec<T>, HashMap, HashSet, BTreeMap,
BTreeSet, VecDeque, [T; N], &[T], Cow<str>
For strings, this is the count from .chars(), rather than bytes or displayed
grapheme clusters. For example, a letter followed by a combining accent
counts as two scalar values.
§Presence Validators
§required
Validates that an Option field contains a value.
use valid8r::Validate;
#[derive(Validate)]
struct Registration {
#[validate(required)]
email: Option<String>,
#[validate(required(message = "Password is required"))]
password: Option<String>,
}§required_if
Conditionally requires a field based on a function.
use valid8r::Validate;
fn needs_shipping(order: &Order) -> bool {
order.is_physical
}
#[derive(Validate)]
struct Order {
is_physical: bool,
#[validate(required_if(func = needs_shipping))]
shipping_address: Option<String>,
}§required_with
The field is required if any of the specified fields have a value.
use valid8r::Validate;
#[derive(Validate)]
struct Address {
// Country is required if area_id OR city_id is provided
#[validate(required_with(other_fields("area_id", "city_id")))]
country_id: Option<i32>,
area_id: Option<i32>,
city_id: Option<i32>,
}§required_with_all
The field is required if all specified fields have values.
use valid8r::Validate;
#[derive(Validate)]
struct DateRange {
start_date: Option<String>,
end_date: Option<String>,
// Timezone required only if both start and end dates are provided
#[validate(required_with_all(other_fields("start_date", "end_date")))]
timezone: Option<String>,
}§required_without
The field is required if any of the specified fields are missing.
use valid8r::Validate;
#[derive(Validate)]
struct Contact {
// Email required if phone is missing
#[validate(required_without(other_fields("phone")))]
email: Option<String>,
// Phone required if email is missing
#[validate(required_without(other_fields("email")))]
phone: Option<String>,
}§required_without_all
The field is required if all specified fields are missing.
use valid8r::Validate;
#[derive(Validate)]
struct Auth {
oauth_token: Option<String>,
api_key: Option<String>,
// Password required only if both oauth_token AND api_key are missing
#[validate(required_without_all(other_fields("oauth_token", "api_key")))]
password: Option<String>,
}§Prohibition Validators
§prohibited_if
The field must be absent if a condition is met.
use valid8r::Validate;
fn is_readonly(form: &Form) -> bool {
form.readonly
}
#[derive(Validate)]
struct Form {
readonly: bool,
#[validate(prohibited_if(func = is_readonly))]
new_value: Option<String>,
}§prohibited_with
The field must be absent if any of the specified fields have values.
use valid8r::Validate;
#[derive(Validate)]
struct Transfer {
// Cannot specify both bank transfer AND credit card
#[validate(prohibited_with(other_fields("credit_card_id")))]
bank_account_id: Option<String>,
#[validate(prohibited_with(other_fields("bank_account_id")))]
credit_card_id: Option<String>,
}§prohibited_with_all
The field must be absent if all specified fields have values.
§prohibited_without
The field must be absent if any of the specified fields are missing.
§prohibited_without_all
The field must be absent if all specified fields are missing.
§Container Validators
§contains
Validates that a string contains a specific substring. Works with String, &str,
Cow<str>, and HashMap<String, V> (checks key presence).
use std::collections::HashMap;
use valid8r::Validate;
#[derive(Validate)]
struct Config {
#[validate(contains(pattern = "@company.com"))]
corporate_email: String,
// For HashMap, checks if key exists
#[validate(contains(pattern = "admin"))]
permissions: HashMap<String, bool>,
}§does_not_contain
Checks that a string does not contain a substring, or a supported map does not contain the specified key.
use valid8r::Validate;
#[derive(Validate)]
struct Content {
#[validate(does_not_contain(pattern = "<script>"))]
html_content: String,
}§Comparison Validators
§must_match
Compares a field with another field of the same underlying type. The check runs only when the annotated field has a value. If the other field is absent or cleared, a present value fails the comparison.
use valid8r::Validate;
#[derive(Validate)]
struct PasswordChange {
new_password: String,
#[validate(must_match(other = "new_password"))]
confirm_password: String,
}§Consent Validators
§accepted
Accepts true for booleans. For strings, accepts "true", "1", "on", or
"yes", ignoring ASCII case.
use valid8r::Validate;
#[derive(Validate)]
struct Terms {
#[validate(accepted)]
accept_terms: bool,
#[validate(accepted)]
accept_privacy: String, // Accepts "yes", "on", "1", "true"
}§declined
Accepts false for booleans. For strings, accepts every value that accepted
rejects, including an empty string. It does not restrict input to a fixed
list of negative answers.
use valid8r::Validate;
#[derive(Validate)]
struct Preferences {
#[validate(declined)]
marketing_enabled: bool,
}§accepted_if / declined_if
Checks acceptance or decline when the predicate returns true. For an
Option<bool>, None skips this value check; add a required* rule when
absence should also fail.
use valid8r::Validate;
fn is_premium(reg: &Registration) -> bool {
reg.plan == "premium"
}
#[derive(Validate)]
struct Registration {
plan: String,
#[validate(accepted_if(function = is_premium))]
accept_premium_terms: Option<bool>,
}§License
Licensed under either MIT or Apache License, Version 2.0, at your option. The MIT license includes the original upstream copyright notice.
Structs§
- Validation
Error - Represents a single validation error.
- Validation
Errors - A collection of validation errors, typically mapping field names to their respective errors.
It’s newtype wrapper around a
HashMap.
Enums§
- Validation
Errors Kind - Represents the different kinds of validation errors that can occur for a field.
Traits§
- AsRegex
- A trait for types that can be converted or provide access to a
Regexinstance. - Validate
- A trait for data structures that can be validated.
- Validate
Args - This trait will be implemented by deriving
Validate. This implementation can take one argument and pass this on to custom validators. The defaultArgstype will be()if there is no custom validation with defined arguments. - Validate
Consent - A trait for types that can be validated as representing consent.
- Validate
Contains - A trait for types that can be checked for the presence of a substring or key.
- Validate
Credit Card - A trait for types that can be validated as a credit card number.
- Validate
Does NotContain - A trait for types that can be checked for the absence of a substring or key.
- Validate
Email - Validates whether the given string is an email based on the HTML5 spec. RFC 5322 is not practical in most circumstances and allows email addresses that are unfamiliar to most users.
- Validate
Ip - A trait for types that can be validated as an IP address.
- Validate
Length - Validates the length of the value given.
If the validator has
equalset, it will ignore anyminandmaxvalue. - Validate
NonControl Character - A trait for types that can be validated to ensure they do not contain control characters.
- Validate
Phone Number - A trait for types that can be validated as a phone number.
- Validate
Prohibited - A trait for types that can be checked for absence, particularly in “prohibited” validation scenarios.
- Validate
Range - Validates that the given
valueis inside the defined range. Themax,min,exclusive_maxandexclusive_minparameters are optional and will only be validated if they are notNone - Validate
Regex - A trait for types that can be validated against a regular expression.
- Validate
Required - A trait for types that can be validated for presence.
- Validate
Url - A trait for types that can be validated as a URL.
Functions§
- validate_
must_ match - Validates that the 2 given fields match. Both fields are optionals
Derive Macros§
- Validate
- The main procedural macro function for
#[derive(Validate)].