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.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 | 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 +} +``` + + +