Documentation

Differences in GraphQL response structure and markdown output in Adobe Experience Manager

Last update: Mon May 11 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

After upgrading to AEM 6.5.23+ or 6.5 LTS, differences are observed in the structure of GraphQL responses for content fragments and in markdown output formatting compared to earlier versions, such as AEM 6.5.20. These changes affect how empty objects are handled in union-type queries and how whitespace is rendered in markdown fields. To fix this issue, handle empty objects in responses, adjust markdown processing, and follow consistent persisted query encoding.

Description description

Environment

  • Product: Adobe Experience Manager (AEM) Managed Services, AEM Sites
  • Version: 6.5.23+/ 6.5 LTS (including SP1/SP2), Previous version referenced: 6.5.20

Issue and symptoms

  • In GraphQL responses, when a multifield fragment reference contains content fragments that don’t match any allowed model listed in the query, AEM 6.5.23+ and 6.5 LTS return empty JSON objects for those entries, while earlier versions omit them entirely.
  • Markdown output from rich text fields shows differences in whitespace handling, such as additional spaces or blank lines between paragraphs or blocks.
  • The persisted query endpoint in AEM 6.5.23+ and 6.5 LTS is more tolerant of unencoded special characters, but it still requires URL encoding for consistent behavior.

Resolution resolution

To fix this issue, follow these steps:

  1. Handling empty JSON objects returned by union-type queries:

    • Filter out empty objects (objects with no properties) on the client side when processing the GraphQL response.
    • Alternatively, update the persisted query to include fragments for all possible referenced models to ensure that relevant data is returned for each type.

  2. Differences in Markdown whitespace and formatting:

    • If exact whitespace or formatting is critical, consider using the HTML or JSON representation of the field instead of Markdown.
    • Optionally, normalize whitespace during post-processing by collapsing repeated spaces or blank lines before rendering.

  3. Persisted query encoding:

    • Always URL-encode special characters, such as semicolons, spaces, and colons, in persisted query suffixes and variables, according to documented patterns.
    • Do not rely on increased tolerance for unencoded characters introduced in newer versions, as this behavior is not guaranteed across future updates.

  4. Verify that:

    • The client application correctly filters out empty objects from GraphQL responses, if required.
    • Rendered content appears as expected after applying normalization steps to Markdown output.
    • Persisted queries function consistently across environments by following encoding requirements.

Notes

  • The described behaviors are expected due to intentional changes introduced in AEM 6.5.23+ / 6.5 LTS and the updated GraphQL engine.
  • Semantic consistency (correct structure and content) is maintained; however, byte-for-byte identical Markdown output across versions is not guaranteed.
  • If semantic issues, such as missing content or incorrect structure, are observed, further investigation may be required, as these could indicate defects rather than expected behavioral changes.
recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f