# ranking.json

Signals and weights, boost and bury strengths, sort options and section order.

## `signals`

array of objects

How each signal is read before it is weighted.

A signal and how it is normalized into the business score.

- `code` (string · required): The code of a signal, such as `sales_30d` or `rating`.

- `direction` (string · required): - `higher_is_better`
  
  - `lower_is_better`
  
  - `newer_is_better`: For dates: the more recent, the better.

- `normalize` ("percentile" or object · required): How a signal becomes a number between 0 and 1.
  
  - `damped` (object): An average pulled towards the mean while few votes back it, such as a rating with few reviews.
    
    - `count_signal` (string · required): The signal that counts the votes, such as `rating_count`. It is read from the catalog and needs no definition of its own.
    
    - `prior_count` (integer · required): How many votes count as much as the mean.
  
  - `half_life_days` (integer): Halves its effect every this many days; for dates.

## `weights`

map of maps of numbers

Per type, the weight of each signal in the business score. A weight change needs an index run.

## `strengths`

object

The multipliers behind the strengths `slight`, `medium` and `strong`.

The multipliers of each strength. Boosts above 1, buries below.

- `boost` (object · required): - `slight` (number · required)
  
  - `medium` (number · required)
  
  - `strong` (number · required)

- `bury` (object · required): - `slight` (number · required)
  
  - `medium` (number · required)
  
  - `strong` (number · required)

## `sorts`

array of objects

The sort options pages may offer besides `relevance`.

A sort option, such as `price_asc` over `price`.

- `code` (string · required): The code of a sort option, such as `price_asc`. `relevance` is built in.

- `label` (string or map of strings): A plain value, or a map from locale to value such as \{ "de": "Farbe", "en": "Color" \}.

- `by` (string · required): `price`, `delivery_days`, `discount` (the reduction a sale gives, in percent of the regular price), a sortable `attributes.<code>`, or `signals.<code>` of a defined signal.

- `direction` (string · required): One of `asc` or `desc`.

## `sections`

array of strings

The order of sections in mixed results. Types not listed follow in the order of `types.json`.

## `$schema`

string

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

## Example

```json title="tests/fixtures/home/ranking.json (trimmed)"
{
  "$schema": "../../../contracts/schema/ranking.json",
  "signals": [
    {
      "code": "sales_30d",
      "direction": "higher_is_better",
      "normalize": "percentile"
    }
  ],
  "weights": { "product": { "rating": 0.3, "released_at": 0.2, "sales_30d": 0.5 } },
  "sorts": [
    {
      "code": "price_asc",
      "label": { "de": "Preis aufsteigend", "en": "Price: low to high" },
      "by": "price",
      "direction": "asc"
    }
  ],
  "sections": ["category"]
}
```

**Guide:** [Ranking](/docs/ranking)