From aa3c2b65401f5a942a665b93ee14c86efe7edbd9 Mon Sep 17 00:00:00 2001
From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com>
Date: Thu, 23 Jul 2026 02:23:41 +0000
Subject: [PATCH 1/3] Document morphMany empty-array serialization behavior
Add breaking-change page for the morphMany serialization fix (strapi/strapi#27090):
empty morphMany relations and multiple media fields now return [] instead of null
when populated. Add notes to Document Service and REST API populate pages.
---
.../docs/cms/api/document-service/populate.md | 4 +
.../docs/cms/api/rest/populate-select.md | 4 +
.../morph-many-serialization.md | 107 ++++++++++++++++++
3 files changed, 115 insertions(+)
create mode 100644 docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/morph-many-serialization.md
diff --git a/docusaurus/docs/cms/api/document-service/populate.md b/docusaurus/docs/cms/api/document-service/populate.md
index 7fd271f42a..55042af748 100644
--- a/docusaurus/docs/cms/api/document-service/populate.md
+++ b/docusaurus/docs/cms/api/document-service/populate.md
@@ -246,6 +246,10 @@ Omit `sort` from a `populate` object to preserve the default connect order (the
## Components & Dynamic Zones
+:::note
+When populated, empty `morphMany` relations (including `type: 'media', multiple: true` fields such as a gallery) return `[]` instead of `null`, consistent with `oneToMany` and `manyToMany`. See the [morphMany serialization breaking change](/cms/migration/v4-to-v5/breaking-changes/morph-many-serialization) for migration guidance.
+:::
+
Components are populated the same way as relations:
on the Strapi blog.
:::
+
+:::note
+When populated, empty `morphMany` relations (including `type: 'media', multiple: true` fields such as a gallery) return `[]` instead of `null`, consistent with `oneToMany` and `manyToMany`. See the [morphMany serialization breaking change](/cms/migration/v4-to-v5/breaking-changes/morph-many-serialization) for migration guidance.
+:::
diff --git a/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/morph-many-serialization.md b/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/morph-many-serialization.md
new file mode 100644
index 0000000000..12540f577e
--- /dev/null
+++ b/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/morph-many-serialization.md
@@ -0,0 +1,107 @@
+---
+title: Empty morphMany relations return [] instead of null when populated
+description: In Strapi 5, populating an empty morphMany relation or multiple media field returns an empty array instead of null.
+sidebar_label: Empty morphMany returns []
+displayed_sidebar: cmsSidebar
+tags:
+ - breaking changes
+ - Content API
+ - media
+ - morphMany
+ - populate
+ - upgrade to Strapi 5
+---
+
+import Intro from '/docs/snippets/breaking-change-page-intro.md'
+import MigrationIntro from '/docs/snippets/breaking-change-page-migration-intro.md'
+
+# Empty morphMany relations return [] instead of null when populated
+
+
+
+In Strapi 5, populating an empty `morphMany` relation -- including `type: 'media', multiple: true` fields such as a gallery -- returns `[]` instead of `null`. Update client code that checks `field === null` to treat `[]` as the empty state.
+
+
+
+In Strapi 5, empty `morphMany` relations and `type: 'media', multiple: true` fields (such as a gallery) now serialize as an empty array when populated, consistent with `oneToMany` and `manyToMany` relations. Previously, these fields returned `null` when no related entries existed.
+
+
+
+
+
+## Breaking change description
+
+
+
+
+
+**In Strapi v4**
+
+Populating an empty `morphMany` relation or a multiple media field returned `null`:
+
+```json
+{
+ "gallery": null
+}
+```
+
+
+
+
+
+**In Strapi 5**
+
+Populating an empty `morphMany` relation or a multiple media field returns an empty array:
+
+```json
+{
+ "gallery": []
+}
+```
+
+
+
+
+
+## Migration
+
+
+
+### Notes
+
+- This change applies to all `morphMany` relation types, including `type: 'media', multiple: true` fields (for example, gallery fields).
+- The change is unconditional and is not controlled by the `api.documents.strictRelations` setting.
+- See [Document Service API: Populating fields](/cms/api/document-service/populate) and [REST API: Population & Field Selection](/cms/api/rest/populate-select#population) for related information on populating relations.
+
+### Manual procedure
+
+Check client code, webhooks, and integrations that consume populated `morphMany` or multiple media fields.
+
+1. Search your codebase for code that branches on `field === null` or treats `null` as "no value" for populated `morphMany` or multiple media fields.
+2. Replace `null` checks with array checks, for example using `!field?.length`.
+
+
+
+
+**Before**
+
+```js
+if (entry.gallery === null) {
+ // handle empty gallery
+}
+```
+
+
+
+
+
+**After**
+
+```js
+if (!entry.gallery?.length) {
+ // handle empty gallery
+}
+```
+
+
+
From c1001df5673ed8cb71731ad0c8af84fe2e7aa34d Mon Sep 17 00:00:00 2001
From: Pierre Wizla <4233866+pwizla@users.noreply.github.com>
Date: Fri, 24 Jul 2026 12:09:44 +0200
Subject: [PATCH 2/3] Add morphMany serialization row to breaking changes index
---
docusaurus/docs/cms/migration/v4-to-v5/breaking-changes.md | 1 +
1 file changed, 1 insertion(+)
diff --git a/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes.md b/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes.md
index 52070f9608..2617b557bb 100644
--- a/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes.md
+++ b/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes.md
@@ -109,3 +109,4 @@ You can click on the description of any breaking change in the following tables
| [Upload a file at entry creation is no longer possible](/cms/migration/v4-to-v5/breaking-changes/no-upload-at-entry-creation) | Yes | No |
| [Components and dynamic zones should be populated using the detailed population strategy](/cms/migration/v4-to-v5/breaking-changes/no-shared-population-strategy-components-dynamic-zones) | Yes | No |
| [Updating repeatable components with the Document Service API is not recommended](/cms/migration/v4-to-v5/breaking-changes/do-not-update-repeatable-components-with-document-service-api) | Yes | No |
+| [Empty `morphMany` relations return `[]` instead of `null` when populated](/cms/migration/v4-to-v5/breaking-changes/morph-many-serialization) | Yes | No |
From 199f553eda21f6445174347b613f75f507f7ac2c Mon Sep 17 00:00:00 2001
From: Pierre Wizla
Date: Wed, 29 Jul 2026 10:27:08 +0200
Subject: [PATCH 3/3] Fix review findings on morphMany serialization docs
(#3363)
* Replace double hyphens with parentheses in morphMany Tldr
* Align JS field-selection example endpoint with cURL and response
* Correct fields parameter name and Users & Permissions wording
* Fix publish() example response to use documentId and entries
---
docusaurus/docs/cms/api/document-service/populate.md | 8 ++++----
docusaurus/docs/cms/api/rest/populate-select.md | 2 +-
.../v4-to-v5/breaking-changes/morph-many-serialization.md | 2 +-
3 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/docusaurus/docs/cms/api/document-service/populate.md b/docusaurus/docs/cms/api/document-service/populate.md
index 55042af748..21e3f13ffe 100644
--- a/docusaurus/docs/cms/api/document-service/populate.md
+++ b/docusaurus/docs/cms/api/document-service/populate.md
@@ -26,11 +26,11 @@ Use the `populate` parameter with the Document Service API to explicitly load re
By default the [Document Service API](/cms/api/document-service) does not populate any relations, media fields, components, or dynamic zones. This page describes how to use the `populate` parameter to populate specific fields.
:::tip
-You can also use the `select` parameter to return only specific fields with the query results (see the [`select` parameter](/cms/api/document-service/fields) documentation).
+You can also use the `fields` parameter to return only specific fields with the query results (see the [`fields` parameter](/cms/api/document-service/fields) documentation).
:::
:::caution
-If the Users & Permissions plugin is installed, the `find` permission must be enabled for the content-types that are being populated. If a role doesn't have access to a content-type it will not be populated.
+If the Users & Permissions feature is enabled, the `find` permission must be enabled for the content-types that are being populated. If a role doesn't have access to a content-type it will not be populated.
:::
@@ -449,8 +449,8 @@ Same behavior applies with `unpublish()` and `discardDraft()`.
status: 200,
statusText: "OK",
body: `{
- "id": "cjld2cjxh0000qzrmn831i7rn",
- "versions": [
+ "documentId": "cjld2cjxh0000qzrmn831i7rn",
+ "entries": [
{
"id": "cjld2cjxh0001qzrm1q1i7rn",
"locale": "en",
diff --git a/docusaurus/docs/cms/api/rest/populate-select.md b/docusaurus/docs/cms/api/rest/populate-select.md
index 09d65b29b8..84982afe08 100644
--- a/docusaurus/docs/cms/api/rest/populate-select.md
+++ b/docusaurus/docs/cms/api/rest/populate-select.md
@@ -79,7 +79,7 @@ const query = qs.stringify(
}
);
-await request(`/api/users?${query}`);
+await request(`/api/restaurants?${query}`);
```
diff --git a/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/morph-many-serialization.md b/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/morph-many-serialization.md
index 12540f577e..0c1459fa25 100644
--- a/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/morph-many-serialization.md
+++ b/docusaurus/docs/cms/migration/v4-to-v5/breaking-changes/morph-many-serialization.md
@@ -19,7 +19,7 @@ import MigrationIntro from '/docs/snippets/breaking-change-page-migration-intro.
-In Strapi 5, populating an empty `morphMany` relation -- including `type: 'media', multiple: true` fields such as a gallery -- returns `[]` instead of `null`. Update client code that checks `field === null` to treat `[]` as the empty state.
+In Strapi 5, populating an empty `morphMany` relation (including `type: 'media', multiple: true` fields such as a gallery) returns `[]` instead of `null`. Update client code that checks `field === null` to treat `[]` as the empty state.