OrbSearchDocs
GuideReference

overlays.json

Corrections to catalog data, applied when documents are built.

overlays

array of objects

A correction keyed by an entity id or a selector, never by a snapshot row. An overlay whose target has left the catalog stays, dormant, until it returns.

idstringRequired

An id unique within its file, such as a search test's, an overlay's or a pattern's.

targetobjectRequired

The entities an overlay corrects: one by its id, or all that match a selector.

3 fields
typestringRequired

The code of an entity type, such as product, category or a merchant's own store.

idstring

The merchant's id of an entity, unique per type, such as SOFA-LUND-3. It travels unchanged; OrbSearch never rewrites it.

whereobject

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
categoryobject

The entity is in this category, or below it with within.

A category, exactly or including everything below it.

2 fields
isstring or array of strings

One value, or a list meaning any of them.

withinstring or array of strings

One value, or a list meaning any of them.

anyarray of objectsat least 1 item

At least one of these holds.

allarray of objectsat least 1 item

All of these hold; useful inside any.

notobject

This does not hold.

<key>boolean, number, string, array of (boolean, number or string) or object

A plain value (equal), a list (any of them), or an operator object such as { "lt": 20 }.

6 fields
ltboolean, number or string

A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.

lteboolean, number or string

A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.

gtboolean, number or string

A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.

gteboolean, number or string

A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.

betweenarray of (boolean, number or string)2 items

From the first value to the second, both included.

existsboolean

True: the field has a value. False: it has none.

hideboolean

Hide the targets from every request. Hiding for some requests only is a rule.

keywordsarray of strings or map of arrays of strings

Search terms added to the merchant's own keywords.

badgesarray of strings or map of arrays of strings

Badges shown on the targets' results, such as "OE quality".

fillobject

Values set only where the catalog has none, so the correction steps aside once the feed is fixed.

Attribute values an overlay writes, as a source would send them.

1 field
attributesmap of valuesRequired
setobject

Values that replace the catalog's; the panel shows them with a warning.

Attribute values an overlay writes, as a source would send them.

1 field
attributesmap of valuesRequired
untilstring

The overlay ends at this time.

notestring
originobject

Where an imported rule or overlay came from.

2 fields
importstringRequired

What it was imported from, such as the previous search's export.

refstringRequired

$schema

string

The JSON Schema an editor checks this file against; kept as written.

Example

tests/fixtures/home/overlays.json (trimmed)
{
  "$schema": "../../../contracts/schema/overlays.json",
  "overlays": [
    {
      "id": "bestseller-matratze-wolke",
      "target": { "type": "product", "id": "MATRATZE-WOLKE" },
      "badges": { "de": ["Bestseller"], "en": ["Best seller"] },
      "note": "One of the three products that sold most in the last 30 days"
    },
    {
      "id": "bestseller-regal-steg",
      "target": { "type": "product", "id": "REGAL-STEG" },
      "badges": { "de": ["Bestseller"], "en": ["Best seller"] },
      "note": "One of the three products that sold most in the last 30 days"
    }
  ]
}

Guide: Overlays

On this page

overlays$schemaExample