How to Fix PATCH Endpoint Validation and Mapping Failures in Java

by

Summary

An engineering team encountered a critical failure in a PATCH endpoint implementation where updating user profile details failed due to conflicting validation logic and object mapping strategies. The issue manifested in two stages: first, validation constraints (like @Pattern and @NotBlank) were triggering on null fields that were not intended to be updated, and second, attempting to solve this via Bean Validation Groups caused MapStruct to skip updating other fields to null due to its default NullValuePropertyMappingStrategy.

Root Cause

The failure stems from a fundamental misunderstanding of how Partial Updates (PATCH) interact with DTO Lifecycle and Validation Frameworks:

  • Validation Overreach: The custom validation handler was executing constraints on fields that were explicitly set to null by the JsonPatch application, ignoring the fact that a null in a PATCH request often represents “no change” or “explicitly unset” rather than an invalid input.
  • The “All-or-Nothing” Mapping Trap: To fix the validation, the team introduced Validation Groups. However, to prevent unwanted null-overwrites, they switched MapStruct to an IGNORE strategy. This created a secondary failure where legitimate requests to nullify a field (e.g., clearing a mobileNumber) were ignored by the mapper.
  • State Pollution: The workflow of mapping an existing entity to a DTO, applying a patch to that DTO, and then mapping it back to the entity creates a “dirty” object state that makes it difficult to distinguish between a field that is null because it wasn’t in the JSON and a field that is null because the user wants to clear it.

Why This Happens in Real Systems

In distributed systems and RESTful APIs, Partial Updates are notoriously difficult because of the Null vs. Undefined ambiguity.

  • JSON Ambiguity: Standard JSON does not easily distinguish between a key being absent {} and a key being present with a null value {"mobileNumber": null}.
  • Framework Defaults: Most Java frameworks (Hibernate Validator, MapStruct) are optimized for Full Updates (PUT). They assume that if a field is present in an object, it should be valid and it should be mapped.
  • DTO Reuse: Reusing the same DTO for POST (Create), PUT (Replace), and PATCH (Partial) leads to Constraint Leakage, where rules meant for creation interfere with the flexibility required for updates.

Real-World Impact

  • API Fragility: Developers cannot clear optional fields (like phone numbers or bios) because the mapper ignores null values.
  • Broken UX: Users receive cryptic “Password must contain a special character” errors when they are simply trying to update their display name, leading to high friction and support tickets.
  • Regression Risk: Implementing “hacks” in the service layer (like the if (password != null) conditional logic seen in the input) leads to Spaghetti Code that is hard to test and prone to security vulnerabilities.

Example or Code (if necessary and relevant)

@Mapper(componentModel = "spring", nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
public interface UserMapper {
    void updateExistingUser(UserRequest dto, @MappingTarget User entity);
}

How Senior Engineers Fix It

A senior engineer solves this by decoupling the Intent to Change from the Data Validation.

  1. Use JsonMergePatch or Optional Wrappers: Instead of a standard DTO, use a structure that tracks which fields were actually present in the payload.
  2. Separate DTOs by Intent: Do not use UserRequest for everything. Use a UserPatchRequest specifically designed for updates, where validation constraints are applied only to the fields being changed.
  3. Refined Mapping Strategy: Instead of a global IGNORE strategy, use MapStruct’s @Mapping(target = "...", nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.SET_TO_NULL) on specific fields that should be nullable, while keeping the default behavior for others.
  4. Validation at the Edge: Validate the incoming JsonPatch or the specific delta, rather than validating the entire state of the “patched” DTO against “Create” rules.

Why Juniors Miss It

  • Focusing on Symptoms, Not Systems: Juniors tend to fix the immediate error (e.g., “The password error is annoying, let’s add a validation group”) rather than questioning why the object state is invalid in the first place.
  • Tool Over-reliance: They rely on the default behavior of MapStruct and Spring Validation, assuming these tools are “smart” enough to understand the context of a PATCH request.
  • The “If-Else” Ladder: They attempt to solve complex state management problems with increasingly complex if-else blocks in the Service layer, which hides the underlying architectural flaw.

Leave a Comment