# XML Schema

This section desribes the XML schema used for the merchant review data feed.

## Top-level element: `<feed>`

### Description

The top-most container element that holds all other elements in the feed.

### Attributes

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `xmlns` | [xs:string](https://www.w3.org/TR/xmlschema-2/#string) | Required (1) | Please hardcode the following value: `http://schemas.google.com/merchant_reviews/5.0` |
| `xmlns:xsi` | [xs:string](https://www.w3.org/TR/xmlschema-2/#string) | Required (1) | Please hardcode the following value: `http://www.w3.org/2001/XMLSchema-instance` |
| `xsi:schemaLocation` | [xs:string](https://www.w3.org/TR/xmlschema-2/#string) | Required (1) | Please hardcode the following value, leaving a **single blank space** between URLs: `http://schemas.google.com/merchant_reviews/5.0 http://www.gstatic.com/productsearch/static/reviews/5.0/merchant_reviews.xsd` |

### Example

```
<feed xmlns="http://schemas.google.com/merchant_reviews/5.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://schemas.google.com/merchant_reviews/5.0 https://www.gstatic.com/productsearch/static/reviews/5.0/merchant_reviews.xsd">
```

### Contains

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `merchants` | -- | Optional (0‑1) | Container element for `<merchant>` elements. |
| `deleted_merchants` | -- | Optional (0‑1) | Container element for `<deleted_merchant>` elements. |
| `reviews` | -- | Optional (0‑1) | Container element for `<review>` elements. |
| `deleted_reviews` | -- | Optional (0‑1) | Container element for `<deleted_review>` elements. |

## `<merchants>`

### Description

Container for `<merchant>` elements.

### Contains

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `merchant` | -- | Required (1‑n) | Element repeated for each merchant. |

## `<merchant>`

### Description

Each `<merchant>` element contains information and reviews for one merchant.

### Attributes

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `id` | [Id](https://developers.google.com/merchant-review-feeds/formats#id) | Required (1) | Must be unique and stable across all feeds. In other words, if a feed today and a feed 90 days ago refer to the same merchant, they must have the same id. |

### Example

```
<merchant id="2739">
```

### Contains

Please include the following elements within the merchant element.

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `name` | [NonEmptyString](https://developers.google.com/merchant-review-feeds/formats#nonemptystring) | Required (1) | Human-readable display name for the merchant. |
| `merchant_url` | [xs:anyURI](https://www.w3.org/TR/xmlschema-2/#anyURI) | Required (1) | URL to 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://store.google.com </merchant_url> ``` <br /> |
| `rating_url` | [xs:anyURI](https://www.w3.org/TR/xmlschema-2/#anyURI) | Required (1) | URL to the landing page that hosts the reviews for this merchant. Do not use a redirect URL. Example: ``` <rating_url> http://merchant_url.com/reviews/ </rating_url> ``` <br /> |
| `create_timestamp` | [DateTimeWithTimeZone](https://developers.google.com/merchant-review-feeds/formats#datetimewithtimezone) | Required (1) | Time/date the merchant was created. This should never change. |
| `last_update_timestamp` | [DateTimeWithTimeZone](https://developers.google.com/merchant-review-feeds/formats#datetimewithtimezone) | Required (1) | Time/date the merchant was last updated. If any of the fields in the `<merchant>` element are updated for a given merchant ID, this value must also change. |

## `<deleted_merchants>`

### Description

Container for merchants which were deleted.

### Contains

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `deleted_merchant` | -- | Required (1‑n) | Contains element(s) related to a single deleted merchant. |

## `<deleted_merchant>`

### Description

Merchant which was deleted.

### Attributes

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `id` | [Id](https://developers.google.com/merchant-review-feeds/formats#id) | Required (1) | Specifies the ID of a merchant that should be deleted from the feed. The ID must match the `id` attribute of a `<merchant>` element in any previous feed file. |

### Contains

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `last_update_timestamp` | [DateTimeWithTimeZone](https://developers.google.com/merchant-review-feeds/formats#datetimewithtimezone) | Required (1) | Time/date when a merchant was removed from the system. Example: ``` <last_update_timestamp> 2016-04-03T18:37:32Z </last_update_timestamp> ``` <br /> |

### Example

```
<deleted_merchant id="10">
  <last_update_timestamp>2014-07-12T07:55:06Z</last_update_timestamp>
</deleted_merchant>
```

## `<reviews>`

### Description

Container for `<review>` elements.

### Contains

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `review` | -- | Required (1‑n) | Element repeated for each review. |

## `<review>`

### Description

Container for details related to a review.

### Attributes

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `id` | [Id](https://developers.google.com/merchant-review-feeds/formats#id) | Required (1) | The identifier for a review in your system. Must be unique and stable across all feeds. Example: ``` <review id=132739 mid=1234> ``` <br /> |
| `mid` | [Id](https://developers.google.com/merchant-review-feeds/formats#id) | Required (1) | The identifier of the merchant this review is for. |

### Contains

Please include the following elements within the review element.

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `reviewer_name` | [NonEmptyString](https://developers.google.com/merchant-review-feeds/formats#nonemptystring) | Optional (0‑1) | Display name of the author of the review, provided the review should have a named author. Anonymous reviews should not include this field. Example: ``` <reviewer_name> Joel </reviewer_name> ``` <br /> |
| `create_timestamp` | [DateTimeWithTimeZone](https://developers.google.com/merchant-review-feeds/formats#datetimewithtimezone) | Required (1) | Time/date the review was submitted by the user. This should never change. Example: ``` <create_timestamp> 2016-04-03T18:37:32Z </create_timestamp> ``` <br /> |
| `last_update_timestamp` | [DateTimeWithTimeZone](https://developers.google.com/merchant-review-feeds/formats#datetimewithtimezone) | Required (1) | Time/date the information in the `<review>` element last changed. If any of the fields in the `<review>` element are updated for a given review ID, this value must also change. Example: ``` <last_update_timestamp> 2016-04-03T18:37:32Z </last_update_timestamp> ``` <br /> |
| `country_code` | [CountryCode](https://developers.google.com/merchant-review-feeds/formats#countrycode) | Required (1) | Country of the reviewer. If available, this is the country the product was shipped to or where the service was rendered. Otherwise, use country the reviewer is in at the point of creating the review. The country code must be in [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#search) format. Example: ``` <country_code> US </country_code> ``` <br /> |
| `title` | [xs:string](https://www.w3.org/TR/xmlschema-2/#string) | 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> ``` <br /> |
| `content` | [xs:string](https://www.w3.org/TR/xmlschema-2/#string) | Required (1) | The content of the review. This should be any freeform text provided by the user and 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. If multiple responses to different questions are provided, all responses should be included, with the minimal context for the responses to make sense. Context should not be provided if questions were left unanswered. Example: ``` <content> I like this store! My order arrived on time and I got a great price. </content> ``` <br /> Example: ``` <content> Positives: Great prices. Suggestions: Selection could be better. </content> ``` |
| `ratings` | -- | Required (1) | Container element for the reviewer's ratings of the merchant. 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. |
| `collection_method` | [CollectionMethodType](https://developers.google.com/merchant-review-feeds/formats#collectionmethodtype) | Required (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> ``` <br /> |

## `<ratings>`

### Description

Contains the reviewer's ratings of the merchant. 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.

### Contains

Please include the following elements within the ratings element.

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `overall` | [RatingRange](https://developers.google.com/merchant-review-feeds/formats#ratingrange) | Required (1) | Reviewer's overall rating for a merchant. Example: ``` <overall min="1" max="10">9</overall> ``` <br /> |
| `customer_service` | [RatingRange](https://developers.google.com/merchant-review-feeds/formats#ratingrange) | Optional (0‑1) | Reviewer's rating of the customer service quality for this merchant. Example: ``` <customer_service min="1" max="5">3</customer_service> ``` <br /> |

## `<deleted_reviews>`

### Description

Container for reviews which were deleted.

### Contains

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `deleted_review` | -- | Required (1‑n) | Contains element(s) related to a single deleted review. |

## `<deleted_review>`

### Description

Review which was deleted.

### Attributes

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `id` | [Id](https://developers.google.com/merchant-review-feeds/formats#id) | Required (1) | Specifies the ID of a review that should be deleted from the feed. The ID must match the id attribute of a `<review>` element in any feed file. |

### Contains

| Name | Format | Occurrences | Description |
|---|---|---|---|
| `last_update_timestamp` | [DateTimeWithTimeZone](https://developers.google.com/merchant-review-feeds/formats#datetimewithtimezone) | Required (1) | Time at which a review was removed from the system. Example: ``` <last_update_timestamp> 2016-04-03T18:37:32Z </last_update_timestamp> ``` <br /> |

### Example

```
<deleted_review id="10">
  <last_update_timestamp>2014-07-12T07:55:06Z<last_update_timestamp>
</deleted_review>
```