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
stringRequired
The entity's type, such as product.
id
stringRequired
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.
The id of a category node, such as wohnen/sofas: the merchant's id of a category entity.
The starting order within the category; rules override it.
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.
The merchant's id of an entity, unique per type, such as SOFA-LUND-3. It travels unchanged; OrbSearch never rewrites it.
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.
The merchant's id of an entity, unique per type, such as SOFA-LUND-3. It travels unchanged; OrbSearch never rewrites it.
A plain value, or a map from locale to value such as { "de": "Farbe", "en": "Color" }.
A plain value, or a map from locale to value such as { "de": "Farbe", "en": "Color" }.
Price and availability per channel.
Price and availability of a variant, or of an entity without variants, in one channel.
8 fields
A channel's id, such as de or ch: a market or storefront.
The reduced price, valid within sale_window if one is given.
An ISO 4217 currency code, such as EUR.
One of in_stock, out_of_stock, preorder or backorder.
The reduced price, valid within sale_window if one is given.
An ISO 4217 currency code, such as EUR.
One of in_stock, out_of_stock, preorder or backorder.
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.
A channel's id, such as de or ch: a market or storefront.
The reduced price, valid within sale_window if one is given.
An ISO 4217 currency code, such as EUR.
One of in_stock, out_of_stock, preorder or backorder.
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.
A point in time as RFC 3339 with an offset, such as 2026-11-27T00:00:00+01:00.
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.
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
{
"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