Bean Validation: Annotations for Request Data

1. The "Why" and "How" of Bean Validation

Instead of manually checking data, we can use a standard set of annotations to declare rules on the fields of our classes. For example, we can state that a user's name must not be blank or that their age must be at least 18.

Spring Boot integrates seamlessly with the Jakarta Bean Validation API (formerly Java Bean Validation or JSR-380). The most common implementation of this API is Hibernate Validator, which Spring Boot uses by default.

To get started, we need to add one dependency to our pom.xml file.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

This starter dependency pulls in everything we need. The relationship between these components can be visualized like this:

2. Applying Validation Annotations

Let's see how to use these annotations. We'll apply them to a Data Transfer Object (DTO), which is a class designed specifically to carry data between the client and our API.

Imagine we have a CreateUserRequest DTO.

public class CreateUserRequest {
    private String username;
    private String password;
    private String email;
    private int age;
    // ...getters and setters...
}

Without validation, a client could send a request with a null username or an invalid email. Let's fix that.

The video below provides an excellent walkthrough of the most common validation annotations. We'll go through it in sections.

As you saw, adding @NotNull to a field is simple. But the key is adding @Valid in your controller:

@PostMapping("/users")
public void createUser(@Valid @RequestBody CreateUserRequest request) {
    // If validation fails, this code will not be reached.
    // Spring throws an exception before the method body executes.
    userService.createUser(request);
}

When Spring sees @Valid, it tells Hibernate Validator to inspect the CreateUserRequest object. If any validation rules are violated, Spring throws a MethodArgumentNotValidException and, by default, returns a 400 Bad Request response to the client.

Common Validation Annotations

The Bean Validation standard provides a rich set of annotations. Here is a quick reference table.

Now, let's watch the same video to see a live demonstration of these annotations.

To summarize the key distinctions:

• @NotNull: The value cannot be null.
• @NotEmpty: Used for strings or collections. Cannot be null and its size/length cannot be zero. An empty string "" is not allowed, but a string with only spaces " " is.
• @NotBlank: Only for strings. Cannot be null and the trimmed length must be greater than zero. This is often the most useful for string fields like username.

3. Creating User-Friendly Error Responses

When validation fails, Spring's default error response is functional but very verbose and not ideal for a production API. In the last lesson, you learned to create custom responses with ResponseEntity. We can combine that knowledge with an exception handler to format validation errors cleanly.

This is a preview of a topic we'll cover in-depth in the next lesson (Global Exception Handling), but it's essential for making validation practical.

By implementing an exception handler like the one in the video, you transform a messy default error into a clear and predictable response:

Default Error (Simplified):

{
    "timestamp": "...",
    "status": 400,
    "error": "Bad Request",
    "errors": [
        { "field": "password", "defaultMessage": "size must be between 8 and 20" },
        { "field": "email", "defaultMessage": "must be a well-formed email address" }
    ],
    "path": "/users"
}

Custom Error Response (from video):

{
    "password": "size must be between 8 and 20",
    "email": "must be a well-formed email address"
}

This custom response is much easier for a client application to parse and display to the user.

// private List<String> tags;

@NotNull(message = "Tags list cannot be null")
@Size(max = 5, message = "A product can have at most 5 tags")
private List<@NotBlank(message = "Tag cannot be blank") String> tags;

4. Validating Nested Objects and Collections

What if your DTO contains another object? For example, a CreateUserRequest might contain an Address object.

public class CreateUserRequest {
    @NotBlank
    private String username;
    
    // How do we validate the fields inside the Address object?
    private Address address; 
}

public class Address {
    @NotBlank
    private String street;
    @NotBlank
    private String city;
}

To make Spring validate the nested address object, you must mark it with @Valid.

public class CreateUserRequest {
    @NotBlank
    private String username;
    
    @Valid // Tells Spring to validate the fields inside the Address object
    @NotNull // Ensures the Address object itself isn't null
    private Address address; 
}

This "cascading" validation is essential for complex request bodies. The same principle applies to validating elements inside a collection, as you saw in the "Test your understanding!" exercise.

The video below also provides a clear example of validating a collection.

Conclusion

Congratulations! You've learned how to implement declarative, automated validation in your Spring Boot application. This approach significantly improves code quality by separating validation rules from your business logic, making your controllers cleaner and your API more robust.

Key Takeaways:

• Add the spring-boot-starter-validation dependency to enable Bean Validation.
• Apply validation annotations like @NotBlank, @Size, @Min, @Email, etc., directly to the fields of your DTOs.
• Use the @Valid annotation on @RequestBody parameters in your controller methods to trigger validation.
• Validation failures result in a MethodArgumentNotValidException, which Spring automatically maps to a 400 Bad Request HTTP status.
• You can create a custom, user-friendly error response by using @RestControllerAdvice and an @ExceptionHandler for MethodArgumentNotValidException.
• To validate nested objects or elements within a collection, use the @Valid annotation on the field.

What's Next?

In this lesson, we had a sneak peek at creating a custom exception handler specifically for validation errors. However, a real-world application needs to handle many other types of errors: resources not being found, business rule violations, security issues, and more.

In the next lesson, we will dive deep into this topic and learn how to implement global exception handling using @ControllerAdvice and @ExceptionHandler. You'll learn how to build a centralized, consistent error-handling strategy for your entire API, ensuring that clients always receive predictable and useful error responses, no matter what goes wrong.