# categories.json The facets and sort options of search and category pages. ## `default` object What search pages and every category use unless a node says otherwise. The facets and sort options of a page. - `facets` (array of (string or object)): The facets in display order. A facet on a page: a field code such as `"color"`, or an object that also says how it is shown. A field code alone is shown as `default` shows it, or in the field's natural kind. - `field` (string): An attribute code, or one of `category`, `brand`, `price`, `on_sale`, `availability` and `delivery_days`, which reads the latest day of delivery. - `kind` (string): How the facet is shown. Default: the field's natural kind, such as a list for options and a range for numbers. - `list` - `swatch` - `hierarchical` - `range` - `buckets` - `toggle` - `relative`: Dates relative to the request's time, such as "new in the last 30 days". Bucket bounds are days. - `buckets` (array of objects): The bounds of `buckets` and `relative` facets, in ascending order. A bucket from `from` (inclusive) to `to` (exclusive); either end may be open. Without `from`, a bucket counts everything up to its `to`, as in "up to 2 weeks"; without `to`, everything from its `from` on, as in "4 stars and more". Such open buckets may overlap. - `from` (number) - `to` (number) - `label` (string or map of strings): A plain value, or a map from locale to value such as \{ "de": "Farbe", "en": "Color" \}. - `show` (string): Options: show the values, or the groups they belong to. - `values`: Options: show the values, or the groups they belong to. - `groups`: Options: show the values, or the groups they belong to. - `order` (string): The order of a facet's values. Default: most results first; buckets keep their own order; grades, buttons and a select keep the order the values are listed in. - `count`: Most results first. - `value_order`: The order of the attribute's values. - `label`: Alphabetical by label. - `single` (boolean): One value at most, chosen from a radio group with "Any" first, such as a delivery time whose buckets overlap. - `description` (string or map of strings): Text shown under the facet's name and read with it, such as what a delivery time counts from. Never a tooltip. - `headings` (array of objects): Parts of the list under headings of their own, such as "Wood" above oak and walnut, in order. Values no heading names follow the last one. A heading inside a facet and the values it stands above. - `label` (string or map of strings · required): A plain value, or a map from locale to value such as \{ "de": "Farbe", "en": "Color" \}. - `values` (array of strings · required): Value codes, or group codes where the facet shows groups, in display order. - `search` (boolean): A search box above the values, for long lists such as brands. - `limit` (integer · at least 1): The most values a list or swatch carries with the page before `more` says there are others: the most frequent ones, and every chosen one. Default: the limit [`facet_values`](/docs/reference/limits#facet_values). A select or a scale that shows every value raises it. - `display` (string): How the values look beyond their kind. Default: the kind's own look; a rating shows stars. - `slider`: A range: a two-thumb slider above the two inputs, which stay. - `histogram`: A range over the price: a slider with the distribution of the prices drawn behind it, in the bins of a fixed ladder of preferred numbers (`histogram` of the response). Prices that fall in a single bin get the plain slider. - `stars`: A rating: stars beside each bucket; its words carry the meaning. - `grades`: An option's values on badges in their own swatch colors, such as the energy label's A to G, in the order the values are listed. Every listed value needs a swatch. - `buttons`: Values or buckets as a wrap of toggle buttons, such as sizes. - `select`: One value at most, chosen from one native select with "Any" first, for a long ordered list such as a tyre width. - `images`: Each value's image beside its name: a brand's logo, or the image an option's value carries, such as an icon. - `custom_display` (string): A storefront display of the shop's own, by the name the shop registered it under, such as `color_tiles`. A storefront without it draws `display`, or the kind's own look, so `display` keeps what it means for the data. - `groups` (array of objects): Facets drawn together under one heading. Several of a page's facets under one heading, such as a tyre's width, ratio and rim as "Tyre size". The facets keep their own settings in `facets`; a group only says which belong together. It stands where the first of them stands on the page and draws them in its own order, and a page that lists fewer than two of them draws them apart. Each facet is counted under the choices of the others, as every facet is, and the page counts the group whole or not at all. - `group` (string · required): Names the group in the response and the trace. - `label` (string or map of strings · required): The heading. - `facets` (array of strings · at least 2 items · required): The fields of its facets, at least two, each in one group at most. - `display` (string): How the group is drawn. Default: its facets one under the other beneath the heading. - `finder`: One select beside the next, each with "Any" first and every value counted under the choices of the others, such as a tyre's width, ratio and rim. Each of its facets is shown as `select`. - `sort` (object): The sort options a page offers. `relevance` is built in; the others are defined in `ranking.json`. - `default` (string): The order a page starts with, where the shopper chose none and the request has no words, which rank by relevance. The nearest node up the tree that sets one decides; the layout's `default` is the last. Default: `relevance`. - `options` (array of strings): The orders a shopper can choose, in display order. A page offers those of the nearest node that lists some, or the layout's `default`. ## `nodes` array of objects Settings per category node. A node inherits from its parent and overrides only what differs. One category node's settings. - `category` (string · required): The id of a category node, such as `wohnen/sofas`: the merchant's id of a `category` entity. - `facets` (array of (string or object)): The facets in display order; replaces the inherited list. A facet on a page: a field code such as `"color"`, or an object that also says how it is shown. A field code alone is shown as `default` shows it, or in the field's natural kind. - `field` (string): An attribute code, or one of `category`, `brand`, `price`, `on_sale`, `availability` and `delivery_days`, which reads the latest day of delivery. - `kind` (string): How the facet is shown. Default: the field's natural kind, such as a list for options and a range for numbers. - `list` - `swatch` - `hierarchical` - `range` - `buckets` - `toggle` - `relative`: Dates relative to the request's time, such as "new in the last 30 days". Bucket bounds are days. - `buckets` (array of objects): The bounds of `buckets` and `relative` facets, in ascending order. A bucket from `from` (inclusive) to `to` (exclusive); either end may be open. Without `from`, a bucket counts everything up to its `to`, as in "up to 2 weeks"; without `to`, everything from its `from` on, as in "4 stars and more". Such open buckets may overlap. - `from` (number) - `to` (number) - `label` (string or map of strings): A plain value, or a map from locale to value such as \{ "de": "Farbe", "en": "Color" \}. - `show` (string): Options: show the values, or the groups they belong to. - `values`: Options: show the values, or the groups they belong to. - `groups`: Options: show the values, or the groups they belong to. - `order` (string): The order of a facet's values. Default: most results first; buckets keep their own order; grades, buttons and a select keep the order the values are listed in. - `count`: Most results first. - `value_order`: The order of the attribute's values. - `label`: Alphabetical by label. - `single` (boolean): One value at most, chosen from a radio group with "Any" first, such as a delivery time whose buckets overlap. - `description` (string or map of strings): Text shown under the facet's name and read with it, such as what a delivery time counts from. Never a tooltip. - `headings` (array of objects): Parts of the list under headings of their own, such as "Wood" above oak and walnut, in order. Values no heading names follow the last one. A heading inside a facet and the values it stands above. - `label` (string or map of strings · required): A plain value, or a map from locale to value such as \{ "de": "Farbe", "en": "Color" \}. - `values` (array of strings · required): Value codes, or group codes where the facet shows groups, in display order. - `search` (boolean): A search box above the values, for long lists such as brands. - `limit` (integer · at least 1): The most values a list or swatch carries with the page before `more` says there are others: the most frequent ones, and every chosen one. Default: the limit [`facet_values`](/docs/reference/limits#facet_values). A select or a scale that shows every value raises it. - `display` (string): How the values look beyond their kind. Default: the kind's own look; a rating shows stars. - `slider`: A range: a two-thumb slider above the two inputs, which stay. - `histogram`: A range over the price: a slider with the distribution of the prices drawn behind it, in the bins of a fixed ladder of preferred numbers (`histogram` of the response). Prices that fall in a single bin get the plain slider. - `stars`: A rating: stars beside each bucket; its words carry the meaning. - `grades`: An option's values on badges in their own swatch colors, such as the energy label's A to G, in the order the values are listed. Every listed value needs a swatch. - `buttons`: Values or buckets as a wrap of toggle buttons, such as sizes. - `select`: One value at most, chosen from one native select with "Any" first, for a long ordered list such as a tyre width. - `images`: Each value's image beside its name: a brand's logo, or the image an option's value carries, such as an icon. - `custom_display` (string): A storefront display of the shop's own, by the name the shop registered it under, such as `color_tiles`. A storefront without it draws `display`, or the kind's own look, so `display` keeps what it means for the data. - `groups` (array of objects): Facets drawn together under one heading; replaces the inherited groups, and an empty list leaves the page without any. Several of a page's facets under one heading, such as a tyre's width, ratio and rim as "Tyre size". The facets keep their own settings in `facets`; a group only says which belong together. It stands where the first of them stands on the page and draws them in its own order, and a page that lists fewer than two of them draws them apart. Each facet is counted under the choices of the others, as every facet is, and the page counts the group whole or not at all. - `group` (string · required): Names the group in the response and the trace. - `label` (string or map of strings · required): The heading. - `facets` (array of strings · at least 2 items · required): The fields of its facets, at least two, each in one group at most. - `display` (string): How the group is drawn. Default: its facets one under the other beneath the heading. - `finder`: One select beside the next, each with "Any" first and every value counted under the choices of the others, such as a tyre's width, ratio and rim. Each of its facets is shown as `select`. - `sort` (object): The sort options a page offers. `relevance` is built in; the others are defined in `ranking.json`. - `default` (string): The order a page starts with, where the shopper chose none and the request has no words, which rank by relevance. The nearest node up the tree that sets one decides; the layout's `default` is the last. Default: `relevance`. - `options` (array of strings): The orders a shopper can choose, in display order. A page offers those of the nearest node that lists some, or the layout's `default`. - `where` (object): A smart category: entities matching this selector belong to the node, in addition to those assigned in the catalog. "Sale" is `{ "on_sale": true }`. 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](#nodes.where) · at least 1 item): At least one of these holds. - `all` ([array of objects](#nodes.where) · at least 1 item): All of these hold; useful inside `any`. - `not` ([object](#nodes.where)): This does not hold. - `` (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. - `filter_pages` (array of arrays of strings): The filter pages of the node and the categories below it, from the combinations `routes.json` lists: `[["gender"]]` narrows them, `[]` leaves none. Default: the parent's. ## `$schema` string The JSON Schema an editor checks this file against; kept as written. ## Example ```json title="tests/fixtures/home/categories.json (trimmed)" { "$schema": "../../../contracts/schema/categories.json", "default": { "facets": ["category", { "field": "price", "display": "histogram" }], "sort": { "default": "relevance", "options": ["relevance", "price_asc"] } }, "nodes": [ { "category": "wohnen/sofas", "facets": [ "width", { "field": "seats", "kind": "list", "display": "buttons" } ] }, { "category": "wohnen/sessel", "facets": ["width", { "field": "seats", "kind": "list" }] } ] } ``` **Guide:** [Pages and their filters](/docs/pages)