XML Schema

Google provides an XML schema to define the acceptable structure of your XML feed. An XML schema describes the structure of an XML document. XML schemas use the .xsd file extension. Like DTD files, an XML schema defines the elements and attributes that can appear in a document. An element or attribute can be assigned a type which defines the contents of the element or attribute.

The XML schema for merchant review feeds is published here: http://www.google.com/shopping/reviews/schema/merchant/4.0/merchant_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". Each type name is linked to its definition and each container element is also linked to its definition.

  1. Top-level <feed> element
  2. Container elements
    1. <author>
    2. <merchant>
    3. <merchant_info>
    4. <rating_url>
    5. <ratings>
    6. <review>
    7. <review_url>
  3. Types
    1. NonEmptyString
    2. RatingRange

Top-level <feed> element

The top-level element of a feed is the <feed> element.

The <feed> element should have these XML attributes:

Attribute Value Description
xmlns http://schemas.google.com/merchant_reviews/4.0 Specifies the default XML namespace for all elements in the feed.
xmlns:xsi http://www.w3.org/2001/XMLSchema-instance Defines the xsi: XML namespace prefix.
xsi:schemaLocation http://schemas.google.com/merchant_reviews/4.0 http://www.google.com/shopping/reviews/schema/merchant/4.0/merchant_reviews.xsd Specifies the location of the XML schema for the feed.

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

Element Occurrences Description
<author> Required (1) Contains information about the author of the feed.
<merchant> Required repeated (1–unbounded) Each <merchant> element contains information and reviews for one merchant.

Container elements

The structure of the feed is determined by the following elements which contain attributes and elements.

<author>

The <author> element contains these elements in any order:

Element Type Occurrences Description
<name> NonEmptyString Required (1) The business name of the feed author.
Example: <name>Merchant Reviews Inc.</name>
<email> NonEmptyString Optional (0–1) An email address to contact the feed author.
Example: <email>contact@example.com</email>

<merchant>

The <merchant> element has this attribute:

Attribute Type Use Description
id NonEmptyString Required A permanent, unique identifier for the merchant in your system.
Example: <merchant id="29574">

The <merchant> element contains these elements in the order listed:

Element Type Occurrences Description
<merchant_info> Required (1) Contains information about the merchant.
<review> Repeated (0–unbounded) Each <review> element contains information about one review of the merchant.
<deleted_review_id> NonEmptyString Repeated (0–unbounded) Each <deleted_review_id> element specifies the ID of a review of the merchant that should be deleted from the feed. The ID must match the id attribute of a <review> element in any feed file.
Example: <deleted_review_id>10327821</deleted_review_id>

<merchant_info>

The <merchant_info> element contains these elements in any order:

Element Type Occurrences Description
<name> NonEmptyString Required (1) The business name of the merchant.
Example: <name>Example Pet Store</name>
<country> xs:string Optional (0–1) The country in which the merchant is based. The value must be an ISO 3166-1 alpha-2 code.
Examples:
  • <country>US</country>
  • <country>GB</country>
<merchant_url> xs:anyURI Required (1) The URL for the merchant's main website. Do not use a redirect URL for this value. In other words, the value should point directly to the merchant's site.
Example: <merchant_url>http://www.examplepetstore.com</merchant_url>
<rating_url> Optional (0–1) Contains information about a landing page that contains overall ratings of the merchant.
<merchant_category> NonEmptyString Optional (0–1) The category of the merchant in your system.
Example: <merchant_category>pet supplies</merchant_category>

<rating_url>

The <rating_url> element contains character data of type xs:anyURI which specifies the URL of a landing page that contains overall ratings of the merchant.

The <rating_url> element has this attribute:

Attribute Type Use Description
type xs:string Required The type of the ratings page. The value must be one of the following:
summary
The ratings page contains a summary of ratings for the merchant.
detail
The ratings page contains detailed ratings such as individual reviews for the merchant.

Example: <rating_url type="detail">http://www.example.com/reviews/examplepetstore.com/</rating_url>

<ratings>

The <ratings> element contains these elements in any order:

Element Type Occurrences Description
<overall> RatingRange Required (1) Contains the reviewer's overall rating of the merchant.
<price> RatingRange Optional (0–1) Contains the reviewer's rating of the merchant's prices compared to other merchants.
<buy_again> RatingRange Optional (0–1) Contains the reviewer's rating of the likelihood that they will buy again from the merchant.
<shipping_options> RatingRange Optional (0–1) Contains the reviewer's rating of the merchant's shipping options.
<on_time_delivery> RatingRange Optional (0–1) Contains the reviewer's rating of the timeliness of the merchant's delivery.
<customer_service> RatingRange Optional (0–1) Contains the reviewer's rating of the merchant's customer service.
<product_availability> RatingRange Optional (0–1) Contains the reviewer's rating of the merchant's product availability.
<product_selection> RatingRange Optional (0–1) Contains the reviewer's rating of the merchant's product selection.

<review>

The <review> element has this attribute:

Attribute Type Use Description
id NonEmptyString Required A permanent, unique identifier for the review in your system.
Example: <review id="15636801">

The <review> element contains these elements in any order:

Element Type Occurrences Description
<review_url> Required (1) Contains information about a landing page that contains the review.
<reviewer_id> NonEmptyString Optional (0–1) A permanent, unique identifier for the author of the review in your system.
Example: <reviewer_id>339201</reviewer_id>
<reviewer> NonEmptyString Optional (0–1) The name of the author of the review.
Example: <reviewer>Jane</reviewer>
<reviewer_type> xs:string Required (1) The type of the reviewer. The value must be one of the following:
user
The review was written by a customer of the merchant.
editorial
The review was written by a professional writer for an objective review site.
aggregator
The review was written by the staff of a data aggregator.
Example: <reviewer_type>user</reviewer_type>
<review_date> xs:dateTime Required (1) The date and time when the review was submitted. The value must be in the format specified by the W3C profile of ISO 8601. A time zone designator is required after the time. The time zone designator may be "Z" to indicate UTC or it may have the format "+hh:mm" or "-hh:mm" to indicate an offset from UTC.
Examples:
  • <review_date>2010-07-12T12:55:06Z</review_date>
  • <review_date>2010-07-12T07:55:06-05:00</review_date>
<language> xs:string Optional (0–1) The language used in the review. The value must be an ISO 639-1 two-letter language code.
Example: <language>en</language>
<num_helpful> xs:nonNegativeInteger Optional (0–1) The number of users who found the review helpful. For example, if 21 out of 23 users found the review helpful, then this element should contain "21".
Example: <num_helpful>21</num_helpful>
<num_helpful_raters> xs:nonNegativeInteger Optional (0–1) The number of users who evaluated the helpfulness of the review. For example, if 21 out of 23 users found the review helpful, then this element should contain "23".
Example: <num_helpful_raters>23</num_helpful_raters>
<title> NonEmptyString Optional (0–1) The title of the review. The title should be plain text without any HTML tags in it.
Example: <title>Great prices</title>
<content> NonEmptyString Required (1) The content of the review. The full content should be provided; it should not be truncated. The content should be plain text without any HTML tags in it. For example a line break should be represented by a line feed character, not a <br> tag.
Example:
<content>I like this store!

My order arrived on time and I got a great price.</content>
<ratings> Required (1) Contains the reviewer's ratings of the merchant.
<is_spam> xs:boolean Optional (0–1) Indicates whether the review is marked as spam in your system. The value may be "true" or "false".
Example: <is_spam>true</is_spam>
<may_show_full_content> xs:boolean Optional (0–1) If the value is "true" then Google may show the full content of the review. If the value is "false" then Google may only show a snippet of the content.
Example: <may_show_full_content>true</may_show_full_content>
<collection_method> xs:string Optional (0–1) The method that was 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.
point_of_sale
The user submitted the review in response to a solicitation when the user placed an order.
after_fulfillment
The user submitted the review in response to a solicitation after fulfillment of the user's order.
Example: <collection_method>after_fulfillment</collection_method>
<transaction_id> NonEmptyString Optional (0–1) A permanent, unique identifier for the transaction associated with the review in your system. This ID can be used to indicate that multiple reviews are associated with the same transaction, for example when one review was collected when an order was placed and another review was collected after fulfillment of the same order.
Example: <transaction_id>922451288</transaction_id>

<review_url>

The <review_url> element contains character data of type xs:anyURI which specifies the URL of a landing page that contains the review.

The <review_url> element has this attribute:

Attribute Type Use Description
type xs:string Required The type of the review page. The value 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/reviews/examplepetstore.com/15636801</review_url>

Types

The following XML schema types are used to specify the content of some feed elements and attributes.

NonEmptyString

An element or attribute of type NonEmptyString contains character data of type xs:string with the additional restriction that the character data must have at least one non-whitespace character.

The NonEmptyString type indicates that a field must have valid data. If no data is available for a field and the field is optional, then the field should not appear in the feed. If no data is available for a field and the field is required, then the entire associated review should be excluded from the feed because the review does not have sufficient data to be accepted. For example, reviews without content (rating-only reviews) should be excluded from the feed because the <content> element is required.

RatingRange

An element of type RatingRange contains character data of type xs:decimal which specifies a numerical rating of a merchant.

Do not use "0" or any other value to specify "no rating". If no rating is available, then the particular rating element should not appear in the feed. If no rating is available for the <overall> element, then the entire associated review should be excluded from the feed because the <overall> element is required and the review will not be accepted without it.

An element of type RatingRange has these attributes:

Attribute Type Use Description
min xs:integer Required The minimum possible number for the rating. This should be the worst possible rating and should not be a value for "no rating".
max xs:integer Required The maximum possible number for the rating. This should be the best possible rating.
Examples:
  • <overall min="1" max="10">9</overall>
  • <customer_service min="1" max="5">4.5</customer_service>