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.

When I recently reviewed the serialization modules of a customer project we had taken over,
I stumbled upon something that wasn’t obvious at first glance —
but explained a few weird effects we’d seen during deployments.

Short version:

Serialization rules are evaluated top to bottom.
First match wins.

Sounds obvious, but in practice it’s surprisingly easy to overlook.

A quick refresher

Sitecore Content Serialization (SCS) turns Sitecore items into versionable, shareable files — and that really pays off during deployments. SCS takes care of moving those items into the target environment, which keeps deployments consistent and pleasantly predictable.

Which items become part of your source-controlled configuration and how they should behave during deployments, is defined in your module.json files.

Every *.module.json follows the same basic structure:

• path → where your module starts

• scope → how deep it goes (ItemOnly, ItemAndDescendants, Descendants, …)

• allowedPushOperations → what’s allowed when pushing (CreateOnly, CreateAndUpdate, etc.…)

• rules → exceptions or overrides inside that module

In the client project, the module had:

• a very broad rule at the top (/Settings)

• a more specific rule below (/Settings/Site Grouping)

• different allowedPushOperations on each

Something like this:

{
  "items": {
    "path": "/sitecore/content/MyProject",
    "scope": "ItemAndDescendants",
    "allowedPushOperations": "CreateUpdateAndDelete",
    "rules": [
      {
        "path": "/Settings",
        "scope": "ItemAndDescendants",
        "allowedPushOperations": "CreateAndUpdate"
      },
...
      {
        "path": "/Settings/Site Grouping",
        "scope": "ItemAndDescendants",
        "allowedPushOperations": "CreateOnly"
      }
    ]
  }
}

The result?
The broad /Settings rule matches everything underneath — including /Settings/Site Grouping.
Which means: the more specific “CreateOnly” rule never gets a chance to apply.

**And that’s exactly what we saw: the Site Grouping item was still being updated during deployments.
Definitely not something you want happening in higher environments.
**

How to fix it

Luckily, the fix is straightforward:
put the more specific rule first, then the broader one.

Serialization processes rules from top to bottom, so the specific one needs to get its turn before the general one catches everything.

In our case, swapping the order is all it takes:

"rules": [
  {
    "path": "/Settings/Site Grouping",
    "scope": "ItemAndDescendants",
    "allowedPushOperations": "CreateOnly"
  },
...
  {
    "path": "/Settings",
    "scope": "ItemAndDescendants",
    "allowedPushOperations": "CreateAndUpdate"
  }
]

Now the CreateOnly rule actually applies to the Site Grouping item - exactly as intended.

Extra Tip: How to verify what actually happens

If you want to double-check which rule Serialization is actually using for an item, the CLI can tell you.
The ser explain command shows:

• which module included the item

• which rule matched

• and which allowedPushOperations were applied

dotnet sitecore ser explain -p "/sitecore/content/.../Settings/Site Grouping"

Super handy when something behaves differently than expected and debugging mysterious “why is this still updating?” situations.

Wrap-up

It’s a tiny detail, but it can have a surprisingly big impact.

One misplaced line can silently break your configuration and update items you never meant to touch.
Understanding how Sitecore reads these rules - first come, first served -
can save you a whole afternoon of head-scratching.

“Ich packe meine Sachen und bin raus mein Kind”

– Thomas D, from the song “Rückenwind”

I've just made the spontaneous decision to set off on a new adventure and finally put my plans into action.
For so long, I've been immersed in the world of software development, with a particular focus on Sitecore. Every day brings new experiences - I learn something new, stumble upon challenges, and work through them.
Time and time again, the thought has crossed my mind to share these experiences with other, to help fellow “travelers” on their own journeys. But somehow, I never really took the leap. Until now.
So here I am, ready to embark on this journey. Let’s see where it leads.

A Note on the Quote:

Starting my first article with a German quote is a small hint that I’m based in Germany ;-)

And yes, I’m old enough that this catchy tune from 1998 can loop in my head whenever I think about setting off on a new journey.
But I’m also young enough to stay excited about the constant changes in the world of software and web development, always ready to explore what’s next.