From d40f9984e1e0909927db60298e4ca2a595c73ab9 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Thu, 25 Jun 2026 08:53:40 -0600 Subject: [PATCH 1/2] docs(rest): clarify PATCH is a shallow top-level merge (nested objects are replaced, not deep-merged) --- reference/rest/overview.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/reference/rest/overview.md b/reference/rest/overview.md index a2121f98..4f6730b9 100644 --- a/reference/rest/overview.md +++ b/reference/rest/overview.md @@ -116,6 +116,10 @@ Content-Type: application/json { "status": "active" } ``` +:::warning +The merge is **shallow** (top-level only). Preserving "unspecified properties" applies to top-level attributes — if the body includes a nested object, that whole sub-object is **replaced**, not deep-merged, so any nested properties you didn't include are dropped. For example, `PATCH { "settings": { "theme": "dark" } }` against a record whose `settings` is `{ "theme": "light", "notifications": { ... } }` results in `settings` being just `{ "theme": "dark" }` — `notifications` is gone. To update a single nested field, read-modify-write the parent object (or send the full nested object). Dot-path keys (`"settings.theme"`) are stored literally, not interpreted as paths. +::: + ### DELETE Delete a specific record or all records matching a query. From 0e8347d9f94193b690de41e0df877413e5b848a4 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Fri, 26 Jun 2026 06:18:21 -0600 Subject: [PATCH 2/2] Update reference/rest/overview.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- reference/rest/overview.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/reference/rest/overview.md b/reference/rest/overview.md index 4f6730b9..b106b4fb 100644 --- a/reference/rest/overview.md +++ b/reference/rest/overview.md @@ -117,7 +117,20 @@ Content-Type: application/json ``` :::warning -The merge is **shallow** (top-level only). Preserving "unspecified properties" applies to top-level attributes — if the body includes a nested object, that whole sub-object is **replaced**, not deep-merged, so any nested properties you didn't include are dropped. For example, `PATCH { "settings": { "theme": "dark" } }` against a record whose `settings` is `{ "theme": "light", "notifications": { ... } }` results in `settings` being just `{ "theme": "dark" }` — `notifications` is gone. To update a single nested field, read-modify-write the parent object (or send the full nested object). Dot-path keys (`"settings.theme"`) are stored literally, not interpreted as paths. +The merge is **shallow** (top-level only). Preserving "unspecified properties" applies only to top-level attributes. + +If the request body includes a nested object, that entire sub-object is **replaced** rather than deep-merged. Any omitted nested properties will be dropped. + +**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. + +Note that dot-path keys (e.g., "settings.theme") are stored literally as keys and are not interpreted as paths. ::: ### DELETE