@Valid Annotation on Child Objects

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.