Difference between revisions of "hreview-aggregate"

From Microformats Wiki
hreview-aggregate
Jump to navigation Jump to search
m (Replace <entry-title> with {{DISPLAYTITLE:}})
 
(17 intermediate revisions by 12 users not shown)
Line 1: Line 1:
HOW THING THROUGH
+
{{DISPLAYTITLE:hReview-aggregate 0.2}}
HOW MAKE THING THROUGH
+
{{DraftSpecification}}
HOW THING BE THROUGH
+
 
HOW MAKE THING BE THROUGH
+
[[hreview-aggregate|hReview-aggregate]] is a format for embedding review information (of products, services, businesses, etc). Whereas [[hreview|hReview]] is intended for an individual review, hReview-aggregate is meant for summary information about a collection of user or critic reviews about an item. hReview-aggregate is one of several [[microformats]] open standards suitable for embedding in HTML, XHTML, Atom, RSS, and arbitrary XML.
HOW ANYTHING THROUGH
+
 
HOW MAKE ANYTHING THROUGH
+
== Microformats Draft Specification 2009-11-10 ==
HOW ANYTHING BE THROUGH
+
 
HOW MAKE ANYTHING BE THROUGH
+
; Editor: [[User:KaviGoel|Kavi Goel]], Google
HOW EVERYTHING THROUGH
+
; Authors/Contributers (alphabetical): [[User:Tantek|Tantek Çelik]]
HOW MAKE EVERYTHING THROUGH
+
: Othar Hansson, Google
HOW EVERYTHING BE THROUGH
+
: [[User:JayMyers|Jay Myers]], [http://www.bestbuy.com/ Best Buy, Co., Inc.]
HOW MAKE EVERYTHING BE THROUGH
+
 
HOW UNIVERSE THROUGH
+
== Introduction ==
HOW MAKE UNIVERSE THROUGH
+
 
HOW UNIVERSE BE THROUGH
+
Many websites publish reviews using a variety of organization schemes. hReview-aggregate and the similar microformat [[hreview|hReview]] were designed to enable sharing of review information.
HOW MAKE UNIVERSE BE THROUGH
+
 
HOW THING OUT
+
hReview, created in 2006, is well suited to mark up reviews done by individuals on their own websites or for editor's reviews for a new product or service. However, in recent years, there has been an increasing number of sites who aggregate user reviews, either by accepting reviews submitted to their website or by collecting those user reviews from across the web. In these cases, it is often valuable to share not just the individual reviews shown on the webpage, but the consensus opinion derived from those individual reviews.
HOW MAKE THING OUT
+
 
HOW THING BE OUT
+
hReview-aggregate was created to address this need. hReview-aggregate is a standard that can be used to share the number of reviews, average rating, and consensus opinion for a particular product or service. It is meant to complement hReview and reuses hReview properties wherever appropriate. Research and discussion that fed into the design of hReview-aggregate can be found on the [[aggregate-review-brainstorming|aggregate review brainstorming]] wiki page.
HOW MAKE THING BE OUT
+
 
HOW ANYTHING OUT
+
{{rfc-2119-intro}}
HOW MAKE ANYTHING OUT
+
 
HOW ANYTHING BE OUT
+
=== Scope ===
HOW MAKE ANYTHING BE OUT
+
 
HOW EVERYTHING OUT
+
Collections of reviews consistently share several common aspects. Where possible hReview-aggregate has been based on this common subset.
HOW MAKE EVERYTHING OUT
+
 
HOW EVERYTHING BE OUT
+
=== Out of scope ===
HOW MAKE EVERYTHING BE OUT
+
 
HOW UNIVERSE OUT
+
Portions of reviews that are specific to particular kinds of items have been omitted from hReview-aggregate.
HOW MAKE UNIVERSE OUT
+
 
HOW UNIVERSE BE OUT
+
== Format ==
HOW MAKE UNIVERSE BE OUT
+
 
HOW THING THROUGH
+
=== Schema ===
HOW MAKE THING THROUGH
+
 
HOW THING BE THROUGH
+
The hReview-aggregate schema consists of the following:
HOW MAKE THING BE THROUGH
+
 
HOW ANYTHING THROUGH
+
* hReview-aggregate ('''<code>hreview-aggregate</code>''')
HOW MAKE ANYTHING THROUGH
+
** '''<code>item</code>''' info. required. '''<code>fn</code>''' ('''<code>url</code>''' || '''<code>photo</code>''' ) | '''[[hcard|hCard]]''' (for person or business) | '''[[hcalendar|hCalendar]]''' (for event) | '''[[hproduct|hProduct]]''' (for product)
HOW ANYTHING BE THROUGH
+
** '''<code>rating</code>'''. required. fixed point integer [1.0-5.0], with optional alternate '''<code>worst</code>''' (default:1.0) and/or '''<code>best</code>''' (default:5.0), also fixed point integers, and explicit '''<code>average</code>'''.
HOW MAKE ANYTHING BE THROUGH
+
** '''<code>count</code>'''. optional. non-negative integer.
HOW EVERYTHING THROUGH
+
** '''<code>votes</code>'''. optional. non-negative integer. Note that while <code>count</code> and <code>votes</code> are both marked optional, at least one of the two fields must be specified.
HOW MAKE EVERYTHING THROUGH
+
** '''<code>summary</code>'''. optional. text.
HOW EVERYTHING BE THROUGH
+
 
HOW MAKE EVERYTHING BE THROUGH
+
=== Property details ===
HOW UNIVERSE THROUGH
+
 
HOW MAKE UNIVERSE THROUGH
+
Details of the hReview-aggregate properties:
HOW UNIVERSE BE THROUGH
+
 
HOW MAKE UNIVERSE BE THROUGH
+
'''item''':: This required property {{must}} have at a minimum the name of the entity being reviewed (using the subproperty "fn"), or alternatively have an encapsulated microformat (i.e. [[hcard|hCard]] for a business or person, [[hproduct|hProduct]] for a product, or [[hcalendar|hCalendar]] for an event). If an encapsulated microformat is not used, a URI ("url") for the item and a photo or depiction ("photo") {{may}} also be provided. Non-URL unique item IDs (e.g. ISBNs, UPCs) {{may}} be represented as a URN ("url") for the item.  Encapsulated microformats must be set on the item itself (e.g. class="item vcard").  However, when using item info subproperties ("fn", "url", "photo"), they must be nested inside the item element.
HOW THING OUT
+
 
HOW MAKE THING OUT
+
'''rating''':: The rating is a fixed point integer (one decimal point of precision) from 1.0 to 5.0 inclusive indicating the average rating for the item across all reviews, higher indicating a better rating by default. Optionally a different integral "worst" value and/or "best" value may be specified to indicate a different range (e.g. 6 from 0-10).
HOW THING BE OUT
+
 
HOW MAKE THING BE OUT
+
'''count''':: This property is used to specify the total number of reviews for the product or service.
HOW ANYTHING OUT
+
 
HOW MAKE ANYTHING OUT
+
'''votes''':: This property is used to specify the total number of users who have rated the product or service, contributing to the average rating. For some sites, the number of votes is equal to the number of reviews, so <code>count</code> may be used and this property omitted.
HOW ANYTHING BE OUT
+
 
HOW MAKE ANYTHING BE OUT
+
'''summary''':: This optional property can be the title for the review collection or a very short summary of the consensus opinion from the collection.
HOW EVERYTHING OUT
+
 
HOW MAKE EVERYTHING OUT
+
The <code>item</code>, <code>rating</code>, and <code>summary</code> properties are reused from [[hreview|hReview]].
HOW EVERYTHING BE OUT
+
 
HOW MAKE EVERYTHING BE OUT
+
== Examples ==
HOW UNIVERSE OUT
+
 
HOW MAKE UNIVERSE OUT
+
=== Basic example ===
HOW UNIVERSE BE OUT
+
 
HOW MAKE UNIVERSE BE OUT
+
Here is an example showing aggregate review information for a restaurant:
 +
 
 +
<pre><nowiki>
 +
<div>
 +
<h3>
 +
  <span>Mediterranean Wraps</span>
 +
</h3>
 +
<span>Customers flock to this small restaurant for their
 +
tasty falafel and shawerma wraps and welcoming staff.</span>
 +
<span>4.5 out of 5 based on 17 reviews</span>
 +
</div>
 +
</nowiki></pre>
 +
 
 +
Adding hReview-aggregate markup to this is straightforward:
 +
 
 +
<pre><nowiki>
 +
<div class="hreview-aggregate">
 +
<h3 class="item">
 +
  <span class="fn">Mediterranean Wraps</span>
 +
</h3>
 +
<span class="summary">Customers flock to this small restaurant for their
 +
tasty falafel and shawerma wraps and welcoming staff.</span>
 +
<span><span class="rating">4.5</span> out of 5
 +
based on <span class="count">17</span> reviews</span>
 +
</div>
 +
</nowiki></pre>
 +
 
 +
=== Embedded microformat, 10-point rating scale ===
 +
 
 +
Often, there is more information available on a page about the item being reviewed than the title. Here is another example of a restaurant review, but with address information present.
 +
 
 +
<pre><nowiki>
 +
<div>
 +
<div>
 +
  <h3>Mediterranean Wraps</h3>
 +
  <span>433 S California Ave</span>
 +
  <span>Palo Alto, CA
 +
  <span>(650) 321-8189</span>
 +
</div>
 +
<span>Customers flock to this small restaurant for their
 +
tasty falafel and shawerma wraps and welcoming staff.</span>
 +
<span>9.2 out of 10 based on 17 reviews</span>
 +
</div>
 +
</nowiki></pre>
 +
 
 +
And here it is with hReview-aggregate markup, along with an embedded [[hcard|hCard]] to describe the address and phone information for the restaurant:
 +
 
 +
<pre><nowiki>
 +
<div class="hreview-aggregate">
 +
<div class="item vcard">
 +
  <h3 class="fn">Mediterranean Wraps</h3>
 +
  <span class="adr">
 +
  <span class="street-address">433 S California Ave</span>
 +
  <span><span class="locality">Palo Alto</span>, <span class="region">CA</span></span>
 +
  <span class="tel">(650) 321-8189</span>
 +
  </span>
 +
</div>
 +
<span class="summary">Customers flock to this small restaurant for their
 +
tasty falafel and shawerma wraps and welcoming staff.</span>
 +
<span class="rating"><span class="average">9.2</span> out of <span class="best">10</span>
 +
based on <span class="count">17</span> reviews</span>
 +
</div>
 +
</nowiki></pre>
 +
 
 +
Note that the <code>item</code> and <code>vcard</code> are put next to each other in the same class attribute in order to show that the item being reviewed is described by the embedded hCard.
 +
 
 +
=== Count vs votes ===
 +
 
 +
In the examples so far, the <code>count</code> property has been used but not <code>votes</code>. <code>votes</code> is useful when users have rated an item without writing full corresponding reviews. Their vote contributed toward the average rating but not towards the number of reviews available.
 +
 
 +
Consider this example:
 +
 
 +
<pre><nowiki>
 +
<div>
 +
<h3>
 +
  <span>Mediterranean Wraps</span>
 +
</h3>
 +
<span>Customers flock to this small restaurant for their
 +
tasty falafel and shawerma wraps and welcoming staff.</span>
 +
<span>4.5 out of 5 based on 24 ratings.</span>
 +
<span>5 user reviews:</span>
 +
...
 +
</div>
 +
</nowiki></pre>
 +
 
 +
Here the example is again, with both <code>count</code> and <code>votes</code> specified where appropriate.
 +
 
 +
<pre><nowiki>
 +
<div class="hreview-aggregate">
 +
<h3 class="item">
 +
  <span class="fn">Mediterranean Wraps</span>
 +
</h3>
 +
<span class="summary">Customers flock to this small restaurant for their
 +
tasty falafel and shawerma wraps and welcoming staff.</span>
 +
<span><span class="rating">4.5</span> out of 5
 +
based on <span class="votes">24</span> ratings.</span>
 +
<span><span class="count">5</span> user reviews:</span>
 +
...
 +
</div>
 +
</nowiki></pre>
 +
 
 +
== examples in the wild ==
 +
{{main|hreview-aggregate-examples-in-wild}}
 +
 
 +
== Related Pages ==
 +
 
 +
* [[hreview|hReview]] - microformat for marking up individual reviews
 +
* [[aggregate-review-brainstorming|Aggregate review brainstorming]] - discussions leading to the creation of hReview-aggregate and ideas for improvement.
 +
* [[aggregate-review-examples|Aggregate review examples]]
 +
 
 +
[[Category:Draft Specifications]]
 +
[[Category:hReview-aggregate]]

Latest revision as of 16:27, 18 July 2020

This document represents a draft microformat specification. Although drafts are somewhat mature in the development process, the stability of this document cannot be guaranteed, and implementers should be prepared to keep abreast of future developments and changes. Watch this wiki page, or follow discussions on the #microformats Freenode IRC channel to stay up-to-date.

hReview-aggregate is a format for embedding review information (of products, services, businesses, etc). Whereas hReview is intended for an individual review, hReview-aggregate is meant for summary information about a collection of user or critic reviews about an item. hReview-aggregate is one of several microformats open standards suitable for embedding in HTML, XHTML, Atom, RSS, and arbitrary XML.

Microformats Draft Specification 2009-11-10

Editor
Kavi Goel, Google
Authors/Contributers (alphabetical)
Tantek Çelik
Othar Hansson, Google
Jay Myers, Best Buy, Co., Inc.

Introduction

Many websites publish reviews using a variety of organization schemes. hReview-aggregate and the similar microformat hReview were designed to enable sharing of review information.

hReview, created in 2006, is well suited to mark up reviews done by individuals on their own websites or for editor's reviews for a new product or service. However, in recent years, there has been an increasing number of sites who aggregate user reviews, either by accepting reviews submitted to their website or by collecting those user reviews from across the web. In these cases, it is often valuable to share not just the individual reviews shown on the webpage, but the consensus opinion derived from those individual reviews.

hReview-aggregate was created to address this need. hReview-aggregate is a standard that can be used to share the number of reviews, average rating, and consensus opinion for a particular product or service. It is meant to complement hReview and reuses hReview properties wherever appropriate. Research and discussion that fed into the design of hReview-aggregate can be found on the aggregate review brainstorming wiki page.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Scope

Collections of reviews consistently share several common aspects. Where possible hReview-aggregate has been based on this common subset.

Out of scope

Portions of reviews that are specific to particular kinds of items have been omitted from hReview-aggregate.

Format

Schema

The hReview-aggregate schema consists of the following:

  • hReview-aggregate (hreview-aggregate)
    • item info. required. fn (url || photo ) | hCard (for person or business) | hCalendar (for event) | hProduct (for product)
    • rating. required. fixed point integer [1.0-5.0], with optional alternate worst (default:1.0) and/or best (default:5.0), also fixed point integers, and explicit average.
    • count. optional. non-negative integer.
    • votes. optional. non-negative integer. Note that while count and votes are both marked optional, at least one of the two fields must be specified.
    • summary. optional. text.

Property details

Details of the hReview-aggregate properties:

item:: This required property MUST have at a minimum the name of the entity being reviewed (using the subproperty "fn"), or alternatively have an encapsulated microformat (i.e. hCard for a business or person, hProduct for a product, or hCalendar for an event). If an encapsulated microformat is not used, a URI ("url") for the item and a photo or depiction ("photo") MAY also be provided. Non-URL unique item IDs (e.g. ISBNs, UPCs) MAY be represented as a URN ("url") for the item. Encapsulated microformats must be set on the item itself (e.g. class="item vcard"). However, when using item info subproperties ("fn", "url", "photo"), they must be nested inside the item element.

rating:: The rating is a fixed point integer (one decimal point of precision) from 1.0 to 5.0 inclusive indicating the average rating for the item across all reviews, higher indicating a better rating by default. Optionally a different integral "worst" value and/or "best" value may be specified to indicate a different range (e.g. 6 from 0-10).

count:: This property is used to specify the total number of reviews for the product or service.

votes:: This property is used to specify the total number of users who have rated the product or service, contributing to the average rating. For some sites, the number of votes is equal to the number of reviews, so count may be used and this property omitted.

summary:: This optional property can be the title for the review collection or a very short summary of the consensus opinion from the collection.

The item, rating, and summary properties are reused from hReview.

Examples

Basic example

Here is an example showing aggregate review information for a restaurant:

<div>
 <h3>
  <span>Mediterranean Wraps</span>
 </h3>
 <span>Customers flock to this small restaurant for their 
 tasty falafel and shawerma wraps and welcoming staff.</span>
 <span>4.5 out of 5 based on 17 reviews</span>
</div>

Adding hReview-aggregate markup to this is straightforward:

<div class="hreview-aggregate">
 <h3 class="item">
  <span class="fn">Mediterranean Wraps</span>
 </h3>
 <span class="summary">Customers flock to this small restaurant for their 
 tasty falafel and shawerma wraps and welcoming staff.</span>
 <span><span class="rating">4.5</span> out of 5 
 based on <span class="count">17</span> reviews</span>
</div>

Embedded microformat, 10-point rating scale

Often, there is more information available on a page about the item being reviewed than the title. Here is another example of a restaurant review, but with address information present.

<div>
 <div>
  <h3>Mediterranean Wraps</h3>
  <span>433 S California Ave</span>
  <span>Palo Alto, CA
  <span>(650) 321-8189</span>
 </div> 
 <span>Customers flock to this small restaurant for their 
 tasty falafel and shawerma wraps and welcoming staff.</span>
 <span>9.2 out of 10 based on 17 reviews</span>
</div>

And here it is with hReview-aggregate markup, along with an embedded hCard to describe the address and phone information for the restaurant:

<div class="hreview-aggregate">
 <div class="item vcard">
  <h3 class="fn">Mediterranean Wraps</h3>
  <span class="adr">
   <span class="street-address">433 S California Ave</span>
   <span><span class="locality">Palo Alto</span>, <span class="region">CA</span></span>
   <span class="tel">(650) 321-8189</span>
  </span>
 </div> 
 <span class="summary">Customers flock to this small restaurant for their 
 tasty falafel and shawerma wraps and welcoming staff.</span>
 <span class="rating"><span class="average">9.2</span> out of <span class="best">10</span> 
 based on <span class="count">17</span> reviews</span>
</div>

Note that the item and vcard are put next to each other in the same class attribute in order to show that the item being reviewed is described by the embedded hCard.

Count vs votes

In the examples so far, the count property has been used but not votes. votes is useful when users have rated an item without writing full corresponding reviews. Their vote contributed toward the average rating but not towards the number of reviews available.

Consider this example:

<div>
 <h3>
  <span>Mediterranean Wraps</span>
 </h3>
 <span>Customers flock to this small restaurant for their 
 tasty falafel and shawerma wraps and welcoming staff.</span>
 <span>4.5 out of 5 based on 24 ratings.</span>
 <span>5 user reviews:</span>
 ...
</div>

Here the example is again, with both count and votes specified where appropriate.

<div class="hreview-aggregate">
 <h3 class="item">
  <span class="fn">Mediterranean Wraps</span>
 </h3>
 <span class="summary">Customers flock to this small restaurant for their 
 tasty falafel and shawerma wraps and welcoming staff.</span>
 <span><span class="rating">4.5</span> out of 5 
 based on <span class="votes">24</span> ratings.</span>
 <span><span class="count">5</span> user reviews:</span>
 ...
</div>

examples in the wild

Main article: hReview-aggregate Examples in the wild

Related Pages