A Closer Look at Reference Fields in SitecoreAI - and How to Work With Them Today

Update (Jan 2026):
Since this article was published, the query-related issue described below has been fixed and is now working again for both the Content Editor and the Page Builder (as also reflected in the official changelog).

This resolves the concrete query problem discussed here. However, it does not fully address the underlying challenges I’m seeing when working with reference fields in real-world setups.

A deeper dive into these limitations — including differences across field types and current Page Builder support — will follow in an upcoming article in this series.

Over the past few days, I came across something in SitecoreAI that didn’t immediately seem critical, but certainly didn’t feel right either.
A lookup field - a fundamental element in any Sitecore solution - suddenly showed different results depending on where it was edited.
In the Page Builder, the field returned an empty list. In the classic Content Editor, it worked exactly as expected.
**So I started looking for a more robust way to configure lookup fields - and to understand what’s really going on under the hood.
**

Because this felt unusual (and I’m fairly certain earlier Sitecore XM Cloud versions behaved differently), I started to take a deeper look. After my initial analysis, I opened a support ticket, exchanged findings with colleagues and our TAM, and noticed that similar discussions were already happening on Slack.
What initially looked like a small inconsistency quickly turned into a broader investigation into how SitecoreAI evaluates reference fields today - and why multisite scenarios, in particular, seem to expose these differences.

Instead of letting these observations disappear in internal chats and ticket threads, I wanted to document them here - partly to share the findings, partly because this incident highlighted a topic I’ve been meaning to explore for a while:
how referenced data should ideally be modeled in SitecoreAI, how editors can work with it efficiently, and how we can give them a clear, streamlined workflow - ideally without leaving the Page Builder.

This article is the beginning of that exploration and will likely become the first part of a small series ;-)

---

Part 1: Understanding the Lookup Query Issue

The issue surfaced while configuring a reference field that followed a very common multisite pattern:
allow editors to pick items either from the current site’s Data folder or from a shared Data folder used across multiple sites. (Example use case: a Quote component where you want to select a Contact Person.)

This is a typical SXA-style approach, and in classic XP solutions it has always been solved with a simple union query, for example:

query:$site/Data//[@@templatename='Contact Person'] | $sharedSites/Data//[@@templatename='Contact Person']

This query still works reliably in the SitecoreAI Content Editor.
Editors see exactly the items they expect to see:

However, when the same field is opened in the Page Builder, the lookup list is completely empty. No items, no warning, no indication that the query failed:

To verify whether the Page Builder simply required a different syntax, I tested an alternative version (similar to what you can find on ootb renderings)):

query:$site/Data//[@@templatename='Contact Person'] | query:$sharedSites/Data//[@@templatename='Contact Person']

Somewhat surprisingly, this version does work in the Page Builder — the items appear as expected.

But the same syntax immediately breaks the Content Editor, which throws a LookupSourceException due to invalid query syntax.

At this point, the inconsistency becomes clear:

• The Content Editor accepts the standard query syntax

• The Page Builder only accepts the modified syntax

• Neither editor accepts the other editor’s format

• And there is currently no single query syntax that works in both environments

In other words: Content Editor and Page Builder evaluate the lookup source differently and expect incompatible formats.

What you can do today

For now, there isn’t a single lookup query syntax that works in both the Content Editor and the Page Builder.
But that doesn’t mean we’re stuck — it just means we need to be explicit about how we want editors to work with referenced data today.

Here are a few practical options I see right now:

• Prioritize the Page Builder
  If most authoring happens inside the Page Builder (as recommended), use the query:$site/... | query:$sharedSites/... pattern.
  It’s the format the Page Builder evaluates reliably.
  Just make sure to educate your editors/clients that the Content Editor might show errors for this field - and that this is expected in this setup.

• Prioritize the Content Editor
  If your project still relies heavily on the Content Editor, you can keep the classic union syntax and accept that the Page Builder won’t support this field for now.
  Not ideal for XM Cloud in the long run, but a valid choice if Page Builder isn’t in active use yet - or if your editors are comfortable jumping into the Content Editor via the “Edit in Content Editor” link for certain fields.

• Challenge the data model
  Sometimes the right question is: do we really need two roots here?
  If either the site-specific or the shared location is enough, simplifying the query to a single root avoids the compatibility issue altogether.

• Use a multi-root Treelist as an alternative field type!
  A multi-root Treelist uses a query:-based multi-root source (e.g. query:$site/... | query:$sharedSites/...) - and unlike a standard Lookup field, this syntax works consistently in both the Content Editor and the Page Builder!
  It’s a perfect replacement if you’re currently using a Multilist.
  But unfortunately, there is no equivalent for Droplink fields/single select (More on that in part 2).

• Additional ideas, I would not recommend
  You might be tempted to take other approaches - like using a query that starts at a very high-level root (or even the whole content tree) and filtering only by template. While this technically works, it will definitely hurt performance and opens the door to other issues. Another idea is to split the selection into two separate fields - one for site references and one for sharedSites. I would not recommend either of these approaches.

• Custom field via Marketplace app

  A custom field type from the Marketplace is an interesting option - and in the long run, it might even become the cleanest solution.
  But building a custom field is additional effort and can quickly become quite complex. And considering the importance of referenced data in a CMS like SitecoreAI, this is likely an area that will be addressed more consistently in the product sooner or later.

None of these are perfect, but being aware of the current behavior — and choosing a clear approach per project — already helps teams avoid unexpected lookup issues.

This discovery is just the starting point and connects to a broader topic: how editors can work with referenced data efficiently inside SitecoreAI’s Page Builder — something I’ve been exploring for a while. I’ll dig deeper into that in part 2.