hreview: Difference between revisions
(editorial: microformats IRC channel, regardless of how its accessed, previously mailing list which hasn't been used in years.) |
|||
(152 intermediate revisions by 41 users not shown) | |||
Line 1: | Line 1: | ||
{{DISPLAYTITLE:hReview 0.4 (in progress)}} | |||
{{latest|h-review}} | |||
{{DraftSpecification}} | |||
[[hreview|hReview]] is a simple, open, distributed format, suitable for embedding reviews (of products, services, businesses, events, etc.) in | [[hreview|hReview]] is a simple, open, distributed format, suitable for embedding reviews (of products, services, businesses, events, etc.) in HTML, XHTML, Atom, RSS, and arbitrary XML. hReview is one of several [[microformats]] open standards. | ||
Want to get started with writing an [[hreview|hReview]]? Use the [http://microformats.org/code/hreview/creator hReview creator] to write a review and publish it. | Want to get started with writing an [[hreview|hReview]]? Use the [http://microformats.org/code/hreview/creator hReview creator] to write a review and publish it. | ||
== Microformats Draft Specification | == Microformats Draft Specification 2012 == | ||
<div class="vcard"> | |||
;<span class="role">Editor</span> | |||
:<span class="fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="url">http://tantek.com/</span>, [http://mozilla.org Mozilla]) | |||
</div> | |||
[[hreview#Copyright|copyright]] and [[hreview#Patents|patents]] statements apply. | |||
== Status == | |||
hReview 0.4 is a microformats.org draft specification. Public discussion on hReview takes place on [[hreview-feedback]], the #microformats [[irc]] channel, and previously the [http://microformats.org/discuss/mail/microformats-discuss/ microformats-discuss mailing list]. | |||
=== Available languages === | |||
The English version of this specification is the only normative version. For translations of this document see the [[#translations]] section. | |||
=== Errata and Updates === | |||
Known errors and issues in this specification are corrected in [[hreview-issues-resolved|resolved]] and [[hreview-issues-closed|closed]] issues. Please check there before reporting [[hreview-issues|issues]]. | |||
The hReview 0.4 update is currently under development and incorporates known errata corrections as well as the [[value-class-pattern]]. | |||
== Introduction == | == Introduction == | ||
Line 24: | Line 31: | ||
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 both numerous [[review-examples]] in the wild and earlier attempts at [[review-formats]], and have designed hReview around a simple minimal schema for reviews. Feedback is encouraged on the [[hreview-feedback|hReview feedback]] page. | 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 both numerous [[review-examples]] in the wild and earlier attempts at [[review-formats]], and have designed hReview around a simple minimal schema for reviews. Feedback is encouraged on the [[hreview-feedback|hReview feedback]] page. | ||
{{rfc-2119-intro}} | |||
=== Scope === | === Scope === | ||
Reviews consistently share several common | Reviews consistently share several common aspects. Where possible hReview has been based on this minimal common subset. | ||
==== Out of scope ==== | ==== Out of scope ==== | ||
Portions of reviews that are specific to particular kinds of items 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. | 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. | ||
== Format == | == Format == | ||
=== In General === | === In General === | ||
The hReview format is based on a set of | The hReview format is based on a set of properties common to numerous review sites and formats in use today on the web. Where possible property names have been chosen based on those defined by the related [[hcard|hCard]] and [[hcalendar|hCalendar]] standards. | ||
=== Schema === | === Schema === | ||
Line 46: | Line 49: | ||
* hReview ('''<code>hreview</code>''') | * hReview ('''<code>hreview</code>''') | ||
** '''<code>summary</code>'''. optional. text. | ** '''<code>summary</code>'''. optional. text. | ||
** item '''<code>type</code>'''. optional. product | business | event | person | place | website | url. | ** item '''<code>type</code>'''. optional. product | business | event | person | place | website | url. | ||
** '''<code>item</code>''' info. required. '''<code>fn</code>''' ('''<code>url</code>''' || '''<code>photo</code>''' ) | '''[[hcard|hCard]]''' (for person or business) | '''[[hcalendar|hCalendar]]''' (for event) | ** '''<code>item</code>''' info. required. '''<code>fn</code>''' ('''<code>url</code>''' || '''<code>photo</code>''' ) | '''[[hcard|hCard]]''' (for person or business) | '''[[hcalendar|hCalendar]]''' (for event) | ||
** '''<code>reviewer</code>'''. optional. '''[[hcard|hCard]]'''. | ** '''<code>reviewer</code>'''. optional. '''[[hcard|hCard]]'''. | ||
** '''<code>dtreviewed</code>'''. optional. ISO8601 absolute date time. | ** '''<code>dtreviewed</code>'''. optional. ISO8601 absolute date or date time. Use [[value-class-pattern]] if necessary especially for [[accessibility]]. ([http://www.w3.org/TR/NOTE-datetime http://www.w3.org/TR/NOTE-datetime]) | ||
** '''<code>rating</code>'''. optional. 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>value</code>'''. | ** '''<code>rating</code>'''. optional. 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>value</code>'''. | ||
** '''<code>description</code>'''. optional. text with optional valid | ** '''<code>description</code>'''. optional. text with optional valid HTML markup. | ||
** tags. optional. keywords or phrases, using '''[[rel-tag]]''', each with optional rating. | ** tags. optional. keywords or phrases, using '''[[rel-tag]]''', each with optional rating. | ||
** permalink. optional, using '''[[rel-bookmark]]''' and '''[[rel-self]]'''. | ** permalink. optional, using '''[[rel-bookmark]]''' and '''[[rel-self]]'''. | ||
** license. optional, using '''[[rel-license]]'''. | ** license. optional, using '''[[rel-license]]'''. | ||
=== | === Property details === | ||
Details of the hReview properties: | |||
'''summary''':: This optional | '''summary''':: This optional property serves as a short synopsis, title, or name of the review. Re-used from [[hCalendar]] which re-uses it from iCalendar (section 4.8.1.12 of RFC 2445). | ||
''' | '''type''':: This optional property provides the type of the item being reviewed, one of the following: <code>product, business, place, person, event, website, url</code>. If omitted, then in some cases the item type may be inferred. If the item is also an [[hcard|hCard]], then the item type is a "business", "place", or a "person" based upon which of those the hCard represents. If the item is also an [[hcalendar|hCalendar]] event, then the item type is an "event". | ||
'''item | '''item''':: This required property {{must}} have at a minimum the name (using the subproperty "fn" - the formatted text corresponding to the name, except for an event item which {{must}} have the "summary" subproperty inside the respective hCalendar "vevent") of ''the'' item (an hReview describes only one 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) {{must}} be encapsulated in an [[hcard|hCard]]. For items of type event, the item info {{should}} be encapsulated in an [[hcalendar|hCalendar]] "vevent". Non-URL unique item IDs (e.g. ISBNs, UPCs) {{may}} be represented as a URN ("url") for the item. Encapsulated microformats (e.g. [[hcard|hCard]] and [[hcalendar|hCalendar]] events for now) may be set on the item itself (e.g. class="item vcard"). However, when using item info subproperties ("fn", "url", "photo"), they {{must}} be nested <em>inside</em> the item element. | ||
'''reviewer''':: The optional | '''reviewer''':: The optional property specifies the person who authored the review. If the reviewer is specified, an hCard representing the reviewer {{must}} be provided. For anonymous reviews, use "anonymous" (without quotes) for the full name of the reviewer. If no "reviewer" is found inside the hReview, parsers {{should}} look outside the hReview, in the context of the page, for the "reviewer". If there is no "reviewer" outside either, then parsers {{should}} use the author defined by the containing document language, e.g. for HTML documents, the <code><nowiki><address></nowiki></code> contact info for the page (which is ideally marked up as an [[hcard|hCard]] as well), for Atom 1.0 the <code><nowiki><entry></nowiki></code> <code><nowiki><author></nowiki></code> if present and if not the <code><nowiki><feed></nowiki></code> <code><nowiki><author></nowiki></code>, for RSS the <code><nowiki><author></nowiki></code> inside the containing <code><nowiki><item></nowiki></code> element. | ||
'''dtreviewed''':: This optional | '''dtreviewed''':: This optional property when present {{must}} provide an [[ISO-8601|ISO8601]] absolute date or date time of when the review was written or otherwise authored ([http://www.w3.org/TR/NOTE-datetime http://www.w3.org/TR/NOTE-datetime]). This property must use the [[value-class-pattern]] if necessary (e.g. for [[accessibility]], {{should}} use UTC, but {{may}} use the time zone offset syntax. If dtreviewed is absent from the hReview, then look outside the hReview, in the surrounding context. If the context is an [[hatom|hAtom]] entry, use its "published" (or "updated" if that is missing) datetime as the dtreviewed, if not present on the entry, use the "published" (or "updated" if that is missing) of the feed. Otherwise use the creation date (or modified date if that is missing) information according to the containing document language (e.g. "published"/"updated" similarly for Atom feeds), then protocol (e.g. HTTP Last-Modified, or file system last modified datetime) as the dtreviewed. | ||
'''rating''':: The rating is a fixed point integer (one decimal point of precision) from 1.0 to 5.0 inclusive indicating a rating for the item, higher indicating a better rating by default. Optionally a different integral "worst" value and/or "best" value | '''rating''':: The rating is a fixed point integer (one decimal point of precision) from 1.0 to 5.0 inclusive indicating a rating for the item, 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). The "best" value may be numerically smaller than the "worst" value. | ||
'''description''':: This optional | '''description''':: This optional property serves as a more detailed synopsis of the review (i.e. full text representing the written opinion of the reviewer) than that provided by summary. The property {{may}} include valid HTML markup (e.g. paragraphs). User agents {{should}} preserve any markup. Multiple descriptions or section descriptions (e.g. pros and cons, pluses and minuses) {{should}} be included in the description property. | ||
'''tags''':: Tags are represented using a list of keywords or phrases (using the [[rel-tag]] microformat for each individual keyword or phrase tag) that the reviewer associates with the item. The reviewer | '''tags''':: Tags are represented using a list of keywords or phrases (using the [[rel-tag]] 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 [[rel-tag]], e.g. ambiance: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}} also invert this structure for the same semantic if it is more convenient for their markup, that is, place the [[rel-tag]] inside a rating to indicate a rated tag. Note: rated tags {{should}} ideally use a tag space that explains what the ratings for that tag mean. E.g. Food:18/30 {{should}} link to a tags space for Food that explains what an 18 out of 30 means for the Food tag. | ||
'''permalink''':: This optional | '''permalink''':: This optional property is a URL for the hReview. In addition to using the <code><a href></code> tag for this property, the attribute <code>rel="self bookmark"</code> {{must}} be used to indicate that the hyperlink is a permalink for the review itself. If the hyperlink already contains a <code>rel</code> attribute, then the values <code>self</code> and <code>bookmark</code> {{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. | ||
'''license''':: | '''license''':: an hReview indicates the license for its contents using the '''[[rel-license]]''' microformat. | ||
The following property names have been reused from the [[hcard|hCard]] and [[hcalendar|hCalendar]] microformats: <code>summary, fn, url, photo, description</code>. In addition, items and reviewers described by hCards {{may}} contain any hCard property. The rel value "self" has been reused from the [http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html Atom 1.0 specification]. | |||
=== More Semantic Equivalents === | === More Semantic Equivalents === | ||
Line 97: | Line 95: | ||
==== Language ==== | ==== Language ==== | ||
* To explicitly convey the natural language that an hReview is written in, use the standard | * To explicitly convey the natural language that an hReview is written in, use the standard HTML 'lang' attribute on the element with class="hreview", e.g. <code><div class="hreview" lang="en"> ... </div></code> 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 | * hReview processors which need to handle the language of reviews MUST process the standard HTML 'lang' attribute as specified. | ||
=== Human vs. Machine Readable === | === Human vs. Machine Readable === | ||
Line 108: | Line 106: | ||
# For other properties, the <code><img /></code> element's '<code>alt</code>' attribute is the value of the property. | # For other properties, the <code><img /></code> element's '<code>alt</code>' attribute is the value of the property. | ||
=== | === Includes === | ||
hReview 0. | hReview 0.4 includes support for the [[include-pattern]]. | ||
Often a single page lists an item, and then several reviews for that item. In order to avoid having to repeat the item info for each review of the item, the first review should be marked up as an hReview, with a unique "id" attribute on the item info, and then following reviews should use the object [[include-pattern]] to include the item info from the first review. | Often a single page lists an item, and then several reviews for that item. In order to avoid having to repeat the item info for each review of the item, the first review should be marked up as an hReview, with a unique "id" attribute on the item info, and then following reviews should use the object [[include-pattern]] to include the item info from the first review. | ||
=== Notes === | === Notes === | ||
Line 120: | Line 117: | ||
* 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 which the publisher may explicitly specify using [[rel-license]] as specified above. | * 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 which the publisher may explicitly specify using [[rel-license]] as specified above. | ||
* The enumerated list of item types is under development and may be extended. | * The enumerated list of item types is under development and may be extended. | ||
* Additional details about a particular item should be specified with the rest of the item's info at the URL provided for the item. | * 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.0 to 5.0, and most of those represent the rating as a number (and possibly half) of stars. Sites may use whatever graphic they wish to represent the rating. | * Most rating systems use the range 1.0 to 5.0, and most of those represent the rating as a number (and possibly half) of stars. Sites may use whatever graphic they wish to represent the rating. | ||
Line 131: | Line 127: | ||
=== Restaurant reviews === | === Restaurant reviews === | ||
Here is an example of a | Here is an example of a brief online restaurant review: | ||
< | <source lang=html4strict> | ||
<div> | <div> | ||
<span>5 stars out of 5 stars</span> | <span>5 stars out of 5 stars</span> | ||
Line 149: | Line 145: | ||
<p>Food eaten: <span>Florentine crepe</span></p> | <p>Food eaten: <span>Florentine crepe</span></p> | ||
</div> | </div> | ||
</ | </source> | ||
Adding hReview | Adding a few elements & class names makes the review into an hReview: | ||
< | <source lang=html4strict> | ||
<div class="hreview"> | <div class="hreview"> | ||
<span><span class="rating">5</span> out of 5 stars</span> | <span><span class="rating">5</span> out of 5 stars</span> | ||
<h4 class="summary">Crepes on Cole is awesome</h4> | <h4 class="summary">Crepes on Cole is awesome</h4> | ||
<span class="reviewer vcard">Reviewer: <span class="fn">Tantek</span> - | <span class="reviewer vcard">Reviewer: <span class="fn">Tantek</span></span> - | ||
<abbr class="dtreviewed" title=" | <abbr class="dtreviewed" title="2005-04-18">April 18, 2005</abbr> | ||
<div class="description item vcard"><p> | <div class="description item vcard"><p> | ||
<span class="fn org">Crepes on Cole</span> is one of the best little | <span class="fn org">Crepes on Cole</span> is one of the best little | ||
Line 171: | Line 167: | ||
<p>Food eaten: <span>Florentine crepe</span></p> | <p>Food eaten: <span>Florentine crepe</span></p> | ||
</div> | </div> | ||
</ | </source> | ||
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. | 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. | ||
Line 211: | Line 207: | ||
As an hReview: | As an hReview: | ||
< | <source lang=html4strict> | ||
<div class="hreview"> | <div class="hreview"> | ||
<div class="item vcard"> | <div class="item vcard"> | ||
Line 254: | Line 250: | ||
<a href="http://en.wikipedia.org/wiki/jazz" rel="tag">jazz</a> band nights. | <a href="http://en.wikipedia.org/wiki/jazz" rel="tag">jazz</a> band nights. | ||
</p></div> | </p></div> | ||
<a href="http://microformats.org/wiki/hreview">hReview</a> | |||
by <span class="reviewer vcard"><span class="fn">anonymous</span></span>, | by <span class="reviewer vcard"><span class="fn">anonymous</span></span>, | ||
<abbr class="dtreviewed" title=" | <abbr class="dtreviewed" title="2005-04-28">April 28th, 2005</abbr>. | ||
</div> | </div> | ||
</ | </source> | ||
With an accompanying CSS style sheet like: | With an accompanying CSS style sheet like: | ||
< | <source lang=html4strict> | ||
a.url { display:block } | a.url { display:block } | ||
ul { margin:1em 0; padding:0 } | ul { margin:1em 0; padding:0 } | ||
ul li { display:inline } | ul li { display:inline } | ||
</ | </source> | ||
This hReview could be presented similar to the original text: | This hReview could be presented similar to the original text: | ||
Line 282: | Line 277: | ||
This [http://en.wikipedia.org/wiki/cafe 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 [http://en.wikipedia.org/wiki/coffee coffee] or a snack to accompany a newly purchased book or imported periodical. [http://technorati.com/tag/soup Soups] and [http://technorati.com/tag/sandwich 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. [http://flickr.com/photos/tags/espresso Espresso] afficionados will appreciate the [http://en.wikipedia.org/wiki/Illy Illy] coffee. Noise levels can vary from peaceful in the late mornings to nearly overwhelming on [http://en.wikipedia.org/wiki/jazz jazz] band nights. | This [http://en.wikipedia.org/wiki/cafe 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 [http://en.wikipedia.org/wiki/coffee coffee] or a snack to accompany a newly purchased book or imported periodical. [http://technorati.com/tag/soup Soups] and [http://technorati.com/tag/sandwich 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. [http://flickr.com/photos/tags/espresso Espresso] afficionados will appreciate the [http://en.wikipedia.org/wiki/Illy Illy] coffee. Noise levels can vary from peaceful in the late mornings to nearly overwhelming on [http://en.wikipedia.org/wiki/jazz jazz] band nights. | ||
[http://microformats.org/wiki/hreview hReview] by anonymous, April 28th, 2005. | |||
=== Product review === | === Product review === | ||
Here is an example of a product review: | Here is an example of a product review: | ||
< | <source lang=html4strict> | ||
<div> | <div> | ||
<a href="http://www.amazon.com/exec/obidos/ASIN/B000089CJI/"> | <a href="http://www.amazon.com/exec/obidos/ASIN/B000089CJI/"> | ||
Line 303: | Line 298: | ||
(*****) | (*****) | ||
</div> | </div> | ||
</ | </source> | ||
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: | 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: | ||
< | <source lang=html4strict> | ||
<div class="hreview"><span class="item"> | <div class="hreview"><span class="item"> | ||
<a class="url fn" href="http://www.amazon.com/exec/obidos/ASIN/B000089CJI/"> | <a class="url fn" href="http://www.amazon.com/exec/obidos/ASIN/B000089CJI/"> | ||
Line 325: | Line 320: | ||
<p class="reviewer vcard">Review by | <p class="reviewer vcard">Review by | ||
<a class="url fn" href="http://ifindkarma.com/blog/">Adam Rifkin</a>, | <a class="url fn" href="http://ifindkarma.com/blog/">Adam Rifkin</a>, | ||
<abbr class="dtreviewed" title=" | <abbr class="dtreviewed" title="2005-02">February 2005</abbr> | ||
</p> | </p> | ||
</div> | </div> | ||
</ | </source> | ||
And this hReview might be presented like this: | And this hReview might be presented like this: | ||
Line 350: | Line 345: | ||
Finally, here is an example of a movie review. | Finally, here is an example of a movie review. | ||
< | <source lang=html4strict> | ||
<div> | <div> | ||
<span>anonymous, April 18th, 2005</span> | <span>anonymous, April 18th, 2005</span> | ||
Line 363: | Line 358: | ||
</p></blockquote> | </p></blockquote> | ||
</div> | </div> | ||
</ | </source> | ||
With hReview: | With hReview: | ||
< | <source lang=html4strict> | ||
<div class="hreview"> | <div class="hreview"> | ||
<span class="reviewer vcard"> | <span class="reviewer vcard"> | ||
<span class="fn">anonymous</span>, | <span class="fn">anonymous</span>, | ||
</span> | </span> | ||
<abbr class="dtreviewed" title="2005-04-18">April 18th, 2005</abbr> | |||
<div class="item"> | <div class="item"> | ||
<a lang="zh" class="url fn" href="http://www.imdb.com/title/tt0299977/"> | <a lang="zh" class="url fn" href="http://www.imdb.com/title/tt0299977/"> | ||
Line 383: | Line 378: | ||
</p></div> | </p></div> | ||
</div> | </div> | ||
</ | </source> | ||
Which could be presented like this: | Which could be presented like this: | ||
Line 394: | Line 389: | ||
== Examples in the wild == | == Examples in the wild == | ||
This section is '''informative'''. | This section is '''informative'''. The number of hReview examples in the wild has expanded far beyond the capacity of being kept inline in this specification. They have been moved to a [[hreview-examples-in-wild|separate page]]. | ||
See [[hreview-examples-in-wild|hReview Examples in the wild]]. | |||
== Implementations == | |||
This section is '''informative'''. The number of hReview implementations has also expanded beyond the capacity of keeping them inline. They have been moved to a [[hreview-implementations|separate page]]. | |||
See [[hreview-implementations|hReview Implementations]]. | |||
== Design Principles == | |||
This section is '''informative'''. hReview was designed using design [[principles]] similar to those that went into [[hCard]] and thus this overview is included for informational purposes. | |||
{{semantic-xhtml-design-principles}} | |||
== Inspiration and Acknowledgments == | |||
Thanks to everyone who responded to the open call for implementor participation for hReview. The authors in particular wish to thank the following individuals for their constructive input and feedback: [[User:Richardault|Richard Ault]], [http://dannyayers.com Danny Ayers], [http://www.vertexdev.com/~jeff/ Jeffrey Barr],[http://adriancuthbert.blogspot.com/ Adrian Cuthbert],[http://jason.defillippo.com/ Jason DeFillippo], [http://www.hybernaut.com/bdv Brian Del Vecchio], Scott Derringer, [http://budgibson.com/home/ Bud Gibson], [http://joi.ito.com/ Joi Ito], [http://www.kanai.net/weblog/ Gen Kanai],[http://niallkennedy.com/ Niall Kennedy], [http://labs.commerce.net/wiki/index.php/Rohit_Khare Rohit Khare], [http://theryanking.com/ Ryan King], [http://www.jluster.org/ Jonas Luster], [http://epeus.blogspot.com/ Kevin Marks], Mark Nottingham, [http://www.powazek.com/ Derek Powazek], [http://www.judysbook.com/ Jeff Rodenburg], [http://sifry.com/alerts/ David Sifry], [http://jystewart.net/ James Stewart], [http://kung-foo.tv/ Adriaan Tijsseling], [http://www.flashenabled.com/ Phillip Torrone], Thai Tran, [http://w6daily.winn.com/ Phillip Winn], [http://yohei-y.blogspot.com YAMAMOTO Yohei]. | |||
; hReview v0.3 Authors | |||
: [[User:Tantek|Tantek Çelik]] (tantek.com, and before at [http://technorati.com/ Technorati]) | |||
: <span class="vcard"><span class="fn">[http://360.yahoo.com/alidiabali Ali Diab]</span></span> ([http://yahoo.com Yahoo! Inc.]) | |||
: <span class="vcard"><span class="fn">[http://ianmcall.blogspot.com/ Ian McAllister]</span></span> ([http://amazon.com/ Amazon.com]) | |||
: <span class="vcard"><span class="fn">[http://journals.aol.com/panzerjohn/abstractioneer John Panzer]</span></span> ([http://www.aol.com America Online, Inc.]) | |||
: <span class="vcard"><span class="fn">[http://ifindkarma.com/blog Adam Rifkin]</span></span> ([http://labs.commerce.net/ CommerceNet Labs]) | |||
: <span class="vcard"><span class="fn">[http://sippey.typepad.com/ Michael Sippey]</span></span> ([http://sixapart.com Six Apart, Ltd]) | |||
== References == | == References == | ||
=== Normative References === | === Normative References === | ||
* [http:// | * [http://w3.org/html5 HTML5] | ||
* [http://gmpg.org/xmdp/ XMDP] | * [http://gmpg.org/xmdp/ XMDP] | ||
* [[hcard|hCard]] | * [[hcard|hCard]] | ||
Line 481: | Line 426: | ||
=== Informative References === | === Informative References === | ||
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE] | |||
* [http://www.w3.org/TR/REC-CSS1 CSS1] | * [http://www.w3.org/TR/REC-CSS1 CSS1] | ||
* ISO.8601. | * ISO.8601 [http://www.w3.org/TR/NOTE-datetime http://www.w3.org/TR/NOTE-datetime] | ||
** International Organization for Standardization, "Data elements and interchange formats - Information interchange - Representation of dates and times", ISO Standard 8601, June 1988. | ** International Organization for Standardization, "Data elements and interchange formats - Information interchange - Representation of dates and times", ISO Standard 8601, June 1988. | ||
* [http://www.ietf.org/rfc/rfc3667.txt RFC3667] | * [http://www.ietf.org/rfc/rfc3667.txt RFC3667] | ||
* [http://www.ietf.org/rfc/rfc3668.txt RFC3668] | * [http://www.ietf.org/rfc/rfc3668.txt RFC3668] | ||
Line 496: | Line 441: | ||
* [[xoxo|XOXO]] | * [[xoxo|XOXO]] | ||
== Copyright == | |||
{{MicroformatCopyrightStatement2005}} | {{MicroformatCopyrightStatement2005}} | ||
* [[User:Tantek|Tantek]]: I release all my contributions to this specification into the public domain and I encourage the other authors to do so as well. | |||
** When all authors/editors have done so, we can remove the MicroFormatCopyrightStatement template reference and replace it with the MicroFormatPublicDomainContributionStatement. | |||
== Patents == | |||
{{MicroFormatPatentStatement}} | {{MicroFormatPatentStatement}} | ||
Line 505: | Line 452: | ||
This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added. | This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added. | ||
=== Changes from v0. | === Changes from v0.3 === | ||
The following changes have been made in hReview v0.3 over [[hreview-v0.2|hReview v0.2]]: | The following changes have been made in hReview v0.3 over [[hreview-v0.2|hReview v0.2]]: | ||
Normative changes: | Normative changes: | ||
# | # Add normative references to | ||
## [[value-class-pattern]] - required for support. | |||
## [[html5]] - for HTML5 parsing/DOM | |||
# Changed normative references to informative: | |||
## | ## Includes delegated fully to [[include-pattern]] rather than specifying "Object Includes" | ||
# | ## '''version''' property dropped. Little if any actual publication in practice, and no practical uses found. Smaller is better. | ||
## | ## '''dtreviewed''' may also be an absolute ISO8601 date, and must use [[value-class-pattern]] if necessary. | ||
# | |||
# | |||
# | |||
Informative changes (several, but in particular): | Informative changes (several, but in particular): | ||
# | # changed editorship/authorship to just [[Tantek]] in prep/heads-up for a rewrite. | ||
# examples updated: | |||
## '''dtreviewed''' property values use [[date-pattern]] | |||
## '''version''' property dropped | |||
== Articles == | |||
This <span id="Further_Reading">section</span> is <strong>informative</strong>. | |||
See: [[hreview-articles]]. | |||
== Related Pages == | == Related Pages == | ||
{{hreview-related-pages}} | |||
[[Category:Draft Specifications]] | |||
[[Category:hReview]] | |||
== | == Translations == | ||
* | Read the hReview draft specification in additional <span id="languages">languages</span>: | ||
* [[hreview-fr|français]] | |||
* [[hreview-ja|日本語]] |
Revision as of 20:37, 30 October 2023
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 is a simple, open, distributed format, suitable for embedding reviews (of products, services, businesses, events, etc.) in HTML, XHTML, Atom, RSS, and arbitrary XML. hReview is one of several microformats open standards.
Want to get started with writing an hReview? Use the hReview creator to write a review and publish it.
Microformats Draft Specification 2012
- Editor
- Tantek Çelik (http://tantek.com/, Mozilla)
copyright and patents statements apply.
Status
hReview 0.4 is a microformats.org draft specification. Public discussion on hReview takes place on hreview-feedback, the #microformats irc channel, and previously the microformats-discuss mailing list.
Available languages
The English version of this specification is the only normative version. For translations of this document see the #translations section.
Errata and Updates
Known errors and issues in this specification are corrected in resolved and closed issues. Please check there before reporting issues.
The hReview 0.4 update is currently under development and incorporates known errata corrections as well as the value-class-pattern.
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 both numerous review-examples in the wild and earlier attempts at review-formats, and have designed hReview around a simple minimal schema for reviews. Feedback is encouraged on the hReview feedback 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
Reviews consistently share several common aspects. Where possible hReview has been based on this minimal common subset.
Out of scope
Portions of reviews that are specific to particular kinds of items 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.
Format
In General
The hReview format is based on a set of properties common to numerous review sites and formats in use today on the web. Where possible property names have been chosen based on those defined by the related hCard and hCalendar standards.
Schema
The hReview schema consists of the following:
- hReview (
hreview
)summary
. optional. text.- item
type
. optional. product | business | event | person | place | website | url. item
info. required.fn
(url
||photo
) | hCard (for person or business) | hCalendar (for event)reviewer
. optional. hCard.dtreviewed
. optional. ISO8601 absolute date or date time. Use value-class-pattern if necessary especially for accessibility. (http://www.w3.org/TR/NOTE-datetime)rating
. optional. fixed point integer [1.0-5.0], with optional alternateworst
(default:1.0) and/orbest
(default:5.0), also fixed point integers, and explicitvalue
.description
. optional. text with optional valid HTML markup.- tags. optional. keywords or phrases, using rel-tag, each with optional rating.
- permalink. optional, using rel-bookmark and rel-self.
- license. optional, using rel-license.
Property details
Details of the hReview properties:
summary:: This optional property serves as a short synopsis, title, or name of the review. Re-used from hCalendar which re-uses it from iCalendar (section 4.8.1.12 of RFC 2445).
type:: This optional property provides the type of the item being reviewed, one of the following: product, business, place, person, event, website, url
. If omitted, then in some cases the item type may be inferred. If the item is also an hCard, then the item type is a "business", "place", or a "person" based upon which of those the hCard represents. If the item is also an hCalendar event, then the item type is an "event".
item:: This required property MUST have at a minimum the name (using the subproperty "fn" - the formatted text corresponding to the name, except for an event item which MUST have the "summary" subproperty inside the respective hCalendar "vevent") of the item (an hReview describes only one 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) MUST be encapsulated in an hCard. For items of type event, the item info SHOULD be encapsulated in an hCalendar "vevent". Non-URL unique item IDs (e.g. ISBNs, UPCs) MAY be represented as a URN ("url") for the item. Encapsulated microformats (e.g. hCard and hCalendar events for now) may 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.
reviewer:: The optional property specifies the person who authored the review. If the reviewer is specified, an hCard representing the reviewer MUST be provided. For anonymous reviews, use "anonymous" (without quotes) for the full name of the reviewer. If no "reviewer" is found inside the hReview, parsers SHOULD look outside the hReview, in the context of the page, for the "reviewer". If there is no "reviewer" outside either, then parsers SHOULD use the author defined by the containing document language, e.g. for HTML documents, the <address>
contact info for the page (which is ideally marked up as an hCard as well), for Atom 1.0 the <entry>
<author>
if present and if not the <feed>
<author>
, for RSS the <author>
inside the containing <item>
element.
dtreviewed:: This optional property when present MUST provide an ISO8601 absolute date or date time of when the review was written or otherwise authored (http://www.w3.org/TR/NOTE-datetime). This property must use the value-class-pattern if necessary (e.g. for accessibility, SHOULD use UTC, but MAY use the time zone offset syntax. If dtreviewed is absent from the hReview, then look outside the hReview, in the surrounding context. If the context is an hAtom entry, use its "published" (or "updated" if that is missing) datetime as the dtreviewed, if not present on the entry, use the "published" (or "updated" if that is missing) of the feed. Otherwise use the creation date (or modified date if that is missing) information according to the containing document language (e.g. "published"/"updated" similarly for Atom feeds), then protocol (e.g. HTTP Last-Modified, or file system last modified datetime) as the dtreviewed.
rating:: The rating is a fixed point integer (one decimal point of precision) from 1.0 to 5.0 inclusive indicating a rating for the item, 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). The "best" value may be numerically smaller than the "worst" value.
description:: This optional property serves as a more detailed synopsis of the review (i.e. full text representing the written opinion of the reviewer) than that provided by summary. The property MAY include valid HTML markup (e.g. paragraphs). User agents SHOULD preserve any markup. Multiple descriptions or section descriptions (e.g. pros and cons, pluses and minuses) SHOULD be included in the description property.
tags:: Tags are represented using a list of keywords or phrases (using the rel-tag 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 rel-tag, e.g. ambiance: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 also invert this structure for the same semantic if it is more convenient for their markup, that is, place the rel-tag inside a rating to indicate a rated tag. Note: rated tags SHOULD ideally use a tag space that explains what the ratings for that tag mean. E.g. Food:18/30 SHOULD link to a tags space for Food that explains what an 18 out of 30 means for the Food tag.
permalink:: This optional property is a URL for the hReview. In addition to using the <a href>
tag for this property, 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.
license:: an hReview indicates the license for its contents using the rel-license microformat.
The following property names have been reused from the hCard and hCalendar microformats: summary, fn, url, photo, description
. In addition, items and reviewers described by hCards MAY contain any hCard property. The rel value "self" has been reused from the Atom 1.0 specification.
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 the class name '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
<abbr>
element is particularly useful, as such characters are an abbreviation for the precise rating, e.g.<abbr class="rating" title="3.0">***</abbr>
. This is further explored in the next section.
Language
- To explicitly convey the natural language that an hReview is written in, use the standard HTML 'lang' attribute on the element with class="hreview", e.g.
<div class="hreview" lang="en"> ... </div>
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 HTML 'lang' attribute as specified.
Human vs. Machine Readable
If an <abbr>
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.
Includes
hReview 0.4 includes support for the include-pattern.
Often a single page lists an item, and then several reviews for that item. In order to avoid having to repeat the item info for each review of the item, the first review should be marked up as an hReview, with a unique "id" attribute on the item info, and then following reviews should use the object include-pattern to include the item info from the first review.
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 which the publisher may explicitly specify using rel-license as specified above.
- The enumerated list of item types is under development and may be extended.
- 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.0 to 5.0, and most of those represent the rating as a number (and possibly half) 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.
Want to get started with writing an hReview? Use the hReview creator to write a review and publish it on your blog.
Restaurant reviews
Here is an example of a brief 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>
Adding a few elements & class names makes the review into an hReview:
<div class="hreview">
<span><span class="rating">5</span> out of 5 stars</span>
<h4 class="summary">Crepes on Cole is awesome</h4>
<span class="reviewer vcard">Reviewer: <span class="fn">Tantek</span></span> -
<abbr class="dtreviewed" title="2005-04-18">April 18, 2005</abbr>
<div class="description item vcard"><p>
<span class="fn org">Crepes on Cole</span> is one of the best little
creperies in <span class="adr"><span class="locality">San Francisco</span></span>.
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></div>
<p>Visit date: <span>April 2005</span></p>
<p>Food eaten: <span>Florentine crepe</span></p>
</div>
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 stars
Crepes 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.
Here is one such review in text format:
Cafe Borrone 1010 El Camino Real, Menlo Park, CA 94025, +1-650-327-0830; cafeborrone.com Food: 18/30; Ambience: 19/30; Service: 15/30; Price: $$... 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.
As an hReview:
<div class="hreview">
<div class="item vcard">
<div class="fn org summary">Cafe Borrone</div>
<span class="adr">
<span class="street-address">1010 El Camino Real</span>,
<span class="locality">Menlo Park</span>,
<span class="region">CA</span>
<span class="postal-code">94025</span>,
</span>
<span class="tel">+1-650-327-0830</span>;
<a class="url" href="http://cafeborrone.com">cafeborrone.com</a>
</div>
<ul>
<li class="rating"><a href="http://en.wikipedia.org/wiki/Food" rel="tag">
Food: <span class="value">18</span>/<span class="best">30</span></a>;</li>
<li class="rating"><a href="http://flickr.com/photos/tags/Ambience" rel="tag">
Ambience: <span class="value">19</span>/<span class="best">30</span></a>;</li>
<li class="rating"><a href="http://en.wikipedia.org/wiki/Service" rel="tag">
Service: <span class="value">15</span>/<span class="best">30</span></a>;</li>
<li class="rating"><a href="http://en.wikipedia.org/wiki/Price" rel="tag">
Price: <abbr class="value" title="2">$$</abbr>...</a></li>
</ul>
<div class="description"><p>
This <abbr class="type" title="business">
<a href="http://en.wikipedia.org/wiki/cafe" rel="tag">cafe</a></abbr>
is a welcoming oasis on the Peninsula.
It even has a fountain outside which nearly eliminates
the sounds of El Camino traffic. Next door to a superb indy bookstore,
Cafe Borrone is an ideal spot to grab a
<a href="http://en.wikipedia.org/wiki/coffee" rel="tag">coffee</a>
or a meal to accompany a newly purchased book or imported periodical.
<a href="http://technorati.com/tag/soup" rel="tag">Soups</a> and
<a href="http://technorati.com/tag/sandwich" rel="tag">sandwich</a>
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.
<a href="http://flickr.com/photos/tags/espresso" rel="tag">Espresso</a>
afficionados will appreciate the
<a href="http://en.wikipedia.org/wiki/Illy" rel="tag">Illy</a> coffee.
Noise levels can vary from peaceful in the late mornings to nearly overwhelming on
<a href="http://en.wikipedia.org/wiki/jazz" rel="tag">jazz</a> band nights.
</p></div>
<a href="http://microformats.org/wiki/hreview">hReview</a>
by <span class="reviewer vcard"><span class="fn">anonymous</span></span>,
<abbr class="dtreviewed" title="2005-04-28">April 28th, 2005</abbr>.
</div>
With an accompanying CSS style sheet like:
a.url { display:block }
ul { margin:1em 0; padding:0 }
ul li { display:inline }
This hReview could be presented similar to the original text:
Cafe Borrone
1010 El Camino Real, Menlo Park, CA 94025, +1-650-327-0830;
cafeborrone.com
Food: 18/30;
Ambience: 19/30;
Service: 15/30;
Price: $$...
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.
hReview by anonymous, April 28th, 2005.
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:
<div class="hreview"><span class="item">
<a class="url fn" 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. "
class="photo" />
The Postal Service: Give Up</a></span>
<div class="description"><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></div>
(<abbr class="rating" title="5">*****</abbr>)
<p class="reviewer vcard">Review by
<a class="url fn" href="http://ifindkarma.com/blog/">Adam Rifkin</a>,
<abbr class="dtreviewed" title="2005-02">February 2005</abbr>
</p>
</div>
And this hReview might be presented like this:
[Album cover photo: ]
[The Postal Service:]
[ Give Up ]
The Postal Service: Give Up
"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..."
"Nothing Better" is a great track on this album, too...
(*****)
Review by Adam Rifkin, February 2005.
Movie Review
Finally, here is an example of a movie review.
<div>
<span>anonymous, April 18th, 2005</span>
<div>
<a lang="zh" href="http://www.imdb.com/title/tt0299977/">
Ying Xiong (<span lang="en">HERO</span>)
</a>
</div>
<div>Rating: 4 out of 5</div>
<blockquote><p>
This movie has great visuals and music.
</p></blockquote>
</div>
With hReview:
<div class="hreview">
<span class="reviewer vcard">
<span class="fn">anonymous</span>,
</span>
<abbr class="dtreviewed" title="2005-04-18">April 18th, 2005</abbr>
<div class="item">
<a lang="zh" class="url fn" href="http://www.imdb.com/title/tt0299977/">
Ying Xiong (<span lang="en">HERO</span>)
</a>
</div>
<div>Rating: <span class="rating">4</span> out of 5</div>
<div class="description"><p>
This movie has great music and visuals.
</p></div>
</div>
Which could be presented like this:
anonymous, April 18th, 2005
Ying Xiong (HERO)
Rating: 4 out of 5
This movie has great music and visuals.
Examples in the wild
This section is informative. The number of hReview examples in the wild has expanded far beyond the capacity of being kept inline in this specification. They have been moved to a separate page.
See hReview Examples in the wild.
Implementations
This section is informative. The number of hReview implementations has also expanded beyond the capacity of keeping them inline. They have been moved to a separate page.
Design Principles
This section is informative. hReview was designed using design principles similar to those that went into hCard and thus this overview is included for informational purposes.
Note: the Semantic XHTML Design Principles were written primarily within the context of developing hCard and hCalendar, thus it may be easier to understand these principles in the context of the hCard design methodology (i.e. read that first). Tantek
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.
- Reuse the schema (names, objects, properties, values, types, hierarchies, constraints) as much as possible from pre-existing, established, well-supported standards by reference. Avoid restating constraints expressed in the source standard. Informative mentions are ok.
- 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
Inspiration and Acknowledgments
Thanks to everyone who responded to the open call for implementor participation for hReview. The authors in particular wish to thank the following individuals for their constructive input and feedback: Richard Ault, Danny Ayers, Jeffrey Barr,Adrian Cuthbert,Jason DeFillippo, Brian Del Vecchio, Scott Derringer, Bud Gibson, Joi Ito, Gen Kanai,Niall Kennedy, Rohit Khare, Ryan King, Jonas Luster, Kevin Marks, Mark Nottingham, Derek Powazek, Jeff Rodenburg, David Sifry, James Stewart, Adriaan Tijsseling, Phillip Torrone, Thai Tran, Phillip Winn, YAMAMOTO Yohei.
- hReview v0.3 Authors
- Tantek Çelik (tantek.com, and before at Technorati)
- Ali Diab (Yahoo! Inc.)
- Ian McAllister (Amazon.com)
- John Panzer (America Online, Inc.)
- Adam Rifkin (CommerceNet Labs)
- Michael Sippey (Six Apart, Ltd)
References
Normative References
Informative References
- XHTML 1.0 SE
- CSS1
- ISO.8601 http://www.w3.org/TR/NOTE-datetime
- International Organization for Standardization, "Data elements and interchange formats - Information interchange - Representation of dates and times", ISO Standard 8601, June 1988.
- RFC3667
- RFC3668
- W3C Patent Policy
- Crepes on Cole reviews on Yahoo! Local
- Other reviews efforts. See reviews-formats.
- Contributed from http://developers.technorati.com/wiki/hReview.
Similar Work
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.
- Tantek: I release all my contributions to this specification into the public domain and I encourage the other authors to do so as well.
- When all authors/editors have done so, we can remove the MicroFormatCopyrightStatement template reference and replace it with the MicroFormatPublicDomainContributionStatement.
Patents
This specification is subject to a royalty free patent policy, e.g. per the W3C Patent Policy, and IETF RFC3667 & RFC3668.
Work in progress
This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added.
Changes from v0.3
The following changes have been made in hReview v0.3 over hReview v0.2:
Normative changes:
- Add normative references to
- value-class-pattern - required for support.
- html5 - for HTML5 parsing/DOM
- Changed normative references to informative:
- Includes delegated fully to include-pattern rather than specifying "Object Includes"
- version property dropped. Little if any actual publication in practice, and no practical uses found. Smaller is better.
- dtreviewed may also be an absolute ISO8601 date, and must use value-class-pattern if necessary.
Informative changes (several, but in particular):
- changed editorship/authorship to just Tantek in prep/heads-up for a rewrite.
- examples updated:
- dtreviewed property values use date-pattern
- version property dropped
Articles
This section is informative.
See: hreview-articles.
Related Pages
- hreview
- hReview-aggregate - microformat for specifying summary information from a collection of reviews about a product or service
- hReview creator (feedback) - create your own hReview.
- hReview authoring - learn how to add hReview mark-up to your existing contact info.
- hReview brainstorming - thoughts for improving hReview.
- hReview cheatsheet - hCard properties.
- hReview examples in the wild - an on-going list of websites which use hReview.
- hReview FAQ - If you have any questions about hReview, check here, and if you don't find answers, add your questions!
- hReview feedback - Feedback is encouraged!
- hReview implementations - websites or tools which either generate or parse hReviews.
- hReview issues - Please add any issues with the specification to the issues page.
- hReview parsing - Normatively details of how to parse hReviews.
- hReview profile - The XMDP profile for hReview.
- hReview tests - a wiki page with actual embedded hReviews to try parsing.
- hReview advocacy - encourage others to use hReview.
- review-examples
- review-formats
- review-brainstorming - where we brainstormed about review formats before coming up with hReview.
- currency - proposal for marking up amounts of money (e.g. prices of reviewed items).
- Aggregate reviews - examples - formats - brainstorming
Translations
Read the hReview draft specification in additional languages: