# entity.json

Anything that can be found: a product, a category, a guide, a brand or an entity of the merchant's own type.

Every type shares this shape; a type's capabilities decide which of the type-specific fields it may use.

## `type`

string · required

The entity's type, such as `product`.

## `id`

string · required

The merchant's id, unique per type.

## `title`

string or map of strings

The name shoppers see. A plain string is in the source's locale.

## `url`

string or map of strings

The merchant's own URL for the entity. OrbSearch never generates one when the merchant supplies it.

## `description`

string or map of strings

A plain value, or a map from locale to value such as \{ "de": "Farbe", "en": "Color" \}.

## `image`

string

The main image's URL.

## `images`

array of strings

Further image URLs.

## `keywords`

array of strings or map of arrays of strings

Extra search terms from the merchant.

## `categories`

array of (string or object)

The categories the entity sits in. The first is primary for breadcrumbs unless one is marked `primary`.

A category the entity sits in: its id, or an object with the id, the position in that category and whether it is the primary category.

- `id` (string): The id of a category node, such as `wohnen/sofas`: the merchant's id of a `category` entity.

- `position` (integer): The starting order within the category; rules override it.

- `primary` (boolean)

## `attributes`

map of values

The merchant's data, as the source sends it; the attribute definitions say what each value means.

## `relations`

map of arrays of (string or object)

Links to other entities, interpreted by the relation definitions.

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

- `qualifiers` (object)

## `signals`

map of (boolean, number or string)

Numbers and dates for ranking that shoppers never see, such as `sales_30d` or `released_at`.

## `brand`

string

Products: the brand's name or id; the `brand` relation resolves it to a brand entity.

## `varies_by`

array of strings

Products: the attributes the variants differ by, such as `["color", "size"]`.

## `variants`

array of objects

Products: the buyable variations, one level deep. A product without variants has one implicit variant with the product's id.

A buyable variation of a product. Its axis values, the attributes named in the product's `varies_by`, are unique within the product.

- `id` (string · required): The merchant's id of an entity, unique per type, such as `SOFA-LUND-3`. It travels unchanged; OrbSearch never rewrites it.

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

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

- `image` (string)

- `images` (array of strings)

- `attributes` (map of values)

- `offers` (array of objects): Price and availability per channel.
  
  Price and availability of a variant, or of an entity without variants, in one channel.
  
  - `channel` (string · required): A channel's id, such as `de` or `ch`: a market or storefront.
  
  - `price` (number)
  
  - `sale_price` (number): The reduced price, valid within `sale_window` if one is given.
  
  - `sale_window` (object): A window in time: from `from` (inclusive) until `until` (exclusive). Either end may be open.
    
    - `from` (string): A point in time as RFC 3339 with an offset, such as `2026-11-27T00:00:00+01:00`.
    
    - `until` (string): A point in time as RFC 3339 with an offset, such as `2026-11-27T00:00:00+01:00`.
  
  - `currency` (string): An ISO 4217 currency code, such as `EUR`.
  
  - `availability` (string): One of `in_stock`, `out_of_stock`, `preorder` or `backorder`.
  
  - `stock` (integer)
  
  - `delivery_days` (object): How many days delivery takes, from the earliest to the latest.
    
    - `min` (integer · required)
    
    - `max` (integer · required)

- `price` (number)

- `sale_price` (number): The reduced price, valid within `sale_window` if one is given.

- `sale_window` (object): A window in time: from `from` (inclusive) until `until` (exclusive). Either end may be open.
  
  - `from` (string): A point in time as RFC 3339 with an offset, such as `2026-11-27T00:00:00+01:00`.
  
  - `until` (string): A point in time as RFC 3339 with an offset, such as `2026-11-27T00:00:00+01:00`.

- `currency` (string): An ISO 4217 currency code, such as `EUR`.

- `availability` (string): One of `in_stock`, `out_of_stock`, `preorder` or `backorder`.

- `stock` (integer)

- `delivery_days` (object): How many days delivery takes, from the earliest to the latest.
  
  - `min` (integer · required)
  
  - `max` (integer · required)

## `offers`

array of objects

Types with offers but without variants, such as services: price and availability per channel.

Price and availability of a variant, or of an entity without variants, in one channel.

- `channel` (string · required): A channel's id, such as `de` or `ch`: a market or storefront.

- `price` (number)

- `sale_price` (number): The reduced price, valid within `sale_window` if one is given.

- `sale_window` (object): A window in time: from `from` (inclusive) until `until` (exclusive). Either end may be open.
  
  - `from` (string): A point in time as RFC 3339 with an offset, such as `2026-11-27T00:00:00+01:00`.
  
  - `until` (string): A point in time as RFC 3339 with an offset, such as `2026-11-27T00:00:00+01:00`.

- `currency` (string): An ISO 4217 currency code, such as `EUR`.

- `availability` (string): One of `in_stock`, `out_of_stock`, `preorder` or `backorder`.

- `stock` (integer)

- `delivery_days` (object): How many days delivery takes, from the earliest to the latest.
  
  - `min` (integer · required)
  
  - `max` (integer · required)

## `price`

number

## `sale_price`

number

The reduced price, valid within `sale_window` if one is given.

## `sale_window`

object

A window in time: from `from` (inclusive) until `until` (exclusive). Either end may be open.

- `from` (string): A point in time as RFC 3339 with an offset, such as `2026-11-27T00:00:00+01:00`.

- `until` (string): A point in time as RFC 3339 with an offset, such as `2026-11-27T00:00:00+01:00`.

## `currency`

string

An ISO 4217 currency code, such as `EUR`.

## `availability`

string

One of `in_stock`, `out_of_stock`, `preorder` or `backorder`.

## `stock`

integer

## `delivery_days`

object

How many days delivery takes, from the earliest to the latest.

- `min` (integer · required)

- `max` (integer · required)

## `parent`

string

Categories: the parent node; a node without a parent is a root.

## `path`

string or map of strings

Categories: the merchant's URL path per locale.

## `channels`

array of strings

Categories: the channels the node exists in. Without it, the node exists in every channel.

## `body`

string or map of strings

Content: the full text.

## `kind`

string

Content: what kind of content it is, such as `guide` or `banner`.

## `logo`

string

Brands: the logo's URL.

## `aliases`

array of strings

Brands: other spellings of the brand's name, such as `Robert Bosch GmbH`.

## Example

```json title="tests/fixtures/home/catalog.jsonl (one line)"
{
  "type": "product",
  "id": "SOFA-ASKA-2",
  "title": {
    "de": "Aska 2-Sitzer-Sofa aus Samt",
    "en": "Aska two-seater velvet sofa"
  },
  "url": { "de": "/p/aska-2-sitzer-sofa", "en": "/en/p/aska-two-seater-sofa" },
  "description": {
    "de": "Kompaktes Sofa für kleine Wohnzimmer, mit Samtbezug und schmalen Armlehnen.",
    "en": "A compact sofa for small living rooms, with a velvet cover and slim arms."
  },
  "image": "https://images.example/home/sofa-aska-2.jpg",
  "brand": "Halvard",
  "categories": ["wohnen/sofas"],
  "attributes": {
    "seats": 2,
    "width": "164 cm",
    "depth": "86 cm",
    "height": "78 cm",
    "seat_height": "45 cm",
    "upholstery": "Samt",
    "material": ["Holzwerkstoff", "Samt"],
    "style": "modern",
    "room": ["Wohnzimmer"]
  },
  "varies_by": ["color"],
  "variants": [
    {
      "id": "SOFA-ASKA-2-GRAU",
      "attributes": { "color": "Grau" },
      "price": 749,
      "currency": "EUR",
      "availability": "in_stock",
      "stock": 12,
      "delivery_days": { "min": 3, "max": 5 }
    },
    {
      "id": "SOFA-ASKA-2-SALBEI",
      "attributes": { "color": "Salbei" },
      "price": 749,
      "sale_price": 649,
      "currency": "EUR",
      "availability": "in_stock",
      "stock": 4,
      "delivery_days": { "min": 3, "max": 5 }
    }
  ],
  "signals": {
    "sales_30d": 61,
    "rating": 4.3,
    "rating_count": 118,
    "released_at": "2025-09-01"
  }
}
```

**Guide:** [OrbSearch JSON Lines](/docs/formats#orbsearch-json-lines)