Count vs. Votes Error for schema.org/AggregateRating

by Aaron Bradley on October 28, 2013

in Semantic Web, SEO

schema.org/AggregateRating and the Count vs. Votes Structured Data Testing Tool Error Message

schema.org has a mechanism for stating the average rating of an item based on multiple ratings or reviews: schema.org/AggregateRating. AggregateRating is the expected type for the property aggregateRating, which can be used on all CreativeWork, Organization, Place, Offer and Product types (you can't rate a Person, which is probably a good thing).

The phrase "multiple ratings or reviews" comes directly from schema.org, and noticably does not include the the word "vote" (which, in fact, at time as writing is not to be found anywhere on the schema.org site at all).

This is a problematic omission because one of the most common error messages generated by Google's Structured Data Testing Tool for (chiefly microdata) markup that uses AggregateRating concerns the use of "votes" rather than "count" (and "count" is not a valid property for any schema.org type either).

It is also problematic because this error sheds light on one of the most common reasons why review rich snippets do not appear in Google search results.

The "counts vs. votes" error in the Google Structured Data Testing Tool

Specifically, the Structured Data Testing Tool will often return this message when one tries to validate code containing AggregateRating:

Error: If count is specified in review aggregate, page should contain reviews. Otherwise you may want to use votes. More information about aggregate reviews.

If you were to run this code – HTML with schema.org/AggregateRating marked up using microdata – through the Structured Data Testing Tool that's exactly the error the Tool would return:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Proper use of reviewCount</title>
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
  </head>
  <body>
    <div itemscope itemtype="http://schema.org/Article">
      <h1 itemprop="name">Proper use of reviewCount</h1>
      <div itemprop="description">Don't use reviewCount when you should use ratingCount.</div>
      <div itemprop="articleBody">When marking up something with reviewCount make sure the something in question has reviews.  Otherwise, use ratingCount.</div>
      <div itemprop="aggregateRating" itemscope itemtype="http://schema.org/AggregateRating">Rated <span itemprop="ratingValue">4</span>/5 based on <span itemprop="reviewCount">2</span> reviews</div>
    </div>
  </body>
</html>

This despite the fact that star ratings appear in the Google search results preview for this code:

Google Structured Data Testing Tool rich snippet preview for schema.org/AggregateRating using the reviewCount property

What's going on?

Google guidelines for Review-aggregate and AggregateRating properties

First of all, Google is using the language of data-vocabulary.org in this error message, even though schema.org is used. The data-vocabulary.org item type equivalent to schema.org/AggregateRating is www.data-vocabulary.org/Review-aggregate/.

Review-aggregate employs properties that are different from – but equivalent to – AggregateRating properties.

The Review-aggregate property rating is equivalent to the AggregateRating property ratingValue.

The Review-aggregate property count is equivalent to the AggregateRating property reviewCount.

The Review-aggregate property votes is equivalent to the AggregateRating property ratingCount.

Armed with this nomenclature, we can then transform the Structured Data Testing Tool error message so it addresses schema.org/AggregateRating:

Error: If reviewCount is specified in AggregateRating, page should contain reviews. Otherwise you may want to use ratingCount.

And herein lies the problem with the example code snippet above. It employs the reviewCount property for AggregateRating, but the page itself doesn't list any reviews. That is, one if were to use the reviewCount property on a page, one would also expect to see one or more instances of the review property used for the parent item.

The Google Webmaster Tools rich snippet help page for the topic "rich snippets not appearing" has this to say about count vs. votes:

Your marked-up review uses count instead of votes. count specifies the total number of reviews for an item. votes specifies the number of people who provided a rating, with or without an accompanying review. A review can specify count or votes, or both. However, whenever you include count, the page must also contain markup for each reviewed item.

Again, this pertains to Review-aggregate. For AggregateRating this should read:

Your marked-up review uses reviewCount instead of ratingCount. reviewCount specifies the total number of reviews for an item. ratingCount specifies the number of people who provided a rating, with or without an accompanying review. A review can specify ratingCount or reviewCount, or both. However, whenever you include reviewCount, the page must also contain markup for each reviewed item.

Correct use of AggregateRating properties for items without reviews

The example page code displayed above uses reviewCount but contains no reviews. Simply replacing reviewCount with ratingCount in that code results in error-free valdiation in the Structured Data Testing Tool:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Proper use of reviewCount</title>
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
  </head>
  <body>
    <div itemscope itemtype="http://schema.org/Article">
      <h1 itemprop="name">Proper use of reviewCount</h1>
      <div itemprop="description">Don't use reviewCount when you should use ratingCount.</div>
      <div itemprop="articleBody">When marking up something with reviewCount make sure the something in question has reviews.  Otherwise, use ratingCount.</div>
      <div itemprop="aggregateRating" itemscope itemtype="http://schema.org/AggregateRating">Rated <span itemprop="ratingValue">4</span>/5 based on <span itemprop="ratingCount">2</span> reviews</div>
    </div>
  </body>
</html>

You'll also see that the preview rich snippet for this code now says "2 votes" rather than "2 reviews":

Google Structured Data Testing Tool rich snippet preview for schema.org/AggregateRating using the ratingCount property

In short, for items without reviews use ratingCount to express the total number of ratings, rather than reviewCount, which should only be used to express the total number of reviews.

Correct use of AggregateRating properties for items with reviews

For items with reviews, use reviewCount and markup individual reviews with the review property:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Proper use of reviewCount</title>
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
  </head>
  <body>
    <div itemscope itemtype="http://schema.org/Article">
      <h1 itemprop="name">Proper use of reviewCount</h1>
      <div itemprop="description">Don't use reviewCount when you should use ratingCount.</div>
      <div itemprop="articleBody">When marking up something with reviewCount make sure the something in question has reviews.  Otherwise, use ratingCount.</div>
      <div itemprop="aggregateRating" itemscope itemtype="http://schema.org/AggregateRating">Rated <span itemprop="ratingValue">4</span>/5 based on <span itemprop="reviewCount">2</span> reviews</div>
      <div itemprop="review" itemscope itemtype="http://schema.org/Review"><span itemprop="name">A great article</span> - by <span itemprop="author">John</span>, <meta itemprop="datePublished" content="2013-10-16">October 26, 2013
        <div itemprop="reviewRating" itemscope itemtype="http://schema.org/Rating"><span itemprop="ratingValue">5</span>/5</div>
    <span itemprop="reviewBody">What I especially liked about this piece was that it contained only 17 words.</span>
      </div>
      <div itemprop="review" itemscope itemtype="http://schema.org/Review"><span itemprop="name">A bit brief</span> - by <span itemprop="author">Mary</span>, <meta itemprop="datePublished" content="2013-10-16">October 26, 2013
        <div itemprop="reviewRating" itemscope itemtype="http://schema.org/Rating"><span itemprop="ratingValue">3</span>/5</div>
    <span itemprop="reviewBody">It was okay, but I was hoping for something a bit more comprehensive.</span>
      </div>
    </div>
  </body>
</html>

(If you run this code through the Structured Data Testing Tool, you may still see the "count vs. votes" error message. More on this below.)

This is a legitimate way of marking up an item using the reviewCount property for AggregateRating because there is a on-page review for each of the ratings for which the AggregateRating property ratingValue is an average.

What about off-page reviews? While I can't speak to whether or not the display of rich snippets would be supported by this code, it is at least technically legitimate (in my opinion) to use reviewCount where there is a click-path to individual reviews, even if they are not all present on the page where the item marked up with AggregateRating is declared.

<div itemscope itemtype="http://schema.org/Article">
	...
    <div itemprop="review" itemscope itemtype="http://schema.org/Review"><span itemprop="name">A great article...</span><span
 itemprop="reviewRating" itemscope itemtype="http://schema.org/Rating"><span itemprop="ratingValue">5</span>/5</span> <a href="review1.html" itemprop="url">Read full review</a></div>
</div>

However, how confident you feel using this code depends on how you interpret Google's guidelines that "the page must also contain markup for each reviewed item." Certainly the page contains review markup for each item reviewed, but not – on that same page – the actual review content. Caveat emptor.

Correct use of AggregateRating properties for items with a mix of reviews and ratings

Google has this to say about "votes":

votes is useful whenever users on a review site can rate an item without writing full corresponding reviews. Their vote contributes toward the average rating but not towards the number of reviews available.

Transposing this to AggregateRating one could say that the rating assigned by individual users contributes toward the the ratingValue of an AggregateRating, but not toward the number of reviews available as enumerated by reviewCount.

Accordingly (and in conjunction with the other Google guideline quoted above about a page containing "markup for each reviewed item") for pages that contain a mix of ratings with reviews, and ratings without reviews, I would recommend using only ratingCount and not reviewCount.

One could conceivably use both properties and adjust the counts accordingly, but that seems like rather a lot of bother to go to simply to delcare a correct count of reviews, and it increases the risk of errors appearing in the semantic markup of the page (and any such errors tend to hamper the display of rich snippets, regardless of the specific error).

In short, if your aim is the generation of review rich snippets, error on the side of caution by using ratingCount over reviewCount when in doubt.

What generates an AggregateRating "count vs votes" error message?

While the message under discussion here is prefaced "Error" it is sometimes generated when the code in question is error-free. This includes situations where there there are reviews on the page marked up using the review property, and the number of on-page reviews corresponds to value stated in reviewCount.

That is, indeed, the case with the code showing reviews above, where reviewCount has the value "2" and there are two reviews on the page. This is also the syntax employed by the examples currently displayed on schema.org/Review.

All of this to say that a Testing Tool "error" of this nature may best be thought of as an "informational message," and can certainly appear when one attempts to perfectly valid code.

The error is not even consistent for the same type of code. If one were to refashion the non-validating code above by simply having it reference a Product rather than an Article, but otherwise (after removing the Article-specific property articleBody) use exactly the same syntax, the "counts vs. votes" error message is not generated:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Acme Toaster Oven</title>
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
  </head>
  <body>
    <div itemscope itemtype="http://schema.org/Product">
      <h1 itemprop="name">Acme Toaster Oven</h1>
      <div itemprop="description">It toasts AND bakes.</div>
      <div itemprop="aggregateRating" itemscope itemtype="http://schema.org/AggregateRating">Rated <span itemprop="ratingValue">3</span>/5 based on <span itemprop="reviewCount">2</span> reviews</div>
      <div itemprop="review" itemscope itemtype="http://schema.org/Review"><span itemprop="name">A great toaster</span> - by <span itemprop="author">John</span>, <meta itemprop="datePublished" content="2013-10-16">October 26, 2013
        <div itemprop="reviewRating" itemscope itemtype="http://schema.org/Rating"><span itemprop="ratingValue">5</span>/5</div>
    <span itemprop="reviewBody">First I had bread.  Then I had toast.  Magic!</span>
      </div>
      <div itemprop="review" itemscope itemtype="http://schema.org/Review"><span itemprop="name">A small oven</span> - by <span itemprop="author">Mary</span>, <meta itemprop="datePublished" content="2013-10-16">October 26, 2013
        <div itemprop="reviewRating" itemscope itemtype="http://schema.org/Rating"><span itemprop="ratingValue">1</span>/5</div>
    <span itemprop="reviewBody">My 18-pound turkey wouldn't fit in this thing.</span>
      </div>
    </div>
  </body>
</html>

So beware of using reviewCount when you should be using ratingCount, but also be aware of the Structured Data Testing Tool notifying you of errors that don't exist. In this situation – as in others – if you're confident that your code is solid, go ahead and deploy it even if the Testing Tool complains. But pay close attention to those complaints when troubleshooting rich snippet display problems.

{ 25 comments… read them below or add one }

Leave a Comment

Previous post:

Next post: