The empty field that changed everything
JSON Merge Patch gives omitted fields, empty strings and null different meanings when updating a document.
Alexander Claes2 min read
An edit form shows a contact’s name and phone number. Someone removes the phone number and saves. The request succeeds, but when they reopen the form, the old number is still there.
The field was empty on screen. The request may have said to leave it alone.
JSON Merge Patch defines how a JSON document describes changes to another. Published by the IETF as RFC 7396, it gives omitted fields, empty strings and null different meanings.
Three different instructions
For an update to a contact object, leaving out the phone field preserves its existing value. Sending an empty string replaces the number with text containing no characters. Sending null removes the phone field from the document.
An empty string therefore keeps the field present. Removing the field makes it absent. A form might display both as an empty input, even though the underlying documents differ.
What the form sends
Suppose the form removes every empty value before sending its update. When someone clears the phone number, the field disappears from the request. Under Merge Patch rules, the existing number stays unchanged.
If the form instead sends the phone field with null, the field is removed. The difference lies in the request, even when the form looks the same before saving.
A specific update format
These rules belong to JSON Merge Patch, identified by application/merge-patch+json. The HTTP PATCH method does not impose them on every API. PATCH carries a set of changes; its media type identifies the format used to describe them. The endpoint must support that format.
Merge Patch also replaces arrays as a whole. Within an object, null means removal, so it cannot express setting a field to a literal JSON null value.