Object types and relationships

A catalog holds more than products. Category pages, brand pages and editorial content can be indexed and returned by discovery.

Each object declares what it is in @type, and its identity carries the same type as a prefix. Discovery requests ask for one type at a time.

The types

@type	What it represents	Typical use
product	Something a shopper can buy	Search results, recommendations, listing pages
category	A navigational grouping	Category suggestions in autocomplete, category landing pages
brand	A brand and its landing page	Brand suggestions, brand pages
article	Editorial or help content	Guides and posts alongside product results
query	A popular search phrase stored as an object	Query suggestions in autocomplete

The list is a convention rather than a closed set — a catalog can be configured with other types. What is fixed is that the prefix in @id must equal @type, so product/123 cannot be indexed as a category.

For a query object, the identity value is the phrase, because a query has no other key.

Asking for one type at a time

Every search, collections and recommendation request carries a required type field. One request returns one type of object:

# Products matching "running shoes"
curl -X POST 'https://api.eu1.luigisbox.ai/discovery/v1/search?channel_id=lbn_4hj9tv&surface_id=lbs_search_main' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Lbx-Visitor-Id: 8f14e45f-ea0f-4b5c-9a1d-2b3c4d5e6f70' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "product", "query": "running shoes" }'

An autocomplete panel that shows products, categories and suggested phrases issues three requests — one per type — and renders them into three sections. Each type has its own ranking and its own result count.

How objects relate to each other

Objects link by identity. A product does not embed its category or brand; it points at them.

{
  "@id": "product/sku-1001",
  "@type": "product",
  "@title": "Blue Cotton T-Shirt",
  "@category": ["category/shirts", "category/summer"],
  "@brand": "brand/northwear"
}

The referenced objects live on their own:

{
  "@id": "category/shirts",
  "@type": "category",
  "@title": "Shirts"
}

Two consequences:

• A link does not need to resolve at ingestion time. You can send a product feed before the category feed. Nothing is rejected for pointing at an object that does not exist yet, and nothing has to be re-sent once it does.
• Renaming a category is one write. Because products hold only the link, changing a category title updates one object rather than every product in it.

Categories additionally link to each other, with @parent — see Hierarchies.

To turn those links into displayable data in one round trip, fetch the linked objects with object lookup instead of issuing one request per link.

Variants

Variants are not a separate type. Every variant is a complete product with its own identity; members of one variant group share an opaque @group_id. See Product variants.

See also

• Catalog object model — fields, namespaces, visibility
• Identifiers — the <type>/<value> identity format
• Feeds overview — one feed per object type
• Object lookup — resolving references