Authors

Introduction

Numerous web sites publish reviews using a broad variety of schema for all sorts of things from products (movies, music, books), to businesses (restaurants, hotels, stores), to events (concerts, theatre), to people (artists, leaders, celebrities), to places (landmarks, parks), to online resources (web pages, files), to reviews of reviews themselves.

In order to enable and encourage the sharing, distribution, syndication, and aggregation, of reviews, the authors propose the hReview MicroFormat, an open standard for distributed reviews. The authors have researched numerous earlier attempts at ReviewsFormats, and have designed hReview around a simple minimal schema for reviews. Feedback is encouraged on the ["hReviewFeedback"] page.

Working Name

The name "hReview" is a working name for this microformat. The name was suggested as it shares much with the hCard and hCalendar microformats, despite not having an IETF RFC to reference for a normative schema.

Copyright

This specification is (C) 2005 by the authors. However, the authors intend to submit (or already have submitted, see details in the spec) this specification to a standards body with a liberal copyright/licensing policy such as the GMPG, IETF, and/or W3C. Anyone wishing to contribute should read their copyright principles, policies and licenses (e.g. the GMPG Principles) and agree to them, including licensing of all contributions under all required licenses (e.g. CC-by 1.0 and later), before contributing.

Scope

Reviews consistently share several common fields. Where possible hReview has been based on this minimal common subset.

Out of scope

Fields that are type-specific have been omitted from hReview. It is important that hReview be kept simple and minimal from the start. Additional features can be added as deemed necessary by practical implementation experience.

The concept of a "universal object identifier", that is, how to identify the same object/item/product across different shopping sites, though something very useful to have, is outside the scope of this format.

Semantic XHTML Design Principles

XHTML is built on XML, and thus XHTML-based formats can be used not only for convenient display presentation, but also for general-purpose data exchange. In many ways, XHTML-based formats exemplify the best of both HTML and XML worlds. However, when building XHTML-based formats, it helps to have a guiding set of principles.

For types with multiple components, use nested elements with class names equivalent to the names of the components.

Plural components are made singular, and thus multiple nested elements are used to represent multiple text values that are comma-delimited.

Use the most accurately precise semantic XHTML building block for each object etc.

Otherwise use a generic structural element (e.g. <span> or <div>), or the appropriate contextual element (e.g. an <li> inside a <ul> or <ol>).

Use class names based on names from the original schema, unless the semantic XHTML building block precisely represents that part of the original schema. If names in the source schema are case-insensitive, then use an all lowercase equivalent. Components names implicit in prose (rather than explicit in the defined schema) should also use lowercase equivalents for ease of use. Spaces in component names become dash '-' characters.

Finally, if the format of the data according to the original schema is too long and/or not human-friendly, use <abbr> instead of a generic structural element, and place the literal data into the 'title' attribute (where abbr expansions go), and the more brief and human-readable equivalent into the element itself. Further informative explanation of this use of <abbr>: Human vs. ISO8601 dates problem solved

Format

In General

The hReview format is based on a set of fields common to numerous review sites and formats in use today on the web. Where possible field names have been chosen based on those defined by the related hCard and hCalendar standards.

tags. optional. keywords or phrases, using RelTag, each with optional rating.

permalink. optional.

Field details

The fields of the hReview schema represent the following:

version:: This optional field permits hReview publishers to specify a particular version of hReview that their content uses. By omitting this field, the publisher is stating that implementations may interpret the hReviews according to any version of the hReview specification v0.2 or later. In practice the authors of this specification are comitted to maintaining backward compatibility with content produced using earlier versions of the specification. This field is syntax compatible with, and thus reuses the semantics of "VERSION" as defined in vCard RFC2426 section "3.6.9 VERSION Type Definition". The value of this field for this specification is "0.2".

summary:: This optional field serves as a title for the review itself.

item type:: This optional field "type" provides the type of the item being reviewed, one of the following: product, business, event, person, place, website, url.

item info:: This required field MUST have at a minimum the name ("fn" - the formatted text corresponding to the name) of the item , SHOULD provide at least one URI ("url") for the item, and MAY provide at least one URL to a photo or depiction ("photo") of the item. For items of type person or business, the item info (fn, url, photo) SHOULD be encapsulated in an ["hCard"]. Unique item IDs (e.g. ISBNs, UPCs) MAY be represented as a URN ("url") for the item.

reviewer:: The person who authored the review. An hCard representing the reviewer SHOULD be provided with full name and URL. Alternatively, just a name, email address, or URL to the person MAY be provided. To specify more than one of those, encapsulate them in an hCard. For anonymous reviews, use "anonymous" (without quotes) for the full name of the reviewer.

dtreviewed:: This required field MUST provide an ISO8601 absolute date time of when the review was written or otherwise authored. This field SHOULD use UTC, but MAY use the time zone offset syntax.

rating:: The rating is an integer from 1 to 5 inclusive indicating a rating for the item, higher indicating a better rating. Optionally a different integral "worst" value and/or "best" value MAY be specified (e.g. 6 from 0-10).

description:: This optional field contains the full text representing the written opinion of the reviewer. The field MAY include valid XHTML markup (e.g. paragraphs). User agents SHOULD preserve any markup. Multiple descriptions or section descriptions (e.g. pros and cons, plusses and minusses) SHOULD be included in the description field.

tags:: Tags are represented using a list of keywords or phrases (using the RelTag microformat for each individual keyword or phrase tag) that the reviewer associates with the item. The reviewer MAY optionally provide a tag-specific rating inside each RelTag, e.g. ambience:5. Tag-specific ratings by default use the same range as an overall rating for the item if present, and MAY also have a custom worst...best range specified. Authors MAY enclose all tags for a review inside an element with a specific classname, e.g. "categories" (from vCard RFC2426 and iCalendar RFC2445), but are not required to do so.

permalink:: This optional field is a URL for the hReview. In addition to using the <a href> tag for this field, the attribute rel="self bookmark" MUST be used to indicate that the hyperlink is a permalink for the review itself. If the hyperlink already contains a rel attribute, then the values self and bookmark MUST be included among the space-separated set of values in the attribute. Indexers MAY treat the permalink of a review as a unique ID in order to identify and collate the same review from multiple sources (such as indexing a page multiple times). The permalink MAY also be used to indicate or imply the origin of the review. Authors MAY use the classname of "permalink" on the element representing the permalink, but are not required to do so.

The following field names have been reused from the ["hCard"] and ["hCalendar"] microformats: version, summary, fn, url, email, photo, description, categories. In addition, items and reviewers described by hCards MAY contain any hCard field.

More Semantic Equivalents

For some properties there is a more semantic equivalent, and therefore they get special treatment, e.g.:

For any "url", use <a class="url" href="...">...</a> inside the element with class="hreview" in hReview.

And for "photo", use <img class="photo" src="..." alt="Photo of ..." />

Ratings are often presented either as a set of images or characters, e.g. "***". For these, the </code> element is particularly useful, as such characters are an abbreviation for the precise rating, e.g. ***

. This is further explored in the next section.

Language

To explicitly convey the natural language that an hReview is written in, use the standard (X)HTML 'lang' attribute on the element with class="hreview", e.g.

...

If portions of an hReview (e.g. the item name) are in a different language, use the 'lang' attribute on those portions.

hReview processors which need to handle the language of reviews MUST process the standard (X)HTML 'lang' attribute as specified.

Human vs. Machine Readable

If an </code> element is used for a property, then its 'title' attribute is used for the value of the property, instead of the contents of the element, which can then be used to provide a user-friendly alternate presentation of the value.

Similarly, if an <img /> element is used for one or more properties, it MUST be treated as follows:

For the "photo" property and any other property that takes a URL as its value, the src="..." attribute provides the property value.

For other properties, the <img /> element's 'alt' attribute is the value of the property.

Notes

This section is informative.

By marking up a review with the hReview microformat, the expectation is communicated that the review MAY be indexed. This has no impact on the copyright of the review itself.

The enumerated list of item types is under development and may be extended.

Each type may have custom hReview fields that follow the common set.

Additional details about a particular item should be specified with the rest of the item's info at the URL provided for the item.

Most rating systems use the range 1 to 5, and most of those represent the rating as a number of stars. Sites may use whatever graphic they wish to represent the rating.

Examples

Here are a few examples of reviews from current web sites, and how they could be easily enhanced to support the hReview structured review microformat.

Restaurant reviews

Here is an example of a simple online restaurant review:

<div>
<span>5 stars out of 5 stars</span>
<h4>Crepes on Cole is awesome</h4>
<span>Reviewer: <span>Tantek</span> - April 18, 2005</span>
<blockquote><p>
Crepes on Cole is one of the best little creperies in San Francisco.
Excellent food and service. Plenty of tables in a variety of sizes
for parties large and small. Window seating makes for excellent
people watching to/from the N-Judah which stops right outside.
I've had many fun social gatherings here, as well as gotten
plenty of work done thanks to neighborhood WiFi.
</p></blockquote>
<p>Visit date: <span>April 2005</span></p>
<p>Food eaten: <span>Florentine crepe</span></p>
</div>

Crepes on Cole is one of the best little creperies in San Francisco.
Excellent food and service. Plenty of tables in a variety of sizes
for parties large and small. Window seating makes for excellent
people watching to/from the N-Judah which stops right outside.
I've had many fun social gatherings here, as well as gotten
plenty of work done thanks to neighborhood WiFi.

Visit date: April 2005

Food eaten: Florentine crepe

</div>
</nowiki></pre>

Note that some of the properties of this sample review are not captured by hReview (visit date, food eaten). This is deliberate per the scope of keeping hReview minimal and simple.

This sample hReview could be rendered like this:

5 stars out of 5 starsCrepes on Cole is awesome
Reviewer: Tantek - April 18, 2005

Crepes on Cole is one of the best little creperies in San Francisco. Excellent food and service. Plenty of tables in a variety of sizes for parties large and small. Window seating makes for excellent people watching to/from the N-Judah which stops right outside. I've had many fun social gatherings here, as well as gotten plenty of work done thanks to neighborhood wifi.

Visit date: April 2005
Food eaten: Florentine crepe

Multidimensional Restaurant Review

Some restaurant reviews indicate ratings for different aspects of the restaurant. Such details are represented in hReview using tagged ratings. In addition, note the inline tags inside the description of this review.

This cafe is a welcoming oasis on the Peninsula. It even has a fountain outside which cloaks the nearby sounds of El Camino traffic. Next door to a superb indy bookstore, Cafe Borrone is an ideal spot to grab a coffee or a snack to accompany a newly purchased book or imported periodical. Soups and sandwich specials rotate daily. The corn chowder with croutons and big chunks of cheese goes especially well with a freshly toasted mini-baguette. Evenings are often crowded and may require sharing a table with a perfect stranger. Espresso afficionados will appreciate the Illy coffee. Noise levels can vary from peaceful in the late mornings to nearly overwhelming on jazz band nights.

This cafe is a welcoming oasis on the Peninsula. It even has a fountain outside which cloaks the nearby sounds of El Camino traffic. Next door to a superb indy bookstore, Cafe Borrone is an ideal spot to grab a coffee or a snack to accompany a newly purchased book or imported periodical. Soups and sandwich specials rotate daily. The corn chowder with croutons and big chunks of cheese goes especially well with a freshly toasted mini-baguette. Evenings are often crowded and may require sharing a table with a perfect stranger. Espresso afficionados will appreciate the Illy coffee. Noise levels can vary from peaceful in the late mornings to nearly overwhelming on jazz band nights.

Product review

Here is an example of a product review:

<div>
<a href="http://www.amazon.com/exec/obidos/ASIN/B000089CJI/">
<img src="http://images.amazon.com/images/P/B000089CJI.01._SCTHUMBZZZ_.jpg"
alt="Album cover photo: The Postal Service: Give Up." />
The Postal Service: Give Up</a>
<blockquote><p>
"The people thought they were just being rewarded for treating others
as they like to be treated, for obeying stop signs and curing diseases,
for mailing letters with the address of the sender... Don't wake me,
I plan on sleeping in..."
</p><p>
"Nothing Better" is a great track on this album, too...
</p></blockquote>
(*****)
</div>

Adding hReview to this review is also quite simple, but in this case requires a few more elements for the rating and reviewer which are required by hReview:

<blocquote>"The people thought they were just being rewarded for treating others as they like to be treated, for obeying stop signs and curing diseases, for mailing letters with the address of the sender... Don't wake me, I plan on sleeping in..."</blockquote>

Examples in the wild

This section is informative.

The following sites have published hReviews, and thus are a great place to start for anyone looking for examples "in the wild" to try parsing, indexing, organizing etc. If you publish hReviews on your own page, feel free to add it to the top of this list. Once the list grows too big, we'll make a separate wiki page.

Implementations

This section is informative.

The following implementations have been developed which either generate or parse hReviews. If you have an hReview implementation, feel free to add it to the top of this list. Once the list grows too big, we'll make a separate wiki page.

Changes from v0.1

tags requirement removed. Removed requirement of classname "tags" for the tags field, and thus removed the requirement to have an explicit tags field at all, permitting tags anywhere inside the hReview, e.g. inside the description.

permalink requirement removed. Removed requirement of classname "permalink", as it is unnecessary, given that the permalink field explicitly requires a hyperlink with rel values of "self" and "bookmark".