Custom Validators

Sometimes the built-in Bean Validation annotations like @NotNull, @Email, or @Size are not enough for your application’s specific rules. In such cases, you can create custom validators to enforce your own validation logic.

---

Why Custom Validators?

Spring Boot provides standard validations (@NotNull, @Email, @Size, etc.), but sometimes you need rules that don’t exist out-of-the-box, for example:

• Password strength check
• Validating a custom ID format
• Ensuring a number is prime

Custom validators allow you to define and enforce these rules in a reusable and centralized way.

---

How Custom Validators Work

Custom validators extend the built-in Bean Validation framework to enforce rules that are specific to your application. They are triggered automatically when you use @Valid or @Validated in your controller.

Step 1: Create a Custom Annotation

Define a new annotation for your validation rule and link it to a validator class using @Constraint.

Example: Username validation

import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.*;

@Documented
@Constraint(validatedBy = UsernameValidator.class)// Link to the validator class
@Target({ ElementType.METHOD, ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
public@interface ValidUsername {
    Stringmessage()default"Invalid username";// Default error message
    Class<?>[] groups()default {};// For validation groups
    Class<?extendsPayload>[] payload()default {};// Optional metadata
}

---

Step 2: Implement the Validator Class

The validator contains the logic to check whether a field is valid.

import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;

publicclassUsernameValidatorimplementsConstraintValidator<ValidUsername, String> {

@Override
publicvoidinitialize(ValidUsername constraintAnnotation) {
// Optional initialization logic
    }

@Override
publicbooleanisValid(String username, ConstraintValidatorContext context) {
if (username ==null)returnfalse;
// Example: username must be 5-15 letters only
return username.matches("^[a-zA-Z]{5,15}$");
    }
}

---

Step 3: Use the Custom Validator in a DTO

Apply your custom annotation to the field you want to validate.

import jakarta.validation.constraints.NotNull;

publicclassUserDTO {

@NotNull(message = "Username cannot be null")
@ValidUsername
private String username;

// getters and setters
}

---

Step 4: Trigger Validation in a Controller

When you use @Valid on a DTO in your controller method, Spring Boot automatically performs both standard and custom validations before the method executes.

import org.springframework.web.bind.annotation.*;
import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.http.HttpStatus;

@RestController
@RequestMapping("/users")
publicclassUserController {

@PostMapping
public ResponseEntity<String>createUser(@Valid@RequestBody UserDTO user) {
return ResponseEntity.status(HttpStatus.CREATED).body("User is valid!");
    }
}

If the username is invalid, Spring automatically responds with 400 Bad Request and the custom message "Invalid username".

---

Flow of Custom Validation

Here’s what happens internally:

1. Request comes to the controller.
2. @Valid triggers Spring Boot’s validation mechanism.
3. Bean Validation (Hibernate Validator) checks all annotations:
   • Standard (@NotNull, @Email, etc.)
   • Custom (@ValidUsername, @StrongPassword)
4. For custom validators:
   • The linked ConstraintValidator class’s isValid() method is called.
5. If valid: Controller method executes normally.
6. If invalid: Spring Boot returns 400 Bad Request with the custom error message.

---

Example: Password Strength Validator

We want to enforce the rule:

Password must contain at least 1 uppercase letter, 1 number, 1 special character, and be at least 8 characters long.

1. Create the Custom Annotation

import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.*;

@Documented
@Constraint(validatedBy = PasswordValidator.class)// Link to validator class
@Target({ ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
public@interface StrongPassword {
    Stringmessage()default"Password is too weak";// Default error message
    Class<?>[] groups()default {};// For validation groups
    Class<?extendsPayload>[] payload()default {};// Optional metadata
}

This annotation can now be used on any field in a DTO.

---

2. Implement the Validator Class

import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;

publicclassPasswordValidatorimplementsConstraintValidator<StrongPassword, String> {

@Override
publicbooleanisValid(String password, ConstraintValidatorContext context) {
if (password ==null)returnfalse;

// Password rules:
// At least 1 uppercase, 1 number, 1 special character, min 8 characters
Stringregex="^(?=.*[A-Z])(?=.*\\\\d)(?=.*[@$!%*?&]).{8,}$";

return password.matches(regex);
    }
}

Optional: You can customize initialize() if you want to pass dynamic rules (like minimum length) from the annotation.

---

3. Apply the Annotation in a DTO

import jakarta.validation.constraints.NotBlank;

publicclassUserDTO {

@NotBlank(message = "Name is required")
private String name;

@StrongPassword
private String password;

// Getters and Setters
}

---

4. Trigger Validation in a Controller

import org.springframework.web.bind.annotation.*;
import jakarta.validation.Valid;
import org.springframework.http.ResponseEntity;
import org.springframework.http.HttpStatus;

@RestController
@RequestMapping("/users")
publicclassUserController {

@PostMapping("/register")
public ResponseEntity<String>registerUser(@Valid@RequestBody UserDTO user) {
return ResponseEntity.status(HttpStatus.CREATED).body("User registered successfully!");
    }
}

If the password doesn’t meet the strength requirements, Spring automatically returns a 400 Bad Request with the message "Password is too weak".

---

5. Example Requests

Valid password:

{
"name":"Alice",
"password":"Strong@123"
}

Response:

201 Created - User registered successfully!

Invalid password:

{
"name":"Bob",
"password":"weakpass"
}

Response:

400 Bad Request - Password is too weak

---

Benefits of Custom Validators

• Enforce complex business rules not covered by standard annotations.
• Reusable across multiple DTOs or entities.
• Works seamlessly with @Valid or @Validated in controllers.
• Improves code maintainability by centralizing validation logic.

---

Best Practices for Custom Validators

1. Reuse Validators

• Create validators for rules that are used across multiple fields or DTOs.
• This ensures consistency and reduces duplicate code.

2. Custom Messages with Parameters

• Make error messages dynamic by adding parameters to your annotation.
• Example:

public@interface ValidUsername {
    Stringmessage()default"Username must be between {min} and {max} characters";
intmin()default5;
intmax()default15;
    Class<?>[] groups()default {};
    Class<?extendsPayload>[] payload()default {};
}

3. Combine with Standard Annotations

• Use your custom validator alongside built-in annotations for comprehensive validation.
• Example:

@NotNull(message = "Username cannot be null")
@ValidUsername
private String username;

4. Unit Test Validators Separately

• Always write unit tests for your custom validators independently of controllers.
• This ensures your validation logic works correctly and makes debugging easier.

---

Conclusion

Custom validators in Spring Boot let you enforce application-specific rules beyond standard annotations. By pairing a custom annotation with a validator class, you create reusable, centralized, and automatic validation. Integrated with @Valid or @Validated, invalid data is caught early, keeping your code clean, maintainable, and robust.