Feed Compatibility Review

This document is in Beta stage and we have try to cover all topics in right hierarchy yet indepth. To make this document better, we need your help. Please give your feedback by rating the stars at the end of each topic. For more updates join slack channel #unbxd-knowledgebase

Use this document for internal purpose only. It is not suppose to be shared with customers

In the Feed compatibility review stage we try to the understand feed in terms of compatibility with the Unbxd system. In other words, we try to understand if a given feed has all the attributes and relationships which are mandatory to be ingested by the Unbxd database. Before we start with how to check if a feed is compatible with Unbxd format, we need to learn what is Unbxd feed format. As per Unbxd feed specification, processed feed ( ready to upload in Unbxd database) should look like this

 {
  "feed": {
    "catalog": {
      "add": {
        "items": [
          {
            "uniqueId": "ss10010",
            "title": "Short Sleeve Shirt",
            "description": "Get the perfect look for the summer.",
            "variants" : [
              {
                "variantId":"ff10010",
                "var_size" : "black",
                "var_title" : "Black short sleeve shirt"
              }
            ]
          },
          {
            "uniqueId":"10101",
            "title": "another product title",
            "another_product_field" : "another_key_value"
          },
          {
            "uniqueId":"20345",
            "title": "another product title",
            "another_product_field" : "another_key_value"
          }
        ]
      }
    }
  }
}

A product can contain any number of fields as key and value. Unbxd specifies some of the common product attributes and their data type as follows.

Unbxd Feed Attribute

Field Name	Data Type	Description	Multi Value
uniqueId*	text	Unique identifier of a product. It cannot have special character except '-' and '_'	FALSE
discount	decimal	Discounts or promotional pricing for a product	FALSE
rating	decimal	Unique identifier of a product. It cannot have special character except '-' and '_'	FALSE
currency	text	Unique identifier of a product. It cannot have special character except '-' and '_'	FALSE
catlevel1Name	text	The first level of products. Denotes hierarchy of products on your catalog	FALSE
catlevel2Name	text	The second level of products. Denotes hierarchy of products on your catalog	FALSE
catlevel3Name	text	The third level of products. Denotes hierarchy of products on your catalog	FALSE
catlevel4Name	text	The fourth level of products. Denotes hierarchy of products on your catalog	FALSE
category	text	Denotes the category of the product	TRUE
subCategory	text	Denotes the name of the second level of the hierarchy of the product	TRUE
color	text	Specifies the available colors for a product	TRUE
size	text	Specifies the available sizes for a product	TRUE
availability	bool	Specifies the product’s inventory status	FALSE
description	longText	Is the detailed account of the salient aspects, characteristics or features of a product	FALSE
imageUrl	link	Link to image library	TRUE
productUrl	link	Link to the Product Detail Page (PDP) of a product	FALSE
brand	text	Distinctive name or label of the manufacturer of the product	FALSE
price	decimal	The amount of money a customer pays for a product	FALSE
title	text	Short or summarized description of a product. Precedes the description	FALSE
gender	text	Denotes availability of the product for the two sexes	FALSE
skus	skus	Stock Keeping Unit (sku) is a number assigned to a product by a retail store to identify the price, product options and manufacturer of the merchandise	FALSE
variantId	text	Unique identifier of a variant, if any. It cannot have special character except ‘-’ and ‘_’. Note: It needs to be unique across entire product catalog	FALSE
variants	text	Field holding all the variants for a product	TRUE
categoryPath*	path	The category hierarchy a product belongs to. Different values present need to be separated using “>”. For example, “Men>Shoes>Casual Shoes”	TRUE
categoryPathId	text	The category comprises of names and IDs, a product belongs to.Different values present need to be separated using “>”. IDs and Names need to be separated using “\|”. For example, “cat100\|Home>cat101\|Luggage & Travel Accessories>cat102\|Travel Accessories”	TRUE
sellingPrice	decimal	The amount of money at which a product or service is sold.	FALSE

When you index a feed then Unbxd system analyze the feed and auto generate some extra attributes which are important for better search and browse results. Lets take a look at this with an example

http://search.unbxd.io/c7673ac5cc288b2c548d3f2c8ba0f58a/prod-gb-worldofbooks808001561540321/search?q=*

In the response of the above search API, you will find products with

User defined feed attributes

uniqueId: uniqueId of a product
variantId: variantId of a variant
productUrl: PDP link of a product
price: price of a product

System generated Feed attributed

Better categorisation and browsing
- categoryPath1 : List of all level 1 categories a product belongs to
- categoryPath2 : List of all level 2 categories a product belongs to
- categoryPath3 : List of all level 3 categories a product belongs to and so on
- categoryPath1_fq : List of all fully qualified level 1 categories a product belong to
- categoryPath2_fq : List of all fully qualified level 2 categories a product belong to
- categoryPath3_fq : List of all fully qualified level 3 categories a product belong to and so on

All of the above attributes are generated by breaking down the path present in categoryPath or categoryPathId attribute

For Better Relevancy
- relevantDocument : This attribute can hold either parent or variant as a value. Value parent means, parent product is more relevant to the search query. If variant then first variant in the variant array is more relevant

For more information on fields of search API, take a look at this topic. << Search API response Topic >>

Summary Video

Did you find it useful? Rate it

Feed Review Process

Product uniqueId

Having uniqueId is mandatory for every product. Look at the feed and check which attribute could be treated as uniqueId of a product. More often than not, SKU of a product is treated as uniqueId of a product

Feed Review Question

If you can not determine which attribute can be the uniqueId then you have a feed review question - Which field in the feed should be considered as uniqueId ?

Exercise

Exercise 1

sku,title,description,image,product_url,price,discount
"BON1234","Black Tshirt","Black tshirt made up of cotton", "https://dummyurl.com/black-t-shirt/img.jpg","https://dummyurl.com/black-t-shirt",100,20
"BON1235","Red Tshirt","Red tshirt made up of cotton", "https://dummyurl.com/red-t-shirt/img.jpg","https://dummyurl.com/red-t-shirt",100,20
"BON1236","Green Tshirt","Green tshirt made up of cotton", "https://dummyurl.com/green-t-shirt/img.jpg","https://dummyurl.com/green-t-shirt",100,20
"BON1237","Pink Tshirt","Pink tshirt made up of cotton", "https://dummyurl.com/pink-t-shirt/img.jpg","https://dummyurl.com/pink-t-shirt",100,20

Question: Which of the attribute in the above field could be treated as uniqueId ?

See Answer

sku, as it is a unique identifier of the products in the catalog

Exercise 2

productId,title,description,image,product_url,price,discount
"4321ANC","Pink Tshirt","Pink tshirt made up of cotton", "https://dummyurl.com/pink-t-shirt/img.jpg","https://dummyurl.com/pink-t-shirt",100,20
"654AMIT","Green Tshirt","Green tshirt made up of cotton", "https://dummyurl.com/green-t-shirt/img.jpg","https://dummyurl.com/green-t-shirt",100,20
"876BCVF","Red Tshirt","Red tshirt made up of cotton", "https://dummyurl.com/red-t-shirt/img.jpg","https://dummyurl.com/red-t-shirt",100,20
"098ABD","Black Tshirt","Black tshirt made up of cotton", "https://dummyurl.com/black-t-shirt/img.jpg","https://dummyurl.com/black-t-shirt",100,20

Question: Which of the attribute in the above field could be treated as uniqueId ?

See Answer

productId, as it is a unique identifier of the products in the catalog

Did you find it useful? Rate it

Variant Definition

When reviewing the feed, knowing how to figure out the variants is really important for feed indexing and avoiding rework. If you do not have this information, you can either ask the customer or TPMs of the project.

More often than not, this information ( which product is a variant of which product ) is provided by having

An extra attribute like parentId
A group by key like BaseProductId
In a separate file contains the variant of a product

Example of variant logic using parentId

Consider this sample feed


productId,size,title,description,image,product_url,price,discount,parentId
"4321ANC","small","Pink Tshirt","Pink tshirt made up of cotton", "https://dummyurl.com/pink-t-shirt/img.jpg","https://dummyurl.com/pink-t-shirt",100,20, NULL
"4321DBC","medium","Green Tshirt","Pink tshirt made up of cotton", "https://dummyurl.com/green-t-shirt/img.jpg","https://dummyurl.com/green-t-shirt",100,20, 4321ANC
"4321FGH","small","red Tshirt","Red tshirt made up of cotton", "https://dummyurl.com/red-t-shirt/img.jpg","https://dummyurl.com/red-t-shirt",100,20, 4321ANC
"098ABD","Black Tshirt","Black tshirt made up of cotton", "https://dummyurl.com/black-t-shirt/img.jpg","https://dummyurl.com/black-t-shirt",100,20, NULL

Take a look at a new attribute parentId. Following are the observations could be made

Product with productId 4321DBC, 4321FGH are the variants of the product 4321ANC as their parentId is the productId.
Product 4321ANC is the parent product as its parentId is NULL.
Product with productId 098ABD is a parent product but does not have any variants in the feed.

Example of variant logic using baseProductId or similar field

baseProductId, productId,size,title,description,image,product_url,price,discount,parentId
"UUIDABCFDS12345","4321ANC","small","Pink Tshirt","Pink tshirt made up of cotton", "https://dummyurl.com/pink-t-shirt/img.jpg","https://dummyurl.com/pink-t-shirt",100,20, NULL
"UUIDABCFDS12345","4321DBC","medium","Green Tshirt","Pink tshirt made up of cotton", "https://dummyurl.com/green-t-shirt/img.jpg","https://dummyurl.com/green-t-shirt",100,20, 4321ANC
"UUIDABCFDS12345","4321FGH","small","red Tshirt","Red tshirt made up of cotton", "https://dummyurl.com/red-t-shirt/img.jpg","https://dummyurl.com/red-t-shirt",100,20, 4321ANC
"GIDDABCD562345","098ABD","Black Tshirt","Black tshirt made up of cotton", "https://dummyurl.com/black-t-shirt/img.jpg","https://dummyurl.com/black-t-shirt",100,20, NULL

Take a look at new attribute baseProductId. Following are the observations could be made

Products having baseProductId UUIDABCFDS12345 need to be clubbed together as they belong to the same group.
Product with productId 4321ANC is the parent product as its parentId is NULL
Product with productId 4321DBC, 4321FGH are the variants of the product 4321ANC as their parentId is the productId.

Example of variants in separate block or file itself

Sample product feed file 1

productId,size,title,description,image,product_url,price,discount
"098ABD","Black Tshirt","Black tshirt made up of cotton", "https://dummyurl.com/black-t-shirt/img.jpg","https://dummyurl.com/black-t-shirt",100,20
"4321ANC","Pink Tshirt","Pink tshirt made up of cotton", "https://dummyurl.com/pink-t-shirt/img.jpg","https://dummyurl.com/pink-t-shirt",100,20
"654AMIT","Green Tshirt","Green tshirt made up of cotton", "https://dummyurl.com/green-t-shirt/img.jpg","https://dummyurl.com/green-t-shirt",100,20
"876BCVF","Red Tshirt","Red tshirt made up of cotton", "https://dummyurl.com/red-t-shirt/img.jpg","https://dummyurl.com/red-t-shirt",100,20

Sample product feed file 2 ( which contains variants of above products )

productId,size,title,description,image,product_url,price,discount, parentProductId
"098MNO","medium","Black Tshirt","Black tshirt made up of cotton", "https://dummyurl.com/black-t-shirt/img.jpg","https://dummyurl.com/black-t-shirt",100,20,"098ABD"
"4321OKN","medium,"Pink Tshirt","Pink tshirt made up of cotton", "https://dummyurl.com/pink-t-shirt/img.jpg","https://dummyurl.com/pink-t-shirt",100,20,"4321ANC"
"654ALPO","medium,"Green Tshirt","Green tshirt made up of cotton", "https://dummyurl.com/green-t-shirt/img.jpg","https://dummyurl.com/green-t-shirt",100,20,"654AMIT"
"876BNVB","medium","Red Tshirt","Red tshirt made up of cotton", "https://dummyurl.com/red-t-shirt/img.jpg","https://dummyurl.com/red-t-shirt",100,20,"876BCVF"

As you can see the first feed contains the master products while another feed contains the variants of the product. Following observations could be made

Attribute parentProductId in second feed is establishing the relationship between master product and its variants
Product with productId 098ABD has a variant with productId 098MNO as its parentProductId is the productId of the master product. Similarly for other products as well.

TIP: Whether you are able to find the variant logic or not, you need to confirm this from TPM or through the customer directly

Feed Review Question

If you can not determine the logic of variants then it become your feed review question - How to identify variants in the feed

Did you find it useful? Rate it

Category Information

Almost all e-commerce systems organize their products in the form of categories. While reviewing the feed, it is important to understand the category data and structure. Each product in the feed should contain all the categories a product belongs to. Most of the time, this information is not provided in the unbxd format. So while developing a feed processing script, we may need to parse the data in this category field and process it. Category Information could be provided in two ways

Category information as category Names
Category information as category Ids and names combined.

The feed should have information about all the categories a product belongs to either through category Names or along with category Ids as well.

Feed Review Question

If you can not determine the category information about the product then it become your feed review question - How to determine the categories a product belong to

Exercise

Exercise 1

Consider this sample feed


productId,size,title,description,image,categories
"098ABD","small","Black Tshirt","Black tshirt made up of cotton", "https://dummyurl.com/black-t-shirt/img.jpg", "home>womens,home>womens>topwear"
"4321ANC","small","Pink Tshirt","Pink tshirt made up of cotton", "https://dummyurl.com/pink-t-shirt/img.jpg", "home>insale,home>newproducts"
"654AMIT","small","Green Tshirt","Green tshirt made up of cotton", "https://dummyurl.com/green-t-shirt/img.jpg", "home>newproducts"
"876BCVF","small","Red Tshirt","Red tshirt made up of cotton", "https://dummyurl.com/red-t-shirt/img.jpg", "home>heavydiscounts"

Question: What are the different categories a product with product Id 098ABD ?

See Answer

It belongs to 2 categories, first is “home>Womens” , second is “home>womens”>topwear”

Did you find it useful? Rate it

Title, Description and other fields

In the feed, check if title and description fields are present. If these fields are not present in all or in some of the products then raise this as a feed review question to the customer or TPM of the project.

Feed Review Question

If you can not determine the title and description about the product then it become your feed review question - What are the fields to determine title and description of a product

Exercise

Exercise 1

Consider this sample feed


productId,size,title,description,image,categoriesids
"098ABD","small","Black Tshirt","Black tshirt made up of cotton", "https://dummyurl.com/black-t-shirt/img.jpg", "home>womens,home>womens>topwear"
"4321ANC","small","Pink Tshirt","Pink tshirt made up of cotton", "https://dummyurl.com/pink-t-shirt/img.jpg", "home>insale,home>newproducts"
"654AMIT","small","Green Tshirt","Green tshirt made up of cotton", "https://dummyurl.com/green-t-shirt/img.jpg", "home>newproducts"
"876BCVF","small","Red Tshirt","Red tshirt made up of cotton", "https://dummyurl.com/red-t-shirt/img.jpg", "home>heavydiscounts"

Question: What is the title and description of the product with product id “098ABD”?

See Answer

Title is “Black Tshirt” and Description is “Black tshirt made up of cotton”

Did you find it useful? Rate it

Price & Availability field

Most of the time price field would be present but could have data type as string “100” instead of 100. So you can ask this to change it to integer from string. If it can not be done so, while writing a feed conversion script, you need to make the changes in this field. The availability flag shows whether a product is available in the catalog or not. Sometimes you will find the name of this attribute as “availability” or some time different like in stock. If it is so then you can change the name of the field to “availability“. Availability accepts its value as True or False. So change it accordingly.

Exercise

Exercise 1

Consider this sample feed

productId,size,title,description,categoriesids,instock,price
"098ABD","small","Black Tshirt","Black tshirt made up of cotton", "home>womens,home>womens>topwear", "no","100"
"4321ANC","small","Pink Tshirt","Pink tshirt made up of cotton", "home>insale,home>newproducts","yes","200"
"654AMIT","small","Green Tshirt","Green tshirt made up of cotton", "home>newproducts","yes", "300"
"876BCVF","small","Red Tshirt","Red tshirt made up of cotton", "home>heavydiscounts","no","400"

Question : Which of the attribute in the given feed could be considered as availability?

See Answer

instock attribute could be considered as availability

Question : Having attribute price as string in the feed is ok or do we need to do any conversion?

See Answer

Yes, we need to convert price information from string to decimal

Did you find it useful? Rate it

ImageUrl and ProductUrl

Unbxd supports multiple images of a product and should be mapped to the field imageUrl. Most of the time, the name of this attribute is not sent as imageUrl rather as image or productImage. We need to change the name of this field to imageUrl and combine all values of the image URL in an array. productUrl refers to the URL of the PDP page. While reviewing the feed you need to identify the attribute which contains this value and rename this attribute to productUrl. It is a single value field.

Did you find it useful? Rate it

Product Overview

Feed Review

Feed & Schema Processing

Feed Indexing

Search & Browse API

Analytics

Recommendation Widgets

AutoSuggest

First Integration

Inter Team Cordination

Take Customer Live

Account Handover

Unbxd Feed Attribute

User defined feed attributes

System generated Feed attributed

Summary Video

Feed Review Process

Product uniqueId

Exercise

Exercise 1

Exercise 2

Variant Definition

Category Information

Exercise

Exercise 1

Title, Description and other fields

Exercise

Exercise 1

Price & Availability field

Exercise

Exercise 1

ImageUrl and ProductUrl