# 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.

- `id` (string · required): An id unique within its file, such as a search test's, an overlay's or a pattern's.

- `target` (object · required): The entities an overlay corrects: one by its id, or all that match a selector.
  
  - `type` (string · required): The code of an entity type, such as `product`, `category` or a merchant's own `store`.
  
  - `id` (string): The merchant's id of an entity, unique per type, such as `SOFA-LUND-3`. It travels unchanged; OrbSearch never rewrites it.
  
  - `where` (object): 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" } }`
    
    - `category` (object): The entity is in this category, or below it with `within`.
      
      A category, exactly or including everything below it.
      
      - `is` (string or array of strings): One value, or a list meaning any of them.
      
      - `within` (string or array of strings): One value, or a list meaning any of them.
    
    - `any` ([array of objects](#target.where) · at least 1 item): At least one of these holds.
    
    - `all` ([array of objects](#target.where) · at least 1 item): All of these hold; useful inside `any`.
    
    - `not` ([object](#target.where)): 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 \}.
      
      - `lt` (boolean, 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`.
      
      - `lte` (boolean, 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`.
      
      - `gt` (boolean, 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`.
      
      - `gte` (boolean, 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`.
      
      - `between` (array of (boolean, number or string) · 2 items): From the first value to the second, both included.
      
      - `exists` (boolean): True: the field has a value. False: it has none.

- `hide` (boolean): Hide the targets from every request. Hiding for some requests only is a rule.

- `keywords` (array of strings or map of arrays of strings): Search terms added to the merchant's own keywords.

- `badges` (array of strings or map of arrays of strings): Badges shown on the targets' results, such as "OE quality".

- `fill` (object): 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.
  
  - `attributes` (map of values · required)

- `set` (object): Values that replace the catalog's; the panel shows them with a warning.
  
  Attribute values an overlay writes, as a source would send them.
  
  - `attributes` (map of values · required)

- `until` (string): The overlay ends at this time.

- `note` (string)

- `origin` (object): Where an imported rule or overlay came from.
  
  - `import` (string · required): What it was imported from, such as the previous search's export.
  
  - `ref` (string · required)

## `$schema`

string

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

## Example

```json title="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](/docs/overlays)