Product modeling guide¶
This guide includes examples of how to model product data outside of the fashion and lifestyle industries with the Vodayo Elevate data model.
Data model overview¶
The data model of Voyado Elevate has three levels: product group, product, and variant. Each level has associated predefined attributes. For more information about the levels, their requirements, and their attributes, see Format specification.
Product group¶
A product group represents a collection of products that primarily vary in color or style. There may or may not be a different title for each of these products – in the example below, the color name is not part of the title.
Product¶
The product represents the unique color – or style difference – across the group. The imagery is at the product level and there are some required key attributes at this level.
Variant¶
The variants for each product (color or style) represent the SKUs that can be bought. For fashion and lifestyle, the SKU is the size of the product. The price and stock values are defined at this level.
Elevate response object¶
When modeling products, it is important to consider the structure of the Elevate query responses, especially for the category/landing pages (product lists) and the search results page.
For these pages, Elevate returns an array of product groups where each product group contain the products and their respective variants. Within each product group, the first product returned is the main one to be rendered. All the other products in that same group are also returned, to allow them to be rendered in a suitable way in order to show other products that are also available.
In the image below there are 4 product groups where the first product in each group is rendered as the primary product, and the remaining products in each group (if any) are rendered as thumbnails.
Homeware¶
Homeware is a broad industry that includes products that can range from photo albums to kitchen supplies to decorative cushions. The following example includes homeware products from the kitchen supplies segment - mixing bowls.
As seen below, mixing bowls can vary in size/volume, and each size can have different color alternatives. The products can be modeled as follows:
The blue rectangle represents the product group level. The green rectangle represents the product level. The pink rectangle represents the variant level. In this case, each mixing bowl size encompasses the entire product group. Each color alternative from each size encompasses both the product and the variant level, although there must still be a product and a variant for each. This modeling is in order to present the products in a list page as shown in the illustration below:
This example makes some assumptions about the retailer's requirements:
- Mixing bowls for each color and size combination are to be presented as separate entries on the product list page.
- Color variations for a mixing bowl of a particular size can be viewed as thumbnails underneath the default color for that bowl.
- When presenting the product cards on the product list page, the title must include the color and the size information.
Product group¶
In this particular case, a product group represents products that all have the same size/volume, and the distinguishing feature for the products is the color.
The different sizes of mixing bowls are slightly different visually, and the retailer wants to have a clear distinguishing title for each product.
Product¶
The product's imagery is provided at the product data level and each product represents a color-alternative in the group. Given the retailer’s requirements on how the products should appear in the product list page, each color (of a particular size common to the group) is modeled as a separate product with a separate title.
Variant¶
In this instance, there is no difference between the product and the variant – each color of mixing bowl has exactly one SKU. The model requires a product and a variant, so each product will have exactly one variant. The variant level will have the price and stock values.
Do not use label or sizes if there is only one variant per product.
Data feed example¶
Homeware example feed
<?xml version='1.0' encoding='UTF-8'?>
<data_import type="full">
<modify market="TEST" locale="en-US">
<product_groups>
<add_or_replace>
<product_group key="PG1">
<brand>Test</brand>
<department>Kitchenware</department>
<products>
<product key="PG1_P1">
<title>Blue mixing bowl 1,5L</title>
<url>/kitchenware/bowls/PG1_P1</url>
<release_date>2022-01-10T00:00:00Z</release_date>
<description>BPA free mixing bowl.</description>
<images>
<image>
<urls>
<url>//images/bluemixingbowl15.jpg</url>
</urls>
</image>
<!-- other images of 1,5L blue mixing bowls-->
</images>
<color_default>#0000FF</color_default>
<volume>
<amount>1.5</amount>
<unit>l</unit>
</volume>
<variants>
<variant key="PG1_P1_V1">
<stock_number>12</stock_number>
<selling_price>12.00</selling_price>
<list_price>12.00</list_price>
</variant>
</variants>
</product>
<product key="PG1_P2">
<title>Red mixing bowl 1,5L</title>
<url>/kitchenware/bowls/PG1_P2</url>
<release_date>2022-01-10T00:00:00Z</release_date>
<description>BPA free mixing bowl.</description>
<images>
<image>
<urls>
<url>//images/redmixingbowl15.jpg</url>
</urls>
</image>
<!-- other images of 1,5L red mixing bowls-->
</images>
<color_default>#FF0000</color_default>
<volume>
<amount>1.5</amount>
<unit>l</unit>
</volume>
<variants>
<variant key="PG1_P2_V1">
<stock_number>10</stock_number>
<selling_price>12.00</selling_price>
<list_price>12.00</list_price>
</variant>
</variants>
</product>
<!--The other colors of the 1,5 L mixing bowls as product and variant entities-->
</products>
</product_group>
<product_group key="PG2">
<brand>Test</brand>
<department>Kitchenware</department>
<products>
<product key="PG2_P1">
<title>Blue mixing bowl 0,5L</title>
<url>/kitchenware/bowls/PG2_P1</url>
<release_date>2022-01-10T00:00:00Z</release_date>
<description>BPA free mixing bowl.</description>
<images>
<image>
<urls>
<url>//images/bluemixingbowl05.jpg</url>
</urls>
</image>
<!-- other images of 0,5L blue mixing bowls-->
</images>
<color_default>#0000FF</color_default>
<volume>
<amount>0.5</amount>
<unit>l</unit>
</volume>
<variants>
<variant key="PG2_P1_V1">
<stock_number>12</stock_number>
<selling_price>5.00</selling_price>
<list_price>5.00</list_price>
</variant>
</variants>
</product>
<product key="PG2_P2">
<title>Red mixing bowl 0,5L</title>
<url>/kitchenware/bowls/PG2_P2</url>
<release_date>2022-01-10T00:00:00Z</release_date>
<description>BPA free mixing bowl.</description>
<images>
<image>
<urls>
<url>//images/redmixingbowl05.jpg</url>
</urls>
</image>
<!-- other images of 0,5L red mixing bowls-->
</images>
<color_default>#FF0000</color_default>
<volume>
<amount>0.5</amount>
<unit>l</unit>
</volume>
<variants>
<variant key="PG2_P2_V1">
<stock_number>10</stock_number>
<selling_price>5.00</selling_price>
<list_price>5.00</list_price>
</variant>
</variants>
</product>
<!--The other colors of the 1,5 L mixing bowls as product and variant entities-->
</products>
</product_group>
</add_or_replace>
</product_groups>
</modify>
</data_import>
DIY¶
The DIY (Do-it-yourself) industry is another broad industry with everything needed to complete small or large projects around ones home, from screws to bathroom fixtures, paint cans and welding equipment.
In the example below, screws have different property types. They may visually all look quite similar but have different specifications. The products can be modeled as follows:
The blue rectangle represents the product group level. The green rectangle represents the product level. The pink rectangle represents the variant level. In this case, each type of screw is modeled as a product group. The different size dimensions for each type are modeled across the product and variant level.
This modeling is in order to present the products in a list page as shown in the illustration below:
This example makes some assumptions about the retailer's requirements:
- Each different type of screw should be shown only once in a list page. Unlike in the Homeware example, the size is not part of the product’s title at this level.
- The visitor must be able to filter the list by length or diameter.
Product group¶
To fulfill the requirement of having each type of screw showing up once in the product listing page, they need to be modeled as separate product groups with the supress_duplicates attribute enabled. This will ensure that the product group is only represented once in the Elevate API response.
It is possible to have an acid-proof wooden screw and a regular wooden screw in the same product group; for this modeling option the supress_duplicates flag should be disabled.
Each dimension for each screw type will be shown in different product cards in the product listing page.
Product¶
The visitor must have the option to filter the list by diameter and length. Therefore, these differences must be represented at product level, which supports typed custom attributes and predefined attributes for this task. Hence, each combination of dimension and length alternative is modeled as a unique product.
Variant¶
In this instance, there is no difference between the product and the variant – each screw type of a particular size is also the SKU. The stock values and price will be set at the variant level even when there is only one variant.
Data feed example¶
DIY example feed
<?xml version='1.0' encoding='UTF-8'?>
<data_import type="full">
<modify market="TEST" locale="en-US">
<product_groups>
<add_or_replace>
<product_group key="PG1">
<brand>Test</brand>
<department>Construction</department>
<products suppress_duplicates="true">
<product key="PG1_P1">
<title>Acid Proof Wooden screw</title>
<url>/construction/screw/PG1_P1</url>
<release_date>2022-01-10T00:00:00Z</release_date>
<description>Acid proof screw for wood with dimension 3,5 x 20mm</description>
<images>
<image>
<urls>
<url>//images/acidproof1.jpg</url>
</urls>
</image>
<!-- other images of acid proof screw size 3,5x20 mm-->
</images>
<length>
<amount>20</amount>
<unit>mm</unit>
</length>
<custom>
<lengths>
<diameter>
<amount>3.5</amount>
<unit>mm</unit>
</diameter>
</lengths>
</custom>
<variants>
<variant key="PG1_P1_V1">
<stock_number>1200</stock_number>
<selling_price>15.00</selling_price>
<list_price>15.00</list_price>
</variant>
</variants>
</product>
<product key="PG1_P2">
<title>Acid Proof Wooden screw</title>
<url>/construction/screw/PG1_P2</url>
<release_date>2022-01-10T00:00:00Z</release_date>
<description>Acid proof screw for wood with dimension 3,5 x 30mm.</description>
<images>
<image>
<urls>
<url>//images/acidproof2.jpg</url>
</urls>
</image>
<!-- other images of acid proof screw size 3,5x30mm -->
</images>
<length>
<amount>30</amount>
<unit>mm</unit>
</length>
<custom>
<lengths>
<diameter>
<amount>3.5</amount>
<unit>mm</unit>
</diameter>
</lengths>
</custom>
<variants>
<variant key="PG1_P2_V1">
<stock_number>100</stock_number>
<selling_price>20.00</selling_price>
<list_price>20.00</list_price>
</variant>
</variants>
</product>
<!--The other dimensions/sizes of the acid proof wooden screw as product and variant entities-->
</products>
</product_group>
<product_group key="PG2">
<brand>Test</brand>
<department>Construction</department>
<products suppress_duplicates="true">
<product key="PG2_P1">
<title>Wooden Screw</title>
<url>/construction/screw/PG2_P1</url>
<release_date>2022-01-10T00:00:00Z</release_date>
<description>Wooden screw with dimension 3,5x20mm.</description>
<images>
<image>
<urls>
<url>//images/woodenscrew1.jpg</url>
</urls>
</image>
<!-- other images of wooden screw with size 3,5x20mm-->
</images>
<length>
<amount>20</amount>
<unit>mm</unit>
</length>
<custom>
<lengths>
<diameter>
<amount>3.5</amount>
<unit>mm</unit>
</diameter>
</lengths>
</custom>
<variants>
<variant key="PG2_P1_V1">
<stock_number>200</stock_number>
<selling_price>6.00</selling_price>
<list_price>6.00</list_price>
</variant>
</variants>
</product>
<product key="PG2_P2">
<title>Wooden Screw</title>
<url>/construction/screw/PG2_P2</url>
<release_date>2022-01-10T00:00:00Z</release_date>
<description>Wooden screw with dimension 3,5x30mm</description>
<images>
<image>
<urls>
<url>//images/woodenscrew2.jpg</url>
</urls>
</image>
<!-- other images of wooden screw with size 3,5x30mm-->
</images>
<length>
<amount>30</amount>
<unit>mm</unit>
</length>
<custom>
<lengths>
<diameter>
<amount>3.5</amount>
<unit>mm</unit>
</diameter>
</lengths>
</custom>
<variants>
<variant key="PG2_P2_V1">
<stock_number>100</stock_number>
<selling_price>6.50</selling_price>
<list_price>6.50</list_price>
</variant>
</variants>
</product>
<!--The other dimensions/sizes of the wooden screw as product and variant entities-->
</products>
</product_group>
</add_or_replace>
</product_groups>
</modify>
</data_import>
Summary¶
When modeling the products into the Elevate 4 format, the following principles are recommended:
- Identify the variations across the items, to determine how to model between product group and product.
- Does the product title on the list page contain the size? If so, then the Homeware model example may be the best option, where the product group consists of products with the same size.
- Is only one product from the same product group required on the list page? If so, then use the
suppress_duplicatesattribute for that group. - Consider the filtering / faceting options required on a list page. If there is more than one size entity required, such as diameter and length, then the DIY model example may be the best option, since custom attributes at product level are required.