diff --git a/docusaurus/docs/cms/api/document-service/populate.md b/docusaurus/docs/cms/api/document-service/populate.md index 0a53285fab..7694080d18 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. ::: @@ -278,6 +278,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: @@ -322,3 +322,7 @@ For many-to-many and other join-table relations, an explicit `sort` within a `po :::tip Performance tip In production, always use explicit population instead of wildcards like `populate=*`. Limit population depth to 2-3 levels and consider centralizing population logic in route middlewares. See 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..0c1459fa25 --- /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 +} +``` + + +