Guide to Spring Boot Validation Annotations

Detailed Explanations and Practical Examples of Key Validation Annotations.

Spring Boot validation is a mechanism provided by the Spring Framework to ensure that incoming data adheres to specified constraints before it is processed by the application. This validation is typically used for user inputs in web forms, API requests, or any other form of data entry where certain rules must be followed. It integrates with Java Bean Validation (JSR 380) and the Hibernate Validator to provide annotations that allow you to define constraints directly on model attributes.

For example, by using annotations like @NotNull, @Size, and @Email, you can ensure that fields in an entity or DTO (Data Transfer Object) meet specific requirements such as being non-null, having a certain length, or being a valid email address.

Why is Spring Boot Validation Needed?

Data Integrity: It ensures that the data passed into your application is valid, preventing improper or incomplete data from being processed or stored.

For example, you can ensure that an email is in the correct format or that a required field is not left empty.

2. Error Prevention: Without validation, incorrect data can cause application errors, crashes, or unexpected behavior. Validating input before processing helps prevent these issues.

3. Security: Proper validation helps in protecting the application from attacks like SQL injection or malicious input that could compromise your system.

For example, by validating numeric fields or constraining text input to certain patterns, you minimize the risk of unexpected input causing security issues.

4. User Feedback: Validation provides immediate feedback to users when they submit invalid data, improving the user experience by letting them know exactly what needs to be corrected.

For instance, you can show a user that a field like “password” does not meet the length requirements or that an email address is incorrectly formatted.

5. Maintainability: By defining validation rules directly on the model or DTO class, you ensure that constraints are consistently applied across your application, making the code easier to maintain.

Example Scenario:

Imagine an API for creating an employee record. You want to ensure:

The employee’s name is not blank.
The email address is in a valid format.
The phone number is exactly 10 digits.
The salary must be a positive number.
The joining date must be in the future.

Without validation, incorrect or malicious data could be passed into the system, leading to potential errors, inconsistent data, or even security vulnerabilities. Spring Boot validation ensures that only properly formatted and complete data enters your application.

To create a complete example for the validation annotations in a Spring Boot Employee module, we can proceed by following these steps:

1. Set Up Spring Boot Project

In your pom.xml, add the following dependencies for Spring Boot and Hibernate Validator:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
        <groupId>org.hibernate.validator</groupId>
        <artifactId>hibernate-validator</artifactId>
    </dependency>
</dependencies>

2. Employee Model with Validation Annotations

Here’s the Employee class annotated with various validation annotations:

package com.example.demo.model;

import javax.validation.constraints.*;
import org.hibernate.validator.constraints.CreditCardNumber;
import org.hibernate.validator.constraints.Length;
import org.hibernate.validator.constraints.Range;
import org.hibernate.validator.constraints.URL;

public class Employee {

    @NotNull(message = "ID cannot be null")
    @Min(value = 1, message = "ID must be a positive number")
    private Long id;

    @NotBlank(message = "Name is mandatory")
    @Length(min = 3, max = 100, message = "Name must be between 3 and 100 characters")
    private String name;

    @NotEmpty(message = "Email cannot be empty")
    @Email(message = "Email should be valid")
    private String email;

    @Pattern(regexp = "^[0-9]{10}$", message = "Phone number must be 10 digits")
    private String phoneNumber;

    @Size(min = 8, message = "Password must be at least 8 characters")
    private String password;

    @AssertTrue(message = "Active must be true")
    private Boolean isActive;

    @Future(message = "Joining date must be in the future")
    private LocalDate joiningDate;

    @PastOrPresent(message = "Date of Birth must be in the past or present")
    private LocalDate dateOfBirth;

    @DecimalMin(value = "0.0", message = "Salary must be positive")
    @Digits(integer = 6, fraction = 2, message = "Salary must be a decimal value with up to 6 digits and 2 decimal places")
    private BigDecimal salary;

    @CreditCardNumber(message = "Credit card number is invalid")
    private String creditCardNumber;

    @URL(message = "Invalid URL format")
    private String website;

    @Range(min = 18, max = 65, message = "Age must be between 18 and 65")
    private int age;

    @Valid
    private Address address;  // Nested validation example

    // Getters and Setters
}

3. Address Class for Nested Validation

package com.example.demo.model;

import javax.validation.constraints.NotBlank;
import javax.validation.constraints.Pattern;

public class Address {

    @NotBlank(message = "Street cannot be blank")
    private String street;

    @NotBlank(message = "City cannot be blank")
    private String city;

    @Pattern(regexp = "^[0-9]{5}$", message = "Postal Code must be 5 digits")
    private String postalCode;

    // Getters and Setters
}

4. Controller to Handle Employee Requests

package com.example.demo.controller;

import com.example.demo.model.Employee;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;

@RestController
@RequestMapping("/employees")
@Validated
public class EmployeeController {

    @PostMapping
    public ResponseEntity<String> createEmployee(@Valid @RequestBody Employee employee) {
        // Business logic
        return new ResponseEntity<>("Employee created successfully", HttpStatus.CREATED);
    }
}

5. Testing with Postman

POST Request to http://localhost:8080/employees:

Valid Input Example:

{
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]",
    "phoneNumber": "1234567890",
    "password": "password123",
    "isActive": true,
    "joiningDate": "2024-12-31",
    "dateOfBirth": "1990-01-01",
    "salary": 5000.00,
    "creditCardNumber": "4111111111111111",
    "website": "http://example.com",
    "age": 30,
    "address": {
        "street": "123 Main St",
        "city": "Springfield",
        "postalCode": "12345"
    }
}

Response:

{
    "message": "Employee created successfully"
}

Invalid Input Example (With Errors):

{
    "id": null,
    "name": "Jo",
    "email": "invalid-email",
    "phoneNumber": "12345",
    "password": "pass",
    "isActive": false,
    "joiningDate": "2022-12-31",
    "dateOfBirth": "2030-01-01",
    "salary": -1000.00,
    "creditCardNumber": "1234567890123456",
    "website": "invalid-url",
    "age": 70,
    "address": {
        "street": "",
        "city": "Springfield",
        "postalCode": "12"
    }
}

Response:

{
    "errors": [
        "ID cannot be null",
        "Name must be between 3 and 100 characters",
        "Email should be valid",
        "Phone number must be 10 digits",
        "Password must be at least 8 characters",
        "Active must be true",
        "Joining date must be in the future",
        "Date of Birth must be in the past or present",
        "Salary must be positive",
        "Credit card number is invalid",
        "Invalid URL format",
        "Age must be between 18 and 65",
        "Street cannot be blank",
        "Postal Code must be 5 digits"
    ]
}

6. Run and Test

Start the Spring Boot application, and use Postman to test the API with various input cases to see validation in action.

This setup should cover the usage of all the requested annotations with a working example and Postman testing.

Here are the definitions and purposes of each validation annotation used in this Example.

1. @NotNull

Definition: Ensures that the annotated field is not null.
Purpose: Used when a field must have a value, but it can be empty or have zero length.
Example: Ensures that the id field in Employee is not null.

2. @NotEmpty

Definition: Ensures that the annotated field is not null and that the size/length of the field is greater than zero (for collections, arrays, or strings).
Purpose: Used to check that a field is neither null nor an empty string or collection.
Example: Ensures that the email field contains a value that is not empty.

3. @NotBlank

Definition: Ensures that the annotated string is not null, not empty, and contains at least one non-whitespace character.
Purpose: Used to ensure that a string field is not empty or blank (e.g., for names or text fields).
Example: Ensures that the name field contains meaningful text.

4. @Size

Definition: Validates that the size of a collection, array, map, or string is within the specified boundaries (inclusive).
Purpose: Used to enforce size constraints on collections or strings.
Example: Ensures that the password is at least 8 characters long.

5. @Min

Definition: Ensures that the annotated field is greater than or equal to the specified minimum value.
Purpose: Used for number fields to ensure a minimum value (typically integers).
Example: Ensures that id is a positive number greater than or equal to 1.

6. @Max

Definition: Ensures that the annotated field is less than or equal to the specified maximum value.
Purpose: Used to constrain number fields within a maximum boundary.
Example: Not used in this example, but would limit a number field (e.g., age) to a certain upper value.

7. @Pattern

Definition: Validates that the annotated string matches a regular expression pattern.
Purpose: Used to enforce formatting rules (e.g., phone numbers, postal codes, etc.).
Example: Ensures that the phoneNumber is exactly 10 digits.

8. @Email

Definition: Ensures that the annotated string is a valid email address.
Purpose: Used for validating email addresses in string fields.
Example: Ensures that the email is in a valid email format.

9. @Digits

Definition: Validates that the annotated number is within the specified integer and fraction limits.
Purpose: Used to control the number of digits allowed for integers and decimals.
Example: Ensures that the salary has up to 6 integer digits and 2 decimal places.

10. @Positive

Definition: Ensures that the annotated field is a positive number.
Purpose: Used when a field must have a value greater than zero.
Example: Ensures a number field (e.g., quantity, price) is positive.

11. @Negative

Definition: Ensures that the annotated field is a negative number.
Purpose: Used for fields where only negative numbers are valid.
Example: Ensures a field contains only negative values (e.g., for certain metrics).

12. @PositiveOrZero

Definition: Ensures that the annotated field is a positive number or zero.
Purpose: Used when a field should be non-negative.
Example: Ensures that a `balance` or `salary` field is either positive or zero.

13. @NegativeOrZero

Definition: Ensures that the annotated field is a negative number or zero.
Purpose: Used for fields where zero or negative numbers are valid.
Example: Used in specific cases like financial deductions or adjustments.

14. @Future

Definition: Ensures that the annotated date or time is in the future.
Purpose: Used for fields representing dates or times to validate that they are after the current date/time.
Example: Ensures that the joiningDate is a future date.

15. @FutureOrPresent

Definition: Ensures that the annotated date is either in the future or today (i.e., the current date).
Purpose: Used when a field can have the present or future date but not past.
Example: Would be used for fields like event start dates that must happen now or later.

16. @Past

Definition: Ensures that the annotated date is in the past.
Purpose: Used for fields like birthdates that should always be in the past.
Example: Ensures that the dateOfBirth is a past date.

17. @PastOrPresent

Definition: Ensures that the annotated date is either in the past or the present (not in the future).
Purpose: Used for dates that must be in the past or today.
Example: Ensures that the dateOfBirth is not a future date.

18. @AssertTrue

Definition: Validates that the annotated Boolean field is true.
Purpose: Used when a field must be true to be valid.
Example: Ensures that isActive is true (e.g., an employee must be active).

19. @AssertFalse

Definition: Validates that the annotated Boolean field is false.
Purpose: Used when a field must be false to be valid.
Example: Used when certain states or conditions must be false.

20. @DecimalMin

Definition: Ensures that the annotated field is greater than or equal to the specified minimum decimal value.
Purpose: Used to validate the minimum value for decimal fields.
Example: Ensures that salary is at least 0.0.

21. @DecimalMax

Definition: Ensures that the annotated field is less than or equal to the specified maximum decimal value.
Purpose: Used to validate the maximum value for decimal fields.
Example: Not used in this example but would limit a salary or price field to a maximum value.

22. @CreditCardNumber

Definition: Validates that the annotated string is a valid credit card number.
Purpose: Used for fields that require valid credit card numbers.
Example: Ensures that the creditCardNumber field contains a valid credit card format.

23. @Length (Hibernate Validator)

Definition: Validates that the annotated string’s length is between the specified min and max boundaries.
Purpose: Used to validate string length.
Example: Ensures that name is between 3 and 100 characters long.

24. @Range (Hibernate Validator)

Definition: Ensures that the annotated field is within the specified numeric range.
Purpose: Used for range-based validation on numeric fields.
Example: Ensures that the age is between 18 and 65.

25. @URL (Hibernate Validator)

Definition: Validates that the annotated string is a valid URL format.
Purpose: Used to validate URL fields.
Example: Ensures that website is a valid URL.

26. @Valid

Definition: Ensures that the nested object within the parent object is also validated.
Purpose: Used for validating nested objects.
Example: Validates the address field within the Employee object.

27. @Pattern.List

Definition: A container for multiple @Pattern annotations.
Purpose: Used when multiple regex patterns need to be validated on a single field.
Example: Not used in this example, but it would allow validating multiple patterns on a field.

👏 If you found my articles useful, please consider giving it claps and sharing it with your friends and colleagues.

To read other topics