JSON Merge Patch is a standardized, widely adopted format for partial updates: a consumer sends only the resource properties it wants to modify through PATCH instead of replacing the complete resource with PUT. Its partial structure keeps update requests smaller and more intuitive. section 5.3.4 section 13.5.6
Updating a product
A PATCH /products/{productReference} request can use a ProductModification model containing only the changed properties. The model may restrict updates further: for example, a supplier defined during creation can remain non-modifiable. Consumers therefore avoid resending the complete product required by a total replacement. section 5.3.4
Choose JSON Merge Patch with these trade-offs in mind:
- Prefer it over JSON Patch when usability, common adoption, and straightforward OpenAPI or JSON Schema documentation matter. section 13.5.6 section 14.2.5
- Treat array updates carefully: JSON Merge Patch sends the entire affected array, while JSON Patch can address one element efficiently. section 13.5.6
- Use dedicated operations when arrays contain many frequently changed elements rather than optimizing every update with JSON Patch. section 13.5.6
- Support both formats through content negotiation when consumers require different update representations. section 13.5.6 section 13.9
