h-review: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(time element allows space instead of T separator between date and time. Undo revision 56859 by GlennJones (Talk))
(Note convergence to h-entry with a couple of properties seen in the wild, add Aaron to examples section, and mention his great piece on keeping backwards compatibility.)
(13 intermediate revisions by 6 users not shown)
Line 2: Line 2:
<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
----
----
<dfn style="font-style:normal;font-weight:bold">h-review</dfn> is a simple, open format for publishing reviews on the web. h-review is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML/HTML5 on the web.
<dfn style="font-style:normal;font-weight:bold">h-review</dfn> is a simple, open format for publishing reviews on the web. h-review is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.


h-review is the [[microformats2]] update to [[hReview]].
h-review is the [[microformats2]] update to [[hReview]].
{{cc0-owfa-license}}


== Example ==
== Example ==
Line 19: Line 21:
   <p>
   <p>
     <data class="p-rating" value="5">★★★★★</data>
     <data class="p-rating" value="5">★★★★★</data>
     Published <time class="dt-reviewed" datetime="2013-06-12 12:00:00">12<sup>th</sup> June 2013</time>
     Published <time class="dt-published" datetime="2013-06-12 12:00:00">12<sup>th</sup> June 2013</time>
     by <a class="p-reviewer h-card" href="http://example.com">Joe Bloggs</a>.
     by <a class="p-author h-card" href="http://example.com">Joe Bloggs</a>.
   </p>
   </p>
    
    
   <div class="e-description">
   <div class="e-content">
     <p>Yes, microformats are undoubtedly great. They are the simplest way to markup structured data in HTML and reap the benefits thereof, including using your web page as your API by automatic conversion to JSON. The alternatives of microdata/schema and RDFa are much more work, require more markup, and are more complicated (harder to get right, more likely to break).</p>
     <p>Yes, microformats are undoubtedly great. They are the simplest way to markup structured data in HTML and reap the benefits thereof, including using your web page as your API by automatic conversion to JSON. The alternatives of microdata/schema and RDFa are much more work, require more markup, and are more complicated (harder to get right, more likely to break).</p>
   </div>
   </div>
</div>
</div>
</source>
Parsed JSON:
<source lang=javascript>
{
  "items": [
    {
      "type": [
        "h-review"
      ],
      "properties": {
        "name": [
          "Microformats: is structured data worth it?"
        ],
        "item": [
          {
            "value": "Microformats",
            "type": [
              "h-item"
            ],
            "properties": {
              "name": [
                "Microformats"
              ],
              "url": [
                "http://microformats.org"
              ]
            }
          }
        ],
        "rating": [
          "5"
        ],
        "published": [
          "2013-06-12 12:00:00"
        ],
        "author": [
          {
            "value": "Joe Bloggs",
            "type": [
              "h-card"
            ],
            "properties": {
              "name": [
                "Joe Bloggs"
              ],
              "url": [
                "http://example.com"
              ]
            }
          }
        ],
        "content": [
          {
            "value": "Yes, microformats are undoubtedly great. They are the simplest way to markup structured data in HTML and reap the benefits thereof, including using your web page as your API by automatic conversion to JSON. The alternatives of microdata/schema and RDFa are much more work, require more markup, and are more complicated (harder to get right, more likely to break).",
            "html": "<p>Yes, microformats are undoubtedly great. They are the simplest way to markup structured data in HTML and reap the benefits thereof, including using your web page as your API by automatic conversion to JSON. The alternatives of microdata/schema and RDFa are much more work, require more markup, and are more complicated (harder to get right, more likely to break).</p>"
          }
        ]
      }
    }
  ]
}
</source>
</source>


Line 32: Line 96:
The class '''<code>h-review</code>''' is a ''root class name'' that indicates the presence of an h-review.
The class '''<code>h-review</code>''' is a ''root class name'' that indicates the presence of an h-review.


'''p-name''', '''p-item''', '''p-rating''', '''dt-reviewed''', '''p-reviewer''', '''e-description''' and the other property class names listed below defined elements as ''properties'' of the h-review.
'''p-name''', '''p-item''', '''p-rating''', '''dt-published''', '''p-author''', '''e-content''' and the other property class names listed below defined elements as ''properties'' of the h-review.


The class '''<code>h-item</code>''' is a ''root class name'' that indicates an embedded '''[[h-item]]''' for the p-item property.
The class '''<code>h-item</code>''' is a ''root class name'' that indicates an embedded '''[[h-item]]''' for the p-item property.


The class '''<code>h-card</code>''' is a ''root class name'' that indicates an embedded '''[[h-card]]''' for the p-reviewer property.
The class '''<code>h-card</code>''' is a ''root class name'' that indicates an embedded '''[[h-card]]''' for the p-author property.


See [[microformats2-parsing]] to learn more about property class names.
See [[microformats2-parsing]] to learn more about property class names.
Line 45: Line 109:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed, including embedded microformat for e.g. business or person ([[h-card]]), event ([[h-event]]), place ([[h-adr]] or [[h-geo]]), product ([[h-product]]), website, url, or other item ([[h-item]]).
* '''<code>p-item</code>''' - thing been reviewed, including embedded microformat for e.g. business or person ([[h-card]]), event ([[h-event]]), place ([[h-adr]] or [[h-geo]]), product ([[h-product]]), website, url, or other item ([[h-item]]).
* '''<code>p-reviewer</code>''' - person who authored the review, optionally with an embedded [[h-card]]
* '''<code>p-author</code>''' - person who authored the review, optionally with an embedded [[h-card]]
* '''<code>dt-reviewed</code>''' - date time of when the review was written
* '''<code>dt-published</code>''' - date time of when the review was written and published
* '''<code>p-rating</code>''' - value from 1-5 indicating a rating for the item (5 best).
* '''<code>p-rating</code>''' - value from 1-5 indicating a rating for the item (5 best).
* '''<code>p-best</code>'''  - define best rating value. can be numerically lower than worst.
* '''<code>p-best</code>'''  - define best rating value. can be numerically lower than worst.
* '''<code>p-worst</code>'''  - define worst rating value. can be numerically higher than best.  
* '''<code>p-worst</code>'''  - define worst rating value. can be numerically higher than best.  
* '''<code>e-description</code>''' - the full text written evaluation and opinion of the reviewer
* '''<code>e-content</code>''' - the full text written evaluation and opinion of the reviewer
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer  
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer  
* '''<code>u-url</code>''' - review permalink URL
* '''<code>u-url</code>''' - review permalink URL


All properties are optional.
All properties are optional.
Experimental properties currently in use in the wild but not (yet) part of the official h-review spec. Several of these seem to be because of h-review convergence towards [[h-entry]], as h-review gets used alongside h-entry within [[h-feed]]:
* '''<code>p-location</code>''' - location the review was posted from, optionally embed [[h-card]], [[h-adr]], or [[h-geo]]
* '''<code>p-summary</code>''' - short review summary
* '''<code>u-syndication</code>''' - URL(s) of syndicated copies of this review. The property equivalent of [[rel-syndication]] ([https://aaronparecki.com/2018/01/29/10/ example] with [https://www.amazon.com/review/R1P2C3ATN75836/ref=pe_1098610_137716200_cm_rv_eml_rv0_rv syndication to Amazon])


== Status ==
== Status ==
'''h-review''' is a microformats.org draft specification. Public discussion on h-review takes place on [[h-review-feedback]], the #microformats [[irc]] channel on irc.freenode.net, and [http://microformats.org/discuss/mail/microformats-new/ microformats-new mailing list].
'''h-review''' is a microformats.org draft specification. Public discussion on h-review takes place on [[h-review-feedback]] and the #microformats [[irc]] channel on irc.freenode.net.


h-review is ready to use and implemented in the wild.
h-review is ready to use.


== Property Details ==
== Property Details ==
Line 66: Line 136:
== Examples in the Wild ==
== Examples in the Wild ==
* … add any h-review examples you find in the wild
* … add any h-review examples you find in the wild
* https://cleverdevil.io/2015/blood-rites-book-six-of-the-dresden-files
* https://aaronparecki.com/2018/01/29/10/ (more on Aaron’s [https://aaronparecki.com/reviews review feed])


== Implementations ==
* [https://github.com/cleverdevil/Known-Reviews Reviews plugin for Known CMS] by [https://cleverdevil.io Jonathan LaCour].
** [https://github.com/cleverdevil/Known-Reviews/pull/4 pending pull request to sync with spec update 2016-05-29] -t


== Validating ==
{{h-spec-section-validating}}
{{h-spec-section-validating}}


 
== Backward Compatibility ==
== Backward Compatiblity ==
=== Publisher Compatibility ===
=== Publisher Compatibility ===
For backward compatibility, you may wish to use classic [[hReview]] classnames in addition to the more future-proof h-review properties, for example:
For backward compatibility, you may wish to use classic [[hReview]] classnames on an h-review permalink page in addition to the more future-proof h-review properties, for example:


<source lang=html4strict>
<source lang=html4strict>
Line 80: Line 155:
</div>
</div>
</source>
</source>
See [https://aaronparecki.com/ Aaron Parecki]’s [https://aaronparecki.com/2016/12/17/8/owning-my-reviews Why Microformats? Owning My Reviews] for a reason to be backwards compatible.


=== Parser Compatibility ===
=== Parser Compatibility ===
Line 92: Line 169:
* <code>photo</code> - parse as '''u-photo''' of the item being reviewed (p-item h-item u-photo)
* <code>photo</code> - parse as '''u-photo''' of the item being reviewed (p-item h-item u-photo)
* <code>url</code> - parse as '''u-url''' of the item being reviewed (p-item h-item u-url)
* <code>url</code> - parse as '''u-url''' of the item being reviewed (p-item h-item u-url)
* <code>reviewer</code>  - including compat root vcard in the absence of h-card
* <code>item</code> (without vcard, vevent, hproduct) - parse as '''p-item h-item''' including backcompat nested properties:
* <code>dtreviewed</code> - parse as '''dt-'''
** <code>fn</code> - parse as '''p-name''' of the item being reviewed (p-item h-item p-name)
** <code>photo</code> - parse as '''u-photo''' of the item being reviewed (p-item h-item u-photo)
** <code>url</code> - parse as '''u-url''' of the item being reviewed (p-item h-item u-url)
* <code>item vcard</code> - parse as '''p-item h-card''' including backcompat [[hCard]] parsing
* <code>item vevent</code> - parse as '''p-item h-event''' including backcompat [[hCalendar]] vevent property parsing
* <code>item hproduct</code> - parse as '''p-item h-product''' including backcompat [[hProduct]] parsing
* <code>reviewer</code>  - parse as '''p-author''', including compat root vcard in the absence of h-card
* <code>dtreviewed</code> - parse as '''dt-published'''
* <code>rating</code>
* <code>rating</code>
* <code>best</code>
* <code>best</code>
* <code>worst</code>
* <code>worst</code>
* <code>description</code> - parse as '''e-'''
* <code>description</code> - parse as '''e-content'''
* <code>rel=tag</code> - parse as '''p-category'''
* <code>rel=tag</code> - parse as '''<code>p-category</code>'''. While not a class name nor typical microformats property, [[rel-tag|rel=tag]] was the typical way to tag an hreview. Thus parsers should look for rel=tag hyperlinks inside an hreview, and take the last path segment of their "href" value as a value for a '''<code>p-category</code>''' property.
* <code>rel="self bookmark"</code> - parse as '''u-url'''. note that <code>rel</code> attribute value is treated as a space separated set, thus any presence of "self" and "bookmark" within such a set in a rel value is accepted.
* <code>rel="self bookmark"</code> - parse as '''u-url'''. note that <code>rel</code> attribute value is treated as a space separated set, thus any presence of "self" and "bookmark" within such a set in a rel value is accepted.


Note: The [[hReview]] format has three properties which make use of <code>rel</code> attribute, these are <code>tag</code>, permalink (via the <code>self</code> and <code>bookmark</code> values) and <code>license</code>. Microformats 2 parsers {{should}} map these URLs into the page scoped rel collection.
Note: The [[hReview]] format has three properties which make use of <code>rel</code> attribute, these are <code>tag</code>, permalink (via the <code>self</code> and <code>bookmark</code> values) and <code>license</code>. Microformats 2 parsers {{should}} map these URLs into the page scoped rel collection.
=== prior property names ===
There may be a handful of h-reviews out there (only one known so far) that use prior h-review property names. Parsers encountering these *may* interpret them as follows:
* <code>dt-reviewed</code> treat as a fallback for '''<code>dt-published</code>'''
* <code>e-description</code> treat as a fallback for '''<code>e-content</code>'''
* <code>p-reviewer</code> treat as a fallback for '''<code>p-author</code>'''


== Background ==
== Background ==

Revision as of 08:44, 24 April 2018

<entry-title>h-review</entry-title> Tantek Çelik (Editor)


h-review is a simple, open format for publishing reviews on the web. h-review is one of several open microformat draft standards suitable for embedding data in HTML.

h-review is the microformats2 update to hReview.

Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2024-03-28, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.

Example

Here is a simple review example:

<div class="h-review">
  <h1 class="p-name">Microformats: is structured data worth it?</h1>
  
  <blockquote>
    <a class="p-item h-item" href="http://microformats.org">Microformats</a> are the simplest way to publish structured data on the web.
  </blockquote>
  
  <p>
    <data class="p-rating" value="5">★★★★★</data>
    Published <time class="dt-published" datetime="2013-06-12 12:00:00">12<sup>th</sup> June 2013</time>
    by <a class="p-author h-card" href="http://example.com">Joe Bloggs</a>.
  </p>
  
  <div class="e-content">
    <p>Yes, microformats are undoubtedly great. They are the simplest way to markup structured data in HTML and reap the benefits thereof, including using your web page as your API by automatic conversion to JSON. The alternatives of microdata/schema and RDFa are much more work, require more markup, and are more complicated (harder to get right, more likely to break).</p>
  </div>
</div>

Parsed JSON:

{
  "items": [
    {
      "type": [
        "h-review"
      ],
      "properties": {
        "name": [
          "Microformats: is structured data worth it?"
        ],
        "item": [
          {
            "value": "Microformats",
            "type": [
              "h-item"
            ],
            "properties": {
              "name": [
                "Microformats"
              ],
              "url": [
                "http://microformats.org"
              ]
            }
          }
        ],
        "rating": [
          "5"
        ],
        "published": [
          "2013-06-12 12:00:00"
        ],
        "author": [
          {
            "value": "Joe Bloggs",
            "type": [
              "h-card"
            ],
            "properties": {
              "name": [
                "Joe Bloggs"
              ],
              "url": [
                "http://example.com"
              ]
            }
          }
        ],
        "content": [
          {
            "value": "Yes, microformats are undoubtedly great. They are the simplest way to markup structured data in HTML and reap the benefits thereof, including using your web page as your API by automatic conversion to JSON. The alternatives of microdata/schema and RDFa are much more work, require more markup, and are more complicated (harder to get right, more likely to break).",
            "html": "<p>Yes, microformats are undoubtedly great. They are the simplest way to markup structured data in HTML and reap the benefits thereof, including using your web page as your API by automatic conversion to JSON. The alternatives of microdata/schema and RDFa are much more work, require more markup, and are more complicated (harder to get right, more likely to break).</p>"
          }
        ]
      }
    }
  ]
}

Get started

The class h-review is a root class name that indicates the presence of an h-review.

p-name, p-item, p-rating, dt-published, p-author, e-content and the other property class names listed below defined elements as properties of the h-review.

The class h-item is a root class name that indicates an embedded h-item for the p-item property.

The class h-card is a root class name that indicates an embedded h-card for the p-author property.

See microformats2-parsing to learn more about property class names.

Properties

h-review properties, inside an element with class h-review:

  • p-name - name of the review
  • p-item - thing been reviewed, including embedded microformat for e.g. business or person (h-card), event (h-event), place (h-adr or h-geo), product (h-product), website, url, or other item (h-item).
  • p-author - person who authored the review, optionally with an embedded h-card
  • dt-published - date time of when the review was written and published
  • p-rating - value from 1-5 indicating a rating for the item (5 best).
  • p-best - define best rating value. can be numerically lower than worst.
  • p-worst - define worst rating value. can be numerically higher than best.
  • e-content - the full text written evaluation and opinion of the reviewer
  • p-category - freeform categories or tags applied to the item by the reviewer
  • u-url - review permalink URL

All properties are optional.

Experimental properties currently in use in the wild but not (yet) part of the official h-review spec. Several of these seem to be because of h-review convergence towards h-entry, as h-review gets used alongside h-entry within h-feed:

Status

h-review is a microformats.org draft specification. Public discussion on h-review takes place on h-review-feedback and the #microformats irc channel on irc.freenode.net.

h-review is ready to use.

Property Details

(stub, add any property explanations here)

Examples in the Wild

Implementations

Validating

Main article: validators

Test and validate microformats2 markup in general with:

Backward Compatibility

Publisher Compatibility

For backward compatibility, you may wish to use classic hReview classnames on an h-review permalink page in addition to the more future-proof h-review properties, for example:

<div class="h-review hreview">
  <h1 class="p-name fn">My great review</h1>
</div>

See Aaron Parecki’s Why Microformats? Owning My Reviews for a reason to be backwards compatible.

Parser Compatibility

Microformats parsers should detect classic properties and parse them as microformats 2 properties. If an "h-review" is found, don't look for an "hReview" on the same element.

Compatibility root class name: hreview

Properties: (parsed as p- plain text unless otherwise specified)

  • summary parse as p-name
  • fn - parse as p-name of the item being reviewed (p-item h-item p-name)
  • photo - parse as u-photo of the item being reviewed (p-item h-item u-photo)
  • url - parse as u-url of the item being reviewed (p-item h-item u-url)
  • item (without vcard, vevent, hproduct) - parse as p-item h-item including backcompat nested properties:
    • fn - parse as p-name of the item being reviewed (p-item h-item p-name)
    • photo - parse as u-photo of the item being reviewed (p-item h-item u-photo)
    • url - parse as u-url of the item being reviewed (p-item h-item u-url)
  • item vcard - parse as p-item h-card including backcompat hCard parsing
  • item vevent - parse as p-item h-event including backcompat hCalendar vevent property parsing
  • item hproduct - parse as p-item h-product including backcompat hProduct parsing
  • reviewer - parse as p-author, including compat root vcard in the absence of h-card
  • dtreviewed - parse as dt-published
  • rating
  • best
  • worst
  • description - parse as e-content
  • rel=tag - parse as p-category. While not a class name nor typical microformats property, rel=tag was the typical way to tag an hreview. Thus parsers should look for rel=tag hyperlinks inside an hreview, and take the last path segment of their "href" value as a value for a p-category property.
  • rel="self bookmark" - parse as u-url. note that rel attribute value is treated as a space separated set, thus any presence of "self" and "bookmark" within such a set in a rel value is accepted.

Note: The hReview format has three properties which make use of rel attribute, these are tag, permalink (via the self and bookmark values) and license. Microformats 2 parsers SHOULD map these URLs into the page scoped rel collection.

prior property names

There may be a handful of h-reviews out there (only one known so far) that use prior h-review property names. Parsers encountering these *may* interpret them as follows:

  • dt-reviewed treat as a fallback for dt-published
  • e-description treat as a fallback for e-content
  • p-reviewer treat as a fallback for p-author

Background

h-review is based on the existing hReview specification.

See Also