XML schema and data requirements

You must use the appropriate elements and attributes within the XML feed file. The primary feed elements include:

Feed: The root container that defines the file's metadata, including the client name, schema version, and whether the upload is a full or incremental update.
Brands: A parent element used to define the manufacturers in your catalog. Each brand must have a unique ExternalId and a consumer-facing display name.
Categories: A required element that establishes your site’s organizational structure. It allows you to map products to specific groups and create hierarchical parent/child relationships.
Products: The core element of the feed. It defines individual items using unique ExternalId values, names, descriptions, and URLs to ensure customer transactions are accurately matched to the correct product pages.

Note: If you use any non-required elements or attributes for your products, please include them in your XML feed file.

Feed elements

This element is required. The following table identifies required attributes for the <Feed> element.

Attribute	Description
xmlns	Schema reference. Set this value to http://www.bazaarvoice.com/xs/PRR/ProductFeed/15.1.
name	The short version of your Bazaarvoice client name.
extractDate	A timestamp that should be populated automatically in the XML DateTime format.
incremental	Whether the feed includes all catalog data. If you are uploading a data feed that contains your entire product catalog, set this value to false.
supplemental	Whether the feed contains supplemental catalog data. This feed type should be used only when providing multiple catalog sources.

Example feed elements

Copy Code

XML

<Feed xmlns="http://www.bazaarvoice.com/xs/PRR/ProductFeed/15.1" 
name="ExampleClient" incremental="false" 
extractDate="2016-01-18T12:00:00">

Brands elements

You can declare all product brands in the <Brands> element using these child elements:

Element Value

Element	Value
`Brand`	Represents a product brand in your feed and must contain the following `<ExternalId>` and `<Name>` or `<Names>` child elements. You can include the removed="true" attribute in the `<Brand>` element to mark the brand inactive.
`ExternalId`	Unique brand ID that can contain only alphanumeric characters, hyphens (`-`), and underscores (`_`). If a brand ID contains an invalid character, replace it with an alternate character, such as an underscore. This format is used in the data feed only and does not affect end users. The ID is case insensitive, so you cannot use IDs that match except for case. Ensure the ID is a stable ID that will not change for the same logical brand, even if the name of the brand changes.
`Name` or `Names`	Name of the brand, which is visible to end users. If specifying localized brand names in a multilingual implementation, include a `<Name>` element for each locale in a parent `<Names>` element, and then specify the locale attribute (of type String) for each `<Name>` child element.

Brand

Represents a product brand in your feed and must contain the following <ExternalId> and <Name> or <Names> child elements.

You can include the removed="true" attribute in the <Brand> element to mark the brand inactive.

ExternalId

Unique brand ID that can contain only alphanumeric characters, hyphens (-), and underscores (_). If a brand ID contains an invalid character, replace it with an alternate character, such as an underscore. This format is used in the data feed only and does not affect end users. The ID is case insensitive, so you cannot use IDs that match except for case.

Ensure the ID is a stable ID that will not change for the same logical brand, even if the name of the brand changes.

Name or Names

Name of the brand, which is visible to end users.

If specifying localized brand names in a multilingual implementation, include a <Name> element for each locale in a parent <Names> element, and then specify the locale attribute (of type String) for each <Name> child element.

Then, when defining products in the <Products> element, you can use the <BrandExternalId> element to reference a brand's ID in the <Brands> element.

Note: Another way to declare brands in your catalog is to use the <Brand> child element in the <Product> element. If needed, you can also use this method instead of using the <Brands> element as described here.

Example brand elements

Copy Code

XML

<Brands>
  <Brand>
    <ExternalId>AAA</ExternalId>
    <Name>First Brand</Name>
  </Brand>
  <Brand>
    <ExternalId>BBB</ExternalId>
    <!-- Default brand name -->
    <Name>Second Brand</Name>
    <!-- Localized brand names -->
    <Names>
      <Name locale="en_CA">Second Brand CA</Name>
      <Name locale="fr_CA">Deuxième marque CA</Name>
    </Names>
  </Brand>
</Brands>
<Products>
  <Product>
    <Name>First Product</Name>
    <ExternalId>Prod-1234</ExternalId>
    <BrandExternalId>
      AAA
    </BrandExternalId>
    ...
  </Product>
</Products>

Categories elements

This element is required. The <Categories> element defines each category that is represented by products in your feed using the following child elements. It can also be used to define a category hierarchy. The maximum allowed category depth is 20 levels. A single category cannot have a chain of parent-to-child relationships that exceeds a total hierarchy depth of 20

Element	Value	Required
`Category`	Represents a product category in your feed and may include other elements listed in this table. You can include the removed="true" attribute in the `<Category>` element to mark the category inactive.	Yes
`ExternalId`	Unique category or subcategory ID that can contain only alphanumeric characters, hyphens (`-`), and underscores (`_`). If a category ID contains an invalid character, replace it with an alternate character, such as an underscore. This format is used in the data feed only and does not affect end users. The ID is case insensitive, so you cannot use IDs that match except for case. Ensure that the category ID is stable and will not change, even if the name of the category changes.	Yes
`ParentExternalId`	Parent category's ID of the subcategory in question.	No
`Name` or `Names`	Name of the category or subcategory, which is visible to end users. If specifying localized categories in a multilingual implementation, include a `<Name>` element for each locale in a parent `<Names>` element, and then specify the locale attribute (of type String) for each `<Name>` child element.	Yes
`CategoryPageUrl` or `CategoryPageUrls`	Unique URL for the category or subcategory. When specifying a URL, be aware of the following: Do not include extraneous query string parameters that you might use for tracking and partnership codes. If the URL contains a reserved (special) character, you must URL-encode the character. For example, use `&amp` for an ampersand, use `%20` for a space, or use `%5B` and `%5D` for square brackets ([ ]). If specifying localized categories in a multilingual implementation, include a `<CategoryPageUrl>` element for each locale in a parent `<CategoryPageUrls>` element, and then specify the locale attribute (of type String) for each `<CategoryPageUrl>` child element.	Only if collecting Questions & Answers content at the Category level
`ImageUrl` or `ImageUrls`	Unique URL for the category or subcategory image, which is usually hosted on your website or a content delivery network. When specifying a URL, be aware of the following: If the URL contains a reserved (special) character, you must URL-encode the character. For example, use `&amp` for an ampersand, use `%20` for a space, or use `%5B` and `%5D` for square brackets ([ ]). If specifying localized categories in a multilingual implementation, include an `<ImageUrl>` element for each locale in a parent `<ImageUrls>` element, and then specify the locale attribute (of type String) for each `<ImageUrl>` child element. Note: If Ratings & Reviews is deployed on an HTTPS site, you must provide image URLs at an HTTPS location in your product catalog. If you do not, your customers will see a mixed content warning.	Only if collecting Questions & Answers content at the Category level

Example categories elements

Copy Code

XML

<Categories>
  <Category>
    <ExternalId>1010</ExternalId>
    <!-- Default category name -->
    <Name>First Category</Name>
    <!-- Localized category names -->
    <Names>
      <Name locale="en_CA">First Category CA</Name>
      <Name locale="fr_CA">Première catégorie CA</Name>
    </Names>
    <!-- Default category page URL -->
    <CategoryPageUrl>
      http://www.example.com/category.htm?cat=1010
    </CategoryPageUrl>
    <!-- Localized category page URLs -->
    <CategoryPageUrls>
      <CategoryPageUrl locale="en_CA">
        http://www.example.ca/en_ca/category.htm?cat=1010
      </CategoryPageUrl>
      <CategoryPageUrl locale="fr_CA">
        http://www.example.ca/fr_ca/category.htm?prod=1010
      </CategoryPageUrl>
    </CategoryPageUrls>
    <!-- Default category image URL -->
    <ImageUrl>http://images.example.com/catimages/1010.gif</ImageUrl>
    <!-- Localized category image URLs -->
    <ImageUrls>
      <ImageUrl locale="en_CA">
        http://images.example.ca/en_ca/catimages/1010.gif
      </ImageUrl>
      <ImageUrl locale="fr_CA">
        http://images.example.ca/fr_ca/catimages/1010.gif
      </ImageUrl>
    </ImageUrls>
  </Category>
  <Category>
    <ExternalId>1020</ExternalId>
    <Name>Second Category</Name>
    <CategoryPageUrl>
      http://www.example.com/category.htm?cat=1020
    </CategoryPageUrl>
    <ImageUrl>http://images.example.com/catimages/1020.gif</ImageUrl>
  </Category>
  <Category>
    <ExternalId>1021</ExternalId>
    <ParentExternalId>
      1020
    </ParentExternalId>
    <Name>Sub Category</Name>
    <CategoryPageUrl>
      http://www.example.com/category.htm?cat=1021
    </CategoryPageUrl>
    <ImageUrl>http://images.example.com/catimages/1021.gif</ImageUrl>
  </Category>
</Categories>

Define a product category hierarchy

Use the following two key elements to define a product category hierarchy in your XML file:

<CategoryExternalId>: Assigns a product to a specific category.
<ParentExternalId>: Designates a category's parent, effectively building the organizational structure.

Be aware of the following if you are providing multiple feeds for your catalog data:

A product that appears in multiple feeds must be in the same category in all feeds. Therefore, if product A is in category X in Feed A, then product A cannot be in category Y in Feed B.
A category that is listed in multiple feeds must be in the same parent category in all feeds. Therefore, if category A is in parent category X in Feed A, then category A cannot be in parent category Y in Feed B.

The following example XML file demonstrates how to define a category using <CategoryExternalId> and then nest it using the <ParentExternalId> element.

Copy Code

XML

<Categories>
   <Category>
      <ExternalId>food-1123</ExternalId>
       <Name>Food</Name>            <= no parent category; this is a top-level hierarchy element
         ...
   </Category>
   <Category>
      <ExternalId>fruit-1789</ExternalId>
      <Name>Fruit</Name>
      <ParentExternalId>food-1123</ParentExternalId>         <= "Fruit" category is a child of category “Food”
      ...
   </Category>
</Categories>
<Products>
   <Product>
      <ExternalId>123</ExternalId>
      <Name>Apple</Name>
      <CategoryExternalId>fruit-1789</CategoryExternalId>      <= belongs to category “Fruit”
      ...
   </Product>
   ...
</Products>

Products elements

<Products> is a required parent element that defines each product in your feed using the common child elements shown in the following table. Refer to the product feed XML schema Opens in new tab for a complete list of available elements.

Element	Value	Required
`Product`	Represents a product in your feed and may include other elements listed in this table. You can include the removed="true" attribute in the `<Product>` element to mark the product inactive. If the product does not exist in the database and is marked inactive, it is not added to the database.	Yes
`ExternalId`	Unique product ID that can contain only alphanumeric characters, hyphens (`-`), and underscores (`_`). If the external product ID contains an invalid character, replace it with an alternate character, such as an underscore. The ID is case insensitive, so you cannot use IDs that match except for case. This format is used in the data feed only and is not visible to end users.	Yes, one for each product
`Name` or `Names`	Name or names of the product, which is visible to end users. If specifying localized product names in a multilingual implementation, include a `<Name>` element for each locale in a parent `<Names>` element, and then specify the locale attribute (of type String) for each `<Name>` child element.	Yes, one for each locale
`Description` or `Descriptions`	Description of the product. We recommend that product descriptions be at least three sentences or 300 characters long. If specifying localized product descriptions in a multilingual implementation, include a `<Description>` element for each locale in a parent `<Descriptions>` element, and then specify the locale attribute (of type String) for each `<Description>` child element.	Yes, one for each locale
`Brand`	The name of the brand to which the product belongs. You must include a `<Name>` child element, to specify the brand name. Note: Specify either `<Brand>` or `<BrandExternalId>` in the `<Product>` element, but do not specify both.	Yes, one per product, if `<BrandExternalId>` is not provided
`BrandExternalId`	ID of the brand to which the product belongs. Specify this element if a brand is declared as a separate element in the `<Brands>` block. The value of `<BrandExternalId>` must match a brand ID defined in the `<Brands>` block. If the `<Brands>` block is not defined in the product feed, use `<Brand>` (above) instead. Note: Specify either `<BrandExternalId>` or `<Brand>` in the `<Product>` element, but do not specify both.	Yes, one per product, if `<Brand>` is not provided
`CategoryExternalId`	Category or subcategory ID for the product. Specify this element if a category is declared as a separate element in the `<Categories>` block. The value of `<CategoryExternalId>` must match a category ID defined in the `<Categories>` block. If the `<Categories>` block is not defined in the product feed, use `<CategoryPath>` (below) instead. Note: Specify either `<CategoryExternalId>` or `<CategoryPath>` in the `<Product>` element, but you cannot specify both.	Yes, one per product
`CategoryPath`	A list of categories ordered by hierarchy. Each category must be specified in a `<CategoryName>` child element. You can specify multiple `<CategoryName>` child elements, each for a subcategory of the `<CategoryName>` immediately above it. Note: Specify either `<CategoryPath>` or `<CategoryExternalId>` in the `<Product>` element, but you cannot specify both.	Recommended, one per product
`ProductPageUrl` or `ProductPageUrls`	Unique, uncorrupted URL for a product page. Do not include extraneous query string parameters that you might use for tracking and partnership codes. When specifying a URL, be aware of the following: If the URL contains a reserved (special) character, you must URL-encode the character. For example, use `&amp` for an ampersand, use `%20` for a space, or use `%5B` and `%5D` for square brackets ([ ]). If specifying localized URLs in a multilingual implementation, include a `<ProductPageUrl>` element for each locale in a parent `<ProductPageUrls>` element, and then specify the locale attribute (of type String) for each `<ProductPageUrl>` child element.	Yes, one per locale
`ImageUrl` or `ImageUrls`	Unique URL for the product image. The optimal but slightly flexible display size is 600 x 600 pixels. When specifying a URL, be aware of the following: If the URL contains a reserved (special) character, you must URL-encode the character. For example, use `&amp` for an ampersand, use `%20` for a space, or use `%5B` and `%5D` for square brackets ([ ]). If specifying localized images in a multilingual implementation, include an `<ImageUrl>` element for each locale in a parent `<ImageUrls>` element, and then specify the locale attribute (of type String) for each `<ImageUrl>` child element. Note: If Ratings & Reviews is deployed on an HTTPS site, you must provide image URLs at an HTTPS location in your product catalog. If you do not, your customers will see a mixed content warning.	Yes, one per locale
`ModelNumbers`	Unique referencing code that businesses use to identify a part that a particular industry uses. Specify a `<ModelNumber>` child element for each model number you want to define. Each model number can contain letters, numerals, and other characters.	No; if included, one per product
`ManufacturerPartNumbers`	Manufacturer-specific part number. Specify a `<ManufacturerPartNumber>` child element for each part number you want to define. Part numbers can contain letters, numerals, and characters.	Yes; you can specify an unlimited number of child elements
`EANs` (Common product identifier)	European Article Numbers (EANs), which are used worldwide for marking retail goods. Specify an `<EAN>` child element for each EAN you want to define, which must be a string of eight numerals or 13 numerals (no letters or other characters are allowed). Remove spaces and hyphens because they disrupt syndication matching. Note: Version 14.3+ of the schema does not enforce length or numerical constraints on UPCs, EANs, and ISBNs. Any string in one of these fields is treated as valid by the product schema. Values in the UPC, EAN, and ISBN fields are validated during the catalog import process, however, and only valid values are stored. You can find the complete syntax for all globally unique identifiers in this example product feed file.	Either `EANs`, `UPCs`, or `ISBNs` is required. Review syndication depends entirely on matching product identifiers between the source and destination products. Missing or mismatched identifiers prevent reviews from syndicating. You can specify an unlimited number of child elements. Syndication matching improves if you specify multiple values.
`UPCs` (Common product identifier)	Universal Product Code (UPC), which is a 6- or 12-digit bar code used for standard retail packaging in the United States. Specify a `<UPC>` child element for each UPC you want to define, which can contain numerals only, with no letters or other characters. Remove spaces and hyphens because they disrupt syndication matching. Note: Version 14.3+ of the schema does not enforce length or numerical constraints on UPCs, EANs, and ISBNs. Any string in one of these fields is treated as valid by the product schema. Values in the UPC, EAN, and ISBN fields are validated during the catalog import process, however, and only valid values are stored. You can find the complete syntax for all globally unique identifiers in this example product feed file.	Either `EANs`, `UPCs`, or `ISBNs` is required. Review syndication depends entirely on matching product identifiers between the source and destination products. Missing or mismatched identifiers prevent reviews from syndicating. You can specify an unlimited number of child elements. Syndication matching improves if you specify multiple values.
`ISBNs` (Common product identifier)	International Standard Book Number (ISBN), which is a 10- or 13-character value used predominantly for media products such as books, music, and videos. Specify an `<ISBN>` child element for each ISBN you want to define. The last character provides a checksum that helps validate the product identifier. Most ISBNs are composed only of digits, except for some 10-character ISBN values that use an X for the checksum.	Either `EANs`, `UPCs`, or `ISBNs` is required. Review syndication depends entirely on matching product identifiers between the source and destination products. Missing or mismatched identifiers prevent reviews from syndicating. You can specify an unlimited number of child elements. Syndication matching improves if you specify multiple values.
`Attributes`	Custom attributes that enable you to define additional product-specific information, to report on product-specific information or to support product families. Specify an `<Attribute>` child element for each product attribute you want to define. Be sure to include the name of the product attribute using the id attribute of the `<Attribute>` element; spaces are not permitted in the attribute ID. The character limit is 32.	No
`Color`	Color of the product.	No; Recommended
`Size`	Size of the product.	No; Recommended
`Material`	Material of the product. For example, steel, plastic, silk, etc.	No; Recommended
`Currency`	Monetary value of the product. This element includes two attributes: Price and CurrencyCode. Note: Currency must be provided in the following format: <Currency Price="10.00" CurrencyCode="USD"></Currency>	No; Recommended
`Availability`	Indicates whether or not a product is available to purchase. It may be out of stock or out of season.	No; Recommended

Example product elements

Copy Code

XML

<Products>
  <Product>
    <ExternalId>11111111111abc</ExternalId>
    <Name>First Product Round with Green</Name>
    <Description>First Product Description Text</Description>
    <BrandExternalId>
      AAA
    </BrandExternalId>
    <CategoryExternalId>1021</CategoryExternalId>
    <ProductPageUrl>
      http://www.example.com/product.htm?prod=2000001
    </ProductPageUrl>
    <ImageUrl>http://images.example.com/prodimages/2000001.gif</ImageUrl>
    <Color>Red
    </Color>
    <Size>L</Size>
    <Material>Denim</Material>
    <Availability>false</Availability>
    <Currency Price="12.99" CurrencyCode="GBP"/>
    <!-- Product details needed for syndication -->
    <ManufacturerPartNumbers>
      <ManufacturerPartNumber>26-12345-8Z</ManufacturerPartNumber>
    </ManufacturerPartNumbers>
    <EANs>
      <EAN>0213354752286</EAN>
      <EAN>0188173724031</EAN>
    </EANs>
    <UPCs>
      <UPC>382157229380</UPC>
      <UPC>28392932<span class="dxhe-searchHI">32</span></ModelNumber>
      <ModelNumber>1235839</ModelNumber>
    </ModelNumbers>
    <ManufacturerPartNumbers>
      <ManufacturerPartNumber>26-12345-8W</ManufacturerPartNumber>
    </ManufacturerPartNumbers>
    <EANs>
      <EAN>0213354752287</EAN>
    </EANs>
    <UPCs>
      <UPC>138313830283</UPC>
    </UPCs>
    <!-- Custom product attributes. The locale attribute on Value is optional:
         omit it for a single value, or repeat Value once per locale. -->
    <Attributes>
      <Attribute id="SAP_STATUS">
        <Value>L</Value>
      </Attribute>
      <!-- Localized custom attribute values -->
      <Attribute id="CARE_INSTRUCTIONS">
        <Value locale="en_CA">Machine wash cold</Value>
        <Value locale="fr_CA">Laver à la machine à l'eau froide</Value>
      </Attribute>
    </Attributes>
  </Product>
</Products>