DTO validation macros in nestrs

nestrs DTO validation combines serde for deserialization with the validator crate for constraint checking. The #[dto] macro derives both automatically; ValidationPipe or ValidatedBody<T> runs the validation before your handler receives the data. Invalid payloads return 422 Unprocessable Entity with a structured error body.

`#[dto]`

Derives serde::Deserialize, validator::Validate, and NestDto on a struct. By default it also emits #[serde(deny_unknown_fields)] so any JSON key not in the struct definition causes a 400 Bad Request (deserialization fails inside the JSON extractor, before validation runs).

use nestrs::prelude::*;

#[dto]
struct CreateUserDto {
    #[IsEmail]
    email: String,

    #[Length(min = 3, max = 32)]
    username: String,

    #[IsOptional]
    #[IsInt]
    age: Option<i64>,
}

`#[dto(allow_unknown_fields)]`

Opts out of deny_unknown_fields. Use this when you intentionally accept JSON payloads from forward-compatible clients that may include extra fields.

#[dto(allow_unknown_fields)]
struct PartialUpdateDto {
    #[IsString]
    name: Option<String>,
}

Do not manually add #[serde(deny_unknown_fields)] to a struct that already uses #[dto]—the macro applies it by default and duplicating the attribute causes a compile error.

`NestDto` trait

NestDto is a marker trait generated by #[dto]. The validation extractors (ValidatedBody<T>, ValidatedQuery<T>, ValidatedPath<T>) and ValidationPipe do not require it — they accept any T that is DeserializeOwned (or Validate for the pipe), so hand-written structs work too. NestDto marks #[dto]-derived types for macros that require them, such as #[crud], which asserts at compile time that its generated DTOs came from #[dto].

pub trait NestDto {}

You do not implement NestDto manually; #[dto] handles it.

Using DTOs in handlers

ValidatedBody extractor
#[param::body] + ValidationPipe
ValidatedQuery extractor

use nestrs::prelude::*;

#[dto]
struct SignupDto {
    #[IsEmail]
    email: String,
}

#[routes(state = AppState)]
impl AuthController {
    #[post("/signup")]
    async fn signup(
        ValidatedBody(dto): ValidatedBody<SignupDto>,
    ) -> &'static str {
        let _ = dto;
        "created"
    }
}

use nestrs::prelude::*;

#[dto]
struct SignupDto {
    #[IsEmail]
    email: String,
}

#[routes(state = AppState)]
impl AuthController {
    #[post("/signup")]
    #[use_pipes(ValidationPipe)]
    async fn signup(#[param::body] dto: SignupDto) -> &'static str {
        let _ = dto;
        "created"
    }
}

use nestrs::prelude::*;

#[dto]
struct PaginationQuery {
    #[IsInt]
    #[Min(1)]
    page: i64,

    #[IsInt]
    #[Max(100)]
    limit: i64,
}

#[routes(state = AppState)]
impl ItemsController {
    #[get("/")]
    async fn list(
        ValidatedQuery(q): ValidatedQuery<PaginationQuery>,
    ) -> axum::Json<serde_json::Value> {
        axum::Json(serde_json::json!({ "page": q.page, "limit": q.limit }))
    }
}

Field validation attributes

All field attributes are applied inside a #[dto] struct. They expand to validator crate constraint annotations.

String constraints

attribute

Readability marker — string-ness is enforced by the Rust field type. On a String (or Option<String>) field it emits no validation code; on any other field type it is a compile-time error. Use #[IsNotEmpty] for a non-empty/presence check.

attribute

Validates that the field is a well-formed email address.

attribute

Validates that the field is a well-formed URL.

attribute

Validates string length. Both min and max are optional.

#[dto]
struct ProfileDto {
    #[IsEmail]
    email: String,

    #[IsUrl]
    website: String,

    #[Length(min = 1, max = 255)]
    bio: String,
}

Numeric constraints

attribute

Compile-checked: the field must be an integer type (i8–i128, u8–u128, isize, usize). Adds no runtime validation — the field type already guarantees it; a non-integer field is a compile-time error.

attribute

Compile-checked: the field must be a numeric type (integers, or f32/f64). Adds no runtime validation; a non-numeric field is a compile-time error.

attribute

Validates that the numeric field is greater than or equal to N.

attribute

Validates that the numeric field is less than or equal to N.

#[dto]
struct PriceDto {
    #[IsNumber]
    #[Min(0)]
    amount: f64,

    #[IsInt]
    #[Min(1)]
    #[Max(1000)]
    quantity: i64,
}

Boolean and optional

attribute

Compile-checked: the field must be a bool. Adds no runtime validation; a non-bool field is a compile-time error.

attribute

Stripped at compile time — optionality comes entirely from the field type. Wrap the field in Option<T> and a missing JSON key deserializes as None, skipping the field’s other validators. The attribute exists to document intent for readers coming from NestJS’s @IsOptional().

#[dto]
struct UpdateDto {
    #[IsOptional]
    #[IsString]
    name: Option<String>,

    #[IsOptional]
    #[IsBoolean]
    active: Option<bool>,
}

Nested DTOs

attribute

Runs validation recursively on a nested struct field. The nested type must also derive Validate (which #[dto] provides).

#[dto]
struct AddressDto {
    #[IsString]
    street: String,

    #[IsString]
    city: String,
}

#[dto]
struct OrderDto {
    #[IsString]
    product_id: String,

    #[ValidateNested]
    shipping_address: AddressDto,
}

Comprehensive example

The following DTO covers string, numeric, boolean, optional, and nested validation in a single type:

use nestrs::prelude::*;

#[dto]
struct ContactInfoDto {
    #[IsString]
    first_name: String,

    #[IsString]
    last_name: String,

    #[IsEmail]
    email: String,

    #[IsOptional]
    #[IsUrl]
    website: Option<String>,

    #[IsInt]
    #[Min(18)]
    #[Max(120)]
    age: i64,

    #[IsOptional]
    #[IsBoolean]
    newsletter: Option<bool>,
}

#[dto]
struct CreateContactDto {
    #[ValidateNested]
    contact: ContactInfoDto,

    #[IsOptional]
    #[Length(max = 500)]
    notes: Option<String>,
}

#[controller(prefix = "/contacts")]
struct ContactsController;

#[routes(state = AppState)]
impl ContactsController {
    #[post("/")]
    #[http_code(201)]
    async fn create(
        ValidatedBody(dto): ValidatedBody<CreateContactDto>,
    ) -> axum::Json<serde_json::Value> {
        axum::Json(serde_json::json!({ "created": true }))
    }
}

`deny_unknown_fields` default behavior

#[dto] applies #[serde(deny_unknown_fields)] by default. This means any JSON key in the request body that is not a field on the struct causes deserialization to fail with a 400 Bad Request before validation even runs.

// Request body — fails with 400 if `#[dto]` is used (no allow_unknown_fields)
{
  "email": "user@example.com",
  "unexpected_field": "value"
}

This is intentional and matches NestJS’s ValidationPipe behavior with whitelist: true, forbidNonWhitelisted: true (unknown keys are rejected, not silently stripped). Use #[dto(allow_unknown_fields)] when you need to accept extra fields from clients on a different schema version.

Application

Macros

Crates

DTO validation macros in nestrs

`#[dto]`

`#[dto(allow_unknown_fields)]`

`NestDto` trait

Using DTOs in handlers

Field validation attributes

String constraints

Numeric constraints

Boolean and optional

Nested DTOs

Comprehensive example

`deny_unknown_fields` default behavior

​#[dto]

​#[dto(allow_unknown_fields)]

​NestDto trait

​Using DTOs in handlers

​Field validation attributes

​String constraints

​Numeric constraints

​Boolean and optional

​Nested DTOs

​Comprehensive example

​deny_unknown_fields default behavior

`#[dto]`

`#[dto(allow_unknown_fields)]`

`NestDto` trait

Using DTOs in handlers

Field validation attributes

String constraints

Numeric constraints

Boolean and optional

Nested DTOs

Comprehensive example

`deny_unknown_fields` default behavior