Request Validation

21 min read

In Express.js you reach for a library like Zod, Joi, or express-validator and wire it up as middleware that runs before your handler. Axum’s extractors already guarantee a request deserialized into the right shape — but “shape-correct” is not the same as “valid”. This page covers the next layer: enforcing business rules (a name is 2-50 characters, an email is well-formed, an age is in range) and returning a 400/422 with a helpful, structured body when those rules are broken.

Quick Overview

Deserialization answers “is this the right type?”; validation answers “is this acceptable?”. A JSON body can parse perfectly into a CreateUser { name: String, age: u8 } and still be garbage — an empty name, an email with no @, an age of 0. In Rust the idiomatic tool is the validator crate, which adds a #[derive(Validate)] macro and field attributes (length, email, range, custom, nested) that feel a lot like Zod’s schema methods. You then call .validate() and translate any ValidationErrors into a clean JSON response.

The current stable toolchain is Rust 1.96.0 on the latest stable edition (2024); cargo new selects it automatically. This page targets axum 0.8 and validator 0.20.

Note: Axum returns 422 Unprocessable Entity (not 400) when a JSON body has the right syntax but the wrong shape — e.g. a missing field. We follow the same convention for semantic validation failures, and reserve 400 Bad Request for malformed input (broken JSON, wrong Content-Type). Both are perfectly valid choices; pick one and be consistent.

TypeScript/JavaScript Example

A typical Express handler validates with Zod, then maps any error into a 400 with a per-field breakdown.

1
// Express.js + Zod
2
import express, { Request, Response } from "express";
3
import { z } from "zod";
4

5
const app = express();
6
app.use(express.json());
7

8
const CreateUser = z.object({
9
  name: z.string().min(2).max(50),
10
  email: z.string().email(),
11
  age: z.number().int().min(18).max(120),
12
  username: z.string().regex(/^[A-Za-z0-9_]+$/, "letters, numbers, underscores only"),
13
});
14

15
type CreateUser = z.infer<typeof CreateUser>;
16

17
app.post("/users", (req: Request, res: Response) => {
18
  const result = CreateUser.safeParse(req.body);
19

20
  if (!result.success) {
21
    // Map Zod issues into { field: [messages] }
22
    const details: Record<string, string[]> = {};
23
    for (const issue of result.error.issues) {
24
      const field = issue.path.join(".");
25
      (details[field] ??= []).push(issue.message);
26
    }
27
    return res.status(400).json({ error: "validation failed", details });
28
  }
29

30
  const user: CreateUser = result.data; // fully typed AND validated
31
  res.status(201).json({ name: user.name });
32
});
33

34
app.listen(3000);

Key points:

The schema is a runtime value; safeParse either returns typed data or an error you inspect.
z.infer derives the static TypeScript type from the schema, so the type and the runtime checks stay in sync.
You manually walk error.issues to build a client-friendly response. There is no single canonical shape — every team invents its own.

Rust Equivalent

The validator crate plays the role of Zod. You annotate the struct that your Json extractor already produces, then call .validate(). Here we wrap both steps in a custom ValidatedJson<T> extractor so handlers stay clean — the request never reaches the handler body unless it parsed and validated.

Add the dependencies in a new project:

1
cargo new user-api && cd user-api
2
cargo add axum
3
cargo add tokio --features full
4
cargo add serde --features derive
5
cargo add serde_json
6
cargo add validator --features derive

1
use std::collections::HashMap;
2

3
use axum::{
4
    extract::{rejection::JsonRejection, FromRequest, Request},
5
    http::StatusCode,
6
    response::{IntoResponse, Response},
7
    routing::post,
8
    Json, Router,
9
};
10
use serde::{de::DeserializeOwned, Deserialize, Serialize};
11
use serde_json::json;
12
use validator::{Validate, ValidationError, ValidationErrors};
13

14
#[derive(Debug, Deserialize, Validate)]
15
struct CreateUser {
16
    #[validate(length(min = 2, max = 50, message = "name must be 2-50 characters"))]
17
    name: String,
18

19
    #[validate(email(message = "must be a valid email address"))]
20
    email: String,
21

22
    #[validate(range(min = 18, max = 120, message = "age must be between 18 and 120"))]
23
    age: u8,
24

25
    #[validate(custom(function = "validate_username"))]
26
    username: String,
27
}
28

29
// A custom validator: takes &str, returns Result<(), ValidationError>.
30
fn validate_username(username: &str) -> Result<(), ValidationError> {
31
    if username.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') {
32
        Ok(())
33
    } else {
34
        let mut err = ValidationError::new("username_charset");
35
        err.message = Some("username may only contain letters, numbers, and underscores".into());
36
        Err(err)
37
    }
38
}
39

40
// The JSON shape we return on failure: { "error": ..., "details": { field: [msgs] } }
41
#[derive(Serialize)]
42
struct ValidationProblem {
43
    error: &'static str,
44
    details: HashMap<String, Vec<String>>,
45
}
46

47
fn to_problem(errors: &ValidationErrors) -> ValidationProblem {
48
    let mut details: HashMap<String, Vec<String>> = HashMap::new();
49
    for (field, errs) in errors.field_errors() {
50
        let messages = errs
51
            .iter()
52
            .map(|e| {
53
                // Prefer our human message; fall back to the machine code.
54
                e.message
55
                    .as_ref()
56
                    .map(|m| m.to_string())
57
                    .unwrap_or_else(|| e.code.to_string())
58
            })
59
            .collect();
60
        details.insert(field.to_string(), messages);
61
    }
62
    ValidationProblem { error: "validation failed", details }
63
}
64

65
// A reusable extractor: parse JSON, THEN validate, before the handler runs.
66
struct ValidatedJson<T>(T);
67

68
enum ApiError {
69
    JsonRejection(JsonRejection), // bad/missing JSON  -> 400/415/422 from axum
70
    Validation(ValidationErrors), // shape OK, rules broken -> 422
71
}
72

73
impl<T, S> FromRequest<S> for ValidatedJson<T>
74
where
75
    T: DeserializeOwned + Validate,
76
    S: Send + Sync,
77
{
78
    type Rejection = ApiError;
79

80
    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
81
        let Json(value) = Json::<T>::from_request(req, state)
82
            .await
83
            .map_err(ApiError::JsonRejection)?;
84
        value.validate().map_err(ApiError::Validation)?;
85
        Ok(ValidatedJson(value))
86
    }
87
}
88

89
impl IntoResponse for ApiError {
90
    fn into_response(self) -> Response {
91
        match self {
92
            ApiError::JsonRejection(rejection) => (
93
                rejection.status(), // axum picks 400 / 415 / 422 as appropriate
94
                Json(json!({ "error": rejection.body_text() })),
95
            )
96
                .into_response(),
97
            ApiError::Validation(errors) => {
98
                (StatusCode::UNPROCESSABLE_ENTITY, Json(to_problem(&errors))).into_response()
99
            }
100
        }
101
    }
102
}
103

104
// Handlers receive already-valid data. No validation noise here.
105
async fn create_user(ValidatedJson(user): ValidatedJson<CreateUser>) -> impl IntoResponse {
106
    (StatusCode::CREATED, Json(json!({ "name": user.name })))
107
}
108

109
fn app() -> Router {
110
    Router::new().route("/users", post(create_user))
111
}
112

113
#[tokio::main]
114
async fn main() {
115
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
116
        .await
117
        .unwrap();
118
    println!("listening on http://{}", listener.local_addr().unwrap());
119
    axum::serve(listener, app()).await.unwrap();
120
}

Sending an invalid body returns a real 422 with a per-field breakdown. Hitting the running server confirms it:

1
curl -s -i -X POST http://127.0.0.1:3000/users \
2
  -H 'content-type: application/json' \
3
  -d '{"name":"x","email":"nope","age":9,"username":"bad name!"}'

The verified response status and body (captured from an end-to-end request against the server above):

1
STATUS 422 Unprocessable Entity
2
{
3
  "details": {
4
    "age": [
5
      "age must be between 18 and 120"
6
    ],
7
    "email": [
8
      "must be a valid email address"
9
    ],
10
    "name": [
11
      "name must be 2-50 characters"
12
    ],
13
    "username": [
14
      "username may only contain letters, numbers, and underscores"
15
    ]
16
  },
17
  "error": "validation failed"
18
}

A valid body sails through to the handler:

1
STATUS 201 Created
2
{"name":"Ada Lovelace"}

Detailed Explanation

The attributes mirror Zod methods. Each #[validate(...)] declares one rule on one field:

validator attribute	Zod equivalent	Checks
`length(min = 2, max = 50)`	`.min(2).max(50)`	string/collection length
`email`	`.email()`	HTML5-style email shape
`range(min = 18, max = 120)`	`.int().min(18).max(120)`	numeric bounds
`url`	`.url()`	parseable URL
`must_match(other = "field")`	`.refine(...)`	two fields are equal
`contains(pattern = "x")`	`.includes("x")`	substring present
`custom(function = "fn")`	`.refine(fn, msg)`	arbitrary logic
`nested`	nested `z.object`	validates a child struct
`required`	non-optional field	`Option` is `Some`

#[validate(custom(function = "validate_username"))] points at a free function with the exact signature fn(&T) -> Result<(), ValidationError>. Returning Err(ValidationError::new("code")) records a failure; setting .message gives the client a human-readable string. This is where any rule the built-in attributes can’t express lives (checking a value against a database, cross-field math, format rules).

Warning: The custom-function syntax changed in newer validator releases. The current form is custom(function = "name"). The older custom = "name" no longer compiles — see Common Pitfalls.

value.validate() comes from the Validate trait that #[derive(Validate)] implements. It returns Result<(), ValidationErrors>. On success you have a value you know is valid; on failure you get a structured ValidationErrors.

errors.field_errors() returns a map of field name to a slice of ValidationError. Each ValidationError carries a machine code ("length", "email", "range", or your custom code) and an optional human message. We prefer the message and fall back to the code, then collect into { field: [messages] } — exactly the shape the Zod example produced. Standardizing this in one to_problem helper means every endpoint returns identical-looking errors.

The ValidatedJson<T> extractor is the real payoff. By implementing FromRequest for it, we run parse-then-validate before the handler. A handler signature of ValidatedJson(user): ValidatedJson<CreateUser> is a compile-time promise that user is valid — the type system carries the guarantee, so handler bodies never re-check. This is closer to what Zod gives TypeScript than scattered if statements, and it composes with every route.

JsonRejection vs ValidationErrors. These are two genuinely different failure modes. JsonRejection fires when the bytes are not valid JSON, a required field is missing, a field has the wrong type, or the Content-Type header is wrong — Axum already produced a sensible status (400, 415, or 422) and message, so we forward rejection.status() and rejection.body_text(). ValidationErrors fires only after a successful parse, so it is always our 422.

Key Differences

Concept	TypeScript (Zod)	Rust (validator)
Schema location	A runtime value (`z.object({...})`)	Attributes on a compile-time `struct`
Type ↔ rules sync	`z.infer` derives the type from the schema	The struct is the type; attributes annotate it
Run validation	`schema.safeParse(data)`	`data.validate()`
Result on failure	`error.issues[]`	`ValidationErrors` (map of field -> errors)
Custom rule	`.refine(fn, msg)`	`fn(&T) -> Result<(), ValidationError>`
Where it runs	Middleware or top of handler	A reusable `FromRequest` extractor
Default failure status	Whatever you write (often 400)	You choose; 422 is idiomatic for shape/semantic errors

The schema is the type, not a separate object. In Zod the schema is a value you can compose, pass around, and .partial(). In Rust the struct is the source of truth and validation rules are attributes baked onto it at compile time. You cannot build a validator dynamically at runtime the way you compose Zod schemas — but you also cannot accidentally let the type and the rules drift apart, because there is only one declaration.

Validation is opt-in and explicit. Deriving Validate does nothing on its own; something must call .validate(). There is no “this struct is automatically validated whenever it’s deserialized.” The ValidatedJson<T> extractor is how you make that automatic at the boundary — a deliberate seam, unlike a Zod schema that only validates where you remember to call it.

Parsing and validating are separate phases. Serde gives you a well-typed value or a parse error; validator then judges that value. In Zod both happen in one safeParse call. Keeping them separate is why a malformed body and a business-rule violation can return different statuses with almost no extra code.

Common Pitfalls

Using the old `custom = "..."` syntax

Older tutorials and validator versions used #[validate(custom = "fn_name")]. In validator 0.20 that is a hard compile error. This snippet does not compile:

1
use serde::Deserialize;
2
use validator::{Validate, ValidationError};
3

4
#[derive(Deserialize, Validate)]
5
struct Form {
6
    #[validate(custom = "validate_username")] // does not compile (Unexpected type `string`)
7
    username: String,
8
}
9

10
fn validate_username(_: &str) -> Result<(), ValidationError> { Ok(()) }
11
fn main() {}

The real compiler error is:

1
error: Unexpected type `string`
2
 --> src/main.rs:6:25
3
  |
4
6 |     #[validate(custom = "validate_username")]
5
  |                         ^^^^^^^^^^^^^^^^^^^^

Use custom(function = "validate_username") instead. The function name is still a string literal, but it must sit inside function = ....

Deriving `Validate` but never calling `.validate()`

1
#[derive(serde::Deserialize, validator::Validate)]
2
struct CreateUser {
3
    #[validate(email)]
4
    email: String,
5
}
6

7
// A plain `Json<CreateUser>` parses but is NEVER validated:
8
async fn handler(axum::Json(_user): axum::Json<CreateUser>) {
9
    // `email` could be "not-an-email" here. The derive did nothing on its own.
10
}

This compiles and runs, accepting invalid emails. The derive only generates a validate method — nothing calls it for you. Use a ValidatedJson<T> extractor (as above) or call user.validate()? at the top of the handler. There is no runtime warning; the bug is silent, which is exactly why the extractor pattern is worth the boilerplate.

Returning the raw `ValidationErrors` debug output to clients

ValidationErrors implements Serialize, so it is tempting to do Json(errors). But its serialized form leaks internal code/params details and, for nested structs, a deeply nested object that is awkward to consume:

1
{
2
  "quantity": [
3
    {
4
      "code": "range",
5
      "message": "quantity must be at least 1",
6
      "params": { "min": 1, "value": 0 }
7
    }
8
  ],
9
  "shipping": {
10
    "country": [
11
      {
12
        "code": "length",
13
        "message": "country must be a 2-letter code",
14
        "params": { "value": "USA", "equal": 2 }
15
      }
16
    ]
17
  }
18
}

(That output is real — it comes from serializing a ValidationErrors for a struct using #[validate(nested)].) It exposes implementation details and an unstable shape. Map it through a small DTO like ValidationProblem so the client contract is yours, not the crate’s.

Confusing a parse failure with a validation failure

A request like {"name":"Ada Lovelace","email":"ada@example.com"} (missing age) never reaches .validate() — serde rejects it first. Against the server above it returns:

1
STATUS 422 Unprocessable Entity
2
{"error":"Failed to deserialize the JSON body into the target type: missing field `age` at line 1 column 49"}

And a request with no JSON Content-Type is rejected even earlier:

1
STATUS 415 Unsupported Media Type
2
{"error":"Expected request with `Content-Type: application/json`"}

If you only handle ValidationErrors, these cases fall through to a generic 500. Handle the JsonRejection arm too (the ApiError enum above does), or wire a centralized error type — see error-handling-web.md.

Forgetting `#[validate(nested)]` on a child struct

If Order contains shipping: Address and you omit #[validate(nested)] on that field, order.validate() checks the Order’s own fields but silently skips the Address. It compiles and passes invalid children. Always annotate sub-structs you want recursively validated.

Best Practices

Validate at the boundary, once. A single ValidatedJson<T> (or ValidatedQuery<T>) extractor means handlers receive types that are provably valid. Don’t re-validate deeper in the call stack.
Own your error contract. Map ValidationErrors into a stable DTO ({ "error": ..., "details": { field: [msg] } }). Document it. Clients and your frontend depend on its shape far more than on any single endpoint.
Write helpful messages. A bare code like "length" tells the user nothing. "name must be 2-50 characters" does. Set message = "..." on every attribute, and on custom errors.
Pick a status and stick to it. 422 Unprocessable Entity for semantic/shape failures, 400 Bad Request for malformed input, 415 Unsupported Media Type for the wrong content type. Consistency beats cleverness.
Reach for the validator crate before hand-rolling. Manual if checks (shown below) are fine for one or two fields, but they don’t compose, don’t standardize messages, and grow into a swamp. Use validator for anything beyond trivial.
Keep custom validators pure and synchronous. validator’s custom functions are not async and shouldn’t touch a database. Do async checks (uniqueness, existence) in the handler after structural validation passes — see json-apis.md and Database.
Trim/normalize before validating when needed (e.g. lowercasing an email) so " Ada@Example.com " and "ada@example.com" are treated the same.

When manual validation is enough

For a tiny payload you don’t need a crate at all — a function returning Result<(), Vec<String>> keeps full control:

1
use axum::{http::StatusCode, response::{IntoResponse, Response}, Json};
2
use serde::Deserialize;
3
use serde_json::json;
4

5
#[derive(Deserialize)]
6
struct Signup {
7
    email: String,
8
    password: String,
9
}
10

11
fn validate_signup(input: &Signup) -> Result<(), Vec<String>> {
12
    let mut errors = Vec::new();
13
    if !input.email.contains('@') {
14
        errors.push("email must contain @".to_string());
15
    }
16
    if input.password.len() < 8 {
17
        errors.push("password must be at least 8 characters".to_string());
18
    }
19
    if errors.is_empty() { Ok(()) } else { Err(errors) }
20
}
21

22
async fn signup(Json(input): Json<Signup>) -> Response {
23
    match validate_signup(&input) {
24
        Ok(()) => (StatusCode::CREATED, Json(json!({ "ok": true }))).into_response(),
25
        Err(errors) => (
26
            StatusCode::UNPROCESSABLE_ENTITY,
27
            Json(json!({ "error": "validation failed", "details": errors })),
28
        )
29
            .into_response(),
30
    }
31
}

Tip: Collect all errors and return them together (as above), rather than bailing on the first one. Returning one error at a time forces the client into a frustrating round-trip-per-mistake loop; both Zod and the validator crate return the full set by default.

Real-World Example

A registration endpoint with realistic rules: name length, a valid email, a password of at least 8 characters that must match a confirmation field, and a custom check that the username has an allowed charset. It uses the ValidatedJson<T> extractor so the handler body is pure business logic.

1
use std::collections::HashMap;
2

3
use axum::{
4
    extract::{rejection::JsonRejection, FromRequest, Request},
5
    http::StatusCode,
6
    response::{IntoResponse, Response},
7
    routing::post,
8
    Json, Router,
9
};
10
use serde::{de::DeserializeOwned, Deserialize, Serialize};
11
use serde_json::json;
12
use validator::{Validate, ValidationError, ValidationErrors};
13

14
#[derive(Debug, Deserialize, Validate)]
15
struct Register {
16
    #[validate(length(min = 2, max = 50, message = "name must be 2-50 characters"))]
17
    name: String,
18

19
    #[validate(email(message = "must be a valid email address"))]
20
    email: String,
21

22
    #[validate(custom(function = "validate_username"))]
23
    username: String,
24

25
    #[validate(length(min = 8, message = "password must be at least 8 characters"))]
26
    password: String,
27

28
    #[validate(must_match(other = "password", message = "passwords do not match"))]
29
    password_confirm: String,
30
}
31

32
fn validate_username(username: &str) -> Result<(), ValidationError> {
33
    let ok = !username.is_empty()
34
        && username.chars().all(|c| c.is_ascii_alphanumeric() || c == '_');
35
    if ok {
36
        Ok(())
37
    } else {
38
        let mut err = ValidationError::new("username_charset");
39
        err.message = Some("username may only contain letters, numbers, and underscores".into());
40
        Err(err)
41
    }
42
}
43

44
#[derive(Serialize)]
45
struct ValidationProblem {
46
    error: &'static str,
47
    details: HashMap<String, Vec<String>>,
48
}
49

50
fn to_problem(errors: &ValidationErrors) -> ValidationProblem {
51
    let mut details: HashMap<String, Vec<String>> = HashMap::new();
52
    for (field, errs) in errors.field_errors() {
53
        let messages = errs
54
            .iter()
55
            .map(|e| {
56
                e.message
57
                    .as_ref()
58
                    .map(|m| m.to_string())
59
                    .unwrap_or_else(|| e.code.to_string())
60
            })
61
            .collect();
62
        details.insert(field.to_string(), messages);
63
    }
64
    ValidationProblem { error: "validation failed", details }
65
}
66

67
struct ValidatedJson<T>(T);
68

69
enum ApiError {
70
    JsonRejection(JsonRejection),
71
    Validation(ValidationErrors),
72
}
73

74
impl<T, S> FromRequest<S> for ValidatedJson<T>
75
where
76
    T: DeserializeOwned + Validate,
77
    S: Send + Sync,
78
{
79
    type Rejection = ApiError;
80

81
    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
82
        let Json(value) = Json::<T>::from_request(req, state)
83
            .await
84
            .map_err(ApiError::JsonRejection)?;
85
        value.validate().map_err(ApiError::Validation)?;
86
        Ok(ValidatedJson(value))
87
    }
88
}
89

90
impl IntoResponse for ApiError {
91
    fn into_response(self) -> Response {
92
        match self {
93
            ApiError::JsonRejection(rejection) => (
94
                rejection.status(),
95
                Json(json!({ "error": rejection.body_text() })),
96
            )
97
                .into_response(),
98
            ApiError::Validation(errors) => {
99
                (StatusCode::UNPROCESSABLE_ENTITY, Json(to_problem(&errors))).into_response()
100
            }
101
        }
102
    }
103
}
104

105
async fn register(ValidatedJson(input): ValidatedJson<Register>) -> impl IntoResponse {
106
    // Reached only when every rule passed. In a real app, async checks
107
    // (is the email already taken?) and the INSERT happen here.
108
    (
109
        StatusCode::CREATED,
110
        Json(json!({ "username": input.username, "email": input.email })),
111
    )
112
}
113

114
fn app() -> Router {
115
    Router::new().route("/register", post(register))
116
}
117

118
#[tokio::main]
119
async fn main() {
120
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
121
        .await
122
        .unwrap();
123
    println!("listening on http://{}", listener.local_addr().unwrap());
124
    axum::serve(listener, app()).await.unwrap();
125
}

A mismatched-password request:

1
curl -s -X POST http://127.0.0.1:3000/register \
2
  -H 'content-type: application/json' \
3
  -d '{"name":"Ada","email":"ada@example.com","username":"ada_l","password":"hunter22","password_confirm":"hunter99"}'

returns 422 with {"error":"validation failed","details":{"password_confirm":["passwords do not match"]}}, while a fully-valid body returns 201 with the created user. The handler itself contains zero validation code — that is the goal.

Note: must_match compares password_confirm against password, and the failure is reported on password_confirm. Order your fields so the confirmation comes after the original.

Exercises

Exercise 1: Validate a query string

Difficulty: Beginner

Objective: Apply #[derive(Validate)] to a pagination struct and reject out-of-range values.

Instructions: Define a Pagination { page: u32, per_page: u32 } struct. Require page >= 1 and per_page between 1 and 100 using range. Write a function check(p: &Pagination) -> Result<(), validator::ValidationErrors> that validates it. Test it against { page: 0, per_page: 500 } and confirm both fields fail.

Solution

1
use validator::{Validate, ValidationErrors};
2

3
#[derive(Debug, Validate)]
4
struct Pagination {
5
    #[validate(range(min = 1, message = "page must be at least 1"))]
6
    page: u32,
7
    #[validate(range(min = 1, max = 100, message = "per_page must be 1-100"))]
8
    per_page: u32,
9
}
10

11
fn check(p: &Pagination) -> Result<(), ValidationErrors> {
12
    p.validate()
13
}
14

15
fn main() {
16
    let bad = Pagination { page: 0, per_page: 500 };
17
    match check(&bad) {
18
        Ok(()) => println!("valid"),
19
        Err(e) => {
20
            for (field, errs) in e.field_errors() {
21
                for err in errs {
22
                    let msg = err
23
                        .message
24
                        .as_ref()
25
                        .map(|m| m.to_string())
26
                        .unwrap_or_else(|| err.code.to_string());
27
                    println!("{field}: {msg}");
28
                }
29
            }
30
        }
31
    }
32
}

Running it prints (field order may vary):

1
page: page must be at least 1
2
per_page: per_page must be 1-100

Exercise 2: A custom cross-field validator

Difficulty: Intermediate

Objective: Use a struct-level custom validator to enforce a rule spanning two fields.

Instructions: Define a DateRange { start: u32, end: u32 } (days since epoch, say). The built-in attributes can’t express “end must be after start”, so write a struct-level validator. Apply #[validate(schema(function = "validate_range"))] to the struct and implement validate_range(value: &DateRange) -> Result<(), ValidationError>. Reject { start: 10, end: 5 }.

Solution

1
use validator::{Validate, ValidationError};
2

3
#[derive(Debug, Validate)]
4
#[validate(schema(function = "validate_range"))]
5
struct DateRange {
6
    start: u32,
7
    end: u32,
8
}
9

10
fn validate_range(range: &DateRange) -> Result<(), ValidationError> {
11
    if range.end > range.start {
12
        Ok(())
13
    } else {
14
        let mut err = ValidationError::new("date_order");
15
        err.message = Some("end must be after start".into());
16
        Err(err)
17
    }
18
}
19

20
fn main() {
21
    let bad = DateRange { start: 10, end: 5 };
22
    match bad.validate() {
23
        Ok(()) => println!("valid"),
24
        Err(e) => println!("invalid: {e}"),
25
    }
26

27
    let good = DateRange { start: 5, end: 10 };
28
    println!("good is_ok: {}", good.validate().is_ok());
29
}

Running it prints:

1
invalid: __all__: end must be after start
2
good is_ok: true

Struct-level errors are recorded under the special __all__ key; map that to a top-level message in your API response rather than to a single field.

Exercise 3: A `ValidatedJson<T>` extractor with a clean error body

Difficulty: Advanced

Objective: Build the reusable extractor end-to-end and prove it returns a 422 with a per-field map.

Instructions: Define ValidatedJson<T> implementing FromRequest (parse with Json::<T>::from_request, then .validate()). On a ValidationErrors, respond 422 with body { "error": "validation failed", "details": { field: [messages] } }; on a JsonRejection, forward its status and text. Wire it to a POST /products route taking a Product { name (1-100 chars), price (range 1..=1_000_000) }, run the server, and POST an invalid product to confirm the response.

Solution

Dependencies: cargo add axum tokio --features tokio/full, then cargo add serde --features derive, cargo add serde_json, cargo add validator --features derive.

1
use std::collections::HashMap;
2

3
use axum::{
4
    extract::{rejection::JsonRejection, FromRequest, Request},
5
    http::StatusCode,
6
    response::{IntoResponse, Response},
7
    routing::post,
8
    Json, Router,
9
};
10
use serde::{de::DeserializeOwned, Deserialize, Serialize};
11
use serde_json::json;
12
use validator::{Validate, ValidationErrors};
13

14
#[derive(Debug, Deserialize, Validate)]
15
struct Product {
16
    #[validate(length(min = 1, max = 100, message = "name must be 1-100 characters"))]
17
    name: String,
18
    #[validate(range(min = 1, max = 1_000_000, message = "price must be 1-1000000"))]
19
    price: u32,
20
}
21

22
#[derive(Serialize)]
23
struct ValidationProblem {
24
    error: &'static str,
25
    details: HashMap<String, Vec<String>>,
26
}
27

28
fn to_problem(errors: &ValidationErrors) -> ValidationProblem {
29
    let mut details = HashMap::new();
30
    for (field, errs) in errors.field_errors() {
31
        let messages = errs
32
            .iter()
33
            .map(|e| {
34
                e.message
35
                    .as_ref()
36
                    .map(|m| m.to_string())
37
                    .unwrap_or_else(|| e.code.to_string())
38
            })
39
            .collect();
40
        details.insert(field.to_string(), messages);
41
    }
42
    ValidationProblem { error: "validation failed", details }
43
}
44

45
struct ValidatedJson<T>(T);
46

47
enum ApiError {
48
    JsonRejection(JsonRejection),
49
    Validation(ValidationErrors),
50
}
51

52
impl<T, S> FromRequest<S> for ValidatedJson<T>
53
where
54
    T: DeserializeOwned + Validate,
55
    S: Send + Sync,
56
{
57
    type Rejection = ApiError;
58

59
    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
60
        let Json(value) = Json::<T>::from_request(req, state)
61
            .await
62
            .map_err(ApiError::JsonRejection)?;
63
        value.validate().map_err(ApiError::Validation)?;
64
        Ok(ValidatedJson(value))
65
    }
66
}
67

68
impl IntoResponse for ApiError {
69
    fn into_response(self) -> Response {
70
        match self {
71
            ApiError::JsonRejection(r) => {
72
                (r.status(), Json(json!({ "error": r.body_text() }))).into_response()
73
            }
74
            ApiError::Validation(errors) => {
75
                (StatusCode::UNPROCESSABLE_ENTITY, Json(to_problem(&errors))).into_response()
76
            }
77
        }
78
    }
79
}
80

81
async fn create_product(ValidatedJson(p): ValidatedJson<Product>) -> impl IntoResponse {
82
    (StatusCode::CREATED, Json(json!({ "name": p.name, "price": p.price })))
83
}
84

85
#[tokio::main]
86
async fn main() {
87
    let app = Router::new().route("/products", post(create_product));
88
    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
89
        .await
90
        .unwrap();
91
    axum::serve(listener, app).await.unwrap();
92
}

Posting {"name":"","price":0}:

1
curl -s -i -X POST http://127.0.0.1:3000/products \
2
  -H 'content-type: application/json' -d '{"name":"","price":0}'

returns 422 Unprocessable Entity with {"error":"validation failed","details":{"name":["name must be 1-100 characters"],"price":["price must be 1-1000000"]}}, while a valid product returns 201 Created.

Request Validation

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Key Differences

Common Pitfalls

Using the old custom = "..." syntax

Deriving Validate but never calling .validate()

Returning the raw ValidationErrors debug output to clients

Confusing a parse failure with a validation failure

Forgetting #[validate(nested)] on a child struct

Best Practices

When manual validation is enough

Real-World Example

Further Reading

Exercises

Exercise 1: Validate a query string

Exercise 2: A custom cross-field validator

Exercise 3: A ValidatedJson<T> extractor with a clean error body

Using the old `custom = "..."` syntax

Deriving `Validate` but never calling `.validate()`

Returning the raw `ValidationErrors` debug output to clients

Forgetting `#[validate(nested)]` on a child struct

Exercise 3: A `ValidatedJson<T>` extractor with a clean error body