Request Validation in Spring Boot

Never trust input that arrives over HTTP. Spring Boot integrates with Bean Validation (the Jakarta Validation specification, implemented by Hibernate Validator) so you can declare validation rules directly on a DTO's fields with annotations, and have Spring enforce them automatically before your controller method body even runs.

Enabling Validation and Common Annotations

Add spring-boot-starter-validation to your dependencies, then annotate DTO fields with constraint annotations from jakarta.validation.constraints.

• @NotNull — the value must not be null.
• @NotBlank — a String must not be null and must contain at least one non-whitespace character.
• @Size(min, max) — bounds the length of a String or the size of a collection.
• @Email — the String must be a well-formed email address.
• @Min / @Max — numeric lower/upper bounds.
• @Positive / @PositiveOrZero — numeric sign constraints.

Triggering Validation with @Valid

Adding @Valid before a @RequestBody parameter in a controller method tells Spring to run Bean Validation on the deserialized object before the method executes. If any constraint fails, Spring throws a MethodArgumentNotValidException and, by default, responds with HTTP 400 Bad Request and a body describing each failed field — before your business logic ever sees the invalid data.

Customizing the Validation Error Response

Spring Boot's default 400 response says almost nothing: {"timestamp":…,"status":400,"error":"Bad Request","path":"/api/users"}. It does not tell the client which field failed or why. Pairing @Valid with a @RestControllerAdvice that handles MethodArgumentNotValidException lets you return every field and its message in one consistent payload, so a form can highlight the right inputs.

Validating Nested Objects and Lists

Validation stops at the outer object unless you tell it to go deeper. Put @Valid on a field that holds another object, or on the element type of a list (List<@Valid OrderLine>), and each nested object is checked too. The error then names the exact path, such as lines[0].quantity. Add @NotEmpty on the list itself if an order with no lines should be rejected.

Validating Query and Path Parameters

Since Spring Framework 6.1, constraint annotations work directly on @RequestParam and @PathVariable parameters, for example @RequestParam @Min(1) @Max(100) int limit. You no longer need @Validated on the controller class for this. A failure raises HandlerMethodValidationException instead of MethodArgumentNotValidException, so a global handler needs a method for each.

Where Validation Belongs

• At the API edge with Bean Validation: required fields, lengths, formats and ranges. These are rules about the shape of one request.
• In the service layer: rules that need the database or other data, such as "this email is already registered" or "stock is too low". Throw a specific exception and map it to 409 or 422.
• In the database: NOT NULL, UNIQUE and foreign-key constraints as the last line of defence, because code paths other than your API (scripts, batch jobs, other services) can write data too.

Examples

public record CreateUserRequest(
    @NotBlank(message = "Name is required") String name,
    @Email(message = "Email must be valid") @NotBlank String email,
    @Size(min = 8, message = "Password must be at least 8 characters") String password
) {}

@RestController
@RequestMapping("/api/users")
public class UserController {

    @PostMapping
    public ResponseEntity<String> create(@Valid @RequestBody CreateUserRequest request) {
        return ResponseEntity.status(HttpStatus.CREATED).body("User created: " + request.name());
    }
}

// POST /api/users {"name":"", "email":"not-an-email", "password":"123"}

-> 400 Bad Request   (Spring Boot's default body, with no handler of your own)
{"timestamp":"2026-10-09T21:18:38.467Z","status":400,"error":"Bad Request","path":"/api/users"}

The controller method never runs. The next example shows how to tell the client which fields failed.

public record OrderLine(@NotBlank String sku, @Positive int quantity) {}

public record CreateOrderRequest(@NotEmpty List<@Valid OrderLine> lines) {}

@RestController
@RequestMapping("/api")
public class UserController {

    @PostMapping("/users")
    public ResponseEntity<String> create(@Valid @RequestBody CreateUserRequest request) {
        return ResponseEntity.status(HttpStatus.CREATED).body("User created: " + request.name());
    }

    @PostMapping("/orders")
    public String order(@Valid @RequestBody CreateOrderRequest request) {
        return "order with " + request.lines().size() + " lines";
    }

    @GetMapping("/users")
    public String list(@RequestParam @Min(1) @Max(100) int limit) {
        return "listing " + limit + " users";
    }
}

@RestControllerAdvice
public class ApiExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ProblemDetail handleInvalidBody(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new LinkedHashMap<>();
        for (FieldError error : ex.getBindingResult().getFieldErrors()) {
            errors.put(error.getField(), error.getDefaultMessage());
        }
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "Some fields are invalid");
        problem.setTitle("Validation failed");
        problem.setProperty("errors", errors);
        return problem;
    }

    @ExceptionHandler(HandlerMethodValidationException.class)
    public ProblemDetail handleInvalidParameter(HandlerMethodValidationException ex) {
        Map<String, String> errors = new LinkedHashMap<>();
        ex.getParameterValidationResults().forEach(result -> result.getResolvableErrors().forEach(error ->
                errors.put(result.getMethodParameter().getParameterName(), error.getDefaultMessage())));
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "Some parameters are invalid");
        problem.setTitle("Validation failed");
        problem.setProperty("errors", errors);
        return problem;
    }
}

POST /api/users {"name":"","email":"not-an-email","password":"123"}
-> 400 {"detail":"Some fields are invalid","instance":"/api/users","status":400,"title":"Validation failed",
        "errors":{"password":"Password must be at least 8 characters","email":"Email must be valid","name":"Name is required"}}

POST /api/orders {"lines":[{"sku":"A1","quantity":0}]}
-> 400 {..., "errors":{"lines[0].quantity":"must be greater than 0"}}

POST /api/orders {"lines":[]}
-> 400 {..., "errors":{"lines":"must not be empty"}}

GET /api/users?limit=500
-> 400 {"detail":"Some parameters are invalid", ..., "errors":{"limit":"must be less than or equal to 100"}}

(The order of fields inside "errors" can change between runs.)

Exercise

Using the lesson's Validating a request DTO with @Valid and Bean Validation annotations example, create a small implementation or design sketch that demonstrates Bean Validation annotations (@NotNull, @NotBlank, @Size, @Email, @Min/@Max) declare rules directly on DTO fields.. Add a test case or scenario that would catch Writing a handler only for MethodArgumentNotValidException. Constraint failures on @RequestParam and @PathVariable raise HandlerMethodValidationException instead, and fall back to the bare default 400., and describe the expected result.

Quick quiz

Interview questions