docs(rest): clarify PATCH is a shallow top-level merge (nested objects replaced, not deep-merged)#547
docs(rest): clarify PATCH is a shallow top-level merge (nested objects replaced, not deep-merged)#547kriszyp wants to merge 2 commits into
Conversation
…s are replaced, not deep-merged)
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the REST API overview documentation to add a warning explaining that PATCH requests perform a shallow merge, meaning nested objects are replaced rather than deep-merged. The reviewer suggested formatting this warning with bullet points and clear examples to improve readability and make the behavior easier for developers to understand.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-547 This preview will update automatically when you push new commits. |
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
dawsontoth
left a comment
dawsontoth
left a comment
There was a problem hiding this comment.
Content looks good! I like the example. Once the format is happy, I think this'll be good to go!
2 participants
What
Adds a warning to the REST PATCH reference clarifying that the merge is shallow (top-level only): a PATCH whose body contains a nested object replaces that whole sub-object rather than deep-merging it, so untouched nested properties are silently dropped.
Why
The current text ("merging only the provided properties... Unspecified properties are preserved") is accurate for top-level attributes but reads as a deep merge. In practice
PATCH { "settings": { "theme": "dark" } }dropssettings.notifications— a silent data-loss footgun, since the request returns 204 with no indication anything was lost. This came up during exploratory QA (qa-explorer): a single nested-field PATCH silently loses sibling nested data on both engines, with no error and no public docs describing the behavior.The behavior itself is consistent (RFC 7386-style top-level merge) — this PR just documents it and points to the safe pattern (read-modify-write the parent, or send the full nested object). Also notes that dot-path keys are stored literally.
— KrAIs (Claude) on Kris's behalf