rules.json
The rules in precedence order.
rules
array of objects
The rules in precedence order: the first rule is the highest.
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
One line, up to 200 characters, shown in the panel, the trace and diffs.
A disabled rule is not evaluated. Default: true.
The condition over the request. Without one, the rule always matches.
A predicate over the request (when). Without a condition, a rule always matches.
{ "on": "search", "query": { "contains": ["bremsen", "bremse"] } }
10 fields
The query as typed, after normalization. Matching is literal: no typos, synonyms or plurals.
How the query must look. A list of phrases means any of them.
4 fields
One value, or a list meaning any of them.
One value, or a list meaning any of them.
One value, or a list meaning any of them.
True: nothing was typed. False: something was.
The surface the request comes from.
3 values
The search page's results.
A category's listing.
A search box's suggestions while the shopper types.
What the query named. Rules that resolve or rewrite run before resolution and cannot read it.
What the query named: its category, its detected filters, and whether any text is left.
3 fields
The detected filters, as a selector over the detected values.
Picks entities (where). Attribute codes and the built-in fields brand, price, on_sale, availability and delivery_days are keys of the same object; category takes is or within.
{ "any": [{ "brand": "bosch" }, { "quality": "oe" }], "not": { "availability": "out_of_stock" } }
5 fields
At least one of these holds.
All of these hold; useful inside any.
A plain value (equal), a list (any of them), or an operator object such as { "lt": 20 }.
6 fields
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
From the first value to the second, both included.
True: the field has a value. False: it has none.
True when the query resolved completely and no text is left.
One value, or a list meaning any of them.
One value, or a list meaning any of them.
Declared context keys and the values they must have, such as { "customer_group": "b2b" }.
What the rule does: at least one effect.
What a rule does. Understand-phase effects (resolve, rewrite) run before the query is resolved; redirect ends planning; the rest shape the results, and place puts banners beside them.
10 fields
Decides what an ambiguous term means. Per term, the higher rule decides.
What one term means: values such as { "term": "puma", "as": { "brand": "puma" } }, a category such as "as": { "category": "parts/brakes" }, or "as": "text" to keep it as text.
Removes words from the query before it is resolved and searched. Removals of all rules are united.
1 field
Sends the shopper elsewhere. The highest redirect wins and ends planning.
Where a redirect goes: an entity's page, whose URL follows the merchant's catalog, or a fixed URL.
3 fields
An entity named with its type, type:id, such as product:SOFA-LUND-3.
With a category: the filters chosen on its page, as a request's filters name them.
Picks entities (where). Attribute codes and the built-in fields brand, price, on_sale, availability and delivery_days are keys of the same object; category takes is or within.
{ "any": [{ "brand": "bosch" }, { "quality": "oe" }], "not": { "availability": "out_of_stock" } }
5 fields
At least one of these holds.
All of these hold; useful inside any.
A plain value (equal), a list (any of them), or an operator object such as { "lt": 20 }.
6 fields
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
From the first value to the second, both included.
True: the field has a value. False: it has none.
A fixed URL: a path such as /werkstatt, or one that starts with https://.
Narrows the results. Shoppers see it as a chip they can remove.
A filter a rule adds, optionally only for one type's section.
2 fields
The code of an entity type, such as product, category or a merchant's own store.
Picks entities (where). Attribute codes and the built-in fields brand, price, on_sale, availability and delivery_days are keys of the same object; category takes is or within.
{ "any": [{ "brand": "bosch" }, { "quality": "oe" }], "not": { "availability": "out_of_stock" } }
5 fields
At least one of these holds.
All of these hold; useful inside any.
A plain value (equal), a list (any of them), or an operator object such as { "lt": 20 }.
6 fields
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
From the first value to the second, both included.
True: the field has a value. False: it has none.
Removes entities from the results. Hide beats pin.
The entities an effect is about: one entity, several, or all that match a selector, optionally of one type.
4 fields
An entity named with its type, type:id, such as product:SOFA-LUND-3.
Picks entities (where). Attribute codes and the built-in fields brand, price, on_sale, availability and delivery_days are keys of the same object; category takes is or within.
{ "any": [{ "brand": "bosch" }, { "quality": "oe" }], "not": { "availability": "out_of_stock" } }
5 fields
At least one of these holds.
All of these hold; useful inside any.
A plain value (equal), a list (any of them), or an operator object such as { "lt": 20 }.
6 fields
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
From the first value to the second, both included.
True: the field has a value. False: it has none.
With where: only entities of this type.
Puts entities at fixed positions, within every filter.
3 fields
An entity named with its type, type:id, such as product:SOFA-LUND-3.
The slot, counted from 1. Positions are unique within a rule; on a tie between rules the higher one takes the slot and the other moves to the next free one.
A paid placement: the hit names its campaign, so a storefront marks it as an ad and reports its views and clicks for the campaign. It is placed as any pin is, only where the product meets the page's category and filters.
The campaign a paid placement belongs to: { "campaign": "Michelin spring" }.
1 field
The merchant's name for it, which the campaign report counts by.
Moves entities up, within relevance.
A boost or bury.
5 fields
An entity named with its type, type:id, such as product:SOFA-LUND-3.
Picks entities (where). Attribute codes and the built-in fields brand, price, on_sale, availability and delivery_days are keys of the same object; category takes is or within.
{ "any": [{ "brand": "bosch" }, { "quality": "oe" }], "not": { "availability": "out_of_stock" } }
5 fields
At least one of these holds.
All of these hold; useful inside any.
A plain value (equal), a list (any of them), or an operator object such as { "lt": 20 }.
6 fields
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
From the first value to the second, both included.
True: the field has a value. False: it has none.
With where: only entities of this type.
One of slight, medium or strong.
Moves entities down, within relevance.
A boost or bury.
5 fields
An entity named with its type, type:id, such as product:SOFA-LUND-3.
Picks entities (where). Attribute codes and the built-in fields brand, price, on_sale, availability and delivery_days are keys of the same object; category takes is or within.
{ "any": [{ "brand": "bosch" }, { "quality": "oe" }], "not": { "availability": "out_of_stock" } }
5 fields
At least one of these holds.
All of these hold; useful inside any.
A plain value (equal), a list (any of them), or an operator object such as { "lt": 20 }.
6 fields
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
From the first value to the second, both included.
True: the field has a value. False: it has none.
With where: only entities of this type.
One of slight, medium or strong.
The order of sections. Types not listed follow in the release's order.
Puts banners and teasers above, among or below the results. A placement is not a hit: it changes no total, facet, page size or order of hits.
A banner at a place of the page: { "slot": "top", "banner": { ... } }, or among the tiles, { "slot": "grid", "position": 5, "banner": { ... } }.
3 fields
Where on a page a banner sits.
3 values
With grid, and only there: the tile it sits before, counted from 1 across the pages of the listed section, whose tiles are the page's products, or its services on a workshop's page. Positions are unique within a rule; on a tie between rules the higher one takes the position and the other moves to the next free one, as pins do. A position past the last tile the pages reach shows nowhere, and the trace says why.
When the rule is active, checked against the time in the request, never the engine's clock.
A window in time: from from (inclusive) until until (exclusive). Either end may be open.
$schema
string
The JSON Schema an editor checks this file against; kept as written.
Example
{
"$schema": "../../../contracts/schema/rules.json",
"rules": [
{
"id": "home/sofa-sale",
"description": "Sofa sale on top of the sofas, armchairs among them",
"when": { "category": { "is": "wohnen/sofas" } },
"then": {
"place": [
{
"slot": "top",
"banner": {
"kind": "banner",
"title": { "de": "Sofas im Angebot", "en": "Sofas on sale" },
"text": {
"de": "Samt, Leder und Stoff: ausgewählte Sofas jetzt reduziert.",
"en": "Velvet, leather and fabric: selected sofas, now reduced."
},
"image": {
"url": "/demo/images/81dwblf8ogL.jpg",
"alt": {
"de": "Grünes Samtsofa mit goldenen Beinen",
"en": "Green velvet sofa with gold legs"
}
},
"link": {
"to": "category:wohnen/sofas",
"filters": { "on_sale": true }
}
}
}
]
}
}
]
}Guide: Rules · Banners and teasers