Custom DAM metadata unavailable in asset references returned by AEM Headless GraphQL

Last update: September 4, 2026

This article explains why custom DAM metadata stored under /jcr:content/metadata isn’t returned for ImageRef, MultimediaRef, or DocumentRef asset references in AEM Headless GraphQL. These asset reference types expose a fixed set of fields and don’t provide a supported extension point for arbitrary custom metadata. To fix this, add the required values as explicit Content Fragment Model fields or retrieve the asset metadata separately through an Assets metadata or delivery API.

Description description

Environment

Adobe Experience Manager Sites as a Cloud Service
Adobe Experience Manager Assets
AEM Headless GraphQL with Content Fragment Models
Content Fragments that reference DAM assets

Issue/Symptoms

Organizations using Adobe Experience Manager (AEM) Headless GraphQL with Content Fragment Models may need to expose custom DAM metadata properties, such as properties stored under /jcr:content/metadata on assets, in GraphQL API responses for asset reference fields.

Custom DAM metadata fields aren’t available in the GraphQL response for asset reference fields.
By default, asset reference types such as ImageRef, MultimediaRef, and DocumentRef expose only a fixed set of fields in the GraphQL schema.
There is no documented or supported extension point to add arbitrary custom metadata fields to these asset reference types in the GraphQL response.

Cause

Asset reference types in AEM Headless GraphQL expose a fixed, product-defined set of fields. AEM doesn’t provide a documented or supported extension point to add arbitrary custom properties from /jcr:content/metadata directly to these types in the GraphQL response.

Resolution resolution

Follow these steps to expose or retrieve custom DAM metadata for asset references:

Review the current product capabilities. Asset reference types such as ImageRef, MultimediaRef, and DocumentRef expose only a fixed set of fields. There is no supported out-of-the-box mechanism or extension point to add custom metadata fields directly to these types in the GraphQL response.
Use model-level mirroring. Add the required metadata fields as explicit fields on your Content Fragment Model, keep these fields synchronized with the DAM metadata by using a workflow or integration process, and query the fields directly in the GraphQL schema.
Use dual-API access. Query the Content Fragment through GraphQL to retrieve asset references, such as paths or IDs. Then use the Assets HTTP/Delivery APIs to retrieve custom metadata from /jcr:content/metadata for each asset as needed.
After implementing the selected supported approach, query the Content Fragment through GraphQL and verify that the required metadata fields are present in the response.

Notes:

If needed, implement a customer-owned workaround. Implement a @SlingServletFilter to intercept the GraphQL JSON response, such as the response from /graphql/execute.json. In the filter, resolve each asset reference path and read the custom metadata properties. Inject the metadata values into the asset reference objects in the response before returning the response to the client.
Monitor the performance of the customer-owned workaround and perform regression testing with every AEM upgrade because it relies on the internal response structure, which may change between AEM releases.

recommendation-more-help

experience-cloud-kcs-help-kbarticles