XML Schema Reference

Book: /product-review-feeds/_book.yaml

Title: XML Schema Reference

The XML schema for Google Product Review Feeds defines the acceptable structure of your XML feed. XML schemas use the .xsd file extension. Like DTD files, an XML schema defines the elements and attributes that can appear in an XML document.

You can learn more about XML schemas from this XML Schema Primer.

The XML schema for product review feeds is published here: http://www.google.com/shopping/reviews/schema/product/2.3/product_reviews.xsd

A description of the feed structure defined by this schema follows. In this description, type names with the prefix xs: refer to built-in XML schema types which are in the XML namespace http://www.w3.org/2001/XMLSchema.

Our system always expects a full feed. Any reviews previously submitted, but not included in your next full feed will be deleted. Therefore, you should always submit all of your reviews when submitting your feed.

Top-level <feed> element

The <feed> element contains these elements in the order listed.

Element Occurrence Type Description
<version> Required (1) xs:string Indicates which version of the product review feed schema is being used. At this time only <version>2.3</version> is supported.
<aggregator> Optional (1) aggregatorType A publisher may use a reviews aggregator to manage reviews and provide the feeds. This element indicates the use of an aggregator and contains information about the aggregator.
<publisher> Required (1) publisherType The information about the publisher, which may be a retailer, manufacturer, reviews service company, or any entity that publishes product reviews.
<reviews> Optional (1) xs:sequence Contains the product reviews.

The <feed> defines uniqueness constraints on elements used in the feed.

Child Elements

<aggregator>

A publisher may use a reviews aggregator to manage reviews and provide the feeds. This element indicates the use of an aggregator and contains information about the aggregator. The <aggregator> element contains these elements in the order listed.

Element Occurrence Type Description
<name> Required (1) nonEmptyStringType The name of the aggregator of the product reviews.

<publisher>

The information about the publisher, which may be a retailer, manufacturer, reviews service company, or any entity that publishes product reviews.The <publisher> element contains these elements in the order listed.

Element Occurrence Type Description
<name> Required (1) nonEmptyStringType The name of the publisher of the product reviews.
<favicon> Optional (1) httpUrlType A link to the company favicon of the publisher. The image dimensions should be favicon size: 16x16 pixels. The image format should be GIF, JPG or PNG.

<reviews>

Contains the product reviews. The <reviews> element contains these elements in the order listed.

Element Occurrence Type Description
<review> Required (1-unlimited) reviewType An individual unique product review. If a review pertains to multiple products in the publisher's inventory, then specify the review once, and include multiple <product> elements in the <products> element.

<review>

An individual unique product review. If a review pertains to multiple products in the publisher's inventory, then specify the review once, and include multiple <product> elements in the <products> element.The <review> element contains these elements in the order listed.

Element Occurrence Type Description
<review_id> Required (1) nonEmptyStringType The permanent, unique identifier for the product review in the publisher’s system.
<reviewer> Required (1) reviewerType The author of the product review.
<review_timestamp> Required (1) xs:dateTime

The timestamp indicating when the review was written.

Examples:

2014-04-21T11:07:07-06:00
2014-04-21T18:00:00+01:00
2014-04-21T00:00:00Z
<title> Optional (1) nonEmptyStringType The title of the review.
<content> Required (1) nonEmptyStringType The content of the review.
<pros> Optional (1) xs:sequence Contains the pros based on the opinion of the reviewer. Omit boilerplate text like "pro:" unless it was written by the reviewer.
<cons> Optional (1) xs:sequence Contains the cons based on the opinion of the reviewer. Omit boilerplate text like "con:" unless it was written by the reviewer.
<reviewer_images> Optional (1) xs:sequence Contains links to images of the product supplied by the reviewer.
<review_url> Required (1) reviewUrlType The URL of the review landing page.
<ratings> Required (1) xs:sequence Contains the ratings associated with the review.
<products> Required (1) xs:sequence Contains the products associated with the review.
<is_spam> Optional (1) xs:boolean Indicates whether the review is marked as spam in the publisher's system.
<collection_method> Optional (1) collectionMethodType

The method used to collect the review. The value must be one of the following:

unsolicited
The user was not responding to a specific solicitation when they submitted the review.
post_fulfillment
The user submitted the review in response to a solicitation after fulfillment of the user's order.
<transaction_id> Optional (1) nonEmptyStringType A permanent, unique identifier for the transaction associated with the review in the publisher's system. This ID can be used to indicate that multiple reviews are associated with the same transaction.

<reviewer>

The author of the product review. The <reviewer> element contains these elements in the order listed.

Element Occurrence Type Description
<name> Required (1) reviewerNameType

The name of the author of the review.

Example:

<name>Jane</name>
<reviewer_id> Optional (1) nonEmptyStringType

A permanent, unique identifier for the author of the review in the publisher’s system.

Example:

<reviewer_id>14295</reviewer_id>

<name>

The name of the author of the review. The <name> element is an extension of the nonEmptyStringType and contains the name or alias of the reviewer. The <name> element contains these attributes.

Attribute Occurrence Type Description
is_anonymous Optional xs:boolean

Indicates whether the reviewer is anonymous.

Example:

<name is_anonymous="true">Anonymous</name>

<pros>

Contains the pros based on the opinion of the reviewer. The <pros> element contains these elements in the order listed.

Element Occurrence Type Description
<pro> Required (1-unlimited) nonEmptyStringType

An individual pro based on the opinion of the reviewer. The pros should be listed in the same order as they are displayed. Omit boilerplate text like "pro:" unless it was written by the reviewer.

Example:

<pros>
  <pro>Sleek design</pro>
</pros>

<cons>

Contains the cons based on the opinion of the reviewer. The <cons> element contains these elements in the order listed.

Element Occurrence Type Description
<con> Required (1-unlimited) nonEmptyStringType

An individual con based on the opinion of the reviewer. The cons should be listed in the same order as they are displayed. Omit boilerplate text like "con:" unless it was written by the reviewer.

Example:

<cons>
  <con>Pricey</con>
</cons>

<review_url>

The URL of the review landing page. The <review_url> element is an extension of the httpUrlType and contains the link to the landing page of the review. The <review_url> element contains these attributes.

Attribute Occurrence Type Description
type Required xs:string

The type must be one of the following:

singleton
The review page contains only this single review.
group
The review page contains a group of reviews including this review.

Example:

<review_url type="singleton">http://www.example.com/review_5.html</review_url>

<reviewer_images>

Contains images of the product supplied by the reviewer. The <reviewer_images> tag contains many <reviewer_image> elements.

Element Occurrence Type Description
<reviewer_image> Required (1-unlimited) reviewImageType

An image of the reviewed product created by the review author.

<reviewer_image>

A single review image element.

Element Occurrence Type Description
<url> Required (1) httpUrlType

A URL to an image of the reviewed product created by the review author. The URL does not have to end with an image file extension.

Example:

<reviewer_images>
  <reviewer_image>
    <url>https://example.com/test.jpg</url>
  </reviewer_image>
  <reviewer_image>
    <url>https://example.com/test.gif</url>
  </reviewer_image>
</reviewer_images>

<ratings>

Contains the ratings associated with the review. The <ratings> element contains these elements in the order listed.

Element Occurrence Type Description
<overall> Required (1) ratingType The reviewer's overall rating of the product.

<overall>

The reviewer's overall rating of the product. The <overall> element extends an xs:decimal simpleType and captures the rating assigned by the reviewer. The value should be within the inclusive range defined by the min and max attributes. The <overall> element contains these attributes.

Attribute Occurrence Type Description
min Required xs:integer The minimum possible number for the rating. This should be the worst possible rating and should not be a value for no rating.
max Required xs:integer The maximum possible number for the rating. The value of the max attribute must be greater than the value of the min attribute.

<products>

Contains the products associated with the review. The <products> element contains these elements in the order listed.

Element Occurrence Type Description
<product> Required (1-unlimited) productType A product associated with the review.

<product>

A product associated with the review. The <product> element contains these elements in the order listed.

Element Occurrence Type Description
<product_ids> Optional (1) productIdsType The identifiers associated with a product.
<product_name> Optional (1) nonEmptyStringType Descriptive name of a product.
<product_url> Required (1) httpUrlType The URL of the product. This URL can have the same value as the <review_url> element, if the review URL and the product URL are the same.

<product_ids>

The identifiers associated with a product. The <product_ids> element contains these elements in the order listed.

Element Occurrence Type Description
<gtins> Required (For all reviews associated with products with a known GTIN to enable full review matching)

Optional (strongly recommended) for all other reviews (1)
gtinsType Contains GTINs (global trade item numbers) associated with a product.
<mpns> Required (MPN should be included to facilitate review matching if the product associated with the review does not have an assigned GTIN. Must be submitted with Brand)

Optional for all other reviews (1)
mpnsType Contains MPNs (manufacturer part numbers) associated with a product.
<skus> Required (SKU should be included to facilitate review matching, if the product associated with the review does not have an assigned GTIN or MPN. Should be submitted with Brand)

Optional for all other reviews (1)
skusType Contains SKUs (stock keeping units) associated with a product. Often this matches the product Offer Id in the product feed.
<brands> Required (Brand should be included to facilitate review matching if the product associated with the review does not have an assigned GTIN. Must be submitted with MPN)

Optional for all other reviews (1)
brandsType Contains brand names associated with a product.
<asins> Optional (1) asinsType Contains ASINs (Amazon Standard Identification Numbers) associated with a product.

<gtins>

Contains GTINs (global trade item numbers) associated with a product. The <gtins> element contains these elements in the order listed.

Element Occurrence Type Description
<gtin> Required (1-unlimited) nonEmptyStringType The product's global trade item number.

<mpns>

Contains MPNs (manufacturer part numbers) associated with a product. The <mpns> element contains these elements in the order listed.

Element Occurrence Type Description
<mpn> Required (1-unlimited) nonEmptyStringType The product’s manufacturer part number.

<skus>

Contains SKUs (stock keeping units) associated with a product. The <skus> element contains these elements in the order listed.

Element Occurrence Type Description
<sku> Required (1-unlimited) nonEmptyStringType The product’s stock keeping unit in the publisher's inventory.

<brands>

Contains brand names associated with a product. The <brands> element contains these elements in the order listed.

Element Occurrence Type Description
<brand> Required (1-unlimited) nonEmptyStringType The brand name of the product.

<asins>

Contains ASINs (Amazon Standard Identification Numbers) associated with a product. The element contains these elements in the order listed.

Element Occurrence Type Description
<asin> Required (1-unlimited) nonEmptyStringType The product's Amazon Standard Identification Number. Each ASIN is 10 characters in length and alphanumeric.