docs(rest): clarify PATCH is a shallow top-level merge (nested objects replaced, not deep-merged)

[kriszyp]

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" } } drops settings.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

[gemini-code-assist]

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.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-547

This preview will update automatically when you push new commits.

[dawsontoth]

Content looks good! I like the example. Once the format is happy, I think this'll be good to go!

[Ethan-Arrowood]

Content looks great — this is a real footgun worth documenting, and the example makes it immediately clear. Echoing @dawsontoth: good to go once the format is happy.

The CI failure is caused by this diff (not a flake): bare JSON braces in MDX text. I've attached a one-click suggestion below that fixes the build and the prettier check (verified both locally). Approving on that basis — apply the suggestion and merge at your discretion once it's green.

_{sent with Claude Fable 5}

[Ethan-Arrowood]

This is what's breaking CI: the bare {...} JSON here gets parsed as JSX expressions by MDX (Docusaurus compiles .md through MDX), so the site build fails on this file — the Deploy PR Preview log shows MDX compilation failed for reference/rest/overview.md. Prettier also wants - bullets and blank lines before the lists.

This suggestion fixes both — I verified it passes prettier --check and compiles under MDX:

Suggested change

	**Example:**
	* **Existing record:** {"settings": {"theme": "light", "notifications": {"email": true}}}
	* **PATCH request body:** {"settings": {"theme": "dark"}}
	* **Resulting record:** {"settings": {"theme": "dark"}} (the "notifications" object is lost)
	To update a single nested field, you must either:
	1. Read-modify-write the parent object.
	2. Send the full nested object with the updated values.
	**Example:**
	- **Existing record:** `{"settings": {"theme": "light", "notifications": {"email": true}}}`
	- **PATCH request body:** `{"settings": {"theme": "dark"}}`
	- **Resulting record:** `{"settings": {"theme": "dark"}}` (the `notifications` object is lost)
	To update a single nested field, you must either:
	1. Read-modify-write the parent object.
	2. Send the full nested object with the updated values.