Partner – Moderne – NPI EA (cat=Spring Boot)
announcement - icon

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Course – Black Friday 2026 – NPI EA – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – before_post_content
announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

1. Introduction

In this tutorial, we’ll understand how to use @Valid annotation to validate objects and their nested child objects.

Validating incoming data can be straightforward when it is of a basic data type, such as an integer or string. However, it can be more difficult when the incoming information is an object, specifically an object graph. Luckily, @Valid annotation simplifies validating nested child objects.

2. What Is @Valid Annotation?

The @Valid annotation comes from the Jakarta Bean Validation specification and marks particular parameters for validation.

Usage of this annotation ensures that data passed to the method or stored in the field complies with specified validation rules. This helps us promote data integrity and consistency.

When used on the field or method of JavaBean it triggers all defined constraint checks. Some of the most used constraints from Bean Validation API are @NotNull, @NotBlank, @NotEmpty, @Size, @Email, @Pattern, etc.

3. How to Use @Valid Annotation on Child Object

First, we must determine the validation rules and apply the previously mentioned validation constraints to the fields.

Next, we define a class that represents a project and it contains a nested User object that we’ll decorate with the @Valid annotation:

public class User {

    @NotBlank(message = "User name must be present")
    @Size(min = 3, max = 50, message = "User name size not valid")
    private String name;

    @NotBlank(message = "User email must be present")
    @Email(message = "User email format is incorrect")
    private String email;

    // omitted constructors, getters and setters

}

public class Project {

    @NotBlank(message = "Project title must be present")
    @Size(min = 3, max = 20, message = "Project title size not valid")
    private String title;

    @Valid
    private User owner;

    // omitted constructors, getters and setters

}

After that, we’ll perform validation with the simple use of the validate() method on the Validator instance. Let’s ensure the child object is validated with a test:

@Test
public void whenInvalidProjectAndUser_thenAssertConstraintViolations() {
    Project project = new Project(null);
    project.setOwner(new User(null, "invalid-email"));

    List<String> messages = validate(project);

    assertEquals(3, messages.size());
    assertTrue(messages.contains("Project title must be present"));
    assertTrue(messages.contains("User name must be present"));
    assertTrue(messages.contains("User email format is incorrect"));
}

private List<String> validate(Project project) {
    return validator.validate(project)
      .stream()
      .map(ConstraintViolation::getMessage)
      .collect(Collectors.toList());
}

In addition, bean validation using @Valid annotation works perfectly with frameworks such as Spring and Jakarta EE. By using annotation on the method parameter of our controller class, we can perform validation before even entering the controller method, which is perfect for keeping our data consistent.

4. Understand the Object Graph Validation

Now that we’ve seen how to use @Valid, let’s understand better why it works this way. In situations where objects have other nested objects, we have to apply a mechanism known as Object Graph Validation.

This mechanism validates the full structure of related objects in an object graph. All children objects (and their children as well) annotated with @Valid are validated when their parent is. In other words, validation is applied recursively across the entire graph.

As a result of this graph traversal, we get ConstraintViolations as a collection that contains all combined validation violations from nested objects.

Because we validate each object in the graph recursively, we might have a problem with cycling references, where objects reference each other in a cycle. This could make us get stuck in infinite loops, constantly validating the same objects repeatedly.

Fortunately, Jakarta Bean Validation includes a concept of defining a validation path, which is described as the sequence of @Valid associations starting from the root object. The implementation keeps track of each instance it has already validated in the current path, starting from a root object. If the same instance appears multiple times in a given navigation path, the validation routine will ignore it, thus preventing infinite loops.

5. Annotation Usage on Child Objects

Now that we know how to use the @Valid annotation and how it works beneath the surface, let’s check out all the places we can use it. We’ll look at using @Valid on nested instances, collections, and type arguments in container objects.

5.1. Validate Nested Instance With @Valid

One way to validate the nested instances is to use the Field Access Strategy, the same way we validated the nested User object inside the Project in the previous example. Simply, we decorate the field with the @Valid annotation and that instance is added to the navigation path:

@Valid
private User owner;

Similarly, another way of validating nested instances is to use Property Access Strategy, which means we can put @Valid on the getter method accessing the state of a property that way:

@Valid
public User getOwner() {
    return owner;
}

5.2. Validate Iterables With @Valid

Collections, arrays, or any other implementations of java.lang.Iterebale interface are eligible for the @Valid annotation. If we annotate in this case, we’ll apply validation for each element of Iterable following the same rules.

It’s important to know that only values will be validated if a collection is an implementation of the java.util.Map interface. We must specifically annotate keys to trigger validation for them.

For example, let’s check out a Map that validates both the key and value:

private Map<@Valid User, @Valid Task> assignedTasks;

5.3. Using Annotation on Container Objects and Type Arguments

Applying annotation on container objects and type arguments is very similar, let’s first take a look at how to do it:

@Valid 
private List<Task> tasks;
    
private List<@Valid Task> tasks;

The first example shows us using annotation on a container, whereas the second one is on type argument directly. In this case, there is no difference, they both work as we expect them to. As a rule, we should avoid using it in both places because that could result in container elements being validated twice.

As we can see, using annotation in these cases is flexible, but they don’t always work in the way we want them to. In cases where we have nested generic containers, to validate the contents of a container we must apply annotation on the type reference of the inner container.

Let’s see an example where a List is nested inside a Map:

private Map<String, List<@Valid Task>> taskByType;

6. Conclusion

In this article, we learned what @Valid annotation is, how to use it to perform validation on child objects, and how Object Graph Validation works.

The @Valid annotation is a powerful tool we can use in different places to make sure things are validated as intended. It’s great because it automatically checks each validated object in the graph, making our job easier.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.
Partner – Moderne – NPI EA (tag=Refactoring)
announcement - icon

Modern Java teams move fast — but codebases don’t always keep up. Frameworks change, dependencies drift, and tech debt builds until it starts to drag on delivery. OpenRewrite was built to fix that: an open-source refactoring engine that automates repetitive code changes while keeping developer intent intact.

The monthly training series, led by the creators and maintainers of OpenRewrite at Moderne, walks through real-world migrations and modernization patterns. Whether you’re new to recipes or ready to write your own, you’ll learn practical ways to refactor safely and at scale.

If you’ve ever wished refactoring felt as natural — and as fast — as writing code, this is a good place to start.

Course – Black Friday 2026 – NPI EA – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

Course – Black Friday 2026 – NPI – main – after_post_content

announcement - icon

Yes, we're now running our Black Friday Sale. All Courses are 33% off until 1st December, 2026 at 17:00 Romania time:

>> EXPLORE ACCESS NOW

2 Comments
Oldest
Newest