ObjectMapper in 4.3.2 causes unintended validation failures on PATCH with input DTO

[Cafeine42]

API Platform version(s) affected: 4.3.2

Description
Since upgrading to API Platform 4.3.2, PATCH operations using a custom input DTO and a custom output DTO now fail validation on fields that were not sent by the client.
The root cause is that ObjectMapper::map() is now called to hydrate the input DTO from the existing entity before deserialization. This means all DTO properties get populated with the entity's current values, including properties that the client deliberately did not include in the PATCH payload.
Previously (4.3.1), unsent properties on the input DTO remained uninitialized, so validation constraints on those properties were naturally skipped (or passed, as the values were not set). Now, because ObjectMapper pre-fills them from the entity, validation runs against the entity's current state for every property — even those the user has no intention of modifying.
This is a breaking change for any endpoint that allows partial updates on an entity whose current state would not pass full validation on all fields.

How to reproduce

• Define an entity Foo with properties bar (valid) and baz (currently in a state that would fail validation, e.g. a legacy value).
• Create a PATCH operation with a dedicated input DTO (FooUpdateInput) that has validation constraints on both bar and baz.
• Send a PATCH request providing only bar.

Possible Solution

• Skip ObjectMapper hydration for input DTOs on PATCH operations, restoring the previous behavior where only deserialized (client-sent) properties are present on the DTO.
• Make ObjectMapper hydration opt-in for input DTOs via an operation attribute (e.g. mapInput: true, mapOutput).

[soyuka]

Linked to #7879 and #7745 now we need to find out what is the correct wanted behavior, I'm almost never using input/output I'm not sure what are the usages and why. Can you check the #7745 report as I don't see how I'd fix both issues.

[Cafeine42]

I think the solution proposed here — pre-filling the input DTO with the entity's current state — is actually the wrong direction. Here's why:

The whole point of a PATCH operation is partial update: the client sends only the fields they want to change. The input DTO should reflect exactly that intent. If we hydrate the DTO from the entity beforehand, we lose the ability to distinguish between "the client sent this value" and "this value was copied from the entity". This has concrete consequences:

1. ObjectMapper will overwrite entity properties it shouldn't touch. If all DTO properties are initialized (even with values copied from the entity), ObjectMapper has no way to know which ones actually came from the request. It will map everything back to the entity, including properties the client never intended to modify (With property hook, it could have unwanted behavior ?).

2. Validation breaks (my case). Pre-filled properties that the client didn't send will be validated against constraints that may not apply in this context, causing unexpected failures.

3. It contradicts the semantics of PATCH. RFC 5789 is clear: a PATCH request contains only the changes. The input DTO should be the representation of those changes — not a full snapshot of the current state.

The correct approach, in my opinion, is:

• Do NOT hydrate the input DTO on PATCH. Properties not sent by the client should remain uninitialized.
• ObjectMapper should skip uninitialized properties when mapping the DTO back to the entity. This naturally preserves the existing values in the entity for fields the client didn't touch, achieving a true partial update without any merge logic.

This keeps the flow simple and predictable:
Request body → Deserialize into DTO (only sent fields) → ObjectMapper maps only initialized properties to entity → Validation → Persist

No need for a "merge" step, no ambiguity about which values came from the client vs. the database.

Beware with the PUT because of standard_put options maybe.

[Cafeine42]

Following up on my previous comment — I'd argue the same logic applies to PUT as well. There's no reason to hydrate the input DTO from the entity on PUT either.

Per RFC 7231, PUT is a full replacement of the resource. The client sends the complete representation. So either:

• The client sends all properties → the DTO is already complete → hydration is redundant
• The client omits a property → it means they want it reset → hydration would contradict that intent

In both cases, hydrating from the entity is either useless or harmful.

One trade-off to be aware of: if we don't hydrate the input DTO on PATCH (or PUT), it means you can't share the same input DTO between POST and PATCH if your POST DTO has default values.

For example, if your CreateContact DTO sets $status = 'active' as a default, and you reuse it for PATCH, that default value would be treated as "client-sent" and mapped to the entity — even though the client didn't send it.

In practice, this means:

• Either you use separate input DTOs for POST and PATCH (the POST one can have defaults, the PATCH one leaves properties uninitialized)
• Or you rely on default values defined on the entity itself

This is a trade-off, but arguably a reasonable one. In practice, creation and partial update often end up needing different input DTOs regardless — required fields, validation constraints, and business rules tend to diverge enough that sharing the same DTO becomes awkward.

[Cafeine42]

I closed by mistake, reopening

[soyuka]

Indeed you're right I was quite mitigated with having input/output mixed with the object mapper. I think there's a misuse somewhere where either the serializer should handle them, or the ObjectMapper should transform them. But if we transform Input to Entity directly (when using stateoptions) it makes things weird. It should be Input => Resource then mapped to Entity. I'll revert shortly and try to have a proper documented approach, in the meantime please stay on 4.2.x.

[soyuka]

Warning

this is a claude generated comment but very interesting on the current state of things

Analysis: Input/Output and ObjectMapper are two solutions to the same problem

After investigating #7886, #7879 and #7745, here's a summary of the root cause and the proposed direction.

The Two Systems

Both input/output and ObjectMapper (map: true) solve the same problem — "my API representation differs from my persistence layer" — but at different levels:

	ObjectMapper (map: true)	Input/Output (serializer)
Read	Entity → Resource (automatic via #[Map])	Entity → OutputDto (serializer dispatches)
Write	Resource → Entity (automatic via #[Map])	InputDto → Entity (user's custom processor)
PATCH merge	Entity → Resource → merge JSON → Resource → Entity	User handles manually in custom provider/processor
DTO count	2 classes: Resource + Entity	3-4 classes: Resource + Input + Output + Entity

Using both together creates a double-transformation pipeline that is impossible to get right.

Why both directions fail when combining input/output + ObjectMapper

After PR #7879 (current state — causes #7886):

Entity → ObjectMapperProvider maps to InputDto (ALL properties pre-filled from entity)
       → DeserializeProvider sets OBJECT_TO_POPULATE = pre-filled InputDto
       → Serializer merges JSON into pre-filled InputDto
       → ALL properties now populated → validation fails on non-sent fields

Before PR #7879 (caused #7745):

Entity → ObjectMapperProvider maps to OutputDto/Resource
       → DeserializeProvider sets OBJECT_TO_POPULATE = wrong type
       → Serializer needs InputDto, gets Resource → merge fails
       → Fresh InputDto created, no existing data → PATCH broken

Neither direction works because the ObjectMapperProvider runs once for all operations (both read and write). You can't serve both input (write) and output (read) concerns in a single provider call.

Three places where the systems are conflated

1. ObjectMapperProvider line 44: $operation->getInput()['class'] ?? $operation->getOutput()['class'] ?? $operation->getClass()
2. ObjectMapperInputProcessor line 42: $operation->getInput()['class'] ?? $operation->getClass()
3. ObjectMapperMetadataCollectionFactory line 60-65: checks input/output classes for #[Map] attributes and auto-enables map: true

All three should use only $operation->getClass() — the Resource class. ObjectMapper should only know about Resource ↔ Entity mapping. Input/Output should remain a serializer-only concern.

What users should do instead

Want automatic mapping? → Use ObjectMapper. The Resource class IS the DTO. No input/output needed.

#[ApiResource(stateOptions: new Options(entityClass: Contact::class))]
#[Map(target: Contact::class)]
class ContactResource { /* this IS your input and output */ }

Need different read/write shapes with ObjectMapper? → Declare operations directly on the correct class that represents the data:

// Read representation
#[Get(uriTemplate: '/contacts/{id}')]
#[Map(target: Contact::class)]
class ContactRead { /* read-specific properties */ }

// Write representation
#[Patch(uriTemplate: '/contacts/{id}')]
#[Map(target: Contact::class)]
class ContactWrite { /* write-specific properties */ }

Want input/output DTOs? → Don't use ObjectMapper. Write custom processors.

#[ApiResource(
    input: ContactInput::class,
    output: ContactOutput::class,
    processor: MyProcessor::class, // InputDto → Entity
)]
class ContactResource { }

Plan

• Revert PR fix(state): prioritize input class over output in ObjectMapperProvider #7879 and fix(metadata): use operation output class for mapping instead of operation class #7601 (both made ObjectMapper aware of input/output classes)
• ObjectMapperProvider, ObjectMapperInputProcessor, and ObjectMapperMetadataCollectionFactory should only use $operation->getClass()
• Document that input/output and ObjectMapper are alternative, mutually exclusive approaches

[Cafeine42]

@soyuka

I don't have a problem with the ObjectMapper handling the mapping from the input to the stateOption target, and from the stateOption target to the output. That flow makes sense.

However, I think forcing an intermediate mapping through the ApiResource at every step would have two significant drawbacks:

Performance impact: Adding a systematic round-trip through the ApiResource means extra mapping passes that are unnecessary in many scenarios. When you have a dedicated input DTO and a dedicated output DTO, going input → ApiResource → entity → ApiResource → output is wasteful compared to input → entity → output.

Breaking real use cases: An intermediate ApiResource step assumes that all data flowing in or out can be represented by the ApiResource, which is simply not the case. Input DTOs and output DTOs exist precisely because they carry information that doesn't belong on the ApiResource — validation constraints specific to an operation, default values, computed or aggregated fields for display, etc.

Here are the patterns I rely on in my projects:

• GET → returns the ApiResource directly
• POST → input DTO (with validation constraints + default values), returns ApiResource
• PATCH/PUT → a separate input DTO (different validation constraints, no default values / uninitialized properties), returns ApiResource
• Beyond CRUD — for example on a large entity/ApiResource, having multiple distinct PATCH operations reflecting different use cases: a PATCH with an input DTO containing a workflow transition name (applied via ObjectMapper + a transform using the Workflow component), where the output could be a dedicated output DTO giving transition-specific feedback, or the ApiResource to reflect the new state.

The way I see the ObjectMapper flow, each combination should be handled directly without forcing everything through the ApiResource:

Input	stateOption	Output	Flow
inputDTO	entity	outputDTO	inputDTO → entity → outputDTO (mapper at each step, no ApiResource involved)
inputDTO	entity	ApiResource	inputDTO → entity → ApiResource
ApiResource	entity	outputDTO	ApiResource → entity → outputDTO
inputDTO	—	ApiResource	inputDTO → ApiResource (mapper is redundant from storage to output)
ApiResource	—	outputDTO	ApiResource → ApiResource → outputDTO (on POST the deserialized ApiResource can be used directly; on PATCH it needs hydration, but then we validate the full ApiResource, which is expected since there's no input DTO scoping the changeset)
—	—	—	ApiResource → ApiResource → ApiResource (no ObjectMapper needed)

The ApiResource is essentially the default class for input/storage/output, but at each stage — input, storage (stateOption), output — if a replacement class is specified (input DTO, stateOption target, output DTO), the mapper should work directly between those, without routing everything back through the ApiResource.

[Cafeine42]

• Document that input/output and ObjectMapper are alternative, mutually exclusive approaches

Wait, you want input/output and ObjectMapper mutually exclusive? That's going to shatter my entire world 😅

[soyuka]

yes its too complicated if not but it doesn't mean you can't create a provider/processor that does this... Or we need to have several ways of configuring what direction we want... I'm not sure yet but imo automatic mappig is there only for resource to entity with magic stateOptions...

[Cafeine42]

I don't think the problem is that complicated honestly. Right now the only actual issue is the mapper hydrating the input from existing data before deserialization. Making that opt-in per operation would already fix this.

Instead of a single generic map flag, maybe something like:

• mapDataToInput (default: false) — hydrate the input from stateOption/ApiResource before deserialization
• mapInputToData (default: true when input is set) — map input to stateOption/ApiResource
• mapDataToOutput (default: true when output is set) — map stateOption/ApiResource to output

That keeps the magic for the simple resource-to-entity case, while giving explicit control for advanced setups without needing a custom provider/processor.

Maybe a couple of flowcharts showing the data flow with and without input/output DTOs would help make this clearer? I can put some together if that helps move the discussion forward.
It would likely be valuable to add something along these lines to the documentation later, to clarify how providers and processors interact, as well as how object mapping, validation, serialization, and deserialization are used—along with their execution order and priority.

[soyuka]

I fully understood your needs, I'm just trying to find a better way then these options, could you show me your code somehow? Maybe send me some extract on slack in a private conversation?