Using the Preferred Format

Our preferred catalog data format consists of the following 2 to 3 .CSV files

• Products File - Items shown as results on a product listing page (e.g. search result pages, browse pages)
• Groups File - Hierarchy of groups for organizing products
• Variations File - Not all catalogs use variations. Variations refer to sub-items that can be shown as swatches of top level results on a product listing page

note

Some fields below are marked as required (✅), as they are essential to delivering Proof Schedule results. Other fields are marked as optional, but please note that our AI produces stronger learnings when fed more data about your products. Facet and groups fields are especially high leverage product data for optimizing product discovery for your users.

Products File

Field	Required	What
id	✅	Unique id available for the beacon to track (in the DOM or on the window object) across your search results, browse results, and product detail pages
item_name	✅	Display name
image_url	✅	One image URL for the product
group_ids	✅	A pipe-separated list of group ids associated with this product. Each product can belong to one group, multiple groups, or no groups at all. These values must correspond to the group ids provided in the Groups File. For products that don't belong to any group, simply pass an empty string.
facets	✅	Each facet should be in its own field with a name in the format "facet:[facet name]" (e.g. "facet:Material"). When a product has multiple values for a single facet, use pipes (|) to separate values (e.g. "Cotton|Bamboo"). These fields often correspond to the filters that are displayed on search result pages in your current search experience.
url		The URL a user is taken to after selecting an item in autosuggest, search results, browse results, or recommendation pods
description		The item description
keywords		Key terms or phrases that help users find the item, separated by pipes (|)

Example:

"id","item_name","url","image_url","group_ids","facet:product_type","facet:gender","facet:material","metadata:price","description","keywords"
"27","Cotton T-Shirt",https://Krestor/products/mens-cotton-tshirt,"https://Krestor/media/19890103.jpg","mens-tops-athletic|mens-tops-casual","Shirts|T-Shirts","Male","Cotton","18.00","Treat yourself to a comfy upgrade with this Short Sleeve Shirt from Etchell's Emporium. This short-sleeve T-shirt comes with a classic crew-neck, giving you style and comfort that can easily be paired with a variety of bottoms.", "gym|casual|athletic|workout|comfort|simple"

WHY are these fields important for a Proof Schedule?

• id links behavioral tracking data from the beacon with the data provided in this catalog
• group_ids link products to browse pages
• group_ids & facets improve result rankings when fed to our AI
• item_name, image_url, url, & description makes Proof Schedule results demo-able
• item_name, facets, & keywords make items searchable

Groups File

Products are organized into groups. Users view these groups of products on browse pages.

Each item in this file represents a single group (and browse page). A valid group hierarchy has a single top level group with a name like “All” that has a blank parent_id, and all other groups reference a parent group.

Field	Required	What
parent_id	✅	Links this group to its parent group
id	✅	Unique id available for tracking on your browse pages (in the DOM or on the window object)
name	✅	Group display name
url		Browse page url where this group of products is displayed to end users in production

Example:

parent_id,id,name
,1,All
1,2,Jackets
2,1000,Rain Jackets
1000,142,Waterproof
1000,144,Water Resistant
2,1001,Winter Coats
1,3,Pants

Variations File

This does not apply to all catalogs, but it can be helpful to separate a product's data into multiple variations.

Field	Required	What
id	✅	Unique variation ID
product_id	✅	Product ID, must match id field in the products file
image_url	✅	Variation image URL
facets	✅	Each facet should be in its own field with a name in the format "facet:[facet name]" (e.g. "facet:Color"). When a variation has multiple values for a single facet, use pipes (|) to separate values (e.g. "Blue|Red"). These fields often correspond to the filters that are displayed on search result pages in your current search experience.
item_name		variation display name - If this is provided, it will be used instead of the product's item_name
url		The URL a user is taken to after selecting a variation. Not all websites support variation-specific urls - If this is provided, it will be used instead of the product's url

Example:

A shirt that comes in multiple colors would have a single item in the products file with multiple variation items in this file. Each variation item in this file has different values for fields named facet:color and image_url, but has the same value for the product_id field.

"id","product_id","image_url","facet:color"
"xy78n-a","27","https://Krestor/media/19890103.jpg","Blue"
"xy78n-b","27","https://Krestor/media/19890104.jpg","Purple"
"xy78n-c","27","https://Krestor/media/19890105.jpg","Green"