From d40f9984e1e0909927db60298e4ca2a595c73ab9 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Thu, 25 Jun 2026 08:53:40 -0600 Subject: [PATCH 1/4] 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/4] 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 From 89d3ffa9ba5fae05d06610387d5b962e0bc9c720 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Sun, 19 Jul 2026 18:48:28 -0600 Subject: [PATCH 3/4] docs(rest): fix MDX/Prettier failures from raw JSON in PATCH example Wrap the inline JSON snippets in the PATCH shallow-merge example with backticks. Raw `{...}` outside a code span is parsed by MDX as a JS expression, which broke the build ("Could not parse expression with acorn"); the missing backticks also failed Prettier's format check. Co-Authored-By: Claude Sonnet 5 --- reference/rest/overview.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/reference/rest/overview.md b/reference/rest/overview.md index b106b4fb..62a879cd 100644 --- a/reference/rest/overview.md +++ b/reference/rest/overview.md @@ -122,11 +122,13 @@ The merge is **shallow** (top-level only). Preserving "unspecified properties" a 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) + +- **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. From 64480979da354b2b4a7a2c69f645169c384b776b Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Sun, 19 Jul 2026 22:42:06 -0600 Subject: [PATCH 4/4] Update reference/rest/overview.md Co-authored-by: Ethan Arrowood --- reference/rest/overview.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/reference/rest/overview.md b/reference/rest/overview.md index 62a879cd..deb4bd1e 100644 --- a/reference/rest/overview.md +++ b/reference/rest/overview.md @@ -123,9 +123,11 @@ If the request body includes a nested object, that entire sub-object is **replac **Example:** +**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) +- **Resulting record:** `{"settings": {"theme": "dark"}}` (the `notifications` object is lost) To update a single nested field, you must either: