Validation of Property, method param and Return type

📚 Table of Contents

• 📚 Table of Contents
  • 🧩 Required Maven Dependency
  • 🔑 Rest API Validation: @Valid and Constraint Annotations
    • 1. Controller Implementation
    • 2. Bean (Model) Constraint Definition
      • Project Reference:
  • 💡 Validation Scope Insights
    • 1. Method Parameter Validation (Most Common)
    • 2. Property Validation (Demonstrated Above)
    • 3. Method Return Type Validation
    • 4. Property Validation (Cascading)
  • 🛠️ Validation Flow Diagram
• 🛑 Global Exception Handling for Validation Errors
  • 1. The Global Exception Handler Component
  • 2. Request and Response Examples
    • 📝 Example Client Request (Invalid Data)
    • 🖥️ Example Server Response (Handled by @ControllerAdvice)
  • 3. Error Handling Architecture
  • 🚀 Enhancements and Best Practices

🧩 Required Maven Dependency

To enable automatic validation support in Spring Boot REST controllers and service layers, you need the following starter dependency. It bundles the required validation API and implementation (like Hibernate Validator).

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

🔑 Rest API Validation: @Valid and Constraint Annotations

Validation in a Spring Boot REST API typically involves using the @Valid annotation on a method parameter to trigger validation on the request body (DTO/Bean).

1. Controller Implementation

The @Valid annotation on the @RequestBody parameter tells Spring to check the constraints (like @Size, @Past) defined inside the User class before executing the method logic. If validation fails, Spring throws a MethodArgumentNotValidException, which is typically handled globally by a Spring Boot application to return a 400 Bad Request error.

import jakarta.validation.Valid;
import org.springframework.web.bind.annotation.RestController;
// ... other imports ...

@RestController
public class UserController {

    // ... service and logger ...

    @PostMapping("/users")
    public ResponseEntity<User> createUser(@Valid @RequestBody User user) {

        logger.debug("User to save : {}", user);

        var savedUser = userDaoService.save(user);

        var location = ServletUriComponentsBuilder.fromCurrentRequest()
			.path("{id}")
			.buildAndExpand(savedUser.getId())
            .toUri();
        return ResponseEntity.created(location).body(savedUser);
    }
}

2. Bean (Model) Constraint Definition

The constraints themselves are defined within the User POJO using annotations from the jakarta.validation.constraints.* package.

import com.fasterxml.jackson.annotation.JsonFormat;
import jakarta.validation.constraints.Past;
import jakarta.validation.constraints.Size;
import java.time.LocalDate;

public class User {

    private Integer id;

    @Size(min = 3, max = 20, message = "Name must be more than 2 characters.")
    private String name;

    @Past(message = "Birth date should be in past.")
    @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
    private LocalDate birthDate;

    // constructors, setter-getters and other methods.
}

Project Reference:

• Property Validation POC

💡 Validation Scope Insights

The Jakarta Bean Validation API, leveraged by Spring, allows validation on different scopes: Property, Method Parameter, and Method Return Type.

1. Method Parameter Validation (Most Common)

• Use Case: Validating the body of a POST/PUT request (as demonstrated above), or a path/query parameter.
• Mechanism: Use @Valid on the @RequestBody or use constraint annotations directly on method parameters (e.g., @Min on a query parameter).

2. Property Validation (Demonstrated Above)

• Use Case: Defining constraints on the fields of a bean (DTO/Model).
• Mechanism: Direct use of constraint annotations (e.g., @Size, @NotNull, @Email) on fields within the class. This is the source of the rules.

3. Method Return Type Validation

• Use Case: Validating the object returned by a method. Useful for ensuring that data retrieved from a database or another service adheres to constraints before being sent to the client. Requires using @Validated at the class level.
• Limitation: Less common and can add performance overhead.

4. Property Validation (Cascading)

• Use Case: When a DTO/Model contains another DTO/Model, and you want to validate the constraints on the nested object as well.
• Mechanism: Place @Valid on the nested property within the parent class.

🛠️ Validation Flow Diagram

The following diagram illustrates the standard validation flow for a REST API call.

sequenceDiagram
    participant C as Client
    participant SB as Spring Boot App
    participant V as Validator (Jakarta)

    C->>SB: POST /users (Request Body)
    SB->>SB: Pre-check for @Valid on parameter
    alt Validation Required
        SB->>V: Validate User Object
        V->>V: Check @Size, @Past constraints
        alt Validation Fails
            V-->>SB: ConstraintViolations
            SB->>SB: Handle MethodArgumentNotValidException
            SB-->>C: 400 Bad Request (Error Details)
        else Validation Success
            V-->>SB: Validation Success
            SB->>SB: Execute Controller Method
            SB->>SB: Service Logic
            SB-->>C: 201 Created (User)
        end
    else No @Valid
        SB->>SB: Execute Controller Method
        SB->>SB: Service Logic
        SB-->>C: Success Response
    end

That’s an excellent next step! Implementing a Global Exception Handler is a professional standard for robust microservices. It ensures that user-facing validation errors are caught, aggregated, and returned in a consistent, user-friendly 400 Bad Request JSON format, instead of a generic server-side error page.

Here is the documentation for implementing the Global Exception Handler, formatted for your Jekyll website.

🛑 Global Exception Handling for Validation Errors

When a client sends an invalid request body to a Spring Boot controller annotated with @Valid, the framework throws a MethodArgumentNotValidException. We use a Global Exception Handler component (annotated with @ControllerAdvice) to intercept this exception and transform it into a clear, structured JSON response.

1. The Global Exception Handler Component

We define a class annotated with @ControllerAdvice to make it applicable across all controllers. The key method uses @ExceptionHandler(MethodArgumentNotValidException.class) to specifically handle validation failures.

• Key Action: Iterates through all field errors present in the exception object.
• Response Status: Uses @ResponseStatus(HttpStatus.BAD_REQUEST) to ensure the HTTP status code is correctly set to 400.
• Response Body: Formats the errors into a map, typically mapping the field name to the error message, which is highly readable by API consumers.

import java.util.HashMap;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;

@ControllerAdvice
public class CustomizedResponseEntityExceptionHandler {

    /**
     * Handles exceptions thrown when method argument validation fails (e.g., @Valid on @RequestBody).
     */
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Map<String, String> handleValidationExceptions(MethodArgumentNotValidException ex) {

        Map<String, String> errors = new HashMap<>();

        ex.getBindingResult().getFieldErrors().forEach(error -> {
            errors.put(error.getField(), error.getDefaultMessage());
        });

        // Add Global Errors if any (non-field specific)
        ex.getBindingResult().getGlobalErrors().forEach(error -> {
            errors.put(error.getObjectName(), error.getDefaultMessage());
        });

        return errors;
    }
}

2. Request and Response Examples

This handler ensures a clean, consistent response when the input fails the defined constraints.

📝 Example Client Request (Invalid Data)

If a client sends a request that violates the @Size and @Past constraints defined in the User bean:

{
    "name": "A",
    "birthDate": "2026-01-01"
}

🖥️ Example Server Response (Handled by @ControllerAdvice)

Instead of a bulky 500 error, the client receives a structured 400 Bad Request with specific field issues:

{
    "name": "Name must be more than 2 characters.",
    "birthDate": "Birth date should be in past."
}

3. Error Handling Architecture

This approach centralizes error handling, adhering to the Separation of Concerns principle. The controller focuses purely on business logic, and the advice component handles the cross-cutting concern of exception management.

sequenceDiagram
    participant C as Client
    participant Ctrl as Controller (@PostMapping)
    participant EH as ExceptionHandler (@ControllerAdvice)

    C->>Ctrl: Invalid POST Request (User DTO)
    Ctrl->>Ctrl: Validation Triggered by @Valid
    alt Validation Fails
        Ctrl->>EH: throws MethodArgumentNotValidException
        EH->>EH: @ExceptionHandler catches Exception
        EH->>EH: Extracts Field Errors
        EH-->>C: 400 Bad Request (JSON Error Map)
    else Validation Success
        Ctrl->>Ctrl: Business Logic Executes
        Ctrl-->>C: 201 Created
    end

Best Practice: For very complex microservices, you can introduce a custom Error DTO (Data Transfer Object) instead of a simple Map<String, String> to include more contextual information, such as a timestamp, a unique error code, and the request path.

Would you like to continue documenting other aspects of microservice development, such as Custom Validation Annotations or Integration Testing?

🚀 Enhancements and Best Practices

Note: Spring Boot internally uses the Hibernate Validator as the default implementation of the Jakarta Bean Validation API. This is why you primarily use annotations from jakarta.validation.constraints.*.