hreview-aggregate: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
mNo edit summary
Line 29: Line 29:
== Format ==
== Format ==


=== Schema ===


The hReview-aggregate schema consists of the following:


* hReview-aggregate ('''<code>hreview-aggregate</code>''')
** '''<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)
** '''<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>'''.
** '''<code>count</code>'''. required. non-negative integer.
** '''<code>summary</code>'''. 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|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.
'''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 required property is used to specify the total number of reviews for the product or service.
'''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 <code>item</code>, <code>item</code>, and <code>item</code> properties are reused from [[hreview|hReview]].


== todo's ==
== todo's ==

Revision as of 04:40, 11 November 2009

<entry-title>hReview-aggregate 0.1</entry-title> 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 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.

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. required. non-negative integer.
    • 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 required property is used to specify the total number of reviews for the product or service.

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, item, and item properties are reused from hReview.

todo's

to-do: this "hReview aggregate" draft specification page needs to be written up from the chosen/consensus proposal in aggregate-review-brainstorming, perhaps using hReview as a spec draft template.

examples in the wild

This section is informative.

The following sites have implemented hReview-aggregate, and thus are a great place to start for anyone looking for examples "in the wild" to try parsing, indexing, organizing etc. If your site is marked up with hReview aggregate, feel free to add it to the top of this list. Once the list grows too big, we'll make a separate wiki page like hreview-aggregate-examples-in-wild.

  • STV Local uses hreview-aggregate for business ratings, average prices and contact details with hcard
  • Critiki publishes ratings and reviews of Tiki bars, and uses hReview aggregate for average ratings on their pages, e.g. overview of The Tonga Room. (as tweeted by humuhumu 2009-09-21)
  • NAPLESPLUS is an example of a website that has implemented hreview-aggregate via Google specs.
  • ...