# patterns.json

Query patterns that become filters.

## `patterns`

array of objects

Phrases that, found in a query, become filters. A placeholder captures a number for a numeric attribute, in the attribute's unit, or for a numeric built-in field, `price`, `delivery_days` or `rating`: `{width} x {depth}` turns "160 x 230" into width 160 and depth 230, and "lieferung in \{delivery_days\} tagen" read `at_most` a delivery time. For an option attribute it reads one of the values the attribute lists, by its code, a label or an alias, always exactly: `{load_index}{speed_index}` turns "91V" and "91 V" into load index 91 and speed index V. A placeholder written against a word or another placeholder may have a space between them, so `R{rim}` reads "R16" and "R 16".

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

- `description` (string)

- `phrases` (array of strings or map of arrays of strings · required): The phrases, matched like rule conditions after normalization. A plain list holds in every language.

- `captures` (string or object): How a captured number filters. Default: `exact`.
  
  How a captured number filters: `"exact"`, `"at_most"`, `"at_least"`, or `{ "within": 5 }` for a tolerance either way.
  
  - `exact`
  
  - `at_most`
  
  - `at_least`
  
  - `within` (number)

- `filter` (object): Filters the pattern adds besides its captures, such as `{ "shape": "round" }`.
  
  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](#filter) · at least 1 item): At least one of these holds.
  
  - `all` ([array of objects](#filter) · at least 1 item): All of these hold; useful inside `any`.
  
  - `not` ([object](#filter)): 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.

## `built_in`

object

The built-in patterns, each on unless switched off here.

The built-in patterns a merchant can switch off. Both are on by default.

- `quantity` (boolean): A number with a unit, such as "bis 220 cm", filters the one attribute that measures it. Default: on.

- `price` (boolean): A price in the channel's currency, such as "unter 200 €", filters the price. Default: on.

## `$schema`

string

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

## Example

```json title="tests/fixtures/home/patterns.json (trimmed)"
{
  "$schema": "../../../contracts/schema/patterns.json",
  "patterns": [
    {
      "id": "width-by-depth",
      "description": "A size such as 160 x 230 that is no size value: width and depth within 5 cm",
      "phrases": ["{width}x{depth}", "{width} x {depth}"],
      "captures": { "within": 5 }
    },
    {
      "id": "round-diameter",
      "description": "A diameter such as ø 120 or 120 cm rund: diameter within 5 cm, shape round",
      "phrases": {
        "de": ["ø {diameter}", "ø{diameter}"],
        "en": ["ø {diameter}", "ø{diameter}"]
      },
      "captures": { "within": 5 },
      "filter": { "shape": "round" }
    }
  ]
}
```

**Guide:** [Patterns](/docs/patterns)