Enrichment configuration

Before a content author can add enrichment content to product pages, configure your query.yaml file so the storefront can automatically generate the enrichment.json file it depends on.

Caution

Configure query.yaml before anyone authors enrichment content. Manually creating enrichment.json instead of generating it from query.yaml is the most common cause of enrichment failures.

Configure query.yaml to generate enrichment.json

To include the enrichment index configuration, configure your helix-query.yaml or the query.yaml pushed to your Helix site config.

query.yaml enrichment index configuration

version: 1
indices:
enrichment:
  target: /enrichment/enrichment.json
  include:
    - '**/enrichment/**'
  properties:
    title:
      select: head > meta[property="og:title"]
      value: |
        attribute(el, 'content')
    products:
      select: head > meta[name="enrichment-products"]
      values: |
        match(attribute(el, 'content'), '([^,]+)')
    categories:
      select: head > meta[name="enrichment-categories"]
      values: |
        match(attribute(el, 'content'), '([^,]+)')
    positions:
      select: head > meta[name="enrichment-positions"]
      values: |
        match(attribute(el, 'content'), '([^,]+)')

The /enrichment/enrichment.json file is generated automatically from this configuration — you don’t need to create it manually.

Choose the correct location for your query.yaml

You have two options for where to place your query.yaml configuration:

Option 1: Site-specific configuration (recommended for Helix 5)

• Configure at: https://admin.hlx.page/config/[ORG]/sites/[SITE]/content/query.yaml
• Each site has its own independent configuration, so multiple sites don’t conflict.

Option 2: GitHub-based configuration

• Place as helix-query.yaml in your GitHub repository.
• All sites that share this codebase share this configuration, so use this option for multi-site deployments with shared configuration.

Tip

For the complete query.yaml configuration, including all required indices, see the AEM boilerplate repository .

To allow your content author to add enrichment content, provide access to the storefront once enrichment.json is generated correctly.

Troubleshooting

Enrichment content doesn’t appear on product pages

• Verify the query.yaml configuration: Confirm the enrichment index is configured with the correct include pattern ('**/enrichment/**').
• Confirm the enrichment target: Check that target: /enrichment/enrichment.json is present in your configuration.
• Compare against the boilerplate: Check your query.yaml against the default-query.yaml in the AEM boilerplate repository.
• Check the browser console: Identify JavaScript errors that prevent enrichment from loading.

If issues continue, check the AEM boilerplate repository for a reference implementation, or contact Adobe Commerce support with the specific error messages from your browser console.