Microformats Wiki - User contributions [en]

h-event

2026-02-24T00:57:44Z

GRegorLove: /* Examples in the wild */ IA link for 68 middle St example

{{DISPLAYTITLE:h-event}}
<dfn style="font-style:normal;font-weight:bold">h-event</dfn> is a simple, open format for events on the web. h-event is often used with both event listings and individual event pages. h-event is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.

h-event is the [[microformats2]] update to [[hCalendar]].

;<span id="status">Status</span>
:This is a '''Living Specification''' yet mature enough to encourage additional implementations and [https://github.com/microformats/h-event/issues feedback].
;<span id="participate">Participate</span>
:[https://github.com/microformats/h-event/issues Open Issues]
:[[IRC]]
:Advance the spec by contributing to a consensus in [https://github.com/microformats/h-event/issues/1 issue: adopt same change control as h-entry]
<div class="p-author h-card vcard">
;<span class="p-role role">Editor</span>
:<span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span>
</div>
;License
: {{cc0-owfa-license}}
<span style="float:right">__TOC__</span>

== Example ==
Here is a simple event example:

<syntaxhighlight lang="html">
<div class="h-event">
<h1 class="p-name">Microformats Meetup</h1>
<p>From
<time class="dt-start" datetime="2013-06-30 12:00">30<sup>th</sup> June 2013, 12:00</time>
to <time class="dt-end" datetime="2013-06-30 18:00">18:00</time>
at <span class="p-location">Some bar in SF</span></p>
<p class="p-summary">Get together and discuss all things microformats-related.</p>
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [
{
"type": [
"h-event"
],
"properties": {
"name": [
"Microformats Meetup"
],
"start": [
"2013-06-30 12:00:00"
],
"end": [
"2013-06-30 18:00:00"
],
"location": [
"Some bar in SF"
],
"summary": [
"Get together and discuss all things microformats-related."
]
}
}
]
}
</syntaxhighlight>

=== Get started ===
The class '''<code>h-event</code>''' is a ''root class name'' that indicates the presence of an h-event.

'''p-name''', '''dt-start''', '''dt-end''', '''p-location''', '''p-summary''', and the other h-event property class names listed below define ''properties'' of the h-event.

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

== Properties ==
h-event properties, inside an element with class '''h-event''':
* '''<code>p-name</code>''' - event name (or title)
* '''<code>p-summary</code>''' - short summary of the event
* '''<code>dt-start</code>''' - datetime the event starts
* '''<code>dt-end</code>''' - datetime the event ends
* '''<code>dt-duration</code>''' - duration of the event
* '''<code>p-description</code>''' - more detailed description of the event
** '''WARNING:''' Proposed to be replaced by '''<code>e-content</code>''' (re-used from [[h-entry]])
** See and follow-up: https://github.com/microformats/h-event/issues/3
* '''<code>u-url</code>''' - permalink for the event
* '''<code>p-category</code>''' - event category(ies)/tag(s)
* '''<code>p-location</code>''' - where the event takes place, optionally embedded [[h-card]], [[h-adr]], or [[h-geo]]

All properties are optional.

=== Experimental Properties ===

These properties are currently in use in the wild but not (yet) part of the draft h-event spec:

* '''<code>p-attendee</code>''' - a person attending the event, optionally embed [[h-card]]
<div class="discussion">
* This draft has not been updated in almost 2 years. During this period, <code>h-entry</code> <code>p-rsvp</code> has been standardised, thus making it robust and mature enough for the addition. I guess it's about time to unlabel <code>p-attendee</code> as experimental.
** I've filed https://github.com/microformats/h-event/issues/2 to track advancing this draft as a whole. Let's do that with the existing draft before discussing p-attendee in particular. And rather than guessing, take a look at the vocabulary maturity levels in h-entry and perhaps help evaluate (in another issue) p-attendee according to those criteria. [[User:Tantek|Tantek]] 01:10, 28 February 2017 (UTC)
* I would also suggest to extend expected value to [[h-entry]], so that, while the personal info can be preserved, the attendee can also support p-rsvp property of h-entry.
** I don't understand this. p-attendee is supposed to represent a person, e.g. an [[h-card]]. How would it having that be an [[h-entry]] make sense and work (from a publishing and consuming code perspective)? This proposed extension to p-attendee may be worth its own issue as well. [[User:Tantek|Tantek]] 01:10, 28 February 2017 (UTC)
</div>
* '''<code>p-organizer</code>''' - a person organizing an event, optionally embedded [[h-card]]. Used in Indieweb events, but not consumed. https://github.com/microformats/h-event/issues/10
* '''<code>u-rsvp</code>''' - similar to the proposed u-comment on h-entry, this would be the proposed property to mark up displayed RSVPs on an h-event. https://github.com/microformats/h-event/issues/9

== Status ==
'''h-event''' is a microformats.org draft specification. Public discussion on h-event takes place on the [[irc|#microformats channel on irc.freenode.net]] ([https://chat.indieweb.org/microformats view recent discussions]), and specific issues [https://github.com/microformats/h-event/issues may be filed on GitHub].

h-event is ready to use and implemented in the wild. For backwards compatibility you should also mark up top-level h-events as classic [[hCalendar]] events.

== Property Details ==
(stub, to be expanded)

=== p-location ===
<code>p-location</code> is typically a physical address, optionally marked up with [[h-adr]], for example:

<syntaxhighlight lang="html">
<p class="p-location h-adr">
<span class="p-street-address">17 Austerstræti</span>
<span class="p-locality">Reykjavík</span>
<span class="p-country-name">Iceland</span>
</p>
</syntaxhighlight>

=== Reserved Properties ===
Reserved properties:
* '''<code>p-organizer</code>''' - a person (co-)organizing the event, optionally embed [[h-card]] {{main|h-card}}
** proposed as way to [https://github.com/snarfed/bridgy/issues/275 implement copying an event organizer to Eventbrite]

== Examples in the wild ==
Real world in the wild examples:

* ... add uses of h-event you see in the wild here.
* [http://www.w3.org/conf/ W3Conf 2013] uses h-event for the main event, and h-card for all the speakers and notable attendees. The h-cards make particularly good use of implied name, url, and photo properties.
* [http://tantek.com/ Tantek Çelik] uses h-event on his home page
* [http://tantek.com/presentations/2012/06/microformats microformats.org at 7 years] presentation with h-event
* [http://tantek.com/presentations/2012/06/pdf2012-indieweb.html Rise of the Indie Web hCards] (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has [[microformats2]] h-event and h-card markup
* WebMaker by Mozilla has h-event and h-card on event search (e.g. [https://webmaker.org/en-US/events/near/?lat=45.5234515&lng=-122.6762071 search near Portland Oregon]) and event pages (e.g. [https://webmaker.org/en-US/events/192f56eb9/ IndieWebCamp 2012]).[https://twitter.com/microformats/status/212207925643587585]
* [http://indiewebcamp.com IndieWebCamp] has [[microformats2]] h-event markup with embedded h-cards for the organizers and the location.
* [https://wiki.mozilla.org/Events Mozilla Events] page has [[microformats2]] h-event markup with attendees marked up with h-card.
* https://gregorlove.com/events has h-event markup, for example: https://gregorlove.com/2017/06/homebrew-website-club/
** has additional property from [[h-entry]]: <code>dt-published</code>
* https://oauth.net/events/ has a list of h-event marked up events relating to OAuth, both future and past
* [https://web.archive.org/web/20191231175256/http://68middle.st/events 68middle.st/events (archived)] had events marked up in h-event
* [https://www.gov.uk/government/publications/open-standards-for-government/exchange-of-calendar-events gov.uk] mentions that iCalendar can be translated into h-event microformats in their "Exchange of calendar events" guidance.
<blockquote>You can map events to and from iCalendar from other formats, such as h-event.</blockquote>

See [[microformats2#Examples_in_the_wild|microformats2 examples in the wild]] for more

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

== Implementations ==
Software implementations that publish or consume h-event, including themes, plugins, or extensions:

When adding an implementation, please provide and link to its home page and open source repo if any.

* [https://github.com/gRegorLove/mf2-to-iCalendar mf2 to iCalendar]: Convert microformats h-event to iCalendar. Example: https://gregorlove.com/calendar/

== Backward Compatibility ==
=== Publisher Compatibility ===
For backward compatibility, you may wish to use classic [[hCalendar]] classnames in addition to the more future-proof h-event properties, for example:

<syntaxhighlight lang="html">
<div class="h-event vevent">
<h1 class="p-name summary">Some great event</h1>
</div>
</div>
</syntaxhighlight>

=== Parser Compatibility ===
Microformats parsers {{should}} detect classic properties only if a classic root class name is found and parse them as microformats2 properties.

If an "h-event" is found, don't look for a "vevent" on the same element.

Compat root class name: <code id="vevent">vevent</code><br/>
Properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> - parse as '''<code>p-name</code>'''
* <code>dtstart</code> - parse as '''<code>dt-start</code>'''
* <code>dtend</code> - parse as '''<code>dt-end</code>'''
* <code>duration</code> - parse as '''<code>dt-duration</code>'''
* <code>description</code>
* <code>url</code> - parse as '''u-'''
* <code>category</code>
* <code>location</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>, and compat root <code>adr</code> in the absence of <code>h-adr</code>
* <code>geo</code> - parse as '''<code>p-location h-geo</code>''' including compat root <code>geo</code>

=== iCalendar Compatibility ===
hCalendar-specific implementations that perform custom display or translation to iCalendar .ics {{should}} prefer <code>p-name</code> over <code>p-summary</code>, and use <code>p-summary</code> value(s) as a fallback if there is no <code>p-name</code>.

== Background ==
This work is based on the existing [[hCalendar]] and [[iCalendar]] specifications.

== Design Principles ==
(stub, expand)

== See Also ==
* [[h-calendar-to-do]]
* [[h-event-brainstorming]]
* [[microformats2]]
* [[microformats2-parsing]]
* [[h-adr]]
* [[h-geo]]
* [[h-card]]
* [[hCalendar]]
* [[h-entry]]s can be RSVPs to events, using the p-rsvp property

[[Category:Draft Specifications]]

representative-h-card

2025-11-17T00:58:26Z

GRegorLove: +How section

{{stub}}

This page is for keeping track of the representative h-card effort, which is the [[microformats2]] update to [[representative-hcard]].

== How ==
* How to publish: [[representative-h-card-authoring]]
* How to find/discover and parse: [[representative-h-card-parsing]]

== See Also ==
* [[representative-h-card]]
* [[representative-h-card-authoring]]
* [[representative-h-card-parsing]]
* [[representative-h-card-examples]]
* [[representative-h-card-formats]]
* [[representative-h-card-brainstorming]]
* [[representative-h-card-issues]]
* [[h-card]]
* [[h-card-authoring]]
* [[xfn]]
* [[rel-me]]

h-review

2025-11-07T21:25:29Z

GRegorLove: /* Examples in the Wild */ +https://indieweb.org/review#IndieWeb_Examples

{{warning|Note proposal to [https://github.com/microformats/h-entry/issues/32 merge h-review properties into h-entry]. If the points in that issue are addressed and we get [[h-entry]] change control approval for adding <code>u-review-of</code>, then we’ll likely merge accordingly and redirect this page accordingly}}
<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]].

;<span id="Status">Status</span>
:This is a '''Draft Specification'''
;Participate
:[[IRC]]: [irc://irc.libera.chat/microformats #microformats on Libera]
;Editor
:<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
;License
:{{cc0-owfa-license}}
__TOC__

== Example ==
Here is a simple review example:

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="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>"
}
]
}
}
]
}
</syntaxhighlight>

=== Get started ===
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-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-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.

== Properties ==
h-review properties, inside an element with class '''h-review''':

* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing being reviewed, including embedded microformat for e.g. business or person ([[h-card]]), event ([[h-event]]), place ([[h-adr]] or [[h-geo]]), product ([[h-product]]), recipe ([[h-recipe]]), website, url, or other item ([[h-item]]).
* '''<code>p-author</code>''' - person who authored the review, optionally with an embedded [[h-card]]
* '''<code>dt-published</code>''' - date time of when the review was written and published
* '''<code>p-rating</code>''' - value from 0-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-worst</code>''' - define worst rating value. can be numerically higher than best.
* '''<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>u-url</code>''' - 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]]:

* '''<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 ==
'''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 ==
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])
* https://khleedril.org/dale-mellor/bookblog; a book blog with two-way syndication of reviews.
* More examples on https://indieweb.org/review#IndieWeb_Examples

== Implementations ==
* [https://github.com/cleverdevil/Known-Reviews Reviews plugin for Known CMS] by [https://cleverdevil.io Jonathan LaCour].

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

== 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:

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

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 ===
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)

* <code>summary</code> parse as '''<code>p-name</code>'''
* <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</code> (without vcard, vevent, hproduct) - parse as '''p-item h-item''' including backcompat nested properties:
** <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>best</code>
* <code>worst</code>
* <code>description</code> - parse as '''e-content'''
* <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.

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 ==
h-review is based on the existing [[hReview]] specification.

== See Also ==
* [[microformats2]]
* [[h-card]]
* [[h-event]]
* [[h-adr]]
* [[h-geo]]
* [[h-product]] can all be embedded in h-review as the p-item
* [[h-item]] is a minimal microformat in case none of the others suitably represent the item being reviewed

[[Category:Draft Specifications]]

microformats2

2025-11-07T20:42:48Z

GRegorLove: /* h-review */ sync with /h-review spec: p-author, dt-published, e-content

<span style="float:right">__TOC__</span>
Welcome to the microformats2 home page.

== Summary ==
Microformats2 is the latest version of microformats, the simplest way to markup structured information in HTML. Microformats2 improves ease of use and implementation for <em>both</em> authors (publishers) and developers ([[microformats2-parsing|parser]] implementers).

Microformats2 replaces and supersedes both classic microformats (sometimes called microformats1), as well as incorporates lessons learned from [[microdata]] and [[RDFa]].

=== simple microformats2 examples ===
Here are a few <span id="simple_microformats_2_examples">simple microformats2 examples</span> along with canonical [[JSON]].

==== person example ====
* Simple person reference:
<syntaxhighlight lang="html">
<span class="h-card">Frances Berriman</span>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Frances Berriman"]
}
}]
}
</syntaxhighlight>

----

==== hyperlinked person ====
* Simple hyperlinked person reference
<syntaxhighlight lang="html">
<a class="h-card" href="http://benward.me">Ben Ward</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Ben Ward"],
"url": ["http://benward.me"]
}
}]
}
</syntaxhighlight>

----

==== hyperlinked person image ====
* Simple hyperlinked person image
<syntaxhighlight lang="html">
<a class="h-card" href="http://rohit.khare.org/">
<img alt="Rohit Khare"
src="https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg" />
</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Rohit Khare"],
"url": ["http://rohit.khare.org/"],
"photo": ["https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg"]
}
}]
}
</syntaxhighlight>

Additional simple cases details in [[microformats-2-implied-properties]].

----

==== detailed person example ====
* More detailed person
<syntaxhighlight lang="html">
<div class="h-card">
<img class="u-photo" alt="photo of Mitchell"
src="https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"/>
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="u-url"
href="https://twitter.com/MitchellBaker"
>@MitchellBaker</a>)
<span class="p-org">Mozilla Foundation</span>
<p class="p-note">
Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities.
</p>
<span class="p-category">Strategy</span>
<span class="p-category">Leadership</span>
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"photo": ["https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"],
"name": ["Mitchell Baker"],
"url": [
"http://blog.lizardwrangler.com/",
"https://twitter.com/MitchellBaker"
],
"org": ["Mozilla Foundation"],
"note": ["Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities."],
"category": [
"Strategy",
"Leadership"
]
}
}]
}
</syntaxhighlight>

----
=== details from examples ===
Details demonstrated by the examples:
# The JSON <code>"type"</code> uses the full microformat root class name (e.g. <code>"h-card"</code>) for consistent identification.
# all properties are optional and syntactically plural with parsed values provided in document order; particular microformats (and applications there-of) may apply specific/singular semantics to first value of a property.

=== microformats2 design ===

microformats2 has the following key design aspects:

; Prefixes for class names
: All microformats class names use prefixes. Prefixes are '''syntax independent from vocabularies''', which are developed separately.
* <code>h-*</code> for root class names (e.g. <code>h-card</code>)
* <code>p-*</code> for plain text properties (e.g. <code>p-name</code>)
* <code>u-*</code> for URL properties (e.g. <code>u-photo</code>)
* <code>dt-*</code> for date/time properties (e.g. <code>dt-bday</code>)
* <code>e-*</code> for embedded markup properties (e.g. <code>e-note</code>)<br />

See [[microformats2-prefixes]] for more details.

; Flat sets of optional properties
: All microformats consist of a root, and a collection of properties. Hierarchical data is represented with nested microformats, typically as property values themselves. Properties are all optional and potentially multivalued (applications needing a singular semantic may use first instance).

; Single class markup for common uses
: Common simple markup patterns require only a single microformat root class name, which parsers use to find a few generic properties: <code>name</code>, <code>url</code>, <code>photo</code>. The simple microformats2 examples above demonstrate these.

----

Parsing each prefix (including generating canonical JSON) is detailed step-by-step in:
* The '''[[microformats2-parsing|microformats2 parsing specification]]'''

'''Note:''' Most properties are specified and used with a single specific prefix (or occasionally two or three) that is self-evident from context. However, any parsing prefix can be used with any property, especially if you find a good reason to do so!

== v2 vocabularies ==
Status: '''<span id="draft_v2_vocabularies">draft</span>'''. Please review and provide feedback in [[IRC]].
* [[h-adr]]
* [[h-card]]
* [[h-entry]]
* [[h-event]]
* [[h-feed]]
* [[h-geo]]
* [[h-item]]
* [[h-listing]]
* [[h-product]]
* [[h-recipe]]
* [[h-resume]]
* [[h-review]]
* [[h-review-aggregate]]

See below for vocabulary summaries.

=== h-adr ===
{{main|h-adr}}

The '''h-adr''' microformat is for marking up structured locations such as addresses, physical and/or postal. This is an update to [[adr]].

root class name: '''<code>h-adr</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-adr</nowiki>

properties:
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-street-address</code>'''
* '''<code>p-locality</code>'''
* '''<code>p-region</code>'''
* '''<code>p-postal-code</code>'''
* '''<code>p-country-name</code>'''
* '''<code>p-label</code>''' - new in [[vCard4]] ([[RFC6350]])
* '''<code>p-geo</code>''' (or '''<code>u-geo</code>''' with a RFC 5870 geo: URL) - new in [[vCard4]] ([[RFC6350]])
* '''<code>p-latitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-longitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-adr" is found, don't look for an "adr" on the same element.

compat root class name: <code id="adr">adr</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>post-office-box</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>

=== h-card ===
{{main|h-card}}

The '''h-card''' microformat is for marking up people and organizations. This is an update to [[hCard]].

root class name: '''<code>h-card</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-card</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>p-honorific-prefix</code>'''
* '''<code>p-given-name</code>'''
* '''<code>p-additional-name</code>'''
* '''<code>p-family-name</code>'''
* '''<code>p-sort-string</code>'''
* '''<code>p-honorific-suffix</code>'''
* '''<code>p-nickname</code>'''
* '''<code>u-email</code>'''
* '''<code>u-logo</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>'''
* '''<code>u-uid</code>'''
* '''<code>p-category</code>'''
* '''<code>p-adr</code>'''
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-street-address</code>'''
* '''<code>p-locality</code>'''
* '''<code>p-region</code>'''
* '''<code>p-postal-code</code>'''
* '''<code>p-country-name</code>'''
* '''<code>p-label</code>'''
* '''<code>p-geo</code>''' or '''<code>u-geo</code>''' with a RFC 5870 geo: URL, new in [[vCard4]] ([[RFC6350]])
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-tel</code>'''
* '''<code>p-note</code>'''
* '''<code>dt-bday</code>'''
* '''<code>u-key</code>'''
* '''<code>p-org</code>'''
* '''<code>p-job-title</code>''' - previously 'title' in hCard, disambiguated.
* '''<code>p-role</code>
* '''<code>u-impp</code>''' per RFC 4770, new in [[vCard4]] ([[RFC6350]])
* '''<code>p-sex</code>''' new in [[vCard4]] ([[RFC6350]])
* '''<code>p-gender-identity</code>''' new in [[vCard4]] ([[RFC6350]])
* '''<code>dt-anniversary</code>''' new in [[vCard4]] ([[RFC6350]])
* ...

Reserved properties: (properties not used much (if at all) in practice)
* '''<code>p-organization-name</code>'''
* '''<code>p-organization-unit</code>'''
* '''<code>p-tz</code>'''
* '''<code>dt-rev</code>'''
* ...

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-card" is found, don't look for a "vcard" on the same element.

compat root class name: <code id="vcard">vcard</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>honorific-prefix</code>
* <code>given-name</code>
* <code>additional-name</code>
* <code>family-name</code>
* <code>honorific-suffix</code>
* <code>nickname</code>
* <code>email</code> - parse as '''u-'''
* <code>logo</code> - parse as '''u-'''
* <code>photo</code> - parse as '''u-'''
* <code>url</code> - parse as '''u-'''
* <code>uid</code> - parse as '''u-'''
* <code>category</code>
* <code>adr</code> - parse as '''<code>p-adr h-adr</code>''' including compat root class <code>adr</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>
* <code>label</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root class <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* <code>tel</code>
* <code>note</code>
* <code>bday</code> - parse as '''dt-'''
* <code>key</code> - parse as '''u-'''
* <code>org</code>
* <code>organization-name</code>
* <code>organization-unit</code>
* <code>title</code> - parse as '''p-job-title'''
* <code>role</code>
* ...

Reserved: (backward compat properties that parsers {{may}} implement, if they do, they {{must}} implement in this way:
* <code>tz</code>
* <code>rev</code> - parse as '''dt-'''
* ...

Note: use of 'value' within 'tel' should be automatically handled by the support of the [[value-class-pattern]]. And for now, the 'type' subproperty of 'tel' is dropped/ignored. If there is demonstrable documented need for additional tel types (e.g. fax), we can introduce new flat properties as needed (e.g. p-tel-fax).

=== h-entry ===
{{main|h-entry}}

The '''h-entry''' microformat is for marking up syndicatable content such as blog posts, notes, articles, comments, photos and similar. This is an update to [[hAtom]].

root class name: '''<code>h-entry</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-entry</nowiki>

properties:
* '''<code>p-name</code>''' (was p-entry-title, see issues)
* '''<code>p-summary</code>''' (was p-entry-summary, see issues)
* '''<code>e-content</code>''' (was e-entry-content, see issues)
* '''<code>dt-published</code>'''
* '''<code>dt-updated</code>'''
* '''<code>p-author</code>'''
* '''<code>p-category</code>'''
* '''<code>u-url</code>'''
* '''<code>u-uid</code>'''
* '''<code>p-geo</code>'''
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''

This is an update to [[hAtom]].

Brainstorming:

The following properties are proposed additions to h-entry above and beyond what hAtom (or Atom) provides, based on various existing link preview markup conventions:
* '''<code>u-photo</code>'''
* '''<code>u-audio</code>''' - consider special u- parsing rules for <code><audio></code>
* '''<code>u-video</code>''' - consider special u- parsing rules for <code><video></code>
* '''<code>u-in-reply-to</code>''' - for links to other posts that this post is a reply to (comment regarding, etc.)

Backward compatibility:

(*)hAtom-specific implementations that perform custom display or translation (e.g. to Atom XML) {{should}} prefer <code>p-name</code> over <code>p-entry-title</code>, and use <code>p-entry-title</code> value(s) as a fallback if there is no <code>p-name</code>.

For hAtom backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-entry" is found, don't look for a "hentry" on the same element.

compat root class name: <code id="hentry">hentry</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>entry-title</code> - parse as '''<code>p-name</code>'''
* <code>entry-summary</code>
* <code>entry-content</code> - parse as '''e-'''
* <code>published</code> - parse as '''dt-'''
* <code>updated</code> - parse as '''dt-'''
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>category</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* ...

<span id="h-entry-faq">FAQ:</span>
<div class="discussion">
* '''What is the <code>p-name</code> of a [http://indiewebcamp.com/note note]?'''
** A few options, from simplest to most detailed.
*** '''same as the p-content/e-content''' property.
*** '''same as the <code>title</code> element''' on the note permalink post page. When publishing a note on its own permalink post page, the contents of the note are likely abbreviated for the title of the page. The same abbreviation can be used for the p-name.
*** '''first sentence of the p-content/e-content''' property. It may be better for [http://indiewebcamp.com/syndication syndication] and [[link-preview]] purposes to provide just the first sentence of the note as the <code>p-name</code>. Similarly if only a portion of the content is syndicated to other sites, that portion can be marked up as the <code>p-summary</code>.
* ...
</div>

Resolved Issues:
* 2012-245 Resolved. See [http://krijnhoetmer.nl/irc-logs/microformats/20120830#l-120 2012-243 IRC discussion/consensus] for:
** Use '''<code>p-summary</code> instead of <code>p-entry-summary</code>'''. The historical semantic of "entry-summary" is not different from "summary" in any significant (or discernible way). Collapsing the two will simplify the overall microformats2 vocabularies further. In microformats2, entry-summary is no more.
** Use '''<code>e-content</code> instead of <code>e-entry-content</code>'''. Same point and advantage. In microformats2, entry-content is no more.
** '''drop <code>p-entry-title</code>'''. Unnecessary and subsumed by "p-name". Would consider move to backward compat only if cases are presented - known publishing uses are expected to be updated shortly.

=== h-event ===
{{main|h-event}}

The '''h-event''' microformat is for marking up events. This is an update to [[hCalendar]].

root class name: '''<code>h-event</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-event</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>p-summary</code>'''(*)
* '''<code>dt-start</code>'''
* '''<code>dt-end</code>'''
* '''<code>dt-duration</code>'''
* '''<code>p-description</code>'''
* '''<code>u-url</code>'''
* '''<code>p-category</code>'''
* '''<code>p-location</code>'''
* '''<code>p-geo</code>'''
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* ...

This is an update to [[hCalendar]].

(*)hCalendar-specific implementations that perform custom display or translation (e.g. to iCalendar .ics) {{should}} prefer <code>p-name</code> over <code>p-summary</code>, and use <code>p-summary</code> value(s) as a fallback if there is no <code>p-name</code>.

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-event" is found, don't look for a "vevent" on the same element.

compat root class name: <code id="vevent">vevent</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> - parse as '''<code>p-name</code>'''
* <code>dtstart</code> - parse as '''<code>dt-start</code>'''
* <code>dtend</code> - parse as '''<code>dt-end</code>'''
* <code>duration</code> - parse as '''<code>dt-duration</code>'''
* <code>description</code>
* <code>url</code> - parse as '''u-'''
* <code>category</code>
* <code>location</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>, and compat root <code>adr</code> in the absence of <code>h-adr</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* ...

=== h-geo ===
{{main|h-geo}}

The '''h-geo''' microformat is for marking up WGS84 geophysical coordinates. This is an update to [[geo]].

root class name: '''<code>h-geo</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-geo</nowiki>

properties:
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-geo" is found, don't look for an "geo" on the same element.

compat root class name: <code id="geo">geo</code>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>latitude</code>
* <code>longitude</code>

=== h-item ===
{{main|h-item}}

The '''h-item''' microformat is for marking up the item of an [[h-review]] or [[h-product]]. This is an update to part of [[hReview]].

root class name: '''<code>h-item</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-item</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>'''

Note: in practice, due to the microformats2 implied property rules, it is expected that most uses of "h-item" won't require any explicit properties at all (since microformats2 parsers will infer name, photo, and url properties from the structure of the element with "h-item" and its contained content/elements if any).

=== h-product ===
{{main|h-product}}

The '''h-product''' microformat is for marking up products. This is an update to [[hProduct]].

root class name: '''<code>h-product</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-product</nowiki>

properties:
* '''<code>p-name</code>''' - name of the product
* '''<code>u-photo</code>''' - photo of the product
* '''<code>p-brand</code>''' - manufacturer, can also be a nested <code>h-card</code>
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>e-description</code>'''
* '''<code>u-url</code>''' - URL of the product
* '''<code>u-identifier</code>''' - includes type (e.g. mpn, upc, isbn, issn, sn, vin, sku etc.) and value.
* '''<code>p-review</code>''' - a review of the product, can also be a nested <code>h-review</code>
* '''<code>p-price</code>''' - retail price of the product

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-product" is found, don't look for an "hproduct" on the same element.

compat root class name: <code id="hproduct">hproduct</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>photo</code> - parse as '''u-'''
* <code>brand</code>
* <code>category</code>
* <code>description</code>
* <code>identifier</code> - parse as '''u-'''
* <code>url</code> - parse as '''u-'''
* <code>review</code> - including compat root class <code>hreview</code> in the absence of <code>h-review</code>
* <code>price</code>

Note: [[hProduct]] has at least one experimental property which has real world adoption due to [[Google]] and [[Bing]] search support of hProduct. Currently this is: '''price'''

=== h-recipe ===
{{main|h-recipe}}

The '''h-recipe''' microformat is for marking up food recipes. This is an update to [[hRecipe]].

root class name: '''<code>h-recipe</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-recipe</nowiki>

properties:
* '''<code>p-name</code>''' - the name of the recipe
* '''<code>p-ingredient</code>''' - describes one or more ingredients used in the recipe.
* '''<code>p-yield</code>''' - Specifies the quantity produced by the recipe, like how many persons it satisfyies
* '''<code>e-instructions</code>''' - the method of the recipe.
* '''<code>dt-duration</code>''' - the time it takes to prepare the meal described by the recipe.
* '''<code>u-photo</code>''' - an accompanying image

Experimental properties with wide adoption
* '''<code>p-summary</code>''' - provides a short summary or introduction
* '''<code>p-author</code>''' - the person who wrote the recipe with <code>h-card</code>
* '''<code>dt-published</code>''' - the date the recipe was published
* '''<code>p-nutrition</code>''' - nutritional information like calories, fat, dietary fiber etc.
* ...

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-recipe" is found, don't look for an "hrecipe" on the same element.

compat root class name: <code id="hrecipe">hrecipe</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>ingredient</code>
* <code>yield</code>
* <code>instructions</code> - parse as '''e-'''
* <code>duration</code> - parse as '''dt-'''
* <code>photo</code> - parse as '''u-'''
* <code>summary</code>
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>nutrition</code>

Note: [[hRecipe]] has a number of experimental properties which have real world adoption due to [[Google]] recipe search support of hRecipe. These are: summary, author, published and nutrition

=== h-resume ===
{{main|h-resume}}

The '''h-resume''' microformat is for marking up resumes. This is an update to [[hResume]].

root class name: '''<code>h-resume</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-resume</nowiki>

properties:
* '''<code>p-summary</code>''' - overview of qualifications and objectives
* '''<code>p-contact</code>''' - current contact info in an <code>h-card</code>
* '''<code>p-education</code>''' - an education <code>h-calendar</code> event, years, nested <code>h-card</code> of the school, location.
* '''<code>p-experience</code>''' - a job or other professional experience <code>h-calendar</code> event, years, nested <code>h-card</code> of the organization, location, job-title.
* '''<code>p-skill</code>''' - a skill or ability, optionally including level and/or duration of experience
* '''<code>p-affiliation</code>''' - an affiliation with an <code>h-card</code> organization

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-resume" is found, don't look for an "hresume" on the same element.

compat root class name: <code id="hresume">hresume</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code>
* <code>contact</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>education</code> - including compat root <code>vevent</code> in the absence of <code>h-event</code>
* <code>experience</code> - including compat root <code>vevent</code> in the absence of <code>h-event</code>
* <code>skill</code>
* <code>affiliation</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>

Note: skill has a [[hresume-skill-brainstorm|proposed expansion into competency]] with explicit summary, rating and/or duration components. Based on existing real world adoption, we should consider an h-competency vocabulary with p-summary, p-rating, and dt-duration properties.

=== h-review ===
{{main|h-review}}

The '''h-review''' microformat is for marking up reviews. This is an update to [[hReview]]. See also [[h-item]].

root class name: '''<code>h-review</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-review</nowiki>

properties:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed i.e. 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-author</code>''' - person who authored the review, optionally with an embedded [[h-card]]
* '''<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-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>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>u-url</code>''' - URL of the review

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review" is found, don't look for an "hreview" on the same element.

compat root class name: <code id="hreview">hreview</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> parse as '''<code>p-name</code>'''
* <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>reviewer</code> - including compat root vcard in the absence of h-card
* <code>dtreviewed</code> - parse as '''dt-'''
* <code>rating</code>
* <code>best</code>
* <code>worst</code>
* <code>description</code> - parse as '''e-'''
* <code>rel="tag"</code> - parse as '''p-category'''
* <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>. Microformats2 parsers {{should}} map these URLs into the page scoped rel collection.

=== h-review-aggregate ===
{{main|h-review-aggregate}}

The '''h-review-aggregate''' microformat is for marking up aggregate reviews of a single item. This is an update to [[hreview-aggregate]]. See also [[h-item]].

root class name: '''<code>h-review-aggregate</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-review-aggregate</nowiki>

properties:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed i.e. 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-rating</code>''' - value from 1-5 indicating average rating for the item (5 best).
* '''<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-count</code>''' - number of reviews aggregated.
* '''<code>p-votes</code>''' - number of reviewers who have rated the product, thus contributing to the average rating.
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>u-url</code>''' - URL of the review

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review-aggregate" is found, don't look for an "hreview-aggregate" on the same element.

compat root class name: <code id="hreview-aggregate">hreview-aggregate</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> parse as '''<code>p-name</code>'''
* <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>rating</code>
* <code>best</code>
* <code>worst</code>
* <code>count</code>
* <code>votes</code>
* <code>rel="tag"</code> - parse as '''p-category'''
* <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.

=== v2 vocab notes ===
Notes:
* All v2 vocabularies are defined as flat lists of properties of an object/item, and thus can be used in microformats-2 syntax as shown, or in microdata items, or RDFa. The microformats-2 property parsing prefixes "p-", "u-", "dt-", "e-" are omitted when using defined properties in microdata itemprop and RDFa property as those syntaxes have their own element-specific parsing rules.
* Profile URLs are provided for use with the HTML4 <code>profile</code> attribute, microdata <code>itemtype</code> attribute, and RDFa <code>vocab</code> & <code>typeof</code> attributes (though the latter requires slicing off the trailing segment of the profile for the typeof attribute, and leaving the rest in vocab).
* microformats2 properties may also be explicitly bound as URIs using [[rel-profile]], the [[html5-profile]] attribute proposal, or an HTML5 'vocab' attribute instead. If URI bound terms are important to you, please express interest on [[rel-profile]], [[html5-profile]], or contribute to an [[html5-vocab]] draft.

=== v2 vocab to-do ===
To do:
* write a simple tutorial for creating/getting started with microformats-2 markup for new content
* examples in each h-* spec listed above of how to embed other microformats in them
* actual profile documents at <nowiki>http://microformats.org/profile/h-*</nowiki> URLs mentioned above.
* Provide any necessary microdata-specific language as needed (e.g. to be comparably understandable to the [http://www.whatwg.org/specs/web-apps/current-work/#vcard sample vCard4/hCard1 microdata vocabulary]. Also provide any necessary RDFa-specific language as needed. Both preferably in a generic vocabulary-independent way.
* write a porting guide mapping v1 property -> v2 property
** use-case: simple search/replace in templates (e.g. in case web author doesn't remember existing microformats vocabs and where they used them).
** advise using *both* in existing templates (e.g. in case some CSS depends on the existing microformats)
* analyzie/document how well the microformats2 model and vocabularies satisfy the [http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2009-May/019681.html use-cases used to design/create microdata].

== combining microformats ==
Since microformats2 uses simple flat sets of properties for each microformat, multiple microformats are combined to indicate additional structure.

=== h-event location h-card ===
Events commonly have venue information with additional structure, like address information. For example:

<syntaxhighlight lang="html">
<div class="h-event">
<a class="p-name u-url" href="http://indiewebcamp.com/2012">
IndieWebCamp 2012
</a>
from <time class="dt-start">2012-06-30</time>
to <time class="dt-end">2012-07-01</time> at
<span class="p-location h-card">
<a class="p-name p-org u-url" href="http://geoloqi.com/">
Geoloqi
</a>,
<span class="p-street-address">920 SW 3rd Ave. Suite 400</span>,
<span class="p-locality">Portland</span>,
<abbr class="p-region" title="Oregon">OR</abbr>
</span>
</div>
</syntaxhighlight>

The nested h-card used to structure the p-location of the h-event is represented as a structured value for "location" in the JSON, which has an additional key, "value" that represents the plain text version parsed from the p-location.

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-event"],
"properties": {
"name": ["IndieWebCamp 2012"],
"url": ["http://indiewebcamp.com/2012"],
"start": ["2012-06-30"],
"end": ["2012-07-01"],
"location": [{
"value": "Geoloqi",
"type": ["h-card"],
"properties": {
"name": ["Geoloqi"],
"org": ["Geoloqi"],
"url": ["http://geoloqi.com/"],
"street-address": ["920 SW 3rd Ave. Suite 400"],
"locality": ["Portland"],
"region": ["Oregon"]
}
}]
}
}]
}
</syntaxhighlight>

Questions:
<div class="discussion">
* Should the nested hCard be present also as a top-level item in the JSON? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
** My current (2012-243) leaning is no. - [[User:Tantek|Tantek]] 18:53, 30 August 2012 (UTC)
** If so, how do we avoid expansion of the JSON geometrically proportional to the depth of microformat nesting? (Or do we not worry about it?)
* Should there be a canonical hierarchical JSON and a canonical flattened JSON? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
** My current (2012-243) leaning is no, we stick with one canonical JSON for uf2 which is hierarchical. - [[User:Tantek|Tantek]] 18:53, 30 August 2012 (UTC)
** If so, should the flattened JSON have references from properties to nested microformats that have been pushed to the top level per flattening? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
*** If so, what convention does/do JSON follow for such synthetic local reference identifiers? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
</div>

Notes:
* The 'location' value reflects the visible text of its element, including spaces and punctuation, as well as the state abbreviation 'OR'. The 'h-card' property values are only what is marked up, and thus include structure values without extra punctuation, and the state takes the expanded form from the <code>title</code> attribute of its <code><abbr></code> element.

=== h-card org h-card ===
People often publish information general to their company rather than specific to them, in which case, they may wish to encapsulate that in separately nested microformat. E.g. here is a simple h-card example with org property:

[http://blog.lizardwrangler.com Mitchell Baker] (Mozilla Foundation)

with source:
<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<span class="p-org">Mozilla Foundation</span>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": ["Mozilla Foundation"]
}
}]
}
</syntaxhighlight>

Sometimes such organization affiliations are hyperlinked to the website of the organization:

[http://blog.lizardwrangler.com Mitchell Baker] ([http://mozilla.org/ Mozilla Foundation])

You can mark that up with a nested h-card:
<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
</syntaxhighlight>

Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an <code><a href></code> would.

'''FOR PARSERS ONLY:'''

The nested 'h-card' could be marked up as an 'h-org' as well, which adds it to the nested microformat's type array, all as part of the property specified by the 'p-org'.

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card h-org"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card", "h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
</syntaxhighlight>

'''FOR PARSERS ONLY:'''

Without a property class name like 'p-org' holding all the nested objects together, we need to introduce another array for nested children (similar to the existing DOM element notion of children) of a microformat that are not attached to a specific property:

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card","h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
</syntaxhighlight>

Since there's no property class name on the element with classes 'h-card' and 'h-org', the microformat representing that element is collected into the children array.

Such a nested microformat implies some relationship (containment, being related), but is not as useful as if the nested microformat was a specific property of its parent.

For this reason it's recommended that authors should not publish nested microformats without a property class name, and instead, when nesting microformats, authors should always specify a property class name (like 'p-org') on the same element as the root class name(s) of the nested microformat(s) (like 'h-card' and/or 'h-org').

'''FOR PARSERS ONLY:'''

Or the nested object could be only marked up with 'h-card'. Source:

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
</syntaxhighlight>

'''TO DO: Add h-event h-card example and JSON, per real world publishing examples like [http://www.swingtime.co.uk/List/ClSouth.html Swing Time: Classes in Southern England].'''

== authoring ==
=== minimal markup ===
The best way to use microformats-2 is with as little additional markup as possible. This keeps your code cleaner, improves its maintainability, and thus the quality and longevity of your microformats.

One big advantage of microformats-2 over previous microformats (and others) is the ability to add one class name to an existing element to create a structured item.

See the [[microformats-2#simple_microformats_2_examples|simple examples at the top]] for a start, e.g.

Simple hCards work just by adding <code>class="h-card"</code> :
<syntaxhighlight lang="html">
<span class="h-card">Frances Berriman</span>

<a class="h-card" href="http://benward.me">Ben Ward</a>

<img class="h-card" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>

<a class="h-card" href="http://tantek.com">
<img alt="Tantek Çelik" src="http://ttk.me/logo.jpg"/>
</a>
</syntaxhighlight>

* Tip: Inside an open tag, put the <code>class</code> attribute <em>first</em>, then any human text content attributes (e.g. <code>alt</code>), then URL attributes (e.g. <code>href</code> <code>src</code>), and lastly other attributes (e.g. <code>style</code>). Putting the class attribute first ties it closely to the element name/tag itself, makes it more obvious, and thus more likely to be kept up to date.

=== backward compatible ===
If you depend on current microformats [[implementations]], while they're being updated to support [[microformats2]], you can include both existing classic microformats and microformats2 markup.

In short: use both sets of class names simultaneously.

When doing so, use them on the same element, with the microformats-2 class name first, followed immediately by the existing microformats class name.

Here are the microformats-2 hCards from above with current [[hCard]] markup as well, which may require adding a wrapping element (e.g. a <code><span></code>) to separate the root class name element from explicit property class name elements:

<syntaxhighlight lang="html">
<span class="h-card vcard">
<span class="p-name fn">Frances Berriman</span>
</span>

<span class="h-card vcard">
<a class="p-name fn u-url url" href="http://benward.me">Ben Ward</a>
</span>

<span class="h-card vcard">
<img class="p-name fn u-photo photo" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>
</span>

<span class="h-card vcard">
<a class="u-url url" href="http://tantek.com">
<img class="p-name fn u-photo photo" alt="Tantek Çelik"
src="http://ttk.me/logo.jpg"/>
</a>
</span>
</syntaxhighlight>

Tips:
* use the microformats-2 class name first, e.g.
** <code>class="h-card vcard"</code>
** <code>class="u-url url"</code>
* and pair them when using an element for multiple properties, e.g.:
** <code>class="p-name fn u-url url"</code>
** <code>class="p-name fn u-photo photo"</code>
* put microformats classes after classes for CSS (since page authors will likely interact more with their own classes for design than with microformats classes), e.g. as used on individual microformats [[events]] pages:
** <code>class="event-page h-event vevent"</code>

The prefixes (h-, p-, etc.) of microformats2 class names provide easier recognition, and when followed by the similarly named existing class name, they're more easily recognized as related and thus kept together when the markup is maintained over time.

Related FAQ: [[microformats2-faq#when_using_both_h-card_and_vcard_which_should_be_first_and_why|When using both h-card and vcard which should be first and why?]]

== extensions ==
microformats2 is extensible by means of two separate but syntactically similar extension prefixes for experiments intended to be iterated & evolved and for vendor specific extensions not intended for standardization.

=== experimental extensions ===
There have been times when specific sites have wanted to extend microformats beyond the set of properties in the microformat vocabulary, and currently lack any '''experimental''' way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus:

For experimental extensions for the purpose of prototyping to learn more, iterate, towards possibly standardizing, use the <code>-x-</code> prefix before root and property class names.

Specifically:
* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a literal 'x' for an experimental extension

Examples:
* "p-x-prep-time" - a possible experimental property name to be added to [[h-recipe]] upon consideration/documentation of real-world usage/uptake.

See [[microformats2-experimental-properties]] for more examples.

=== <span id="VENDOR_EXTENSIONS">vendor extensions</span> ===
For vendor specific extensions, microformats2 uses a mechanism similar to CSS vendor extensions, using a similar syntax as experimental extensions, except with a vendor prefix instead of a literal 'x'.

* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-, numbers allowed after first character)

Examples:
* "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "one-ring" microformat root class name.
* "p-goog-preptime" - to represent [http://www.google.com/support/webmasters/bin/answer.py?answer=173379 Google's "preptime" property extension] to [[hRecipe]] (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.)

See [[vendor-prefixes]] for more examples.

=== extensions background ===
This extensibility mechanism is a composition of the following (at least somewhat) successful extension syntaxes:
* [http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords CSS 2.1 4.1.2.1 Vendor-specific extensions]
* IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [http://en.wikipedia.org/wiki/Internet_media_type]
* IETF MIME experimental fields (e.g. x-spam-score)
* HTTP header extensions (e.g. x-pingback)
* note also [http://www.mnot.net/blog/2009/02/18/x- some critical thoughts from mnot]

In particular:

Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.

Proprietary or experimental CSS3 property implementations have been very successful.

There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like:

* -moz-border-radius
* -webkit-border-radius

etc.

Note that these are merely string '''prefixes''', not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use.

This use of vendor specific CSS properties allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.

The benefits have been two-fold:
* designers have been able to make more attractive sites sooner (at least in some browsers)
* features have been market / real-world tested before being fully standardized, thus resulting in better features

Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and [https://secure.wikimedia.org/wikipedia/en/wiki/List_of_HTTP_header_fields#Common_non-standard_headers Wikipedia: HTTP header fields - non-standard headers] (could use RFC reference instead) respectively, like:

* application/x-latex (per [https://secure.wikimedia.org/wikipedia/en/wiki/Internet_media_type#Type_x Wikipedia Internet media type: Type x])
* x-spam-score (in email headers)
* X-Pingback (per [http://en.wikipedia.org/wiki/Pingback Wikipedia:Pingback])

Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases:

* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])

See [[microformats2-origins#VENDOR_EXTENSIONS]] for more background.

== validators ==
microformats2 validators:

{{new}} Test your microformatted web page with:
* https://pin13.net/mf2/

Barnaby Walters has a hosted version of the open source php-mf2 [[parser]] where you can enter your markup into a textarea and see how it's parsed:
* http://waterpigs.co.uk/php-mf2/

See the [[validators]] page for a longer list of validators.

== Examples in the wild ==
Please add new examples in the wild of microformats-2 to the top of this list. When it gets too big we can move it to a separate page like [[microformats-2-examples-in-wild]].

* ...
* David John Mead marks up his profile, blog posts and comments with h-card, h-entry and h-cite on [http://davidjohnmead.com davidjohnmead.com]
* [[User:Brian|Brian Suda]] marks up his blog posts up with h-entry and h-card on [http://optional.is/required/ optional.is]
* Ashton McAllan marks up her blog posts, reposts, comments and likes with h-entry, h-card and h-cite on [https://acegiak.net/ acegiak.net]
* Emma Kuo marks up her blog posts and notes with h-entry and h-card on [http://notenoughneon.com/ notenoughneon.com]
* Scott Jenson marks up his blog posts with h-entry and h-card on [http://jenson.org/ jenson.org]
* Emily McAllen marks up her blog posts with h-entry and h-card on [http://blackwoolholiday.com/ blackwoolholiday.com]
* Ryan Barrett marks up his blog posts, notes, replies and likes with h-entry and h-card on [https://snarfed.org/ snarfed.org]
* Barry Frost marks up his notes with h-entry, h-card and h-cite on [http://barryfrost.com/ barryfrost.com]
* Amber Case marks up her profile, blog posts, replies and notes with h-entry and h-card on [http://caseorganic.com/ caseorganic.com]
* Johannes Ernst marks up his blog posts with h-entry on [http://upon2020.com/blog/ upon2020.com]
* Michiel de Jong marks up his profile and notes with h-entry and h-card on [https://michielbdejong.com/ michielbdejong.com]
* Mike Taylor marks up his profile and blog posts with h-card and h-entry on [https://bear.im/bearlog/ bear.im]
* Erin Jo Ritchey marks up her profile, posts and comments using h-card, h-entry and h-cite with idno on [http://erinjo.is/ erinjo.is]
* Jeena Paradies marks up his profile, blog posts, notes and comments using h-card, h-entry and h-cite on [https://jeena.net/ jeena.net]
* Andy Sylvester marks up his profile, blog posts and comments using h-card and h-entry on [http://andysylvester.com/2014/03/01/howto-setting-up-the-selfoss-feed-reader-with-microformats-support/ andysylvester.com] (note: as of 2014-03-13 using h-entry for comments instead of correct h-cite --[[User:Barnabywalters|bw]] 14:44, 13 March 2014 (UTC))
* Hakan Demir marks up his Coupon and Voucher blog posts with h-entry and h-card on [http://www.gutscheinflagge.de/ gutscheinflagge.de]
* Chloe Weil marks up her blog posts with h-entry on [http://chloeweil.com/blog chloeweil.com]
* Christophe Ducamp marks up his blog posts and profile with h-entry and h-card on [http://christopheducamp.com/ christopheducamp.com]
* Glenn Jones marks up his blog posts, notes, replies, profile and comments with h-entry, h-card and h-cite on [http://glennjones.net/ glennjones.net]
* Marcus Povey marks up his blog posts and profile with h-entry and h-card on [http://www.marcus-povey.co.uk/ marcus-povey.co.uk]
* Eugen Busoiu marks up his web profile with h-card on [http://eugenbusoiu.com/#utm_source=microformats2&utm_medium=h-card&utm_campaign=Microformats eugenbusoiu.com]]
* Matthias Pfefferle marks up his blog posts, comments and profile with h-card, h-cite and h-entry on [http://notizblog.org/ notizblog.org]
* Kyle Mahan marks up his profile and notes with h-card and h-entry on [http://kylewm.com/ kylewm.com]
* Emil Björklund marks up his blog posts with h-entry and h-card ([http://thatemil.com/blog/2013/09/16/webmentioning-adactio/ example])
* App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 ([https://alpha.app.net/voidfiles example])
* Brett Comnes marks up his posts with h-entry and h-card ([http://bret.io/2013/06/29/getting-started-with-bower/ example])
* Ben Werdmuller marks up his posts with h-card and h-entry, u-in-reply-to and u-like ([http://werd.io/view/51d5097fbed7ded0633a5956 example])
* Sandeep Shetty marks his posts up with h-card and h-entry, as well as draft u-in-reply-to and experimental u-like properties ([http://sandeep.io/101 example])
* Laurent Eschenauer marks up his posts with h-entry ([http://eschnou.com/entry/first-autonomous-flight-of-my-nodecopter-62-24992.html example])
* Tom Morris marks up his posts using h-entry ([http://tommorris.org/posts/8417 example])
* Sinolandquality marks up some of their content using h-feed and h-entry on [http://www.sinolandquality.com/Blog/?page_id=3516&utm_content=buffere4d40&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer sinolandquality.com]
* [http://www.w3.org/conf/ W3Conf 2013] uses h-event for the main event, and h-card for all the speakers and notable attendees. The h-cards make particularly good use of implied name, url, and photo properties.
* [http://wordpress.org/extend/themes/sempress SemPress] is a WordPress theme that supports h-card, h-feed/h-entry and h-as-*
* [http://the-pastry-box-project.net/ The Pastry Box Project] use h-card and h-entry markup on their homepage and individual thoughts pages
* Tom Morris uses h-card and [[XFN]] to markup [http://tommorris.org/pages/blogroll his blogroll].
* Aaron Parecki uses h-card to markup both authorship and references to people in his notes permalinks, e.g. [http://aaronparecki.com/2012/230/reply/1 2012/230/reply/1].
* [http://tantek.com/ Tantek Çelik] uses h-card, h-event, and h-entry on his home page, as well as h-entry on all post permalinks, e.g. [http://tantek.com/2012/243/t1/name-beats-title-modern-use-dubline-core-wrong-uf2 2012-243 post], with [[rel-prev]]/[[rel-next]] (if applicable) to indicate prev/next posts, and with [[rel-author]] to his home page with canonical hCard to indicate authorship.
* [http://waterpigs.co.uk/ Barnaby Walters] uses h-card on his home page, h-card, h-entry and XFN markup on his [http://waterpigs.co.uk/notes notes page].
** 2013-01-25 Barnaby Walters: <cite>[http://waterpigs.co.uk/articles/experimental-markup Experimental Markup]</cite> - describes how he's using microformats2 vocabularies: <code>h-adr</code>, <code>h-card</code>, <code>h-entry</code>, <code>h-event</code>, <code>h-geo</code>, <code>h-review</code>, and experimental vocabularies: <code>h-feed</code> (embedded for update histories), [[activity-streams]] objects <code>h-as-article</code>, <code>h-as-collection</code>, <code>h-as-note</code>, <code>h-as-update</code>, as well as experimental properties: <code>u-alternate</code> and <code>u-as-downstream-duplicate</code> (links to POSSE copies), and <code>u-in-reply-to</code> (links to content that the posts are in reply to).
* [http://tantek.com/presentations/2012/06/microformats microformats.org at 7 years] presentation with h-event and h-card markup for people and organizations.
* [http://tantek.com/presentations/2012/06/pdf2012-indieweb.html Rise of the Indie Web hCards] (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has [[microformats-2]] h-calendar and h-card markup
* WebMaker by Mozilla has [[microformats-2]] h-calendar and h-card on event search (e.g. [https://webmaker.org/en-US/events/near/?lat=45.5234515&lng=-122.6762071 search near Portland Oregon]) and event pages (e.g. [https://webmaker.org/en-US/events/192f56eb9/ IndieWebCamp 2012]).[https://twitter.com/microformats/status/212207925643587585]
* WebFWD by Mozilla has [[microformats-2]] h-card markup on [https://webfwd.org/about/experts/ experts] and [https://webfwd.org/about/team/ team] pages
* [http://indiewebcamp.com IndieWebCamp] has [[microformats-2]] h-event markup with nested h-cards for the organizers and the location.
* [https://wiki.mozilla.org/Events Mozilla Events] page has [[microformats-2]] h-event markup with attendees marked up with h-card.
* The [http://pdx.esri.com/blog/2013/10/17/introducing-mapattack/ Esri PDX Blog] has h-entry markup on all blog posts (as of 2013-10-19), and h-product markup on [http://pdx.esri.com/projects/terraformer/ project pages]

=== offline ===
* spreadly marks up share permalink pages with h-entry, as well as minimal h-cards and experimental p-like properties

== Implementations ==
Test your microformatted web page with:

=== Live Textarea Input ===
Use any of these to enter HTML+microformats2 markup and see the parsed result!

* https://microformats.io hosts several of the parser libraries listed below for interactive testing
** https://go.microformats.io
** https://node.microformats.io/
** https://php.microformats.io/
** https://python.microformats.io/
** https://ruby.microformats.io/
** or look for "Parser Libraries" on the homepage
* https://pin13.net/mf2/ (where it says "Microformats Parser")


=== Blogging tools ===
* '''Storytlr''' parses the <code>target</code> from [http://indiewebcamp.com/pingback pingbacks] for [https://github.com/storytlr/storytlr/blob/master/protected/application/public/controllers/PingbackController.php#L63 h-entry with properties and nested h-card] for information to automatically display in the [http://web.archive.org/web/20130425010536/http://eschnou.com/entry/testing-indieweb-federation-with-waterpigscouk-aaronpareckicom-and--62-24908.html comments section on a post] (archived; [http://eschnou.com/entry/testing-indieweb-federation-with-waterpigscouk-aaronpareckicom-and--62-24908.html original]).
** Note: per storytlr.org, retrieved 2022-05-22:
<blockquote>Storytlr is no longer maintained and '''might be unsafe to run on a public server'''. It is running on an old version of PHP and the Zend framework and has not been upgraded to latest versions and security patches.</blockquote>

=== Converters ===
* '''[https://github.com/snarfed/granary granary]''' is a library and REST API that converts between silo APIs, [[ActivityStreams]], [[microformats2]], and Atom (all directions). Supported silos include Facebook, Twitter, Instagram, Google+, and Flickr. Users include [http://brid.gy/ Bridgy], [http://reader.kylewm.com/ Woodwind], and [https://facebook-atom.appspot.com/ facebook-atom] and [https://twitter-atom.appspot.com/ twitter-atom], among others.

* '''[http://pipes.yahoo.com/pipes/pipe.info?_id=afc5568b4e8643bfb05436b1caaf91bc microformats to RSS]''' - a Yahoo! pipe that converts a URL containing an [[h-feed]] containing h-entries, into an [[RSS]] feed ([http://waterpigs.co.uk/notes/4SeNi5/ 2013-10-21 blog post announcing])

* '''[https://xray.p3k.io XRay]''' ([https://github.com/aaronpk/XRay source code]) - Returns a normalized representation of the microformats data at a URL

=== Parsers ===
Parsers, open source libraries, in alphabetical order by programming language:

If you are implementing a microformats2 parser, see:
* [[microformats2-parsing]]

==== Parsers in production ====
The following parsers are of very high quality, in active development, and use on live sites on the web in production.

===== Java =====
* [[any23]] Apache Any23 (Anything to Triples)] a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents: http://any23.apache.org

===== Javascript =====
* '''microformats-parser''' for both browser and node.js
** github open source: https://github.com/aimee-gm/microformats-parser (current)
** live: https://aimee-gm.github.io/microformats-parser/

Previously:
* '''microformat-node''' Node.js microformats2 parser
** github open source: https://github.com/microformats/microformat-node (current)
*** forked from https://github.com/glennjones/microformat-node
** test suite: https://github.com/microformats/tests

** command line: https://github.com/JerrySievert/mf2
* '''microformat-shiv''' - cross browser javascript microformats2 parser which can also be used in browser extensions.

** github open source: https://github.com/glennjones/microformat-shiv

===== PHP =====
* '''<span id="php-mf2">php-mf2</span>''' - PHP microformats2 parser
** github open source: https://github.com/indieweb/php-mf2
** Packagist: https://packagist.org/packages/mf2/mf2
** live:
*** textarea entry: http://waterpigs.co.uk/php-mf2/
*** URL and textarea entry: https://pin13.net/mf2/
** [https://github.com/barnabywalters/php-mf-cleaner mf-cleaner]: functions for working with the raw mf2 data structure

===== Python =====
* '''mf2py''' Python microformats2 parser
** main entry: [[mf2py]]
** github open source: https://github.com/tommorris/mf2py
** live:
*** URL entry: [https://mf2py.herokuapp.com/ mf2py.herokuapp.com]
*** textarea entry: https://kartikprabhu.com/connection/mfparser
*** another textarea: http://www.unmung.com/?html=
*** URL and/or textarea: https://kylewm.com/services/mf2

===== Ruby =====
* '''indieweb/microformats-ruby''' Ruby microformats parser
** github open source: https://github.com/indieweb/microformats-ruby
** live text entry: https://microformats-parser-ruby.herokuapp.com

===== Haskell =====
* '''myfreeweb/microformats2-parser''' Haskell microformats2 parser
** github open source: https://github.com/myfreeweb/microformats2-parser
** live textarea entry: https://unrelenting.technology/mf2/

==== Development parsers ====
The following parsers are in-development and have key microformats2 functionality yet are incomplete, not fully tested, or have other limitations. Contributions welcome!

===== Erlang =====
* '''hazybluedot/mf2erl''' Erlang microformats2 parser
** github open source: https://github.com/hazybluedot/mf2erl

===== Elixir =====
* '''ckruse/microformats-elixir''' Elixir microformats2 parser
** github open source: https://github.com/ckruse/microformats2-elixir

===== Go =====
* '''willnorris/microformats''' Golang microformats2 parser
** github open source: https://github.com/willnorris/microformats
** live textarea entry: https://go.microformats.io/

===== Java =====
* '''Apache Any23''' a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents. Supports Microformats1 and 2.
** Download recent release: http://any23.apache.org/download.html
** live: http://any23-vm.apache.org/
** source: http://any23.apache.org/build-src.html
* '''mf2j''' An early-stage Java microformats2 parser
** github open source: https://github.com/kylewm/mf2j
** live: https://mf2j.herokuapp.com/?url={http://example.com}

===== Perl =====
* '''Web::Microformats2''' Perl microformats2 parser
** https://metacpan.org/pod/Web::Microformats2
** open source: https://github.com/jmacdotorg/microformats2-perl

==== Experiments ====
Experiments and other proof of concept microformat2 parsing support.
* '''Rust''' - https://gitlab.com/maxburon/microformats-parser
* ...

=== Outreach ===
* [https://github.com/mozilla/fathom/issues/42 Mozilla Fathom: examples with nested classes, e.g. microformats2]

== Presentations ==
Presentations about microformats2:
* 2013-01-24 <cite>[http://waterpigs.co.uk/presentations/microformats-2/ Microformats 2]</cite> presentation by [[User:Barnabywalters|Barnaby Walters]] at the [[events/2013-01-24-exeter-web-meetup|Exeter Web Meetup]] in Devon, UK.
* 2012-09-21 <cite>[http://tantek.com/presentations/2012/09/microformats2/ microformats2 & bits of HTML5: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-09-21-refreshlx|RefreshLX]] in Lisbon, Portugal.
* 2012-07-21 <cite>[http://tantek.com/presentations/2012/07/html5-uf2/ HTML5 and microformats2: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-07-21-cascadesf|Innovators of the Web conference]] in San Francisco, CA.
* 2012-07-14 <cite>[http://tantek.com/presentations/2012/07/html5-microformats2/ HTML5 and microformats2: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-07-14-open-web-camp-4|Open Web Camp IV]] in San Jose, CA.

== Testimonials ==
* <blockquote class="twitter-tweet">To prove the web standards community can come up with better standards than the SE’s, compare this: http://microformats.org/wiki/microformats-2 with schema . org — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298907685452124160 2013-02-05 13:35]</blockquote>
* <blockquote class="twitter-tweet">... I’m hoping SE’s will pick up microformats2. It’s SO much cleaner. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298911287117758464 2013-02-05 13:49]</blockquote>
* <blockquote class="twitter-tweet">... But damn Microformats2 are sexy. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298912179292344320 2013-02-05 13:53]</blockquote>

== Origins ==
This page was originally used to brainstorm and develop microformats2 in an exploratory manner, with problem statements, questions, lessons learned from past and other formats.

Now that [[microformats2-parsing]] is a Microformats specification, the original brainstorming has been moved to a separate page for anyone who wants to understand more about how we came up with the design of microformats2, and how it evolved in the early years.
* [[microformats2-origins]]

== See Also ==
* [[microformats2]]
* [[microformats2-brainstorming]] - moving more experimental / undeveloped / and rejected thoughts ideas here to simplify/progress *this* page further.
* [[microformats2-experimental-properties]] - listing experimental (-x- prefixed) properties and their use
* [[microformats2-prefixes]]
* [[vendor-prefixes]]
* [[microformats2-faq]]
* [[microformats2-parsing]]
* 2010-05-02 [[events/2010-05-02-microformats-2-0|microformats 2.0 discussion session at FOO East]]

spread-microformats

2024-11-29T23:12:24Z

GRegorLove: /* T-Shirts */ +motto ideas

{{DISPLAYTITLE:Spread Microformats}}

Inspired by [http://spreadfirefox.com/ Spread Firefox], this page is for sharing community resources for marketing microformats such as [[buttons]], banners, wallpaper / desktop screens, logo graphics, [[stickers]], t-shirts etc.

== Email ==
* See [[advocacy-email-samples]] for some sample emails you can copy/customize and send to site owners to encourage them adopt microformats.

== Wallpaper ==
=== Wallpaper and desktop screens. ===
* A [https://web.archive.org/web/20111128072549/http://remiprevost.com/images/wallpapers/microformats/ wallpaper] by [[User:Remi|Rémi Prévost]]

== Logo ==
https://indieweb.org/images/8/80/microformats-logo.png

=== logo text ===
https://web.archive.org/web/20110820103746/http://img.skitch.com/20090715-c3xmikadkj8udt4sq6aqfkqtac.png

* The logo [https://web.archive.org/web/20151003234446/http://vault.simplebits.com/notebook/2005/06/22/microformats/ was designed by Dan Cederholm]
* High-resolution [http://vault.simplebits.com/bits/microformats/microformats-logo.eps EPS] and [http://vault.simplebits.com/bits/microformats/microformats-logo.png transparent PNG] versions of the microformats logo text by [[User:DanCederholm|Dan Cederholm]].
* the microformats typeface is [https://www.emigre.com/Fonts/Solex Solex Medium] by Emigre.

=== logo mark ===
* An [https://web.archive.org/web/20111128072549/http://remiprevost.com/images/wallpapers/microformats/mf-vector.svg SVG] and [https://web.archive.org/web/20111128072549/http://remiprevost.com/images/wallpapers/microformats/mf-vector.png PNG] (for Fireworks) version, by [[User:Remi|Rémi Prévost]]. Released under [https://creativecommons.org/licenses/by-nc-sa/3.0/ CC BY-NC-SA].
* An [https://github.com/btrem/microformats/blob/master/logos/microformats.svg SVG] version (and alternative [https://github.com/btrem/microformats/blob/master/logos/microformats-orange.svg orange colour]) by [https://btrem.com Brian Tremblay]. Released under [https://creativecommons.org/publicdomain/zero/1.0/ CC0 1.0 Universal (CC0 1.0) Public Domain Dedication].
** Also available (slightly modified) [https://github.com/edent/SuperTinyIcons/pull/442 as part of] the [https://github.com/edent/SuperTinyIcons Super Tiny Web Icons collection]. Released under [https://github.com/edent/SuperTinyIcons/blob/e6ea45f6441bd0111295b2713df73c1502de6ec5/LICENSE MIT License].

== POSH ==
* [[posh|POSH]] logos and buttons

== stickers ==
See the [[stickers]] page to easily order a set of moo microformats stickers!

== T-Shirts ==
* See [http://flickr.com/photos/tags/microformatstshirt photos of microformats tshirts on Flickr] (the [http://flickr.com/photos/tags/microformatstshirt/clusters/ clusters] are especially fun)
** Note also [http://pixelsebi.com/2006-10-26/microformats-t-shirt-in-second-life/ microformats t-shirt in Second Life]

=== motto ideas ===
"microformats.org: keeping it classy since 2005"

=== do it yourself tshirts ===
[[User:TheJbf|Burcu Dogan]] has made her own microformats t-shirt:

http://web.archive.org/web/20120528054541if_/http://i44.tinypic.com/2s01i1j.jpg

For those who are not able to find a microformats t-shirt, it is possible to make one at home less than an hour. The requirements for such a pressing process are listed below:
* A high quality microformats logo (which can be found below the '''Logo headline''' on this page)
* A black t-shirt
* An iron-on transfer paper for '''dark t-shirts''' (note that printers doesn't print white, so there're special papers to print white on dark)
* An iron an a hard surface. (Ironing press with a large surface is highly recommended.)
* A laser printer
* Sharp and sensitive scissors
* Non-metalic heat resisting papers

('''Warning:''' Take the instructions on the transfer paper you bought as the first reference, we're not responsible for unsuccessful attempts. Tips about pressing can change from paper to paper.)

Firstly, you need to print the logo on the transfer paper. Transfer papers for dark t-shirts are sticky backed white papers which vary in size. You need to decide which size you want to press on your t-shirt. A4 and A3 are suitable for microformats t-shirts.

Print the logo with a black background. The result of the paper printed should look like this:

http://web.archive.org/web/20120528052329if_/http://i40.tinypic.com/2ylqqmb.jpg

(You can, of course decrease, the amount of background area to save ink)

Now it is time to separate logo from the background. Carefully clip the edges and get the logo all alone. White borders should stay with the green layers, don't make a mistake by clipping them out.

Prepare the iron press, you will need the highest temperature with no stream to transfer successfully. Give your press at least 10 minutes to heat fully. While the iron is heating, decide which position your logo should appear. Use a ruler to check if the logo is positioned symmetrically.

http://web.archive.org/web/20120528061614if_/http://i41.tinypic.com/2v334pc.png

If your iron press is heated, gently peel the tiny paper on the back of the transfer paper to make it sticky. Place it on the t-shirt and put 1 or 2 non-metalic heat resisting paper of any kind on the logo. Be sure that transfer paper doesn't overlap.

http://web.archive.org/web/20120601000105if_/http://i40.tinypic.com/kcl7gk.png

Press the iron for 10-15 seconds. This actually depends on the paper you are using, so it is best to follow the instructions on the iron-on transfer paper you purchased. If necessary repress the iron on the whole surface for 5-10 seconds again.

And, you made a new microformats t-shirt! Don't forget to take a picture and share.

Note that you should hand wash your t-shirt and iron it from back carefully. Don't forget that it is also possible to use another fabrics such as bags to print microformats logos. We're waiting for your creations.

== External online community resources ==

=== Video ===
* See [http://www.youtube.com/results?search_query=microformats videos of microformats on YouTube] or [http://vimeo.com/groups/microformats Vimeo], in particular, a [http://www.youtube.com/watch?v=UAV4SGpPuQI video of a microformats tshirt] ([http://www.flickr.com/photos/fumi/372068162/ photo]).

===Social networking===
Groups for fans and advocates of microformats to join or follow:
* [http://www.facebook.com/microformats Facebook microformats fan page]
* [http://www.facebook.com/group.php?gid=2374732285 Facebook microformats group]
* [http://flickr.com/groups/microformats/ Flickr microformats group]
* [http://getsatisfaction.com/microformats microformats on Satisfaction]
* [http://twitter.com/microformats microformats on Twitter].

=== wiki-communities ===
* [http://en.wikipedia.org/wiki/Wikipedia:WikiProject_Microformats Wikipedia: Project Microformats]
**[http://ko.wikipedia.org/wiki/%EC%9C%84%ED%82%A4%EB%B0%B1%EA%B3%BC:%EC%9C%84%ED%82%A4%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8_%EB%A7%88%EC%9D%B4%ED%81%AC%EB%A1%9C%ED%8F%AC%EB%A7%B7 -" - in Korean]
**[http://zh.wikipedia.org/wiki/Wikipedia:%E5%B0%88%E9%A1%8C/%E5%BE%AE%E6%A0%BC%E5%BC%8F -" - in Chinese]
* [http://www.usemod.com/cgi-bin/mb.pl?MicroFormats meatball:microformats] -- a first page (stub to be reviewed) dedicated to have any review/opinion from the meatballers especially on the wiki-formats.
* [http://communitywiki.org/fr/MicroFormats communitywiki:microformats] -- an old multilingual page with a blockcodemachine proposal.

== See Also ==
* [[advocacy]]
* [[buttons]]
* [[podcasts]]
* [[presentations]]
* [[press]]
* [[2d_barcodes]]

sitemap-brainstorming

2024-11-18T23:21:45Z

GRegorLove: /* Content and class values */ note: google ignores priority and changefreq

{{DISPLAYTITLE:Sitemap Brainstorming}}

Per the microformats [[process]] this page documents attempts to brainstorm a [[sitemap]] and related mechanisms microformat.

'''Note''' : We define 'site mapping' as the process of generating a particular sitemap flavour, like sitemap.xml or an HTML sitemap, or something related like an HTML5 cache manifest.

'''Note''' : Here we are attempting to derive a simple mechanism, lowest common denominator and driven by a top level HTML nav mechanism. We are not considering crawlers etc just yet. It is possible that later when/if we look at crawlers we may need to encode some kind of order information (for now this is explicitly defined in the order the author defined the link elements).

== Brainstorming solution 1 ==
=== Content and class values ===
* h-sitemap required
** wraps a sitemap block
* u-url, required
** every link element we want included in a generated artifact must be annotated with this
* p-priority-x, optional
** only pertinent to sitemap.xml
** p-priority-0-0 = 0.0, p-priority-0.1 = 0.1 ... p-priority-1-0 = 1.0
** if the author fails to specify a priority it is sane to assume a machine may generate the default of 0.5 as per the sitemaps.org protocol
* p-change-x, optional
** only pertinent to sitemap.xml
** we can lift the possible values directly out of the sitemaps.org protocol (p-change-always|p-change-hourly...)

'''Notes''':
* We ignore <code>lastmod</code> for now (again only pertinent to sitemap.xml)
* Google (and maybe others) ignore <code>priority</code> and <code>changefreq</code> [https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap#xml]

=== Examples ===
==== Simple HTML sitemap or cache manifest example ====
<pre><nowiki>
<ul class="h-sitemap">
<li>
<a class="u-url" href="http://www.site.tld/">Home</a>
</li>
<li>
<a class="u-url" href="http://www.site.tld/section1/">Section 1</a>
</li>
</ul>
</nowiki></pre>

==== sitemap.xml example with changefreq specified ====
<pre><nowiki>
<ul class="h-sitemap">
<li>
<a class="u-url p-change-daily" href="http://www.site.tld/">Home</a>
</li>
<li>
<a class="u-url p-change-weekly" href="http://www.site.tld/section1/">Section 1</a>
</li>
</ul>
</nowiki></pre>

==== sitemap.xml example with changefreq and priority specified ====
<pre><nowiki>
<ul class="h-sitemap">
<li>
<a class="u-url p-change-daily p-priority-1-0" href="http://www.site.tld/">Home</a>
</li>
<li>
<a class="u-url p-change-weekly p-priority-0-8" href="http://www.site.tld/section1/">Section 1</a>
</li>
</ul>
</nowiki></pre>

==== sitemap.xml example where nav mechanism is structured differently ====
<pre><nowiki>
<div class="h-sitemap">
<a class="u-url p-change-weekly p-priority-0-6" href="/section1">Section 1</a>
<span>.</span>
<a class="u-url p-change-monthly p-priority-0-4" href="/section2">Section 2</a>
</div>
</nowiki></pre>

== see also ==
* [[sitemap]]
* [[sitemap-examples]]
* [[sitemap-formats]]
* [[sitemap-brainstorming]]
* [[sitemap-issues]]

blog-redesign

2024-09-16T21:20:42Z

GRegorLove: /* Simple PHP templates */ +Plates: Native PHP Templates

{{stub}}

This page is to keep track (project management) of a 2024 microformats.org blog redesign including moving from WordPress to something based on static files in order to drastically reduce admintax and potential for future vulnerabilities/compromises.

== Goals ==
Preservation:
* All existing blog posts remain
* Ideally at their existing permalinks, or at least redirecting from current permalinks to new permalinks
* Preserve custom inline HTML and styles in blog posts
* Preserve existing styling and presentation of blog posts and aggregation pages in general

Future:
* Able to add new blog posts occasionally (this only happens around once a year at this point)

Maintenance:
* As little dynamic server code as possible to reduce the chances of vulnerabilities

== Non-goals ==
* Another dynamic CMS that requires frequent software updates
* Redesigning the look and feel of the blog
* Preserving WordPress user accounts / identities (ok to replace with another identity system, IndieAuth, GitHub etc.)

== Types of pages ==
Pages (URLs) to preserve:
* Blog top level index: https://microformats.org/blog
* 99 blog post permalinks: e.g. https://microformats.org/2022/02/19/how-to-consume-microformats-2-data
* Month pages: e.g. https://microformats.org/2018/06
* Tag pages: e.g. https://microformats.org/tag/microformats2

== Options ==

=== Static site generator built on GitHub Actions ===
* Port the site to some sort of SSG that can be built on GitHub
* Deploy the static built files to the server

=== Simple PHP templates ===
Similar to oauth.net, use simple PHP templating for the pages. ([https://github.com/aaronpk/oauth.net/blob/main/public/webauthn/index.php example source file])
* Another solid example from The PHP League, [https://platesphp.com/ Plates: Native PHP Templates]

=== Static HTML archive ===
* Archive all pages as static HTML, including month pages and tag pages
* New blog post pages would exist entirely outside of the static archive

=== Switch entire site to MediaWiki ===
* MediaWiki already running at <code>/wiki</code>; update it to run at <code>/</code>; would need to add redirects so existing wiki permalinks keep working
* Port blog posts into wiki pages (may be issues preserving custom inline HTML and styles in blog posts?)

== General Checklist ==
Before decommissioning our WordPress install:
* [ ] make a list of WordPress user accounts
* [ ] determine which WordPress user accounts belong to [[admins]] and find their equivalent GitHub usernames
* [ ] determine which accounts belong to blog post authors, and find their equivalent personal site to credit instead (and ideally their GitHub handle to credit wherever the raw post content is moved to)
* [ ] ...

blog-redesign

2024-09-13T00:05:47Z

GRegorLove: /* Options */ Switch entire site to MediaWiki

{{stub}}

This page is to keep track (project management) of a 2024 microformats.org blog redesign including moving from WordPress to something based on static files in order to drastically reduce admintax and potential for future vulnerabilities/compromises.

== Goals ==
Preservation:
* All existing blog posts remain
* Ideally at their existing permalinks, or at least redirecting from current permalinks to new permalinks
* Preserve custom inline HTML and styles in blog posts
* Preserve existing styling and presentation of blog posts and aggregation pages in general

Future:
* Able to add new blog posts occasionally (this only happens around once a year at this point)

Maintenance:
* As little dynamic server code as possible to reduce the chances of vulnerabilities

== Non-goals ==
* Another dynamic CMS that requires frequent software updates
* Redesigning the look and feel of the blog
* Preserving WordPress user accounts / identities (ok to replace with another identity system, IndieAuth, GitHub etc.)

== Types of pages ==
Pages (URLs) to preserve:
* Blog top level index: https://microformats.org/blog
* 99 blog post permalinks: e.g. https://microformats.org/2022/02/19/how-to-consume-microformats-2-data
* Month pages: e.g. https://microformats.org/2018/06
* Tag pages: e.g. https://microformats.org/tag/microformats2

== Options ==

=== Static site generator built on GitHub Actions ===
* Port the site to some sort of SSG that can be built on GitHub
* Deploy the static built files to the server

=== Simple PHP templates ===
Similar to oauth.net, use simple PHP templating for the pages. ([https://github.com/aaronpk/oauth.net/blob/main/public/webauthn/index.php example source file])

=== Static HTML archive ===
* Archive all pages as static HTML, including month pages and tag pages
* New blog post pages would exist entirely outside of the static archive

=== Switch entire site to MediaWiki ===
* MediaWiki already running at <code>/wiki</code>; update it to run at <code>/</code>; would need to add redirects so existing wiki permalinks keep working
* Port blog posts into wiki pages (may be issues preserving custom inline HTML and styles in blog posts?)

xfolk-fr

2024-06-20T23:54:15Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:xFolk RC1}}
{{DraftSpecification}}

'''xFolk''' (de "xFolksonomie) est un format simple et ouvert pour publier des collections de signets. Il permet aux services de mieux améliorer l'expérience utilisateur et de partager des données dans un logiciel de signets basé sur le web. xFolk peut être embarqué dans HTML ou XHTML, Atom, RSS et le XML arbitraire. C'est l'un des nombreux [[microformats-fr|microformats]] standards ouverts.

== Spécification Brouillon ==
=== Editeur/Auteur ===
[http://thecommunityengine.com/ Bud Gibson], ([http://thecommunityengine.com The Community Engine])

(traduction [[Christophe Ducamp]])

=== Copyright ===
{{MicroFormatCopyrightStatement2005-fr}}

=== Brevets ===
{{MicroFormatPatentStatement-fr}}

=== Inspiration et Reconnaissances ===
Merci à : [http://www.cnbc.cmu.edu/~plaut/ David Plaut] qui m'a présenté l'idée que les items peuvent appartenir partiellement à beaucoup de catégories en une fois.
Plus récemment, merci à : [http://tantek.com/ Tantek Çelik], [http://epeus.blogspot.com/ Kevin Marks], [http://steve.osdir.com/ Steve Mallet], [http://hybernaut.com/ Brian DelVecchio] et [http://blogmarks.net François Hodierne] qui ont contribué au développement de xFolk avec des critiques sensées et des implémentations.

== Introduction ==
Les services de signets sociaux laissent les utilisateurs sauvegarder et taguer leurs signets pour les partager avec d'autres utilisateurs. Durant la dernière année,
le nombre de ces services a poussé comme des champignons (plus de [http://en.wikipedia.org/wiki/Social_bookmarking 20], avec des exemples comprenant : [http://del.icio.us del.icio.us], [http://furl.net furl], [http://de.lirio.us de.lirio.us], [http://jots.com jots] et [http://blogmarks.net blogmarks].

Le manque d'un standard ouvert et interopérable de données est une problématique majeure pour utiliser les services de signets sociaux. Un standard ouvert ferait qu'il soit possible de collecter facilement des données signets et de les remixer pour inventer de nouveaux services du moteur expérimental de recherche de signets [http://gataga.com gataga]. Un standard ouvert ferait qu'il serait aussi possible d'écrire des javascripts qui fonctionnent transversalement sur les services [http://johnvey.com/features/deliciousdirector/ comme le font certains actuellement pour del.icio.us], permettant des améliorations en expérience utilisateur.

xFolk est un standard ouvert de signet social qui a pour but de parvenir à tous ces avantages. Les services de signets sociaux qui adoptent xFolk continueront à se différencier eux-mêmes des services de données. Mais, la donnée en elle-même sera facile à manipuler par des scripts tiers et sera facile à partager. En tant que résultat, les services de signets pourront offrir à leurs utilisateurs un ensemble plus large d'options à un moindre coût, et se concentrer sur ce qui les différencie vraiment. Les individus ou les groupes opérant seul des répertoires de signets auront accès à un plus large ensemble de fonctionnalités que celles qu'ils pourraient produire seuls.

== Principes de Design XHTML Sémantique ==
{{semantic-xhtml-design-principles-fr}}

== Format ==
Une analyse extensive des services de signets sociaux et des linkblogs, déposée [http://thecommunityengine.com/home/archives/xfolk ailleurs], révèle que les données publiées par tous les services de signets et '''beaucoup''' de linkblogs différents sont décrites par le schéma implicite suivant :

* Un lien bookmarké ou tagué.
* Un titre pour l'entrée.
* Les tags pour le lien.
* Une description étendue ou un résumé du lien.

Comme démontré dans les premières itérations du standard xFolk, ce schéma général peut être traduit en balisage par :
# créer un élément conteneur pour chaque entrée de la classe <code>xfolkentry</code>,
# utiliser un élément <a> pour le lien bookmarké ou tagué de la classe <code>taggedlink</code>,
# utiliser l'attribut title pour l'élément lien tagué <a>, s'il existe, comme l'entry title, autrement utiliser la valeur de l'élément,
# utiliser [[rel-tag-fr|RelTag]] pour les tags, et
# utiliser un élément conteneur de classe <code>description</code>, tel que <p>, pour toute autre description étendue ou résumé.

Une entrée donnée xFolk contiendra toujours un lien tagué comprenant un 'title' avec d'autres éléments optionnels. Les entrées peuvent avoir plus d'un tag tout comme plus d'un élément de classe <code>description</code>. Plusieurs éléments de classe <code>description</code> sont triés par l'ordre du document par défaut. Les éléments sémantiques dans les entrées xFolk peuvent Ãªtre imbriqués à des profondeurs abritraires.

Beaucoup de systèmes de signets sociaux existent, chacun d'eux avec se propres conventions de balisage. En outre, beaucoup de personnes publient déjà des blogs de liens. xFolk est conçu en priorité pour faciliter l'adoption de ces pratiques actuelles. Par conséquent, peu d'hypothèses ont été produites comme les types exacts des éléments utilisés pour une entrée xFolk. Le travail de définir la sémantique est entièrement laissé à la casse et aux valeurs d'attribut rel (dans le cas de [[rel-tag-fr|reltag]]).

Il est attendu que les développeurs utiliseront [http://www.w3.org/TR/xpath XPath] ou une syntaxe équivalente en accédant à des éléments d'entrée xFolk. Une exigence pour xPath est que le document HTML soit bien formé mais pas nécessairement
valide. Par conséquent, bien que non désirable, il est possible d'utiliser xFolk dans un document HTML qui ne valide pas.

=== XMDP Profile ===

Voir le [[xfolk-profile-fr|xFolk profile]] pour le profil [http://gmpg.org/xmdp XMDP] de xFolk.

== Exemple ==
Voilà un signet échantillon comme affiché dans la syntaxe standard de [http://del.icio.us del.icio.us]. Les lignes où les attributs de classe d'éléments doivent changer pour se conformer à xFolk sont marquées avec un commentaire à la fin.
<pre><div class="post"> 
<div>
<a class="delLink" href="http://www.sifry.com/alerts/archives/000306.html"> 
Sifry's Alerts: Technorati launches Related Tags
</a>
</div>
<div class="extended"> 
Ever wanted to see what posts are related to other posts, what tags
are related to others? Now you can! Just check under the Tag
description on most tag pages, like this one, or this one, and you'll
see the patterns. Can you smell the emergence?
</div>
<div class="meta">
to
<a class="delNav" href="/fpgibson/folksonomy">folksonomy</a> 
<a class="delNav" href="/fpgibson/technorati">technorati</a> 
... <a class="delNav" href="/url/cbcabf7de070fdb46598ee679367be49">
and 1 other person
</a>
... on 2005-04-09
</div>
</div></pre>

L'équivalent dans xFolk se fait comme suit. Les commentaires sont placés à la fin des lines oÃ¹ les modifiations d'attribut de classe sont requises
<pre><nowiki>
<div class="xfolkentry"> 
<div>
<a class="taggedlink" href="http://www.sifry.com/alerts/archives/000306.html"> 
Sifry's Alerts: Technorati launches Related Tags
</a>
</div>
<div class="description"> 
Ever wanted to see what posts are related to other posts, what tags
are related to others? Now you can! Just check under the Tag
description on most tag pages, like this one, or this one, and you'll
see the patterns. Can you smell the emergence?
</div>
<div class="meta">
to
<a rel="tag" href="/fpgibson/folksonomy">folksonomy</a> 
<a rel="tag" href="/fpgibson/technorati">technorati</a> 
... <a class="delNav" href="/url/cbcabf7de070fdb46598ee679367be49">
and 1 other person
</a>
... on 2005-04-09
</div>
</div>
</nowiki></pre>

Convertir le balisage pour être conforme à xFolk est presque toujours aussi facile. L'avantage de xFolk est que cela fournit un ensemble d'attributs de classe qui peuvent être réutilisés sur tous les services et blogs de liens, presque toujours sans aucune perte de granularité. La prochaine section présentera plusieurs autres exemples pour illustrer ce point.

Un autre exemple simple (utilisant le marquage listes) :
<syntaxhighlight lang="html">
<ul>
<li>
<ul class="xfolkentry">
<li><a class="taggedlink" href="http://microformats.org/wiki/Main_Page-fr">microformats wiki</a></li>
<li class="description">L'endroit principal pour comprendre les microformats et jouer avec...</li>
<li class="description">Wiki piloté par une communauté</li>
<li class="meta">
Tags :
<a rel="tag" href="http://del.icio.us/tag/microformats">microformats</a>
<a rel="tag" href="http://del.icio.us/tag/websocial">websocial</a>
<a rel="tag" href="http://del.icio.us/tag/semantics">semantics</a>
</li>
</ul>
</li>

<li>

</li>

</ul>
</syntaxhighlight>
== Beaucoup plus d'exemples ==

Nous avons de nombreux exemples pour aider les développeurs à incorporer xFolk dans leurs sites.

=== Dans la jungle ===

Ce sont de vrais exemples de systèmes qui fonctionnent et qui publient les signets dans xFolk. Ceci est une endroit idéal pour commencer à regarder des exemples "dans la jungle" pour essayer de parser, indexer, organiser, etc. Si vous publiez en utilisant xFolk, sentez-vous à l'aise pour ajouter '''en haut''' de cette liste. Une fois que la liste sera trop grosse, nous ferons une page wiki séparée.

* [http://greenvoice.com Greenvoice] a une liste de liens environnementaux générée par les utilisateurs, qui est marquée avec xFolk.
* [http://www.idoneos.com Idoneos.com], une collection conceptuellement en réseau de pages d'informations (essentiellement en espagnol), tague les signets avec xFolk.
* [http://ashaszin.lautre.net/ Ashaszin] - Petit blog tournant sous [http://spip.net SPIP] : les liens del.icio.us et fils web sont tagués avec xFolk .
* [http://www.rolandinsh.lv/blog/ Rolands Umbrovskis - blog] tous les billets sont marqués avec xFolk.
* [http://www.bbc.co.uk/worldservice/bangladeshboat BBC World Service Bangladesh River Journey] et un mashup de réseau social, il utilise xFolk pour les entrées de signets hAtom. voir la [http://dharmafly.com/blog/bangladeshboat discussision blog Dharmafly].
* [http://waferbaby.com/hussy waferbaby's Hussy] publie actuellement les liens en utilisant xFolk.
* [http://unalog.com unalog] publie actuellement tous les liens partagés (y compris les résultats de recherche) en utilisant xFolk.
* [http://smarking.com/ Smarking] publie actuellement tous les liens partagés (y compris les résultats de recherche) en utilisant xFolk.
* [http://de.lirio.us de.lirio.us] publie actuellement ses signets en utilisant xFolk (avec l'attribut de classe déprécié <code>extended</code> a lieu de <code>description</code>, voir [[xfolk-profile-fr| le XMDP]]).
* [http://dev.blogmarks.net/wiki/BlogSync blogmarks] exporte actuellement les signets vers les blogs en xFolk (défilez plus bas pour voir l'exemple d'export sur la page ; l'attribut de classe déprécié <code>extended</code> est utilisé au lieu de <code>description</code>, voir [[xfolk-profile-fr| le XMDP]]).
* [http://thecommunityengine.com The Community Engine] utilise xFolk (avec l'attribut de classe déprécié <code>extended</code> utilisé au lieu de <code>description</code>, voir [[xfolk-profile-fr| le XMDP]]) pour ses [http://thecommunityengine.com/home entrées principales] et pour ses [http://thecommunityengine.com/webcites signets republiés].
* [http://groovymother.com/links/ Groovy Links] est un blog de liens qui est balisé avec xFolk.
* [http://tommorris.org/blog/ Tom Morris] - les liens quotidiens del.icio.us sont marqués avec xFolk, [[hcard-fr|hCard]] et [[vote-links-fr|vote-links]].

=== Services de signets sociaux supplémentaires ===
Cet exemple illustre comment xFolk peut être appliqué à un service additionnel :

* [[xfolk-scuttle-fr| scuttle]]

=== Blogs de liens ===

Les services de signets sociaux sont seulement les exemples les plus récents de personnes publiant des liens. Les blogs de liens ont presque toujours existé depuis le début du blogging. Ils représentent en quelque sorte plus qu'un défi pour xFolk parce que leurs balisages tendent à Ãªtre moins sémantiques qu'au début. Les exemples suivants illustrent quelques défis particuliers et comment ils peuvent Ãªtre surmontés.

* [[xfolk-kottke | kottke]]
* [[xfolk-pollas | pollas]]
* [[xfolk-jacobian | jacobian]]
* [[xfolk-julian-bez | julian-bez]]

=== Spam ===
Quelques spammers sont en train d'ajouter des tags xFolk à leurs fermes à liens. (C'est probablement une mauvaise idée de lier vers ces sites). Par exemple :
* phontron.info

== Implémentations ==
Les implémentations suivantes ont été développées et elles génèrent ou utilisent xFolk. Si vous avez une implémentation xFolk, sentez-vous à l'aise pour l'ajouter en haut de cette liste. Une fois que la liste sera trop grosse, nous ferons une page wiki séparée.
* [http://bildu.net Bildu] un service de bookmarking social en Basque qui supporte xFolk (et aussi rel-tag).
* [http://bookmarks.excite.co.uk/ Excite Bookmarks] un service de bookmarking social qui supporte xFolk et rel-tag.
* [http://buzka.com Buzka], un service de signet social supporte maintenant xFolk
* [http://blip.tv Blip.tv], un site d'hébergement vidéo [http://blog.blip.tv/blog/2006/08/19/blip-supports-xfolk/ supporte maintenant xFolk].
* [http://www.s9y.org/ Serendipity], une application de Blogging/CMS motorisée par PHP a maintenant un [http://www.numblog.de/archives/241-Social-Bookmarks-Plugin-for-Serendipity.html plugin de signets sociaux] qui supporte xFolk.
* [http://claimid.com claimID] a implémenté xFolk pour les liens vers les personnes.
* [http://ma.gnolia.com ma.gnolia] supporte maintenant xFolk.
* [http://smarking.com/ Smarking.com] (un service de signet social) balise ses liens tagués avec xFolk ! truc : [http://3spots.blogspot.com/2006/05/social-bookmarking-smarking.html 3spots: Social + bookMARKING = Smarking] qui lui-mÃªme est un [[hreview-fr|hReview]].
* [http://blog.codeeg.com/2006/03/20/flock-tails-flocktails/ Flocktails] - port de l'extension Tails pour Flock 0.5.12 qui cherche les hCards, hCalendar, xFolk et hReview et les porte dans une barre supérieure à portée de main.
* [http://blog.codeeg.com/tails-firefox-extension/ Tails est une Extension Firefox] qui affiche la présence de microformats ([[hcard-fr|hCard]], [[hcalendar-fr|hCalendar]], [[hreview-fr|hReview]], [[xfolk-fr|xFolk]]) sur une page web.
* Bud Gibson et Mike Migurski [http://thecommunityengine.com/home/archives/2005/09/vegomatic_an_al.html ont écrit] [http://thecommunityengine.com/veg-o-matic veg-o-matic], un outil et service xFolk de reblogging.
* [http://inside.glnetworks.de/ Martin Rehfeld] a mis à jour le travail de [http://blogmatrix.blogmatrix.com/ David Janes] et produit un [http://inside.glnetworks.de/2006/06/05/microformats-have-arrived-in-firefox-15-greasemonkey-06/ script] [[Greasemonkey-fr|GreaseMonkey]] qui trouve beaucoup d'éléments microformats, y compris xFolk et [http://blog.davidjanes.com/mtarchives/2005_08.html#003379 fournit un menu en popup d'actions]. ''Ceci fonctionnera maintenant avec FireFox 1.5+/GreaseMonkey 0.6.4+.''
* [http://www.midgard-project.org/midcom-permalink-6416db7e1f0e297b4cf3dcc285702a8d net.nemein.bookmarks], le gestionnaire de signets dans [http://www.midgard-project.org/ Midgard CMS] utilise xFolk comme le format natif de production, avec un ajout <code>abbr class=posted</code> pour la date de publication et <code>abbr class=poster</code> pour l'utilisateur qui a ajouté le signet. Vor l'[http://bergie.iki.fi/links/ exemple]
* [http://de.lirio.us de.lirio.us] publie actuellement ses signets en utilisant xFolk 0.4 (l'attribut de classe <code>extended</code> est utilisé au lieu de <code>description</code>).
* [http://dev.blogmarks.net/wiki/BlogSync blogmarks] exporte actuellement les signets vers les blogs en xFolk 0.4 (scrollez vers le bas pour voir l'exemple d'exportation sur la page ; l'attribut de classe <code>extended</code> est utilisé au lieu de <code>description</code>).
* [http://pokkari.com/microformat/javadoc/ Sivitols] est une librairie Java pour les microformats. Actuellement seul le standard xFolk RC1 est implémenté mais le support microformat additionnel est planifié. (adapté à partir de [http://blog.blip.tv/blog/microformats/])

== Références ==
=== Références Normatives ===
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE]
* [[rel-tag-fr|rel-tag]]

=== Références Informatives ===
* [http://thecommunityengine.com/home/archives/xfolk articles about xFolk]
* [http://thecommunityengine.com/home/archives/tags/microformats articles about the business value of microformats]
* [http://gataga.com gataga social bookmark search engine]
* [http://johnvey.com/features/deliciousdirector/ an ajax based interface for del.icio.us]
* [http://en.wikipedia.org/wiki/Social_bookmarking social bookmarking defined at wikipedia]

=== Travaux similaires ===
* [[hreview-fr| hReview]]

== Chantier en cours ==
Bien que cette spécification ait récemment commencé à se stabiliser comme indiqué par la version RC1, c'est encore un chantier en cours. Si garantie, je suis prÃªt à aller vers plusieurs versions candidates pour parvenir à l'objectif de produire des entrées de signets plus généralement accessibles avec un format aussi léger que possible. Tous les changements depuis la dernière itération ont été motivés par l'expérience d'implémentations des développeurs tentant de parvenir à cet objectif. Des changements plus en profondeur seront aussi probablement motivés par les problèmes d'implémentation. Voir "directions futures" ci-dessous pour des possibilités supplémetaires de microformat.

=== Changements depuis xFolk 0.4 ===
La valeur de l'attribut de classe <code>extended</code> a été dépréciée en faveur de <code>description</code> pour mieux se conformer à d'autres usages de microformats et quelques requÃªtes durant l'implémentation. L'autre changement a été de permettre l'utilisation de plusieurs éléments de classe <code>extended</code> basés sur quelque cas d'utilisation découverts dans l'implémentation.

=== Directions futures ===
Il y a plusieurs extenstion qu'on pourrait imaginer pour xFolk. Fréquemment, ces extensions sont mieux abouties en combinant xFolk avec un autre microformat. Par exemple, on pourrait vouloir indiquer son évaluation de l'item mis en signet. Ceci pourrait Ãªtre réalisé en utilisant [[vote-links-fr| Vote Links]] ou [[hreview-fr | hReview]] avec xFolk.

On peut aussi imaginer d'étendre xFolk pour fournir des données conformes avec plusieurs APIs de services de signets sociaux, par exemple pour fournir tous les signets par tag. Ces APIs sont actuellement trop fluides pour la spécification de quelque type de standard. Les APIs et la fonctionnalité qu'elles fournissent représentent un moyen dont les services de signets sociaux et les méta-services peuvent eux-mÃªmes se différencier.

Un format compagnon appelé "xFolk definition" est en développement. "xFolk definition" fournira un moyen de définir explicitement les tags utilisés dans les signets sociaux.

=== Brainstorming ===
* [[xfolk-brainstorming-fr|xFolk brainstorming]]

== Discussions ==

=== Q&R ===
* Si vous avez quelque question à propos d'xFolk, regardez les [[xfolk-faq-fr|FAQ xFolk]], et si vous ne trouvez pas de réponses, ajoutez vos questions !

=== Problématiques ===
* SVP, ajoutez toute problématique avec la spécification au document séparé [[xfolk-issues-fr| xFolk issues]].

==Pages apparentées==
{{template:xfolk-related-pages-fr}}

[[Category:Draft Specifications]]
[[Category:xFolk]]

rel-home

2024-06-20T23:51:25Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:rel="home"}}
{{DraftSpecification}}
__TOC__

== Draft Specification 2005-12-07 ==
=== Editor/Author ===
[http://dannyayers.com Danny Ayers]

=== Copyright ===
{{MicroFormatCopyrightStatement2005}}

=== Patents ===
{{MicroFormatPatentStatement}}

== Abstract ==
Rel-Home is one of several [[MicroFormats]]. By adding <code>rel="home"</code> to a hyperlink, a page indicates that the destination of that hyperlink is the homepage of the site in which the current page appears. When the appropriate HTML Meta data profile is in use, the "home" type can be used alongside standard [http://www.w3.org/TR/html4/types.html#type-links Link Types].

Example usage :

<pre><nowiki>
<head>
...
<link href="http://technorati.com" rel="home" />
...
</head>
</nowiki></pre>

The rel value may also appear wherever an anchor link may appear, e.g.

<pre><nowiki>
<body>
...
<a href="http://technorati.com" rel="home">Home</a>
...
</body>
</nowiki></pre>

the author indicates that the linked page is the homepage of the site.

The linked page {{should}} exist. Use of an absolute URI is recommended.

== Scope ==
rel="home" is designed for site navigation purposes, as well as allowing some description of site structure to be derived from individual pages. Typical use might be in the archive pages of a weblog, pointing back to the front page.

== XMDP profile ==
<pre><nowiki>
<dl class="profile">
<dt id="rel">rel</dt>
<dd><p>
<a rel="help" href="http://www.w3.org/TR/html401/struct/links.html#adef-rel">
HTML4 definition of the 'rel' attribute.</a>
Here is an additional value.</p>
<dl>
<dt id="home">home</dt>
<dd>Indicates that the referred resource serves as the homepage,
of the site which includes the referring page.</dd>
</dl>
</dd>
</dl>
</nowiki></pre>

==Examples in the Wild==
This section is '''informative'''.

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

* [http://www.my-warehouse.de the my-Warehouse shopsystem] implements rel-home into the breadcrumb.
* [http://www.sunfactory.fr/en/gift-ideas/ Sun Factory] implements rel-home into the breadcrumb.
* http://chrisruppel.com uses rel-home as a link in the <head>
* [http://www.cleanertoday.com Cleaner Today] uses multiple implementations: 1) [http://www.cleanertoday.com/Moth-Traps-by-Catchmaster-s/85.htm Moth Trap] page uses rel-home in <head> 2) [http://www.cleanertoday.com/Spider-traps-s/86.htm Spider Traps] page uses rel="home" on Corner Logo Link & "Home" link in the footer.
* [http://www.jdclark.org/ www.jdclark.org] uses rel-home on virtually all web pages within the domain and its sub-domains (for example, please see [http://www.jdclark.org/card Jordan Clark's profile]).
* Tantek.com posts (e.g. [http://tantek.com/2011/220/b1/web-actions-a-new-building-block Web Actions: Identifying A New Building Block For The Web]) use rel="home" as part of the link to the site's alternate feed as such: <nowiki><link rel="home updates alternate" type="application/atom+xml" href="http://tantek.com/updates.atom" /></nowiki> to indicate that the link is an ''alternate'' for a page that is also the ''home'' for the current page, rather than an alternate for the current page.
* [http://www.fastquotes.co.za fastQuotes] uses rel-home on every page in multiple locations.
* [http://www.9thCO.com 9thCO] uses rel="home" in <head>. 9thCO follows all web standards and is happy to embrace the new Rel-Home microformat specification.
* [http://lllooolll.com Lol x3] implemented rel=home in the head sitewide, together with other rel's and hreflang.

== Implementations ==
This section is '''informative'''.
The following implementations have been developed which either generate or parse rel-home links.

''Ed. : links to follow''

* Opera browser supports rel="home"
* [http://cdn.mozdev.org/linkToolbar/ FireFox Link Toolbar] - need to confirm
* [https://addons.mozilla.org/firefox/1324/ cmSiteNavigation Toolbar] - Firefox Extension that supports rel="home" and rel="directory"

== References ==

=== Normative References ===
* [http://www.w3.org/TR/REC-html40/ HTML 4]
* [http://www.w3.org/TR/xhtml1/ XHTML 1]
* [http://gmpg.org/xmdp/ XMDP]
* RFC 3986 specifies URL syntax

=== Informative References ===
* [http://diveintoaccessibility.org/day_9_providing_additional_navigation_aids.html Dive Into Accessibility] (Mark Pilgrim)

''Ed. : need to track down previous discussions, e.g. re. Opera''

== Discussions ==

=== Q&A ===
* If you have any questions about rel-home, check the [[rel-faq|rel FAQ]], and if you don't find answers, add your questions!

=== Issues ===
* Please add any issues with the specification to the separate [[rel-home-issues|rel-home issues]] document.

=== Brainstorming ===
If this section gets too large (and is not just incorporated into the draft), it can be moved to [[rel-home-brainstorming]].

==== use with rel-alternate ====
===== rel-alternate and type =====
Many blog post permalink pages have feed autodiscovery links that link from the permalink page via a link element to the feed for the site using just rel="alternate".

This is semantically incorrect as the feed is an alternate for the *site*, not the permalink page.

rel="home" could (and should) be used with [[rel-alternate]] to link from a permalink page to the feed for the site (home page). e.g. on tantek.com permalink pages (e.g. [http://tantek.com/2011/220/b1/web-actions-a-new-building-block recent post]), here's a simplified version of the markup:
<syntaxhighlight lang="html">
<link rel="home alternate" type="application/atom+xml" href="../updates.atom" />
</syntaxhighlight>

This way a feed reader / indexer / search engine knows that the link represents an ''alternate'' for the ''home'' page relative to the current page, not an alternate for the page itself.

There is one known exception which is that if the alternate link is a feed to the ''comments'' on that post, then that would make sense as an actual alternate representation of the post permalink page.

Implementations (consuming parsers) could thus treat these two types of 'alternate' links differently to provide the user a better experience, e.g. with separate buttons for:
* Subscribe to this site
* Subscribe to the comments on this post

===== rel-alternate and hreflang =====
It might make sense for links from pages of one language anywhere on a site when linking to the home page of another language on a site to use rel-alternate with rel-home and hreflang together.

To see if it's worth specifying that however, we'd need to document real world examples of pages linking this way first.

===== FAQ home alternate =====
Frequently asked questions about rel="home alternate" (likely merits inclusion in [[rel-faq]]).
<div class="discussion">
* Doesn't rel="home alternate" mean it's the home page ''and'' it's an alternate independently? (as asked [http://krijnhoetmer.nl/irc-logs/microformats/20110810#l-84], [https://twitter.com/tabatkins/status/101391569160114176], [https://twitter.com/apparentlymart/status/101481300086620161])
** No. That's not [http://dev.w3.org/html5/spec/semantics.html#attr-link-rel how rel works]. Rel values combine. E.g. <code>[http://www.w3.org/TR/html4/present/styles.html#h-14.3.1 rel="alternate stylesheet"]</code> has worked this way for over a decade. Rel values also combine with other attributes, e.g. use <code>rel="alternate" media="handheld"</code> on a link to a separate mobile-specific version of a page. [[User:Tantek|Tantek]] 20:56, 10 August 2011 (UTC)
*** This seems to contradict the spec: "if a single link element has a rel attribute with the value next stylesheet, it creates both a hyperlink (for the next keyword) and an external resource link (for the stylesheet keyword)" implying that they are independant and not related. -- [[User:Singpolyma|Singpolyma]] 21:43, 10 August 2011 (UTC)
**** That's a ''non-normative NOTE'' documentation of what <code>rel="next stylesheet"</code> and (subsequently in a non-normative example) <code>rel="author license"</code> mean, and thus (being non-normative) not something you can derive any implications from. The ''normative'' language of the spec says: <strong>"exactly which and how many links are created depends on the keywords given in the rel attribute"</strong> which is precisely correct and provides us the flexibility to define combinations as having meanings. (Note that it does NOT say: create one link per rel value, which it would if the rel values were actually independent, which you can't say in general that they are.) -- [[User:Tantek|Tantek]] 21:54, 10 August 2011 (UTC)
</div>

===== discuss home alternate =====
Go to [[irc|the #microformats IRC channel on Freenode]] to discuss rel="home alternate". Additionally if you have a specific opinion, of support/rejection/neutrality and optionally reasons why, feel free to record your (+1/-1) etc. here:
<div class="discussion">
* +1 [[User:Tantek|Tantek]] - as [http://krijnhoetmer.nl/irc-logs/microformats/20110810#l-61 proposed/discussed in IRC]
* +1 [http://krijnhoetmer.nl/irc-logs/microformats/20110810#l-79 DGlazkov] - "home alternate" sounds reasonably intuitive
* +1 [[User:Kevin Marks|Kevin Marks]] though need to check behavior in browsers that support rel-home on link
* -1 [[User:SEOTOC | Oleg G.]] even HTML5 holding rel-home on draft
* ...
</div>
==== use with lang ====
* Edit: Sabin Simionescu: I have a proposal:
<syntaxhighlight lang="html">
<link rel="home" href="http://www.example.com'''/" lang="en"''' />
<link rel="home" href="http://www.example.com'''/de/" lang="de"''' />
</syntaxhighlight>

Multilingual sites have multiple home pages. I have looked closely at this rel-home specification, and while it looks very good for SEO applications, users would benefit from a language option as well.

My proposal is to specify all ACTIVE languages of the site using rel-home.

<div class="discussion">
* '''Proposal misunderstands "lang" attribute.''' Instead of <code>lang</code>, use the <code>hreflang</code> attribute to specify the language of the destination of an href (e.g. on <code><link></code> and <code><a></code> tags). The <code>lang</code> attribute is only for the contents of the element itself, which in the link tag examples above, would only apply to the <code>title</code> attribute if any. - [[User:Tantek|Tantek]] 01:00, 24 December 2012 (UTC)
* '''This proposal is likely unnecessary.''' Use [[rel-alternate#alternate_language_versions|rel="alternate" with hreflang]] to link to different language versions of a page. - 01:00, 24 December 2012 (UTC)
** '''Needs URLs to real world examples of such linking behavior.''' Using rel-alternate with rel-home and hreflang together might make sense for links from pages of one language anywhere on a site to link to the home page of another language on a site. To see if it's worth specifying that however, we'd need to document real world examples of pages linking this way first. - [[User:Tantek|Tantek]] 01:00, 24 December 2012 (UTC)
</div>

== see also ==
* [[rel-alternate]], in particular [[rel-alternate#special_combinations|special combinations]]
* [[existing-rel-values]]
* [[rel-faq]]

[[Category:Draft Specifications]]
[[Category:rel-home]]

hreview-v0.3

2024-06-20T23:50:03Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:hReview 0.3}}

This is previous ''snapshot'' of the [[hReview]] specification.

Please see the latest [[hReview]] draft.

{{DraftSpecification}}

[[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.

== Microformats Draft Specification 2006-02-22 ==
<div class="vcard">
;<span class="role">Editor</span>
:<span class="fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="url">http://tantek.com/</span>, and before at [http://technorati.com Technorati, Inc.])
</div>
; Authors
: [[User:Tantek|Tantek Çelik]] (affiliations above)
: <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])

[[hreview#Copyright|copyright]] and [[hreview#Patents|patents]] statements apply.

== Status ==
hReview 0.3 is a microformats.org draft specification. Public discussion on hReview takes place on [[hreview-feedback]], the #microformats [[irc]] channel on irc.freenode.net, and [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 ==
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|hReview feedback]] page.

{{rfc-2119-intro}}

=== 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|hCard]] and [[hcalendar|hCalendar]] standards.

=== Schema ===
The hReview schema consists of the following:

* hReview ('''<code>hreview</code>''')
** '''<code>version</code>'''. optional. text.
** '''<code>summary</code>'''. optional. text.
** 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>reviewer</code>'''. optional. '''[[hcard|hCard]]'''.
** '''<code>dtreviewed</code>'''. optional. ISO8601 absolute date time. ([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>description</code>'''. 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:

'''version''':: This optional property permits hReview publishers to specify a particular version of hReview that their content uses. By omitting this property, 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 property 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 property for this specification is "0.3".

'''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''':: 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 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 property when present {{must}} provide an [[ISO-8601|ISO8601]] absolute date time of when the review was written or otherwise authored. This property {{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 {{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, plusses and minusses) {{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. 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}} 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 <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''':: 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>version, 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 ===

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

* For any "url", use <code><a class="url" href="...">...</a></code> inside the element with the class name 'hreview' in hReview.
* And for "photo", use <code><img class="photo" src="..." alt="Photo of ..." /></code>

* Ratings are often presented either as a set of images or characters, e.g. "***". For these, the <code><abbr></code> element is particularly useful, as such characters are an abbreviation for the precise rating, e.g. <code><abbr class="rating" title="3.0">***</abbr></code>. 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. <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 HTML 'lang' attribute as specified.

=== Human vs. Machine Readable ===
If an <code><abbr></code> element is used for a property, then its '<code>title</code>' 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 <code><img /></code> 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 <code>src="..."</code> attribute provides the property value.
# For other properties, the <code><img /></code> element's '<code>alt</code>' attribute is the value of the property.

=== Object Includes ===

hReview 0.3 includes support for the object [[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|hReview]]? Use the [http://microformats.org/code/hreview/creator hReview creator] to write a review and publish it on your blog.

=== Restaurant reviews ===

Here is an example of a simple online restaurant review:

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

Adding hReview to this review is quite simple:

<syntaxhighlight lang="html">
<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> -
<abbr class="dtreviewed" title="2005-04-18T23:00-07:00">April 18, 2005</abbr></span>
<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>
</syntaxhighlight>

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<br />
'''Crepes on Cole is awesome'''<br />
Reviewer: Tantek - April 18, 2005<br />

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<br />
Food eaten: Florentine crepe<br />

==== 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:

<syntaxhighlight lang="html">
<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>
Review (<a href="http://microformats.org/wiki/hreview">
hReview v<span class="version">0.3</span></a>)
by <span class="reviewer vcard"><span class="fn">anonymous</span></span>,
<abbr class="dtreviewed" title="2005-04-28T21:30-07:00">April 28th, 2005</abbr>.
</div>
</syntaxhighlight>

With an accompanying CSS style sheet like:

<syntaxhighlight lang="html">
a.url { display:block }
ul { margin:1em 0; padding:0 }
ul li { display:inline }
</syntaxhighlight>

This hReview could be presented similar to the original text:

Cafe Borrone<br />
1010 El Camino Real, Menlo Park, CA 94025, +1-650-327-0830;<br />
[http://cafeborrone.com/ cafeborrone.com]<br />
<br />
[http://en.wikipedia.org/wiki/Food Food: 18/30];
[http://flickr.com/photos/tags/Ambience Ambience: 19/30];
[http://en.wikipedia.org/wiki/Service Service: 15/30];
[http://en.wikipedia.org/wiki/Price Price: $$...]<br />

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.

Review ([http://microformats.org/wiki/hreview hReview v0.3]) by anonymous, April 28th, 2005.

=== Product review ===
Here is an example of a product review:

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

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:

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

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.

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

With hReview:

<syntaxhighlight lang="html">
<div class="hreview">
<span class="reviewer vcard">
<span class="fn">anonymous</span>,
<abbr class="dtreviewed" title="2005-04-18">April 18th, 2005</abbr>
</span>
<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>
</syntaxhighlight>

Which could be presented like this:

anonymous, April 18th, 2005<br />
Ying Xiong (HERO)<br />
Rating: 4 out of 5<br />

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 [[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].

== References ==
=== Normative References ===
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE]
* [http://gmpg.org/xmdp/ XMDP]
* [[hcard|hCard]]
* [[hcalendar|hCalendar]]
* [[rel-tag]]
* [http://www.ietf.org/rfc/rfc2119.txt RFC2119]
* [http://www.ietf.org/rfc/rfc3986.txt RFC3986]
* [http://www.ietf.org/rfc/rfc4287.txt RFC4287] (Atom 1.0)

=== Informative References ===
* [http://www.w3.org/TR/REC-CSS1 CSS1]
* ISO.8601.1988 [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.
* [http://www.w3.org/TR/1998/NOTE-datetime-19980827 W3C NOTE-datetime-19980827]
* [http://www.ietf.org/rfc/rfc3667.txt RFC3667]
* [http://www.ietf.org/rfc/rfc3668.txt RFC3668]
* [http://www.w3.org/Consortium/Patent-Policy-20040205/ W3C Patent Policy]
* [http://local.yahoo.com/details?id=21359628 Crepes on Cole reviews on Yahoo! Local]
* Other reviews efforts. See [[reviews-formats]].
* Contributed from http://developers.technorati.com/wiki/hReview.

==== Similar Work ====
* [[hlisting-proposal|hListing]]
* [[xoxo|XOXO]]

== Copyright ==
{{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}}

== 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.2 ===
The following changes have been made in hReview v0.3 over [[hreview-v0.2|hReview v0.2]]:

Normative changes:
# MUST (instead of SHOULD) use [[hcard|hCard]] for the item description of a business or person
# "reviewer" changes
## Made reviewer *optional* per feedback from Ryan King and Mark Nottingham
## If reviewer is absent from the hReview, then look outside the hReview, in the context of the page, for the reviewer. If there is no "reviewer" outside either, then use the author information according to the containing document language (e.g. <code><nowiki><address></nowiki></code> for HTML pages) as the reviewer.
## MUST (instead of SHOULD) use [[hcard|hCard]] to represent reviewer information
# "dtreviewed" changes
## Made dtreviewed *optional* per feedback from Ryan King and Mark Nottingham
## 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 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).
# SHOULD use [[hcalendar|hCalendar]] to represent an item of 'type' 'event'
# Added one decimal digit of precision to ratings' numerical values based on publisher experience.
# Use [http://microformats.org/wiki/hcard#Value_excerpting the "value" construct from hCard] (as it is used in "tel" properties for example) to more explicitly markup the rating value when also providing (marking up) the best/worst of a rating.
# Added [[rel-license]] to indicate the license of the hReview as a whole.
# Permit tags inside ratings to denote rated tags, the same as ratings inside tags per suggestion from Eran Globen.
# Add [[include-pattern]] support to allow multiple reviews for the same item to not repeat the item info.

Informative changes (several, but in particular):
# Note that scalar/rated tags would ideally use a tag space that explain the ratings for that tag. E.g. to explain what Food:18/30 means.
# Updated examples accordingly.

== Articles ==
This <span id="Further_Reading">section</span> is <strong>informative</strong>.

See: [[hreview-articles]].

== Related Pages ==
{{hreview-related-pages}}

== Translations ==
Read the hReview draft specification in additional <span id="languages">languages</span>:
* [[hreview-fr|français]]
* [[hreview-ja|日本語]]

hreview

2024-06-20T23:48:03Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{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 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.

== 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 ==
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|hReview feedback]] page.

{{rfc-2119-intro}}

=== 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|hCard]] and [[hcalendar|hCalendar]] standards.

=== Schema ===
The hReview schema consists of the following:

* hReview ('''<code>hreview</code>''')
** '''<code>summary</code>'''. optional. text.
** 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>reviewer</code>'''. optional. '''[[hcard|hCard]]'''.
** '''<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>description</code>'''. 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: <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''':: 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 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 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 {{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 <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''':: 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 ===

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

* For any "url", use <code><a class="url" href="...">...</a></code> inside the element with the class name 'hreview' in hReview.
* And for "photo", use <code><img class="photo" src="..." alt="Photo of ..." /></code>

* Ratings are often presented either as a set of images or characters, e.g. "***". For these, the <code><abbr></code> element is particularly useful, as such characters are an abbreviation for the precise rating, e.g. <code><abbr class="rating" title="3.0">***</abbr></code>. 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. <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 HTML 'lang' attribute as specified.

=== Human vs. Machine Readable ===
If an <code><abbr></code> element is used for a property, then its '<code>title</code>' 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 <code><img /></code> 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 <code>src="..."</code> attribute provides the property value.
# For other properties, the <code><img /></code> element's '<code>alt</code>' 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|hReview]]? Use the [http://microformats.org/code/hreview/creator hReview creator] to write a review and publish it on your blog.

=== Restaurant reviews ===

Here is an example of a brief online restaurant review:

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

Adding a few elements & class names makes the review into an hReview:

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

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<br />
'''Crepes on Cole is awesome'''<br />
Reviewer: Tantek - April 18, 2005<br />

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<br />
Food eaten: Florentine crepe<br />

==== 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:

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

With an accompanying CSS style sheet like:

<syntaxhighlight lang="html">
a.url { display:block }
ul { margin:1em 0; padding:0 }
ul li { display:inline }
</syntaxhighlight>

This hReview could be presented similar to the original text:

Cafe Borrone<br />
1010 El Camino Real, Menlo Park, CA 94025, +1-650-327-0830;<br />
[http://cafeborrone.com/ cafeborrone.com]<br />
<br />
[http://en.wikipedia.org/wiki/Food Food: 18/30];
[http://flickr.com/photos/tags/Ambience Ambience: 19/30];
[http://en.wikipedia.org/wiki/Service Service: 15/30];
[http://en.wikipedia.org/wiki/Price Price: $$...]<br />

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 ===
Here is an example of a product review:

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

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:

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

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.

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

With hReview:

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

Which could be presented like this:

anonymous, April 18th, 2005<br />
Ying Xiong (HERO)<br />
Rating: 4 out of 5<br />

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 [[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 ==
=== Normative References ===
* [http://w3.org/html5 HTML5]
* [http://gmpg.org/xmdp/ XMDP]
* [[hcard|hCard]]
* [[hcalendar|hCalendar]]
* [[rel-tag]]
* [http://www.ietf.org/rfc/rfc2119.txt RFC2119]
* [http://www.ietf.org/rfc/rfc3986.txt RFC3986]
* [http://www.ietf.org/rfc/rfc4287.txt RFC4287] (Atom 1.0)

=== Informative References ===
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE]
* [http://www.w3.org/TR/REC-CSS1 CSS1]
* 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.
* [http://www.ietf.org/rfc/rfc3667.txt RFC3667]
* [http://www.ietf.org/rfc/rfc3668.txt RFC3668]
* [http://www.w3.org/Consortium/Patent-Policy-20040205/ W3C Patent Policy]
* [http://local.yahoo.com/details?id=21359628 Crepes on Cole reviews on Yahoo! Local]
* Other reviews efforts. See [[reviews-formats]].
* Contributed from http://developers.technorati.com/wiki/hReview.

==== Similar Work ====
* [[hlisting-proposal|hListing]]
* [[xoxo|XOXO]]

== Copyright ==
{{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}}

== 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|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 <span id="Further_Reading">section</span> is <strong>informative</strong>.

See: [[hreview-articles]].

== 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|日本語]]

hresume

2024-06-20T23:39:19Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:hResume}}
{{latest|h-resume}}
{{DraftSpecification}}
hResume is a microformat for publishing resumes and CVs. hResume is one of several open microformat standards suitable for embedding in HTML, XHTML, Atom, RSS, and arbitrary XML.

Want to get started with writing an hResume? Use the [http://recherche.telecom-bretagne.eu/labo_communicant/dev_labc/hResumeCreator.php hResume Creator] to create your hResume and publish it, or follow the hResume authoring tips to add hResume markup to your web page or blog.

==Microformats Draft Specification==

; Editors: <span class="h-card">[http://tantek.com Tantek Çelik]</span> and <span class="h-card">[http://glennjones.net Glenn Jones]</span>
; Previous Editor & Author: <span class="h-card">[http://theryanking.com Ryan King]</span>
; Acknowledgments: See [http://microformats.org/wiki/hresume#Acknowledgements acknowledgments].

Microformats [http://microformats.org/wiki/hresume#Copyright copyright] and [http://microformats.org/wiki/hresume#Patents patents] statements apply.

{{rfc-2119-intro}}

== Status ==
Draft, version 0.1.

== Introduction ==
=== Semantic XHTML Design Principles ===
{{SemanticXHTMLDesignPrinciples}}

== Format ==
=== In General ===
The hResume format is based on a set of fields common to numerous resumes published today on the web. Where possible field names have been chosen and reused from preexisting microformats.

=== Schema ===
The hResume schema consists of the following:

* hResume
** summary. optional. text.
** contact info. required. {{must}} use [[hcard|hCard]]; {{should}} use <code class="element"><address></code> + [[hcard|hCard]].
** experience. optional. One or more [[hcalendar]] events with the class name '<code class="class-name">experience</code>', with an embedded [[hcard|hCard]] indicating the job title, name of company, address of company etc.
** education. optional One or more [[hcalendar]] events with the class name '<code class="class-name">education</code>', with an embedded [[hcard|hCard]] indicating the name of school, address of school etc.
** skills. optional. phrases or keywords using the [[rel-tag]] microformat with the class name '<code class="class-name">skill</code>'.
** affiliations. optional. the class name <code class="class-name">affiliation</code> along with an [[hcard]] of the organization
** publications. optional. One or more citations. Use cite tag.

=== Field details ===
The fields of the hResume schema represent the following:

* '''<code class="class-name">hresume</code>''':: root class name
* '''<code class="class-name">summary</code>''':: The class name <code class="class-name">summary</code> is used to mark up an overview of qualifications and objectives.
* '''contact''':: Current contact info in an [[hCard]]; {{should}} use <code class="element"><address></code> with [[hCard]] when possible.
* '''<code class="class-name">education</code>''':: the class name '<code class="class-name">education</code>' is applied to an [[hcalendar]] event.
* '''<code class="class-name">experience</code>''':: the class name '<code class="class-name">experience</code>' is applied to an [[hcalendar]] event. Job titles/positions should use an [[hCard]].
* '''<code class="class-name">skill</code>''':: An hResume may be tagged using the [[rel-tag]] microformat and the '<code class="class-name">skill</code>' class name.
* '''<code class="class-name">affiliation</code>''':: The class name <code class="class-name">affiliation</code> is used along with an [[hcard]] of the organization
* '''publications''':: just use <code class="element"><cite></code>. When there is a [[citation]] microformat, then that can be used in combination with the cite element to further markup the components of the citation.

=== XMDP Profile ===
* [[hresume-profile]] (@TODO)

=== Notes ===
This section is informative.

*...

== Examples ==
=== Summary ===
An example summary:

<syntaxhighlight lang="html">
<p class="summary">
I have 10 years experience with all Web 2.0 technologies– I've been working with Ajax since 1996,
designing with pastels while others will still using tiled background images and frames...
</p>
</syntaxhighlight>

=== Contact ===
<syntaxhighlight lang="html">
<address class="vcard">
<span class="fn">Pedro Sanchez</span>
<span class="adr">
<span class="street-address">123 Fake St.</span>
<span class="locality">Preston</span>, <span class="region">Idaho</span> <span class="postal-code">83263</span>
</span>
<span>Email: <a class="email" href="mailto:joe@example.com">pedro@vote-for-pedro.com</a></span>
<span>Homepage: <a class="url" href="http://vote-for-pedro.com/">vote-for-pedro.com</a></span>
<span>Phone: <span class="tel">+01.208.555.4567</span></span>
</address>
</syntaxhighlight>

=== Education ===
<syntaxhighlight lang="html">
<ol class="vcalendar">
<li class="education vevent">
<div class="summary vcard">
<a class="url fn org" href="http://www.example.edu/">Preston High School</a>
<div class="adr">
<span class="locality">SomeCity</span>,
<abbr class="region" title="Alaska">AK</abbr>
</div>
</div>
(<abbr class="dtstart" title="2001-01-24">2001</abbr> - <abbr class="dtend" title="2005-05-25">2005</abbr>)
</li>
...
</syntaxhighlight>

=== Experience ===
==== Basic ====
A basic experience event:

<syntaxhighlight lang="html">
<ol class="vcalendar">
<li class="experience vevent">
<span class="summary">President</span>,
<span class="location">Preston High School</span>,
<abbr class="dtstart" title="2004-09-01">May 2004</abbr> - <abbr title="2005-05-25">present</abbr>
</li>
...
</syntaxhighlight>

==== Job Titles ====
To express one or more job titles/positions in the same experience event you should use one or more [[hcard|hCard]]s. hCard requires the <code class="class-name">fn</code> ("formatted name") field, but it isn't customary to repeat your name for every job title you mark up in [[hResume|hresume]]. So, you may use an <code class="element"><object></code> and the class name '<code class="class-name">include</code>' with a reference to the <code class="class-name">fn</code> somewhere else on the page.

Currently, the recommended way to reference includes within microformats is to use a hyperlink with class="include". See [[include-pattern|include-pattern]] for details.

For example, this hCard refers to another hCard:

Using <code><a></code>:
<pre>
<span class="vcard">
<a href="#pedro-name" class="include" title="Pedro Sanchez"></a>
<span class="org">Preston High School</span>
<span class="title">Class President</span>
</span>
</pre>

Using <code><object></code>:
<pre>
<span class="vcard">
<object data="#pedro-name" class="include"></object>
<span class="org">Preston High School</span>
<span class="title">Class President</span>
</span>
</pre>

Where "<code class="attr-value">pedro-name</code>" is the id attribute value of the "<code class="mf-prop">fn n</code>" element of the contact hCard at the top of the page, e.g. (shown here as a verbose hCard for purposes of illustration that the reference may be to a subtree, not just a text node):

<syntaxhighlight lang="html">
<address class="vcard">
<span class="fn n" id="pedro-name">
<span class="given-name">Pedro</span>
<span class="family-name">Sanchez</span>
</span>
</address>
</syntaxhighlight>

This method of hCard property indirection via an object element [[include-pattern|has been generalized]] to apply to any/all string/text properties in hCard.

Note: the object data attribute {{must}} be a local ID reference. External references (which would require a consuming application to load an external resource) are not supported by this method.

=== Skills ===
Some sample skills tags:
<syntaxhighlight lang="html">
I have skills in <a class="skill" rel="tag" href="http://en.wikipedia.org/wiki/Bow_%28weapon%29">bow hunting</a>
and <a class="skill" rel="tag" href="http://en.wikipedia.org/wiki/Nunchucks">nunchucks</a>.
</syntaxhighlight>

=== Affiliations ===
<syntaxhighlight lang="html">
<span class="affiliation vcard"><span class="fn org">National Honor Society</span></span>
</syntaxhighlight>

=== Publications ===
<syntaxhighlight lang="html">
<cite>Breeding Ligers for Fun and Magic</cite>, Idaho Press, 2004.
</syntaxhighlight>

== Examples in the wild ==
See [[hresume-examples-in-wild]]

== Implementations ==
This section is '''informative'''.

The following implementations have been developed which either generate or parse hResumes. If you have an hResume 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 like [[hresume-implementations]].

* [http://ben.balter.com/2010/09/12/wordpress-resume-plugin/ WP Resume] is an out-of-the-box solution to publish your resume on your WordPress site and outputs the resume in an hResume compatible template.

* [http://www.cvmatch4jobs.com/ cvmatch4jobs] has implemented hResume import for publicly published CV's. A Career site for 3 UK building and proprety magazines from publishers UBM. 19 Jan 2010.

* [http://careercv.mad.co.uk/ CareerCV] has implemented hResume import for publicly published CV's. A Career site for major UK design magazines from publishers Centaur Communications. 19 Jan 2010.

* [http://lab.madgex.com/hresume/ Madgex] has implemented hResume to Microsoft Word and PDF conversion API. 13 Dec 2009.

* [http://jobs.guardian.co.uk/profile/ Guardian Jobs] has implemented hResume import for publicly published CV's. 4 Sep 2009.

* [http://www.yiid.com/ YIID - Your Internet Identity] supports importing of hResumes (e.g. here is the result of an import: http://pfefferle.yiid.com/cv [requires login] via @pfefferle)

* [[Resume.app]]

* [http://www.xing.com/ Xing] generates hResume for all Public Profiles. [http://www.xing.com/profile/Matthias_Pfefferle Xing Public Profile Example].

* [http://linkedin.com LinkedIn] generates hResume for all Public Profiles. [http://www.linkedin.com/in/steveganz LinkedIn Public Profile Example].

* [http://www.antix.co.uk Anthony Johnston] has implemented hResume (Creation and Import) in the [http://cv.antix.co.uk Antix CV Builder], an example resume using this site can be found [http://cv.antix.co.uk/ant here]
** The example resume is ''invalid''; job titles are marked with an hCard that is missing a "fn" (either directly or via object). --[[User:Gazza|Gazza]] 04:23, 1 May 2007 (PDT)
*** This is fixed now --[[User:Antix|Ant]] 00:38, 8 Dec 2007 (GMT)

* The [http://spurinc.com Spur] team has created an hResume WordPress plugin located at [http://hresume.weblogswork.com/?page_id=3 hResume Plugin]. See an example of the hResume markup [http://hresume.weblogswork.com/?page_id=6 here]. Neat feature of the hResume plugin is that it automatically creates a new page for the resume - no cutting and pasting...

* Spur also created a standalone hResume Creator located at [http://hresume.weblogswork.com/hresumecreator/ hResume Creator]. The creator will generate hResume markup ready to cut and paste into your webpage.

== Copyright ==
* [[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.
* [[RyanKing]]: I release all of my contributions to the public domain.

Per the above, and the public domain release on the author, [[User:RyanKing|RyanKing]]'s, user page this specification is released into the public domain.

{{MicroFormatPublicDomainContributionStatement}}

== Patents ==
{{MicroFormatPatentStatement}}

== References ==
=== Normative References ===
* [[hcard|hCard]]
* [[hcalendar|hCalendar]]
* [[include-pattern|include pattern]]
* [http://www.w3.org/TR/REC-html40/ HTML 4]
* [http://www.w3.org/TR/xhtml1/ XHTML]
* [http://gmpg.org/xmdp/ XMDP]
* [[rel-tag| Rel-Tag]]
* [[rfc-2119]]
* @TODO

=== Informative References ===
* @TODO

== Acknowledgements ==
=== Concept ===
* [http://theryanking.com/ Ryan King] ([http://technorati.com Technorati])
* [http://tantek.com/ Tantek Çelik] ([http://technorati.com Technorati])
* James Levine ([http://simplyhired.com Simply Hired])
* [http://epeus.blogspot.com/ Kevin Marks] ([http://technorati.com Technorati])

== Related Pages ==
{{hresume-related-pages}}

== Further Reading ==
* See also [http://www.technorati.com/cosmos/referer.html blogs discussing this page].
* [http://www.ablognotlimited.com/articles/getting-semantic-with-microformats-part-6-hresume/ Getting Semantic With Microformats, Part 6: hResume] by Emily Lewis

[[Category:Draft Specifications]]
[[Category:hResume]]

hrecipe

2024-06-20T23:35:28Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:hRecipe 0.22}}
{{latest|h-recipe}}
{{Template:DraftSpecification}}
{{TOC-right}}
http://www.livingathome.de/test/recipe/hRecipe.png

[[recipe|hRecipe]] is a simple, open, distributed format, suitable for embedding information about recipes for cooking in (X)HTML, Atom, RSS, and arbitrary XML. hRecipe is one of several [[microformats]] open standards. This page and Microformat is in the public domain.

== hRecipe Microformat Draft Specification ==

=== Editor ===
* [[User:ThomasLoertsch | Thomas Lörtsch]]

=== Authors ===
* [[User:Phae|Frances Berriman]]
* [[User:BenWard|Ben Ward]]
* [[User:TobyInk|Toby Inkster]]

=== Contributors===
[[User:AndyMabbett|Andy Mabbett]], [[User:Phae|Frances Berriman]], [[User:IamCam|Cameron Perry]], [[User:JohnLeMasney|John LeMasney]], [[User:Tantek|Tantek Çelik]], [[User:SudarshanP|SudarshanP]], [[User:CiaranMc|Ciaran McNulty]], [[User:LeeJordan|Lee Jordan]], [[User:RobertBachmann|Robert Bachmann]], [[User:JeffMcNeill|jeffmcneill]], [[User:ManuSporny|Manu Sporny]], [[User:RyanKing|Ryan King]], HollyMarieKoltz, Straup, [[User:ChristopheDucamp|Christophe Ducamp]], Mercman, [[User:Yde|Yde]], [[User:AmeerDawood|Ameer Dawood]], Scottk, [[User:Lee_Jordan|Lee Jordan]], MonroAlmon, EstevaoSamuel, [[User:Brian|Brian Suda]], SteveL, JohnLeMasney,

Microformats [[#Copyright]] and [[#Patents]] statements apply.

== Introduction ==

The hRecipe microformat is designed for the mark-up of instructions for creating meals, drinks or food-based items.

It is difficult for a browser to extract semantic information about a recipe described on a web page. Metadata such as author and name and details such as ingredients, method, preparation time etc provide relevant information about the recipe.

Having such information marked up can provide a number of benefits to the viewer. If a web browser understands that a particular web page contains a recipe with specific characteristics, it can produce richer interactions. For example, specific searches may be performed for ingredients or authors via general search services such as Google and Wikipedia. Additionally, classification by crawlers can become more accurate. If there are 20 recipes found on a page, and they all contain a certain ingredient, it can be assumed that the page is not only about cooking, but also about that particular ingredient.

In order to enable and encourage the sharing, distribution, syndication, and aggregation of recipes, the authors propose the hRecipe microformat, an open standard for distributed recipe metadata. The authors have researched both numerous [[recipe-examples]] in the wild and earlier attempts at [[recipe-formats]], and have designed hRecipe around a simple minimal schema for recipe content. Feedback is encouraged on the [[recipe-feedback|hRecipe feedback]] page.

=== Inspiration and Acknowledgments ===

Many thanks to the various individuals that did research and proposed ideas and discussion related to the hRecipe-format and recipes in general.

=== Scope ===

hRecipe is a format to annotate descriptions and lists of ingredients for the preparation of food and meals. Recipes consistently share several common properties. hRecipe has been based on this minimal common subset.

=== Out of scope ===

Recipes that are not for stuff that's meant to be eaten by humans are out of scope.

== Format ==

{{rfc-2119-intro}}

=== In General ===
The hRecipe format is based on a set of properties common to numerous recipe sites and formats in use today on the web. Where possible property names have been chosen based on those defined by related microformat standards.<br>
Some properties are marked ''experimental'' since they exceed the minimum set of properties needed to describe a recipe but still are very commonly used on the web. It's not sure if they are relevant enough for inclusion in the format. Implementation and general uptake of these properties will be observed and inform further decisions. So their use is not at all discouraged - but use them with care and be prepared for their eventual removal from the final spec.

=== Schema ===
The hRecipe schema consists of the following properties:

* '''hrecipe'''
** '''fn'''. required. text. the name of the recipe.
** '''ingredient'''. required. 1 or more. text with optional valid (x)HTML markup.
*** '''''value''''' and '''''type'''''. optional. [experimental]
** '''''yield'''''. optional. text.
** '''''instructions'''''. optional. text with optional valid (x)HTML markup.
** '''''duration'''''. optional. 1 or more. text.
** ''photo''. optional. 1 or more. using any element containing a URL, such as IMG. [experimental]
** ''summary''. optional. text. [experimental]
** ''author''. optional. 1 or more. [experimental]
** ''published''. optional. [experimental]
** ''nutrition''. optional. 1 or more. [experimental]
*** ''value'' and ''type''. optional. [experimental]
** ''tag''. optional. 1 or more. [experimental]
** ''license''. optional. 1 or more. just use [[rel-license]] to license recipe permalink pages

=== Property details ===

Property names <code>fn</code>, <code>photo</code>, <code>author</code>, <code>value</code> and <code>type</code> are reused from [[hCard]]. Property name <code>duration</code> is reused from [[hAudio]]. Property name <code>summary</code> is reused from [[hCalendar]]. Property name <code>published</code> is reused from [[hAtom]]. Property name <code>tag</code> is reused from [[rel-tag]].

The fields of the hRecipe schema represent the following:

==== hRecipe ====

A hRecipe is used to identify and describe values and metadata typically associated with a recipe.

* A hRecipe property is identified by the name <code>hrecipe</code>

==== fn ====

The title of a single recipe. A short textual description used to identify the work among interested parties. This can be the name of a meal or a short description regarding it's ingredients.

* The property is identified by the name <code>fn</code>.
* A Recipe {{must}} include a <code>fn</code>.
* The property {{must}} follow the conventions outlined in [[hCard]] e.g. by using only plain text.

==== ingredient ====

Describes one or more ingredients used in the recipe.

* The property is identified by the name <code>ingredient</code>.
* A Recipe {{must}} include one or more <code>ingredient</code>s.
* The property {{may}} include valid HTML markup (e.g. a list of ingredients).
* The property {{may}} include the properties <code>value</code> and <code>type</code> following the conventions outlined in [[hCard]], e.g. <syntaxhighlight lang="html"><p class="ingredient"><span class="value">125</span><span class="type">ml</span> milk</p></syntaxhighlight> In this case each ingredient should be marked up with it's own <code>ingredient</code> property. These subproperties are considered ''experimental'' and may be removed from the final specification or replaced by 'num' and 'unit' from [[measure]].

==== yield ====

Specifies the quantity produced by the recipe, like how many persons it satisfyies or how many pieces can be made of it.

* The property is identified by the name <code>yield</code>.
* A Recipe {{may}} include a <code>yield</code>.

==== instructions ====

The method of the recipe.

* The property is identified by the name <code>instructions</code>.
* A Recipe {{may}} include a <code>instructions</code> property.
* The property {{may}} include valid HTML markup e.g. paragraphs or a list of steps.

==== duration ====

The time it takes to prepare the meal described by the recipe. Multiple duration properties can be used to denote e.g. time for preparing a dough, time needed for the dough to raise, time to bake the dough, time for decorating the cake etc.

* The property is identified by the name <code>duration</code>.
* A Recipe {{may}} include one or more <code>duration</code> properties.
* The property {{may}} encode the timespan as outlined in the [[value-class-pattern|value-class-pattern]]. A duration of 1 hour 30 minutes would translate to "PT1H30M" in ISO 8601 format and can be encoded as follows:<syntaxhighlight lang="html"><span class="duration"><span class="value-title" title="PT1H30M"> </span>90 min</span></syntaxhighlight>

==== photo ====

Accompanying image.

* The property is identified by the name <code>photo</code>.
* A Recipe {{may}} include one or more <code>photo</code> properties.
* The property {{should}} use an <img> element. It {{may}} use any other element that contains a URL, such as <a> or <object>, but it is not recommended. See [[hRecipe#Semantic_XHTML_Design_Principles | notes]] below.
* The property is considered ''experimental'' and may be removed from the final specification.

==== summary ====

The summary provides a short introduction to or an accompanying statement about the recipe.

* The property is identified by the name <code>summary</code>.
* A Recipe {{may}} include a <code>summary</code>.
* The property {{must}} follow the conventions outlined in [[hCalendar]]. Plain text fulfills these requirements.
* The property is considered ''experimental'' and may be removed from the final specification.

==== author ====

An author is the person who wrote the recipe.

* The property is identified by the name <code>author</code>.
* A Recipe {{may}} include one or more <code>author</code> properties.
* The contents of the element {{may}} be a plain text string in which case it defaults to a "vcard fn". Anything more elaborate {{must}} follow the conventions outlined in [[hCard]].
* The element is considered ''experimental'' and may be removed from the final specification.

==== published ====

The date the recipe was published.

* The property is identified by the name <code>published</code>.
* A Recipe {{may}} include a <code>published</code> date.
* The property {{may}} be encoded using the [[value-class-pattern|value-class-pattern]], e.g.:<syntaxhighlight lang="html"><p>Published <span class="published"><span class="value-title" title="2008-10-14T10:05:37-01:00"> </span>14. Oct 2008</span></p></syntaxhighlight>
* The property is considered ''experimental'' and may be removed from the final specification.

==== nutrition ====

Nutritional information like calories, fat, dietary fiber etc.

* The property is identified by name <code>nutrition</code>.
* A Recipe {{may}} include one or more <code>nutrition</code> properties.
* The property {{may}} include the properties <code>value</code> and <code>type</code> following the conventions outlined in [[hCard]]. In this case each nutritional information item should be marked up with it's own <code>nutrition</code> property. These subelement are considered ''experimental'' and may be replaced by 'num' and 'unit' from [[measure]].
* The property <code>nutrition</code> itself is also considered ''experimental'' and may be removed from the final specification.

==== tag ====

A keyword indicating a subject or an important aspect of the recipe like it's main ingredient, type of meal etc.

* The property is identified by the name <code>tag</code>.
* A Recipe {{may}} include one or more <code>tag</code>'s.
* The property {{must}} follow the conventions outlined in [[rel-tag]].
* The property is considered ''experimental'' and may be removed from the final specification.

==== license ====
'license' is simply re-use of the [[rel-license]] microformat as a building block.

Use [[rel-license]] to link to a license for the recipe on the recipe permalink page.

=== Version history ===

* Version 0.22 changed the proposed formatting of time and date from the [[datetime-design-pattern|datetime-design-pattern]], which has [[datetime-design-pattern#Accessibility_issues|accessibility issues]], to the [[value-class-pattern|value-class-pattern]]. Also corrected some errors in the example especially with regard to the correct handling of vcard properties.
* Version 0.21 changed the status of ingredient/value and ingredient/type to ''experimental'', mentioning that there still is discussion if they should be replaced by 'num' and 'unit' from [[measure]] (which is still in brainstorming).
* Version 0.2: From [http://microformats.org/wiki/index.php?title=hrecipe&oldid=37357 Version 0.1] some elements have been renamed to strenghten re-use of established elements: '''fn''' for '''hRecipe-title''', '''summary''' for '''hRecipe-summary''', '''duration''' for '''preparation-time''', '''value''' and '''type''' for '''num''' and '''unit'''. Also some elements have been marked '''experimental''' because of concerns of element bloat. See the [[hrecipe-issues]] page for a more thorough discussion.<br/>Draft 0.1 was already a result of long lasting efforts. Nonetheless after publishing of it there has been a lively debate about some properties. Since they mostly could be resolved version 0.2 is considered fairly stable now, although of course you never know ;-)

=== Parser Processing Notes ===

* If the "author" property contains only a plain text string it should be regarded as of type "vcard fn".

=== Semantic XHTML Design Principles ===

{{semantic-xhtml-design-principles}}

==== More Semantic Equivalents ====

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

* For "photo", use <code><img class="photo" src="..." alt="" /></code>

==== Language ====

* To explicitly convey the natural language that an recipe is written in, use the standard (X)HTML 'lang' or 'xml:lang' attribute on the element with class="hrecipe"
**e.g. <code><nowiki><p>I like <span class="hrecipe" lang="de"><span class="fn">Kartoffelknödel</span></span> best.</p></nowiki></code>
*If portions of an hRecipe (e.g. an ingredient name) are in a different language to the rest of the hRecipe, use the 'lang' or 'xml:lang' attribute on those portions.
* hRecipe parsers which need to handle the native language of hRecipe {{must}} process the standard (X)HTML 'lang' or 'xml:lang' attribute as specified.
* hRecipe parsers which need to handle native language {{may}} traverse up the DOM to discover the native language of the page and apply that to the hRecipe if no other language is specified on the hRecipe.

==== Human vs. Machine Readable ====

If an <code><abbr></code> element is used for a property, then its '<code>title</code>' 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.

If an <code><a></code> 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 <code>href="..."</code> attribute provides the property value.
# For other properties, the element's content is the value of the property.

If an <code><img></code> element is used for the 'photo' property, it {{must}} use the property value provided by the <code>src="..."</code> attribute as property value.

If an <code><object></code> element is used for the 'photo' property, it {{must}} use the property value provided by the <code>data="..."</code> attribute as property value.

=== Notes ===

This section is informative.

*Non so far.

== XMDP Profile ==

<syntaxhighlight lang="html">
<dl class="profile">
<dt>class</dt>
<dd><p>
<a rel="help" href="http://www.w3.org/TR/html401/struct/global.html#adef-class">
HTML4 definition of the 'class' attribute.</a>
This meta data profile defines some 'class' attribute values (class names)
and their meanings as suggested by a
<a href="http://www.w3.org/TR/WD-htmllink-970328#profile">
draft of "Hypertext Links in HTML"</a>.</p>
<dl>
<dt>hrecipe</dt>
<dd>
Used to identify and describe metadata associated with instructions for creating meals, drinks or food-based items.
</dd>
<dt>fn</dt>
<dd>
The title of the recipe.
</dd>
<dt>ingredient</dt>
<dd>
Describes the ingredient(s) used in the recipe.
</dd>
<dt>yield</dt>
<dd>
Specifies the quantity produced by the recipe.
</dd>
<dt>instructions</dt>
<dd>
The method of the recipe.
</dd>
<dt>duration</dt>
<dd>
The time it takes to prepare the meal described by the recipe.
</dd>
<dt>photo</dt>
<dd>
Accompanying image.
</dd>
<dt>summary</dt>
<dd>
The summary provides a short introduction or an accompanying statement about the recipe.
</dd>
<dt>author</dt>
<dd>
The person who authored the recipe..
</dd>
<dt>published</dt>
<dd>
The date that the recipe was made available to the public.
</dd>
<dt>nutrition</dt>
<dd>
Nutritional information like calories, fat, dietary fiber etc.
</dd>
<dt>tag</dt>
<dd>
Keyword(s) describing the recipe.
</dd>
</dl>
</dd>
</dl>
</syntaxhighlight>

== Examples ==

This section is informative.

Here '''will be''' a few examples of recipes, from real web sites, showing how they could be easily enhanced to use hRecipe. In the meantime the following contrieved example will have to do.

<syntaxhighlight lang="html"><div class="hrecipe">
<h1 class="fn">Pommes Frites</h1>
<p class="summary">
Pommes frites originate in outer space. They are served hot.<br />
This recipe is only an example. Don't try this at home!
</p>
<p>
Contributed by <span class="author">CJ Tom</span> and the
<span class="author vcard"><a class="url fn" href="http://example.com">Cooky Gang</a></span>.
</p>
<p>Published <span class="published"><span class="value-title" title="2008-10-14T10:05:37-01:00"> </span>14. Oct 2008</span></p>
<img src="/img/pommes.png" class="photo" width="100" height="100" alt="Pommes Frites"/>
<h2>Ingredients</h2>
<ul>
<li class="ingredient">
<span class="value">500</span>
<span class="type">gramme</span> potatoes, hard cooking.
</li>
<li class="ingredient">
<span class="value">1</span> <span class="type">spoonful</span> of salt
</li>
<li>
You may want to provide some
<span class="ingredient">Ketchup and Mayonnaise</span>
as well.
</li>
</ul>
<h2>Instructions</h2>
<ul class="instructions">
<li>First wash the potatoes.</li>
<li>Then slice and dice them and put them in boiling fat.</li>
<li>After a few minutes take them out again.</li>
</ul>
<h2>Further details</h2>
<p>Enough for <span class="yield">12 children</span>.</p>
<p>Preparation time is approximately
<span class="duration"><span class="value-title" title="PT1H30M"> </span>90 min</span>
</p>
<p>Add <span class="duration"><span class="value-title" title="PT30M"></span>half an hour</span> to prepare your homemade Ketchup.</p>
<p>This recipe is <a href="http://www.example.com/tags/difficulty/easy" rel="tag">easy</a> and <a href="http://www.example.com/tags/tastyness/delicious" rel="tag">delicious</a>.</p>
<p>
<span class="nutrition">
Pommes Frites have more than
<span class="value">1000</span>
<span class="type">Joule</span>
Energy</span>,
while Ketchup and Mayonnaise have
<span class="nutrition">0 vitamins</span>.
</p>
</div>
</syntaxhighlight>


== Examples in the wild ==

This section is '''informative'''.

Sites and pages that publish hRecipes. When it gets too big we can move it to a separate page like [[hrecipe-examples-in-wild]].

* [http://www.vegichef.de/ Vegichef.de]'s recipes are marked up with hRecipe e.g. [http://www.vegichef.de/rezepte/seitan-doner-mit-zaziki/ Seitan Döner mit Tsatsiki]
* [http://funcook.com/ Red social de recetas de cocina] recipes are marked up with hRecipe e.g. [http://funcook.com/receta.php?id=124 Pollo al curry con arroz basmati]
* [http://www.therecipedepository.com The Recipe Depository] recipes are marked up with hRecipe e.g. [http://therecipedepository.com/recipe/650/african-sweet-potato-and-peanut-stew African Sweet Potato and Peanut Stew]
* [http://sabores.sapo.pt/ SAPO Sabores]'s recipes are marked up with hRecipe, e.g. [http://sabores.sapo.pt/receita/espetadas-de-camarao-com-molho-picante Receita: Espetadas de camarão com molho picante - SAPO Sabores]

* [http://www.epicurious.com/ Epicurious.com]'s [http://www.epicurious.com/recipesmenus/ recipes] have been marked up with hRecipe as of April 2010. (E.g., [http://www.epicurious.com/recipes/food/views/Chocolate-Almond-and-Banana-Parfaits-357369 Chocolate, Almond, and Banana Parfaits])
* [http://www.williams-sonoma.com/ Williams-Sonoma]'s [http://www.williams-sonoma.com/recipe/ recipes section], e.g. [http://www.williams-sonoma.com/recipe/cherry-almond-bundt-cake.html Cherry Almond Bundt Cake]
* http://foodnetwork.com/ has marked up all their recipes with hRecipe as of 2009-10, e.g. [http://www.foodnetwork.com/recipes/ina-garten/deep-dish-apple-pie-recipe2/index.html Deep-Dish Apple Pie recipe]
* [http://www.plantoeat.com/ Plan to Eat]'s [http://www.plantoeat.com/recipe_book recipe planner] is now in hRecipe format as of April 2010. (E.g., [http://www.plantoeat.com/recipes/4583/1fv1A5vFhjm Pasta With Smashed Peas])
* essen & trinken. As of spring 2009 [http://www.essen-und-trinken.de essen & trinken] publishes all recipes with hRecipe-conformant metadata encoded in RDF. See [[hrecipe-rdf]] for technical details.
* It's Ripe! As of January 2009, [http://itsripe.com/recipes/ http://itsripe.com] supports hRecipe for recipe pages and will soon add support in lists.
*'''Wild Mushroom, Pancetta & Truffle Risotto''' by Toby Inkster
** [http://tobyinkster.co.uk/blog/2008/10/23/mushroom-risotto/ Marked up as hRecipe] using the September 2007 draft format
** [http://srv.buzzword.org.uk/recipebook/tobyinkster.co.uk/blog/2008/10/23/mushroom-risotto/ RecipeBook XML] output from Cognition.
** [http://srv.buzzword.org.uk/rdf-xml/tobyinkster.co.uk/blog/2008/10/23/mushroom-risotto/ RDF/XML] and [http://srv.buzzword.org.uk/turtle/tobyinkster.co.uk/blog/2008/10/23/mushroom-risotto/ Turtle] output from Cognition.
* allrecipes.com e.g. [http://allrecipes.com//Recipe/slow-cooker-chicken-and-dumplings/Detail.aspx Slow cooker chicken and dumplings]
* food.com e.g. [http://www.food.com/recipe/chicken-and-dumplings-72963 Chicken dumplings]
* tablespoon.com e.g. [http://www.tablespoon.com/recipes/old-fashioned-chicken-and-dumplings-recipe/1/ Chicken dumplings]
* shopglider.com e.g. [http://shopglider.com/r/dimathepublisher/19/Fatush-Salad/ Fatush Salad]

== Implementations ==
This section is '''informative'''.

Tools for generating and consuming hRecipes. When it gets too big we can move it to a separate page like [[hrecipe-implementations]].

Consuming hRecipes (sites and tools that consume and do something with hRecipes)
* '''[[Google Search]] feature: Recipes''' . Launched 24th February, 2011, [http://www.google.com/landing/recipes/ Recipe View] search results from Google are powered by hRecipe marked-up snippets.
* '''Cognition.''' As of September 2008, [http://buzzword.org.uk/cognition/ Cognition] has experimental support for this format. ([http://buzzword.org.uk/cognition/uf-plus.html#hrecipe Details of support].) Recipes may be exported in [[recipe-formats#RecipeBook_XML|RecipeBook XML]] format or RDF.

Generating hRecipes (sites and tools that help produce and publish hRecipes)
* '''[http://recipeseo.com/ RecipeSEO Application]''' - a nice hRecipe creator form with fields for title/name, ingredients (expandable), instructions, and more options (author, photo, yield, etc.)
* '''Recipe SEO WordPress Plugin''': [http://sushiday.com/recipe-seo-plugin/ RecipeSEO Plugin] helps you publish hRecipe on your self-hosted WordPress blog. Donation supported.
* '''WordPress hRecipe Plugin.''' There's a [http://wordpress.org/ WordPress ] [http://wordpress.org/extend/plugins/hrecipe/ hRecipe Plugin] available which makes adding hRecipe metadata to recipes very easy, practically effortless. Very nice!
* '''hRecipeHelper Chrome Extension.''' Released 16th March, 2011 [https://chrome.google.com/webstore/detail/cgpnljccbfcjhhekfnikhpllfjpjidlj hRecipeHelper] A [[Chrome]] Extension for building hRecipe formatted HTML for blogging or websites.
* '''hRecipeHelper web app'''. Released 5th April, 2011 [http://bit.ly/hPcVDD hRecipeHelper-webapp] Very similar to the Chrome Extension but, now available for other modern browsers and even IE8.

== References ==

=== Normative References ===
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE]
* [http://gmpg.org/xmdp/ XMDP]
* [[hcard|hCard]]
* [[abbr-design-pattern]]
* [[datetime-design-pattern]]

=== Informative References ===
* [http://www.w3.org/TR/REC-CSS1 CSS1]
* ISO.8601.1988
** International Organization for Standardization, "Data elements and interchange formats - Information interchange - Representation of dates and times", ISO Standard 8601, June 1988.
* [http://www.w3.org/TR/1998/NOTE-datetime-19980827 W3C NOTE-datetime-19980827]
* [http://www.w3.org/Consortium/Patent-Policy-20040205/ W3C Patent Policy]
* Other recipe metadata efforts. See [[recipe-formats]].
* [[grouping-examples]]
* [[grouping-brainstorming]]
* [[xoxo|XOXO]]

== Copyright ==

<span class="vevent"><span class="summary">Per [[Microformats_Wiki:Copyrights]], hRecipe was placed into the public domain</span> on <span class="dtstart">2008-11-14</span></span> by the authors. There are no usage, distribution, re-printing, or any other restrictions of any kind with regards to the text or content of this specification.

== Patents ==

{{MicroFormatPatentStatement}}

== Public Domain Release ==

The authors and editors of this page due hereby relinquish their copyright on the document and release the text of this page into the public domain.

* [[User:Phae|Frances Berriman]] (BBC)
* [[User:BenWard|Ben Ward]]
* [[User:TobyInk|Toby Inkster]]
* [[User:ThomasLoertsch | Thomas Loertsch]] ([http://www.essen-und-trinken.de Gruner+Jahr])

== Work in progress ==
This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added.

== derivative works ==
* [[hrecipe-rdf|hRecipe in RDF]] - mapping of hRecipe into a RDF vocabulary called "aRecipe"

==related pages==
* [[hrecipe-issues|hRecipe issues]] - issues regarding the hRecipe draft
* [[hrecipe-feedback|hRecipe feedback]] - general feedback regarding hRecipe

Per the microformats [[process]], the [[recipe]] effort developed
* [[recipe-examples]]
* [[recipe-formats]]
* [[recipe-brainstorming]] (see also [[recipe-brainstorming-archive]])
* [[recipe-issues]]
towards the development of this draft.

[[Category:Draft Specifications]]

hnews

2024-06-20T23:33:41Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:hNews 0.1}}
{{Template:DraftSpecification}}

hNews is a microformat for news content. hNews extends [http://microformats.org/wiki/hatom hAtom], introducing a number of fields that more completely describe a journalistic work. hNews also introduces another data format, [[rel-principles]], a format that describes the journalistic principles upheld by the journalist or news organization that has published the news item. hNews will be one of several open standards.
__TOC__
== Draft Specification ==

;Editor/Author
:[[:User:JonathanMalek|Jonathan Malek]] ([http://www.ap.org Associated Press])

;Contributors
:[[:User:Smyles|Stuart Myles]] ([http://www.ap.org Associated Press])
:[[:User:Martinjemoore|Martin Moore]] ([http://mediastandardstrust.org Media Standards Trust])
:[[:User:MarkNg|Mark Ng]] ([http://mediastandardstrust.org Media Standards Trust])
:[[:User:Tbmartinwiki|Todd B. Martin]] ([http://www.ap.org Associated Press])

=== Copyright ===
Per the public domain release on the authors' user pages ([[:User:JonathanMalek|Jonathan Malek]]) this specification is released into the public domain.

{{MicroFormatPublicDomainContributionStatement}}

=== Patents ===
{{MicroFormatPatentStatement}}

== Introduction ==
hNews is a microformat for identifying semantic information in news stories. It builds on [[hAtom]], while adding a number of fields that more completely define a journalistic work. hNews can be thought of as inheriting from [[hAtom]], since parsers and tools that do not understand the hNews extensions can still parse the [[hAtom]] content. However, those parsers and applications that understand hNews can enable a richer set of semantic actions on news stories.

{{rfc-2119-intro}}

== Semantic XHTML Design Principles ==
{{semantic-xhtml-design-principles}}

== Format ==
=== In General ===
hNews extends hAtom. As the hAtom draft format notes, "Atom provides a lot more functionality than we need for a 'blog post' microformat, so we've taken the minimal number of elements needed." News stories typically introduce more fields (for instance, the publishing organization) than the current 0.1 draft of hAtom, and those fields are very important when reading or evaluating a news story. We focus on those fields that enable the development of semantic actions around news: license, principles, dateline (geo) and source organization.

=== Schema ===
The hNews schema consists of the following:

* hNews ('''<code>hnews</code>''') and '''<code>hentry</code>'''. required. Using [[hAtom]].
** '''<code>source-org</code>'''. required. Using [[hCard]].[*]
** '''<code>dateline</code>'''. optional. Using text or [[hCard]].
** '''<code>geo</code>'''. optional. Using [[geo]].[*]
** '''<code>item-license</code>'''. recommended. Using a [[licensing-brainstorming#item_as_container|brainstorm proposal]].
** '''<code>principles</code>'''. recommended. Using the draft microformat [[principles-brainstorming#rel-principles_specification|rel-principles]].

[*] Some required elements have defaults if missing, see below.

=== Field and Element Details ===

==== hAtom Fields ====

===== Entry =====
* an hNews story {{must}} be encoded as an [[hAtom]] <code>hentry</code>.
* if an hNews story cannot be parsed as an [[hAtom]] <code>hentry</code>, it is invalid hNews.

==== Additional Fields ====

===== Source Organization =====
* a Source Organization element is identified by the class name <code>source-org</code>.
* Source Organization represents the originating organization for the news story.
* a Source Organization {{must}} be encoded in an [[hCard]].
* if the Source Organization is missing
** find the [[algorithm-nearest-in-parent]] element(s) with class name <code>source-org</code> and that is/are a valid [[hCard]]
** otherwise the entry is invalid hNews

===== Dateline =====
* a dateline element is identified by the class name <code>dateline</code>.
* dateline represents the location where the news story was written or filed (see [http://en.wikipedia.org/wiki/Dateline dateline] for more details).
* a dateline element {{may}} be encoded with an [[adr]], [[geo]] or [[hCard]].
* a news story {{should}} have a dateline element.
* dateline sometimes also includes the publish date of the news story. In such cases, use the [[datetime-design-pattern]] to encode the date.

===== Geo =====
* a geo element is identified by the class name <code>geo</code>
* geo represents the geographic coordinates of relevant locations in the news story.
* a geo element should be encoded in a [[geo]].
* in those cases where the latitude and longitude represent the dateline, a variant of [[geo]] should be used (see [http://microformats.org/wiki/geo-brainstorming#Geo_improvements Geo Improvements] for an example).

===== License =====
* a license element is identified by the rel value of <code>item-license</code>.
* a license element {{must}} be encoded as described in this [http://microformats.org/wiki/licensing-brainstorming#item_as_container license brainstorm proposal].
* a news story {{should}} include a license element.

===== Principles =====
* a principles element is identified by <code>rel-principles</code>.
* principles represents the statement of principles and ethics adhered to by the news organization and/or individual that produced the news story at the time of writing.
* a principles element {{must}} be encoded in [[principles-brainstorming#rel-principles_specification|rel-principles]].
* a news story {{should}} include principles.
* principles {{should}} be linked to using the icons http://labs.ap.org/principles-button-blue.png or http://labs.ap.org/principles-book-blue.png.

=== XMDP Profile ===
<syntaxhighlight lang="html">
<dl class="profile">

<dt>class</dt>
<dd>
<p><a rel="help" href="http://www.w3.org/TR/html401/struct/global.html#adef-class">
HTML4 definition of the 'class' attribute.</a>
This meta data profile defines some 'class' attribute values (class names)
and their meanings as suggested by a
<a href="http://www.w3.org/TR/WD-htmllink-970328#profile">draft of
"Hypertext Links in HTML"</a>.</p>
<dl>

<dt>hnews</dt>
<dd>Used to describe semantic information associated with news stories.</dd>

<dt>source-org</dt>
<dd>The originating organization for the news story.</dd>

<dt>dateline</dt>
<dd>Represents the location where the news story was filed.</dd>

<dt>geo</dt>
<dd>Represents geographic coordinates of relevant locations in the story.</dd>

</dl>
</dd>

<dt>rel</dt>
<dd>
<dl>

<dt>item-license</dt>
<dd>Represents the license for the story.</dd>

<dt>principles</dt>
<dd>Represents the statement of principles and ethics used by the news organization that produced the news story.</dd>

</dl>
</dd>

</dl>
</syntaxhighlight>

== Examples ==

See [[hnews-examples]].

=== Examples in the wild ===

See [[hnews-examples-in-wild]].

== Implementations ==
* Readability parses and consumes hNews. See their [http://www.readability.com/developers/guidelines Article Publishing Guidelines] for details.
* [[Google]] also parses hAtom (e.g. it's supported by their Rich Snippets [[validator]]).

== References ==

=== Normative References ===
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0]
* [[hatom|hAtom]]
* [[hcard|hCard]]
* [http://gmpg.org/xmdp/ XMDP]
* [[rel-tag]]
* [[geo]]
* [[licensing-brainstorming#item_as_container_license|item-license brainstorm]]
* [http://newscredit.org/development/newscredit-specification/rel-principles-specification/ rel-principles]
* [http://www.ietf.org/rfc/rfc2119.txt RFC2119]
* [http://www.ietf.org/rfc/rfc4287.txt RFC4287] (Atom 1.0)

=== Informative References ===
* Other news efforts: see [[news-formats]].

== Work in progress ==
This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added.

=== Version 0.1 ===

Version 0.1 was drafted August 2008.

== Further Reading ==
* See [http://www.technorati.com/cosmos/referer.html blogs discussing this page].

== Related Pages ==
* hnews
* [[news-brainstorming]]: thoughts for improving hNews.
* [[hnews-faq|hNews FAQ]]: if you have any questions about hNews, check here, and if you don't find answers, add your questions!
* [[hnews-issues]]: please add any issues with the specification to the issues page.
* [[news-formats]]: existing news and news management schemas.
* [[news-examples]]: examples of news formats on the web.
** [[hnews-examples]]: examples of how to implement hNews.

[[Category:Draft Specifications]]
[[Category:hNews]]

hatom

2024-06-20T23:32:30Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:hAtom 0.1}}
{{latest|h-entry}}
{{Template:DraftSpecification}}

hAtom is a microformat for content that can be syndicated, primarily but not exclusively weblog postings. hAtom is based on a subset of the [http://www.atomenabled.org/ Atom] syndication format. hAtom will be one of several [[microformats]] open standards.
__TOC__
== Draft Specification ==

<div class="vcard">
;<span class="role">Editor/Author</span>
:<span class="fn">[http://blogmatrix.blogmatrix.com/ David Janes]</span> <span class="org">([http://www.blogmatrix.com BlogMatrix, Inc.])</span>
</div>

;Contributors
:<span class="vcard"><span class="fn">[http://members.optusnet.com.au/benjamincarlyle/benjamin/blog/ Benjamin Carlyle]</span></span>
:<span class="vcard"><span class="fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="url">http://tantek.com/</span> and before at [http://technorati.com Technorati, Inc.])</span>

[[hatom#Copyright|copyright]] and [[hatom#Patents|patents]] statements apply.

== Status ==
hAtom 0.1 is a microformats.org draft specification. Public discussion on hAtom takes place on [[hatom-feedback]], the #microformats [[irc]] channel on irc.freenode.net, and [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 [[hatom-issues-resolved|resolved]] and [[hatom-issues-closed|closed]] issues. Please check there before reporting [[hatom-issues|issues]].

The hAtom 0.2 update is currently under development and incorporates known errata corrections as well as the [[value-class-pattern]].

== Introduction ==
hAtom is a [[microformat]] for identifying semantic information in weblog posts and practically any other place [http://www.atomenabled.org/ Atom] may be used, such as news articles. hAtom content is easily added to most blogs by simple modifications to the blog's template definitions.

{{rfc-2119-intro}}

== Example ==
Here is a simple blog post example:

<syntaxhighlight lang="html">
<article class="hentry">
<h1 class="entry-title">Microformats are amazing</h1>
<p>Published by <span class="author vcard"><span class="fn">W. Developer</span></span>
on <time class="published" datetime="2013-06-13 12:00:00">13<sup>th</sup> June 2013</time></p>

<p class="entry-summary">In which I extoll the virtues of using microformats.</p>

<div class="entry-content">
<p>Blah blah blah</p>
</div>
</article>
</syntaxhighlight>

=== Get started ===
The class '''<code>hentry</code>''' is a ''root class name'' that indicates the presence of an hAtom entry.

'''<code>entry-title</code>''', '''<code>author</code>''', '''<code>published</code>''', '''<code>entry-summary</code>''', '''<code>entry-content</code>''' and the other hAtom property classnames listed below define properties of the entry.

== Format ==
=== In General ===
The [http://atomenabled.org/developers/syndication/#person Atom Syndication Format] provides the conceptual basis for this microformat, with the following caveats:

* Atom provides a lot more functionality than we need for a "blog post" microformat, so we've taken the minimal number of elements needed.
* the "logical" model of hAtom is that of Atom. If there is a conflict, Atom should be taken as correct.
* the "physical" model of hAtom -- the actual writing of elements -- is a lot more varied than Atom provides for, due to the variety of ways weblogs are actually produced in the wild. The hAtom microformat provides a number of rules for "bridging the gap"

=== Schema ===
Schema elements are based on the Atom nomenclature and follow the microformat pattern of prefixing a unique identifier (in this case, '<code>h</code>') on the outermost container elements -- the Feed or Entry. The parts of this microformat are based on analysis of many weblog, bulletin board and media posts and can be read [[blog-post-brainstorming#Discovered_Elements]].

The hAtom schema consists of the following:

* hfeed ('''<code>hfeed</code>'''). optional.
** '''<code>feed category</code>'''. optional. keywords or phrases, using '''[[rel-tag]]'''.
** [[hentry]] ('''<code>hentry</code>''').
*** '''<code>entry-title</code>'''. required. text.
*** '''<code>entry-content</code>'''. optional (see field description). text. [*]
*** '''<code>entry-summary</code>'''. optional. text.
*** '''<code>updated</code>'''. required using [[value-class-pattern#Date_and_time_parsing|value class pattern date and time]]. [*]
*** '''<code>published</code>'''. optional using [[value-class-pattern#Date_and_time_parsing|value class pattern date and time]].
*** '''<code>author</code>'''. required using '''[[hcard|hCard]]'''. [*]
*** '''<code>bookmark</code>''' (permalink). optional, using '''[[rel-bookmark]]'''.
*** tags. optional. keywords or phrases, using '''[[rel-tag]]'''.

[*] Some required elements have defaults if missing, see below.

=== Field and Element Details ===

===== Feed =====
* a Feed element is identified by the class name <code>hfeed</code>
* a Feed element represents the concept of an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#rfc.section.4.1.1 Atom feed]
* the Feed element is optional and, if missing, is assumed to be the page
* hAtom documents {{may}} have multiple Feed elements

===== Feed Category =====
* a Feed Category element is identified by [[rel-tag]]
* a Feed {{may}} have a Feed Category
* a Feed Category element represents the concept of an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#rfc.section.4.2.2 Atom category] inside a [http://www.atomenabled.org/developers/syndication/#optionalFeedElements feed]
* Feed Category elements {{must}} appear inside a Feed element but not inside an Entry element
* the [[rel-tag]] <code>href</code> encodes the atom <code>category:term</code>; the link text defines the atom <code>category:label</code>

===== Entry =====
* an Entry element is identified by class name <code>hentry</code>
* an Entry element represents the concept of an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#rfc.section.4.1.2 Atom entry]
* any microformat content inside a <code><blockquote></code> or <code><q></code> element within the Entry should not be considered part of the Entry.
: ''This allows quoting other microformated data without worry of corrupting the model''

===== Entry Category =====
* an Entry Category element is identified by [[rel-tag]]
* an Entry {{may}} have an Entry Category
* an Entry Category element represents the concept of an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#rfc.section.4.2.2 Atom category] inside an [http://www.atomenabled.org/developers/syndication/#optionalEntryElements entry]
* the [[rel-tag]] <code>href</code> encodes the atom <code>category:term</code>; the link text defines the atom <code>category:label</code>

===== Entry Title =====
* an Entry Title element is identified by the class name <code>entry-title</code>
* an Entry {{should}} have an Entry Title
* an Entry Title element represents the concept of an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#rfc.section.4.2.14 Atom entry title]
* if the Entry Title is missing, use
** the first <code><h#></code> element in the Entry, or
** the <code><title></code> of the page, if there is no enclosing Feed element, or
** assume it is the empty string

===== Entry Content =====
* an Entry Content element is identified by class name <code>entry-content</code>
* an Entry {{should}} have Entry Content
* an Entry Content element represents the concept of an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#atomContent Atom content]
* an Entry {{may}} have 0 or more Entry Content elements. The "logical Entry Content" of an Entry is the concatenation, in order of appearance, of all the Entry Contents within the Entry
: ''Many web logs split content into multiple sections with a "Read More" link and JavaScript tricks. This is also needed in cases where Entry Titles are coded in-line and are considered part of the content.''
* if the Entry Content is missing, assume it is the empty string

===== Entry Summary =====
* an Entry Summary element is identified by class name <code>entry-summary</code>
* an Entry Summary element represents the concept of an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#rfc.section.4.2.13 Atom summary]
* an Entry {{may}} have 0 or more Entry Summary elements. The "logical Entry Summary" of an Entry is the concatenation, in order of appearance, of all the Entry Summarys within the Entry

===== Entry Permalink =====
* an Entry Permalink element is identified by [[rel-bookmark]]
* an Entry {{should}} have an Entry Permalink
* an Entry Permalink element represents the concept of an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#rfc.section.4.2.7 Atom link in an entry]
* if the Entry Permalink is missing, use the URI of the page; if the Entry has an "id" attribute, add that as a fragment to the page URI to distinguish individual entries

===== Entry Updated =====
* an Entry Updated element is identified by class name <code>updated</code>
* an Entry Updated element represents the concept of [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#rfc.section.4.2.15 Atom updated]
* an Entry {{should}} have an Entry Updated element
* use the [[value-class-pattern#Date_and_time_parsing|value class pattern date and time]] to encode the updated datetime
* if there is no Entry Updated element,
** use the Entry Published element, if present
** otherwise the page is invalid hAtom

===== Entry Published =====
* an Entry Published element is identified by the class name <code>published</code>
* an Entry Published element represents the concept of [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#rfc.section.4.2.9 Atom published]
* use the [[value-class-pattern#Date_and_time_parsing|value class pattern date and time]] to encode the published datetime

===== Entry Author =====
* an Entry Author element is represented by class name <code>author</code>
* an Entry Author element represents the concept of an [http://www.atomenabled.org/developers/syndication/atom-format-spec.php#rfc.section.4.2.1 Atom author]
* an Entry Author element {{must}} be encoded in an [[hcard|hCard]]
* an Entry Author element {{should}} be encoded in an <code><address></code> element
* an Entry {{should}} have at least one Entry Author element
* an Entry {{may}} have more than one Entry Author elements
* if the Entry Author is missing
** find the [[algorithm-nearest-in-parent|Nearest In Parent]] <code><address></code> element(s) with class name <code>author</code> and that is/are a valid [[hcard|hCard]]
** otherwise the entry is invalid hAtom

=== XMDP Profile ===
See [[hatom-profile]].

== Examples ==

See [[hatom-examples]].

=== Examples in the wild ===

See [[hatom-examples-in-wild]].

== Implementations ==

See [[hatom-implementations]].

== Copyright ==
{{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}}

== Semantic HTML Design Principles ==
<div id="Semantic_XHTML_Design_Principles">{{semantic-html-design-principles}}</div>

== References ==
=== Normative References ===
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE]
* [http://www.ietf.org/rfc/rfc4287 RFC4287: The Atom Syndication Format]
* [[hcard-parsing]]
* [[rfc-2119|RFC 2119]]
* [[iso-8601|ISO8601]]

=== Informative References ===
* [http://www.atomenabled.org/ atomenabled.org]

== Further Reading ==
* [http://www.ablognotlimited.com/articles/getting-semantic-with-microformats-part-5-hatom/ Getting Semantic With Microformats, Part 5: hAtom] by [http://www.ablognotlimited.com/ Emily Lewis]

== Work in progress ==
This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added. There is a separate document where we are keeping our brainstorms and other explorations relating to hAtom:

* [[blog-post-brainstorming|blog-post Brainstorming]]

=== Version 0.1 ===

Version 0.1 was released 28 February 2006.

== Discussions ==

* See [http://www.technorati.com/cosmos/referer.html blogs discussing this page].

=== Q&A ===
* If you have any questions about hAtom, check the [[hatom-faq|hAtom FAQ]], and if you don't find answers, add your questions!

=== Issues ===
* Please add any issues with the specification to the separate [[hatom-issues|hAtom issues]] document.

==See Also==
{{hatom-related-pages}}
* [[rel-enclosure]] - how to semantically reference enclosures (e.g. podcasts) in hAtom
* [[blog-post-brainstorming]]
* [[blog-post-formats]]
* [[blog-post-examples]]
* [[blog-post-feed-equivalence]]
* [[blog-description-format]] - how to describe a blog (as opposed to the individual entries, which is what we're doing here)
* [[xhtml-syndication]]

[[Category:Draft Specifications]]
[[Category:hAtom]]

== Translations ==
Read the hAtom draft specification in additional <span id="languages">languages</span>:
* [[hatom-fr|français]]

geo

2024-06-20T23:04:43Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:Geo}}
{{latest|h-geo}}
{{Template:DraftSpecification}}

'''geo''' (pronounced "gee-oh") is a simple format for marking up [http://en.wikipedia.org/wiki/WGS84 WGS84] geographic coordinates (latitude; longitude), suitable for embedding in HTML or XHTML, Atom, RSS, and arbitrary XML. '''geo''' is a 1:1 representation of the "geo" property in the vCard standard ([http://www.ietf.org/rfc/rfc2426.txt RFC2426]) in HTML, one of several open [[microformats|microformat]] standards.

== Draft Specification ==

;Editor/Author
: [http://tantek.com/ Tantek Çelik] ([http://technorati.com Technorati, Inc.])

=== Copyright ===
Per the public domain release on [[User:Tantek|my user page]], this specification is released into the public domain.

{{MicroFormatPublicDomainContributionStatement}}

=== Patents ===
{{MicroFormatPatentStatement}}

=== Inspiration and Acknowledgments ===
Thanks to everyone who participated in the [[geo-bof-2005-06-30|Geo Microformat BOF at O'Reilly's Where 2.0 conference]], and in particular to [http://radar.oreilly.com/nat/ Nat Torkington] and Vee McMillen of [http://oreilly.com O'Reilly] for [http://conferences.oreillynet.com/cs/where2005/view/e_sess/7476 arranging and hosting the BOF]. Thanks to Chris Hibbbert for providing the [http://www.geocaching.com/seek/cache_details.aspx?guid=dc4754bf-64d5-4f28-8715-45ad2505c86f real world geo-caching example].

== Introduction and Background ==
The vCard standard ([http://www.ietf.org/rfc/rfc2426.txt RFC2426]), has been broadly and interoperably implemented (e.g. Apple's Address Book application). The [[hcard|hCard]] microformat has similarly received significant adoption, from numerous sites publishing the format, to hCard to vCard proxies, to clientside javascript parsers.

At the [http://conferences.oreillynet.com/where/ Where 2.0 conference] in June 2005, there was widespread recognition that the community needed a way to simply and easily publish visible, extractable, geographic location information on the Web, given how often bloggers, and numerous other sites publish such information. The [[geo-bof-2005-06-30|geo microformat BOF]] discussed this very topic, and concluded with a consensus decision to just try using ''geo'' from vCard/hCard.

This specification introduces the '''geo''' microformat, which is a 1:1 representation of the aforementioned ''geo'' property from the vCard standard, by simply reusing the ''geo'' property and sub-properties as-is from the [[hcard|hCard]] microformat.

Publishers can both embed '''geo''' addresses directly in their web pages and feeds, as well as markup existing latitude/longitude coordinates in the context of the rest of the information in their web pages and feeds.

If the publisher knows and is publishing the ''name'' of the location in addition to its geo lat/long, then the publisher {{must}} use [[hcard|hCard]] instead of just '''geo''' to publish the name and geo lat/long of the location.

If the publisher knows and is publishing the address of the location, OR if the address of the location was what was actually entered by a human, and the publisher simply turned that into lat/long using some sort of a service, then the publisher {{should}} use [[adr]] to publish the actual human entered address information since that communicates far more semantic information than a simple geo lat/long coordinate.

== Semantic XHTML Design Principles ==
{{semantic-xhtml-design-principles}}

== Format ==
=== Singular Properties ===

Note that all the properties in '''geo''' are singular properties, and thus the first descendant element with that class should take effect, any others being ignored.

=== Human vs. Machine readable ===

If an <code><abbr></code> element is used for a property, then the <code>title</code> attribute of the <code><abbr></code> element is the value of the property, instead of the contents of the element, which instead provide a human presentable version of the value.

=== Value excerpting ===

Sometimes only part of an element which is the equivalent for a property should be used for the value of the property. For this purpose, the special class name <code>value</code> is used to excerpt out the subset of the element that is the value of the property. See [[hcard|hCard]] for details on this.

=== Root Class Name ===

The root class name for an geo location is <code>geo</code>.

=== Property List ===

This is the list of properties in geo, taken from [[hcard|hCard]]:

* latitude
* longitude

=== XMDP Profile ===

See [[hcard-profile]] for the [http://gmpg.org/xmdp XMDP] profile of hCard which contains the above complete list of properties, with references to their RFC 2426 definitions.

=== Parsing Details ===

See [[hcard-parsing|hCard parsing]], with the only difference being that "geo" is the root class name, rather than "vcard".

== Examples ==

This section is informative.

=== Example from RFC2426 ===

Section 3.4.2 of RFC2426 has a simple geo example:

<code>
GEO:37.386013;-122.082932
</code>

this vCard fragment as a geo, as [http://microformats.org/wiki/hcard-examples#3.4.2_GEO_Type_Definition first documented on the hCard examples page]:

<syntaxhighlight lang="html">
<div class="geo">GEO:
<span class="latitude">37.386013</span>,
<span class="longitude">-122.082932</span>
</div>
</syntaxhighlight>

this geo could be displayed as: 

<div class="geo">GEO: <span class="latitude">37.386013</span>, <span class="longitude">-122.082932</span></div>

Note that this is a '''live''' geo microformat, which will be found on this page by parsers.

=== Real world geo example ===

Here is a sample of published lat/long info (from [http://www.geocaching.com/seek/cache_details.aspx?guid=dc4754bf-64d5-4f28-8715-45ad2505c86f geocaching: Noble Steed]):

<source lang=text>
N 37° 24.491 W 122° 08.313
</syntaxhighlight>

With geo markup:

<syntaxhighlight lang="html">
<div class="geo">
<abbr class="latitude" title="37.408183">N 37° 24.491</abbr>
<abbr class="longitude" title="-122.13855">W 122° 08.313</abbr>
</div>
</syntaxhighlight>

This geo might be displayed as: 

<div class="geo"><abbr class="latitude" title="37.408183">N 37° 24.491</abbr> <abbr class="longitude" title="-122.13855">W 122° 08.313</abbr>
</div>

Again, this is a '''live''' example.

Note that since the real world example used a more human readable presentation of the geo coordinates, we use the [[abbr-design-pattern]] to keep that more human readable presentation, and in addition provide the respective absolute numerical values for the geo.

=== with value-title ===
There may be instances where you only have text like "the location" in your page, and yet you want to mark it up with geo coordinates. While it is better to markup visible data (for longevity, fidelity, reviewability), if for design reasons you're unable to provide visible display of geo details, you may use the [[value-class-pattern#Parsing_value_from_a_title_attribute|value class pattern value-title]] to markup them up:

<syntaxhighlight lang="html">
We met at a
<span class="geo">
<span class="latitude">
<span class="value-title" title="37.386013"> </span>
</span>
<span class="longitude">
<span class="value-title" title="-122.082932"> </span>
</span>
certain location
</span>
</syntaxhighlight>

This geo may be displayed as:

We met at a <span class="geo"><span class="latitude"><span class="value-title" title="37.386013"> </span></span><span class="longitude"><span class="value-title" title="-122.082932"> </span></span> certain location</span>

== Examples in the wild ==

This section is '''informative'''. The number of Geo 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, [[geo-examples-in-wild|Geo examples in the wild]].

== Implementations ==
This section is '''informative'''.

The following implementations have been developed which either generate or parse geos outside the context of hCards. If you have an geo 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.

*WordPress.com's [http://en.support.wordpress.com/geotagging/ geotagging feature] lets you geotag user profiles and posts. Geo Search is also coming soon.
*Clem Rutter's "[http://www.rutter.uklinux.net/ostowiki.html OSGBGridRefs to WGS84]" converter - Takes UK or Irish OS grid references and converts them to WGS84 coordinates, with two types of Geo mark-up (<code>SPAN</code> and <code>ABBR</code>) available to copy & paste.
* GIS-Wiki's "[http://www.giswiki.org/hjl_get_CoorE.htm hjl_getCoor]" now outputs Geo markup, from a Google Maps API.
* [http://www.addressfix.com/ AddressFix] takes any valid address in the listed countries (as at 2003-07) or map point (using GoogleMaps API) and outputs geo markup.
**Countries: Andorra, Australia, Austria, Belgium, Canada, France, Germany, Gibraltar, Italy, Japan (but only in Japanese), Liechtenstein, Luxembourg, Monaco, Netherlands, New Zealand, San Marino, Spain, Sweden, Switzerland, United States of America and the Vatican City.
**For countries other than the UK, the British Isles and China it provides geocoding for country names and city names (e.g. "Nairobi, Kenya").
**For UK, the British Isles and China, Google returns an error.
* [http://code.highearthorbit.com/greaseroute/index.php GreaseRoute] is a GreaseMonkey user script (also available as a simple Firefox Extension) which will add icons for displaying the MapQuest map of a [[geo]]. Written by [http://highearthorbit.com Andrew Turner]
* [http://www.podster.de/page/geotest podster.de] finds geo markups in podcast RSS Feeds and maps soundseeing episodes on a map (German only)
* [http://bluesmoon.blogspot.com/ Philip Tellis] has written a [http://bluesmoon.blogspot.com/2006/01/of-microformats-and-geocoding.html javascript to add maps to geo markup on pages]
* [http://placenamehere.com/TXP/pnh_mf/ pnh_mf] is a plugin for [http://textpattern.com/ Textpattern] that supports embedding geos and other microformats in templates and blog posts. Written by [http://placenamehere.com/ Chris Casciano].
* [http://bluesmoon.blogspot.com/ Philip Tellis] has written some javascript to [http://bluesmoon.blogspot.com/2006/01/of-microformats-and-geocoding.html convert the geo microformat to a google map] using [[geo]].
* Brian Suda has written some [http://suda.co.uk/projects/microformats/geo/ geo extracting] code to convert geo microformats to KML for use with Google Maps and Google Earth. There is also a bookmarklet to extract the data and pass it to google maps automatically. He is working on a GeoRSS version for Yahoo! Maps as well.
**GPX export is done, but needs some tweaking and testing. Just change &type=(kml|georss|gpx). Not quite ready for primetime yet. Feel free to test and send feedback.
* Fil explains [http://www.jquery.info/spip.php?article7 how to use the geo microformat with the javascript library jQuery] [http://jquery.com].
* [http://www.locify.com Locify] uses [[geo]] format for presenting waypoints stored from the mobile client.

=== old implementations ===
Implementations that have disappeared or appear to be offline:

Offline as of 2013-088:
* [http://www.sydneydirectory.org/ Sydney Directory Wiki] supports geographical coordinates for locations
* [http://blog.codeeg.com/ Calvin Yu] has written a [http://blog.codeeg.com/2006/01/28/using-microformats-to-plot-my-favorite-places/ web service that will allow you plot and describe places on a Yahoo Map easily] using [[hreview|hReview]] and [[geo]].
* [http://mmm.iamnear.net Magical Microformat Maker - a Geo Microformat Generator with a big map]

== References ==
=== Normative References ===
* [[hcard|hCard]]

=== Informative References ===
* [http://www.ietf.org/rfc/rfc2426.txt vCard RFC2426] ([http://www.w3.org/2002/12/cal/rfc2426 HTML reformatted version of RFC2426])
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE]
* [http://www.census.gov/geo/www/tiger/tigermap.html TIGER Map Service]
* [http://en.wikipedia.org/wiki/Geotagging Wikipedia article on GeoTagging]

== Work in progress ==
This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added.

* Proposals for changes, additions and other thoughts about [[geo]] may be found at [[geo-brainstorming]].

== Related Work ==
* [[luna]] (proposal for geo-style microformat for co-ordinates on The Moon)
* [[mars]] (proposal for geo-style microformat for co-ordinates on the planet Mars)
* [[geo-extension-strawman]] - extends [[geo]] to include the above, and for representing coordinates on other planets, moons etc.
* [[thoughts-on-extending-the-geo-microformat|thoughts on addind time and reference system]] to the geo microformat, that could also be used for places on other celestial bodies

== Similar Work ==
* [[adr]]
* [[hcalendar|hCalendar]]
* [[XOXO]]

== See Also ==
* [http://en.wikipedia.org/wiki/Geo_%28microformat%29 Geo on Wikipedia]
* [http://wikitravel.org/en/Wikitravel:Geocoding#Sources_for_lat.2Flongs Sources for latitude/ longitude coordinates]

== Related Pages ==
{{geo-related-pages}}

[[Category:Draft_Specifications]]
[[Category:Geo]]
[[Category:hCard]]

faq

2024-06-20T23:00:40Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE: Microformats FAQ }}

This page document frequently asked questions about microformats. For frequently asked questions from the [[press]], see [[press-faq]].

If you're looking for a microformat for marking up FAQs, see [[question-answer]].

== How To ==
=== What microformats should I use to markup my blog ===
''What microformats should I use to markup my blog?''

A: Use a classic [[microformat]] on the body of each page. For your index page, use an [[h-card]], since it's about you, and an [[h-feed]] for any recent updates you post there. For your individual permalink pages, use [[h-entry]].

For all of the data on your pages, use [[microformats2]].

From: http://indiewebcamp.com/faq#How_should_I_markup_my_blog

=== When should I use microformats2 or microformats1 ===
<span id="When_should_I_use_microformats2_over_microformats1">''On sites that don't currently have microformats, should microformats2 be utilized in or classic microformats? E.g. for a rather large site.''</span>

A: [[microformats2]] use less markup (are even simpler) than classic (v1) microformats, so in general microformats2 is preferred for adding to sites.

You may also want to add one v1 microformat for each page that describes the primary subject of the page.

You can easily use both:
* if a page is about a '''person''' or '''company''', add an '''[[hCard]]''' (and '''[[h-card]]''') to markup the info about the person/company.
* Or if the page is for an '''event''', add an '''[[hCalendar]]''' <code>vevent</code> (and '''[[h-event]]''') about the event info.
* Similarly with a page that is a '''[[hReview|review]], [[hProduct|product]], [[hAtom|blog post]], or [[hRecipe|recipe]]'''.
See the [[Main_Page#Specifications|list of specs and drafts]] for more recommended top level microformats.

For all other references to things on the page, links to or mentions of [[h-card|people]]/[[h-event|events]]/[[h-cite|citations]]/products, etc. use [[microformats2]].

=== What microformats should I use for backward compatibility ===
For backwards compatibility, e.g. with some [[search-engines]], it's sufficient to include one v1 microformat for each page that best describes what that page is about. See above '''When should I use microformats2 or microformats1''' for more details.

== Common Details ==
=== Can you mix properties and the root class name ===
''<span id="nesting-properties">Can you put properties on the same element as the root class for a microformat? E.g. span class="h-card p-org"?</span>''
* No, property elements must be inside the root class name element.

Mixing will result in more confusion for parsers which may be parsing nested microformats. In this case in the question, you need two elements:
* WRONG: <code><span class="h-card p-org"></code>
* RIGHT: <code><span class="h-card"><span class="p-org"></code>

The only time you can put a root class name (like "h-card") and a property class name on the same element, is when the root class name is providing an entire object as the embedded value of that property which then belongs to some other object higher up the tree.

E.g. using an h-card for the location of an h-event

<syntaxhighlight lang="html">
<span class="h-event">
<span class="p-name">HTML5 Developer Conference</span>,
<time class="dt-start">2013-04-01</time>...<time class="dt-end">2013-04-03</time>, at
<span class="p-location h-card">
<span class="p-name p-org">The Palace Hotel</span>,
<span class="p-locality">San Francisco</span>
</span>
</span>
</syntaxhighlight>

Note the <code><span class="p-location h-card"></code> which specifies that:
* the <code>p-location</code> is a property of the surrounding <code>[[h-event]]</code>
* the <em>value</em> of that h-event’s <code>p-location</code> is an entire embedded <code>h-card</code>

Another example, inside an [[h-entry]], specifying the author as an h-card: <code><span class="p-author h-card"></code>

Derived from: [[hcard-faq#Can_you_mix_properties_and_the_root_class_name]]

== Wiki specific questions ==
===Q: ''How do I create a username? Why won't it let me use my preferred username?''===

A: First, read this: http://en.wikipedia.org/wiki/Wikipedia:Username . Second, real names are preferred to pseudonyms/handles etc. Real names encourage better transparency and accountability. Third, the most common problem creating a user name is forgetting to capitalize the first letter of the user name. Try using a WikiCase version of your full name as username, e.g. RyanKing.

===Q: ''How do I pass a reCAPTCHA V1'' ===

A: Do you feel that there's a part of you that's missing?

== Email list ==
=== Why do I get You are not allowed to post to this mailing list ===
''' ''Q: I've tried sending email to the mailing list. Why do I get a bounce message stating: "You are not allowed to post to this mailing list. ..." ? '' '''

A: You must first subscribe to the microformats mailing list that you are trying to post to.

===Q: ''I've joined the discussion mailing list but am not seeing my replies anywhere. Why?''===

A: There is no moderation on microformats-discuss, but it only accepts posts from subscribers. You MUST post to microformats-discuss using the email address you used to subscribe.

===Q: ''What does "The message's content type was not explicitly allowed" mean?'' ===

A: Please go read [http://microformats.org/mailinglists-policies/ mailinglists-policies]. In particular note:
<blockquote>
'''No HTML or RTF e-mail''' period, end of story, full stop. Your mail client should let you configure it so you can send plain text messages. Make use of this ability or else there are no guarantees that anyone will be able to read your email.
</blockquote>
The mailing lists are set up to automatically reject email that is sent as text/html. Thus please configure your email client to send plain text (text/plain) email.

== Basic Microformat Questions ==
===Q: ''Who uses microformats?'' ===

A: See a list of [[examples-in-wild|sites using microformats]] and [[implementations|numerous tools]] that support microformats.

===Q: ''When should I use a microformat? What are they for?''===

A: You are writing some HTML that contains useful human-readable information (such as a piece of contact information). You say to yourself: I would like to mark this up with some classes now for styling. You look up the relevant microformat, and you
pull in the standard names. You don't have to make your own up, and now your page is machine-readable too. Bonus!

Microformats are designed to make the data you already publish for humans available to machines. It allows applications as simple as cut-and-paste or as complex as a search engine to use your data effectively.

===Q: ''Should I use microformats or microdata?'''===

A: '''microformats''' require less markup, are easier to learn for common cases like [[hcard-authoring|people]]/[[hcalendar-authoring|events]]/[[get-started|etc.]], and are supported by more [[tools]] including [[search-engines]].

If you're looking for minimal markup addition, just use microformats.

If you want to use both, you may do so because they don't interfere.

===Q: ''Are microformats dependent upon (X)HTML?''===

A: No. Microformats work with the class attribute in HTML5, SVG etc., and can also be embedded in any XML (like Atom or RSS), as embedded XHTML.

===Q: ''Microformats sound great. How can I help?''===

A: Take a look at [[get-started]] for how to implement microformats yourself, and the [[to-do]] list for things to help out with. See http://microformats.org/discuss to see some ways to join the conversations about microformats.

===Q: ''I'd like to make a donation to the microformat cause. How can I do this?''===

A: Thank you for your willingness to support microformats. microformats.org is an all volunteer unpaid organization, and sponsor contributions really help the community. There are several ways to support microformats with donations:
<div class="discussion">
* Donate to a microformats [[open source]] effort, e.g.
** [https://addons.mozilla.org/en-US/firefox/addon/4106/developers DONATE to Operator] - an essential [[Firefox]] extension
* Sponsor a microformats [[weekly meetup]].
** Watch the [[events]] page for a weekly meetup near you, participate and sponsor dinner and or drinks!
* Sponsor a microformatsDevCamp like the [[events/2009-07-25-dev-camp|recent devCamp in SF]].
** Watch the [[events]] page for upcoming devCamps, vEvents, and other similar opportunities to sponsor.
</div>

===Q: ''Which microformats have been implemented?'' ===

A: See the [[implementations]] page.

===Q: ''Which microformats should I implement?''===

A: Chances are you that your website already has data very similar to several microformats. For example, you probably have people and/or their contact information somewhere. That information could be marked up with [[hcard|hCard]], see the [[hcard-authoring|hCard authoring]] page for step by step instructions. If you are publishing press releases, try using [[hatom|hAtom]].

===Q: ''Do you have any link badges I can add to my website/blog?''===

A: There are some [[buttons]] but we can certainly use more! Please contribute what you come up with!

===Q. ''Are there any tools that support microformats?''===

A. Yes...tons... [[implementations]].

===Q. ''What is the 'h' for, in front of Calendar and Card?'' ===
''What's the meaning of the 'h' before the [[hCalendar]] and [[hCard]] microformats?''

A. hCard and hCalendar are the <strong>H</strong>TML versions of vCard and iCalendar, hence the replacement of the leading lowercase 'v' or 'i' with 'h'. Origins: <cite>[http://tantek.com/log/2004/09.html#d30t1725 Tantek's Thoughts: "Semantic XHTML" slides posted]</cite>.

See the [[hcard-faq|hCard FAQ]] and the [[hcalendar-faq|hCalendar faq]] for more specific questions on those microformats.

===Q. ''Is there a way to indicate that a given web page contains markup that conforms to one or more microformats?'' ===

A. The HTML HEAD element's '<code>profile</code>' attribute alerts applications to the potential presence of microformats. The [http://www.w3.org/TR/1999/REC-html401-19991224/struct/global.html#h-7.4.4.3 W3C HTML Specification] describes more about the profile attribute, and the [http://gmpg.org/xmdp/description XMDP description] documents how it is used.

===Q: ''What do these specific jargon terms mean?''===

A: See our [[glossary]].

===Q. ''What about using new URI schemes instead of class names, e.g. for geo information?''===

A. In general, it is more work, and less content-publisher friendly, to ask publishers to use URI schemes instead of class names.

Authors aren't publishing links to geo information.

They're publishing *visible text* of [[geo]] information.

So the easiest thing to do, for the author, is to leave it as visible text.

Thus, it makes the most sense to do the simple thing of just wrapping that
visible text with a little bit of markup, rather than asking the author to
move (or copy) it into an attribute, which may or may not require a
reformatting of the data as well.

It would make sense from a usability persepective to hyperlink geo information to a maps page or something, so that clicking it actually does something. If you forced them to use a hypothetical "geo:" protocol instead, then that would interfere, since you can only hyperlink something to one destination.

===Q: ''Who controls microformats?''===

A: An open community. Microformats are open standards originally licensed under Creative Commons Attribution, and placed into the [[Microformats_Wiki:Copyrights|public domain since 2007-12-29]]. Much of the work here was begun on [http://developers.technorati.com/wiki Technorati's Developer Wiki], and Technorati contributed the work done there to the microformats community when microformats.org was established. The microformats.org domain is registered to Rohit Khare (see [http://whois.uberdose.com/microformats.org Whois microformats.org]), CommerceNet is graciously hosting the servers, but claims no control over microformat standards. Anyone may follow the established [[process]] and contribute towards the development of microformat standards.

Any required [[governance]] (and very little ''has been'' required) of the microformats [[IRC]] channel, wiki, and [[mailing lists]] is discussed by a group of volunteer [[administrators]].

===Q: ''Who is the registrar for microformats?''===

A: There is no central registry. Microformats are registered in a distributed manner using profiles. For more information on profiles see http://microformats.org/wiki/profile-uris and http://gmpg.org/xmdp/

Conflicts and interoperability are managed through social processes rather than a formal registry. Current microformat profiles can be found at http://gmpg.org, http://w3.org, and http://microformats.org.

===Q: ''So multiple microformats with the same name can be valid?''===

A: Yes. The community at microformats.org can hopefully play a role in determining which is preferred by bringing interested folks together in one place and helping them resolve that question. As long as each microformat maintains a valid profile, each can be used effectively.

===Q: ''How do I validate my microformated content?''===

A: See [[validators]] for a list of microformats validators.

===Q: ''Why do microformats use English terms for property names?''===
A: Similar to how HTML uses English words like "class", "span" or "head", microformats re-uses English words for property names. As microformats property names are based on existing standards (see [[process]], and [[naming-principles]]), this is another problem that is far outside the scope of microformats. As Ryan King put it, this is a pre-existing (unsolved) "problem" with English-based HTML, the English-based CSS, the English-based HTTP and so on. Note that this is NOT about the internationalization of the content and data itself - which is of course an excellent goal, advocated and promoted by microformats and the standards they are based on (e.g. W3C, IETF). This is purely about the names of the properties (and enumerated values) in the formats. See also [[internationalization]] and the [[en-us-faq#why_not_use_other_spellings_and_languages_for_properties|en-US FAQ: why not use other spellings and languages for properties]] regarding the question of alternate (non-English) names in other (natural) languages, and mappings.

===Q: ''How come microformats stay as drafts even though they seem usable?'' ===

A: This was discussed at the [http://2007.sxsw.com/interactive/programming/panels/?action=show&id=IAP060234 The Growth and Evolution of Microformats] panel at [http://en.wikipedia.org/wiki/South_by_Southwest SXSW] 2007. The basic answer is it was important to at least have a basic software implementation -- even an experimental one -- before moving a format from Draft to Specification. It can sometimes be hard to recognize subtle inconsistencies within a format by eye; however, in the process of implementing a format-reader in code, inconsistencies (if any) can become much more noticeable (due to [[dry | DRY / Don't Repeat Yourself]], among other programming best practices). Then, once such tools have been created (in effect, confirming both the programmability of the format, and interoperability across tools), it can be considered for transition to a Specification. Using interoperable implementations as a measure of format quality is a long-standing practice of IETF and W3C.

== Creating and Suggesting New Microformats ==

===Q. ''I would like to author a new microformats open standards specification for my site/business. How do I get started?''===

A. The first thing to do before attempting a new microformat open standard is to make as much use of [[POSH]] and existing [[microformats]] open standards as possible in whatever site you are looking to mark up with your new microformat, as a way of learning what is left to be done. That is, at a minimum first:
* Mark up all people and organizations as [[hcard|hCards]] and add those pages to [[hcard-examples-in-wild]]
* Mark up all events and time based things as [[hcalendar|hCalendar]] events and add those pages to [[hcalendar-examples-in-wild]]
* Mark up all reviews as [[hreview|hReviews]] and add those pages to [[hreview-examples-in-wild]]
* etc.
Then join the microformats [http://microformats.org/discuss IRC channel and discuss list], and ask folks what they think of your use of the microformats and if it can be improved.

From that experience you will then be able to figure out what is left to be specified. Otherwise it is too hard to approach the "whole problem".

Once you have completed that, take a look at the microformats [[process]] for how to walk through the steps of creating a new microformat, and note the specific problem you are trying to solve to the microformats-discuss list. This will help you find more people to help you solve the problems you are trying to solve.

===''Q How do I know if an idea for a Microformat has already been suggested in the past?''===

A. Check the list of proposed and rejected microformats.
* [[rejected-formats]]

===Q. ''What if I can't find real-world examples of a standard I'd like to propose?''===

A. If we can't find real-world examples of the '''types of data''' a proposal would address, it's probably not suitable for a microformat. If we only can't find real-world examples of the '''specific markup''' a proposal would use for that data, however, that's not really a problem. It's actually the lack of such standard markup in real-world publishing around a specific problem that suggests the need for increased consensus.

== Specific Microformat Questions ==
If you have a question regarding a specific microformat, you may want to check the FAQ specific to that microformat.
* [[hatom-faq]]
* [[hcalendar-faq]]
* [[hcard-faq]]
* [[hreview-faq]]
* [[rel-faq]]
* [[rel-tag-faq]]
* [http://gmpg.org/xfn/faq xfn-faq]
* [[xfolk-faq]]
* [[xmdp-faq]]
* [[xoxo-faq]]

== Class interactions ==
===Q. ''Are there issues with page styling when specific class values are used?''===

A. There might be. However, any such issues can be easily (trivially) worked around by using contextual selectors.

===Q. ''How does the use of class values for semantics interact with the use of class values for attaching CSS styles?''===

A. The class attribute takes a space separated set of class names [http://www.w3.org/TR/REC-html40/struct/global.html#h-7.5.2 HTML4 reference]. Thus both author and microformat defined class names may be used in the same class attribute. Experience has shown that the best practice is for authors to use their own class names for styling, and only use microformats class names for expressing microformats semantics. If the author is already using using specific class names, they can continue to do so. If the author is already using a class name that happens to also be a microformats class name, then the author may want to consider using contextual CSS class selectors to make sure to reduce any unintentional styling effects, or ideally use their own site-specific class names that are not microformats class names.

See also:
* [http://tantek.com/log/2002/12.html#L20021216 A Touch Of Class]
* [http://tantek.com/log/2004/07.html#classmeaningnotshow Class For Meaning Not For Show]
* [http://www.meyerweb.com/eric/thoughts/2004/07/18/competent-classing Competant Classing], by Eric Meyer for discussion of choosing class names in (X)HTML
* [http://www.microformats.org/blog/2005/10/19/more-than-styling/ Class attributes are about more than styling] - Ryan King dispells common misconceptions about the ''HTML'' class attribute.
* [https://tantek.com/2012/353/b1/why-html-classes-css-class-selectors Why you should say HTML classes, CSS class selectors, or CSS pseudo-classes, but not CSS classes]

===Q. ''Are class names case sensitive?'' ===

A: Yes, HTML class names (i.e. as used in microformats) are case-sensitive.

By [[naming-principles#Some_Details|convention]], microformats use all lowercase classnames similar to CSS's approach. This way authors never have to guess about the capitalization of microformats properties - they're always all lowercase.

== <code><div></code> and <code><span></code> semantics ==

=== Q. ''Can microformats use other elements besides divs?'' ===
A. Yes. Markup with microformats should use the most appropriate semantic HTML. For example if the name of an organization hCard is a top level heading, then: <p><code><div class=vcard><br/><strong><h1 class="fn org">ACME Co.</h1></strong><br/></div></code></p> is more appropriate than <p><code><div class=vcard><br/><strong><div class="fn org">ACME Co.</div></strong><br/></div></code></p>

=== Q. ''Is it semantically meaningless to use divs?'' ===

A. Yes, both <code><div></code> and <code><span></code> have nearly no semantics. <code><div></code> can be used to represent a "division" of the page content. Similarly <code><span></code> can be used to reperesent that that "span" of text has some meaning, but the specifics of what that meaning is undefined by the <code><span></code>.

=== Q. ''Does the use of <code><div></code> and <code><span></code> elements add any semantics to web pages?''===

A. According to the [http://www.w3.org/TR/REC-html40/struct/global.html#h-7.5.4 HTML 4 spec], <code><div></code> and <code><span></code> "offer a generic mechanism for adding structure to documents." Their only meaning is in dividing documents into sections, and as such, their presence implies that the content within has a specific, but undefined by the element markup, semantic. Thus they are nearly semantic-free.

=== Q. ''Why do the examples on the wiki use <code class="element"><span></code> and <code class="element"><div></code> for nearly everything?''===

A. <code class="element"><span></code> and <code class="element"><div></code> are generic elements in HTML. When you use microformats, you should pick the most specific semantic element available for the semantics you are trying to express. You might, for example, apply <code>class="vevent"</code> to a <code><nowiki><tr></nowiki></code>, or <code>class="vcard"</code> to a <code><nowiki><p></nowiki></code>. Here is an example using more [[semantic HTML]] with a definition list to mark-up an hCard:
<syntaxhighlight lang="html">
<dl class="vcard">
<dt class="category">Restaurant</dt>
<dd class="fn org">
<a class="url" href="http://www.yelp.com/biz/crepes-n-more-fairfield">Crepes N More</a>
</dd>
<dt>Address</dt>
<dd class="adr">
<span class="street-address">620 Jackson st.</span>,
<span class="locality">Fairfield</span>,
<abbr class="region" title="California">CA</abbr>,
<span class="postal-code">94533</span>,
<abbr class="country-name" title="United States of America">USA</abbr>
</dd>
<dt>Phone</dt>
<dd class="tel">+1.707.428.2210</dd>
</dl>
</syntaxhighlight>

== Class semantics ==

===Q. ''How will microformat class names impact page size?''===

A. You probably won't notice any impact on page size when authoring with microformats. Our experience is that people use comparably sized class names, and [[semantic-class-names|semantic class names]] are now considered an industry best practice. Some sites are successfully publishing millions of microformats, and we haven't heard any complaints yet. You are more likely to gain space savings by more fully adopting [[microformats#the_microformats_principles|the principles of microformats]], and eliminating tables for layout.
<span class="todo">''TODO: Consider creating a new section for web authoring tips? Or at least linking to another site that advocates good authorship.''</span>

===Q. ''Can an element have more than one class''===

A. Yes, the class attribute can contain a space delimited list of classes. For example:
<p class="todo idea">Write high quality and simple mark-up.</p>

See W3C HTML 4.01 Specification: [http://www.w3.org/TR/html401/struct/global.html#adef-class 7.5.2 Element identifiers: the id and class attributes]

===Q. ''Does the order of class names matter?'' ===
A. No. The HTML class attribute is an unordered space separated set of class names. The order of classes in an class attribute do affect their meaning or use. E.g. these two divs' class names are equivalent:
<syntaxhighlight lang="html">
<div class="a b">...</div>
<div class="b a">...</div>
</syntaxhighlight>

===Q. ''Do (X)HTML class names have semantics?''===

A. The HTML4 specification does not define any particular class values [http://www.w3.org/TR/REC-html40/struct/global.html#h-7.5.2 REF], nor does it define any particular semantic for class values [http://www.w3.org/TR/REC-html40/struct/global.html#h-7.5.2 REF], except that they "may be used for general user agent processing" [http://www.w3.org/TR/REC-html40/struct/global.html#h-7.5.2 REF]. However, the [http://www.w3.org/TR/WD-htmllink-970328#profile" draft of "Hypertext Links in HTML"], allows for a "profile" to define meanings for those classes. [http://gmpg.org/xmdp/ XMDP] is a format for defining meta data profiles for (X)HTML, and thus an XMDP profile can be used to define the meanings of class names.

See also:
* [http://tantek.com/log/2002/12.html#L20021216 A Touch Of Class]
* [http://www.w3.org/TR/WD-htmllink-970328 Hypertext Links in HTML]

===Q. ''I thought one of the main goals of CSS was to separate data from presentation. Isn’t this sneaking presentation back into data?''===

A. This is a quite commonly expressed objection to the way microformats uses class, but it's based on a misunderstanding of the way the class attribute in HTML was designed. Yes, class is very commonly,and appropriately used by web designers in conjunction with CSS to style pages, and in truth, it is often overused for that, but despite this, class, according to the HTML specification "has several roles in HTML", including [http://www.w3.org/TR/html4/struct/global.html#h-7.5.2 "for general purpose processing by user agents"].

Microformats utilize this second aspect of the class (and id) attribute, and do so legitimately. It is not an abuse of the class or id attribute to use it to add semantic context to a document. Nor is the use of class in and of itself presentational - in fact, it is an important mechanism for separating presentation from structured content.

For some more on using class semantically, here are some articles

* [http://meyerweb.com/eric/thoughts/2004/07/18/competent-classing Competent Classing by Eric Meyer]
* [http://www.w3.org/QA/Tips/goodclassnames Use class with semantics in mind, W3C]
* [http://tantek.com/log/2004/07.html#d20t2359 More about the class attribute, Tantek Çelik]

===Q. ''Should human readable data go into class names?'' ===

A. No. We should not put human readable data into the <code>class</code> attribute, because it puts human-readable data in a spot that's no longer visible. See the [[principles]].

Q. Follow-up. How is that different from putting human readable data into the <code>title</code> attribute?

A. The title attribute is displayed in tool-tips in the overwhelming majority of browsers in use and thus is quite semi-visible, and thus human verifiable by casual users. The class attribute is not displayed in a tool-tip or any other user interface (not withstanding developer interfaces like view source).

===<abbr title='Question'>Q.</abbr> Why don't microformats use the HTML5 <code>data-</code> attributes to embed data?===

<abbr title='Answer'>A</abbr>:
# The HTML5 <code>data-</code> attribute specification expressly forbids the microformats use-case:<blockquote cite='https://www.w3.org/TR/html5/dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes'>Custom data attributes are intended to store custom data private to the page or application, for which there are no more appropriate attributes or elements. These attributes are not intended for use by software that is independent of the site that uses the attributes. [...] It would be inappropriate, however, for the user to use generic software not associated with that music site to search for tracks of a certain length by looking at this data. This is because these attributes are intended for use by the site's own scripts, and are not a generic extension mechanism for publicly-usable metadata.</blockquote>— <cite>[http://www.w3.org/TR/html5/semantics.html#embedding HTML5 · Embedding custom-non-visible data]</cite>
# Microformats are designed around the principle that non-visible data is undesirable, harder to maintain, more prone to inaccuracy (as no-one will see the data on the page to notice errors). The <code>data-</code> attribute is explicitly designed for non-visible data.

== Hidden Content ==
Related to <span id="Microformats_and_Spam">microformats and spam</span>.

=== Q. ''Will crawlers get data from hidden content?'' ===
Q: ''If I markup some content inside of a block with display:none, will crawlers get data from it anyway?''

A. Crawlers and search engines frown upon hidden (e.g. display:none) content in general (e.g. see next FAQ about Google, hidden content, and spam). If some content doesn't fit into your visible design, then it's not worth microformatting it. Visible content is the only content you can reasonably trust/expect to be correct / up to date. Invisible content tends to rot, get out of date, fail to be checked etc., so don't waste any time publishing invisible content - it's going to die anyway.

=== Q. ''Given that Google now looks at hidden content as potential spam, will invisible microformats be considered spam?''===

;shortlink
:http://j.mp/gnohide

A. It is advisable not to hide information in your site, regardless of whether it is microformatted or not. Microformats provide a mechanism for marking up ''visible'' content. Any mechanism for embedding ''invisible'' or hidden content risks being considered spam due to the fact that invisible (meta)data inevitably ends up being abused. Avoid invisible (meta)data. Publish visible data.

Google in particular have said: <blockquote><p>In general, Google won't display content that is not visible to the user. In other words, don't show content to users in one way, and use hidden text to mark up information separately for search engines and web applications. You should mark up the text that actually appears to your users when they visit your web pages.[http://support.google.com/webmasters/bin/answer.py?hl=en&answer=146897]</p></blockquote>

The only 'hidden' data they support according to that article is specific use of the [[value class pattern]] <code>value-title</code> empty span with machine-readable information adjacent to a human-readable equivalent.

== Design Patterns with Abbr & Title ==
=== Q. ''Why is ABBR being used when the title attribute is available on all HTML elements?''===

In the datetime design pattern the title attribute is used for the value of the property and the node value is used as the display value. <abbr title="value-here">Display-Here</abbr>.

A. The short answer is that <abbr> has the correct semantics.

The longer answer is that the value is often an abbreviated version of the formal value. Of course, if you don't want to use an <abbr>, you can use another element like this:

<abbr title="2006-12-31T12:59:59Z" class="dtstamp">New Year</abbr>

<span class="dtstamp">2006-12-31T12:59:59Z</span>

In addition, microformats encourage the content to be visible and thus prefer the text of an element rather than using the 'title' attribute or any other less visible alternative. The exception is made for datetimes and abbr due to the fact that microformats are for humans first, machines second. Thus the content of the abbr element is used to provide human visible content and the machine equivalent is placed in the less visible (but still easily verifiable) 'title' attribute.

=== Q. ''Can I include information within the HTML element itself?'' ===

Longer: ''Can I include information within the HTML element itself? e.g. <span class="org" title="Foobar, Inc."></span>?'' [http://twitter.com/szarka/status/109723996223840256]

A. You can't do that with the <code>span</code> element because there is no specific semantic connection between the element contents and its <code>title</code> other than being [http://www.w3.org/TR/html401/struct/global.html#h-7.4.3 "advisory information about the element"]. In addition, it's bad form (and penalized by Google) to include invisible data on web pages.

Instead, you can use the <code>abbr</code> element and its <code>title</code> attribute to provide an expanded form of the information in cases where substituting the expanded form when reading the text in context reads correctly, e.g. inside an [[hCard]]:
<syntaxhighlight lang="html">
<abbr class="region" title="Connecticut">CT</abbr>
</syntaxhighlight>

[http://twitter.com/microformats/status/112556548877844481]

== Nesting of elements ==
=== Q. ''It seems that <code><span class="vcard fn org" id="club">...</span></code> should work. Is this correct?''===

A. No. See [[hcard-faq#nesting-properties]].

== Usage/Verbiage ==
=== Q. ''Is '''Microformat''' a proper noun? Should it be capitalized?''===

A. Since the term "microformat" was established, it has been written in lowercase. This is a nod to its roots in the term "lowercase semantic web", in contrast to the uppercase "Semantic Web" which has long been tied to RDF and other technologies often viewed as impractical for the open web. In a few cases in the wild(citation needed), the term has been capitalized as "Microformat", perhaps due to proper noun capitalization conventions.

=== Q. ''Can you use microformat as an adjective or verb, as in "microformatted content" or "can you please microformat that page with an hCard?"'' ===

A. Because the word ''microformat'' is derived from the word '''format''', it makes logical sense that one can use the term as an adjective or verb, just as one would use the word '''format'''.

== Other ==
=== Q. '''How do I find an answer to a question not mentioned here?'' ===

A. Join [[irc]] and ask!

== See Also ==
* [[misconceptions]]

rel-author

2024-06-20T22:58:35Z

GRegorLove: s/<source>/<syntaxhighlight>/ fixes "Pages using deprecated source tags" category

{{DISPLAYTITLE:rel author}}
<span class="h-card">[[User:Tantek|Tantek Çelik]]</span> (Editor)
----
<dfn style="font-style:normal;font-weight:bold">rel-author</dfn> is for linking from an article or post (e.g. marked up with [[hAtom]]) to a page or site representing its author. rel-author is one of several open [[microformats|microformat]] standards suitable for embedding data in HTML/HTML5, and Atom/RSS/XHTML or other XML.
== Summary ==
'''<code>rel="author"</code>''' is for relating an article or post to a page or site representing its author, typically to give them credit for their work (or portions of it, like books, articles, blog posts etc).

E.g. a page or a post written by a person "Erin Smith" could contain a link like:
<syntaxhighlight lang="html">
<a href="http://erin.example.com/" rel="author">Erin Smith</a>
</syntaxhighlight>

The <code>rel="author"</code> attribute indicates that the destination of the link represents the author of the current page (or post).

== Examples in the wild ==
Add permalinks of articles (no homepages) using rel=author, with any particularly interesting details about their usage:

* [http://harpers.org/archive/2015/10/the-mother-of-all-questions/?single=1 Harpers.org]
* [http://variety.com/2015/tv/columns/donald-trump-saturday-night-live-host-nbc-controversy-protests-1201634443/ Variety.com]

The Harpers page is interesting because it uses multiple rel=author, but clearly intends to scope the authorship to the containing div class="article" element. This doesn't follow any spec.

The Variety page is interesting because it uses multiple rel=author, with the intent to scope the authorship to the containing article element (as described in the [http://www.w3.org/TR/html/links.html#link-type-author HTML spec])

(Any homepages added to these examples will be reverted, and the editing accounts banned.)

== Implementations ==
This section is '''informative'''.

Plenty of implementations in the IndieWebCamp community, in particular:
* The [https://indiewebcamp.com/authorship authorship algorithm] uses [[rel-author]].

== articles ==
This section is '''informative'''.

Articles and blog posts about rel=author:
* 2013-08-20 http://moz.com/blog/google-plus-correlations
* 2014-08-28 http://searchengineland.com/goodbye-google-authorship-201975

== past implementations ==
This section is '''informative'''.

Past implementations.

=== Google ===
'''Dropped 2014-08-28[http://searchengineland.com/goodbye-google-authorship-201975]'''.

An interesting rel="author" implementation set of examples is brought up by Google in a video posted on Youtube:
* [http://www.youtube.com/watch?v=FgFb6Y-UJUI Authorship markup video] and the respective [http://www.google.com/support/webmasters/bin/answer.py?answer=1229920 implementation procedure].

=== query parameter alternative ===
Google has proposed an alternate mechanism for specifying rel=author on sites/CMSs that don't permit authors to specify the rel attribute, using a query parameter added to the URL instead. e.g. the above example with query parameter:

<syntaxhighlight lang="html">
<a href="http://erin.example.com/?rel=author">Erin Smith</a>
</syntaxhighlight>

This technique is explained in the following video:
* [http://www.youtube.com/watch?v=gG3Oh7Ues8A Authorship markup using URL parameters video] and the [http://www.google.com/support/webmasters/bin/answer.py?answer=1408986 new implementation procedure] with the help of Google Profile (and hopefully, this type of implementation can be used on any other personal BIO page of respective author).

==== query param issues ====
<div class="discussion">
* While I understand the motivation here, this is not a good idea. There will definitely be someone who has ?rel= as an actual query param meaning something in their app, and this will just break things. [[User:Singpolyma|Singpolyma]] 17:56, 12 August 2011 (UTC)
* ...
</div>

== see also ==
* [[rel-author-issues]]
* [[hAtom]]
* [[hNews]]
* [[rel-faq]]
* [[rel-me]]
* [[existing-rel-values]]

[[Category:Draft Specifications]]

microformats2

2024-03-01T19:05:40Z

GRegorLove: /* Implementations */ microformats.io links, commented out Glenn's since it's not working currently

<span style="float:right">__TOC__</span>
Welcome to the microformats2 home page.

== Summary ==
Microformats2 is the latest version of microformats, the simplest way to markup structured information in HTML. Microformats2 improves ease of use and implementation for <em>both</em> authors (publishers) and developers ([[microformats2-parsing|parser]] implementers).

Microformats2 replaces and supersedes both classic microformats (sometimes called microformats1), as well as incorporates lessons learned from [[microdata]] and [[RDFa]].

=== simple microformats2 examples ===
Here are a few <span id="simple_microformats_2_examples">simple microformats2 examples</span> along with canonical [[JSON]].

==== person example ====
* Simple person reference:
<syntaxhighlight lang="html">
<span class="h-card">Frances Berriman</span>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Frances Berriman"]
}
}]
}
</syntaxhighlight>

----

==== hyperlinked person ====
* Simple hyperlinked person reference
<syntaxhighlight lang="html">
<a class="h-card" href="http://benward.me">Ben Ward</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Ben Ward"],
"url": ["http://benward.me"]
}
}]
}
</syntaxhighlight>

----

==== hyperlinked person image ====
* Simple hyperlinked person image
<syntaxhighlight lang="html">
<a class="h-card" href="http://rohit.khare.org/">
<img alt="Rohit Khare"
src="https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg" />
</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Rohit Khare"],
"url": ["http://rohit.khare.org/"],
"photo": ["https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg"]
}
}]
}
</syntaxhighlight>

Additional simple cases details in [[microformats-2-implied-properties]].

----

==== detailed person example ====
* More detailed person
<syntaxhighlight lang="html">
<div class="h-card">
<img class="u-photo" alt="photo of Mitchell"
src="https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"/>
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="u-url"
href="https://twitter.com/MitchellBaker"
>@MitchellBaker</a>)
<span class="p-org">Mozilla Foundation</span>
<p class="p-note">
Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities.
</p>
<span class="p-category">Strategy</span>
<span class="p-category">Leadership</span>
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"photo": ["https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"],
"name": ["Mitchell Baker"],
"url": [
"http://blog.lizardwrangler.com/",
"https://twitter.com/MitchellBaker"
],
"org": ["Mozilla Foundation"],
"note": ["Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities."],
"category": [
"Strategy",
"Leadership"
]
}
}]
}
</syntaxhighlight>

----
=== details from examples ===
Details demonstrated by the examples:
# The JSON <code>"type"</code> uses the full microformat root class name (e.g. <code>"h-card"</code>) for consistent identification.
# all properties are optional and syntactically plural with parsed values provided in document order; particular microformats (and applications there-of) may apply specific/singular semantics to first value of a property.

=== microformats2 design ===

microformats2 has the following key design aspects:

; Prefixes for class names
: All microformats class names use prefixes. Prefixes are '''syntax independent from vocabularies''', which are developed separately.
* <code>h-*</code> for root class names (e.g. <code>h-card</code>)
* <code>p-*</code> for plain text properties (e.g. <code>p-name</code>)
* <code>u-*</code> for URL properties (e.g. <code>u-photo</code>)
* <code>dt-*</code> for date/time properties (e.g. <code>dt-bday</code>)
* <code>e-*</code> for embedded markup properties (e.g. <code>e-note</code>)<br />

See [[microformats2-prefixes]] for more details.

; Flat sets of optional properties
: All microformats consist of a root, and a collection of properties. Hierarchical data is represented with nested microformats, typically as property values themselves. Properties are all optional and potentially multivalued (applications needing a singular semantic may use first instance).

; Single class markup for common uses
: Common simple markup patterns require only a single microformat root class name, which parsers use to find a few generic properties: <code>name</code>, <code>url</code>, <code>photo</code>. The simple microformats2 examples above demonstrate these.

----

Parsing each prefix (including generating canonical JSON) is detailed step-by-step in:
* The '''[[microformats2-parsing|microformats2 parsing specification]]'''

'''Note:''' Most properties are specified and used with a single specific prefix (or occasionally two or three) that is self-evident from context. However, any parsing prefix can be used with any property, especially if you find a good reason to do so!

== v2 vocabularies ==
Status: '''<span id="draft_v2_vocabularies">draft</span>'''. Please review and provide feedback in [[IRC]].
* [[h-adr]]
* [[h-card]]
* [[h-entry]]
* [[h-event]]
* [[h-feed]]
* [[h-geo]]
* [[h-item]]
* [[h-listing]]
* [[h-product]]
* [[h-recipe]]
* [[h-resume]]
* [[h-review]]
* [[h-review-aggregate]]

See below for vocabulary summaries.

=== h-adr ===
{{main|h-adr}}

The '''h-adr''' microformat is for marking up structured locations such as addresses, physical and/or postal. This is an update to [[adr]].

root class name: '''<code>h-adr</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-adr</nowiki>

properties:
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-street-address</code>'''
* '''<code>p-locality</code>'''
* '''<code>p-region</code>'''
* '''<code>p-postal-code</code>'''
* '''<code>p-country-name</code>'''
* '''<code>p-label</code>''' - new in [[vCard4]] ([[RFC6350]])
* '''<code>p-geo</code>''' (or '''<code>u-geo</code>''' with a RFC 5870 geo: URL) - new in [[vCard4]] ([[RFC6350]])
* '''<code>p-latitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-longitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-adr" is found, don't look for an "adr" on the same element.

compat root class name: <code id="adr">adr</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>post-office-box</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>

=== h-card ===
{{main|h-card}}

The '''h-card''' microformat is for marking up people and organizations. This is an update to [[hCard]].

root class name: '''<code>h-card</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-card</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>p-honorific-prefix</code>'''
* '''<code>p-given-name</code>'''
* '''<code>p-additional-name</code>'''
* '''<code>p-family-name</code>'''
* '''<code>p-sort-string</code>'''
* '''<code>p-honorific-suffix</code>'''
* '''<code>p-nickname</code>'''
* '''<code>u-email</code>'''
* '''<code>u-logo</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>'''
* '''<code>u-uid</code>'''
* '''<code>p-category</code>'''
* '''<code>p-adr</code>'''
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-street-address</code>'''
* '''<code>p-locality</code>'''
* '''<code>p-region</code>'''
* '''<code>p-postal-code</code>'''
* '''<code>p-country-name</code>'''
* '''<code>p-label</code>'''
* '''<code>p-geo</code>''' or '''<code>u-geo</code>''' with a RFC 5870 geo: URL, new in [[vCard4]] ([[RFC6350]])
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-tel</code>'''
* '''<code>p-note</code>'''
* '''<code>dt-bday</code>'''
* '''<code>u-key</code>'''
* '''<code>p-org</code>'''
* '''<code>p-job-title</code>''' - previously 'title' in hCard, disambiguated.
* '''<code>p-role</code>
* '''<code>u-impp</code>''' per RFC 4770, new in [[vCard4]] ([[RFC6350]])
* '''<code>p-sex</code>''' new in [[vCard4]] ([[RFC6350]])
* '''<code>p-gender-identity</code>''' new in [[vCard4]] ([[RFC6350]])
* '''<code>dt-anniversary</code>''' new in [[vCard4]] ([[RFC6350]])
* ...

Reserved properties: (properties not used much (if at all) in practice)
* '''<code>p-organization-name</code>'''
* '''<code>p-organization-unit</code>'''
* '''<code>p-tz</code>'''
* '''<code>dt-rev</code>'''
* ...

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-card" is found, don't look for a "vcard" on the same element.

compat root class name: <code id="vcard">vcard</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>honorific-prefix</code>
* <code>given-name</code>
* <code>additional-name</code>
* <code>family-name</code>
* <code>honorific-suffix</code>
* <code>nickname</code>
* <code>email</code> - parse as '''u-'''
* <code>logo</code> - parse as '''u-'''
* <code>photo</code> - parse as '''u-'''
* <code>url</code> - parse as '''u-'''
* <code>uid</code> - parse as '''u-'''
* <code>category</code>
* <code>adr</code> - parse as '''<code>p-adr h-adr</code>''' including compat root class <code>adr</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>
* <code>label</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root class <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* <code>tel</code>
* <code>note</code>
* <code>bday</code> - parse as '''dt-'''
* <code>key</code> - parse as '''u-'''
* <code>org</code>
* <code>organization-name</code>
* <code>organization-unit</code>
* <code>title</code> - parse as '''p-job-title'''
* <code>role</code>
* ...

Reserved: (backward compat properties that parsers {{may}} implement, if they do, they {{must}} implement in this way:
* <code>tz</code>
* <code>rev</code> - parse as '''dt-'''
* ...

Note: use of 'value' within 'tel' should be automatically handled by the support of the [[value-class-pattern]]. And for now, the 'type' subproperty of 'tel' is dropped/ignored. If there is demonstrable documented need for additional tel types (e.g. fax), we can introduce new flat properties as needed (e.g. p-tel-fax).

=== h-entry ===
{{main|h-entry}}

The '''h-entry''' microformat is for marking up syndicatable content such as blog posts, notes, articles, comments, photos and similar. This is an update to [[hAtom]].

root class name: '''<code>h-entry</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-entry</nowiki>

properties:
* '''<code>p-name</code>''' (was p-entry-title, see issues)
* '''<code>p-summary</code>''' (was p-entry-summary, see issues)
* '''<code>e-content</code>''' (was e-entry-content, see issues)
* '''<code>dt-published</code>'''
* '''<code>dt-updated</code>'''
* '''<code>p-author</code>'''
* '''<code>p-category</code>'''
* '''<code>u-url</code>'''
* '''<code>u-uid</code>'''
* '''<code>p-geo</code>'''
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''

This is an update to [[hAtom]].

Brainstorming:

The following properties are proposed additions to h-entry above and beyond what hAtom (or Atom) provides, based on various existing link preview markup conventions:
* '''<code>u-photo</code>'''
* '''<code>u-audio</code>''' - consider special u- parsing rules for <code><audio></code>
* '''<code>u-video</code>''' - consider special u- parsing rules for <code><video></code>
* '''<code>u-in-reply-to</code>''' - for links to other posts that this post is a reply to (comment regarding, etc.)

Backward compatibility:

(*)hAtom-specific implementations that perform custom display or translation (e.g. to Atom XML) {{should}} prefer <code>p-name</code> over <code>p-entry-title</code>, and use <code>p-entry-title</code> value(s) as a fallback if there is no <code>p-name</code>.

For hAtom backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-entry" is found, don't look for a "hentry" on the same element.

compat root class name: <code id="hentry">hentry</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>entry-title</code> - parse as '''<code>p-name</code>'''
* <code>entry-summary</code>
* <code>entry-content</code> - parse as '''e-'''
* <code>published</code> - parse as '''dt-'''
* <code>updated</code> - parse as '''dt-'''
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>category</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* ...

<span id="h-entry-faq">FAQ:</span>
<div class="discussion">
* '''What is the <code>p-name</code> of a [http://indiewebcamp.com/note note]?'''
** A few options, from simplest to most detailed.
*** '''same as the p-content/e-content''' property.
*** '''same as the <code>title</code> element''' on the note permalink post page. When publishing a note on its own permalink post page, the contents of the note are likely abbreviated for the title of the page. The same abbreviation can be used for the p-name.
*** '''first sentence of the p-content/e-content''' property. It may be better for [http://indiewebcamp.com/syndication syndication] and [[link-preview]] purposes to provide just the first sentence of the note as the <code>p-name</code>. Similarly if only a portion of the content is syndicated to other sites, that portion can be marked up as the <code>p-summary</code>.
* ...
</div>

Resolved Issues:
* 2012-245 Resolved. See [http://krijnhoetmer.nl/irc-logs/microformats/20120830#l-120 2012-243 IRC discussion/consensus] for:
** Use '''<code>p-summary</code> instead of <code>p-entry-summary</code>'''. The historical semantic of "entry-summary" is not different from "summary" in any significant (or discernible way). Collapsing the two will simplify the overall microformats2 vocabularies further. In microformats2, entry-summary is no more.
** Use '''<code>e-content</code> instead of <code>e-entry-content</code>'''. Same point and advantage. In microformats2, entry-content is no more.
** '''drop <code>p-entry-title</code>'''. Unnecessary and subsumed by "p-name". Would consider move to backward compat only if cases are presented - known publishing uses are expected to be updated shortly.

=== h-event ===
{{main|h-event}}

The '''h-event''' microformat is for marking up events. This is an update to [[hCalendar]].

root class name: '''<code>h-event</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-event</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>p-summary</code>'''(*)
* '''<code>dt-start</code>'''
* '''<code>dt-end</code>'''
* '''<code>dt-duration</code>'''
* '''<code>p-description</code>'''
* '''<code>u-url</code>'''
* '''<code>p-category</code>'''
* '''<code>p-location</code>'''
* '''<code>p-geo</code>'''
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* ...

This is an update to [[hCalendar]].

(*)hCalendar-specific implementations that perform custom display or translation (e.g. to iCalendar .ics) {{should}} prefer <code>p-name</code> over <code>p-summary</code>, and use <code>p-summary</code> value(s) as a fallback if there is no <code>p-name</code>.

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-event" is found, don't look for a "vevent" on the same element.

compat root class name: <code id="vevent">vevent</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> - parse as '''<code>p-name</code>'''
* <code>dtstart</code> - parse as '''<code>dt-start</code>'''
* <code>dtend</code> - parse as '''<code>dt-end</code>'''
* <code>duration</code> - parse as '''<code>dt-duration</code>'''
* <code>description</code>
* <code>url</code> - parse as '''u-'''
* <code>category</code>
* <code>location</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>, and compat root <code>adr</code> in the absence of <code>h-adr</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* ...

=== h-geo ===
{{main|h-geo}}

The '''h-geo''' microformat is for marking up WGS84 geophysical coordinates. This is an update to [[geo]].

root class name: '''<code>h-geo</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-geo</nowiki>

properties:
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-geo" is found, don't look for an "geo" on the same element.

compat root class name: <code id="geo">geo</code>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>latitude</code>
* <code>longitude</code>

=== h-item ===
{{main|h-item}}

The '''h-item''' microformat is for marking up the item of an [[h-review]] or [[h-product]]. This is an update to part of [[hReview]].

root class name: '''<code>h-item</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-item</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>'''

Note: in practice, due to the microformats2 implied property rules, it is expected that most uses of "h-item" won't require any explicit properties at all (since microformats2 parsers will infer name, photo, and url properties from the structure of the element with "h-item" and its contained content/elements if any).

=== h-product ===
{{main|h-product}}

The '''h-product''' microformat is for marking up products. This is an update to [[hProduct]].

root class name: '''<code>h-product</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-product</nowiki>

properties:
* '''<code>p-name</code>''' - name of the product
* '''<code>u-photo</code>''' - photo of the product
* '''<code>p-brand</code>''' - manufacturer, can also be a nested <code>h-card</code>
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>e-description</code>'''
* '''<code>u-url</code>''' - URL of the product
* '''<code>u-identifier</code>''' - includes type (e.g. mpn, upc, isbn, issn, sn, vin, sku etc.) and value.
* '''<code>p-review</code>''' - a review of the product, can also be a nested <code>h-review</code>
* '''<code>p-price</code>''' - retail price of the product

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-product" is found, don't look for an "hproduct" on the same element.

compat root class name: <code id="hproduct">hproduct</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>photo</code> - parse as '''u-'''
* <code>brand</code>
* <code>category</code>
* <code>description</code>
* <code>identifier</code> - parse as '''u-'''
* <code>url</code> - parse as '''u-'''
* <code>review</code> - including compat root class <code>hreview</code> in the absence of <code>h-review</code>
* <code>price</code>

Note: [[hProduct]] has at least one experimental property which has real world adoption due to [[Google]] and [[Bing]] search support of hProduct. Currently this is: '''price'''

=== h-recipe ===
{{main|h-recipe}}

The '''h-recipe''' microformat is for marking up food recipes. This is an update to [[hRecipe]].

root class name: '''<code>h-recipe</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-recipe</nowiki>

properties:
* '''<code>p-name</code>''' - the name of the recipe
* '''<code>p-ingredient</code>''' - describes one or more ingredients used in the recipe.
* '''<code>p-yield</code>''' - Specifies the quantity produced by the recipe, like how many persons it satisfyies
* '''<code>e-instructions</code>''' - the method of the recipe.
* '''<code>dt-duration</code>''' - the time it takes to prepare the meal described by the recipe.
* '''<code>u-photo</code>''' - an accompanying image

Experimental properties with wide adoption
* '''<code>p-summary</code>''' - provides a short summary or introduction
* '''<code>p-author</code>''' - the person who wrote the recipe with <code>h-card</code>
* '''<code>dt-published</code>''' - the date the recipe was published
* '''<code>p-nutrition</code>''' - nutritional information like calories, fat, dietary fiber etc.
* ...

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-recipe" is found, don't look for an "hrecipe" on the same element.

compat root class name: <code id="hrecipe">hrecipe</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>ingredient</code>
* <code>yield</code>
* <code>instructions</code> - parse as '''e-'''
* <code>duration</code> - parse as '''dt-'''
* <code>photo</code> - parse as '''u-'''
* <code>summary</code>
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>nutrition</code>

Note: [[hRecipe]] has a number of experimental properties which have real world adoption due to [[Google]] recipe search support of hRecipe. These are: summary, author, published and nutrition

=== h-resume ===
{{main|h-resume}}

The '''h-resume''' microformat is for marking up resumes. This is an update to [[hResume]].

root class name: '''<code>h-resume</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-resume</nowiki>

properties:
* '''<code>p-summary</code>''' - overview of qualifications and objectives
* '''<code>p-contact</code>''' - current contact info in an <code>h-card</code>
* '''<code>p-education</code>''' - an education <code>h-calendar</code> event, years, nested <code>h-card</code> of the school, location.
* '''<code>p-experience</code>''' - a job or other professional experience <code>h-calendar</code> event, years, nested <code>h-card</code> of the organization, location, job-title.
* '''<code>p-skill</code>''' - a skill or ability, optionally including level and/or duration of experience
* '''<code>p-affiliation</code>''' - an affiliation with an <code>h-card</code> organization

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-resume" is found, don't look for an "hresume" on the same element.

compat root class name: <code id="hresume">hresume</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code>
* <code>contact</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>education</code> - including compat root <code>vevent</code> in the absence of <code>h-event</code>
* <code>experience</code> - including compat root <code>vevent</code> in the absence of <code>h-event</code>
* <code>skill</code>
* <code>affiliation</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>

Note: skill has a [[hresume-skill-brainstorm|proposed expansion into competency]] with explicit summary, rating and/or duration components. Based on existing real world adoption, we should consider an h-competency vocabulary with p-summary, p-rating, and dt-duration properties.

=== h-review ===
{{main|h-review}}

The '''h-review''' microformat is for marking up reviews. This is an update to [[hReview]]. See also [[h-item]].

root class name: '''<code>h-review</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-review</nowiki>

properties:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed i.e. 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
* '''<code>dt-reviewed</code>''' - date time of when the review was written
* '''<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-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>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>u-url</code>''' - URL of the review

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review" is found, don't look for an "hreview" on the same element.

compat root class name: <code id="hreview">hreview</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> parse as '''<code>p-name</code>'''
* <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>reviewer</code> - including compat root vcard in the absence of h-card
* <code>dtreviewed</code> - parse as '''dt-'''
* <code>rating</code>
* <code>best</code>
* <code>worst</code>
* <code>description</code> - parse as '''e-'''
* <code>rel="tag"</code> - parse as '''p-category'''
* <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>. Microformats2 parsers {{should}} map these URLs into the page scoped rel collection.

=== h-review-aggregate ===
{{main|h-review-aggregate}}

The '''h-review-aggregate''' microformat is for marking up aggregate reviews of a single item. This is an update to [[hreview-aggregate]]. See also [[h-item]].

root class name: '''<code>h-review-aggregate</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-review-aggregate</nowiki>

properties:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed i.e. 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-rating</code>''' - value from 1-5 indicating average rating for the item (5 best).
* '''<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-count</code>''' - number of reviews aggregated.
* '''<code>p-votes</code>''' - number of reviewers who have rated the product, thus contributing to the average rating.
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>u-url</code>''' - URL of the review

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review-aggregate" is found, don't look for an "hreview-aggregate" on the same element.

compat root class name: <code id="hreview-aggregate">hreview-aggregate</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> parse as '''<code>p-name</code>'''
* <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>rating</code>
* <code>best</code>
* <code>worst</code>
* <code>count</code>
* <code>votes</code>
* <code>rel="tag"</code> - parse as '''p-category'''
* <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.

=== v2 vocab notes ===
Notes:
* All v2 vocabularies are defined as flat lists of properties of an object/item, and thus can be used in microformats-2 syntax as shown, or in microdata items, or RDFa. The microformats-2 property parsing prefixes "p-", "u-", "dt-", "e-" are omitted when using defined properties in microdata itemprop and RDFa property as those syntaxes have their own element-specific parsing rules.
* Profile URLs are provided for use with the HTML4 <code>profile</code> attribute, microdata <code>itemtype</code> attribute, and RDFa <code>vocab</code> & <code>typeof</code> attributes (though the latter requires slicing off the trailing segment of the profile for the typeof attribute, and leaving the rest in vocab).
* microformats2 properties may also be explicitly bound as URIs using [[rel-profile]], the [[html5-profile]] attribute proposal, or an HTML5 'vocab' attribute instead. If URI bound terms are important to you, please express interest on [[rel-profile]], [[html5-profile]], or contribute to an [[html5-vocab]] draft.

=== v2 vocab to-do ===
To do:
* write a simple tutorial for creating/getting started with microformats-2 markup for new content
* examples in each h-* spec listed above of how to embed other microformats in them
* actual profile documents at <nowiki>http://microformats.org/profile/h-*</nowiki> URLs mentioned above.
* Provide any necessary microdata-specific language as needed (e.g. to be comparably understandable to the [http://www.whatwg.org/specs/web-apps/current-work/#vcard sample vCard4/hCard1 microdata vocabulary]. Also provide any necessary RDFa-specific language as needed. Both preferably in a generic vocabulary-independent way.
* write a porting guide mapping v1 property -> v2 property
** use-case: simple search/replace in templates (e.g. in case web author doesn't remember existing microformats vocabs and where they used them).
** advise using *both* in existing templates (e.g. in case some CSS depends on the existing microformats)
* analyzie/document how well the microformats2 model and vocabularies satisfy the [http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2009-May/019681.html use-cases used to design/create microdata].

== combining microformats ==
Since microformats2 uses simple flat sets of properties for each microformat, multiple microformats are combined to indicate additional structure.

=== h-event location h-card ===
Events commonly have venue information with additional structure, like address information. For example:

<syntaxhighlight lang="html">
<div class="h-event">
<a class="p-name u-url" href="http://indiewebcamp.com/2012">
IndieWebCamp 2012
</a>
from <time class="dt-start">2012-06-30</time>
to <time class="dt-end">2012-07-01</time> at
<span class="p-location h-card">
<a class="p-name p-org u-url" href="http://geoloqi.com/">
Geoloqi
</a>,
<span class="p-street-address">920 SW 3rd Ave. Suite 400</span>,
<span class="p-locality">Portland</span>,
<abbr class="p-region" title="Oregon">OR</abbr>
</span>
</div>
</syntaxhighlight>

The nested h-card used to structure the p-location of the h-event is represented as a structured value for "location" in the JSON, which has an additional key, "value" that represents the plain text version parsed from the p-location.

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-event"],
"properties": {
"name": ["IndieWebCamp 2012"],
"url": ["http://indiewebcamp.com/2012"],
"start": ["2012-06-30"],
"end": ["2012-07-01"],
"location": [{
"value": "Geoloqi",
"type": ["h-card"],
"properties": {
"name": ["Geoloqi"],
"org": ["Geoloqi"],
"url": ["http://geoloqi.com/"],
"street-address": ["920 SW 3rd Ave. Suite 400"],
"locality": ["Portland"],
"region": ["Oregon"]
}
}]
}
}]
}
</syntaxhighlight>

Questions:
<div class="discussion">
* Should the nested hCard be present also as a top-level item in the JSON? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
** My current (2012-243) leaning is no. - [[User:Tantek|Tantek]] 18:53, 30 August 2012 (UTC)
** If so, how do we avoid expansion of the JSON geometrically proportional to the depth of microformat nesting? (Or do we not worry about it?)
* Should there be a canonical hierarchical JSON and a canonical flattened JSON? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
** My current (2012-243) leaning is no, we stick with one canonical JSON for uf2 which is hierarchical. - [[User:Tantek|Tantek]] 18:53, 30 August 2012 (UTC)
** If so, should the flattened JSON have references from properties to nested microformats that have been pushed to the top level per flattening? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
*** If so, what convention does/do JSON follow for such synthetic local reference identifiers? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
</div>

Notes:
* The 'location' value reflects the visible text of its element, including spaces and punctuation, as well as the state abbreviation 'OR'. The 'h-card' property values are only what is marked up, and thus include structure values without extra punctuation, and the state takes the expanded form from the <code>title</code> attribute of its <code><abbr></code> element.

=== h-card org h-card ===
People often publish information general to their company rather than specific to them, in which case, they may wish to encapsulate that in separately nested microformat. E.g. here is a simple h-card example with org property:

[http://blog.lizardwrangler.com Mitchell Baker] (Mozilla Foundation)

with source:
<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<span class="p-org">Mozilla Foundation</span>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": ["Mozilla Foundation"]
}
}]
}
</syntaxhighlight>

Sometimes such organization affiliations are hyperlinked to the website of the organization:

[http://blog.lizardwrangler.com Mitchell Baker] ([http://mozilla.org/ Mozilla Foundation])

You can mark that up with a nested h-card:
<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
</syntaxhighlight>

Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an <code><a href></code> would.

'''FOR PARSERS ONLY:'''

The nested 'h-card' could be marked up as an 'h-org' as well, which adds it to the nested microformat's type array, all as part of the property specified by the 'p-org'.

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card h-org"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card", "h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
</syntaxhighlight>

'''FOR PARSERS ONLY:'''

Without a property class name like 'p-org' holding all the nested objects together, we need to introduce another array for nested children (similar to the existing DOM element notion of children) of a microformat that are not attached to a specific property:

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card","h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
</syntaxhighlight>

Since there's no property class name on the element with classes 'h-card' and 'h-org', the microformat representing that element is collected into the children array.

Such a nested microformat implies some relationship (containment, being related), but is not as useful as if the nested microformat was a specific property of its parent.

For this reason it's recommended that authors should not publish nested microformats without a property class name, and instead, when nesting microformats, authors should always specify a property class name (like 'p-org') on the same element as the root class name(s) of the nested microformat(s) (like 'h-card' and/or 'h-org').

'''FOR PARSERS ONLY:'''

Or the nested object could be only marked up with 'h-card'. Source:

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
</syntaxhighlight>

'''TO DO: Add h-event h-card example and JSON, per real world publishing examples like [http://www.swingtime.co.uk/List/ClSouth.html Swing Time: Classes in Southern England].'''

== authoring ==
=== minimal markup ===
The best way to use microformats-2 is with as little additional markup as possible. This keeps your code cleaner, improves its maintainability, and thus the quality and longevity of your microformats.

One big advantage of microformats-2 over previous microformats (and others) is the ability to add one class name to an existing element to create a structured item.

See the [[microformats-2#simple_microformats_2_examples|simple examples at the top]] for a start, e.g.

Simple hCards work just by adding <code>class="h-card"</code> :
<syntaxhighlight lang="html">
<span class="h-card">Frances Berriman</span>

<a class="h-card" href="http://benward.me">Ben Ward</a>

<img class="h-card" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>

<a class="h-card" href="http://tantek.com">
<img alt="Tantek Çelik" src="http://ttk.me/logo.jpg"/>
</a>
</syntaxhighlight>

* Tip: Inside an open tag, put the <code>class</code> attribute <em>first</em>, then any human text content attributes (e.g. <code>alt</code>), then URL attributes (e.g. <code>href</code> <code>src</code>), and lastly other attributes (e.g. <code>style</code>). Putting the class attribute first ties it closely to the element name/tag itself, makes it more obvious, and thus more likely to be kept up to date.

=== backward compatible ===
If you depend on current microformats [[implementations]], while they're being updated to support [[microformats2]], you can include both existing classic microformats and microformats2 markup.

In short: use both sets of class names simultaneously.

When doing so, use them on the same element, with the microformats-2 class name first, followed immediately by the existing microformats class name.

Here are the microformats-2 hCards from above with current [[hCard]] markup as well, which may require adding a wrapping element (e.g. a <code><span></code>) to separate the root class name element from explicit property class name elements:

<syntaxhighlight lang="html">
<span class="h-card vcard">
<span class="p-name fn">Frances Berriman</span>
</span>

<span class="h-card vcard">
<a class="p-name fn u-url url" href="http://benward.me">Ben Ward</a>
</span>

<span class="h-card vcard">
<img class="p-name fn u-photo photo" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>
</span>

<span class="h-card vcard">
<a class="u-url url" href="http://tantek.com">
<img class="p-name fn u-photo photo" alt="Tantek Çelik"
src="http://ttk.me/logo.jpg"/>
</a>
</span>
</syntaxhighlight>

Tips:
* use the microformats-2 class name first, e.g.
** <code>class="h-card vcard"</code>
** <code>class="u-url url"</code>
* and pair them when using an element for multiple properties, e.g.:
** <code>class="p-name fn u-url url"</code>
** <code>class="p-name fn u-photo photo"</code>
* put microformats classes after classes for CSS (since page authors will likely interact more with their own classes for design than with microformats classes), e.g. as used on individual microformats [[events]] pages:
** <code>class="event-page h-event vevent"</code>

The prefixes (h-, p-, etc.) of microformats2 class names provide easier recognition, and when followed by the similarly named existing class name, they're more easily recognized as related and thus kept together when the markup is maintained over time.

Related FAQ: [[microformats2-faq#when_using_both_h-card_and_vcard_which_should_be_first_and_why|When using both h-card and vcard which should be first and why?]]

== extensions ==
microformats2 is extensible by means of two separate but syntactically similar extension prefixes for experiments intended to be iterated & evolved and for vendor specific extensions not intended for standardization.

=== experimental extensions ===
There have been times when specific sites have wanted to extend microformats beyond the set of properties in the microformat vocabulary, and currently lack any '''experimental''' way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus:

For experimental extensions for the purpose of prototyping to learn more, iterate, towards possibly standardizing, use the <code>-x-</code> prefix before root and property class names.

Specifically:
* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a literal 'x' for an experimental extension

Examples:
* "p-x-prep-time" - a possible experimental property name to be added to [[h-recipe]] upon consideration/documentation of real-world usage/uptake.

See [[microformats2-experimental-properties]] for more examples.

=== <span id="VENDOR_EXTENSIONS">vendor extensions</span> ===
For vendor specific extensions, microformats2 uses a mechanism similar to CSS vendor extensions, using a similar syntax as experimental extensions, except with a vendor prefix instead of a literal 'x'.

* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-, numbers allowed after first character)

Examples:
* "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "one-ring" microformat root class name.
* "p-goog-preptime" - to represent [http://www.google.com/support/webmasters/bin/answer.py?answer=173379 Google's "preptime" property extension] to [[hRecipe]] (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.)

See [[vendor-prefixes]] for more examples.

=== extensions background ===
This extensibility mechanism is a composition of the following (at least somewhat) successful extension syntaxes:
* [http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords CSS 2.1 4.1.2.1 Vendor-specific extensions]
* IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [http://en.wikipedia.org/wiki/Internet_media_type]
* IETF MIME experimental fields (e.g. x-spam-score)
* HTTP header extensions (e.g. x-pingback)
* note also [http://www.mnot.net/blog/2009/02/18/x- some critical thoughts from mnot]

In particular:

Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.

Proprietary or experimental CSS3 property implementations have been very successful.

There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like:

* -moz-border-radius
* -webkit-border-radius

etc.

Note that these are merely string '''prefixes''', not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use.

This use of vendor specific CSS properties allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.

The benefits have been two-fold:
* designers have been able to make more attractive sites sooner (at least in some browsers)
* features have been market / real-world tested before being fully standardized, thus resulting in better features

Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and [https://secure.wikimedia.org/wikipedia/en/wiki/List_of_HTTP_header_fields#Common_non-standard_headers Wikipedia: HTTP header fields - non-standard headers] (could use RFC reference instead) respectively, like:

* application/x-latex (per [https://secure.wikimedia.org/wikipedia/en/wiki/Internet_media_type#Type_x Wikipedia Internet media type: Type x])
* x-spam-score (in email headers)
* X-Pingback (per [http://en.wikipedia.org/wiki/Pingback Wikipedia:Pingback])

Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases:

* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])

See [[microformats2-origins#VENDOR_EXTENSIONS]] for more background.

== validators ==
microformats2 validators:

{{new}} Test your microformatted web page with:
* https://pin13.net/mf2/

Barnaby Walters has a hosted version of the open source php-mf2 [[parser]] where you can enter your markup into a textarea and see how it's parsed:
* http://waterpigs.co.uk/php-mf2/

See the [[validators]] page for a longer list of validators.

== Examples in the wild ==
Please add new examples in the wild of microformats-2 to the top of this list. When it gets too big we can move it to a separate page like [[microformats-2-examples-in-wild]].

* ...
* David John Mead marks up his profile, blog posts and comments with h-card, h-entry and h-cite on [http://davidjohnmead.com davidjohnmead.com]
* [[User:Brian|Brian Suda]] marks up his blog posts up with h-entry and h-card on [http://optional.is/required/ optional.is]
* Ashton McAllan marks up her blog posts, reposts, comments and likes with h-entry, h-card and h-cite on [https://acegiak.net/ acegiak.net]
* Emma Kuo marks up her blog posts and notes with h-entry and h-card on [http://notenoughneon.com/ notenoughneon.com]
* Scott Jenson marks up his blog posts with h-entry and h-card on [http://jenson.org/ jenson.org]
* Emily McAllen marks up her blog posts with h-entry and h-card on [http://blackwoolholiday.com/ blackwoolholiday.com]
* Ryan Barrett marks up his blog posts, notes, replies and likes with h-entry and h-card on [https://snarfed.org/ snarfed.org]
* Barry Frost marks up his notes with h-entry, h-card and h-cite on [http://barryfrost.com/ barryfrost.com]
* Amber Case marks up her profile, blog posts, replies and notes with h-entry and h-card on [http://caseorganic.com/ caseorganic.com]
* Johannes Ernst marks up his blog posts with h-entry on [http://upon2020.com/blog/ upon2020.com]
* Michiel de Jong marks up his profile and notes with h-entry and h-card on [https://michielbdejong.com/ michielbdejong.com]
* Mike Taylor marks up his profile and blog posts with h-card and h-entry on [https://bear.im/bearlog/ bear.im]
* Erin Jo Ritchey marks up her profile, posts and comments using h-card, h-entry and h-cite with idno on [http://erinjo.is/ erinjo.is]
* Jeena Paradies marks up his profile, blog posts, notes and comments using h-card, h-entry and h-cite on [https://jeena.net/ jeena.net]
* Andy Sylvester marks up his profile, blog posts and comments using h-card and h-entry on [http://andysylvester.com/2014/03/01/howto-setting-up-the-selfoss-feed-reader-with-microformats-support/ andysylvester.com] (note: as of 2014-03-13 using h-entry for comments instead of correct h-cite --[[User:Barnabywalters|bw]] 14:44, 13 March 2014 (UTC))
* Hakan Demir marks up his Coupon and Voucher blog posts with h-entry and h-card on [http://www.gutscheinflagge.de/ gutscheinflagge.de]
* Chloe Weil marks up her blog posts with h-entry on [http://chloeweil.com/blog chloeweil.com]
* Christophe Ducamp marks up his blog posts and profile with h-entry and h-card on [http://christopheducamp.com/ christopheducamp.com]
* Glenn Jones marks up his blog posts, notes, replies, profile and comments with h-entry, h-card and h-cite on [http://glennjones.net/ glennjones.net]
* Marcus Povey marks up his blog posts and profile with h-entry and h-card on [http://www.marcus-povey.co.uk/ marcus-povey.co.uk]
* Eugen Busoiu marks up his web profile with h-card on [http://eugenbusoiu.com/#utm_source=microformats2&utm_medium=h-card&utm_campaign=Microformats eugenbusoiu.com]]
* Matthias Pfefferle marks up his blog posts, comments and profile with h-card, h-cite and h-entry on [http://notizblog.org/ notizblog.org]
* Kyle Mahan marks up his profile and notes with h-card and h-entry on [http://kylewm.com/ kylewm.com]
* Emil Björklund marks up his blog posts with h-entry and h-card ([http://thatemil.com/blog/2013/09/16/webmentioning-adactio/ example])
* App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 ([https://alpha.app.net/voidfiles example])
* Brett Comnes marks up his posts with h-entry and h-card ([http://bret.io/2013/06/29/getting-started-with-bower/ example])
* Ben Werdmuller marks up his posts with h-card and h-entry, u-in-reply-to and u-like ([http://werd.io/view/51d5097fbed7ded0633a5956 example])
* Sandeep Shetty marks his posts up with h-card and h-entry, as well as draft u-in-reply-to and experimental u-like properties ([http://sandeep.io/101 example])
* Laurent Eschenauer marks up his posts with h-entry ([http://eschnou.com/entry/first-autonomous-flight-of-my-nodecopter-62-24992.html example])
* Tom Morris marks up his posts using h-entry ([http://tommorris.org/posts/8417 example])
* Sinolandquality marks up some of their content using h-feed and h-entry on [http://www.sinolandquality.com/Blog/?page_id=3516&utm_content=buffere4d40&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer sinolandquality.com]
* [http://www.w3.org/conf/ W3Conf 2013] uses h-event for the main event, and h-card for all the speakers and notable attendees. The h-cards make particularly good use of implied name, url, and photo properties.
* [http://wordpress.org/extend/themes/sempress SemPress] is a WordPress theme that supports h-card, h-feed/h-entry and h-as-*
* [http://the-pastry-box-project.net/ The Pastry Box Project] use h-card and h-entry markup on their homepage and individual thoughts pages
* Tom Morris uses h-card and [[XFN]] to markup [http://tommorris.org/pages/blogroll his blogroll].
* Aaron Parecki uses h-card to markup both authorship and references to people in his notes permalinks, e.g. [http://aaronparecki.com/2012/230/reply/1 2012/230/reply/1].
* [http://tantek.com/ Tantek Çelik] uses h-card, h-event, and h-entry on his home page, as well as h-entry on all post permalinks, e.g. [http://tantek.com/2012/243/t1/name-beats-title-modern-use-dubline-core-wrong-uf2 2012-243 post], with [[rel-prev]]/[[rel-next]] (if applicable) to indicate prev/next posts, and with [[rel-author]] to his home page with canonical hCard to indicate authorship.
* [http://waterpigs.co.uk/ Barnaby Walters] uses h-card on his home page, h-card, h-entry and XFN markup on his [http://waterpigs.co.uk/notes notes page].
** 2013-01-25 Barnaby Walters: <cite>[http://waterpigs.co.uk/articles/experimental-markup Experimental Markup]</cite> - describes how he's using microformats2 vocabularies: <code>h-adr</code>, <code>h-card</code>, <code>h-entry</code>, <code>h-event</code>, <code>h-geo</code>, <code>h-review</code>, and experimental vocabularies: <code>h-feed</code> (embedded for update histories), [[activity-streams]] objects <code>h-as-article</code>, <code>h-as-collection</code>, <code>h-as-note</code>, <code>h-as-update</code>, as well as experimental properties: <code>u-alternate</code> and <code>u-as-downstream-duplicate</code> (links to POSSE copies), and <code>u-in-reply-to</code> (links to content that the posts are in reply to).
* [http://tantek.com/presentations/2012/06/microformats microformats.org at 7 years] presentation with h-event and h-card markup for people and organizations.
* [http://tantek.com/presentations/2012/06/pdf2012-indieweb.html Rise of the Indie Web hCards] (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has [[microformats-2]] h-calendar and h-card markup
* WebMaker by Mozilla has [[microformats-2]] h-calendar and h-card on event search (e.g. [https://webmaker.org/en-US/events/near/?lat=45.5234515&lng=-122.6762071 search near Portland Oregon]) and event pages (e.g. [https://webmaker.org/en-US/events/192f56eb9/ IndieWebCamp 2012]).[https://twitter.com/microformats/status/212207925643587585]
* WebFWD by Mozilla has [[microformats-2]] h-card markup on [https://webfwd.org/about/experts/ experts] and [https://webfwd.org/about/team/ team] pages
* [http://indiewebcamp.com IndieWebCamp] has [[microformats-2]] h-event markup with nested h-cards for the organizers and the location.
* [https://wiki.mozilla.org/Events Mozilla Events] page has [[microformats-2]] h-event markup with attendees marked up with h-card.
* The [http://pdx.esri.com/blog/2013/10/17/introducing-mapattack/ Esri PDX Blog] has h-entry markup on all blog posts (as of 2013-10-19), and h-product markup on [http://pdx.esri.com/projects/terraformer/ project pages]

=== offline ===
* spreadly marks up share permalink pages with h-entry, as well as minimal h-cards and experimental p-like properties

== Implementations ==
Test your microformatted web page with:

=== Live Textarea Input ===
Use any of these to enter HTML+microformats2 markup and see the parsed result!

* https://microformats.io hosts several of the parser libraries listed below for interactive testing
** https://go.microformats.io
** https://node.microformats.io/
** https://php.microformats.io/
** https://python.microformats.io/
** https://ruby.microformats.io/
** or look for "Parser Libraries" on the homepage
* https://pin13.net/mf2/ (where it says "Microformats Parser")


=== Blogging tools ===
* '''Storytlr''' parses the <code>target</code> from [http://indiewebcamp.com/pingback pingbacks] for [https://github.com/storytlr/storytlr/blob/master/protected/application/public/controllers/PingbackController.php#L63 h-entry with properties and nested h-card] for information to automatically display in the [http://web.archive.org/web/20130425010536/http://eschnou.com/entry/testing-indieweb-federation-with-waterpigscouk-aaronpareckicom-and--62-24908.html comments section on a post] (archived; [http://eschnou.com/entry/testing-indieweb-federation-with-waterpigscouk-aaronpareckicom-and--62-24908.html original]).
** Note: per storytlr.org, retrieved 2022-05-22:
<blockquote>Storytlr is no longer maintained and '''might be unsafe to run on a public server'''. It is running on an old version of PHP and the Zend framework and has not been upgraded to latest versions and security patches.</blockquote>

=== Converters ===
* '''[https://github.com/snarfed/granary granary]''' is a library and REST API that converts between silo APIs, [[ActivityStreams]], [[microformats2]], and Atom (all directions). Supported silos include Facebook, Twitter, Instagram, Google+, and Flickr. Users include [http://brid.gy/ Bridgy], [http://reader.kylewm.com/ Woodwind], and [https://facebook-atom.appspot.com/ facebook-atom] and [https://twitter-atom.appspot.com/ twitter-atom], among others.

* '''[http://pipes.yahoo.com/pipes/pipe.info?_id=afc5568b4e8643bfb05436b1caaf91bc microformats to RSS]''' - a Yahoo! pipe that converts a URL containing an [[h-feed]] containing h-entries, into an [[RSS]] feed ([http://waterpigs.co.uk/notes/4SeNi5/ 2013-10-21 blog post announcing])

* '''[https://xray.p3k.io XRay]''' ([https://github.com/aaronpk/XRay source code]) - Returns a normalized representation of the microformats data at a URL

=== Parsers ===
Parsers, open source libraries, in alphabetical order by programming language:

If you are implementing a microformats2 parser, see:
* [[microformats2-parsing]]

==== Parsers in production ====
The following parsers are of very high quality, in active development, and use on live sites on the web in production.

===== Java =====
* [[any23]] Apache Any23 (Anything to Triples)] a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents: http://any23.apache.org

===== Javascript =====
* '''microformats-parser''' for both browser and node.js
** github open source: https://github.com/aimee-gm/microformats-parser (current)
** live: https://aimee-gm.github.io/microformats-parser/

Previously:
* '''microformat-node''' Node.js microformats2 parser
** github open source: https://github.com/microformats/microformat-node (current)
*** forked from https://github.com/glennjones/microformat-node
** test suite: https://github.com/microformats/tests

** command line: https://github.com/JerrySievert/mf2
* '''microformat-shiv''' - cross browser javascript microformats2 parser which can also be used in browser extensions.

** github open source: https://github.com/glennjones/microformat-shiv

===== PHP =====
* '''<span id="php-mf2">php-mf2</span>''' - PHP microformats2 parser
** github open source: https://github.com/indieweb/php-mf2
** Packagist: https://packagist.org/packages/mf2/mf2
** live:
*** textarea entry: http://waterpigs.co.uk/php-mf2/
*** URL and textarea entry: https://pin13.net/mf2/
** [https://github.com/barnabywalters/php-mf-cleaner mf-cleaner]: functions for working with the raw mf2 data structure

===== Python =====
* '''mf2py''' Python microformats2 parser
** main entry: [[mf2py]]
** github open source: https://github.com/tommorris/mf2py
** live:
*** URL entry: [https://mf2py.herokuapp.com/ mf2py.herokuapp.com]
*** textarea entry: https://kartikprabhu.com/connection/mfparser
*** another textarea: http://www.unmung.com/?html=
*** URL and/or textarea: https://kylewm.com/services/mf2

===== Ruby =====
* '''indieweb/microformats-ruby''' Ruby microformats parser
** github open source: https://github.com/indieweb/microformats-ruby
** live text entry: https://microformats-parser-ruby.herokuapp.com

===== Haskell =====
* '''myfreeweb/microformats2-parser''' Haskell microformats2 parser
** github open source: https://github.com/myfreeweb/microformats2-parser
** live textarea entry: https://unrelenting.technology/mf2/

==== Development parsers ====
The following parsers are in-development and have key microformats2 functionality yet are incomplete, not fully tested, or have other limitations. Contributions welcome!

===== Erlang =====
* '''hazybluedot/mf2erl''' Erlang microformats2 parser
** github open source: https://github.com/hazybluedot/mf2erl

===== Elixir =====
* '''ckruse/microformats-elixir''' Elixir microformats2 parser
** github open source: https://github.com/ckruse/microformats2-elixir

===== Go =====
* '''willnorris/microformats''' Golang microformats2 parser
** github open source: https://github.com/willnorris/microformats
** live textarea entry: https://go.microformats.io/

===== Java =====
* '''Apache Any23''' a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents. Supports Microformats1 and 2.
** Download recent release: http://any23.apache.org/download.html
** live: http://any23-vm.apache.org/
** source: http://any23.apache.org/build-src.html
* '''mf2j''' An early-stage Java microformats2 parser
** github open source: https://github.com/kylewm/mf2j
** live: https://mf2j.herokuapp.com/?url={http://example.com}

===== Perl =====
* '''Web::Microformats2''' Perl microformats2 parser
** https://metacpan.org/pod/Web::Microformats2
** open source: https://github.com/jmacdotorg/microformats2-perl

==== Experiments ====
Experiments and other proof of concept microformat2 parsing support.
* '''Rust''' - https://gitlab.com/maxburon/microformats-parser
* ...

=== Outreach ===
* [https://github.com/mozilla/fathom/issues/42 Mozilla Fathom: examples with nested classes, e.g. microformats2]

== Presentations ==
Presentations about microformats2:
* 2013-01-24 <cite>[http://waterpigs.co.uk/presentations/microformats-2/ Microformats 2]</cite> presentation by [[User:Barnabywalters|Barnaby Walters]] at the [[events/2013-01-24-exeter-web-meetup|Exeter Web Meetup]] in Devon, UK.
* 2012-09-21 <cite>[http://tantek.com/presentations/2012/09/microformats2/ microformats2 & bits of HTML5: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-09-21-refreshlx|RefreshLX]] in Lisbon, Portugal.
* 2012-07-21 <cite>[http://tantek.com/presentations/2012/07/html5-uf2/ HTML5 and microformats2: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-07-21-cascadesf|Innovators of the Web conference]] in San Francisco, CA.
* 2012-07-14 <cite>[http://tantek.com/presentations/2012/07/html5-microformats2/ HTML5 and microformats2: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-07-14-open-web-camp-4|Open Web Camp IV]] in San Jose, CA.

== Testimonials ==
* <blockquote class="twitter-tweet">To prove the web standards community can come up with better standards than the SE’s, compare this: http://microformats.org/wiki/microformats-2 with schema . org — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298907685452124160 2013-02-05 13:35]</blockquote>
* <blockquote class="twitter-tweet">... I’m hoping SE’s will pick up microformats2. It’s SO much cleaner. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298911287117758464 2013-02-05 13:49]</blockquote>
* <blockquote class="twitter-tweet">... But damn Microformats2 are sexy. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298912179292344320 2013-02-05 13:53]</blockquote>

== Origins ==
This page was originally used to brainstorm and develop microformats2 in an exploratory manner, with problem statements, questions, lessons learned from past and other formats.

Now that [[microformats2-parsing]] is a Microformats specification, the original brainstorming has been moved to a separate page for anyone who wants to understand more about how we came up with the design of microformats2, and how it evolved in the early years.
* [[microformats2-origins]]

== See Also ==
* [[microformats2]]
* [[microformats2-brainstorming]] - moving more experimental / undeveloped / and rejected thoughts ideas here to simplify/progress *this* page further.
* [[microformats2-experimental-properties]] - listing experimental (-x- prefixed) properties and their use
* [[microformats2-prefixes]]
* [[vendor-prefixes]]
* [[microformats2-faq]]
* [[microformats2-parsing]]
* 2010-05-02 [[events/2010-05-02-microformats-2-0|microformats 2.0 discussion session at FOO East]]

microformats2

2024-03-01T18:55:04Z

GRegorLove: /* Blogging tools */ IA link for Laurent's post, note that Storytlr not maintained and might not be safe to host

<span style="float:right">__TOC__</span>
Welcome to the microformats2 home page.

== Summary ==
Microformats2 is the latest version of microformats, the simplest way to markup structured information in HTML. Microformats2 improves ease of use and implementation for <em>both</em> authors (publishers) and developers ([[microformats2-parsing|parser]] implementers).

Microformats2 replaces and supersedes both classic microformats (sometimes called microformats1), as well as incorporates lessons learned from [[microdata]] and [[RDFa]].

=== simple microformats2 examples ===
Here are a few <span id="simple_microformats_2_examples">simple microformats2 examples</span> along with canonical [[JSON]].

==== person example ====
* Simple person reference:
<syntaxhighlight lang="html">
<span class="h-card">Frances Berriman</span>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Frances Berriman"]
}
}]
}
</syntaxhighlight>

----

==== hyperlinked person ====
* Simple hyperlinked person reference
<syntaxhighlight lang="html">
<a class="h-card" href="http://benward.me">Ben Ward</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Ben Ward"],
"url": ["http://benward.me"]
}
}]
}
</syntaxhighlight>

----

==== hyperlinked person image ====
* Simple hyperlinked person image
<syntaxhighlight lang="html">
<a class="h-card" href="http://rohit.khare.org/">
<img alt="Rohit Khare"
src="https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg" />
</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Rohit Khare"],
"url": ["http://rohit.khare.org/"],
"photo": ["https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg"]
}
}]
}
</syntaxhighlight>

Additional simple cases details in [[microformats-2-implied-properties]].

----

==== detailed person example ====
* More detailed person
<syntaxhighlight lang="html">
<div class="h-card">
<img class="u-photo" alt="photo of Mitchell"
src="https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"/>
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="u-url"
href="https://twitter.com/MitchellBaker"
>@MitchellBaker</a>)
<span class="p-org">Mozilla Foundation</span>
<p class="p-note">
Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities.
</p>
<span class="p-category">Strategy</span>
<span class="p-category">Leadership</span>
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"photo": ["https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"],
"name": ["Mitchell Baker"],
"url": [
"http://blog.lizardwrangler.com/",
"https://twitter.com/MitchellBaker"
],
"org": ["Mozilla Foundation"],
"note": ["Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities."],
"category": [
"Strategy",
"Leadership"
]
}
}]
}
</syntaxhighlight>

----
=== details from examples ===
Details demonstrated by the examples:
# The JSON <code>"type"</code> uses the full microformat root class name (e.g. <code>"h-card"</code>) for consistent identification.
# all properties are optional and syntactically plural with parsed values provided in document order; particular microformats (and applications there-of) may apply specific/singular semantics to first value of a property.

=== microformats2 design ===

microformats2 has the following key design aspects:

; Prefixes for class names
: All microformats class names use prefixes. Prefixes are '''syntax independent from vocabularies''', which are developed separately.
* <code>h-*</code> for root class names (e.g. <code>h-card</code>)
* <code>p-*</code> for plain text properties (e.g. <code>p-name</code>)
* <code>u-*</code> for URL properties (e.g. <code>u-photo</code>)
* <code>dt-*</code> for date/time properties (e.g. <code>dt-bday</code>)
* <code>e-*</code> for embedded markup properties (e.g. <code>e-note</code>)<br />

See [[microformats2-prefixes]] for more details.

; Flat sets of optional properties
: All microformats consist of a root, and a collection of properties. Hierarchical data is represented with nested microformats, typically as property values themselves. Properties are all optional and potentially multivalued (applications needing a singular semantic may use first instance).

; Single class markup for common uses
: Common simple markup patterns require only a single microformat root class name, which parsers use to find a few generic properties: <code>name</code>, <code>url</code>, <code>photo</code>. The simple microformats2 examples above demonstrate these.

----

Parsing each prefix (including generating canonical JSON) is detailed step-by-step in:
* The '''[[microformats2-parsing|microformats2 parsing specification]]'''

'''Note:''' Most properties are specified and used with a single specific prefix (or occasionally two or three) that is self-evident from context. However, any parsing prefix can be used with any property, especially if you find a good reason to do so!

== v2 vocabularies ==
Status: '''<span id="draft_v2_vocabularies">draft</span>'''. Please review and provide feedback in [[IRC]].
* [[h-adr]]
* [[h-card]]
* [[h-entry]]
* [[h-event]]
* [[h-feed]]
* [[h-geo]]
* [[h-item]]
* [[h-listing]]
* [[h-product]]
* [[h-recipe]]
* [[h-resume]]
* [[h-review]]
* [[h-review-aggregate]]

See below for vocabulary summaries.

=== h-adr ===
{{main|h-adr}}

The '''h-adr''' microformat is for marking up structured locations such as addresses, physical and/or postal. This is an update to [[adr]].

root class name: '''<code>h-adr</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-adr</nowiki>

properties:
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-street-address</code>'''
* '''<code>p-locality</code>'''
* '''<code>p-region</code>'''
* '''<code>p-postal-code</code>'''
* '''<code>p-country-name</code>'''
* '''<code>p-label</code>''' - new in [[vCard4]] ([[RFC6350]])
* '''<code>p-geo</code>''' (or '''<code>u-geo</code>''' with a RFC 5870 geo: URL) - new in [[vCard4]] ([[RFC6350]])
* '''<code>p-latitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-longitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-adr" is found, don't look for an "adr" on the same element.

compat root class name: <code id="adr">adr</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>post-office-box</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>

=== h-card ===
{{main|h-card}}

The '''h-card''' microformat is for marking up people and organizations. This is an update to [[hCard]].

root class name: '''<code>h-card</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-card</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>p-honorific-prefix</code>'''
* '''<code>p-given-name</code>'''
* '''<code>p-additional-name</code>'''
* '''<code>p-family-name</code>'''
* '''<code>p-sort-string</code>'''
* '''<code>p-honorific-suffix</code>'''
* '''<code>p-nickname</code>'''
* '''<code>u-email</code>'''
* '''<code>u-logo</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>'''
* '''<code>u-uid</code>'''
* '''<code>p-category</code>'''
* '''<code>p-adr</code>'''
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-street-address</code>'''
* '''<code>p-locality</code>'''
* '''<code>p-region</code>'''
* '''<code>p-postal-code</code>'''
* '''<code>p-country-name</code>'''
* '''<code>p-label</code>'''
* '''<code>p-geo</code>''' or '''<code>u-geo</code>''' with a RFC 5870 geo: URL, new in [[vCard4]] ([[RFC6350]])
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-tel</code>'''
* '''<code>p-note</code>'''
* '''<code>dt-bday</code>'''
* '''<code>u-key</code>'''
* '''<code>p-org</code>'''
* '''<code>p-job-title</code>''' - previously 'title' in hCard, disambiguated.
* '''<code>p-role</code>
* '''<code>u-impp</code>''' per RFC 4770, new in [[vCard4]] ([[RFC6350]])
* '''<code>p-sex</code>''' new in [[vCard4]] ([[RFC6350]])
* '''<code>p-gender-identity</code>''' new in [[vCard4]] ([[RFC6350]])
* '''<code>dt-anniversary</code>''' new in [[vCard4]] ([[RFC6350]])
* ...

Reserved properties: (properties not used much (if at all) in practice)
* '''<code>p-organization-name</code>'''
* '''<code>p-organization-unit</code>'''
* '''<code>p-tz</code>'''
* '''<code>dt-rev</code>'''
* ...

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-card" is found, don't look for a "vcard" on the same element.

compat root class name: <code id="vcard">vcard</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>honorific-prefix</code>
* <code>given-name</code>
* <code>additional-name</code>
* <code>family-name</code>
* <code>honorific-suffix</code>
* <code>nickname</code>
* <code>email</code> - parse as '''u-'''
* <code>logo</code> - parse as '''u-'''
* <code>photo</code> - parse as '''u-'''
* <code>url</code> - parse as '''u-'''
* <code>uid</code> - parse as '''u-'''
* <code>category</code>
* <code>adr</code> - parse as '''<code>p-adr h-adr</code>''' including compat root class <code>adr</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>
* <code>label</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root class <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* <code>tel</code>
* <code>note</code>
* <code>bday</code> - parse as '''dt-'''
* <code>key</code> - parse as '''u-'''
* <code>org</code>
* <code>organization-name</code>
* <code>organization-unit</code>
* <code>title</code> - parse as '''p-job-title'''
* <code>role</code>
* ...

Reserved: (backward compat properties that parsers {{may}} implement, if they do, they {{must}} implement in this way:
* <code>tz</code>
* <code>rev</code> - parse as '''dt-'''
* ...

Note: use of 'value' within 'tel' should be automatically handled by the support of the [[value-class-pattern]]. And for now, the 'type' subproperty of 'tel' is dropped/ignored. If there is demonstrable documented need for additional tel types (e.g. fax), we can introduce new flat properties as needed (e.g. p-tel-fax).

=== h-entry ===
{{main|h-entry}}

The '''h-entry''' microformat is for marking up syndicatable content such as blog posts, notes, articles, comments, photos and similar. This is an update to [[hAtom]].

root class name: '''<code>h-entry</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-entry</nowiki>

properties:
* '''<code>p-name</code>''' (was p-entry-title, see issues)
* '''<code>p-summary</code>''' (was p-entry-summary, see issues)
* '''<code>e-content</code>''' (was e-entry-content, see issues)
* '''<code>dt-published</code>'''
* '''<code>dt-updated</code>'''
* '''<code>p-author</code>'''
* '''<code>p-category</code>'''
* '''<code>u-url</code>'''
* '''<code>u-uid</code>'''
* '''<code>p-geo</code>'''
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''

This is an update to [[hAtom]].

Brainstorming:

The following properties are proposed additions to h-entry above and beyond what hAtom (or Atom) provides, based on various existing link preview markup conventions:
* '''<code>u-photo</code>'''
* '''<code>u-audio</code>''' - consider special u- parsing rules for <code><audio></code>
* '''<code>u-video</code>''' - consider special u- parsing rules for <code><video></code>
* '''<code>u-in-reply-to</code>''' - for links to other posts that this post is a reply to (comment regarding, etc.)

Backward compatibility:

(*)hAtom-specific implementations that perform custom display or translation (e.g. to Atom XML) {{should}} prefer <code>p-name</code> over <code>p-entry-title</code>, and use <code>p-entry-title</code> value(s) as a fallback if there is no <code>p-name</code>.

For hAtom backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-entry" is found, don't look for a "hentry" on the same element.

compat root class name: <code id="hentry">hentry</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>entry-title</code> - parse as '''<code>p-name</code>'''
* <code>entry-summary</code>
* <code>entry-content</code> - parse as '''e-'''
* <code>published</code> - parse as '''dt-'''
* <code>updated</code> - parse as '''dt-'''
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>category</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* ...

<span id="h-entry-faq">FAQ:</span>
<div class="discussion">
* '''What is the <code>p-name</code> of a [http://indiewebcamp.com/note note]?'''
** A few options, from simplest to most detailed.
*** '''same as the p-content/e-content''' property.
*** '''same as the <code>title</code> element''' on the note permalink post page. When publishing a note on its own permalink post page, the contents of the note are likely abbreviated for the title of the page. The same abbreviation can be used for the p-name.
*** '''first sentence of the p-content/e-content''' property. It may be better for [http://indiewebcamp.com/syndication syndication] and [[link-preview]] purposes to provide just the first sentence of the note as the <code>p-name</code>. Similarly if only a portion of the content is syndicated to other sites, that portion can be marked up as the <code>p-summary</code>.
* ...
</div>

Resolved Issues:
* 2012-245 Resolved. See [http://krijnhoetmer.nl/irc-logs/microformats/20120830#l-120 2012-243 IRC discussion/consensus] for:
** Use '''<code>p-summary</code> instead of <code>p-entry-summary</code>'''. The historical semantic of "entry-summary" is not different from "summary" in any significant (or discernible way). Collapsing the two will simplify the overall microformats2 vocabularies further. In microformats2, entry-summary is no more.
** Use '''<code>e-content</code> instead of <code>e-entry-content</code>'''. Same point and advantage. In microformats2, entry-content is no more.
** '''drop <code>p-entry-title</code>'''. Unnecessary and subsumed by "p-name". Would consider move to backward compat only if cases are presented - known publishing uses are expected to be updated shortly.

=== h-event ===
{{main|h-event}}

The '''h-event''' microformat is for marking up events. This is an update to [[hCalendar]].

root class name: '''<code>h-event</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-event</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>p-summary</code>'''(*)
* '''<code>dt-start</code>'''
* '''<code>dt-end</code>'''
* '''<code>dt-duration</code>'''
* '''<code>p-description</code>'''
* '''<code>u-url</code>'''
* '''<code>p-category</code>'''
* '''<code>p-location</code>'''
* '''<code>p-geo</code>'''
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* ...

This is an update to [[hCalendar]].

(*)hCalendar-specific implementations that perform custom display or translation (e.g. to iCalendar .ics) {{should}} prefer <code>p-name</code> over <code>p-summary</code>, and use <code>p-summary</code> value(s) as a fallback if there is no <code>p-name</code>.

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-event" is found, don't look for a "vevent" on the same element.

compat root class name: <code id="vevent">vevent</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> - parse as '''<code>p-name</code>'''
* <code>dtstart</code> - parse as '''<code>dt-start</code>'''
* <code>dtend</code> - parse as '''<code>dt-end</code>'''
* <code>duration</code> - parse as '''<code>dt-duration</code>'''
* <code>description</code>
* <code>url</code> - parse as '''u-'''
* <code>category</code>
* <code>location</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>, and compat root <code>adr</code> in the absence of <code>h-adr</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* ...

=== h-geo ===
{{main|h-geo}}

The '''h-geo''' microformat is for marking up WGS84 geophysical coordinates. This is an update to [[geo]].

root class name: '''<code>h-geo</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-geo</nowiki>

properties:
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-geo" is found, don't look for an "geo" on the same element.

compat root class name: <code id="geo">geo</code>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>latitude</code>
* <code>longitude</code>

=== h-item ===
{{main|h-item}}

The '''h-item''' microformat is for marking up the item of an [[h-review]] or [[h-product]]. This is an update to part of [[hReview]].

root class name: '''<code>h-item</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-item</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>'''

Note: in practice, due to the microformats2 implied property rules, it is expected that most uses of "h-item" won't require any explicit properties at all (since microformats2 parsers will infer name, photo, and url properties from the structure of the element with "h-item" and its contained content/elements if any).

=== h-product ===
{{main|h-product}}

The '''h-product''' microformat is for marking up products. This is an update to [[hProduct]].

root class name: '''<code>h-product</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-product</nowiki>

properties:
* '''<code>p-name</code>''' - name of the product
* '''<code>u-photo</code>''' - photo of the product
* '''<code>p-brand</code>''' - manufacturer, can also be a nested <code>h-card</code>
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>e-description</code>'''
* '''<code>u-url</code>''' - URL of the product
* '''<code>u-identifier</code>''' - includes type (e.g. mpn, upc, isbn, issn, sn, vin, sku etc.) and value.
* '''<code>p-review</code>''' - a review of the product, can also be a nested <code>h-review</code>
* '''<code>p-price</code>''' - retail price of the product

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-product" is found, don't look for an "hproduct" on the same element.

compat root class name: <code id="hproduct">hproduct</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>photo</code> - parse as '''u-'''
* <code>brand</code>
* <code>category</code>
* <code>description</code>
* <code>identifier</code> - parse as '''u-'''
* <code>url</code> - parse as '''u-'''
* <code>review</code> - including compat root class <code>hreview</code> in the absence of <code>h-review</code>
* <code>price</code>

Note: [[hProduct]] has at least one experimental property which has real world adoption due to [[Google]] and [[Bing]] search support of hProduct. Currently this is: '''price'''

=== h-recipe ===
{{main|h-recipe}}

The '''h-recipe''' microformat is for marking up food recipes. This is an update to [[hRecipe]].

root class name: '''<code>h-recipe</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-recipe</nowiki>

properties:
* '''<code>p-name</code>''' - the name of the recipe
* '''<code>p-ingredient</code>''' - describes one or more ingredients used in the recipe.
* '''<code>p-yield</code>''' - Specifies the quantity produced by the recipe, like how many persons it satisfyies
* '''<code>e-instructions</code>''' - the method of the recipe.
* '''<code>dt-duration</code>''' - the time it takes to prepare the meal described by the recipe.
* '''<code>u-photo</code>''' - an accompanying image

Experimental properties with wide adoption
* '''<code>p-summary</code>''' - provides a short summary or introduction
* '''<code>p-author</code>''' - the person who wrote the recipe with <code>h-card</code>
* '''<code>dt-published</code>''' - the date the recipe was published
* '''<code>p-nutrition</code>''' - nutritional information like calories, fat, dietary fiber etc.
* ...

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-recipe" is found, don't look for an "hrecipe" on the same element.

compat root class name: <code id="hrecipe">hrecipe</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>ingredient</code>
* <code>yield</code>
* <code>instructions</code> - parse as '''e-'''
* <code>duration</code> - parse as '''dt-'''
* <code>photo</code> - parse as '''u-'''
* <code>summary</code>
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>nutrition</code>

Note: [[hRecipe]] has a number of experimental properties which have real world adoption due to [[Google]] recipe search support of hRecipe. These are: summary, author, published and nutrition

=== h-resume ===
{{main|h-resume}}

The '''h-resume''' microformat is for marking up resumes. This is an update to [[hResume]].

root class name: '''<code>h-resume</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-resume</nowiki>

properties:
* '''<code>p-summary</code>''' - overview of qualifications and objectives
* '''<code>p-contact</code>''' - current contact info in an <code>h-card</code>
* '''<code>p-education</code>''' - an education <code>h-calendar</code> event, years, nested <code>h-card</code> of the school, location.
* '''<code>p-experience</code>''' - a job or other professional experience <code>h-calendar</code> event, years, nested <code>h-card</code> of the organization, location, job-title.
* '''<code>p-skill</code>''' - a skill or ability, optionally including level and/or duration of experience
* '''<code>p-affiliation</code>''' - an affiliation with an <code>h-card</code> organization

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-resume" is found, don't look for an "hresume" on the same element.

compat root class name: <code id="hresume">hresume</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code>
* <code>contact</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>education</code> - including compat root <code>vevent</code> in the absence of <code>h-event</code>
* <code>experience</code> - including compat root <code>vevent</code> in the absence of <code>h-event</code>
* <code>skill</code>
* <code>affiliation</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>

Note: skill has a [[hresume-skill-brainstorm|proposed expansion into competency]] with explicit summary, rating and/or duration components. Based on existing real world adoption, we should consider an h-competency vocabulary with p-summary, p-rating, and dt-duration properties.

=== h-review ===
{{main|h-review}}

The '''h-review''' microformat is for marking up reviews. This is an update to [[hReview]]. See also [[h-item]].

root class name: '''<code>h-review</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-review</nowiki>

properties:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed i.e. 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
* '''<code>dt-reviewed</code>''' - date time of when the review was written
* '''<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-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>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>u-url</code>''' - URL of the review

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review" is found, don't look for an "hreview" on the same element.

compat root class name: <code id="hreview">hreview</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> parse as '''<code>p-name</code>'''
* <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>reviewer</code> - including compat root vcard in the absence of h-card
* <code>dtreviewed</code> - parse as '''dt-'''
* <code>rating</code>
* <code>best</code>
* <code>worst</code>
* <code>description</code> - parse as '''e-'''
* <code>rel="tag"</code> - parse as '''p-category'''
* <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>. Microformats2 parsers {{should}} map these URLs into the page scoped rel collection.

=== h-review-aggregate ===
{{main|h-review-aggregate}}

The '''h-review-aggregate''' microformat is for marking up aggregate reviews of a single item. This is an update to [[hreview-aggregate]]. See also [[h-item]].

root class name: '''<code>h-review-aggregate</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-review-aggregate</nowiki>

properties:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed i.e. 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-rating</code>''' - value from 1-5 indicating average rating for the item (5 best).
* '''<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-count</code>''' - number of reviews aggregated.
* '''<code>p-votes</code>''' - number of reviewers who have rated the product, thus contributing to the average rating.
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>u-url</code>''' - URL of the review

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review-aggregate" is found, don't look for an "hreview-aggregate" on the same element.

compat root class name: <code id="hreview-aggregate">hreview-aggregate</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> parse as '''<code>p-name</code>'''
* <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>rating</code>
* <code>best</code>
* <code>worst</code>
* <code>count</code>
* <code>votes</code>
* <code>rel="tag"</code> - parse as '''p-category'''
* <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.

=== v2 vocab notes ===
Notes:
* All v2 vocabularies are defined as flat lists of properties of an object/item, and thus can be used in microformats-2 syntax as shown, or in microdata items, or RDFa. The microformats-2 property parsing prefixes "p-", "u-", "dt-", "e-" are omitted when using defined properties in microdata itemprop and RDFa property as those syntaxes have their own element-specific parsing rules.
* Profile URLs are provided for use with the HTML4 <code>profile</code> attribute, microdata <code>itemtype</code> attribute, and RDFa <code>vocab</code> & <code>typeof</code> attributes (though the latter requires slicing off the trailing segment of the profile for the typeof attribute, and leaving the rest in vocab).
* microformats2 properties may also be explicitly bound as URIs using [[rel-profile]], the [[html5-profile]] attribute proposal, or an HTML5 'vocab' attribute instead. If URI bound terms are important to you, please express interest on [[rel-profile]], [[html5-profile]], or contribute to an [[html5-vocab]] draft.

=== v2 vocab to-do ===
To do:
* write a simple tutorial for creating/getting started with microformats-2 markup for new content
* examples in each h-* spec listed above of how to embed other microformats in them
* actual profile documents at <nowiki>http://microformats.org/profile/h-*</nowiki> URLs mentioned above.
* Provide any necessary microdata-specific language as needed (e.g. to be comparably understandable to the [http://www.whatwg.org/specs/web-apps/current-work/#vcard sample vCard4/hCard1 microdata vocabulary]. Also provide any necessary RDFa-specific language as needed. Both preferably in a generic vocabulary-independent way.
* write a porting guide mapping v1 property -> v2 property
** use-case: simple search/replace in templates (e.g. in case web author doesn't remember existing microformats vocabs and where they used them).
** advise using *both* in existing templates (e.g. in case some CSS depends on the existing microformats)
* analyzie/document how well the microformats2 model and vocabularies satisfy the [http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2009-May/019681.html use-cases used to design/create microdata].

== combining microformats ==
Since microformats2 uses simple flat sets of properties for each microformat, multiple microformats are combined to indicate additional structure.

=== h-event location h-card ===
Events commonly have venue information with additional structure, like address information. For example:

<syntaxhighlight lang="html">
<div class="h-event">
<a class="p-name u-url" href="http://indiewebcamp.com/2012">
IndieWebCamp 2012
</a>
from <time class="dt-start">2012-06-30</time>
to <time class="dt-end">2012-07-01</time> at
<span class="p-location h-card">
<a class="p-name p-org u-url" href="http://geoloqi.com/">
Geoloqi
</a>,
<span class="p-street-address">920 SW 3rd Ave. Suite 400</span>,
<span class="p-locality">Portland</span>,
<abbr class="p-region" title="Oregon">OR</abbr>
</span>
</div>
</syntaxhighlight>

The nested h-card used to structure the p-location of the h-event is represented as a structured value for "location" in the JSON, which has an additional key, "value" that represents the plain text version parsed from the p-location.

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-event"],
"properties": {
"name": ["IndieWebCamp 2012"],
"url": ["http://indiewebcamp.com/2012"],
"start": ["2012-06-30"],
"end": ["2012-07-01"],
"location": [{
"value": "Geoloqi",
"type": ["h-card"],
"properties": {
"name": ["Geoloqi"],
"org": ["Geoloqi"],
"url": ["http://geoloqi.com/"],
"street-address": ["920 SW 3rd Ave. Suite 400"],
"locality": ["Portland"],
"region": ["Oregon"]
}
}]
}
}]
}
</syntaxhighlight>

Questions:
<div class="discussion">
* Should the nested hCard be present also as a top-level item in the JSON? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
** My current (2012-243) leaning is no. - [[User:Tantek|Tantek]] 18:53, 30 August 2012 (UTC)
** If so, how do we avoid expansion of the JSON geometrically proportional to the depth of microformat nesting? (Or do we not worry about it?)
* Should there be a canonical hierarchical JSON and a canonical flattened JSON? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
** My current (2012-243) leaning is no, we stick with one canonical JSON for uf2 which is hierarchical. - [[User:Tantek|Tantek]] 18:53, 30 August 2012 (UTC)
** If so, should the flattened JSON have references from properties to nested microformats that have been pushed to the top level per flattening? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
*** If so, what convention does/do JSON follow for such synthetic local reference identifiers? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
</div>

Notes:
* The 'location' value reflects the visible text of its element, including spaces and punctuation, as well as the state abbreviation 'OR'. The 'h-card' property values are only what is marked up, and thus include structure values without extra punctuation, and the state takes the expanded form from the <code>title</code> attribute of its <code><abbr></code> element.

=== h-card org h-card ===
People often publish information general to their company rather than specific to them, in which case, they may wish to encapsulate that in separately nested microformat. E.g. here is a simple h-card example with org property:

[http://blog.lizardwrangler.com Mitchell Baker] (Mozilla Foundation)

with source:
<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<span class="p-org">Mozilla Foundation</span>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": ["Mozilla Foundation"]
}
}]
}
</syntaxhighlight>

Sometimes such organization affiliations are hyperlinked to the website of the organization:

[http://blog.lizardwrangler.com Mitchell Baker] ([http://mozilla.org/ Mozilla Foundation])

You can mark that up with a nested h-card:
<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
</syntaxhighlight>

Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an <code><a href></code> would.

'''FOR PARSERS ONLY:'''

The nested 'h-card' could be marked up as an 'h-org' as well, which adds it to the nested microformat's type array, all as part of the property specified by the 'p-org'.

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card h-org"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card", "h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
</syntaxhighlight>

'''FOR PARSERS ONLY:'''

Without a property class name like 'p-org' holding all the nested objects together, we need to introduce another array for nested children (similar to the existing DOM element notion of children) of a microformat that are not attached to a specific property:

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card","h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
</syntaxhighlight>

Since there's no property class name on the element with classes 'h-card' and 'h-org', the microformat representing that element is collected into the children array.

Such a nested microformat implies some relationship (containment, being related), but is not as useful as if the nested microformat was a specific property of its parent.

For this reason it's recommended that authors should not publish nested microformats without a property class name, and instead, when nesting microformats, authors should always specify a property class name (like 'p-org') on the same element as the root class name(s) of the nested microformat(s) (like 'h-card' and/or 'h-org').

'''FOR PARSERS ONLY:'''

Or the nested object could be only marked up with 'h-card'. Source:

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
</syntaxhighlight>

'''TO DO: Add h-event h-card example and JSON, per real world publishing examples like [http://www.swingtime.co.uk/List/ClSouth.html Swing Time: Classes in Southern England].'''

== authoring ==
=== minimal markup ===
The best way to use microformats-2 is with as little additional markup as possible. This keeps your code cleaner, improves its maintainability, and thus the quality and longevity of your microformats.

One big advantage of microformats-2 over previous microformats (and others) is the ability to add one class name to an existing element to create a structured item.

See the [[microformats-2#simple_microformats_2_examples|simple examples at the top]] for a start, e.g.

Simple hCards work just by adding <code>class="h-card"</code> :
<syntaxhighlight lang="html">
<span class="h-card">Frances Berriman</span>

<a class="h-card" href="http://benward.me">Ben Ward</a>

<img class="h-card" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>

<a class="h-card" href="http://tantek.com">
<img alt="Tantek Çelik" src="http://ttk.me/logo.jpg"/>
</a>
</syntaxhighlight>

* Tip: Inside an open tag, put the <code>class</code> attribute <em>first</em>, then any human text content attributes (e.g. <code>alt</code>), then URL attributes (e.g. <code>href</code> <code>src</code>), and lastly other attributes (e.g. <code>style</code>). Putting the class attribute first ties it closely to the element name/tag itself, makes it more obvious, and thus more likely to be kept up to date.

=== backward compatible ===
If you depend on current microformats [[implementations]], while they're being updated to support [[microformats2]], you can include both existing classic microformats and microformats2 markup.

In short: use both sets of class names simultaneously.

When doing so, use them on the same element, with the microformats-2 class name first, followed immediately by the existing microformats class name.

Here are the microformats-2 hCards from above with current [[hCard]] markup as well, which may require adding a wrapping element (e.g. a <code><span></code>) to separate the root class name element from explicit property class name elements:

<syntaxhighlight lang="html">
<span class="h-card vcard">
<span class="p-name fn">Frances Berriman</span>
</span>

<span class="h-card vcard">
<a class="p-name fn u-url url" href="http://benward.me">Ben Ward</a>
</span>

<span class="h-card vcard">
<img class="p-name fn u-photo photo" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>
</span>

<span class="h-card vcard">
<a class="u-url url" href="http://tantek.com">
<img class="p-name fn u-photo photo" alt="Tantek Çelik"
src="http://ttk.me/logo.jpg"/>
</a>
</span>
</syntaxhighlight>

Tips:
* use the microformats-2 class name first, e.g.
** <code>class="h-card vcard"</code>
** <code>class="u-url url"</code>
* and pair them when using an element for multiple properties, e.g.:
** <code>class="p-name fn u-url url"</code>
** <code>class="p-name fn u-photo photo"</code>
* put microformats classes after classes for CSS (since page authors will likely interact more with their own classes for design than with microformats classes), e.g. as used on individual microformats [[events]] pages:
** <code>class="event-page h-event vevent"</code>

The prefixes (h-, p-, etc.) of microformats2 class names provide easier recognition, and when followed by the similarly named existing class name, they're more easily recognized as related and thus kept together when the markup is maintained over time.

Related FAQ: [[microformats2-faq#when_using_both_h-card_and_vcard_which_should_be_first_and_why|When using both h-card and vcard which should be first and why?]]

== extensions ==
microformats2 is extensible by means of two separate but syntactically similar extension prefixes for experiments intended to be iterated & evolved and for vendor specific extensions not intended for standardization.

=== experimental extensions ===
There have been times when specific sites have wanted to extend microformats beyond the set of properties in the microformat vocabulary, and currently lack any '''experimental''' way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus:

For experimental extensions for the purpose of prototyping to learn more, iterate, towards possibly standardizing, use the <code>-x-</code> prefix before root and property class names.

Specifically:
* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a literal 'x' for an experimental extension

Examples:
* "p-x-prep-time" - a possible experimental property name to be added to [[h-recipe]] upon consideration/documentation of real-world usage/uptake.

See [[microformats2-experimental-properties]] for more examples.

=== <span id="VENDOR_EXTENSIONS">vendor extensions</span> ===
For vendor specific extensions, microformats2 uses a mechanism similar to CSS vendor extensions, using a similar syntax as experimental extensions, except with a vendor prefix instead of a literal 'x'.

* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-, numbers allowed after first character)

Examples:
* "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "one-ring" microformat root class name.
* "p-goog-preptime" - to represent [http://www.google.com/support/webmasters/bin/answer.py?answer=173379 Google's "preptime" property extension] to [[hRecipe]] (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.)

See [[vendor-prefixes]] for more examples.

=== extensions background ===
This extensibility mechanism is a composition of the following (at least somewhat) successful extension syntaxes:
* [http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords CSS 2.1 4.1.2.1 Vendor-specific extensions]
* IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [http://en.wikipedia.org/wiki/Internet_media_type]
* IETF MIME experimental fields (e.g. x-spam-score)
* HTTP header extensions (e.g. x-pingback)
* note also [http://www.mnot.net/blog/2009/02/18/x- some critical thoughts from mnot]

In particular:

Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.

Proprietary or experimental CSS3 property implementations have been very successful.

There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like:

* -moz-border-radius
* -webkit-border-radius

etc.

Note that these are merely string '''prefixes''', not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use.

This use of vendor specific CSS properties allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.

The benefits have been two-fold:
* designers have been able to make more attractive sites sooner (at least in some browsers)
* features have been market / real-world tested before being fully standardized, thus resulting in better features

Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and [https://secure.wikimedia.org/wikipedia/en/wiki/List_of_HTTP_header_fields#Common_non-standard_headers Wikipedia: HTTP header fields - non-standard headers] (could use RFC reference instead) respectively, like:

* application/x-latex (per [https://secure.wikimedia.org/wikipedia/en/wiki/Internet_media_type#Type_x Wikipedia Internet media type: Type x])
* x-spam-score (in email headers)
* X-Pingback (per [http://en.wikipedia.org/wiki/Pingback Wikipedia:Pingback])

Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases:

* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])

See [[microformats2-origins#VENDOR_EXTENSIONS]] for more background.

== validators ==
microformats2 validators:

{{new}} Test your microformatted web page with:
* https://pin13.net/mf2/

Barnaby Walters has a hosted version of the open source php-mf2 [[parser]] where you can enter your markup into a textarea and see how it's parsed:
* http://waterpigs.co.uk/php-mf2/

See the [[validators]] page for a longer list of validators.

== Examples in the wild ==
Please add new examples in the wild of microformats-2 to the top of this list. When it gets too big we can move it to a separate page like [[microformats-2-examples-in-wild]].

* ...
* David John Mead marks up his profile, blog posts and comments with h-card, h-entry and h-cite on [http://davidjohnmead.com davidjohnmead.com]
* [[User:Brian|Brian Suda]] marks up his blog posts up with h-entry and h-card on [http://optional.is/required/ optional.is]
* Ashton McAllan marks up her blog posts, reposts, comments and likes with h-entry, h-card and h-cite on [https://acegiak.net/ acegiak.net]
* Emma Kuo marks up her blog posts and notes with h-entry and h-card on [http://notenoughneon.com/ notenoughneon.com]
* Scott Jenson marks up his blog posts with h-entry and h-card on [http://jenson.org/ jenson.org]
* Emily McAllen marks up her blog posts with h-entry and h-card on [http://blackwoolholiday.com/ blackwoolholiday.com]
* Ryan Barrett marks up his blog posts, notes, replies and likes with h-entry and h-card on [https://snarfed.org/ snarfed.org]
* Barry Frost marks up his notes with h-entry, h-card and h-cite on [http://barryfrost.com/ barryfrost.com]
* Amber Case marks up her profile, blog posts, replies and notes with h-entry and h-card on [http://caseorganic.com/ caseorganic.com]
* Johannes Ernst marks up his blog posts with h-entry on [http://upon2020.com/blog/ upon2020.com]
* Michiel de Jong marks up his profile and notes with h-entry and h-card on [https://michielbdejong.com/ michielbdejong.com]
* Mike Taylor marks up his profile and blog posts with h-card and h-entry on [https://bear.im/bearlog/ bear.im]
* Erin Jo Ritchey marks up her profile, posts and comments using h-card, h-entry and h-cite with idno on [http://erinjo.is/ erinjo.is]
* Jeena Paradies marks up his profile, blog posts, notes and comments using h-card, h-entry and h-cite on [https://jeena.net/ jeena.net]
* Andy Sylvester marks up his profile, blog posts and comments using h-card and h-entry on [http://andysylvester.com/2014/03/01/howto-setting-up-the-selfoss-feed-reader-with-microformats-support/ andysylvester.com] (note: as of 2014-03-13 using h-entry for comments instead of correct h-cite --[[User:Barnabywalters|bw]] 14:44, 13 March 2014 (UTC))
* Hakan Demir marks up his Coupon and Voucher blog posts with h-entry and h-card on [http://www.gutscheinflagge.de/ gutscheinflagge.de]
* Chloe Weil marks up her blog posts with h-entry on [http://chloeweil.com/blog chloeweil.com]
* Christophe Ducamp marks up his blog posts and profile with h-entry and h-card on [http://christopheducamp.com/ christopheducamp.com]
* Glenn Jones marks up his blog posts, notes, replies, profile and comments with h-entry, h-card and h-cite on [http://glennjones.net/ glennjones.net]
* Marcus Povey marks up his blog posts and profile with h-entry and h-card on [http://www.marcus-povey.co.uk/ marcus-povey.co.uk]
* Eugen Busoiu marks up his web profile with h-card on [http://eugenbusoiu.com/#utm_source=microformats2&utm_medium=h-card&utm_campaign=Microformats eugenbusoiu.com]]
* Matthias Pfefferle marks up his blog posts, comments and profile with h-card, h-cite and h-entry on [http://notizblog.org/ notizblog.org]
* Kyle Mahan marks up his profile and notes with h-card and h-entry on [http://kylewm.com/ kylewm.com]
* Emil Björklund marks up his blog posts with h-entry and h-card ([http://thatemil.com/blog/2013/09/16/webmentioning-adactio/ example])
* App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 ([https://alpha.app.net/voidfiles example])
* Brett Comnes marks up his posts with h-entry and h-card ([http://bret.io/2013/06/29/getting-started-with-bower/ example])
* Ben Werdmuller marks up his posts with h-card and h-entry, u-in-reply-to and u-like ([http://werd.io/view/51d5097fbed7ded0633a5956 example])
* Sandeep Shetty marks his posts up with h-card and h-entry, as well as draft u-in-reply-to and experimental u-like properties ([http://sandeep.io/101 example])
* Laurent Eschenauer marks up his posts with h-entry ([http://eschnou.com/entry/first-autonomous-flight-of-my-nodecopter-62-24992.html example])
* Tom Morris marks up his posts using h-entry ([http://tommorris.org/posts/8417 example])
* Sinolandquality marks up some of their content using h-feed and h-entry on [http://www.sinolandquality.com/Blog/?page_id=3516&utm_content=buffere4d40&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer sinolandquality.com]
* [http://www.w3.org/conf/ W3Conf 2013] uses h-event for the main event, and h-card for all the speakers and notable attendees. The h-cards make particularly good use of implied name, url, and photo properties.
* [http://wordpress.org/extend/themes/sempress SemPress] is a WordPress theme that supports h-card, h-feed/h-entry and h-as-*
* [http://the-pastry-box-project.net/ The Pastry Box Project] use h-card and h-entry markup on their homepage and individual thoughts pages
* Tom Morris uses h-card and [[XFN]] to markup [http://tommorris.org/pages/blogroll his blogroll].
* Aaron Parecki uses h-card to markup both authorship and references to people in his notes permalinks, e.g. [http://aaronparecki.com/2012/230/reply/1 2012/230/reply/1].
* [http://tantek.com/ Tantek Çelik] uses h-card, h-event, and h-entry on his home page, as well as h-entry on all post permalinks, e.g. [http://tantek.com/2012/243/t1/name-beats-title-modern-use-dubline-core-wrong-uf2 2012-243 post], with [[rel-prev]]/[[rel-next]] (if applicable) to indicate prev/next posts, and with [[rel-author]] to his home page with canonical hCard to indicate authorship.
* [http://waterpigs.co.uk/ Barnaby Walters] uses h-card on his home page, h-card, h-entry and XFN markup on his [http://waterpigs.co.uk/notes notes page].
** 2013-01-25 Barnaby Walters: <cite>[http://waterpigs.co.uk/articles/experimental-markup Experimental Markup]</cite> - describes how he's using microformats2 vocabularies: <code>h-adr</code>, <code>h-card</code>, <code>h-entry</code>, <code>h-event</code>, <code>h-geo</code>, <code>h-review</code>, and experimental vocabularies: <code>h-feed</code> (embedded for update histories), [[activity-streams]] objects <code>h-as-article</code>, <code>h-as-collection</code>, <code>h-as-note</code>, <code>h-as-update</code>, as well as experimental properties: <code>u-alternate</code> and <code>u-as-downstream-duplicate</code> (links to POSSE copies), and <code>u-in-reply-to</code> (links to content that the posts are in reply to).
* [http://tantek.com/presentations/2012/06/microformats microformats.org at 7 years] presentation with h-event and h-card markup for people and organizations.
* [http://tantek.com/presentations/2012/06/pdf2012-indieweb.html Rise of the Indie Web hCards] (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has [[microformats-2]] h-calendar and h-card markup
* WebMaker by Mozilla has [[microformats-2]] h-calendar and h-card on event search (e.g. [https://webmaker.org/en-US/events/near/?lat=45.5234515&lng=-122.6762071 search near Portland Oregon]) and event pages (e.g. [https://webmaker.org/en-US/events/192f56eb9/ IndieWebCamp 2012]).[https://twitter.com/microformats/status/212207925643587585]
* WebFWD by Mozilla has [[microformats-2]] h-card markup on [https://webfwd.org/about/experts/ experts] and [https://webfwd.org/about/team/ team] pages
* [http://indiewebcamp.com IndieWebCamp] has [[microformats-2]] h-event markup with nested h-cards for the organizers and the location.
* [https://wiki.mozilla.org/Events Mozilla Events] page has [[microformats-2]] h-event markup with attendees marked up with h-card.
* The [http://pdx.esri.com/blog/2013/10/17/introducing-mapattack/ Esri PDX Blog] has h-entry markup on all blog posts (as of 2013-10-19), and h-product markup on [http://pdx.esri.com/projects/terraformer/ project pages]

=== offline ===
* spreadly marks up share permalink pages with h-entry, as well as minimal h-cards and experimental p-like properties

== Implementations ==
{{new}} Test your microformatted web page with:
=== Live Textarea Input ===
Use any of these to enter HTML+microformats2 markup and see the parsed result!
* http://glennjones.net/tools/microformats/
* https://pin13.net/mf2/ (where it says "Microformats Parser")

=== Blogging tools ===
* '''Storytlr''' parses the <code>target</code> from [http://indiewebcamp.com/pingback pingbacks] for [https://github.com/storytlr/storytlr/blob/master/protected/application/public/controllers/PingbackController.php#L63 h-entry with properties and nested h-card] for information to automatically display in the [http://web.archive.org/web/20130425010536/http://eschnou.com/entry/testing-indieweb-federation-with-waterpigscouk-aaronpareckicom-and--62-24908.html comments section on a post] (archived; [http://eschnou.com/entry/testing-indieweb-federation-with-waterpigscouk-aaronpareckicom-and--62-24908.html original]).
** Note: per storytlr.org, retrieved 2022-05-22:
<blockquote>Storytlr is no longer maintained and '''might be unsafe to run on a public server'''. It is running on an old version of PHP and the Zend framework and has not been upgraded to latest versions and security patches.</blockquote>

=== Converters ===
* '''[https://github.com/snarfed/granary granary]''' is a library and REST API that converts between silo APIs, [[ActivityStreams]], [[microformats2]], and Atom (all directions). Supported silos include Facebook, Twitter, Instagram, Google+, and Flickr. Users include [http://brid.gy/ Bridgy], [http://reader.kylewm.com/ Woodwind], and [https://facebook-atom.appspot.com/ facebook-atom] and [https://twitter-atom.appspot.com/ twitter-atom], among others.

* '''[http://pipes.yahoo.com/pipes/pipe.info?_id=afc5568b4e8643bfb05436b1caaf91bc microformats to RSS]''' - a Yahoo! pipe that converts a URL containing an [[h-feed]] containing h-entries, into an [[RSS]] feed ([http://waterpigs.co.uk/notes/4SeNi5/ 2013-10-21 blog post announcing])

* '''[https://xray.p3k.io XRay]''' ([https://github.com/aaronpk/XRay source code]) - Returns a normalized representation of the microformats data at a URL

=== Parsers ===
Parsers, open source libraries, in alphabetical order by programming language:

If you are implementing a microformats2 parser, see:
* [[microformats2-parsing]]

==== Parsers in production ====
The following parsers are of very high quality, in active development, and use on live sites on the web in production.

===== Java =====
* [[any23]] Apache Any23 (Anything to Triples)] a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents: http://any23.apache.org

===== Javascript =====
* '''microformats-parser''' for both browser and node.js
** github open source: https://github.com/aimee-gm/microformats-parser (current)
** live: https://aimee-gm.github.io/microformats-parser/

Previously:
* '''microformat-node''' Node.js microformats2 parser
** github open source: https://github.com/microformats/microformat-node (current)
*** forked from https://github.com/glennjones/microformat-node
** test suite: https://github.com/microformats/tests

** command line: https://github.com/JerrySievert/mf2
* '''microformat-shiv''' - cross browser javascript microformats2 parser which can also be used in browser extensions.

** github open source: https://github.com/glennjones/microformat-shiv

===== PHP =====
* '''<span id="php-mf2">php-mf2</span>''' - PHP microformats2 parser
** github open source: https://github.com/indieweb/php-mf2
** Packagist: https://packagist.org/packages/mf2/mf2
** live:
*** textarea entry: http://waterpigs.co.uk/php-mf2/
*** URL and textarea entry: https://pin13.net/mf2/
** [https://github.com/barnabywalters/php-mf-cleaner mf-cleaner]: functions for working with the raw mf2 data structure

===== Python =====
* '''mf2py''' Python microformats2 parser
** main entry: [[mf2py]]
** github open source: https://github.com/tommorris/mf2py
** live:
*** URL entry: [https://mf2py.herokuapp.com/ mf2py.herokuapp.com]
*** textarea entry: https://kartikprabhu.com/connection/mfparser
*** another textarea: http://www.unmung.com/?html=
*** URL and/or textarea: https://kylewm.com/services/mf2

===== Ruby =====
* '''indieweb/microformats-ruby''' Ruby microformats parser
** github open source: https://github.com/indieweb/microformats-ruby
** live text entry: https://microformats-parser-ruby.herokuapp.com

===== Haskell =====
* '''myfreeweb/microformats2-parser''' Haskell microformats2 parser
** github open source: https://github.com/myfreeweb/microformats2-parser
** live textarea entry: https://unrelenting.technology/mf2/

==== Development parsers ====
The following parsers are in-development and have key microformats2 functionality yet are incomplete, not fully tested, or have other limitations. Contributions welcome!

===== Erlang =====
* '''hazybluedot/mf2erl''' Erlang microformats2 parser
** github open source: https://github.com/hazybluedot/mf2erl

===== Elixir =====
* '''ckruse/microformats-elixir''' Elixir microformats2 parser
** github open source: https://github.com/ckruse/microformats2-elixir

===== Go =====
* '''willnorris/microformats''' Golang microformats2 parser
** github open source: https://github.com/willnorris/microformats
** live textarea entry: https://go.microformats.io/

===== Java =====
* '''Apache Any23''' a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents. Supports Microformats1 and 2.
** Download recent release: http://any23.apache.org/download.html
** live: http://any23-vm.apache.org/
** source: http://any23.apache.org/build-src.html
* '''mf2j''' An early-stage Java microformats2 parser
** github open source: https://github.com/kylewm/mf2j
** live: https://mf2j.herokuapp.com/?url={http://example.com}

===== Perl =====
* '''Web::Microformats2''' Perl microformats2 parser
** https://metacpan.org/pod/Web::Microformats2
** open source: https://github.com/jmacdotorg/microformats2-perl

==== Experiments ====
Experiments and other proof of concept microformat2 parsing support.
* '''Rust''' - https://gitlab.com/maxburon/microformats-parser
* ...

=== Outreach ===
* [https://github.com/mozilla/fathom/issues/42 Mozilla Fathom: examples with nested classes, e.g. microformats2]

== Presentations ==
Presentations about microformats2:
* 2013-01-24 <cite>[http://waterpigs.co.uk/presentations/microformats-2/ Microformats 2]</cite> presentation by [[User:Barnabywalters|Barnaby Walters]] at the [[events/2013-01-24-exeter-web-meetup|Exeter Web Meetup]] in Devon, UK.
* 2012-09-21 <cite>[http://tantek.com/presentations/2012/09/microformats2/ microformats2 & bits of HTML5: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-09-21-refreshlx|RefreshLX]] in Lisbon, Portugal.
* 2012-07-21 <cite>[http://tantek.com/presentations/2012/07/html5-uf2/ HTML5 and microformats2: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-07-21-cascadesf|Innovators of the Web conference]] in San Francisco, CA.
* 2012-07-14 <cite>[http://tantek.com/presentations/2012/07/html5-microformats2/ HTML5 and microformats2: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-07-14-open-web-camp-4|Open Web Camp IV]] in San Jose, CA.

== Testimonials ==
* <blockquote class="twitter-tweet">To prove the web standards community can come up with better standards than the SE’s, compare this: http://microformats.org/wiki/microformats-2 with schema . org — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298907685452124160 2013-02-05 13:35]</blockquote>
* <blockquote class="twitter-tweet">... I’m hoping SE’s will pick up microformats2. It’s SO much cleaner. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298911287117758464 2013-02-05 13:49]</blockquote>
* <blockquote class="twitter-tweet">... But damn Microformats2 are sexy. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298912179292344320 2013-02-05 13:53]</blockquote>

== Origins ==
This page was originally used to brainstorm and develop microformats2 in an exploratory manner, with problem statements, questions, lessons learned from past and other formats.

Now that [[microformats2-parsing]] is a Microformats specification, the original brainstorming has been moved to a separate page for anyone who wants to understand more about how we came up with the design of microformats2, and how it evolved in the early years.
* [[microformats2-origins]]

== See Also ==
* [[microformats2]]
* [[microformats2-brainstorming]] - moving more experimental / undeveloped / and rejected thoughts ideas here to simplify/progress *this* page further.
* [[microformats2-experimental-properties]] - listing experimental (-x- prefixed) properties and their use
* [[microformats2-prefixes]]
* [[vendor-prefixes]]
* [[microformats2-faq]]
* [[microformats2-parsing]]
* 2010-05-02 [[events/2010-05-02-microformats-2-0|microformats 2.0 discussion session at FOO East]]

microformats2

2024-03-01T18:48:01Z

GRegorLove: /* Live Textarea Input */ rm kylewm link, zombie domain :(

<span style="float:right">__TOC__</span>
Welcome to the microformats2 home page.

== Summary ==
Microformats2 is the latest version of microformats, the simplest way to markup structured information in HTML. Microformats2 improves ease of use and implementation for <em>both</em> authors (publishers) and developers ([[microformats2-parsing|parser]] implementers).

Microformats2 replaces and supersedes both classic microformats (sometimes called microformats1), as well as incorporates lessons learned from [[microdata]] and [[RDFa]].

=== simple microformats2 examples ===
Here are a few <span id="simple_microformats_2_examples">simple microformats2 examples</span> along with canonical [[JSON]].

==== person example ====
* Simple person reference:
<syntaxhighlight lang="html">
<span class="h-card">Frances Berriman</span>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Frances Berriman"]
}
}]
}
</syntaxhighlight>

----

==== hyperlinked person ====
* Simple hyperlinked person reference
<syntaxhighlight lang="html">
<a class="h-card" href="http://benward.me">Ben Ward</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Ben Ward"],
"url": ["http://benward.me"]
}
}]
}
</syntaxhighlight>

----

==== hyperlinked person image ====
* Simple hyperlinked person image
<syntaxhighlight lang="html">
<a class="h-card" href="http://rohit.khare.org/">
<img alt="Rohit Khare"
src="https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg" />
</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Rohit Khare"],
"url": ["http://rohit.khare.org/"],
"photo": ["https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg"]
}
}]
}
</syntaxhighlight>

Additional simple cases details in [[microformats-2-implied-properties]].

----

==== detailed person example ====
* More detailed person
<syntaxhighlight lang="html">
<div class="h-card">
<img class="u-photo" alt="photo of Mitchell"
src="https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"/>
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="u-url"
href="https://twitter.com/MitchellBaker"
>@MitchellBaker</a>)
<span class="p-org">Mozilla Foundation</span>
<p class="p-note">
Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities.
</p>
<span class="p-category">Strategy</span>
<span class="p-category">Leadership</span>
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"photo": ["https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"],
"name": ["Mitchell Baker"],
"url": [
"http://blog.lizardwrangler.com/",
"https://twitter.com/MitchellBaker"
],
"org": ["Mozilla Foundation"],
"note": ["Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities."],
"category": [
"Strategy",
"Leadership"
]
}
}]
}
</syntaxhighlight>

----
=== details from examples ===
Details demonstrated by the examples:
# The JSON <code>"type"</code> uses the full microformat root class name (e.g. <code>"h-card"</code>) for consistent identification.
# all properties are optional and syntactically plural with parsed values provided in document order; particular microformats (and applications there-of) may apply specific/singular semantics to first value of a property.

=== microformats2 design ===

microformats2 has the following key design aspects:

; Prefixes for class names
: All microformats class names use prefixes. Prefixes are '''syntax independent from vocabularies''', which are developed separately.
* <code>h-*</code> for root class names (e.g. <code>h-card</code>)
* <code>p-*</code> for plain text properties (e.g. <code>p-name</code>)
* <code>u-*</code> for URL properties (e.g. <code>u-photo</code>)
* <code>dt-*</code> for date/time properties (e.g. <code>dt-bday</code>)
* <code>e-*</code> for embedded markup properties (e.g. <code>e-note</code>)<br />

See [[microformats2-prefixes]] for more details.

; Flat sets of optional properties
: All microformats consist of a root, and a collection of properties. Hierarchical data is represented with nested microformats, typically as property values themselves. Properties are all optional and potentially multivalued (applications needing a singular semantic may use first instance).

; Single class markup for common uses
: Common simple markup patterns require only a single microformat root class name, which parsers use to find a few generic properties: <code>name</code>, <code>url</code>, <code>photo</code>. The simple microformats2 examples above demonstrate these.

----

Parsing each prefix (including generating canonical JSON) is detailed step-by-step in:
* The '''[[microformats2-parsing|microformats2 parsing specification]]'''

'''Note:''' Most properties are specified and used with a single specific prefix (or occasionally two or three) that is self-evident from context. However, any parsing prefix can be used with any property, especially if you find a good reason to do so!

== v2 vocabularies ==
Status: '''<span id="draft_v2_vocabularies">draft</span>'''. Please review and provide feedback in [[IRC]].
* [[h-adr]]
* [[h-card]]
* [[h-entry]]
* [[h-event]]
* [[h-feed]]
* [[h-geo]]
* [[h-item]]
* [[h-listing]]
* [[h-product]]
* [[h-recipe]]
* [[h-resume]]
* [[h-review]]
* [[h-review-aggregate]]

See below for vocabulary summaries.

=== h-adr ===
{{main|h-adr}}

The '''h-adr''' microformat is for marking up structured locations such as addresses, physical and/or postal. This is an update to [[adr]].

root class name: '''<code>h-adr</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-adr</nowiki>

properties:
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-street-address</code>'''
* '''<code>p-locality</code>'''
* '''<code>p-region</code>'''
* '''<code>p-postal-code</code>'''
* '''<code>p-country-name</code>'''
* '''<code>p-label</code>''' - new in [[vCard4]] ([[RFC6350]])
* '''<code>p-geo</code>''' (or '''<code>u-geo</code>''' with a RFC 5870 geo: URL) - new in [[vCard4]] ([[RFC6350]])
* '''<code>p-latitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-longitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-adr" is found, don't look for an "adr" on the same element.

compat root class name: <code id="adr">adr</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>post-office-box</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>

=== h-card ===
{{main|h-card}}

The '''h-card''' microformat is for marking up people and organizations. This is an update to [[hCard]].

root class name: '''<code>h-card</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-card</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>p-honorific-prefix</code>'''
* '''<code>p-given-name</code>'''
* '''<code>p-additional-name</code>'''
* '''<code>p-family-name</code>'''
* '''<code>p-sort-string</code>'''
* '''<code>p-honorific-suffix</code>'''
* '''<code>p-nickname</code>'''
* '''<code>u-email</code>'''
* '''<code>u-logo</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>'''
* '''<code>u-uid</code>'''
* '''<code>p-category</code>'''
* '''<code>p-adr</code>'''
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-street-address</code>'''
* '''<code>p-locality</code>'''
* '''<code>p-region</code>'''
* '''<code>p-postal-code</code>'''
* '''<code>p-country-name</code>'''
* '''<code>p-label</code>'''
* '''<code>p-geo</code>''' or '''<code>u-geo</code>''' with a RFC 5870 geo: URL, new in [[vCard4]] ([[RFC6350]])
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-tel</code>'''
* '''<code>p-note</code>'''
* '''<code>dt-bday</code>'''
* '''<code>u-key</code>'''
* '''<code>p-org</code>'''
* '''<code>p-job-title</code>''' - previously 'title' in hCard, disambiguated.
* '''<code>p-role</code>
* '''<code>u-impp</code>''' per RFC 4770, new in [[vCard4]] ([[RFC6350]])
* '''<code>p-sex</code>''' new in [[vCard4]] ([[RFC6350]])
* '''<code>p-gender-identity</code>''' new in [[vCard4]] ([[RFC6350]])
* '''<code>dt-anniversary</code>''' new in [[vCard4]] ([[RFC6350]])
* ...

Reserved properties: (properties not used much (if at all) in practice)
* '''<code>p-organization-name</code>'''
* '''<code>p-organization-unit</code>'''
* '''<code>p-tz</code>'''
* '''<code>dt-rev</code>'''
* ...

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-card" is found, don't look for a "vcard" on the same element.

compat root class name: <code id="vcard">vcard</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>honorific-prefix</code>
* <code>given-name</code>
* <code>additional-name</code>
* <code>family-name</code>
* <code>honorific-suffix</code>
* <code>nickname</code>
* <code>email</code> - parse as '''u-'''
* <code>logo</code> - parse as '''u-'''
* <code>photo</code> - parse as '''u-'''
* <code>url</code> - parse as '''u-'''
* <code>uid</code> - parse as '''u-'''
* <code>category</code>
* <code>adr</code> - parse as '''<code>p-adr h-adr</code>''' including compat root class <code>adr</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>
* <code>label</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root class <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* <code>tel</code>
* <code>note</code>
* <code>bday</code> - parse as '''dt-'''
* <code>key</code> - parse as '''u-'''
* <code>org</code>
* <code>organization-name</code>
* <code>organization-unit</code>
* <code>title</code> - parse as '''p-job-title'''
* <code>role</code>
* ...

Reserved: (backward compat properties that parsers {{may}} implement, if they do, they {{must}} implement in this way:
* <code>tz</code>
* <code>rev</code> - parse as '''dt-'''
* ...

Note: use of 'value' within 'tel' should be automatically handled by the support of the [[value-class-pattern]]. And for now, the 'type' subproperty of 'tel' is dropped/ignored. If there is demonstrable documented need for additional tel types (e.g. fax), we can introduce new flat properties as needed (e.g. p-tel-fax).

=== h-entry ===
{{main|h-entry}}

The '''h-entry''' microformat is for marking up syndicatable content such as blog posts, notes, articles, comments, photos and similar. This is an update to [[hAtom]].

root class name: '''<code>h-entry</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-entry</nowiki>

properties:
* '''<code>p-name</code>''' (was p-entry-title, see issues)
* '''<code>p-summary</code>''' (was p-entry-summary, see issues)
* '''<code>e-content</code>''' (was e-entry-content, see issues)
* '''<code>dt-published</code>'''
* '''<code>dt-updated</code>'''
* '''<code>p-author</code>'''
* '''<code>p-category</code>'''
* '''<code>u-url</code>'''
* '''<code>u-uid</code>'''
* '''<code>p-geo</code>'''
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''

This is an update to [[hAtom]].

Brainstorming:

The following properties are proposed additions to h-entry above and beyond what hAtom (or Atom) provides, based on various existing link preview markup conventions:
* '''<code>u-photo</code>'''
* '''<code>u-audio</code>''' - consider special u- parsing rules for <code><audio></code>
* '''<code>u-video</code>''' - consider special u- parsing rules for <code><video></code>
* '''<code>u-in-reply-to</code>''' - for links to other posts that this post is a reply to (comment regarding, etc.)

Backward compatibility:

(*)hAtom-specific implementations that perform custom display or translation (e.g. to Atom XML) {{should}} prefer <code>p-name</code> over <code>p-entry-title</code>, and use <code>p-entry-title</code> value(s) as a fallback if there is no <code>p-name</code>.

For hAtom backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-entry" is found, don't look for a "hentry" on the same element.

compat root class name: <code id="hentry">hentry</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>entry-title</code> - parse as '''<code>p-name</code>'''
* <code>entry-summary</code>
* <code>entry-content</code> - parse as '''e-'''
* <code>published</code> - parse as '''dt-'''
* <code>updated</code> - parse as '''dt-'''
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>category</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* ...

<span id="h-entry-faq">FAQ:</span>
<div class="discussion">
* '''What is the <code>p-name</code> of a [http://indiewebcamp.com/note note]?'''
** A few options, from simplest to most detailed.
*** '''same as the p-content/e-content''' property.
*** '''same as the <code>title</code> element''' on the note permalink post page. When publishing a note on its own permalink post page, the contents of the note are likely abbreviated for the title of the page. The same abbreviation can be used for the p-name.
*** '''first sentence of the p-content/e-content''' property. It may be better for [http://indiewebcamp.com/syndication syndication] and [[link-preview]] purposes to provide just the first sentence of the note as the <code>p-name</code>. Similarly if only a portion of the content is syndicated to other sites, that portion can be marked up as the <code>p-summary</code>.
* ...
</div>

Resolved Issues:
* 2012-245 Resolved. See [http://krijnhoetmer.nl/irc-logs/microformats/20120830#l-120 2012-243 IRC discussion/consensus] for:
** Use '''<code>p-summary</code> instead of <code>p-entry-summary</code>'''. The historical semantic of "entry-summary" is not different from "summary" in any significant (or discernible way). Collapsing the two will simplify the overall microformats2 vocabularies further. In microformats2, entry-summary is no more.
** Use '''<code>e-content</code> instead of <code>e-entry-content</code>'''. Same point and advantage. In microformats2, entry-content is no more.
** '''drop <code>p-entry-title</code>'''. Unnecessary and subsumed by "p-name". Would consider move to backward compat only if cases are presented - known publishing uses are expected to be updated shortly.

=== h-event ===
{{main|h-event}}

The '''h-event''' microformat is for marking up events. This is an update to [[hCalendar]].

root class name: '''<code>h-event</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-event</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>p-summary</code>'''(*)
* '''<code>dt-start</code>'''
* '''<code>dt-end</code>'''
* '''<code>dt-duration</code>'''
* '''<code>p-description</code>'''
* '''<code>u-url</code>'''
* '''<code>p-category</code>'''
* '''<code>p-location</code>'''
* '''<code>p-geo</code>'''
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* ...

This is an update to [[hCalendar]].

(*)hCalendar-specific implementations that perform custom display or translation (e.g. to iCalendar .ics) {{should}} prefer <code>p-name</code> over <code>p-summary</code>, and use <code>p-summary</code> value(s) as a fallback if there is no <code>p-name</code>.

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-event" is found, don't look for a "vevent" on the same element.

compat root class name: <code id="vevent">vevent</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> - parse as '''<code>p-name</code>'''
* <code>dtstart</code> - parse as '''<code>dt-start</code>'''
* <code>dtend</code> - parse as '''<code>dt-end</code>'''
* <code>duration</code> - parse as '''<code>dt-duration</code>'''
* <code>description</code>
* <code>url</code> - parse as '''u-'''
* <code>category</code>
* <code>location</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>, and compat root <code>adr</code> in the absence of <code>h-adr</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* ...

=== h-geo ===
{{main|h-geo}}

The '''h-geo''' microformat is for marking up WGS84 geophysical coordinates. This is an update to [[geo]].

root class name: '''<code>h-geo</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-geo</nowiki>

properties:
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-geo" is found, don't look for an "geo" on the same element.

compat root class name: <code id="geo">geo</code>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>latitude</code>
* <code>longitude</code>

=== h-item ===
{{main|h-item}}

The '''h-item''' microformat is for marking up the item of an [[h-review]] or [[h-product]]. This is an update to part of [[hReview]].

root class name: '''<code>h-item</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-item</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>'''

Note: in practice, due to the microformats2 implied property rules, it is expected that most uses of "h-item" won't require any explicit properties at all (since microformats2 parsers will infer name, photo, and url properties from the structure of the element with "h-item" and its contained content/elements if any).

=== h-product ===
{{main|h-product}}

The '''h-product''' microformat is for marking up products. This is an update to [[hProduct]].

root class name: '''<code>h-product</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-product</nowiki>

properties:
* '''<code>p-name</code>''' - name of the product
* '''<code>u-photo</code>''' - photo of the product
* '''<code>p-brand</code>''' - manufacturer, can also be a nested <code>h-card</code>
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>e-description</code>'''
* '''<code>u-url</code>''' - URL of the product
* '''<code>u-identifier</code>''' - includes type (e.g. mpn, upc, isbn, issn, sn, vin, sku etc.) and value.
* '''<code>p-review</code>''' - a review of the product, can also be a nested <code>h-review</code>
* '''<code>p-price</code>''' - retail price of the product

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-product" is found, don't look for an "hproduct" on the same element.

compat root class name: <code id="hproduct">hproduct</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>photo</code> - parse as '''u-'''
* <code>brand</code>
* <code>category</code>
* <code>description</code>
* <code>identifier</code> - parse as '''u-'''
* <code>url</code> - parse as '''u-'''
* <code>review</code> - including compat root class <code>hreview</code> in the absence of <code>h-review</code>
* <code>price</code>

Note: [[hProduct]] has at least one experimental property which has real world adoption due to [[Google]] and [[Bing]] search support of hProduct. Currently this is: '''price'''

=== h-recipe ===
{{main|h-recipe}}

The '''h-recipe''' microformat is for marking up food recipes. This is an update to [[hRecipe]].

root class name: '''<code>h-recipe</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-recipe</nowiki>

properties:
* '''<code>p-name</code>''' - the name of the recipe
* '''<code>p-ingredient</code>''' - describes one or more ingredients used in the recipe.
* '''<code>p-yield</code>''' - Specifies the quantity produced by the recipe, like how many persons it satisfyies
* '''<code>e-instructions</code>''' - the method of the recipe.
* '''<code>dt-duration</code>''' - the time it takes to prepare the meal described by the recipe.
* '''<code>u-photo</code>''' - an accompanying image

Experimental properties with wide adoption
* '''<code>p-summary</code>''' - provides a short summary or introduction
* '''<code>p-author</code>''' - the person who wrote the recipe with <code>h-card</code>
* '''<code>dt-published</code>''' - the date the recipe was published
* '''<code>p-nutrition</code>''' - nutritional information like calories, fat, dietary fiber etc.
* ...

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-recipe" is found, don't look for an "hrecipe" on the same element.

compat root class name: <code id="hrecipe">hrecipe</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>ingredient</code>
* <code>yield</code>
* <code>instructions</code> - parse as '''e-'''
* <code>duration</code> - parse as '''dt-'''
* <code>photo</code> - parse as '''u-'''
* <code>summary</code>
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>nutrition</code>

Note: [[hRecipe]] has a number of experimental properties which have real world adoption due to [[Google]] recipe search support of hRecipe. These are: summary, author, published and nutrition

=== h-resume ===
{{main|h-resume}}

The '''h-resume''' microformat is for marking up resumes. This is an update to [[hResume]].

root class name: '''<code>h-resume</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-resume</nowiki>

properties:
* '''<code>p-summary</code>''' - overview of qualifications and objectives
* '''<code>p-contact</code>''' - current contact info in an <code>h-card</code>
* '''<code>p-education</code>''' - an education <code>h-calendar</code> event, years, nested <code>h-card</code> of the school, location.
* '''<code>p-experience</code>''' - a job or other professional experience <code>h-calendar</code> event, years, nested <code>h-card</code> of the organization, location, job-title.
* '''<code>p-skill</code>''' - a skill or ability, optionally including level and/or duration of experience
* '''<code>p-affiliation</code>''' - an affiliation with an <code>h-card</code> organization

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-resume" is found, don't look for an "hresume" on the same element.

compat root class name: <code id="hresume">hresume</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code>
* <code>contact</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>education</code> - including compat root <code>vevent</code> in the absence of <code>h-event</code>
* <code>experience</code> - including compat root <code>vevent</code> in the absence of <code>h-event</code>
* <code>skill</code>
* <code>affiliation</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>

Note: skill has a [[hresume-skill-brainstorm|proposed expansion into competency]] with explicit summary, rating and/or duration components. Based on existing real world adoption, we should consider an h-competency vocabulary with p-summary, p-rating, and dt-duration properties.

=== h-review ===
{{main|h-review}}

The '''h-review''' microformat is for marking up reviews. This is an update to [[hReview]]. See also [[h-item]].

root class name: '''<code>h-review</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-review</nowiki>

properties:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed i.e. 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
* '''<code>dt-reviewed</code>''' - date time of when the review was written
* '''<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-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>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>u-url</code>''' - URL of the review

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review" is found, don't look for an "hreview" on the same element.

compat root class name: <code id="hreview">hreview</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> parse as '''<code>p-name</code>'''
* <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>reviewer</code> - including compat root vcard in the absence of h-card
* <code>dtreviewed</code> - parse as '''dt-'''
* <code>rating</code>
* <code>best</code>
* <code>worst</code>
* <code>description</code> - parse as '''e-'''
* <code>rel="tag"</code> - parse as '''p-category'''
* <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>. Microformats2 parsers {{should}} map these URLs into the page scoped rel collection.

=== h-review-aggregate ===
{{main|h-review-aggregate}}

The '''h-review-aggregate''' microformat is for marking up aggregate reviews of a single item. This is an update to [[hreview-aggregate]]. See also [[h-item]].

root class name: '''<code>h-review-aggregate</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-review-aggregate</nowiki>

properties:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed i.e. 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-rating</code>''' - value from 1-5 indicating average rating for the item (5 best).
* '''<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-count</code>''' - number of reviews aggregated.
* '''<code>p-votes</code>''' - number of reviewers who have rated the product, thus contributing to the average rating.
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>u-url</code>''' - URL of the review

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review-aggregate" is found, don't look for an "hreview-aggregate" on the same element.

compat root class name: <code id="hreview-aggregate">hreview-aggregate</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> parse as '''<code>p-name</code>'''
* <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>rating</code>
* <code>best</code>
* <code>worst</code>
* <code>count</code>
* <code>votes</code>
* <code>rel="tag"</code> - parse as '''p-category'''
* <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.

=== v2 vocab notes ===
Notes:
* All v2 vocabularies are defined as flat lists of properties of an object/item, and thus can be used in microformats-2 syntax as shown, or in microdata items, or RDFa. The microformats-2 property parsing prefixes "p-", "u-", "dt-", "e-" are omitted when using defined properties in microdata itemprop and RDFa property as those syntaxes have their own element-specific parsing rules.
* Profile URLs are provided for use with the HTML4 <code>profile</code> attribute, microdata <code>itemtype</code> attribute, and RDFa <code>vocab</code> & <code>typeof</code> attributes (though the latter requires slicing off the trailing segment of the profile for the typeof attribute, and leaving the rest in vocab).
* microformats2 properties may also be explicitly bound as URIs using [[rel-profile]], the [[html5-profile]] attribute proposal, or an HTML5 'vocab' attribute instead. If URI bound terms are important to you, please express interest on [[rel-profile]], [[html5-profile]], or contribute to an [[html5-vocab]] draft.

=== v2 vocab to-do ===
To do:
* write a simple tutorial for creating/getting started with microformats-2 markup for new content
* examples in each h-* spec listed above of how to embed other microformats in them
* actual profile documents at <nowiki>http://microformats.org/profile/h-*</nowiki> URLs mentioned above.
* Provide any necessary microdata-specific language as needed (e.g. to be comparably understandable to the [http://www.whatwg.org/specs/web-apps/current-work/#vcard sample vCard4/hCard1 microdata vocabulary]. Also provide any necessary RDFa-specific language as needed. Both preferably in a generic vocabulary-independent way.
* write a porting guide mapping v1 property -> v2 property
** use-case: simple search/replace in templates (e.g. in case web author doesn't remember existing microformats vocabs and where they used them).
** advise using *both* in existing templates (e.g. in case some CSS depends on the existing microformats)
* analyzie/document how well the microformats2 model and vocabularies satisfy the [http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2009-May/019681.html use-cases used to design/create microdata].

== combining microformats ==
Since microformats2 uses simple flat sets of properties for each microformat, multiple microformats are combined to indicate additional structure.

=== h-event location h-card ===
Events commonly have venue information with additional structure, like address information. For example:

<syntaxhighlight lang="html">
<div class="h-event">
<a class="p-name u-url" href="http://indiewebcamp.com/2012">
IndieWebCamp 2012
</a>
from <time class="dt-start">2012-06-30</time>
to <time class="dt-end">2012-07-01</time> at
<span class="p-location h-card">
<a class="p-name p-org u-url" href="http://geoloqi.com/">
Geoloqi
</a>,
<span class="p-street-address">920 SW 3rd Ave. Suite 400</span>,
<span class="p-locality">Portland</span>,
<abbr class="p-region" title="Oregon">OR</abbr>
</span>
</div>
</syntaxhighlight>

The nested h-card used to structure the p-location of the h-event is represented as a structured value for "location" in the JSON, which has an additional key, "value" that represents the plain text version parsed from the p-location.

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-event"],
"properties": {
"name": ["IndieWebCamp 2012"],
"url": ["http://indiewebcamp.com/2012"],
"start": ["2012-06-30"],
"end": ["2012-07-01"],
"location": [{
"value": "Geoloqi",
"type": ["h-card"],
"properties": {
"name": ["Geoloqi"],
"org": ["Geoloqi"],
"url": ["http://geoloqi.com/"],
"street-address": ["920 SW 3rd Ave. Suite 400"],
"locality": ["Portland"],
"region": ["Oregon"]
}
}]
}
}]
}
</syntaxhighlight>

Questions:
<div class="discussion">
* Should the nested hCard be present also as a top-level item in the JSON? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
** My current (2012-243) leaning is no. - [[User:Tantek|Tantek]] 18:53, 30 August 2012 (UTC)
** If so, how do we avoid expansion of the JSON geometrically proportional to the depth of microformat nesting? (Or do we not worry about it?)
* Should there be a canonical hierarchical JSON and a canonical flattened JSON? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
** My current (2012-243) leaning is no, we stick with one canonical JSON for uf2 which is hierarchical. - [[User:Tantek|Tantek]] 18:53, 30 August 2012 (UTC)
** If so, should the flattened JSON have references from properties to nested microformats that have been pushed to the top level per flattening? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
*** If so, what convention does/do JSON follow for such synthetic local reference identifiers? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
</div>

Notes:
* The 'location' value reflects the visible text of its element, including spaces and punctuation, as well as the state abbreviation 'OR'. The 'h-card' property values are only what is marked up, and thus include structure values without extra punctuation, and the state takes the expanded form from the <code>title</code> attribute of its <code><abbr></code> element.

=== h-card org h-card ===
People often publish information general to their company rather than specific to them, in which case, they may wish to encapsulate that in separately nested microformat. E.g. here is a simple h-card example with org property:

[http://blog.lizardwrangler.com Mitchell Baker] (Mozilla Foundation)

with source:
<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<span class="p-org">Mozilla Foundation</span>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": ["Mozilla Foundation"]
}
}]
}
</syntaxhighlight>

Sometimes such organization affiliations are hyperlinked to the website of the organization:

[http://blog.lizardwrangler.com Mitchell Baker] ([http://mozilla.org/ Mozilla Foundation])

You can mark that up with a nested h-card:
<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
</syntaxhighlight>

Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an <code><a href></code> would.

'''FOR PARSERS ONLY:'''

The nested 'h-card' could be marked up as an 'h-org' as well, which adds it to the nested microformat's type array, all as part of the property specified by the 'p-org'.

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card h-org"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card", "h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
</syntaxhighlight>

'''FOR PARSERS ONLY:'''

Without a property class name like 'p-org' holding all the nested objects together, we need to introduce another array for nested children (similar to the existing DOM element notion of children) of a microformat that are not attached to a specific property:

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card","h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
</syntaxhighlight>

Since there's no property class name on the element with classes 'h-card' and 'h-org', the microformat representing that element is collected into the children array.

Such a nested microformat implies some relationship (containment, being related), but is not as useful as if the nested microformat was a specific property of its parent.

For this reason it's recommended that authors should not publish nested microformats without a property class name, and instead, when nesting microformats, authors should always specify a property class name (like 'p-org') on the same element as the root class name(s) of the nested microformat(s) (like 'h-card' and/or 'h-org').

'''FOR PARSERS ONLY:'''

Or the nested object could be only marked up with 'h-card'. Source:

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
</syntaxhighlight>

'''TO DO: Add h-event h-card example and JSON, per real world publishing examples like [http://www.swingtime.co.uk/List/ClSouth.html Swing Time: Classes in Southern England].'''

== authoring ==
=== minimal markup ===
The best way to use microformats-2 is with as little additional markup as possible. This keeps your code cleaner, improves its maintainability, and thus the quality and longevity of your microformats.

One big advantage of microformats-2 over previous microformats (and others) is the ability to add one class name to an existing element to create a structured item.

See the [[microformats-2#simple_microformats_2_examples|simple examples at the top]] for a start, e.g.

Simple hCards work just by adding <code>class="h-card"</code> :
<syntaxhighlight lang="html">
<span class="h-card">Frances Berriman</span>

<a class="h-card" href="http://benward.me">Ben Ward</a>

<img class="h-card" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>

<a class="h-card" href="http://tantek.com">
<img alt="Tantek Çelik" src="http://ttk.me/logo.jpg"/>
</a>
</syntaxhighlight>

* Tip: Inside an open tag, put the <code>class</code> attribute <em>first</em>, then any human text content attributes (e.g. <code>alt</code>), then URL attributes (e.g. <code>href</code> <code>src</code>), and lastly other attributes (e.g. <code>style</code>). Putting the class attribute first ties it closely to the element name/tag itself, makes it more obvious, and thus more likely to be kept up to date.

=== backward compatible ===
If you depend on current microformats [[implementations]], while they're being updated to support [[microformats2]], you can include both existing classic microformats and microformats2 markup.

In short: use both sets of class names simultaneously.

When doing so, use them on the same element, with the microformats-2 class name first, followed immediately by the existing microformats class name.

Here are the microformats-2 hCards from above with current [[hCard]] markup as well, which may require adding a wrapping element (e.g. a <code><span></code>) to separate the root class name element from explicit property class name elements:

<syntaxhighlight lang="html">
<span class="h-card vcard">
<span class="p-name fn">Frances Berriman</span>
</span>

<span class="h-card vcard">
<a class="p-name fn u-url url" href="http://benward.me">Ben Ward</a>
</span>

<span class="h-card vcard">
<img class="p-name fn u-photo photo" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>
</span>

<span class="h-card vcard">
<a class="u-url url" href="http://tantek.com">
<img class="p-name fn u-photo photo" alt="Tantek Çelik"
src="http://ttk.me/logo.jpg"/>
</a>
</span>
</syntaxhighlight>

Tips:
* use the microformats-2 class name first, e.g.
** <code>class="h-card vcard"</code>
** <code>class="u-url url"</code>
* and pair them when using an element for multiple properties, e.g.:
** <code>class="p-name fn u-url url"</code>
** <code>class="p-name fn u-photo photo"</code>
* put microformats classes after classes for CSS (since page authors will likely interact more with their own classes for design than with microformats classes), e.g. as used on individual microformats [[events]] pages:
** <code>class="event-page h-event vevent"</code>

The prefixes (h-, p-, etc.) of microformats2 class names provide easier recognition, and when followed by the similarly named existing class name, they're more easily recognized as related and thus kept together when the markup is maintained over time.

Related FAQ: [[microformats2-faq#when_using_both_h-card_and_vcard_which_should_be_first_and_why|When using both h-card and vcard which should be first and why?]]

== extensions ==
microformats2 is extensible by means of two separate but syntactically similar extension prefixes for experiments intended to be iterated & evolved and for vendor specific extensions not intended for standardization.

=== experimental extensions ===
There have been times when specific sites have wanted to extend microformats beyond the set of properties in the microformat vocabulary, and currently lack any '''experimental''' way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus:

For experimental extensions for the purpose of prototyping to learn more, iterate, towards possibly standardizing, use the <code>-x-</code> prefix before root and property class names.

Specifically:
* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a literal 'x' for an experimental extension

Examples:
* "p-x-prep-time" - a possible experimental property name to be added to [[h-recipe]] upon consideration/documentation of real-world usage/uptake.

See [[microformats2-experimental-properties]] for more examples.

=== <span id="VENDOR_EXTENSIONS">vendor extensions</span> ===
For vendor specific extensions, microformats2 uses a mechanism similar to CSS vendor extensions, using a similar syntax as experimental extensions, except with a vendor prefix instead of a literal 'x'.

* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-, numbers allowed after first character)

Examples:
* "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "one-ring" microformat root class name.
* "p-goog-preptime" - to represent [http://www.google.com/support/webmasters/bin/answer.py?answer=173379 Google's "preptime" property extension] to [[hRecipe]] (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.)

See [[vendor-prefixes]] for more examples.

=== extensions background ===
This extensibility mechanism is a composition of the following (at least somewhat) successful extension syntaxes:
* [http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords CSS 2.1 4.1.2.1 Vendor-specific extensions]
* IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [http://en.wikipedia.org/wiki/Internet_media_type]
* IETF MIME experimental fields (e.g. x-spam-score)
* HTTP header extensions (e.g. x-pingback)
* note also [http://www.mnot.net/blog/2009/02/18/x- some critical thoughts from mnot]

In particular:

Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.

Proprietary or experimental CSS3 property implementations have been very successful.

There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like:

* -moz-border-radius
* -webkit-border-radius

etc.

Note that these are merely string '''prefixes''', not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use.

This use of vendor specific CSS properties allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.

The benefits have been two-fold:
* designers have been able to make more attractive sites sooner (at least in some browsers)
* features have been market / real-world tested before being fully standardized, thus resulting in better features

Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and [https://secure.wikimedia.org/wikipedia/en/wiki/List_of_HTTP_header_fields#Common_non-standard_headers Wikipedia: HTTP header fields - non-standard headers] (could use RFC reference instead) respectively, like:

* application/x-latex (per [https://secure.wikimedia.org/wikipedia/en/wiki/Internet_media_type#Type_x Wikipedia Internet media type: Type x])
* x-spam-score (in email headers)
* X-Pingback (per [http://en.wikipedia.org/wiki/Pingback Wikipedia:Pingback])

Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases:

* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])

See [[microformats2-origins#VENDOR_EXTENSIONS]] for more background.

== validators ==
microformats2 validators:

{{new}} Test your microformatted web page with:
* https://pin13.net/mf2/

Barnaby Walters has a hosted version of the open source php-mf2 [[parser]] where you can enter your markup into a textarea and see how it's parsed:
* http://waterpigs.co.uk/php-mf2/

See the [[validators]] page for a longer list of validators.

== Examples in the wild ==
Please add new examples in the wild of microformats-2 to the top of this list. When it gets too big we can move it to a separate page like [[microformats-2-examples-in-wild]].

* ...
* David John Mead marks up his profile, blog posts and comments with h-card, h-entry and h-cite on [http://davidjohnmead.com davidjohnmead.com]
* [[User:Brian|Brian Suda]] marks up his blog posts up with h-entry and h-card on [http://optional.is/required/ optional.is]
* Ashton McAllan marks up her blog posts, reposts, comments and likes with h-entry, h-card and h-cite on [https://acegiak.net/ acegiak.net]
* Emma Kuo marks up her blog posts and notes with h-entry and h-card on [http://notenoughneon.com/ notenoughneon.com]
* Scott Jenson marks up his blog posts with h-entry and h-card on [http://jenson.org/ jenson.org]
* Emily McAllen marks up her blog posts with h-entry and h-card on [http://blackwoolholiday.com/ blackwoolholiday.com]
* Ryan Barrett marks up his blog posts, notes, replies and likes with h-entry and h-card on [https://snarfed.org/ snarfed.org]
* Barry Frost marks up his notes with h-entry, h-card and h-cite on [http://barryfrost.com/ barryfrost.com]
* Amber Case marks up her profile, blog posts, replies and notes with h-entry and h-card on [http://caseorganic.com/ caseorganic.com]
* Johannes Ernst marks up his blog posts with h-entry on [http://upon2020.com/blog/ upon2020.com]
* Michiel de Jong marks up his profile and notes with h-entry and h-card on [https://michielbdejong.com/ michielbdejong.com]
* Mike Taylor marks up his profile and blog posts with h-card and h-entry on [https://bear.im/bearlog/ bear.im]
* Erin Jo Ritchey marks up her profile, posts and comments using h-card, h-entry and h-cite with idno on [http://erinjo.is/ erinjo.is]
* Jeena Paradies marks up his profile, blog posts, notes and comments using h-card, h-entry and h-cite on [https://jeena.net/ jeena.net]
* Andy Sylvester marks up his profile, blog posts and comments using h-card and h-entry on [http://andysylvester.com/2014/03/01/howto-setting-up-the-selfoss-feed-reader-with-microformats-support/ andysylvester.com] (note: as of 2014-03-13 using h-entry for comments instead of correct h-cite --[[User:Barnabywalters|bw]] 14:44, 13 March 2014 (UTC))
* Hakan Demir marks up his Coupon and Voucher blog posts with h-entry and h-card on [http://www.gutscheinflagge.de/ gutscheinflagge.de]
* Chloe Weil marks up her blog posts with h-entry on [http://chloeweil.com/blog chloeweil.com]
* Christophe Ducamp marks up his blog posts and profile with h-entry and h-card on [http://christopheducamp.com/ christopheducamp.com]
* Glenn Jones marks up his blog posts, notes, replies, profile and comments with h-entry, h-card and h-cite on [http://glennjones.net/ glennjones.net]
* Marcus Povey marks up his blog posts and profile with h-entry and h-card on [http://www.marcus-povey.co.uk/ marcus-povey.co.uk]
* Eugen Busoiu marks up his web profile with h-card on [http://eugenbusoiu.com/#utm_source=microformats2&utm_medium=h-card&utm_campaign=Microformats eugenbusoiu.com]]
* Matthias Pfefferle marks up his blog posts, comments and profile with h-card, h-cite and h-entry on [http://notizblog.org/ notizblog.org]
* Kyle Mahan marks up his profile and notes with h-card and h-entry on [http://kylewm.com/ kylewm.com]
* Emil Björklund marks up his blog posts with h-entry and h-card ([http://thatemil.com/blog/2013/09/16/webmentioning-adactio/ example])
* App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 ([https://alpha.app.net/voidfiles example])
* Brett Comnes marks up his posts with h-entry and h-card ([http://bret.io/2013/06/29/getting-started-with-bower/ example])
* Ben Werdmuller marks up his posts with h-card and h-entry, u-in-reply-to and u-like ([http://werd.io/view/51d5097fbed7ded0633a5956 example])
* Sandeep Shetty marks his posts up with h-card and h-entry, as well as draft u-in-reply-to and experimental u-like properties ([http://sandeep.io/101 example])
* Laurent Eschenauer marks up his posts with h-entry ([http://eschnou.com/entry/first-autonomous-flight-of-my-nodecopter-62-24992.html example])
* Tom Morris marks up his posts using h-entry ([http://tommorris.org/posts/8417 example])
* Sinolandquality marks up some of their content using h-feed and h-entry on [http://www.sinolandquality.com/Blog/?page_id=3516&utm_content=buffere4d40&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer sinolandquality.com]
* [http://www.w3.org/conf/ W3Conf 2013] uses h-event for the main event, and h-card for all the speakers and notable attendees. The h-cards make particularly good use of implied name, url, and photo properties.
* [http://wordpress.org/extend/themes/sempress SemPress] is a WordPress theme that supports h-card, h-feed/h-entry and h-as-*
* [http://the-pastry-box-project.net/ The Pastry Box Project] use h-card and h-entry markup on their homepage and individual thoughts pages
* Tom Morris uses h-card and [[XFN]] to markup [http://tommorris.org/pages/blogroll his blogroll].
* Aaron Parecki uses h-card to markup both authorship and references to people in his notes permalinks, e.g. [http://aaronparecki.com/2012/230/reply/1 2012/230/reply/1].
* [http://tantek.com/ Tantek Çelik] uses h-card, h-event, and h-entry on his home page, as well as h-entry on all post permalinks, e.g. [http://tantek.com/2012/243/t1/name-beats-title-modern-use-dubline-core-wrong-uf2 2012-243 post], with [[rel-prev]]/[[rel-next]] (if applicable) to indicate prev/next posts, and with [[rel-author]] to his home page with canonical hCard to indicate authorship.
* [http://waterpigs.co.uk/ Barnaby Walters] uses h-card on his home page, h-card, h-entry and XFN markup on his [http://waterpigs.co.uk/notes notes page].
** 2013-01-25 Barnaby Walters: <cite>[http://waterpigs.co.uk/articles/experimental-markup Experimental Markup]</cite> - describes how he's using microformats2 vocabularies: <code>h-adr</code>, <code>h-card</code>, <code>h-entry</code>, <code>h-event</code>, <code>h-geo</code>, <code>h-review</code>, and experimental vocabularies: <code>h-feed</code> (embedded for update histories), [[activity-streams]] objects <code>h-as-article</code>, <code>h-as-collection</code>, <code>h-as-note</code>, <code>h-as-update</code>, as well as experimental properties: <code>u-alternate</code> and <code>u-as-downstream-duplicate</code> (links to POSSE copies), and <code>u-in-reply-to</code> (links to content that the posts are in reply to).
* [http://tantek.com/presentations/2012/06/microformats microformats.org at 7 years] presentation with h-event and h-card markup for people and organizations.
* [http://tantek.com/presentations/2012/06/pdf2012-indieweb.html Rise of the Indie Web hCards] (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has [[microformats-2]] h-calendar and h-card markup
* WebMaker by Mozilla has [[microformats-2]] h-calendar and h-card on event search (e.g. [https://webmaker.org/en-US/events/near/?lat=45.5234515&lng=-122.6762071 search near Portland Oregon]) and event pages (e.g. [https://webmaker.org/en-US/events/192f56eb9/ IndieWebCamp 2012]).[https://twitter.com/microformats/status/212207925643587585]
* WebFWD by Mozilla has [[microformats-2]] h-card markup on [https://webfwd.org/about/experts/ experts] and [https://webfwd.org/about/team/ team] pages
* [http://indiewebcamp.com IndieWebCamp] has [[microformats-2]] h-event markup with nested h-cards for the organizers and the location.
* [https://wiki.mozilla.org/Events Mozilla Events] page has [[microformats-2]] h-event markup with attendees marked up with h-card.
* The [http://pdx.esri.com/blog/2013/10/17/introducing-mapattack/ Esri PDX Blog] has h-entry markup on all blog posts (as of 2013-10-19), and h-product markup on [http://pdx.esri.com/projects/terraformer/ project pages]

=== offline ===
* spreadly marks up share permalink pages with h-entry, as well as minimal h-cards and experimental p-like properties

== Implementations ==
{{new}} Test your microformatted web page with:
=== Live Textarea Input ===
Use any of these to enter HTML+microformats2 markup and see the parsed result!
* http://glennjones.net/tools/microformats/
* https://pin13.net/mf2/ (where it says "Microformats Parser")

=== Blogging tools ===
* '''Storytlr''' parses the 'target' from [http://indiewebcamp.com/pingback pingbacks] for [https://github.com/storytlr/storytlr/blob/master/protected/application/public/controllers/PingbackController.php#L63 h-entry with properties and nested h-card] for information to automatically display in the [http://eschnou.com/entry/testing-indieweb-federation-with-waterpigscouk-aaronpareckicom-and--62-24908.html comments section on a post].

=== Converters ===
* '''[https://github.com/snarfed/granary granary]''' is a library and REST API that converts between silo APIs, [[ActivityStreams]], [[microformats2]], and Atom (all directions). Supported silos include Facebook, Twitter, Instagram, Google+, and Flickr. Users include [http://brid.gy/ Bridgy], [http://reader.kylewm.com/ Woodwind], and [https://facebook-atom.appspot.com/ facebook-atom] and [https://twitter-atom.appspot.com/ twitter-atom], among others.

* '''[http://pipes.yahoo.com/pipes/pipe.info?_id=afc5568b4e8643bfb05436b1caaf91bc microformats to RSS]''' - a Yahoo! pipe that converts a URL containing an [[h-feed]] containing h-entries, into an [[RSS]] feed ([http://waterpigs.co.uk/notes/4SeNi5/ 2013-10-21 blog post announcing])

* '''[https://xray.p3k.io XRay]''' ([https://github.com/aaronpk/XRay source code]) - Returns a normalized representation of the microformats data at a URL

=== Parsers ===
Parsers, open source libraries, in alphabetical order by programming language:

If you are implementing a microformats2 parser, see:
* [[microformats2-parsing]]

==== Parsers in production ====
The following parsers are of very high quality, in active development, and use on live sites on the web in production.

===== Java =====
* [[any23]] Apache Any23 (Anything to Triples)] a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents: http://any23.apache.org

===== Javascript =====
* '''microformats-parser''' for both browser and node.js
** github open source: https://github.com/aimee-gm/microformats-parser (current)
** live: https://aimee-gm.github.io/microformats-parser/

Previously:
* '''microformat-node''' Node.js microformats2 parser
** github open source: https://github.com/microformats/microformat-node (current)
*** forked from https://github.com/glennjones/microformat-node
** test suite: https://github.com/microformats/tests

** command line: https://github.com/JerrySievert/mf2
* '''microformat-shiv''' - cross browser javascript microformats2 parser which can also be used in browser extensions.

** github open source: https://github.com/glennjones/microformat-shiv

===== PHP =====
* '''<span id="php-mf2">php-mf2</span>''' - PHP microformats2 parser
** github open source: https://github.com/indieweb/php-mf2
** Packagist: https://packagist.org/packages/mf2/mf2
** live:
*** textarea entry: http://waterpigs.co.uk/php-mf2/
*** URL and textarea entry: https://pin13.net/mf2/
** [https://github.com/barnabywalters/php-mf-cleaner mf-cleaner]: functions for working with the raw mf2 data structure

===== Python =====
* '''mf2py''' Python microformats2 parser
** main entry: [[mf2py]]
** github open source: https://github.com/tommorris/mf2py
** live:
*** URL entry: [https://mf2py.herokuapp.com/ mf2py.herokuapp.com]
*** textarea entry: https://kartikprabhu.com/connection/mfparser
*** another textarea: http://www.unmung.com/?html=
*** URL and/or textarea: https://kylewm.com/services/mf2

===== Ruby =====
* '''indieweb/microformats-ruby''' Ruby microformats parser
** github open source: https://github.com/indieweb/microformats-ruby
** live text entry: https://microformats-parser-ruby.herokuapp.com

===== Haskell =====
* '''myfreeweb/microformats2-parser''' Haskell microformats2 parser
** github open source: https://github.com/myfreeweb/microformats2-parser
** live textarea entry: https://unrelenting.technology/mf2/

==== Development parsers ====
The following parsers are in-development and have key microformats2 functionality yet are incomplete, not fully tested, or have other limitations. Contributions welcome!

===== Erlang =====
* '''hazybluedot/mf2erl''' Erlang microformats2 parser
** github open source: https://github.com/hazybluedot/mf2erl

===== Elixir =====
* '''ckruse/microformats-elixir''' Elixir microformats2 parser
** github open source: https://github.com/ckruse/microformats2-elixir

===== Go =====
* '''willnorris/microformats''' Golang microformats2 parser
** github open source: https://github.com/willnorris/microformats
** live textarea entry: https://go.microformats.io/

===== Java =====
* '''Apache Any23''' a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents. Supports Microformats1 and 2.
** Download recent release: http://any23.apache.org/download.html
** live: http://any23-vm.apache.org/
** source: http://any23.apache.org/build-src.html
* '''mf2j''' An early-stage Java microformats2 parser
** github open source: https://github.com/kylewm/mf2j
** live: https://mf2j.herokuapp.com/?url={http://example.com}

===== Perl =====
* '''Web::Microformats2''' Perl microformats2 parser
** https://metacpan.org/pod/Web::Microformats2
** open source: https://github.com/jmacdotorg/microformats2-perl

==== Experiments ====
Experiments and other proof of concept microformat2 parsing support.
* '''Rust''' - https://gitlab.com/maxburon/microformats-parser
* ...

=== Outreach ===
* [https://github.com/mozilla/fathom/issues/42 Mozilla Fathom: examples with nested classes, e.g. microformats2]

== Presentations ==
Presentations about microformats2:
* 2013-01-24 <cite>[http://waterpigs.co.uk/presentations/microformats-2/ Microformats 2]</cite> presentation by [[User:Barnabywalters|Barnaby Walters]] at the [[events/2013-01-24-exeter-web-meetup|Exeter Web Meetup]] in Devon, UK.
* 2012-09-21 <cite>[http://tantek.com/presentations/2012/09/microformats2/ microformats2 & bits of HTML5: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-09-21-refreshlx|RefreshLX]] in Lisbon, Portugal.
* 2012-07-21 <cite>[http://tantek.com/presentations/2012/07/html5-uf2/ HTML5 and microformats2: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-07-21-cascadesf|Innovators of the Web conference]] in San Francisco, CA.
* 2012-07-14 <cite>[http://tantek.com/presentations/2012/07/html5-microformats2/ HTML5 and microformats2: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-07-14-open-web-camp-4|Open Web Camp IV]] in San Jose, CA.

== Testimonials ==
* <blockquote class="twitter-tweet">To prove the web standards community can come up with better standards than the SE’s, compare this: http://microformats.org/wiki/microformats-2 with schema . org — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298907685452124160 2013-02-05 13:35]</blockquote>
* <blockquote class="twitter-tweet">... I’m hoping SE’s will pick up microformats2. It’s SO much cleaner. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298911287117758464 2013-02-05 13:49]</blockquote>
* <blockquote class="twitter-tweet">... But damn Microformats2 are sexy. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298912179292344320 2013-02-05 13:53]</blockquote>

== Origins ==
This page was originally used to brainstorm and develop microformats2 in an exploratory manner, with problem statements, questions, lessons learned from past and other formats.

Now that [[microformats2-parsing]] is a Microformats specification, the original brainstorming has been moved to a separate page for anyone who wants to understand more about how we came up with the design of microformats2, and how it evolved in the early years.
* [[microformats2-origins]]

== See Also ==
* [[microformats2]]
* [[microformats2-brainstorming]] - moving more experimental / undeveloped / and rejected thoughts ideas here to simplify/progress *this* page further.
* [[microformats2-experimental-properties]] - listing experimental (-x- prefixed) properties and their use
* [[microformats2-prefixes]]
* [[vendor-prefixes]]
* [[microformats2-faq]]
* [[microformats2-parsing]]
* 2010-05-02 [[events/2010-05-02-microformats-2-0|microformats 2.0 discussion session at FOO East]]

microformats2

2024-03-01T18:46:28Z

GRegorLove: /* Parsers */ +link to /microformats2-parsing

<span style="float:right">__TOC__</span>
Welcome to the microformats2 home page.

== Summary ==
Microformats2 is the latest version of microformats, the simplest way to markup structured information in HTML. Microformats2 improves ease of use and implementation for <em>both</em> authors (publishers) and developers ([[microformats2-parsing|parser]] implementers).

Microformats2 replaces and supersedes both classic microformats (sometimes called microformats1), as well as incorporates lessons learned from [[microdata]] and [[RDFa]].

=== simple microformats2 examples ===
Here are a few <span id="simple_microformats_2_examples">simple microformats2 examples</span> along with canonical [[JSON]].

==== person example ====
* Simple person reference:
<syntaxhighlight lang="html">
<span class="h-card">Frances Berriman</span>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Frances Berriman"]
}
}]
}
</syntaxhighlight>

----

==== hyperlinked person ====
* Simple hyperlinked person reference
<syntaxhighlight lang="html">
<a class="h-card" href="http://benward.me">Ben Ward</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Ben Ward"],
"url": ["http://benward.me"]
}
}]
}
</syntaxhighlight>

----

==== hyperlinked person image ====
* Simple hyperlinked person image
<syntaxhighlight lang="html">
<a class="h-card" href="http://rohit.khare.org/">
<img alt="Rohit Khare"
src="https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg" />
</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Rohit Khare"],
"url": ["http://rohit.khare.org/"],
"photo": ["https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg"]
}
}]
}
</syntaxhighlight>

Additional simple cases details in [[microformats-2-implied-properties]].

----

==== detailed person example ====
* More detailed person
<syntaxhighlight lang="html">
<div class="h-card">
<img class="u-photo" alt="photo of Mitchell"
src="https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"/>
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="u-url"
href="https://twitter.com/MitchellBaker"
>@MitchellBaker</a>)
<span class="p-org">Mozilla Foundation</span>
<p class="p-note">
Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities.
</p>
<span class="p-category">Strategy</span>
<span class="p-category">Leadership</span>
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"photo": ["https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"],
"name": ["Mitchell Baker"],
"url": [
"http://blog.lizardwrangler.com/",
"https://twitter.com/MitchellBaker"
],
"org": ["Mozilla Foundation"],
"note": ["Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities."],
"category": [
"Strategy",
"Leadership"
]
}
}]
}
</syntaxhighlight>

----
=== details from examples ===
Details demonstrated by the examples:
# The JSON <code>"type"</code> uses the full microformat root class name (e.g. <code>"h-card"</code>) for consistent identification.
# all properties are optional and syntactically plural with parsed values provided in document order; particular microformats (and applications there-of) may apply specific/singular semantics to first value of a property.

=== microformats2 design ===

microformats2 has the following key design aspects:

; Prefixes for class names
: All microformats class names use prefixes. Prefixes are '''syntax independent from vocabularies''', which are developed separately.
* <code>h-*</code> for root class names (e.g. <code>h-card</code>)
* <code>p-*</code> for plain text properties (e.g. <code>p-name</code>)
* <code>u-*</code> for URL properties (e.g. <code>u-photo</code>)
* <code>dt-*</code> for date/time properties (e.g. <code>dt-bday</code>)
* <code>e-*</code> for embedded markup properties (e.g. <code>e-note</code>)<br />

See [[microformats2-prefixes]] for more details.

; Flat sets of optional properties
: All microformats consist of a root, and a collection of properties. Hierarchical data is represented with nested microformats, typically as property values themselves. Properties are all optional and potentially multivalued (applications needing a singular semantic may use first instance).

; Single class markup for common uses
: Common simple markup patterns require only a single microformat root class name, which parsers use to find a few generic properties: <code>name</code>, <code>url</code>, <code>photo</code>. The simple microformats2 examples above demonstrate these.

----

Parsing each prefix (including generating canonical JSON) is detailed step-by-step in:
* The '''[[microformats2-parsing|microformats2 parsing specification]]'''

'''Note:''' Most properties are specified and used with a single specific prefix (or occasionally two or three) that is self-evident from context. However, any parsing prefix can be used with any property, especially if you find a good reason to do so!

== v2 vocabularies ==
Status: '''<span id="draft_v2_vocabularies">draft</span>'''. Please review and provide feedback in [[IRC]].
* [[h-adr]]
* [[h-card]]
* [[h-entry]]
* [[h-event]]
* [[h-feed]]
* [[h-geo]]
* [[h-item]]
* [[h-listing]]
* [[h-product]]
* [[h-recipe]]
* [[h-resume]]
* [[h-review]]
* [[h-review-aggregate]]

See below for vocabulary summaries.

=== h-adr ===
{{main|h-adr}}

The '''h-adr''' microformat is for marking up structured locations such as addresses, physical and/or postal. This is an update to [[adr]].

root class name: '''<code>h-adr</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-adr</nowiki>

properties:
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-street-address</code>'''
* '''<code>p-locality</code>'''
* '''<code>p-region</code>'''
* '''<code>p-postal-code</code>'''
* '''<code>p-country-name</code>'''
* '''<code>p-label</code>''' - new in [[vCard4]] ([[RFC6350]])
* '''<code>p-geo</code>''' (or '''<code>u-geo</code>''' with a RFC 5870 geo: URL) - new in [[vCard4]] ([[RFC6350]])
* '''<code>p-latitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-longitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-adr" is found, don't look for an "adr" on the same element.

compat root class name: <code id="adr">adr</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>post-office-box</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>

=== h-card ===
{{main|h-card}}

The '''h-card''' microformat is for marking up people and organizations. This is an update to [[hCard]].

root class name: '''<code>h-card</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-card</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>p-honorific-prefix</code>'''
* '''<code>p-given-name</code>'''
* '''<code>p-additional-name</code>'''
* '''<code>p-family-name</code>'''
* '''<code>p-sort-string</code>'''
* '''<code>p-honorific-suffix</code>'''
* '''<code>p-nickname</code>'''
* '''<code>u-email</code>'''
* '''<code>u-logo</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>'''
* '''<code>u-uid</code>'''
* '''<code>p-category</code>'''
* '''<code>p-adr</code>'''
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-street-address</code>'''
* '''<code>p-locality</code>'''
* '''<code>p-region</code>'''
* '''<code>p-postal-code</code>'''
* '''<code>p-country-name</code>'''
* '''<code>p-label</code>'''
* '''<code>p-geo</code>''' or '''<code>u-geo</code>''' with a RFC 5870 geo: URL, new in [[vCard4]] ([[RFC6350]])
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-tel</code>'''
* '''<code>p-note</code>'''
* '''<code>dt-bday</code>'''
* '''<code>u-key</code>'''
* '''<code>p-org</code>'''
* '''<code>p-job-title</code>''' - previously 'title' in hCard, disambiguated.
* '''<code>p-role</code>
* '''<code>u-impp</code>''' per RFC 4770, new in [[vCard4]] ([[RFC6350]])
* '''<code>p-sex</code>''' new in [[vCard4]] ([[RFC6350]])
* '''<code>p-gender-identity</code>''' new in [[vCard4]] ([[RFC6350]])
* '''<code>dt-anniversary</code>''' new in [[vCard4]] ([[RFC6350]])
* ...

Reserved properties: (properties not used much (if at all) in practice)
* '''<code>p-organization-name</code>'''
* '''<code>p-organization-unit</code>'''
* '''<code>p-tz</code>'''
* '''<code>dt-rev</code>'''
* ...

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-card" is found, don't look for a "vcard" on the same element.

compat root class name: <code id="vcard">vcard</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>honorific-prefix</code>
* <code>given-name</code>
* <code>additional-name</code>
* <code>family-name</code>
* <code>honorific-suffix</code>
* <code>nickname</code>
* <code>email</code> - parse as '''u-'''
* <code>logo</code> - parse as '''u-'''
* <code>photo</code> - parse as '''u-'''
* <code>url</code> - parse as '''u-'''
* <code>uid</code> - parse as '''u-'''
* <code>category</code>
* <code>adr</code> - parse as '''<code>p-adr h-adr</code>''' including compat root class <code>adr</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>
* <code>label</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root class <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* <code>tel</code>
* <code>note</code>
* <code>bday</code> - parse as '''dt-'''
* <code>key</code> - parse as '''u-'''
* <code>org</code>
* <code>organization-name</code>
* <code>organization-unit</code>
* <code>title</code> - parse as '''p-job-title'''
* <code>role</code>
* ...

Reserved: (backward compat properties that parsers {{may}} implement, if they do, they {{must}} implement in this way:
* <code>tz</code>
* <code>rev</code> - parse as '''dt-'''
* ...

Note: use of 'value' within 'tel' should be automatically handled by the support of the [[value-class-pattern]]. And for now, the 'type' subproperty of 'tel' is dropped/ignored. If there is demonstrable documented need for additional tel types (e.g. fax), we can introduce new flat properties as needed (e.g. p-tel-fax).

=== h-entry ===
{{main|h-entry}}

The '''h-entry''' microformat is for marking up syndicatable content such as blog posts, notes, articles, comments, photos and similar. This is an update to [[hAtom]].

root class name: '''<code>h-entry</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-entry</nowiki>

properties:
* '''<code>p-name</code>''' (was p-entry-title, see issues)
* '''<code>p-summary</code>''' (was p-entry-summary, see issues)
* '''<code>e-content</code>''' (was e-entry-content, see issues)
* '''<code>dt-published</code>'''
* '''<code>dt-updated</code>'''
* '''<code>p-author</code>'''
* '''<code>p-category</code>'''
* '''<code>u-url</code>'''
* '''<code>u-uid</code>'''
* '''<code>p-geo</code>'''
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''

This is an update to [[hAtom]].

Brainstorming:

The following properties are proposed additions to h-entry above and beyond what hAtom (or Atom) provides, based on various existing link preview markup conventions:
* '''<code>u-photo</code>'''
* '''<code>u-audio</code>''' - consider special u- parsing rules for <code><audio></code>
* '''<code>u-video</code>''' - consider special u- parsing rules for <code><video></code>
* '''<code>u-in-reply-to</code>''' - for links to other posts that this post is a reply to (comment regarding, etc.)

Backward compatibility:

(*)hAtom-specific implementations that perform custom display or translation (e.g. to Atom XML) {{should}} prefer <code>p-name</code> over <code>p-entry-title</code>, and use <code>p-entry-title</code> value(s) as a fallback if there is no <code>p-name</code>.

For hAtom backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-entry" is found, don't look for a "hentry" on the same element.

compat root class name: <code id="hentry">hentry</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>entry-title</code> - parse as '''<code>p-name</code>'''
* <code>entry-summary</code>
* <code>entry-content</code> - parse as '''e-'''
* <code>published</code> - parse as '''dt-'''
* <code>updated</code> - parse as '''dt-'''
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>category</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* ...

<span id="h-entry-faq">FAQ:</span>
<div class="discussion">
* '''What is the <code>p-name</code> of a [http://indiewebcamp.com/note note]?'''
** A few options, from simplest to most detailed.
*** '''same as the p-content/e-content''' property.
*** '''same as the <code>title</code> element''' on the note permalink post page. When publishing a note on its own permalink post page, the contents of the note are likely abbreviated for the title of the page. The same abbreviation can be used for the p-name.
*** '''first sentence of the p-content/e-content''' property. It may be better for [http://indiewebcamp.com/syndication syndication] and [[link-preview]] purposes to provide just the first sentence of the note as the <code>p-name</code>. Similarly if only a portion of the content is syndicated to other sites, that portion can be marked up as the <code>p-summary</code>.
* ...
</div>

Resolved Issues:
* 2012-245 Resolved. See [http://krijnhoetmer.nl/irc-logs/microformats/20120830#l-120 2012-243 IRC discussion/consensus] for:
** Use '''<code>p-summary</code> instead of <code>p-entry-summary</code>'''. The historical semantic of "entry-summary" is not different from "summary" in any significant (or discernible way). Collapsing the two will simplify the overall microformats2 vocabularies further. In microformats2, entry-summary is no more.
** Use '''<code>e-content</code> instead of <code>e-entry-content</code>'''. Same point and advantage. In microformats2, entry-content is no more.
** '''drop <code>p-entry-title</code>'''. Unnecessary and subsumed by "p-name". Would consider move to backward compat only if cases are presented - known publishing uses are expected to be updated shortly.

=== h-event ===
{{main|h-event}}

The '''h-event''' microformat is for marking up events. This is an update to [[hCalendar]].

root class name: '''<code>h-event</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-event</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>p-summary</code>'''(*)
* '''<code>dt-start</code>'''
* '''<code>dt-end</code>'''
* '''<code>dt-duration</code>'''
* '''<code>p-description</code>'''
* '''<code>u-url</code>'''
* '''<code>p-category</code>'''
* '''<code>p-location</code>'''
* '''<code>p-geo</code>'''
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* ...

This is an update to [[hCalendar]].

(*)hCalendar-specific implementations that perform custom display or translation (e.g. to iCalendar .ics) {{should}} prefer <code>p-name</code> over <code>p-summary</code>, and use <code>p-summary</code> value(s) as a fallback if there is no <code>p-name</code>.

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-event" is found, don't look for a "vevent" on the same element.

compat root class name: <code id="vevent">vevent</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> - parse as '''<code>p-name</code>'''
* <code>dtstart</code> - parse as '''<code>dt-start</code>'''
* <code>dtend</code> - parse as '''<code>dt-end</code>'''
* <code>duration</code> - parse as '''<code>dt-duration</code>'''
* <code>description</code>
* <code>url</code> - parse as '''u-'''
* <code>category</code>
* <code>location</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>, and compat root <code>adr</code> in the absence of <code>h-adr</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* ...

=== h-geo ===
{{main|h-geo}}

The '''h-geo''' microformat is for marking up WGS84 geophysical coordinates. This is an update to [[geo]].

root class name: '''<code>h-geo</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-geo</nowiki>

properties:
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-geo" is found, don't look for an "geo" on the same element.

compat root class name: <code id="geo">geo</code>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>latitude</code>
* <code>longitude</code>

=== h-item ===
{{main|h-item}}

The '''h-item''' microformat is for marking up the item of an [[h-review]] or [[h-product]]. This is an update to part of [[hReview]].

root class name: '''<code>h-item</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-item</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>'''

Note: in practice, due to the microformats2 implied property rules, it is expected that most uses of "h-item" won't require any explicit properties at all (since microformats2 parsers will infer name, photo, and url properties from the structure of the element with "h-item" and its contained content/elements if any).

=== h-product ===
{{main|h-product}}

The '''h-product''' microformat is for marking up products. This is an update to [[hProduct]].

root class name: '''<code>h-product</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-product</nowiki>

properties:
* '''<code>p-name</code>''' - name of the product
* '''<code>u-photo</code>''' - photo of the product
* '''<code>p-brand</code>''' - manufacturer, can also be a nested <code>h-card</code>
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>e-description</code>'''
* '''<code>u-url</code>''' - URL of the product
* '''<code>u-identifier</code>''' - includes type (e.g. mpn, upc, isbn, issn, sn, vin, sku etc.) and value.
* '''<code>p-review</code>''' - a review of the product, can also be a nested <code>h-review</code>
* '''<code>p-price</code>''' - retail price of the product

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-product" is found, don't look for an "hproduct" on the same element.

compat root class name: <code id="hproduct">hproduct</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>photo</code> - parse as '''u-'''
* <code>brand</code>
* <code>category</code>
* <code>description</code>
* <code>identifier</code> - parse as '''u-'''
* <code>url</code> - parse as '''u-'''
* <code>review</code> - including compat root class <code>hreview</code> in the absence of <code>h-review</code>
* <code>price</code>

Note: [[hProduct]] has at least one experimental property which has real world adoption due to [[Google]] and [[Bing]] search support of hProduct. Currently this is: '''price'''

=== h-recipe ===
{{main|h-recipe}}

The '''h-recipe''' microformat is for marking up food recipes. This is an update to [[hRecipe]].

root class name: '''<code>h-recipe</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-recipe</nowiki>

properties:
* '''<code>p-name</code>''' - the name of the recipe
* '''<code>p-ingredient</code>''' - describes one or more ingredients used in the recipe.
* '''<code>p-yield</code>''' - Specifies the quantity produced by the recipe, like how many persons it satisfyies
* '''<code>e-instructions</code>''' - the method of the recipe.
* '''<code>dt-duration</code>''' - the time it takes to prepare the meal described by the recipe.
* '''<code>u-photo</code>''' - an accompanying image

Experimental properties with wide adoption
* '''<code>p-summary</code>''' - provides a short summary or introduction
* '''<code>p-author</code>''' - the person who wrote the recipe with <code>h-card</code>
* '''<code>dt-published</code>''' - the date the recipe was published
* '''<code>p-nutrition</code>''' - nutritional information like calories, fat, dietary fiber etc.
* ...

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-recipe" is found, don't look for an "hrecipe" on the same element.

compat root class name: <code id="hrecipe">hrecipe</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>ingredient</code>
* <code>yield</code>
* <code>instructions</code> - parse as '''e-'''
* <code>duration</code> - parse as '''dt-'''
* <code>photo</code> - parse as '''u-'''
* <code>summary</code>
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>nutrition</code>

Note: [[hRecipe]] has a number of experimental properties which have real world adoption due to [[Google]] recipe search support of hRecipe. These are: summary, author, published and nutrition

=== h-resume ===
{{main|h-resume}}

The '''h-resume''' microformat is for marking up resumes. This is an update to [[hResume]].

root class name: '''<code>h-resume</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-resume</nowiki>

properties:
* '''<code>p-summary</code>''' - overview of qualifications and objectives
* '''<code>p-contact</code>''' - current contact info in an <code>h-card</code>
* '''<code>p-education</code>''' - an education <code>h-calendar</code> event, years, nested <code>h-card</code> of the school, location.
* '''<code>p-experience</code>''' - a job or other professional experience <code>h-calendar</code> event, years, nested <code>h-card</code> of the organization, location, job-title.
* '''<code>p-skill</code>''' - a skill or ability, optionally including level and/or duration of experience
* '''<code>p-affiliation</code>''' - an affiliation with an <code>h-card</code> organization

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-resume" is found, don't look for an "hresume" on the same element.

compat root class name: <code id="hresume">hresume</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code>
* <code>contact</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>education</code> - including compat root <code>vevent</code> in the absence of <code>h-event</code>
* <code>experience</code> - including compat root <code>vevent</code> in the absence of <code>h-event</code>
* <code>skill</code>
* <code>affiliation</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>

Note: skill has a [[hresume-skill-brainstorm|proposed expansion into competency]] with explicit summary, rating and/or duration components. Based on existing real world adoption, we should consider an h-competency vocabulary with p-summary, p-rating, and dt-duration properties.

=== h-review ===
{{main|h-review}}

The '''h-review''' microformat is for marking up reviews. This is an update to [[hReview]]. See also [[h-item]].

root class name: '''<code>h-review</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-review</nowiki>

properties:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed i.e. 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
* '''<code>dt-reviewed</code>''' - date time of when the review was written
* '''<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-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>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>u-url</code>''' - URL of the review

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review" is found, don't look for an "hreview" on the same element.

compat root class name: <code id="hreview">hreview</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> parse as '''<code>p-name</code>'''
* <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>reviewer</code> - including compat root vcard in the absence of h-card
* <code>dtreviewed</code> - parse as '''dt-'''
* <code>rating</code>
* <code>best</code>
* <code>worst</code>
* <code>description</code> - parse as '''e-'''
* <code>rel="tag"</code> - parse as '''p-category'''
* <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>. Microformats2 parsers {{should}} map these URLs into the page scoped rel collection.

=== h-review-aggregate ===
{{main|h-review-aggregate}}

The '''h-review-aggregate''' microformat is for marking up aggregate reviews of a single item. This is an update to [[hreview-aggregate]]. See also [[h-item]].

root class name: '''<code>h-review-aggregate</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-review-aggregate</nowiki>

properties:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed i.e. 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-rating</code>''' - value from 1-5 indicating average rating for the item (5 best).
* '''<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-count</code>''' - number of reviews aggregated.
* '''<code>p-votes</code>''' - number of reviewers who have rated the product, thus contributing to the average rating.
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>u-url</code>''' - URL of the review

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review-aggregate" is found, don't look for an "hreview-aggregate" on the same element.

compat root class name: <code id="hreview-aggregate">hreview-aggregate</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> parse as '''<code>p-name</code>'''
* <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>rating</code>
* <code>best</code>
* <code>worst</code>
* <code>count</code>
* <code>votes</code>
* <code>rel="tag"</code> - parse as '''p-category'''
* <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.

=== v2 vocab notes ===
Notes:
* All v2 vocabularies are defined as flat lists of properties of an object/item, and thus can be used in microformats-2 syntax as shown, or in microdata items, or RDFa. The microformats-2 property parsing prefixes "p-", "u-", "dt-", "e-" are omitted when using defined properties in microdata itemprop and RDFa property as those syntaxes have their own element-specific parsing rules.
* Profile URLs are provided for use with the HTML4 <code>profile</code> attribute, microdata <code>itemtype</code> attribute, and RDFa <code>vocab</code> & <code>typeof</code> attributes (though the latter requires slicing off the trailing segment of the profile for the typeof attribute, and leaving the rest in vocab).
* microformats2 properties may also be explicitly bound as URIs using [[rel-profile]], the [[html5-profile]] attribute proposal, or an HTML5 'vocab' attribute instead. If URI bound terms are important to you, please express interest on [[rel-profile]], [[html5-profile]], or contribute to an [[html5-vocab]] draft.

=== v2 vocab to-do ===
To do:
* write a simple tutorial for creating/getting started with microformats-2 markup for new content
* examples in each h-* spec listed above of how to embed other microformats in them
* actual profile documents at <nowiki>http://microformats.org/profile/h-*</nowiki> URLs mentioned above.
* Provide any necessary microdata-specific language as needed (e.g. to be comparably understandable to the [http://www.whatwg.org/specs/web-apps/current-work/#vcard sample vCard4/hCard1 microdata vocabulary]. Also provide any necessary RDFa-specific language as needed. Both preferably in a generic vocabulary-independent way.
* write a porting guide mapping v1 property -> v2 property
** use-case: simple search/replace in templates (e.g. in case web author doesn't remember existing microformats vocabs and where they used them).
** advise using *both* in existing templates (e.g. in case some CSS depends on the existing microformats)
* analyzie/document how well the microformats2 model and vocabularies satisfy the [http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2009-May/019681.html use-cases used to design/create microdata].

== combining microformats ==
Since microformats2 uses simple flat sets of properties for each microformat, multiple microformats are combined to indicate additional structure.

=== h-event location h-card ===
Events commonly have venue information with additional structure, like address information. For example:

<syntaxhighlight lang="html">
<div class="h-event">
<a class="p-name u-url" href="http://indiewebcamp.com/2012">
IndieWebCamp 2012
</a>
from <time class="dt-start">2012-06-30</time>
to <time class="dt-end">2012-07-01</time> at
<span class="p-location h-card">
<a class="p-name p-org u-url" href="http://geoloqi.com/">
Geoloqi
</a>,
<span class="p-street-address">920 SW 3rd Ave. Suite 400</span>,
<span class="p-locality">Portland</span>,
<abbr class="p-region" title="Oregon">OR</abbr>
</span>
</div>
</syntaxhighlight>

The nested h-card used to structure the p-location of the h-event is represented as a structured value for "location" in the JSON, which has an additional key, "value" that represents the plain text version parsed from the p-location.

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-event"],
"properties": {
"name": ["IndieWebCamp 2012"],
"url": ["http://indiewebcamp.com/2012"],
"start": ["2012-06-30"],
"end": ["2012-07-01"],
"location": [{
"value": "Geoloqi",
"type": ["h-card"],
"properties": {
"name": ["Geoloqi"],
"org": ["Geoloqi"],
"url": ["http://geoloqi.com/"],
"street-address": ["920 SW 3rd Ave. Suite 400"],
"locality": ["Portland"],
"region": ["Oregon"]
}
}]
}
}]
}
</syntaxhighlight>

Questions:
<div class="discussion">
* Should the nested hCard be present also as a top-level item in the JSON? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
** My current (2012-243) leaning is no. - [[User:Tantek|Tantek]] 18:53, 30 August 2012 (UTC)
** If so, how do we avoid expansion of the JSON geometrically proportional to the depth of microformat nesting? (Or do we not worry about it?)
* Should there be a canonical hierarchical JSON and a canonical flattened JSON? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
** My current (2012-243) leaning is no, we stick with one canonical JSON for uf2 which is hierarchical. - [[User:Tantek|Tantek]] 18:53, 30 August 2012 (UTC)
** If so, should the flattened JSON have references from properties to nested microformats that have been pushed to the top level per flattening? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
*** If so, what convention does/do JSON follow for such synthetic local reference identifiers? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
</div>

Notes:
* The 'location' value reflects the visible text of its element, including spaces and punctuation, as well as the state abbreviation 'OR'. The 'h-card' property values are only what is marked up, and thus include structure values without extra punctuation, and the state takes the expanded form from the <code>title</code> attribute of its <code><abbr></code> element.

=== h-card org h-card ===
People often publish information general to their company rather than specific to them, in which case, they may wish to encapsulate that in separately nested microformat. E.g. here is a simple h-card example with org property:

[http://blog.lizardwrangler.com Mitchell Baker] (Mozilla Foundation)

with source:
<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<span class="p-org">Mozilla Foundation</span>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": ["Mozilla Foundation"]
}
}]
}
</syntaxhighlight>

Sometimes such organization affiliations are hyperlinked to the website of the organization:

[http://blog.lizardwrangler.com Mitchell Baker] ([http://mozilla.org/ Mozilla Foundation])

You can mark that up with a nested h-card:
<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
</syntaxhighlight>

Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an <code><a href></code> would.

'''FOR PARSERS ONLY:'''

The nested 'h-card' could be marked up as an 'h-org' as well, which adds it to the nested microformat's type array, all as part of the property specified by the 'p-org'.

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card h-org"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card", "h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
</syntaxhighlight>

'''FOR PARSERS ONLY:'''

Without a property class name like 'p-org' holding all the nested objects together, we need to introduce another array for nested children (similar to the existing DOM element notion of children) of a microformat that are not attached to a specific property:

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card","h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
</syntaxhighlight>

Since there's no property class name on the element with classes 'h-card' and 'h-org', the microformat representing that element is collected into the children array.

Such a nested microformat implies some relationship (containment, being related), but is not as useful as if the nested microformat was a specific property of its parent.

For this reason it's recommended that authors should not publish nested microformats without a property class name, and instead, when nesting microformats, authors should always specify a property class name (like 'p-org') on the same element as the root class name(s) of the nested microformat(s) (like 'h-card' and/or 'h-org').

'''FOR PARSERS ONLY:'''

Or the nested object could be only marked up with 'h-card'. Source:

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
</syntaxhighlight>

'''TO DO: Add h-event h-card example and JSON, per real world publishing examples like [http://www.swingtime.co.uk/List/ClSouth.html Swing Time: Classes in Southern England].'''

== authoring ==
=== minimal markup ===
The best way to use microformats-2 is with as little additional markup as possible. This keeps your code cleaner, improves its maintainability, and thus the quality and longevity of your microformats.

One big advantage of microformats-2 over previous microformats (and others) is the ability to add one class name to an existing element to create a structured item.

See the [[microformats-2#simple_microformats_2_examples|simple examples at the top]] for a start, e.g.

Simple hCards work just by adding <code>class="h-card"</code> :
<syntaxhighlight lang="html">
<span class="h-card">Frances Berriman</span>

<a class="h-card" href="http://benward.me">Ben Ward</a>

<img class="h-card" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>

<a class="h-card" href="http://tantek.com">
<img alt="Tantek Çelik" src="http://ttk.me/logo.jpg"/>
</a>
</syntaxhighlight>

* Tip: Inside an open tag, put the <code>class</code> attribute <em>first</em>, then any human text content attributes (e.g. <code>alt</code>), then URL attributes (e.g. <code>href</code> <code>src</code>), and lastly other attributes (e.g. <code>style</code>). Putting the class attribute first ties it closely to the element name/tag itself, makes it more obvious, and thus more likely to be kept up to date.

=== backward compatible ===
If you depend on current microformats [[implementations]], while they're being updated to support [[microformats2]], you can include both existing classic microformats and microformats2 markup.

In short: use both sets of class names simultaneously.

When doing so, use them on the same element, with the microformats-2 class name first, followed immediately by the existing microformats class name.

Here are the microformats-2 hCards from above with current [[hCard]] markup as well, which may require adding a wrapping element (e.g. a <code><span></code>) to separate the root class name element from explicit property class name elements:

<syntaxhighlight lang="html">
<span class="h-card vcard">
<span class="p-name fn">Frances Berriman</span>
</span>

<span class="h-card vcard">
<a class="p-name fn u-url url" href="http://benward.me">Ben Ward</a>
</span>

<span class="h-card vcard">
<img class="p-name fn u-photo photo" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>
</span>

<span class="h-card vcard">
<a class="u-url url" href="http://tantek.com">
<img class="p-name fn u-photo photo" alt="Tantek Çelik"
src="http://ttk.me/logo.jpg"/>
</a>
</span>
</syntaxhighlight>

Tips:
* use the microformats-2 class name first, e.g.
** <code>class="h-card vcard"</code>
** <code>class="u-url url"</code>
* and pair them when using an element for multiple properties, e.g.:
** <code>class="p-name fn u-url url"</code>
** <code>class="p-name fn u-photo photo"</code>
* put microformats classes after classes for CSS (since page authors will likely interact more with their own classes for design than with microformats classes), e.g. as used on individual microformats [[events]] pages:
** <code>class="event-page h-event vevent"</code>

The prefixes (h-, p-, etc.) of microformats2 class names provide easier recognition, and when followed by the similarly named existing class name, they're more easily recognized as related and thus kept together when the markup is maintained over time.

Related FAQ: [[microformats2-faq#when_using_both_h-card_and_vcard_which_should_be_first_and_why|When using both h-card and vcard which should be first and why?]]

== extensions ==
microformats2 is extensible by means of two separate but syntactically similar extension prefixes for experiments intended to be iterated & evolved and for vendor specific extensions not intended for standardization.

=== experimental extensions ===
There have been times when specific sites have wanted to extend microformats beyond the set of properties in the microformat vocabulary, and currently lack any '''experimental''' way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus:

For experimental extensions for the purpose of prototyping to learn more, iterate, towards possibly standardizing, use the <code>-x-</code> prefix before root and property class names.

Specifically:
* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a literal 'x' for an experimental extension

Examples:
* "p-x-prep-time" - a possible experimental property name to be added to [[h-recipe]] upon consideration/documentation of real-world usage/uptake.

See [[microformats2-experimental-properties]] for more examples.

=== <span id="VENDOR_EXTENSIONS">vendor extensions</span> ===
For vendor specific extensions, microformats2 uses a mechanism similar to CSS vendor extensions, using a similar syntax as experimental extensions, except with a vendor prefix instead of a literal 'x'.

* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-, numbers allowed after first character)

Examples:
* "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "one-ring" microformat root class name.
* "p-goog-preptime" - to represent [http://www.google.com/support/webmasters/bin/answer.py?answer=173379 Google's "preptime" property extension] to [[hRecipe]] (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.)

See [[vendor-prefixes]] for more examples.

=== extensions background ===
This extensibility mechanism is a composition of the following (at least somewhat) successful extension syntaxes:
* [http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords CSS 2.1 4.1.2.1 Vendor-specific extensions]
* IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [http://en.wikipedia.org/wiki/Internet_media_type]
* IETF MIME experimental fields (e.g. x-spam-score)
* HTTP header extensions (e.g. x-pingback)
* note also [http://www.mnot.net/blog/2009/02/18/x- some critical thoughts from mnot]

In particular:

Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.

Proprietary or experimental CSS3 property implementations have been very successful.

There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like:

* -moz-border-radius
* -webkit-border-radius

etc.

Note that these are merely string '''prefixes''', not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use.

This use of vendor specific CSS properties allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.

The benefits have been two-fold:
* designers have been able to make more attractive sites sooner (at least in some browsers)
* features have been market / real-world tested before being fully standardized, thus resulting in better features

Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and [https://secure.wikimedia.org/wikipedia/en/wiki/List_of_HTTP_header_fields#Common_non-standard_headers Wikipedia: HTTP header fields - non-standard headers] (could use RFC reference instead) respectively, like:

* application/x-latex (per [https://secure.wikimedia.org/wikipedia/en/wiki/Internet_media_type#Type_x Wikipedia Internet media type: Type x])
* x-spam-score (in email headers)
* X-Pingback (per [http://en.wikipedia.org/wiki/Pingback Wikipedia:Pingback])

Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases:

* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])

See [[microformats2-origins#VENDOR_EXTENSIONS]] for more background.

== validators ==
microformats2 validators:

{{new}} Test your microformatted web page with:
* https://pin13.net/mf2/

Barnaby Walters has a hosted version of the open source php-mf2 [[parser]] where you can enter your markup into a textarea and see how it's parsed:
* http://waterpigs.co.uk/php-mf2/

See the [[validators]] page for a longer list of validators.

== Examples in the wild ==
Please add new examples in the wild of microformats-2 to the top of this list. When it gets too big we can move it to a separate page like [[microformats-2-examples-in-wild]].

* ...
* David John Mead marks up his profile, blog posts and comments with h-card, h-entry and h-cite on [http://davidjohnmead.com davidjohnmead.com]
* [[User:Brian|Brian Suda]] marks up his blog posts up with h-entry and h-card on [http://optional.is/required/ optional.is]
* Ashton McAllan marks up her blog posts, reposts, comments and likes with h-entry, h-card and h-cite on [https://acegiak.net/ acegiak.net]
* Emma Kuo marks up her blog posts and notes with h-entry and h-card on [http://notenoughneon.com/ notenoughneon.com]
* Scott Jenson marks up his blog posts with h-entry and h-card on [http://jenson.org/ jenson.org]
* Emily McAllen marks up her blog posts with h-entry and h-card on [http://blackwoolholiday.com/ blackwoolholiday.com]
* Ryan Barrett marks up his blog posts, notes, replies and likes with h-entry and h-card on [https://snarfed.org/ snarfed.org]
* Barry Frost marks up his notes with h-entry, h-card and h-cite on [http://barryfrost.com/ barryfrost.com]
* Amber Case marks up her profile, blog posts, replies and notes with h-entry and h-card on [http://caseorganic.com/ caseorganic.com]
* Johannes Ernst marks up his blog posts with h-entry on [http://upon2020.com/blog/ upon2020.com]
* Michiel de Jong marks up his profile and notes with h-entry and h-card on [https://michielbdejong.com/ michielbdejong.com]
* Mike Taylor marks up his profile and blog posts with h-card and h-entry on [https://bear.im/bearlog/ bear.im]
* Erin Jo Ritchey marks up her profile, posts and comments using h-card, h-entry and h-cite with idno on [http://erinjo.is/ erinjo.is]
* Jeena Paradies marks up his profile, blog posts, notes and comments using h-card, h-entry and h-cite on [https://jeena.net/ jeena.net]
* Andy Sylvester marks up his profile, blog posts and comments using h-card and h-entry on [http://andysylvester.com/2014/03/01/howto-setting-up-the-selfoss-feed-reader-with-microformats-support/ andysylvester.com] (note: as of 2014-03-13 using h-entry for comments instead of correct h-cite --[[User:Barnabywalters|bw]] 14:44, 13 March 2014 (UTC))
* Hakan Demir marks up his Coupon and Voucher blog posts with h-entry and h-card on [http://www.gutscheinflagge.de/ gutscheinflagge.de]
* Chloe Weil marks up her blog posts with h-entry on [http://chloeweil.com/blog chloeweil.com]
* Christophe Ducamp marks up his blog posts and profile with h-entry and h-card on [http://christopheducamp.com/ christopheducamp.com]
* Glenn Jones marks up his blog posts, notes, replies, profile and comments with h-entry, h-card and h-cite on [http://glennjones.net/ glennjones.net]
* Marcus Povey marks up his blog posts and profile with h-entry and h-card on [http://www.marcus-povey.co.uk/ marcus-povey.co.uk]
* Eugen Busoiu marks up his web profile with h-card on [http://eugenbusoiu.com/#utm_source=microformats2&utm_medium=h-card&utm_campaign=Microformats eugenbusoiu.com]]
* Matthias Pfefferle marks up his blog posts, comments and profile with h-card, h-cite and h-entry on [http://notizblog.org/ notizblog.org]
* Kyle Mahan marks up his profile and notes with h-card and h-entry on [http://kylewm.com/ kylewm.com]
* Emil Björklund marks up his blog posts with h-entry and h-card ([http://thatemil.com/blog/2013/09/16/webmentioning-adactio/ example])
* App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 ([https://alpha.app.net/voidfiles example])
* Brett Comnes marks up his posts with h-entry and h-card ([http://bret.io/2013/06/29/getting-started-with-bower/ example])
* Ben Werdmuller marks up his posts with h-card and h-entry, u-in-reply-to and u-like ([http://werd.io/view/51d5097fbed7ded0633a5956 example])
* Sandeep Shetty marks his posts up with h-card and h-entry, as well as draft u-in-reply-to and experimental u-like properties ([http://sandeep.io/101 example])
* Laurent Eschenauer marks up his posts with h-entry ([http://eschnou.com/entry/first-autonomous-flight-of-my-nodecopter-62-24992.html example])
* Tom Morris marks up his posts using h-entry ([http://tommorris.org/posts/8417 example])
* Sinolandquality marks up some of their content using h-feed and h-entry on [http://www.sinolandquality.com/Blog/?page_id=3516&utm_content=buffere4d40&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer sinolandquality.com]
* [http://www.w3.org/conf/ W3Conf 2013] uses h-event for the main event, and h-card for all the speakers and notable attendees. The h-cards make particularly good use of implied name, url, and photo properties.
* [http://wordpress.org/extend/themes/sempress SemPress] is a WordPress theme that supports h-card, h-feed/h-entry and h-as-*
* [http://the-pastry-box-project.net/ The Pastry Box Project] use h-card and h-entry markup on their homepage and individual thoughts pages
* Tom Morris uses h-card and [[XFN]] to markup [http://tommorris.org/pages/blogroll his blogroll].
* Aaron Parecki uses h-card to markup both authorship and references to people in his notes permalinks, e.g. [http://aaronparecki.com/2012/230/reply/1 2012/230/reply/1].
* [http://tantek.com/ Tantek Çelik] uses h-card, h-event, and h-entry on his home page, as well as h-entry on all post permalinks, e.g. [http://tantek.com/2012/243/t1/name-beats-title-modern-use-dubline-core-wrong-uf2 2012-243 post], with [[rel-prev]]/[[rel-next]] (if applicable) to indicate prev/next posts, and with [[rel-author]] to his home page with canonical hCard to indicate authorship.
* [http://waterpigs.co.uk/ Barnaby Walters] uses h-card on his home page, h-card, h-entry and XFN markup on his [http://waterpigs.co.uk/notes notes page].
** 2013-01-25 Barnaby Walters: <cite>[http://waterpigs.co.uk/articles/experimental-markup Experimental Markup]</cite> - describes how he's using microformats2 vocabularies: <code>h-adr</code>, <code>h-card</code>, <code>h-entry</code>, <code>h-event</code>, <code>h-geo</code>, <code>h-review</code>, and experimental vocabularies: <code>h-feed</code> (embedded for update histories), [[activity-streams]] objects <code>h-as-article</code>, <code>h-as-collection</code>, <code>h-as-note</code>, <code>h-as-update</code>, as well as experimental properties: <code>u-alternate</code> and <code>u-as-downstream-duplicate</code> (links to POSSE copies), and <code>u-in-reply-to</code> (links to content that the posts are in reply to).
* [http://tantek.com/presentations/2012/06/microformats microformats.org at 7 years] presentation with h-event and h-card markup for people and organizations.
* [http://tantek.com/presentations/2012/06/pdf2012-indieweb.html Rise of the Indie Web hCards] (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has [[microformats-2]] h-calendar and h-card markup
* WebMaker by Mozilla has [[microformats-2]] h-calendar and h-card on event search (e.g. [https://webmaker.org/en-US/events/near/?lat=45.5234515&lng=-122.6762071 search near Portland Oregon]) and event pages (e.g. [https://webmaker.org/en-US/events/192f56eb9/ IndieWebCamp 2012]).[https://twitter.com/microformats/status/212207925643587585]
* WebFWD by Mozilla has [[microformats-2]] h-card markup on [https://webfwd.org/about/experts/ experts] and [https://webfwd.org/about/team/ team] pages
* [http://indiewebcamp.com IndieWebCamp] has [[microformats-2]] h-event markup with nested h-cards for the organizers and the location.
* [https://wiki.mozilla.org/Events Mozilla Events] page has [[microformats-2]] h-event markup with attendees marked up with h-card.
* The [http://pdx.esri.com/blog/2013/10/17/introducing-mapattack/ Esri PDX Blog] has h-entry markup on all blog posts (as of 2013-10-19), and h-product markup on [http://pdx.esri.com/projects/terraformer/ project pages]

=== offline ===
* spreadly marks up share permalink pages with h-entry, as well as minimal h-cards and experimental p-like properties

== Implementations ==
{{new}} Test your microformatted web page with:
=== Live Textarea Input ===
Use any of these to enter HTML+microformats2 markup and see the parsed result!
* http://glennjones.net/tools/microformats/
* https://pin13.net/mf2/ (where it says "Microformats Parser")
* https://kylewm.com/services/mf2

=== Blogging tools ===
* '''Storytlr''' parses the 'target' from [http://indiewebcamp.com/pingback pingbacks] for [https://github.com/storytlr/storytlr/blob/master/protected/application/public/controllers/PingbackController.php#L63 h-entry with properties and nested h-card] for information to automatically display in the [http://eschnou.com/entry/testing-indieweb-federation-with-waterpigscouk-aaronpareckicom-and--62-24908.html comments section on a post].

=== Converters ===
* '''[https://github.com/snarfed/granary granary]''' is a library and REST API that converts between silo APIs, [[ActivityStreams]], [[microformats2]], and Atom (all directions). Supported silos include Facebook, Twitter, Instagram, Google+, and Flickr. Users include [http://brid.gy/ Bridgy], [http://reader.kylewm.com/ Woodwind], and [https://facebook-atom.appspot.com/ facebook-atom] and [https://twitter-atom.appspot.com/ twitter-atom], among others.

* '''[http://pipes.yahoo.com/pipes/pipe.info?_id=afc5568b4e8643bfb05436b1caaf91bc microformats to RSS]''' - a Yahoo! pipe that converts a URL containing an [[h-feed]] containing h-entries, into an [[RSS]] feed ([http://waterpigs.co.uk/notes/4SeNi5/ 2013-10-21 blog post announcing])

* '''[https://xray.p3k.io XRay]''' ([https://github.com/aaronpk/XRay source code]) - Returns a normalized representation of the microformats data at a URL

=== Parsers ===
Parsers, open source libraries, in alphabetical order by programming language:

If you are implementing a microformats2 parser, see:
* [[microformats2-parsing]]

==== Parsers in production ====
The following parsers are of very high quality, in active development, and use on live sites on the web in production.

===== Java =====
* [[any23]] Apache Any23 (Anything to Triples)] a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents: http://any23.apache.org

===== Javascript =====
* '''microformats-parser''' for both browser and node.js
** github open source: https://github.com/aimee-gm/microformats-parser (current)
** live: https://aimee-gm.github.io/microformats-parser/

Previously:
* '''microformat-node''' Node.js microformats2 parser
** github open source: https://github.com/microformats/microformat-node (current)
*** forked from https://github.com/glennjones/microformat-node
** test suite: https://github.com/microformats/tests

** command line: https://github.com/JerrySievert/mf2
* '''microformat-shiv''' - cross browser javascript microformats2 parser which can also be used in browser extensions.

** github open source: https://github.com/glennjones/microformat-shiv

===== PHP =====
* '''<span id="php-mf2">php-mf2</span>''' - PHP microformats2 parser
** github open source: https://github.com/indieweb/php-mf2
** Packagist: https://packagist.org/packages/mf2/mf2
** live:
*** textarea entry: http://waterpigs.co.uk/php-mf2/
*** URL and textarea entry: https://pin13.net/mf2/
** [https://github.com/barnabywalters/php-mf-cleaner mf-cleaner]: functions for working with the raw mf2 data structure

===== Python =====
* '''mf2py''' Python microformats2 parser
** main entry: [[mf2py]]
** github open source: https://github.com/tommorris/mf2py
** live:
*** URL entry: [https://mf2py.herokuapp.com/ mf2py.herokuapp.com]
*** textarea entry: https://kartikprabhu.com/connection/mfparser
*** another textarea: http://www.unmung.com/?html=
*** URL and/or textarea: https://kylewm.com/services/mf2

===== Ruby =====
* '''indieweb/microformats-ruby''' Ruby microformats parser
** github open source: https://github.com/indieweb/microformats-ruby
** live text entry: https://microformats-parser-ruby.herokuapp.com

===== Haskell =====
* '''myfreeweb/microformats2-parser''' Haskell microformats2 parser
** github open source: https://github.com/myfreeweb/microformats2-parser
** live textarea entry: https://unrelenting.technology/mf2/

==== Development parsers ====
The following parsers are in-development and have key microformats2 functionality yet are incomplete, not fully tested, or have other limitations. Contributions welcome!

===== Erlang =====
* '''hazybluedot/mf2erl''' Erlang microformats2 parser
** github open source: https://github.com/hazybluedot/mf2erl

===== Elixir =====
* '''ckruse/microformats-elixir''' Elixir microformats2 parser
** github open source: https://github.com/ckruse/microformats2-elixir

===== Go =====
* '''willnorris/microformats''' Golang microformats2 parser
** github open source: https://github.com/willnorris/microformats
** live textarea entry: https://go.microformats.io/

===== Java =====
* '''Apache Any23''' a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents. Supports Microformats1 and 2.
** Download recent release: http://any23.apache.org/download.html
** live: http://any23-vm.apache.org/
** source: http://any23.apache.org/build-src.html
* '''mf2j''' An early-stage Java microformats2 parser
** github open source: https://github.com/kylewm/mf2j
** live: https://mf2j.herokuapp.com/?url={http://example.com}

===== Perl =====
* '''Web::Microformats2''' Perl microformats2 parser
** https://metacpan.org/pod/Web::Microformats2
** open source: https://github.com/jmacdotorg/microformats2-perl

==== Experiments ====
Experiments and other proof of concept microformat2 parsing support.
* '''Rust''' - https://gitlab.com/maxburon/microformats-parser
* ...

=== Outreach ===
* [https://github.com/mozilla/fathom/issues/42 Mozilla Fathom: examples with nested classes, e.g. microformats2]

== Presentations ==
Presentations about microformats2:
* 2013-01-24 <cite>[http://waterpigs.co.uk/presentations/microformats-2/ Microformats 2]</cite> presentation by [[User:Barnabywalters|Barnaby Walters]] at the [[events/2013-01-24-exeter-web-meetup|Exeter Web Meetup]] in Devon, UK.
* 2012-09-21 <cite>[http://tantek.com/presentations/2012/09/microformats2/ microformats2 & bits of HTML5: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-09-21-refreshlx|RefreshLX]] in Lisbon, Portugal.
* 2012-07-21 <cite>[http://tantek.com/presentations/2012/07/html5-uf2/ HTML5 and microformats2: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-07-21-cascadesf|Innovators of the Web conference]] in San Francisco, CA.
* 2012-07-14 <cite>[http://tantek.com/presentations/2012/07/html5-microformats2/ HTML5 and microformats2: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-07-14-open-web-camp-4|Open Web Camp IV]] in San Jose, CA.

== Testimonials ==
* <blockquote class="twitter-tweet">To prove the web standards community can come up with better standards than the SE’s, compare this: http://microformats.org/wiki/microformats-2 with schema . org — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298907685452124160 2013-02-05 13:35]</blockquote>
* <blockquote class="twitter-tweet">... I’m hoping SE’s will pick up microformats2. It’s SO much cleaner. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298911287117758464 2013-02-05 13:49]</blockquote>
* <blockquote class="twitter-tweet">... But damn Microformats2 are sexy. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298912179292344320 2013-02-05 13:53]</blockquote>

== Origins ==
This page was originally used to brainstorm and develop microformats2 in an exploratory manner, with problem statements, questions, lessons learned from past and other formats.

Now that [[microformats2-parsing]] is a Microformats specification, the original brainstorming has been moved to a separate page for anyone who wants to understand more about how we came up with the design of microformats2, and how it evolved in the early years.
* [[microformats2-origins]]

== See Also ==
* [[microformats2]]
* [[microformats2-brainstorming]] - moving more experimental / undeveloped / and rejected thoughts ideas here to simplify/progress *this* page further.
* [[microformats2-experimental-properties]] - listing experimental (-x- prefixed) properties and their use
* [[microformats2-prefixes]]
* [[vendor-prefixes]]
* [[microformats2-faq]]
* [[microformats2-parsing]]
* 2010-05-02 [[events/2010-05-02-microformats-2-0|microformats 2.0 discussion session at FOO East]]

audio-info-formats

2023-11-04T00:03:55Z

GRegorLove: /* XSPF */ current link, 2005 archive link for v1 that was linked here

=Contributors=

* [[User:ManuSporny | Manu Sporny]], [http://www.bitmunk.com/ Bitmunk] - [http://blog.digitalbazaar.com Digital Bazaar], Inc.
* Charles Iliya Krempeaux
* Ryan King
* [[User:YvesRaimond | Yves Raimond]], [http://blog.dbtune.org/ DBTune]

=Audio Metadata Formats=

== XSPF ==
* [https://xspf.org/spec XSPF] ([https://web.archive.org/web/20051216100424/http://xspf.org/xspf-v1.html 2005 archive link]) - XML playlist format created by Xiph.

== MusicBrainz XML ==
* [http://wiki.musicbrainz.org/MusicBrainzXMLMetaData Music Brainz XML Metadata Format] - Music Brainz artist, album and track metadata format.

== OGG Comment Specification ==
* [http://www.xiph.org/vorbis/doc/v-comment.html OGG Comment Specification] - Comment specification for Ogg Vorbis files.

== OGG Tagging ==
* [http://reactor-core.org/ogg-tagging.html OGG Tagging Specification] - Optional comment specification for Ogg files.

== Bitmunk XML ==
* [http://wiki.digitalbazaar.com/en/Bitmunk_Transaction_Platform_Web_API_Tutorials#Populating_Search_Data Bitmunk Media Info XML] - Media information XML format for describing audio and collections of audio.

== AVI ==
<strong>AVI</strong> is a container format for Audio/Video formats.

References:
* http://en.wikipedia.org/wiki/AVI

== B4S ==
<strong>B4S</strong> is a playlist format.

References:
* http://gonze.com/playlists/playlist-format-survey.html#B4S

== Creative Commons RDF ==

References:
* http://gonze.com/playlists/playlist-format-survey.html#Creative

== Music Ontology ==
* [http://musicontology.com/ The Music Ontology] is a community project aiming at providing a RDF vocabulary for expressing various music-related information, from complex editorial information (<i>this is a cell-phone recording of a performance of Ferde Grofé's arrangement of Gershwin's "Rhapsody in Blue"</i>) to temporal annotation (<i>The pianist was playing in E at that particular time</i>), and simple editorial metadata (<i>This album holds these tracks, was produced by this person, and this track was re-released on that compilation</i>).

== Extended M3U ==

References:
* http://gonze.com/playlists/playlist-format-survey.html#M3U
* http://hanna.pyxidis.org/tech/m3u.html
* http://en.wikipedia.org/wiki/M3U

== FLAC ==
Free Lossless Audio Codec (FLAC)
* http://flac.sourceforge.net/

== iTunes RSS ==

References:
* http://www.apple.com/itunes/podcasts/techspecs.html

== M3U ==
<strong>M3U</strong> is a playlist format.

References:
* http://gonze.com/playlists/playlist-format-survey.html#M3U

== MKV/MKA ==
Matroska <strong>MKV/MKA</strong> are video and audio containers, respectively.
* http://www.matroska.org/

== PLS ==
<strong>PLS</strong> is a playlist format.

References:
* http://gonze.com/playlists/playlist-format-survey.html#PLS
* http://en.wikipedia.org/wiki/PLS_(file_format)

== RTSP ==

References:
* http://www.rtsp.org/
* [http://www.ietf.org/rfc/rfc1889.txt RFC 1889]
* http://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol

== SMIL ==

References:
* http://www.w3.org/AudioVideo/

== Speex ==

References:
* http://www.speex.org/

== WAX ==
<strong>WAX</strong> is an SGML-based playlist for that looks exactly like ASX and WVX, except that it can only reference to ASF or WMA, but NOT to WMV files.

References:
* http://gonze.com/playlists/playlist-format-survey.html#WAX

== Id3 ==

References:
* http://www.id3.org/
* http://www.id3.org/id3v2.4.0-structure

== See also==
*[http://blogs.guardian.co.uk/askjack/2008/01/which_mp3_player_is_best_for_c.html Discussion of labelling of classical works], with links to further discussion and proposed standards, in particular:
**[http://oakroadsystems.com/genl/itunes.htm Taming iTunes for Classical Music]

rel-me

2023-08-11T19:51:21Z

GRegorLove: /* implementations */ +Threads

{{DISPLAYTITLE:rel="me"}}
;short URL
:http://ufs.cc/w/relme

[[XFN]] 1.1 introduced the "me" [[rel]] value which is used to indicate profile equivalence and for [[identity-consolidation]].

== example ==
<code>rel="me"</code> is used on hyperlinks from one page about a person to other pages about that same person.

For example, [[User:Tantek|Tantek]]'s [https://tantek.com/ home page] has (markup simplified)

<syntaxhighlight lang="html"><a href="https://github.com/tantek" rel="me">@t</a></syntaxhighlight>

And his GitHub profile itself has (markup simplified)

<syntaxhighlight lang="html"><a href="https://tantek.com/" rel="me">https://tantek.com/</a></syntaxhighlight>

Thus establishing a bi-directional rel-me link and confirming that the two URLs represent the same person.

Publishers can use the [https://gmpg.org/xfn/creator XFN creator] form to create rel-me hyperlinks.

== screencast and videos ==
Watch some short videos:
* David Recordon's excellent *30 second* explanation of XFN rel="me"
** [http://web.archive.org/web/20090119054502/http://www.sixapart.com/static_news/opening_social_graph/xfn_links/xfn_links.html Archived page], though presentation requires Flash. (original: <nowiki>http://www.sixapart.com/static_news/opening_social_graph/xfn_links/xfn_links.html</nowiki>)
* [https://www.youtube.com/watch?v=LabCylbapuM Brad Fitzpatrick explains rel="me" and more XFN].
* [https://connectedsocialmedia.com/423/plaxo-to-ship-online-identity-aggregator-based-on-microformats/ Joseph Smarr's whiteboard explanation] of rel="me" as implemented in the Plaxo online identity aggregator. ([http://web.archive.org/web/20220708203538/https://connectedsocialmedia.com/423/plaxo-to-ship-online-identity-aggregator-based-on-microformats/ archived]) 

Longer:
* [https://www.youtube.com/watch?v=Q2WzVSVxrrI Gavin Bell on "What is your provenance?"] (40 minutes) - provides a much broader discussion of the problem statement of who is a person on the Web, and [https://youtu.be/Q2WzVSVxrrI?t=450 starting at about 0:07:30] explains how [[hCard]] + rel="me" helps solve this problem.

== tutorials ==
[http://ungeekdapo.wordpress.com/2008/04/29/a-simple-data-portability-project-or-is-it/ A simple data portability project or is it] ([http://web.archive.org/web/20221110203949/https://ungeekdapo.wordpress.com/2008/04/29/a-simple-data-portability-project-or-is-it/ archived]) rel=me summary by Bob Ngu

== domain verification ==
rel=me is the standard way to check that a website belongs to a user on a 3rd party site.

* read a user's website that they entered into their 3rd party site profile
* check for a rel=me hyperlink from their website to their 3rd party site profile
* if such a rel=me hyperlink is found, then the user has proven that they control that personal website sufficient to put a link back to their 3rd party site profile, and thus domain verification succeeds.

If you're the implementer of such a 3rd party site with user profiles, implement the above to implement a personal website domain verification feature.

== rel-me-auth ==
[[RelMeAuth]] is a proposed open standard for using [[rel-me]] links to profiles on [[OAuth]] supporting services to authenticate via either those profiles or your own site.

In short it is a combination of '''domain verification''' as documented above, and OAuth authorization on the 3rd party site that the user's domain links to.

Read more about how to implement [[RelMeAuth]] and [[web sign-in]].

== implementations ==
Notable Sites:
* [https://indieweb.org/Mastodon#rel-me_support Mastodon] uses rel-me to support "verified" site links in a green box with a green checkmark next to the verified site.
* [https://web.archive.org/web/20230314223136/https://hachyderm.io/@nova/109790530971147702 GitHub]
* [https://wikis.world/@wikipedia/110396865170645710 Wikipedia] via [https://www.mediawiki.org/wiki/Special:MyLanguage/Help:Extension:RealMe MediaWiki Extension RealMe]
* [https://indieweb.org/rel-me#Threads Threads] announced rel-me support 2023-08-09 [https://www.threads.net/@mosseri/post/Cvu2eXurRbB]
* ...

Services:
* '''[https://indielogin.com/ IndieLogin]''' is perhaps the most comprehensive [[rel-me]] implementation, using it to implement [[RelMeAuth]] and a superset of [[web-sign-in]] that is focused on [http://indiewebcamp.com/ independent websites].

[[wordpress-plugins|WordPress plugins]]:
* [http://blog.maybe5.com/?page_id=94 Social Links Wordpress plugin] - supports rel-me links to other services
* [http://code.l0g.in/about-me/ About Me plugin] (on github) - supports creation of an About Me page with rel-me links to other profiles.

=== past implementations ===
* '''[https://web.archive.org/web/20170826050132/https://support.google.com/webmasters/answer/1229920 Google]''' used reciprocal rel=me links for domain verification, which it also used for independent site [[rel-author]] support.
* '''[http://web.archive.org/web/20140117144124/http://blog.app.net/2013/04/29/announcing-domain-verification App.net]''' implemented rel-me for officially connecting your domain to your app.net account, as well as publishing rel-me on your site.

=== advocacy ===
Advocating rel=me support can be done a few ways, if a site has:
* user profiles but no "website" field - ask them to add a "website" field and mark it up with rel=me.
* a "website" field on profiles - ask it to support publishing rel=me
* a notion of "verification" or "verified" profiles - ask it to do so via confirming reciprocal rel=me
* login/sign-in - ask it to support [[RelMeAuth]] with a [[Web sign-in]] user interface.

Current requests:
* [https://github.com/liberapay/liberapay.com/issues/1034#issuecomment-461898619 Liberapay: Associate accounts with websites #1034: rel="me" link] - requested 2019-02-08 by https://github.com/Changaco
* ...

----
----
'''TO BE UPDATED'''

The sections below this need to be updated (e.g. links verified, and deadlinks replaced with Internet Archive versions)

----
----

== examples in the wild ==
Examples of sites publishing rel=me support, e.g. on user profiles.

See:
* [[hcard-xfn-supporting-friends-lists#Services_with_XFN_rel.3D.22me.22_to_multiple_external_sites|services supporting XFN rel=me]]

== articles ==
* 2018-04-26 [https://vanderven.se/martijn/ Martijn van der Ven]: [https://wiki.zegnat.net/media/the-real-deal-about-rel-me.html The Real Deal About <code>rel="me"</code>]

== see also ==
* https://indieweb.org/rel-me
* [[hcard-xfn-supporting-friends-lists#Services_with_XFN_rel.3D.22me.22_to_multiple_external_sites|services that support rel="me"]]
* [[rel-me-faq]]
* [[xfn]]
* [[rel]]
* [[social network portability]]
* [https://gmpg.org/xfn/11 XFN 1.1 profile]

vote-links

2023-07-26T21:41:39Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:Vote Links}}
__TOC__
== Specification 2005 ==
=== Editor ===
* [http://tantek.com/ Tantek Çelik] ([http://technorati.com Technorati, Inc.], formerly of [http://microsoft.com/ Microsoft Corporation])

=== Concept ===
* [http://epeus.blogspot.com/ Kevin Marks] ([http://technorati.com Technorati, Inc.])

=== Authors ===
* [http://epeus.blogspot.com/ Kevin Marks] ([http://technorati.com Technorati, Inc])
* [http://tantek.com/ Tantek Çelik] ([http://technorati.com Technorati, Inc])

=== Copyright ===
{{MicroFormatPublicDomainContributionStatement}}
* [[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.
* [[User:Kevin_Marks|Kevin Marks]]: I release all my contributions to this specification into the public domain and I encourage the other authors to do so as well.

=== Patents ===
{{MicroFormatPatentStatement}}

=== Inspiration and Acknowledgments ===
Thanks to everyone who has given feedback on VoteLinks. Thanks especially to EtanWexler, who provided the first really good documentation that VoteLinks should be using 'rev' instead of 'rel' (see [[VoteLinksFAQ]]), and John Allsopp who similarly challenged the use of 'rel', and helped co-author the [[RelFAQ]] exploring questions and issues about the use of the HTML4 'rel', 'rev' attributes and linktypes in general.

== Introduction ==
Indexing and tracking applications treat all links as endorsements, or expressions of support. This is a problem, as we need to link to those we disagree with as well, to discuss why.

== Specification ==
VoteLinks is an [[elemental-microformat|elemental microformat]], one of several [[microformats|microformat]] open standards.
We propose a set of three new values for the rev attribute of the <a> (hyperlink) tag in HTML.

The new values are "vote-for" "vote-abstain" or "vote-against", which are mutually exclusive, and represent agreement, abstention or indifference, and disagreement respectively.

A link without an explicit vote 'rev' value is deemed to have value "vote-for" or "vote-abstain", depending on the application.

Additional human-readable commentary can be added using the existing 'title' attribute, which most browsers show as a rollover.

Examples:
<syntaxhighlight lang="html">
<a rev="vote-for" href="http://example.com/cheesevote"
title="Melt the cheese!">Do it!</a>
<a rev="vote-against" href="http://example.com/cheesevote"
title="Don't melt the cheese!">Don't do it!</a>
</syntaxhighlight>

=== Deprecated: Using 'rel' for VoteLinks ===
A previous draft of the specification used the 'rel' attribute instead of the 'rev' attribute. Analysis and feedback has demonstrated this to have been inappropriate use of the 'rel' attribute, when the 'rev' attribute was much more important. See the [[RelFAQ]] for more details.

Implementations MAY support links with the VoteLinks values in the 'rel' attribute for backward compatibility with any existing VoteLinks content.

Authors MUST NOT use 'rel' for VoteLinks values.

== XMDP profile ==
The following is an [http://gmpg.org/xmdp/ XMDP] profile for the [[vote-links]] specification.

=== URLs ===
This profile is hosted as a separate XMDP file on microformats.org:
* http://microformats.org/profile/vote-links
* shortURL: http://ufs.cc/x/vote-links

=== Usage ===
Profiles are referenced in (X)HTML files in the <HEAD> tag, e.g.:
<syntaxhighlight lang="html">
<head profile='http://microformats.org/profile/vote-links'>
</syntaxhighlight>

=== Profile ===
<syntaxhighlight lang="html">
<dl class="profile">
<dt id="rev">rev</dt>
<dd><p>
<a rel="help" href="http://www.w3.org/TR/html401/struct/links.html#adef-rev">
HTML4 definition of the 'rev' attribute.</a>
Here are additional values as defined in the
<a rel="help start" href="http://microformats.org/wiki/vote-links">
vote-links specification</a>
.</p>
<dl>
<dt id="vote-for">vote-for</dt>
<dd>Indicates agreement with or recommendation for the referred resource.</dd>
<dt id="vote-abstain">vote-abstain</dt>
<dd>Indicates abstention or indifference for the referred resource.</dd>
<dt id="vote-against">vote-against</dt>
<dd>Indicates disagreement with or recommendation against the referred resource.</dd>
</dl>
</dd>
</dl>
</syntaxhighlight>

== Implementations ==
This section is '''informative'''.

* Wordpress VoteBack (vote-link aware pingback and trackback) plugin is in testing at [http://monkinetic.com/2006/12/22/voteback.html VoteBack] ([[User:SteveIvy|Steve Ivy]]) - looking for testers!
** Any examples of WordPress sites running this? - [[User:Tantek|Tantek]] 23:42, 30 July 2012 (UTC)

=== past implementations ===
The following implementations went away or stopped working at some point:

* [http://folksr.de/ Folksr.de] - Apache test page (2012-07-30). Was: using VoteLinks to vote on the World Cup 2006
* '''jyte.com''' - "jyte is sleeping" (2012-07-30). Was: Following a [http://jyte.com/cl/jyte-should-integrate-microformats-votelinks vote-links claim] [http://jyte.com/profile/brianellin.com Brian Ellin] implemented vote-links on [http://jyte.com Jyte] within less than 30 minutes.
* '''moloko.itc.it''' site is unresponsive. was: [http://moloko.itc.it/paoloblog/ Paolo Massa] created [http://moloko.itc.it/paoloblog/semantic_links/ SemanticLinks], a small Firefox extension that shows vote-for, vote-against links information. (Note the download links for SemanticLinks have been removed by the author.)

== Examples in the wild ==
This section is '''informative'''.

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

* [http://www.likeorhate.com/ LikeOrHate] uses Vote-Links all over the site, to rate anything, items, comments, users. Valid votes are Like, Hate, Whatever ("vote-for", "vote-against", "vote-abstain"). CSS is used to "check" votes so logged users can remember them later.
* [http://www.weboffate.com/ Web of Fate] Web of Fate publishes Vote-Links for prediction probability scoring. Users can vote Agree, Disagree, Witness ("vote-for", "vote-against", "vote-abstain")
* [http://tommorris.org/blog/ Tom Morris] has vote links on del.icio.us links (based on tags "vote-for", "vote-against" and "vote-abstain").


== References ==

=== Normative References ===
* [http://gmpg.org/xmdp/ XMDP]

=== Informative References ===
* [http://www.artweb-design.de/articles/2006/06/05/distributed-votings-using-microformats Distributed votings using microformats] from Artweb Design
* [http://24ways.org/2006/boost-your-hyperlink-power Boost Your Hyperlink Power] - Jeremy Keith, using CSS to surface vote information
* Contributed from <nowiki>http://developers.technorati.com/wiki/VoteLinks</nowiki> ([https://web.archive.org/web/20040301041935/http://developers.technorati.com/wiki/VoteLinks 2004-03-01 Internet Archive copy])
== Related Work ==
* [[xoxo]]
* [http://gmpg.org/xfn/ XFN]
* [http://developers.technorati.com/wiki/attentionxml Attention.xml]
* [[rellicense]]
* [[reltag]]
* [[relnofollow]]

== FAQ ==
* See [[vote-links-faq]] and the broader [[rel-faq]].
* See also [[vote-links-issues]] for issues which have been raised with the votelinks [[microformat]].

[[Category:Specifications]]
[[Category:vote-links]]

value-class-pattern-tests

2023-07-26T21:40:27Z

GRegorLove: s/<source>/<syntaxhighlight>/

With the goal of developing a thorough test-suite for the [[value-class-pattern]], here are some test cases:

== test cases ==
The following value-class-pattern test cases have been developed (all of which use the [[test-fixture]] poshformat for easier extraction).

=== Date and time values ===
{{main|value-class-date-time-tests}}
* [[value-dt-test-YYYY-MM-DD--HH-MM]]
* [[value-dt-test-abbr-YYYY-MM-DD--HH-MM]]
* [[value-dt-test-abbr-YYYY-MM-DD-abbr-HH-MM]]
* [[value-dt-test-YYYY-MM-DD--HHpm]]
* [[value-dt-test-YYYY-MM-DD--Hpm-EEpm]]
* [[value-dt-test-YYYY-MM-DD--abbr-HH-MMpm]]
* [[value-dt-test-YYYY-MM-DD--12am-12pm]]
* [[value-dt-test-YYYY-MM-DD--H-MMam-Epm]]
* [[value-dt-test-YYYY-MM-DD--0Ham-EEam]]
* [[value-dt-test-YYYY-MM-DD--H-MM-SSpm-EE-NN-UUpm]]
* [[value-dt-test-YYYY-DDD--HH-MM-SS]]
* [[value-dt-test-YYYY-MM-DD--HH-MMZ-EE-NN-UUZ]]
* [[value-dt-test-YYYY-MM-DD--HH-MM-XX-YY--EE-NN-UU--XXYY]]
* [[value-dt-test-YYYY-MM-DD--HH-MM-XX--EE-NN-UU--Y]]
* [[value-dt-test-YYYY-MM-DD--HH-MM-SS-XXYY--EE-NN--Z]]
* [[value-dt-test-e-title-YYYY-MM-DD--HH-MM]]

=== Parsing value from a title attribute ===
* ...

== inline development tests ==
Here are inline tests developed during the development and design of the [[value-class-pattern]]. Each of those tests needs to be updated as follows:

# move to a separate page (one test per page), similar to the format used by [[value-dt-test-YYYY-MM-DD--HH-MM]].
# mark up using the [[test-fixture]] poshformat.
# "Result" at a minimum converted from abstract hierarchical text properties/values to an [[vCard]] and/or [[iCalendar]] expected result block.
# linked to from the previous section.

Please help the value class pattern testing, development, and implementation effort by updating the following tests accordingly:

===Conforming <code>value-title</code> Tests===

====One====

<syntaxhighlight lang="html">
<p class='tel'>My
<span class='type'>
<span class='value-title' title='cell'> </span>mobile
</span> phone number is <span class='value'>+44 1245 333 333</span>
</p>
</syntaxhighlight>

Result

<pre>
TEL
TYPE = cell
VALUE = +44 1245 333 333
</pre>

====Two====

<syntaxhighlight lang="html">
<p class='vevent'>
My <span class='summary'>Birthday Party</span> will be held
<span class='dtstart'>
<span class='value-title' title='2009-04-01'>tomorrow</span>
</span>
and last until
<span class='dtend'>
<span class='value-title' title='2009-04-05'> </span>
the following Tuesday (April 5th)
</span>.
</p>
</syntaxhighlight>

Result

<pre>
VEVENT
SUMMARY = Birthday Party
DTSTART = 2009-04-01
DTEND = 2009-04-05
</pre>

===Tests of Non-Conforming <code>value-title</code> Code===

====One====

In this case, the human text appears before the <code>value-title</code> element, so the machine-data value has a weaker association with the property declaration. The likelihood of the data not being maintained correctly — the data value being ignored by an editor — is increased.

<syntaxhighlight lang="html">
<p class='tel'>My
<span class='type'>
mobile
<span class='value-title' title='cell'> </span>
</span> phone number is <span class='value'>+44 1245 333 333</span>
</p>
</syntaxhighlight>

Result

<pre>
TEL
TYPE = none/default/unknown ('mobile' is unknown in hCard)
VALUE = +44 1245 333 333
</pre>

====Two====

In this case, the <code>value-title</code> element is used for a property that is not valid for use with this pattern.

<syntaxhighlight lang="html">
<p class='vevent'>You are invited to
<span class='summary'>
<span class='value-title' title='FooCamp'> </span>
BarCamp
</span>
</p>
</syntaxhighlight>

Result

<pre>
VEVENT
SUMMARY = BarCamp
</pre>

== inline examples from Microformation ==
Here are inline examples published by Jeremy Keith in his blog post [http://adactio.com/journal/1579/ Microformation].

=== to do value-title test pages ===
'''Each of the examples below needs to be updated as follows:'''

# move to a separate page (one test per page), similar to the format used by [[value-dt-test-YYYY-MM-DD--HH-MM]].
# construct a complete [[hCalendar]] event that uses inline <code>dtstart</code> example
# mark up using the [[test-fixture]] poshformat.
# document "Result" at a minimum as an [[iCalendar]] expected result block.
# linked to from the appropriate section at the top of this page.

Please help the value class pattern testing, development, and implementation effort by creating separate test case pages for each of the following examples.

=== value title with contents ===
<syntaxhighlight lang="html">
<span class="dtstart">
<span class="value-title" title="2009-06-05T20:00:00">
Friday, June 5th at 8pm
</span>
</span>
</syntaxhighlight>

=== separate value title date and time ===
Not sure if this is actually allowed by the [[value-class-pattern]], but we should write up a test case regardless, to see what implementations do. [[User:Tantek|Tantek]]

<syntaxhighlight lang="html">
<span class="dtstart">
<span class="value-title" title="2009-06-05">
Friday, June 5th
</span>
at
<span class="value-title" title="20:00">
8pm
</span>
</span>
</syntaxhighlight>

=== value title span with empty content ===
<syntaxhighlight lang="html">
<span class="dtstart">
<span class="value-title" title="2009-06-05T20:00:00"> </span>
Friday, June 5th at 8pm
</span>
</syntaxhighlight>

== see also ==
* [[value-class-pattern]]
* [[value-class-date-time-tests]]
* [[test-fixture]]

google-search

2023-07-26T21:37:29Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:Google Search}}

Google is one of several [[search-engines]] that index and support microformats.

== main search ==
[http://google.com/ Google.com] supports [[rel-nofollow]], [[hCard]], [[hReview]], [[hreview-aggregate|hReview aggregate]], [[hProduct]] (since 2009-05-12 for [https://web.archive.org/web/20130717002527/https://support.google.com/webmasters/answer/99170 rich snippets]), [[hCalendar]] ([http://googlewebmastercentral.blogspot.com/2010/01/introducing-new-rich-snippets-format.html since 2010-01-22]), and [[hRecipe]] ([http://googlewebmastercentral.blogspot.com/2010/04/better-recipes-on-web-introducing.html since 2010-04-13]) - in main search. See also [http://microformats.org/2010/04/28/google-adds-support-for-hcalendar-and-hrecipe-rich-snippets related blog post on hCalendar hRecipe support].

=== rich snippets ===
{{main|rich-snippets}}
Rich Snippets is [[Google]]'s term for the enhancement of search results ("snippets") with information from microformats from pages.
* See [[google-rich-snippets-examples]] for documentation of Google's microformats examples.
* See [[google-rich-snippets-issues]] for issues with Google's Rich Snippets Testing tool.

----
=== people ===
Google's [http://support.google.com/webmasters/bin/answer.py?hl=en&answer=146646 documentation on Rich snippets - People support]

http://www.google.com//help/hc/images/webmasters_146676_rspeople.png

Details:
* at least two of the following must be present:
** title or role
** org
** adr

[[hCard]] properties supported ('''bold''' = required)
* '''fn'''
* nickname
* photo
* title
* role
* url
* org - "If fn and org have the exact same value, Google will interpret the information as referring to a business or organization"
* adr
** street-address
** locality
** region
** postal-code
** country-name
* friend (presumably from [[xfn]])
* contact (presumably from [[xfn]])
* acquaintance (presumably from [[xfn]])

[[rel-me]] support:
* https://support.google.com/webmasters/answer/1229920

----
=== organizations ===
Google's [http://support.google.com/webmasters/bin/answer.py?hl=en&answer=146861 documentation on Rich snippets - Organizations support]

Details:
* "Organization information (for example, details about a business such as a restaurant or attraction) that is marked up in the body of a web page can help Google understand '''location information in reviews or events.'''"
* "It can also be displayed on a '''Place Page'''—a web page that organizes all relevant information about a place. [http://maps.google.com/help/maps/richsnippetslocal/ more about rich snippets for local search]

http://maps.google.com/help/maps/richsnippetslocal/images/rich-snippets-info.png

[[hCard]] properties supported ('''bold''' = required)
* '''fn/org''' - "use both fn and org, and ensure that these have the same value."
* url
* adr
** street-address
** locality
** region
** postal-code
** country-name
* tel
* geo
** latitude
** longitude

----
=== events ===
Google's [http://support.google.com/webmasters/bin/answer.py?hl=en&answer=164506 documentation on Rich snippets - Reviews support]

Multiple events: <br>
http://www.google.com/help/hc/images/webmasters/webmasters_164506_richsnippets_multipleevent_en.gif

Or a single event: <br>
http://www.google.com/help/hc/images/webmasters_164506_richsnippetsevents_singleevent_en.gif

Details:
* "Event markup can be used to mark up events that occur on ''' ''specific'' future dates''', such as a musical concert or an art festival."
* "the name and location of the event, also needs to be clearly defined. Since this feature isn’t meant for advertising purposes, your '''event name should not contain any promotional elements such as the ''price'' of the event, a ''call to purchase'', or an indication of a ''sale or temporary discount'' '''."

[[hCalendar]] properties supported ('''bold''' = required)
* '''summary'''
* '''url''' - "Required for pages listing multiple events"
* '''location''' - "Required for single event. ... we recommend that you represent the location by using a nested Organization to specify a venue '''name and address'''." - [[hCard]]
* description
* dtstart
* dtend
* duration
* category
* geo
** latitude
** longitude
* photo
* tickets - "offer to buy tickets for the event. Can be a URL to a page where tickets can be purchased, or can include specific Offer properties, such as"
** price
** quantity
** priceValidUntil
** currency

----
=== reviews ===
Google's [http://support.google.com/webmasters/bin/answer.py?hl=en&answer=146645 documentation on Rich snippets - Reviews support]

http://www.google.com/help/hc/images/webmasters_146645_individualimage.png

Details:
* the main topic of the page needs to be about '''a ''specific'' product or service'''. For example, using review markup on a page containing multiple products is not supported.
* If the markup contains a single review, the '''reviewer’s name needs to be a valid name''' (Person or Organization)
** presumably an [[hCard]]

[[hReview]] properties supported ('''bold''' = required)
* '''item'''
** fn
* rating
** value
** best
*** value-title support: <syntaxhighlight lang="html"> <span class="best"><span class="value-title" title="10"/></span> </syntaxhighlight>
** worst
** "Tip: Don't add a separate hidden text block to specify the rating. '''Hidden content will not be displayed.'''"[http://support.google.com/webmasters/bin/answer.py?hl=en&answer=172705]
** img alt number parsing: <syntaxhighlight lang="html"><img class="rating" src="four_star_rating.gif" alt="4 Star Rating: Recommended" /></syntaxhighlight>
** value-title support: <syntaxhighlight lang="html"><span class="rating"><span class="value-title" title="4.5" /></span></syntaxhighlight>
* '''reviewer'''
* dtreviewed
* description
* summary
[[hReview-aggregate]] additional properties supported in addition to the above (or additional requirements / subproperties)
* count - "The total number of reviews for the item on your site. Note: Whenever you include count, the page must also contain review markup for each reviewed item. count should only include reviews on your own site."
* votes - "contributes toward the average rating but not towards the number of reviews available" - essentially, a "number of ratings" property.
* '''rating''' - required in their hReview-aggregate support
* rating
** average (additional subproperty)
* photo - though presumably this works in hReviews as well

----
=== recipes ===
Google's [http://support.google.com/webmasters/bin/answer.py?hl=en&answer=173379 documentation on Rich snippets - Recipes support]

http://www.google.com/help/hc/images/webmasters_173379_en.png

Details:
* "When using recipe markup, the '''main topic of the page needs to be about a ''specific'' recipe.''' Using recipe markup on a page containing multiple recipes is not supported."
* "f the recipe markup contains a single review, the '''reviewer’s name needs to be a valid name (Person or Organization).'''" [[[hCard]]]

[[hRecipe]] properties supported ('''bold''' = required)
* '''fn'''
* tag
* photo
* published
* summary
* review - nested [[hReview]]
* prepTime - "length of time it takes to prepare the recipe for dish, in ISO 8601 duration format."
** min
** max
* cookTime - "time it takes to actually cook the dish, in ISO 8601 duration format."
** min
** max
* duration - "total time it takes to prepare the<nowiki>[sic]</nowiki> cook the dish, in ISO 8601 duration format."
** min
** max
* nutrition - "These elements are not explicitly part of the hRecipe microformat, but Google will recognize them."
** servingSize
** calories
** fat
** saturatedFat
** unsaturatedFat
** carbohydrates
** sugar
** fiber
** protein
** cholesterol
* instructions
** instruction
* yield
* ingredient
** name (not fn?)
** amount
* author - Can include nested Person information - [[hCard]]

----
=== products and listings ===
Google's [http://support.google.com/webmasters/bin/answer.py?hl=en&answer=146750 documentation on Rich snippets - Products support] and [http://support.google.com/webmasters/bin/answer.py?hl=en&answer=186036 Product properties: hProduct] in particular.

Details:
* "mark up your product information on a product page (a page that contains '''only a single product''') or an '''aggregated offer page''' (a page that lists a single product, along with information about different sellers offering that product).
* "Because you cannot use microformats to indicate condition or availability (for example, "used" or "out-of-stock"), we recommend using hProduct only for new, in-stock products only."

[[hProduct]] properties supported ('''bold''' = required)
* '''fn''' ("name" in other vocabs)
* photo ("image" in other vocabs)
* brand
* description
* category
* review - a nested [[hReview aggregate]]
* (identifier - mentioned in other vocabs only)
** types: asin, isbn, mpn, sku, upc
* offerDetails - [[hListing]] - "An offer to sell the product. Includes a nested Offer or Offer-aggregate."

[[hListing]] (offers) properties supported ('''bold''' = required)
* '''fn''' (as part of item)
* '''price''' - "A floating point number. You may use either a decimal point ('.') or a comma (',') as a separator."
* currency - "currency used to describe the product price, in three-letter ISO format" (documented as "required", but testing tool doesn't report any error for omitting)
* url (for offers, offer-aggregates in particular)
* priceValidUntil - "date (in ISO date format) after which the price will no longer be available. (Your product snippet may not display if the priceValidUntil property indicates a past date.)"
* seller - [[hCard]] (Person or Organization)
* condition - "content" attribute must be one of: "new, used, refurbished"
* availability - "content" attribute must be one of: "out_of_stock, in_stock, instore_only, preorder"
* quantity
* identifier
** types: asin, isbn, mpn, sku, upc
* itemOffered - [[hProduct]] - "The item being sold. Typically, this includes a nested Product, but it can also contain other item types or free text."

Related: Offer-aggregate properties supported ('''bold''' = required)
* '''lowPrice''' - Floating point number
* highPrice - Floating point number
* '''currency''' - [http://http//www.iso.org/iso/support/faqs/faqs_widely_used_standards/widely_used_standards_other/currency_codes.htm three-letter ISO format].
* offerCount
* condition - "content" attribute must be one of: "new, used, refurbished"
* offerURL
* identifier
** types: asin, isbn, mpn, sku, upc
* itemOffered - [[hProduct]] - "The item being sold. Typically, this includes a nested Product, but it can also contain other item types or free text."

There is an obsolete claim of non-support: <blockquote>"We do not currently support the hListing format for product rich snippets."</blockquote> Real world examples have disproven this, e.g.:
* http://www.smartmaster.co.il/Default.asp?sType=0&PageId=77222
** has several hListings with <code>class=hlisting</code>
** Google Structured Data Testing Tool [http://www.google.com/webmasters/tools/richsnippets?url=http%3A%2F%2Fwww.smartmaster.co.il%2FDefault.asp%3FsType%3D0%26PageId%3D77222& shows extracted structured data]
*** 10 hListings, with <code>item</code> / <code>fn</code>, and <code>price</code> - all as marked up on the page.

== advanced search ==
Through additional user interfaces:
* [http://www.google.com/advanced_search Google Advanced Search - Usage rights] supports [[rel-license]] (since 2005(?) citation needed)

== search APIs ==
* ...

== previous support ==
Google often [http://indiewebcamp.com/Google#Dead_Silos shuts down sites or services], and some of those were implementations.
=== Social Graph API ===
[http://code.google.com/apis/socialgraph/ Google Social Graph API] supported [[XFN]] (launched 2008 February). See "[http://socialgraph-resources.googlecode.com/svn/trunk/samples/findyours.html Google Social Graph API How are your sites connected?]".

== see also ==
* [[search-engines]]
* [[implementations]]

RelMeAuth

2023-07-26T21:36:11Z

GRegorLove: s/<source>/<syntaxhighlight>/

[[RelMeAuth]] is a proposed open standard for using [[rel-me]] links to profiles on [[OAuth]] supporting services to authenticate via either those profiles or your own site.

RelMeAuth is the technology behind [[web-sign-in]].

<div class="vcard">
; <span class="role">Editor</span>
: <span class="fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="url">http://tantek.com/</span>)
</div>

== support RelMeAuth ==
=== users ===
See [[web-sign-in]]

Here's a more technical explanation:

'''Use [[rel-me|rel="me"]] on your personal site, and enter your personal site as your web address on sites with [[web-sign-in]] (RelMeAuth).'''

Steps:

'''1. Add [[rel-me|rel="me"]] links to your other profiles.'''

Add [[rel-me|rel="me"]] to links from your home page to your various profiles on other services.

'''2. Edit your other profiles to link back to your site.'''

Edit your other profiles and set their "home page" or "personal site" or "URL" field to your personal site.

Here's a [[hcard-xfn-supporting-friends-lists#Services_with_XFN_rel.3D.22me.22_to_one_external_site|list of profile sites that have URL fields and support rel-me]].

'''3. There is no step 3. You're done.'''

Now on any site that uses (Web sign-in) / RelMeAuth login (e.g. try [http://tantek.com/relmeauth/ the RelMeAuth prototype]), simply enter your personal site URL, and that site's RelMeAuth code will sign you in by authenticating you with one of the social profiles that you've linked to (e.g. Twitter).

==== examples in the wild ====
===== simple home page =====

Tantek's home page http://tantek.com/ has (simplified markup)
<syntaxhighlight lang="html">
<ul>
<li><a rel="me" href="http://twitter.com/t">Twitter: @t</a></li>
<li><a rel="me" href="http://identi.ca/t">identi.ca: t</a></li>
</ul>
</syntaxhighlight>

=== users with separate contact pages ===

'''But what if I prefer to have a separate contact or about page with my links to other profiles?'''

If you prefer a simpler home page and have it link to a separate contact page that links to your other profiles, then

# add [[rel-me|rel="me"]] to the link from your home page to your contact page
# add [[rel-me|rel="me"]] to links from your contact page to those other profiles

==== more examples in the wild ====
===== separate contact page =====

Jeremy Keith's home page http://adactio.com/ has (simplified markup)
<syntaxhighlight lang="html">
<ul>
<li><a rel="me" href="/journal/">Journal</a></li>
<li><a rel="me" href="/contact/">Contact</a></li>
</ul>
</syntaxhighlight>

and then also:

http://adactio.com/journal/ has (simplified markup)
<syntaxhighlight lang="html">
<ul>
<li><a rel="me" href="http://huffduffer.com/adactio/">Huffduffer</a></li>
<li><a rel="me" href="http://twitter.com/adactio/">Twitter</a></li>
<li><a rel="me" href="http://adactio.tumblr.com/">Tumblr</a></li>
<li><a rel="me" href="http://www.last.fm/user/adactio/">Last.fm</a></li>
<li><a rel="me" href="http://www.dopplr.com/traveller/adactio/public">Dopplr</a></li>
<li><a rel="me" href="http://www.vimeo.com/user196031">Vimeo</a></li>
<li><a rel="me" href="http://ffffound.com/home/adactio/found/">Ffffound</a></li>
<li><a rel="me" href="http://readernaut.com/adactio">Readernaut</a></li>
<li><a rel="me" href="http://97bottles.com/people/adactio/">97 Bottles</a></li>
</ul>
</syntaxhighlight>

==== authentication preference ====
If you have a specific preference for what service(s) to authenticate with, just make sure that you list links to your profiles on those other services in preference order (on your home page or contact page as described above).

=== profile sites ===
Do you run a site with profiles?

Any social network site or similar site that has user profile pages should:
# provide a [[user interface]] for a user to enter and publicly publish a URL back to their home page
# publish a visible link with [[rel-me|rel="me"]] from user's profile page to their personal home page

Most [[hcard-xfn-supporting-friends-lists#Services_with_XFN_rel.3D.22me.22_to_one_external_site|sites already do this]].

=== authentication sites ===
Do you run a site with user profiles that you want to let your users use to login to other sites?

In addition to supporting rel-me as [[#profile_sites|described above]]:

Any site that wants to allow users to login with their credentials from that site on 3rd party sites should:
# Support [[OAuth]] (2.0 even)
# Follow Twitter's conventions for:
#* endpoint paths and other protocol details
#* mimic Twitter's user interface for authentication flow (on both desktop and mobile - they've done a great job)

==== RelMeAuth providers ====
Sites that support both [[rel-me]] and are also [[OAuth]] providers:

* Twitter ([http://apiwiki.twitter.com/OAuth-Examples Twitter OAuth Examples])
* Google Profiles ([http://sites.google.com/site/oauthgoog/ Google OAuth documentation])
* Identi.ca (uses the same endpoint paths/details as Twitter)
* Github ([http://developer.github.com/v3/oauth/ Github OAuth 2 documentation])
* ...

=== sites needing a user login ===
Do you have a site and want to let users login with their own identity?

Any site that wants to let users login with their own identity should:
# provide a user interface for users to enter or choose their preferred online identity (e.g. their own URL)
# perform RelMeAuth authentication as described below

== how it works ==
=== summary algorithm ===
Summary of the RelMeAuth authentication algorithm

* input: a user identity (URL) to authenticate
* output: success or cancel authentication or no authenticatable URLs found

# start with a user identity URL (e.g from the UI, or from a cookie from previous login etc.)
# iterate through their outbound rel-me links on the user identity URL (and any rel-me local subpages if necessary)
## if
### a rel-me destination is up (HTTP Get succeeded, following any redirects)
### and rel-me links back to user identity URL
### and has OAuth endpoint
### then do OAuth authentication
### if authentication succeeded, you're done, the user has been been authenticated with the user identity URL, exit
### if it was rejected, the user canceled, thus cancel the entire authentication process, exit
## continue iteration with the next rel-me link if any
# no authenticatable URLs found (either none at all, or any provided had some other error, 404, no response, no OAuth endpoint, other OAuth error)

=== detailed algorithm ===
{{main|relmeauth-algorithms}}

* input: a user identity (URL) to authenticate
* output: success or cancel authentication or no authenticatable URLs found

# start with a user identity URL (e.g from the UI, or from a cookie from previous login etc.)
## if the identity URL is not user-owned (i.e. at a known silo domain),
## then
### the implementation should not accept it, and await user correction of the URL
### the implementation may accept 1-2 silo domains for testing or demonstration purposes
# if the URL is an IndieAuth provider
# then try authenticating with it (we prefer the user's own site for auth)
## if it succeeds, exit
## if canceled, exit
## otherwise continue
# iterate through their outbound rel-me links on the user identity URL (first through direct rel-me links to external sites in order, then iterate through URLs deeper into the personal site in order, e.g. to a contacts page, and iterate through rel-me links from there to external sites in order, then the next breadth-first local rel-me page from the identity URL if necessary)
## if
### a rel-me destination is up (HTTP Get succeeded, following any redirects)
### and rel-me links back to the user identity URL
### and has OAuth endpoint
### then do OAuth authentication
### if authentication succeeded, you're done, the user has been been authenticated with the user identity URL, exit
### if it was rejected, the user canceled, thus cancel the entire authentication process, exit
## continue iteration with the next rel-me link if any
# no authenticatable URLs found (either none at all, or any provided had some other error, 404, no response, no OAuth endpoint, other OAuth error)

== Error Cases ==

Document things which can go wrong during the relmeauth process along with real world examples and what message should be shown to the end user to help them fix it.

Let '''rel-me-url''' be the URL given by the user.

'''The rel-me-url redirect chain includes a redirect where the scheme changes'''
* Example: http://brennannovak.com redirects to https://brennannovak.com
* Why is this a problem? … explain vulnerabilities for both directions here
* What message should be presented to the user? Two cases:
** If the insecure redirect only changed the scheme (as in the above example), tell them that they need to enter the https:// version of the URL
*** Would it be acceptable to automatically restart the process using the secure URL? --[[User:Barnabywalters|bw]] 10:16, 8 October 2013 (UTC)
*** What warning to give if a https:// URL redirects to a http:// URL? --[[User:Barnabywalters|bw]] 10:16, 8 October 2013 (UTC)
** Otherwise, let them know there was an insecure redirect, as well as what it was. Bonus: explain how MITM attacks work and why they’re dangerous

'''A reverse rel-me link’s redirect chain includes a redirect where the scheme changes'''
* Example: …
* Why is this a problem? …
* What message should be presented to the user?

== open source implementations ==
There are a couple of open source libraries that sites can use to implement RelMeAuth so their users can login using their own identities.

=== Go ===
* https://github.com/hawx/relme-auth
** Live demo site: https://auth.hawx.me/

=== Node.js ===
* https://www.npmjs.com/package/relmeauth
* https://github.com/superfeedr/node-relmeauth

=== Python ===
* [http://github.com/ptarjan/relmeauth Python RelMeAuth] by Paul Tarjan and Jeff Lindsay

=== PHP ===
* [http://github.com/themattharris/relmeauth PHP RelMeAuth] by Matt Harris and Tantek Çelik
** Live demo sites:
*** http://tantek.com/relmeauth/
*** http://apps.themattharris.com/relmeauth/ (2022-09-15: site appears to be dead)

=== Ruby ===
* [https://github.com/aaronpk/IndieAuth.com IndieAuth.com] (deprecated) by Aaron Parecki contains Ruby code for performing RelMeAuth authentication
** To Do: Separate Ruby gem for Ruby implementation of RelMeAuth

== to do ==
* update [[web-sign-in]] with some screenshots of auth screens (e.g. Twitter's OAuth flow with auth/read-only request, no write perms), or a picture of a lock or something.
* create an Architecture Diagram for RelMeAuth per [http://blog.mozilla.org/security/2012/05/08/speeding-up-security-reviews/ Mozilla Security Blog: Speeding Up Security Reviews]
* create a Detailed Application Diagram for RelMeAuth per the same[http://blog.mozilla.org/security/2012/05/08/speeding-up-security-reviews/].
* write-up Data flow enumeration per the same[http://blog.mozilla.org/security/2012/05/08/speeding-up-security-reviews/].
* write-up a Threat Analysis per the same[http://blog.mozilla.org/security/2012/05/08/speeding-up-security-reviews/].
* resolve and close issues (see below).

== issues ==
If this gets too long, we can move it to [[relmeauth-issues]]. As issues are resolved/closed, please move them to [[relmeauth-issues-resolved]]/[[relmeauth-issues-closed]] respectively.
<div class="issues">
* How do you find the OAuth endpoint for any given user profile site/service? -[[User:Tantek|Tantek]]
** Use OAuth 2.0 discovery mechanism if supported
** Use a whitelist of provider site to OAuth endpoint
** Try the Twitter OAuth endpoint paths on other sites to see if they work - assuming that many OAuth providers will simply mimic Twitter's example as suggested.
*** This discovery by convention technique will work for example on:
**** http://identi.ca/

* How do you get an appID to use with any given site's OAuth? -[[User:Tantek|Tantek]]
** This appears to still be a manual process, per site, and thus a legitimate limitation of RelMeAuth in comparison to say [[OpenID]].
*** Some services are supporting appkey/secret pair anonymous/anonymous for mobile/desktop apps already. Unsure how popular this is [[User:Singpolyma|Singpolyma]] 13:51, 23 April 2010 (UTC)

* OAuth is for authorization, and as such gives the site I'm ident asserting to access to my account on the id service. This is very bad. Suggested solution: use OpenID instead. [[User:Singpolyma|Singpolyma]] 13:51, 23 April 2010 (UTC)
** OAuth actually suggests granularity in access rather than blanket access ([http://tools.ietf.org/html/draft-hammer-oauth-10 OAuth IETF draft, see Sec 4.8]): <blockquote><p>When implementing this protocol, servers should consider the types of access resource owners may wish to grant clients, and should provide mechanisms to do so. Servers should also take care to ensure that resource owners understand the access they are granting, as well as any risks that may be involved.</p></blockquote>Thus for RelMeAuth purposes, the RelMeAuth "consumer"/library should ask merely for "authentication" rather than read, write, update, or delete access. One exception is the "share" scenario, where a site lets a user RelMeAuth login via another site (e.g. Twitter), and then provides a UI for the user to share from that site to Twitter - in that case request auth/read/write access granularity makes sense. [[User:Tantek|Tantek]] 22:46, 26 April 2010 (UTC)

* After authing with OAuth, how do you know what user it is that auth'd? OAuth specifically does not tell you that information... [[User:Singpolyma|Singpolyma]] 13:54, 23 April 2010 (UTC)
** Twitter provides user information via the OAuth token and their API, it is recommended that other OAuth providers follow this API convention while OAuth is evolved to provide to capability. [[User:Tantek|Tantek]] 22:46, 26 April 2010 (UTC)
</div>

== history ==
On 2010-02-01 Tantek [http://tantek.com/2010/032/t5/modest-proposal-authentication-oauth-twitter-rel-me introduced the basis for] and Jeff Lindsay [http://twitter.com/progrium/status/8521001762 suggested the name] for RelMeAuth.

In a follow-up Tantek [http://tantek.com/2010/032/t6/relmeauth-oauth-rel-me-auto-fallback-authentication suggested the following simple protocol] for RelMeAuth:

<blockquote cite="http://tantek.com/2010/032/t6/relmeauth-oauth-rel-me-auto-fallback-authentication"><p>
RelMeAuth works for any #OAuth + rel-me site, and enables auto-fallback with use of alternate identities for authentication:</p><ol><li>user enters their site URL</li><li>iterate through their outbound rel-me links</li><li>if <ol><li>a rel-me destination is up, and</li><li> rel-me links back to user's site, and</li><li>has OAuth endpoint,</li></ol> then do OAuth authentication.</li></ol><p>Thus user links to their RelMeAuth profiles in preference order, and authentication code tries them in order. e.g. Twitter, Identi.ca, ... etc.</p></blockquote>

Later that evening Tantek, Jeff Lindsay, Paul Tarjan and others discussed RelMeAuth at the [[events/2010-02-02-weekly-dinner-mv|microformats dinner in Mountain View]] and afterwards Jeff and Paul implemented RelMeAuth in an open source Python library at Hacker Dojo and discussed/tested it in IRC.

http://krijnhoetmer.nl/irc-logs/microformats/20100203

Less than 24 hours from concept to open source implementation.

== articles posts comments ==
* 2010-03-03 [http://simonwillison.net/2010/Mar/2/bewildering/#c60551 Blaine Cook] comment
* 2010-02-16 [http://www.google.com/buzz/dclinton/HeMv1AQTXS8/Envisioning-decentralized-replies-and#1266371138608000 Tantek Çelik] comment re: user interface
* 2010-02-06 [http://aaronparecki.com/RelMeAuth Aaron Parecki] wiki page

== vendor specific sign in ==
The following vendor specific sign-in methods have succeeded and are in far greater use than previous efforts at user-centric URL identity (e.g. OpenID).

http://hueniverse.com/wp-content/uploads/2009/09/Sign-in-with-Twitter.png

http://4.mshcdn.com/wp-content/uploads/2009/04/facebook-twitter-connect.gif

* Sign in with Twitter
** 2009-04-16 [http://hueniverse.com/2009/04/introducing-sign-in-with-twitter-oauth-style-connect/ Introducing ‘Sign-in with Twitter’, OAuth-Style “Connect”]
** [https://dev.twitter.com/docs/auth/sign-twitter Sign in with Twitter developer home page]
** [https://dev.twitter.com/docs/sign-twitter-resources Sign in with Twitter Resources] (more/latest buttons)
* Connect with Facebook
** ...
See articles comparing/contrasting them:
* 2009-04-18 [http://mashable.com/2009/04/18/twitter-facebook-connect/ Facebook Connect vs. Sign in with Twitter: Fight!]
User-facing [[web-sign-in]] functionality (including "( Web sign-in )" button graphic) must be at least as simple, easy, and trustworthy as the these vendor specific sign in methods.

== related ==
* [[rel-me]]
* [[OAuth]]
* [[hCard]]
* [[OpenID]]

rel-license

2023-07-26T21:35:04Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:rel="license"}}

<p class="entry-summary">Rel-License is a simple, open, format for indicating content licenses which is embedable in HTML or XHTML, Atom, RSS, and arbitrary XML. Rel-License is one of several [[microformats|microformat]] open standards.</p>

== Specification 2005-02-06 ==
=== Author ===
[http://tantek.com/ Tantek Çelik] ([http://technorati.com Technorati, Inc.], formerly of [http://microsoft.com/ Microsoft Corporation])

=== Copyright ===
Per the public domain release on [[User:Tantek|my user page]], this specification is released into the public domain.

{{MicroFormatPublicDomainContributionStatement}}

=== Patents ===
{{MicroFormatPatentStatement}}

== Abstract ==
Rel-License is one of several microformats. By adding <code>rel="license"</code> to a hyperlink, a page indicates that the destination of that hyperlink is a license for the current page. E.g. with the following hyperlink:

<syntaxhighlight lang="html">
<a href="http://creativecommons.org/licenses/by/2.0/" rel="license">cc by 2.0</a>
</syntaxhighlight>

the author indicates that the page is licensed under a Creative Commons 2.0 Attribution Required license.

== Multiple Licenses ==
Multiple such rel="license" hyperlinks indicate that the page is available under any of the referred licenses. E.g. the following hyperlinks could be used to declare that a page is available under either a Creative Commons 2.0 Attribution Required license or the Apache 2.0 license:

<syntaxhighlight lang="html"><a href="http://creativecommons.org/licenses/by/2.0/" rel="license">cc by 2.0</a>
<a href="http://www.apache.org/licenses/LICENSE-2.0" rel="license">Apache 2.0</a></syntaxhighlight>

== XMDP profile ==
The following is an [http://gmpg.org/xmdp/ XMDP] profile for the [[rel-license]] specification.

=== URLs ===
This profile is hosted as a separate XMDP file on microformats.org:
* http://microformats.org/profile/rel-license
* shortURL: http://ufs.cc/x/rel-license

=== Usage ===
Profiles are referenced in (X)HTML files in the <HEAD> tag, e.g.:
<syntaxhighlight lang="html">
<head profile='http://microformats.org/profile/rel-license'>
</syntaxhighlight>

=== Profile ===
<syntaxhighlight lang="html">
<dl class="profile">
<dt id="rel">rel</dt>
<dd><p>
<a rel="help" href="http://www.w3.org/TR/html401/struct/links.html#adef-rel">
HTML4 definition of the 'rel' attribute.</a>
Here is an additional value as defined in the
<a rel="help start" href="http://microformats.org/wiki/rel-license">
rel-license specification</a>
.</p>
<dl>
<dt id="license">license</dt>
<dd>Indicates that the referred resource is a license for the referring page.</dd>
</dl>
</dd>
</dl>
</syntaxhighlight>

== Implementations ==
* [http://www.webstandards.org/action/dwtf/microformats/ Dreamweaver Extension suite] from the [http://webstandards.org/ Web Standards Project] enables the authoring of rel-license links from within Dreamweaver 8. Includes (cc) defaults.
* [http://placenamehere.com/TXP/pnh_mf/ pnh_mf] is a plugin for [http://textpattern.com/ Textpattern] that supports embedding rel license and other microformats in templates and blog posts. Written by [http://placenamehere.com/ Chris Casciano].
* [http://creativecommons.org/license/ Creative Commons (cc) license chooser]
* [http://search.yahoo.com/cc Yahoo! (cc) search] (appears to pick up link-rel in a but not link elements)
* [http://www.google.com/support/bin/answer.py?answer=29508 Google "Usage Rights" search] (also appears to pick up link-rel in a but not link elements)

== List of Licenses ==
* [http://creativecommons.org CC]
* [http://www.opensource.org/licenses/ Open Source Initiative] licenses -- mostly software-focused

== Articles ==
This section is '''informative'''.

Articles about rel-license, most recent first. When this section gets too big, we can move it to [[rel-license-articles]].
* (undated) [http://reference.sitepoint.com/html/rel-mf#rel__license SitePoint reference: rel- Microformats / license] by Ian Lloyd

== References ==
=== Normative References ===
* [http://gmpg.org/xmdp/ XMDP]

=== Informative References ===
* 2004-02-11 rel="license" first proposed in presentation [http://tantek.com/presentations/2004etech/realworldsemanticspres.html real world semantics] at 2004 O'Reilly Emerging Technologies Conference, San Diego, CA, USA.
* 2004-02-25 [http://tantek.com/log/2004/02.html#d25t1805 Thorough discussion of rel="license"] including advantages and presentation possibilities.
* [http://creativecommons.org/licenses/by/2.0/ Creative Commons 2.0 By (Attribution Required) license]
* [http://www.apache.org/licenses/LICENSE-2.0 Apache 2.0 license]
* Contributed from <nowiki>http://developers.technorati.com/wiki/RelLicense</nowiki> ([https://web.archive.org/web/20050321015449/http://developers.technorati.com/wiki/RelLicense 2005-03-21 Internet Archive version])
* [http://microformatique.com/?p=60 Know your rel-license at Microformatique]

== see also ==
* [[rel-license-issues]] - issues which have been raised with this microformat.
* [[rel-faq]]

[[Category:Specifications]]
[[Category:rel-license]]

rel-alternate

2023-07-26T21:33:33Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{stub}}

== Special Combinations ==
While <code>rel="alternate"</code> does by itself mean that the destination is some alternate representation or version of the current page, it combines in special ways with other <code>rel</code> values and other attributes to provide different more specific meanings, in particular:

=== With <code>rel stylesheet</code> ===
==== Alternate stylesheets ====
<code>rel="alternate stylesheet"</code> is [http://www.w3.org/TR/html4/present/styles.html#h-14.3.1 how you provide an alternate stylesheet] for the document. Note that the stylesheet is ''not'' an alternate representation of the current page.

=== With <code>hreflang</code> ===
==== Alternate language versions ====
When used in combination with the <code>hreflang</code> attribute (with a value other than that of the document itself), <code>rel="alternate"</code> means a link to a version of the current document, but in the language indicated by the <code>hreflang</code> attribute.

Example from http://gmpg.org/xfn/creator :
<syntaxhighlight lang="html">
<link href="creator-fr" rel="alternate" hreflang="fr" title="Créateur XFN 1.1" />
</syntaxhighlight>

See also: [http://support.google.com/webmasters/bin/answer.py?hl=en&answer=189077 Google Webmaster Tools Help: rel="alternate" hreflang="x"] and [[hreflang]]

=== With <code>media</code> ===
==== Alternate devices and media ====
When used in combination with the <code>media</code> attribute, <code>rel="alternate"</code> means a link to a version of the current document, especially for the specified device or medium indicated by the <code>media</code> attribute.

For example, this is one possible way of linking to a site's mobile version:
<syntaxhighlight lang="html">
<a href="http://m.twitter.com" rel="alternate" media="handheld">Twitter mobile site</a>
</syntaxhighlight>

=== With <code>type</code> ===
==== Page Feed ====

When used in combination with the <code>type</code> attribute (with a value other than that of the document itself; e.g. other than <code>"text/html"</code>), <code>rel="alternate"</code> means a link to a representation of the contents of the current document in a different format, as designated by the <code>type</code> attribute.

Examples:

<syntaxhighlight lang="html">
<link rel="alternate" type="application/rss+xml" href=".rss"
title="RSS feed for this page"/>
<link rel="alternate" type="application/atom+xml" href=".atom"
title="Atom feed for this page"/>
<link rel="alternate" type="application/activitystream+json" href=".as"
title="Activity Streams JSON feed for this page"/>
</syntaxhighlight>

=== With <code>type</code> and <code>rel home</code> ===
==== Site Feed ====
{{main|rel-home#use_with_rel-alternate}}

'''Proposed:'''
When used in combination with the <code>type</code> attribute (with a value other than that of the document itself, e.g. other than <code>"text/html"</code>), <code>rel="alternate home"</code> means a link to a representation of the contents of the ''site'' (the home page for the current page) in a different format, as designated by the <code>type</code> attribute.

Examples:

<syntaxhighlight lang="html">
<link rel="alternate home" type="application/rss+xml" href=".rss"
title="RSS feed for this site"/>
<link rel="alternate home" type="application/atom+xml" href=".atom"
title="Atom feed for this site"/>
<link rel="alternate home" type="application/activitystream+json" href=".as"
title="Activity Streams JSON feed for this site"/>
</syntaxhighlight>

== See Also ==
* [[existing-rel-values]]
* [[rel-faq]]
* [[rel-home]], in particular [[rel-home#use_with_rel-alternate|rel-home with rel-alternate proposal]]

microformats2-faq

2023-07-26T21:32:02Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:microformats2 FAQ}}

Frequently asked questions about [[microformats2]].

== when using both h-card and vcard which should be first and why ==
Q: When using both microformats2 and traditional microformats for backwards compatibility, which class name should go first and why?
Another example: should "h-event" be first (before the "vevent") in the class attribute?

A: '''Use the microformats2 class names first,''' and in equivalent pairs when marking up more than one property. E.g.
<syntaxhighlight lang="html">
<span class="h-card vcard">
<a class="p-name fn p-org org u-url url"
href="http://microformats.org/">microformats.org</a>
</span>

<span class="h-event vevent">
<a class="p-name summary u-url url"
href="http://plancast.com/p/e83d">microformats meetup SF</a>,
<time class="dt-start dtstart">2012-11-14 18:00</time>
</span>
</syntaxhighlight>
Here's how:
* [[microformats2#backward_compatible|using microformats2 and backward compatible microformats]].

And why:
* The prefixes (h-, p-, etc.) of microformats2 class names provide easier recognition (as class names ''for'' microformats), and when followed by the similarly named existing class name, they're more easily recognized as related and thus kept together when the markup is moved or maintained over time.

== why are microformats2 properties prefixed ==
{{main|prefixes}}
<span id="why_are_microformats_2_properties_prefixed">Q: Why do microformats2 property class names have prefixes like 'p-', 'u-', 'dt-', 'e-' ?</span>

A: For the benefit of both web authors and developers of parsers/consumers. By using class names with a small handful of short easily recognizable prefixes, it's easier to see which class names belong to microformats, and which may serve other purposes on the page. This helps web designers better recognize and maintain support for microformats across site redesigns for example. In particular:
* The 'p-' prefix is for typical string properties and parsing thereof.
* 'u-' is for URL-like properties whose values often come from another attribute such as the <a> 'href' or <img> 'src'.
* 'dt-' is for date and time related properties that have a particular format themselves, and ideally should make good use of the HTML5 <time> element, though for backward compatibility they work on any element.
* Finally, 'e-' is for properties whose value is the entirety of the text and HTML inside an element, as represented by the element's DOM. The 'e-entry-content' property from hAtom for example permits marking up and parsing/extracting an entire post from an HTML blog post page to an Atom feed entry with full markup/DOM fidelity of the original post.
Since prefixes determine specific parsing rules, parser developers are able to write simple and efficient generic microformats2 parsers without needing to know any specific vocabularies, either currently or in the future. These are both advantages of microformats2 over original microformats. For more details, including why and how microformats2 class name prefixes were developed, see: [[microformats2-prefixes]].

== how do you use experimental microformats and property names ==
I.e. what is the correct way to start using experimental microformats and property names in microformats2?

Documented primarily as [[microformats2#VENDOR_EXTENSIONS|microformats2 vendor extensions]], here's a quick summary:

There are two cases:

'''1. Vendor-specific''' - extensions that either only make sense in or have a very specific detailed or other meaning (e.g. a shibboleth) in a particular company or organizational context.

Use <code>-vendorabbr-</code> immediately after a microformats2 prefix, where "vendorabbr" is an abbreviation for the company (e.g. stock symbol) or organiztion. E.g.
* <code>h-goog-volcano</code> for a proprietary "volcano" object
* <code>p-osm-shop</code> for an OSM-site specific "shop" property

See '''[[vendor-prefixes]]''' for currently used and proposed vendor-prefixes (in case there already is one for the vendor-specific stuff you want to publish or consume, re-use instead of reinvent etc.).

'''2. Experimental''' - ideas that authors/developers want to experiment with in the wild without going through the microformats [[process]] to craft well-researched microformats and property names. Or for experimental formats that you're not even sure would be worth trying to standardize, may apply to a narrow / small community etc. (which might still grow as a result of experimentation, and thus eventually merit a format).

Use <code>-x-</code> immediately after a microformats2 prefix, e.g.:
* <code>h-x-test-fixture</code> for an experimental "text-fixture" format (e.g. for a [[test-suite]]).
* <code>p-x-prep-time</code> - a possible experimental preparation time property to be added to [[h-recipe]] upon consideration/documentation of real-world usage/uptake.

== how do h-adr and h-geo work with an implied name property ==

Q: Some microformats like h-adr and h-geo are usually used as just collections of properties and typically lack explicit names or "p-name" properties. How does the implied "name" property work with such microformats?

A: First, there is the use-case of named locations which aren't necessarily full h-card venues in and of themselves. For named locations, the name is published in visible text and should be marked up with e.g. class="p-name".

Other h-adr and h-geo microformats which lack an explicit name will have a name implied for them (e.g. from the full text of the element including all such visible property values in document order).

While at first it may seem silly to create a name for something which is merely an address or a latitude+longitude geolocation, there are some good reasons to imply a name even for such collections of properties.

Locations are often shown in a list (e.g. by [http://indiewebcamp.com/checkin Checkin] interfaces and applications). Lists showing all the locations on a page (e.g. all its h-card, h-adr, h-geo microformats) need labels for each item. The name of a location (whether explicit or implied) serves as the presentational label/title for that location in such lists.

Checkin location lists are just one use-case, there are many more. Any kind of page summarization tool (e.g. validators, linters) or anything which presents an interface to summaries of a page (e.g. web search results) benefits from having an explicit automatic way to determine how to label each and every microformat data item on a page.

Every such list of data items needs to label the items, and rather than just calling them "untitled item 1" etc., using the actual visible content of the item provides a nice clear connection to the specific item. Since the implied name comes directly from a snippet of text authored by a human, in the order that the human authored it as they intended it to be read (listened to), it will make sense as a label as well.

If an author explicitly wants an empty label for their microformat, while not recommended, they can explicitly specify as such: <code><span class="p-name"></span></code>

In practice this has yet to be seen, thus for now, any concerns about awkward or confusing implied names for things like h-adr or h-geo are categorized as a "theoretical issue". If someone finds a real world example where the implied "name" causes a bad user experience in some actual use-case, then we can re-explore this topic.

== how does microformats2 separate syntax and vocabularies ==
<span id="does_microformats_2_split_vocabularies_and_syntax">Q: How does microformats2 separate syntax and vocabularies?</span>

A: microformats2 [[microformats2-parsing|specifies a syntax for parsing microformats]] which is independent of any specific vocabulary such as [[h-card]], [[h-entry]], or [[h-event]], each of which themselves defines vocabularies and backward compatibility handling for their classic microformats equivalents. Thus microformats2 separates specific vocabularies and syntax, whereas classic microformats combined the rules for parsing and specific vocabularies. There are three common property names (name, url, photo) determined from common markup patterns that the generic parsing algorithm is specified to imply. These apply across all vocabularies and thus are not dependent on any specific vocabulary.

<span id="does_microformats_2_combine_vocabularies_and_syntax">Q: Does microformats2 combine vocabularies and syntax?</span>

A: No. From a parsing perspective, microformats2 syntax is independent of any particular vocabulary.

== are microformats2 vocabularies available to other languages ==
<span id="are_microformats_2_vocabularies_available_to_other_languages">Q: Are microformats2 vocabularies available to other languages?</span>

A: ''Existing'' microformats vocabularies have [http://microformats.org/profile profiles] which are already available to other languages. Each term is defined by a URL ending in a hash and the term. This is due to the design of [[XMDP]] which deliberately produces such URLs which are compatible with microdata, RDF, and any other LinkedData system. microformats2 vocabularies will use the same profile format and thus also be available to other languages.

== how do you convert a microformats2 example to RDFa syntax ==
<span id="how_do_you_convert_a_microformats_2_example_to_RDFa_syntax">Q: How do you convert a microformats2 example to RDFa 1.1 syntax?</span>

A: In short you may use the 'typeof' attribute for the microformats2 root class name, and use the 'property' attribute for microformats2 properties.

E.g. this from the microformats2 page:

<syntaxhighlight lang="html">
<h1 class="h-card">
<span class="p-name">
<span class="p-given-name">Chris</span>
<abbr class="p-additional-name">R.</abbr>
<span class="p-family-name">Messina</span>
</span>
</h1>
</syntaxhighlight>

Here is the same markup with RDFa 1.1 syntax, using an implied or explicit RDFa Profile from somewhere else (undefined):

<syntaxhighlight lang="html">
<h1 typeof="h-card">
<span property="p-name">
<span property="p-given-name">Chris</span>
<abbr property="p-additional-name">R.</abbr>
<span property="p-family-name">Messina</span>
</span>
</h1>
</syntaxhighlight>

The similarity of these two markup examples implies that it may be possible to extend RDFa 1.1 compliant parsers to become compliant microformats2 parsers.

== see also ==
* [[microformats2]]
* [[microformats2-brainstorming]]
* [[microformats2-experimental-properties]]
* [[microformats2-prefixes]]
* [[microformats2-faq]]

microformats2

2023-07-26T21:30:17Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:microformats2}}
Welcome to the microformats2 home page.

== Summary ==
Microformats2 is the latest version of microformats, the simplest way to markup structured information in HTML. Microformats2 improves ease of use and implementation for <em>both</em> authors (publishers) and developers ([[microformats2-parsing|parser]] implementers).

Microformats2 replaces and supersedes both classic microformats (sometimes called microformats1), as well as incorporates lessons learned from [[microdata]] and [[RDFa]].

=== simple microformats2 examples ===
Here are a few <span id="simple_microformats_2_examples">simple microformats2 examples</span> along with canonical [[JSON]].

==== person example ====
* Simple person reference:
<syntaxhighlight lang="html">
<span class="h-card">Frances Berriman</span>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Frances Berriman"]
}
}]
}
</syntaxhighlight>

----

==== hyperlinked person ====
* Simple hyperlinked person reference
<syntaxhighlight lang="html">
<a class="h-card" href="http://benward.me">Ben Ward</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Ben Ward"],
"url": ["http://benward.me"]
}
}]
}
</syntaxhighlight>

----

==== hyperlinked person image ====
* Simple hyperlinked person image
<syntaxhighlight lang="html">
<a class="h-card" href="http://rohit.khare.org/">
<img alt="Rohit Khare"
src="https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg" />
</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Rohit Khare"],
"url": ["http://rohit.khare.org/"],
"photo": ["https://s3.amazonaws.com/twitter_production/profile_images/53307499/180px-Rohit-sq_bigger.jpg"]
}
}]
}
</syntaxhighlight>

Additional simple cases details in [[microformats-2-implied-properties]].

----

==== detailed person example ====
* More detailed person
<syntaxhighlight lang="html">
<div class="h-card">
<img class="u-photo" alt="photo of Mitchell"
src="https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"/>
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="u-url"
href="https://twitter.com/MitchellBaker"
>@MitchellBaker</a>)
<span class="p-org">Mozilla Foundation</span>
<p class="p-note">
Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities.
</p>
<span class="p-category">Strategy</span>
<span class="p-category">Leadership</span>
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"photo": ["https://webfwd.org/content/about-experts/300.mitchellbaker/mentor_mbaker.jpg"],
"name": ["Mitchell Baker"],
"url": [
"http://blog.lizardwrangler.com/",
"https://twitter.com/MitchellBaker"
],
"org": ["Mozilla Foundation"],
"note": ["Mitchell is responsible for setting the direction and scope of the Mozilla Foundation and its activities."],
"category": [
"Strategy",
"Leadership"
]
}
}]
}
</syntaxhighlight>

----
=== details from examples ===
Details demonstrated by the examples:
# The JSON <code>"type"</code> uses the full microformat root class name (e.g. <code>"h-card"</code>) for consistent identification.
# all properties are optional and syntactically plural with parsed values provided in document order; particular microformats (and applications there-of) may apply specific/singular semantics to first value of a property.

=== microformats2 design ===

microformats2 has the following key design aspects:

; Prefixes for class names
: All microformats class names use prefixes. Prefixes are '''syntax independent from vocabularies''', which are developed separately.
* <code>h-*</code> for root class names (e.g. <code>h-card</code>)
* <code>p-*</code> for plain text properties (e.g. <code>p-name</code>)
* <code>u-*</code> for URL properties (e.g. <code>u-photo</code>)
* <code>dt-*</code> for date/time properties (e.g. <code>dt-bday</code>)
* <code>e-*</code> for embedded markup properties (e.g. <code>e-note</code>)<br />

See [[microformats2-prefixes]] for more details.

; Flat sets of optional properties
: All microformats consist of a root, and a collection of properties. Hierarchical data is represented with nested microformats, typically as property values themselves. Properties are all optional and potentially multivalued (applications needing a singular semantic may use first instance).

; Single class markup for common uses
: Common simple markup patterns require only a single microformat root class name, which parsers use to find a few generic properties: <code>name</code>, <code>url</code>, <code>photo</code>. The simple microformats2 examples above demonstrate these.

----

Parsing each prefix (including generating canonical JSON) is detailed step-by-step in:
* The '''[[microformats2-parsing|microformats2 parsing specification]]'''

'''Note:''' Most properties are specified and used with a single specific prefix (or occasionally two or three) that is self-evident from context. However, any parsing prefix can be used with any property, especially if you find a good reason to do so!

== v2 vocabularies ==
Status: '''<span id="draft_v2_vocabularies">draft</span>'''. Please review and provide feedback in [[IRC]].
* [[h-adr]]
* [[h-card]]
* [[h-entry]]
* [[h-event]]
* [[h-feed]]
* [[h-geo]]
* [[h-item]]
* [[h-listing]]
* [[h-product]]
* [[h-recipe]]
* [[h-resume]]
* [[h-review]]
* [[h-review-aggregate]]

See below for vocabulary summaries.

=== h-adr ===
{{main|h-adr}}

The '''h-adr''' microformat is for marking up structured locations such as addresses, physical and/or postal. This is an update to [[adr]].

root class name: '''<code>h-adr</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-adr</nowiki>

properties:
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-street-address</code>'''
* '''<code>p-locality</code>'''
* '''<code>p-region</code>'''
* '''<code>p-postal-code</code>'''
* '''<code>p-country-name</code>'''
* '''<code>p-label</code>''' - new in [[vCard4]] ([[RFC6350]])
* '''<code>p-geo</code>''' (or '''<code>u-geo</code>''' with a RFC 5870 geo: URL) - new in [[vCard4]] ([[RFC6350]])
* '''<code>p-latitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-longitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-adr" is found, don't look for an "adr" on the same element.

compat root class name: <code id="adr">adr</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>post-office-box</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>

=== h-card ===
{{main|h-card}}

The '''h-card''' microformat is for marking up people and organizations. This is an update to [[hCard]].

root class name: '''<code>h-card</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-card</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>p-honorific-prefix</code>'''
* '''<code>p-given-name</code>'''
* '''<code>p-additional-name</code>'''
* '''<code>p-family-name</code>'''
* '''<code>p-sort-string</code>'''
* '''<code>p-honorific-suffix</code>'''
* '''<code>p-nickname</code>'''
* '''<code>u-email</code>'''
* '''<code>u-logo</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>'''
* '''<code>u-uid</code>'''
* '''<code>p-category</code>'''
* '''<code>p-adr</code>'''
* '''<code>p-post-office-box</code>'''
* '''<code>p-extended-address</code>'''
* '''<code>p-street-address</code>'''
* '''<code>p-locality</code>'''
* '''<code>p-region</code>'''
* '''<code>p-postal-code</code>'''
* '''<code>p-country-name</code>'''
* '''<code>p-label</code>'''
* '''<code>p-geo</code>''' or '''<code>u-geo</code>''' with a RFC 5870 geo: URL, new in [[vCard4]] ([[RFC6350]])
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)
* '''<code>p-tel</code>'''
* '''<code>p-note</code>'''
* '''<code>dt-bday</code>'''
* '''<code>u-key</code>'''
* '''<code>p-org</code>'''
* '''<code>p-job-title</code>''' - previously 'title' in hCard, disambiguated.
* '''<code>p-role</code>
* '''<code>u-impp</code>''' per RFC 4770, new in [[vCard4]] ([[RFC6350]])
* '''<code>p-sex</code>''' new in [[vCard4]] ([[RFC6350]])
* '''<code>p-gender-identity</code>''' new in [[vCard4]] ([[RFC6350]])
* '''<code>dt-anniversary</code>''' new in [[vCard4]] ([[RFC6350]])
* ...

Reserved properties: (properties not used much (if at all) in practice)
* '''<code>p-organization-name</code>'''
* '''<code>p-organization-unit</code>'''
* '''<code>p-tz</code>'''
* '''<code>dt-rev</code>'''
* ...

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-card" is found, don't look for a "vcard" on the same element.

compat root class name: <code id="vcard">vcard</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>honorific-prefix</code>
* <code>given-name</code>
* <code>additional-name</code>
* <code>family-name</code>
* <code>honorific-suffix</code>
* <code>nickname</code>
* <code>email</code> - parse as '''u-'''
* <code>logo</code> - parse as '''u-'''
* <code>photo</code> - parse as '''u-'''
* <code>url</code> - parse as '''u-'''
* <code>uid</code> - parse as '''u-'''
* <code>category</code>
* <code>adr</code> - parse as '''<code>p-adr h-adr</code>''' including compat root class <code>adr</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>
* <code>label</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root class <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* <code>tel</code>
* <code>note</code>
* <code>bday</code> - parse as '''dt-'''
* <code>key</code> - parse as '''u-'''
* <code>org</code>
* <code>organization-name</code>
* <code>organization-unit</code>
* <code>title</code> - parse as '''p-job-title'''
* <code>role</code>
* ...

Reserved: (backward compat properties that parsers {{may}} implement, if they do, they {{must}} implement in this way:
* <code>tz</code>
* <code>rev</code> - parse as '''dt-'''
* ...

Note: use of 'value' within 'tel' should be automatically handled by the support of the [[value-class-pattern]]. And for now, the 'type' subproperty of 'tel' is dropped/ignored. If there is demonstrable documented need for additional tel types (e.g. fax), we can introduce new flat properties as needed (e.g. p-tel-fax).

=== h-entry ===
{{main|h-entry}}

The '''h-entry''' microformat is for marking up syndicatable content such as blog posts, notes, articles, comments, photos and similar. This is an update to [[hAtom]].

root class name: '''<code>h-entry</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-entry</nowiki>

properties:
* '''<code>p-name</code>''' (was p-entry-title, see issues)
* '''<code>p-summary</code>''' (was p-entry-summary, see issues)
* '''<code>e-content</code>''' (was e-entry-content, see issues)
* '''<code>dt-published</code>'''
* '''<code>dt-updated</code>'''
* '''<code>p-author</code>'''
* '''<code>p-category</code>'''
* '''<code>u-url</code>'''
* '''<code>u-uid</code>'''
* '''<code>p-geo</code>'''
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''

This is an update to [[hAtom]].

Brainstorming:

The following properties are proposed additions to h-entry above and beyond what hAtom (or Atom) provides, based on various existing link preview markup conventions:
* '''<code>u-photo</code>'''
* '''<code>u-audio</code>''' - consider special u- parsing rules for <code><audio></code>
* '''<code>u-video</code>''' - consider special u- parsing rules for <code><video></code>
* '''<code>u-in-reply-to</code>''' - for links to other posts that this post is a reply to (comment regarding, etc.)

Backward compatibility:

(*)hAtom-specific implementations that perform custom display or translation (e.g. to Atom XML) {{should}} prefer <code>p-name</code> over <code>p-entry-title</code>, and use <code>p-entry-title</code> value(s) as a fallback if there is no <code>p-name</code>.

For hAtom backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-entry" is found, don't look for a "hentry" on the same element.

compat root class name: <code id="hentry">hentry</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>entry-title</code> - parse as '''<code>p-name</code>'''
* <code>entry-summary</code>
* <code>entry-content</code> - parse as '''e-'''
* <code>published</code> - parse as '''dt-'''
* <code>updated</code> - parse as '''dt-'''
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>category</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* ...

<span id="h-entry-faq">FAQ:</span>
<div class="discussion">
* '''What is the <code>p-name</code> of a [http://indiewebcamp.com/note note]?'''
** A few options, from simplest to most detailed.
*** '''same as the p-content/e-content''' property.
*** '''same as the <code>title</code> element''' on the note permalink post page. When publishing a note on its own permalink post page, the contents of the note are likely abbreviated for the title of the page. The same abbreviation can be used for the p-name.
*** '''first sentence of the p-content/e-content''' property. It may be better for [http://indiewebcamp.com/syndication syndication] and [[link-preview]] purposes to provide just the first sentence of the note as the <code>p-name</code>. Similarly if only a portion of the content is syndicated to other sites, that portion can be marked up as the <code>p-summary</code>.
* ...
</div>

Resolved Issues:
* 2012-245 Resolved. See [http://krijnhoetmer.nl/irc-logs/microformats/20120830#l-120 2012-243 IRC discussion/consensus] for:
** Use '''<code>p-summary</code> instead of <code>p-entry-summary</code>'''. The historical semantic of "entry-summary" is not different from "summary" in any significant (or discernible way). Collapsing the two will simplify the overall microformats2 vocabularies further. In microformats2, entry-summary is no more.
** Use '''<code>e-content</code> instead of <code>e-entry-content</code>'''. Same point and advantage. In microformats2, entry-content is no more.
** '''drop <code>p-entry-title</code>'''. Unnecessary and subsumed by "p-name". Would consider move to backward compat only if cases are presented - known publishing uses are expected to be updated shortly.

=== h-event ===
{{main|h-event}}

The '''h-event''' microformat is for marking up events. This is an update to [[hCalendar]].

root class name: '''<code>h-event</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-event</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>p-summary</code>'''(*)
* '''<code>dt-start</code>'''
* '''<code>dt-end</code>'''
* '''<code>dt-duration</code>'''
* '''<code>p-description</code>'''
* '''<code>u-url</code>'''
* '''<code>p-category</code>'''
* '''<code>p-location</code>'''
* '''<code>p-geo</code>'''
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* ...

This is an update to [[hCalendar]].

(*)hCalendar-specific implementations that perform custom display or translation (e.g. to iCalendar .ics) {{should}} prefer <code>p-name</code> over <code>p-summary</code>, and use <code>p-summary</code> value(s) as a fallback if there is no <code>p-name</code>.

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-event" is found, don't look for a "vevent" on the same element.

compat root class name: <code id="vevent">vevent</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> - parse as '''<code>p-name</code>'''
* <code>dtstart</code> - parse as '''<code>dt-start</code>'''
* <code>dtend</code> - parse as '''<code>dt-end</code>'''
* <code>duration</code> - parse as '''<code>dt-duration</code>'''
* <code>description</code>
* <code>url</code> - parse as '''u-'''
* <code>category</code>
* <code>location</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>, and compat root <code>adr</code> in the absence of <code>h-adr</code>
* <code>geo</code> - parse as '''<code>p-geo h-geo</code>''' including compat root <code>geo</code>
* <code>latitude</code>
* <code>longitude</code>
* ...

=== h-geo ===
{{main|h-geo}}

The '''h-geo''' microformat is for marking up WGS84 geophysical coordinates. This is an update to [[geo]].

root class name: '''<code>h-geo</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-geo</nowiki>

properties:
* '''<code>p-latitude</code>'''
* '''<code>p-longitude</code>'''
* '''<code>p-altitude</code>''' - new in [[vCard4]] ([[RFC6350]] from RFC 5870)

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-geo" is found, don't look for an "geo" on the same element.

compat root class name: <code id="geo">geo</code>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>latitude</code>
* <code>longitude</code>

=== h-item ===
{{main|h-item}}

The '''h-item''' microformat is for marking up the item of an [[h-review]] or [[h-product]]. This is an update to part of [[hReview]].

root class name: '''<code>h-item</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-item</nowiki>

properties:
* '''<code>p-name</code>'''
* '''<code>u-photo</code>'''
* '''<code>u-url</code>'''

Note: in practice, due to the microformats2 implied property rules, it is expected that most uses of "h-item" won't require any explicit properties at all (since microformats2 parsers will infer name, photo, and url properties from the structure of the element with "h-item" and its contained content/elements if any).

=== h-product ===
{{main|h-product}}

The '''h-product''' microformat is for marking up products. This is an update to [[hProduct]].

root class name: '''<code>h-product</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-product</nowiki>

properties:
* '''<code>p-name</code>''' - name of the product
* '''<code>u-photo</code>''' - photo of the product
* '''<code>p-brand</code>''' - manufacturer, can also be a nested <code>h-card</code>
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>e-description</code>'''
* '''<code>u-url</code>''' - URL of the product
* '''<code>u-identifier</code>''' - includes type (e.g. mpn, upc, isbn, issn, sn, vin, sku etc.) and value.
* '''<code>p-review</code>''' - a review of the product, can also be a nested <code>h-review</code>
* '''<code>p-price</code>''' - retail price of the product

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-product" is found, don't look for an "hproduct" on the same element.

compat root class name: <code id="hproduct">hproduct</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>photo</code> - parse as '''u-'''
* <code>brand</code>
* <code>category</code>
* <code>description</code>
* <code>identifier</code> - parse as '''u-'''
* <code>url</code> - parse as '''u-'''
* <code>review</code> - including compat root class <code>hreview</code> in the absence of <code>h-review</code>
* <code>price</code>

Note: [[hProduct]] has at least one experimental property which has real world adoption due to [[Google]] and [[Bing]] search support of hProduct. Currently this is: '''price'''

=== h-recipe ===
{{main|h-recipe}}

The '''h-recipe''' microformat is for marking up food recipes. This is an update to [[hRecipe]].

root class name: '''<code>h-recipe</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-recipe</nowiki>

properties:
* '''<code>p-name</code>''' - the name of the recipe
* '''<code>p-ingredient</code>''' - describes one or more ingredients used in the recipe.
* '''<code>p-yield</code>''' - Specifies the quantity produced by the recipe, like how many persons it satisfyies
* '''<code>e-instructions</code>''' - the method of the recipe.
* '''<code>dt-duration</code>''' - the time it takes to prepare the meal described by the recipe.
* '''<code>u-photo</code>''' - an accompanying image

Experimental properties with wide adoption
* '''<code>p-summary</code>''' - provides a short summary or introduction
* '''<code>p-author</code>''' - the person who wrote the recipe with <code>h-card</code>
* '''<code>dt-published</code>''' - the date the recipe was published
* '''<code>p-nutrition</code>''' - nutritional information like calories, fat, dietary fiber etc.
* ...

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-recipe" is found, don't look for an "hrecipe" on the same element.

compat root class name: <code id="hrecipe">hrecipe</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>fn</code> - parse as '''<code>p-name</code>'''
* <code>ingredient</code>
* <code>yield</code>
* <code>instructions</code> - parse as '''e-'''
* <code>duration</code> - parse as '''dt-'''
* <code>photo</code> - parse as '''u-'''
* <code>summary</code>
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>nutrition</code>

Note: [[hRecipe]] has a number of experimental properties which have real world adoption due to [[Google]] recipe search support of hRecipe. These are: summary, author, published and nutrition

=== h-resume ===
{{main|h-resume}}

The '''h-resume''' microformat is for marking up resumes. This is an update to [[hResume]].

root class name: '''<code>h-resume</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-resume</nowiki>

properties:
* '''<code>p-summary</code>''' - overview of qualifications and objectives
* '''<code>p-contact</code>''' - current contact info in an <code>h-card</code>
* '''<code>p-education</code>''' - an education <code>h-calendar</code> event, years, nested <code>h-card</code> of the school, location.
* '''<code>p-experience</code>''' - a job or other professional experience <code>h-calendar</code> event, years, nested <code>h-card</code> of the organization, location, job-title.
* '''<code>p-skill</code>''' - a skill or ability, optionally including level and/or duration of experience
* '''<code>p-affiliation</code>''' - an affiliation with an <code>h-card</code> organization

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-resume" is found, don't look for an "hresume" on the same element.

compat root class name: <code id="hresume">hresume</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code>
* <code>contact</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>education</code> - including compat root <code>vevent</code> in the absence of <code>h-event</code>
* <code>experience</code> - including compat root <code>vevent</code> in the absence of <code>h-event</code>
* <code>skill</code>
* <code>affiliation</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>

Note: skill has a [[hresume-skill-brainstorm|proposed expansion into competency]] with explicit summary, rating and/or duration components. Based on existing real world adoption, we should consider an h-competency vocabulary with p-summary, p-rating, and dt-duration properties.

=== h-review ===
{{main|h-review}}

The '''h-review''' microformat is for marking up reviews. This is an update to [[hReview]]. See also [[h-item]].

root class name: '''<code>h-review</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-review</nowiki>

properties:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed i.e. 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
* '''<code>dt-reviewed</code>''' - date time of when the review was written
* '''<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-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>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>u-url</code>''' - URL of the review

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review" is found, don't look for an "hreview" on the same element.

compat root class name: <code id="hreview">hreview</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> parse as '''<code>p-name</code>'''
* <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>reviewer</code> - including compat root vcard in the absence of h-card
* <code>dtreviewed</code> - parse as '''dt-'''
* <code>rating</code>
* <code>best</code>
* <code>worst</code>
* <code>description</code> - parse as '''e-'''
* <code>rel="tag"</code> - parse as '''p-category'''
* <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>. Microformats2 parsers {{should}} map these URLs into the page scoped rel collection.

=== h-review-aggregate ===
{{main|h-review-aggregate}}

The '''h-review-aggregate''' microformat is for marking up aggregate reviews of a single item. This is an update to [[hreview-aggregate]]. See also [[h-item]].

root class name: '''<code>h-review-aggregate</code>'''<br/>
profile/itemtype: <nowiki>http://microformats.org/profile/h-review-aggregate</nowiki>

properties:
* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing been reviewed i.e. 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-rating</code>''' - value from 1-5 indicating average rating for the item (5 best).
* '''<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-count</code>''' - number of reviews aggregated.
* '''<code>p-votes</code>''' - number of reviewers who have rated the product, thus contributing to the average rating.
* '''<code>p-category</code>''' - freeform categories or tags applied to the item by the reviewer
* '''<code>u-url</code>''' - URL of the review

For backward compatibility, microformats2 parsers {{should}} detect the following root class name and property names. A microformats2 parser may use existing classic microformats [[parsers]] to extract these properties. If an "h-review-aggregate" is found, don't look for an "hreview-aggregate" on the same element.

compat root class name: <code id="hreview-aggregate">hreview-aggregate</code><br/>
properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> parse as '''<code>p-name</code>'''
* <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>rating</code>
* <code>best</code>
* <code>worst</code>
* <code>count</code>
* <code>votes</code>
* <code>rel="tag"</code> - parse as '''p-category'''
* <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.

=== v2 vocab notes ===
Notes:
* All v2 vocabularies are defined as flat lists of properties of an object/item, and thus can be used in microformats-2 syntax as shown, or in microdata items, or RDFa. The microformats-2 property parsing prefixes "p-", "u-", "dt-", "e-" are omitted when using defined properties in microdata itemprop and RDFa property as those syntaxes have their own element-specific parsing rules.
* Profile URLs are provided for use with the HTML4 <code>profile</code> attribute, microdata <code>itemtype</code> attribute, and RDFa <code>vocab</code> & <code>typeof</code> attributes (though the latter requires slicing off the trailing segment of the profile for the typeof attribute, and leaving the rest in vocab).
* microformats2 properties may also be explicitly bound as URIs using [[rel-profile]], the [[html5-profile]] attribute proposal, or an HTML5 'vocab' attribute instead. If URI bound terms are important to you, please express interest on [[rel-profile]], [[html5-profile]], or contribute to an [[html5-vocab]] draft.

=== v2 vocab to-do ===
To do:
* write a simple tutorial for creating/getting started with microformats-2 markup for new content
* examples in each h-* spec listed above of how to embed other microformats in them
* actual profile documents at <nowiki>http://microformats.org/profile/h-*</nowiki> URLs mentioned above.
* Provide any necessary microdata-specific language as needed (e.g. to be comparably understandable to the [http://www.whatwg.org/specs/web-apps/current-work/#vcard sample vCard4/hCard1 microdata vocabulary]. Also provide any necessary RDFa-specific language as needed. Both preferably in a generic vocabulary-independent way.
* write a porting guide mapping v1 property -> v2 property
** use-case: simple search/replace in templates (e.g. in case web author doesn't remember existing microformats vocabs and where they used them).
** advise using *both* in existing templates (e.g. in case some CSS depends on the existing microformats)
* analyzie/document how well the microformats2 model and vocabularies satisfy the [http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2009-May/019681.html use-cases used to design/create microdata].

== combining microformats ==
Since microformats2 uses simple flat sets of properties for each microformat, multiple microformats are combined to indicate additional structure.

=== h-event location h-card ===
Events commonly have venue information with additional structure, like address information. For example:

<syntaxhighlight lang="html">
<div class="h-event">
<a class="p-name u-url" href="http://indiewebcamp.com/2012">
IndieWebCamp 2012
</a>
from <time class="dt-start">2012-06-30</time>
to <time class="dt-end">2012-07-01</time> at
<span class="p-location h-card">
<a class="p-name p-org u-url" href="http://geoloqi.com/">
Geoloqi
</a>,
<span class="p-street-address">920 SW 3rd Ave. Suite 400</span>,
<span class="p-locality">Portland</span>,
<abbr class="p-region" title="Oregon">OR</abbr>
</span>
</div>
</syntaxhighlight>

The nested h-card used to structure the p-location of the h-event is represented as a structured value for "location" in the JSON, which has an additional key, "value" that represents the plain text version parsed from the p-location.

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-event"],
"properties": {
"name": ["IndieWebCamp 2012"],
"url": ["http://indiewebcamp.com/2012"],
"start": ["2012-06-30"],
"end": ["2012-07-01"],
"location": [{
"value": "Geoloqi",
"type": ["h-card"],
"properties": {
"name": ["Geoloqi"],
"org": ["Geoloqi"],
"url": ["http://geoloqi.com/"],
"street-address": ["920 SW 3rd Ave. Suite 400"],
"locality": ["Portland"],
"region": ["Oregon"]
}
}]
}
}]
}
</syntaxhighlight>

Questions:
<div class="discussion">
* Should the nested hCard be present also as a top-level item in the JSON? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
** My current (2012-243) leaning is no. - [[User:Tantek|Tantek]] 18:53, 30 August 2012 (UTC)
** If so, how do we avoid expansion of the JSON geometrically proportional to the depth of microformat nesting? (Or do we not worry about it?)
* Should there be a canonical hierarchical JSON and a canonical flattened JSON? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
** My current (2012-243) leaning is no, we stick with one canonical JSON for uf2 which is hierarchical. - [[User:Tantek|Tantek]] 18:53, 30 August 2012 (UTC)
** If so, should the flattened JSON have references from properties to nested microformats that have been pushed to the top level per flattening? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
*** If so, what convention does/do JSON follow for such synthetic local reference identifiers? - [[User:Tantek|Tantek]] 02:02, 19 June 2012 (UTC)
</div>

Notes:
* The 'location' value reflects the visible text of its element, including spaces and punctuation, as well as the state abbreviation 'OR'. The 'h-card' property values are only what is marked up, and thus include structure values without extra punctuation, and the state takes the expanded form from the <code>title</code> attribute of its <code><abbr></code> element.

=== h-card org h-card ===
People often publish information general to their company rather than specific to them, in which case, they may wish to encapsulate that in separately nested microformat. E.g. here is a simple h-card example with org property:

[http://blog.lizardwrangler.com Mitchell Baker] (Mozilla Foundation)

with source:
<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<span class="p-org">Mozilla Foundation</span>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": ["Mozilla Foundation"]
}
}]
}
</syntaxhighlight>

Sometimes such organization affiliations are hyperlinked to the website of the organization:

[http://blog.lizardwrangler.com Mitchell Baker] ([http://mozilla.org/ Mozilla Foundation])

You can mark that up with a nested h-card:
<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
</syntaxhighlight>

Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an <code><a href></code> would.

'''FOR PARSERS ONLY:'''

The nested 'h-card' could be marked up as an 'h-org' as well, which adds it to the nested microformat's type array, all as part of the property specified by the 'p-org'.

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="p-org h-card h-org"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"],
"org": [{
"value": "Mozilla Foundation",
"type": ["h-card", "h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}
}]
}
</syntaxhighlight>

'''FOR PARSERS ONLY:'''

Without a property class name like 'p-org' holding all the nested objects together, we need to introduce another array for nested children (similar to the existing DOM element notion of children) of a microformat that are not attached to a specific property:

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-org h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card","h-org"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
</syntaxhighlight>

Since there's no property class name on the element with classes 'h-card' and 'h-org', the microformat representing that element is collected into the children array.

Such a nested microformat implies some relationship (containment, being related), but is not as useful as if the nested microformat was a specific property of its parent.

For this reason it's recommended that authors should not publish nested microformats without a property class name, and instead, when nesting microformats, authors should always specify a property class name (like 'p-org') on the same element as the root class name(s) of the nested microformat(s) (like 'h-card' and/or 'h-org').

'''FOR PARSERS ONLY:'''

Or the nested object could be only marked up with 'h-card'. Source:

<syntaxhighlight lang="html">
<div class="h-card">
<a class="p-name u-url"
href="http://blog.lizardwrangler.com/"
>Mitchell Baker</a>
(<a class="h-card"
href="http://mozilla.org/"
>Mozilla Foundation</a>)
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [{
"type": ["h-card"],
"properties": {
"name": ["Mitchell Baker"],
"url": ["http://blog.lizardwrangler.com/"]
},
"children": [{
"type": ["h-card"],
"properties": {
"name": ["Mozilla Foundation"],
"url": ["http://mozilla.org/"]
}
}]
}]
}
</syntaxhighlight>

'''TO DO: Add h-event h-card example and JSON, per real world publishing examples like [http://www.swingtime.co.uk/List/ClSouth.html Swing Time: Classes in Southern England].'''

== authoring ==
=== minimal markup ===
The best way to use microformats-2 is with as little additional markup as possible. This keeps your code cleaner, improves its maintainability, and thus the quality and longevity of your microformats.

One big advantage of microformats-2 over previous microformats (and others) is the ability to add one class name to an existing element to create a structured item.

See the [[microformats-2#simple_microformats_2_examples|simple examples at the top]] for a start, e.g.

Simple hCards work just by adding <code>class="h-card"</code> :
<syntaxhighlight lang="html">
<span class="h-card">Frances Berriman</span>

<a class="h-card" href="http://benward.me">Ben Ward</a>

<img class="h-card" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>

<a class="h-card" href="http://tantek.com">
<img alt="Tantek Çelik" src="http://ttk.me/logo.jpg"/>
</a>
</syntaxhighlight>

* Tip: Inside an open tag, put the <code>class</code> attribute <em>first</em>, then any human text content attributes (e.g. <code>alt</code>), then URL attributes (e.g. <code>href</code> <code>src</code>), and lastly other attributes (e.g. <code>style</code>). Putting the class attribute first ties it closely to the element name/tag itself, makes it more obvious, and thus more likely to be kept up to date.

=== backward compatible ===
If you depend on current microformats [[implementations]], while they're being updated to support [[microformats2]], you can include both existing classic microformats and microformats2 markup.

In short: use both sets of class names simultaneously.

When doing so, use them on the same element, with the microformats-2 class name first, followed immediately by the existing microformats class name.

Here are the microformats-2 hCards from above with current [[hCard]] markup as well, which may require adding a wrapping element (e.g. a <code><span></code>) to separate the root class name element from explicit property class name elements:

<syntaxhighlight lang="html">
<span class="h-card vcard">
<span class="p-name fn">Frances Berriman</span>
</span>

<span class="h-card vcard">
<a class="p-name fn u-url url" href="http://benward.me">Ben Ward</a>
</span>

<span class="h-card vcard">
<img class="p-name fn u-photo photo" alt="Sally Ride"
src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>
</span>

<span class="h-card vcard">
<a class="u-url url" href="http://tantek.com">
<img class="p-name fn u-photo photo" alt="Tantek Çelik"
src="http://ttk.me/logo.jpg"/>
</a>
</span>
</syntaxhighlight>

Tips:
* use the microformats-2 class name first, e.g.
** <code>class="h-card vcard"</code>
** <code>class="u-url url"</code>
* and pair them when using an element for multiple properties, e.g.:
** <code>class="p-name fn u-url url"</code>
** <code>class="p-name fn u-photo photo"</code>
* put microformats classes after classes for CSS (since page authors will likely interact more with their own classes for design than with microformats classes), e.g. as used on individual microformats [[events]] pages:
** <code>class="event-page h-event vevent"</code>

The prefixes (h-, p-, etc.) of microformats2 class names provide easier recognition, and when followed by the similarly named existing class name, they're more easily recognized as related and thus kept together when the markup is maintained over time.

Related FAQ: [[microformats2-faq#when_using_both_h-card_and_vcard_which_should_be_first_and_why|When using both h-card and vcard which should be first and why?]]

== extensions ==
microformats2 is extensible by means of two separate but syntactically similar extension prefixes for experiments intended to be iterated & evolved and for vendor specific extensions not intended for standardization.

=== experimental extensions ===
There have been times when specific sites have wanted to extend microformats beyond the set of properties in the microformat vocabulary, and currently lack any '''experimental''' way to do so - to try and see if a feature (or even a whole format) is interesting in the real world before bothering to pursue researching and walking it through the microformats process. Thus:

For experimental extensions for the purpose of prototyping to learn more, iterate, towards possibly standardizing, use the <code>-x-</code> prefix before root and property class names.

Specifically:
* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a literal 'x' for an experimental extension

Examples:
* "p-x-prep-time" - a possible experimental property name to be added to [[h-recipe]] upon consideration/documentation of real-world usage/uptake.

See [[microformats2-experimental-properties]] for more examples.

=== <span id="VENDOR_EXTENSIONS">vendor extensions</span> ===
For vendor specific extensions, microformats2 uses a mechanism similar to CSS vendor extensions, using a similar syntax as experimental extensions, except with a vendor prefix instead of a literal 'x'.

* '*-x-' + '-' + meaningful name for root and property class names
** where "*" indicates the single-character-prefix as defined above
** where "x" indicates a vendor prefix (more than one character, e.g. like CSS vendor extension abbreviations, or some stock symbols, avoiding first words/phrases/abbreviations of microformats properties like dt-, numbers allowed after first character)

Examples:
* "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "one-ring" microformat root class name.
* "p-goog-preptime" - to represent [http://www.google.com/support/webmasters/bin/answer.py?answer=173379 Google's "preptime" property extension] to [[hRecipe]] (aside: "duration" may be another property type to consider separate from "datetime" as it may be subject to different parsing rules.)

See [[vendor-prefixes]] for more examples.

=== extensions background ===
This extensibility mechanism is a composition of the following (at least somewhat) successful extension syntaxes:
* [http://www.w3.org/TR/CSS21/syndata.html#vendor-keywords CSS 2.1 4.1.2.1 Vendor-specific extensions]
* IETF MIME/content-type "x-*" extensions per RFC 2045 Section 6.3. [http://en.wikipedia.org/wiki/Internet_media_type]
* IETF MIME experimental fields (e.g. x-spam-score)
* HTTP header extensions (e.g. x-pingback)
* note also [http://www.mnot.net/blog/2009/02/18/x- some critical thoughts from mnot]

In particular:

Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.

Proprietary or experimental CSS3 property implementations have been very successful.

There has been much use of border radius properties and animations/transitions which use CSS properties with vendor-specific prefixes like:

* -moz-border-radius
* -webkit-border-radius

etc.

Note that these are merely string '''prefixes''', not bound to any URL, and thus not namespaces in any practical sense of the word. This is quite an important distinction, as avoiding the need to bind to a URL has made them easier to support and use.

This use of vendor specific CSS properties allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.

The benefits have been two-fold:
* designers have been able to make more attractive sites sooner (at least in some browsers)
* features have been market / real-world tested before being fully standardized, thus resulting in better features

Implementers have used/introduced "x-" prefixes for IETF MIME/content-types for experimental content-types, MIME parameter extensions, and HTTP header extensions, per RFC 2045 Section 6.3, RFC 3798 section 3.3, and [https://secure.wikimedia.org/wikipedia/en/wiki/List_of_HTTP_header_fields#Common_non-standard_headers Wikipedia: HTTP header fields - non-standard headers] (could use RFC reference instead) respectively, like:

* application/x-latex (per [https://secure.wikimedia.org/wikipedia/en/wiki/Internet_media_type#Type_x Wikipedia Internet media type: Type x])
* x-spam-score (in email headers)
* X-Pingback (per [http://en.wikipedia.org/wiki/Pingback Wikipedia:Pingback])

Some standard types started as experimental "x-" types, thus demonstrating this experiment first, standardize later approach has worked for at least some cases:

* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])

See [[microformats2-origins#VENDOR_EXTENSIONS]] for more background.

== validators ==
microformats2 validators:

{{new}} Test your microformatted web page with:
* https://pin13.net/mf2/

Barnaby Walters has a hosted version of the open source php-mf2 [[parser]] where you can enter your markup into a textarea and see how it's parsed:
* http://waterpigs.co.uk/php-mf2/

See the [[validators]] page for a longer list of validators.

== Examples in the wild ==
Please add new examples in the wild of microformats-2 to the top of this list. When it gets too big we can move it to a separate page like [[microformats-2-examples-in-wild]].

* ...
* David John Mead marks up his profile, blog posts and comments with h-card, h-entry and h-cite on [http://davidjohnmead.com davidjohnmead.com]
* [[User:Brian|Brian Suda]] marks up his blog posts up with h-entry and h-card on [http://optional.is/required/ optional.is]
* Ashton McAllan marks up her blog posts, reposts, comments and likes with h-entry, h-card and h-cite on [https://acegiak.net/ acegiak.net]
* Emma Kuo marks up her blog posts and notes with h-entry and h-card on [http://notenoughneon.com/ notenoughneon.com]
* Scott Jenson marks up his blog posts with h-entry and h-card on [http://jenson.org/ jenson.org]
* Emily McAllen marks up her blog posts with h-entry and h-card on [http://blackwoolholiday.com/ blackwoolholiday.com]
* Ryan Barrett marks up his blog posts, notes, replies and likes with h-entry and h-card on [https://snarfed.org/ snarfed.org]
* Barry Frost marks up his notes with h-entry, h-card and h-cite on [http://barryfrost.com/ barryfrost.com]
* Amber Case marks up her profile, blog posts, replies and notes with h-entry and h-card on [http://caseorganic.com/ caseorganic.com]
* Johannes Ernst marks up his blog posts with h-entry on [http://upon2020.com/blog/ upon2020.com]
* Michiel de Jong marks up his profile and notes with h-entry and h-card on [https://michielbdejong.com/ michielbdejong.com]
* Mike Taylor marks up his profile and blog posts with h-card and h-entry on [https://bear.im/bearlog/ bear.im]
* Erin Jo Ritchey marks up her profile, posts and comments using h-card, h-entry and h-cite with idno on [http://erinjo.is/ erinjo.is]
* Jeena Paradies marks up his profile, blog posts, notes and comments using h-card, h-entry and h-cite on [https://jeena.net/ jeena.net]
* Andy Sylvester marks up his profile, blog posts and comments using h-card and h-entry on [http://andysylvester.com/2014/03/01/howto-setting-up-the-selfoss-feed-reader-with-microformats-support/ andysylvester.com] (note: as of 2014-03-13 using h-entry for comments instead of correct h-cite --[[User:Barnabywalters|bw]] 14:44, 13 March 2014 (UTC))
* Hakan Demir marks up his Coupon and Voucher blog posts with h-entry and h-card on [http://www.gutscheinflagge.de/ gutscheinflagge.de]
* Chloe Weil marks up her blog posts with h-entry on [http://chloeweil.com/blog chloeweil.com]
* Christophe Ducamp marks up his blog posts and profile with h-entry and h-card on [http://christopheducamp.com/ christopheducamp.com]
* Glenn Jones marks up his blog posts, notes, replies, profile and comments with h-entry, h-card and h-cite on [http://glennjones.net/ glennjones.net]
* Marcus Povey marks up his blog posts and profile with h-entry and h-card on [http://www.marcus-povey.co.uk/ marcus-povey.co.uk]
* Eugen Busoiu marks up his web profile with h-card on [http://eugenbusoiu.com/#utm_source=microformats2&utm_medium=h-card&utm_campaign=Microformats eugenbusoiu.com]]
* Matthias Pfefferle marks up his blog posts, comments and profile with h-card, h-cite and h-entry on [http://notizblog.org/ notizblog.org]
* Kyle Mahan marks up his profile and notes with h-card and h-entry on [http://kylewm.com/ kylewm.com]
* Emil Björklund marks up his blog posts with h-entry and h-card ([http://thatemil.com/blog/2013/09/16/webmentioning-adactio/ example])
* App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 ([https://alpha.app.net/voidfiles example])
* Brett Comnes marks up his posts with h-entry and h-card ([http://bret.io/2013/06/29/getting-started-with-bower/ example])
* Ben Werdmuller marks up his posts with h-card and h-entry, u-in-reply-to and u-like ([http://werd.io/view/51d5097fbed7ded0633a5956 example])
* Sandeep Shetty marks his posts up with h-card and h-entry, as well as draft u-in-reply-to and experimental u-like properties ([http://sandeep.io/101 example])
* Laurent Eschenauer marks up his posts with h-entry ([http://eschnou.com/entry/first-autonomous-flight-of-my-nodecopter-62-24992.html example])
* Tom Morris marks up his posts using h-entry ([http://tommorris.org/posts/8417 example])
* Sinolandquality marks up some of their content using h-feed and h-entry on [http://www.sinolandquality.com/Blog/?page_id=3516&utm_content=buffere4d40&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer sinolandquality.com]
* [http://www.w3.org/conf/ W3Conf 2013] uses h-event for the main event, and h-card for all the speakers and notable attendees. The h-cards make particularly good use of implied name, url, and photo properties.
* [http://wordpress.org/extend/themes/sempress SemPress] is a WordPress theme that supports h-card, h-feed/h-entry and h-as-*
* [http://the-pastry-box-project.net/ The Pastry Box Project] use h-card and h-entry markup on their homepage and individual thoughts pages
* Tom Morris uses h-card and [[XFN]] to markup [http://tommorris.org/pages/blogroll his blogroll].
* Aaron Parecki uses h-card to markup both authorship and references to people in his notes permalinks, e.g. [http://aaronparecki.com/2012/230/reply/1 2012/230/reply/1].
* [http://tantek.com/ Tantek Çelik] uses h-card, h-event, and h-entry on his home page, as well as h-entry on all post permalinks, e.g. [http://tantek.com/2012/243/t1/name-beats-title-modern-use-dubline-core-wrong-uf2 2012-243 post], with [[rel-prev]]/[[rel-next]] (if applicable) to indicate prev/next posts, and with [[rel-author]] to his home page with canonical hCard to indicate authorship.
* [http://waterpigs.co.uk/ Barnaby Walters] uses h-card on his home page, h-card, h-entry and XFN markup on his [http://waterpigs.co.uk/notes notes page].
** 2013-01-25 Barnaby Walters: <cite>[http://waterpigs.co.uk/articles/experimental-markup Experimental Markup]</cite> - describes how he's using microformats2 vocabularies: <code>h-adr</code>, <code>h-card</code>, <code>h-entry</code>, <code>h-event</code>, <code>h-geo</code>, <code>h-review</code>, and experimental vocabularies: <code>h-feed</code> (embedded for update histories), [[activity-streams]] objects <code>h-as-article</code>, <code>h-as-collection</code>, <code>h-as-note</code>, <code>h-as-update</code>, as well as experimental properties: <code>u-alternate</code> and <code>u-as-downstream-duplicate</code> (links to POSSE copies), and <code>u-in-reply-to</code> (links to content that the posts are in reply to).
* [http://tantek.com/presentations/2012/06/microformats microformats.org at 7 years] presentation with h-event and h-card markup for people and organizations.
* [http://tantek.com/presentations/2012/06/pdf2012-indieweb.html Rise of the Indie Web hCards] (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has [[microformats-2]] h-calendar and h-card markup
* WebMaker by Mozilla has [[microformats-2]] h-calendar and h-card on event search (e.g. [https://webmaker.org/en-US/events/near/?lat=45.5234515&lng=-122.6762071 search near Portland Oregon]) and event pages (e.g. [https://webmaker.org/en-US/events/192f56eb9/ IndieWebCamp 2012]).[https://twitter.com/microformats/status/212207925643587585]
* WebFWD by Mozilla has [[microformats-2]] h-card markup on [https://webfwd.org/about/experts/ experts] and [https://webfwd.org/about/team/ team] pages
* [http://indiewebcamp.com IndieWebCamp] has [[microformats-2]] h-event markup with nested h-cards for the organizers and the location.
* [https://wiki.mozilla.org/Events Mozilla Events] page has [[microformats-2]] h-event markup with attendees marked up with h-card.
* The [http://pdx.esri.com/blog/2013/10/17/introducing-mapattack/ Esri PDX Blog] has h-entry markup on all blog posts (as of 2013-10-19), and h-product markup on [http://pdx.esri.com/projects/terraformer/ project pages]

=== offline ===
* spreadly marks up share permalink pages with h-entry, as well as minimal h-cards and experimental p-like properties

== Implementations ==
{{new}} Test your microformatted web page with:
=== Live Textarea Input ===
Use any of these to enter HTML+microformats2 markup and see the parsed result!
* http://glennjones.net/tools/microformats/
* https://pin13.net/mf2/ (where it says "Microformats Parser")
* https://kylewm.com/services/mf2

=== Blogging tools ===
* '''Storytlr''' parses the 'target' from [http://indiewebcamp.com/pingback pingbacks] for [https://github.com/storytlr/storytlr/blob/master/protected/application/public/controllers/PingbackController.php#L63 h-entry with properties and nested h-card] for information to automatically display in the [http://eschnou.com/entry/testing-indieweb-federation-with-waterpigscouk-aaronpareckicom-and--62-24908.html comments section on a post].

=== Converters ===
* '''[https://github.com/snarfed/granary granary]''' is a library and REST API that converts between silo APIs, [[ActivityStreams]], [[microformats2]], and Atom (all directions). Supported silos include Facebook, Twitter, Instagram, Google+, and Flickr. Users include [http://brid.gy/ Bridgy], [http://reader.kylewm.com/ Woodwind], and [https://facebook-atom.appspot.com/ facebook-atom] and [https://twitter-atom.appspot.com/ twitter-atom], among others.

* '''[http://pipes.yahoo.com/pipes/pipe.info?_id=afc5568b4e8643bfb05436b1caaf91bc microformats to RSS]''' - a Yahoo! pipe that converts a URL containing an [[h-feed]] containing h-entries, into an [[RSS]] feed ([http://waterpigs.co.uk/notes/4SeNi5/ 2013-10-21 blog post announcing])

* '''[https://xray.p3k.io XRay]''' ([https://github.com/aaronpk/XRay source code]) - Returns a normalized representation of the microformats data at a URL

=== Parsers ===
Parsers, open source libraries, in alphabetical order by programming language:

==== Parsers in production ====
The following parsers are of very high quality, in active development, and use on live sites on the web in production.

===== Java =====
* [[any23]] Apache Any23 (Anything to Triples)] a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents: http://any23.apache.org

===== Javascript =====
* '''microformats-parser''' for both browser and node.js
** github open source: https://github.com/aimee-gm/microformats-parser (current)
** live: https://aimee-gm.github.io/microformats-parser/

Previously:
* '''microformat-node''' Node.js microformats2 parser
** github open source: https://github.com/microformats/microformat-node (current)
*** forked from https://github.com/glennjones/microformat-node
** test suite: https://github.com/microformats/tests

** command line: https://github.com/JerrySievert/mf2
* '''microformat-shiv''' - cross browser javascript microformats2 parser which can also be used in browser extensions.

** github open source: https://github.com/glennjones/microformat-shiv

===== PHP =====
* '''<span id="php-mf2">php-mf2</span>''' - PHP microformats2 parser
** github open source: https://github.com/indieweb/php-mf2
** Packagist: https://packagist.org/packages/mf2/mf2
** live:
*** textarea entry: http://waterpigs.co.uk/php-mf2/
*** URL and textarea entry: https://pin13.net/mf2/
** [https://github.com/barnabywalters/php-mf-cleaner mf-cleaner]: functions for working with the raw mf2 data structure

===== Python =====
* '''mf2py''' Python microformats2 parser
** main entry: [[mf2py]]
** github open source: https://github.com/tommorris/mf2py
** live:
*** URL entry: [https://mf2py.herokuapp.com/ mf2py.herokuapp.com]
*** textarea entry: https://kartikprabhu.com/connection/mfparser
*** another textarea: http://www.unmung.com/?html=
*** URL and/or textarea: https://kylewm.com/services/mf2

===== Ruby =====
* '''indieweb/microformats-ruby''' Ruby microformats parser
** github open source: https://github.com/indieweb/microformats-ruby
** live text entry: https://microformats-parser-ruby.herokuapp.com

===== Haskell =====
* '''myfreeweb/microformats2-parser''' Haskell microformats2 parser
** github open source: https://github.com/myfreeweb/microformats2-parser
** live textarea entry: https://unrelenting.technology/mf2/

==== Development parsers ====
The following parsers are in-development and have key microformats2 functionality yet are incomplete, not fully tested, or have other limitations. Contributions welcome!

===== Erlang =====
* '''hazybluedot/mf2erl''' Erlang microformats2 parser
** github open source: https://github.com/hazybluedot/mf2erl

===== Elixir =====
* '''ckruse/microformats-elixir''' Elixir microformats2 parser
** github open source: https://github.com/ckruse/microformats2-elixir

===== Go =====
* '''willnorris/microformats''' Golang microformats2 parser
** github open source: https://github.com/willnorris/microformats
** live textarea entry: https://go.microformats.io/

===== Java =====
* '''Apache Any23''' a library, a web service and a command line tool that extracts structured data in RDF format from a variety of Web documents. Supports Microformats1 and 2.
** Download recent release: http://any23.apache.org/download.html
** live: http://any23-vm.apache.org/
** source: http://any23.apache.org/build-src.html
* '''mf2j''' An early-stage Java microformats2 parser
** github open source: https://github.com/kylewm/mf2j
** live: https://mf2j.herokuapp.com/?url={http://example.com}

===== Perl =====
* '''Web::Microformats2''' Perl microformats2 parser
** https://metacpan.org/pod/Web::Microformats2
** open source: https://github.com/jmacdotorg/microformats2-perl

==== Experiments ====
Experiments and other proof of concept microformat2 parsing support.
* '''Rust''' - https://gitlab.com/maxburon/microformats-parser
* ...

=== Outreach ===
* [https://github.com/mozilla/fathom/issues/42 Mozilla Fathom: examples with nested classes, e.g. microformats2]

== Presentations ==
Presentations about microformats2:
* 2013-01-24 <cite>[http://waterpigs.co.uk/presentations/microformats-2/ Microformats 2]</cite> presentation by [[User:Barnabywalters|Barnaby Walters]] at the [[events/2013-01-24-exeter-web-meetup|Exeter Web Meetup]] in Devon, UK.
* 2012-09-21 <cite>[http://tantek.com/presentations/2012/09/microformats2/ microformats2 & bits of HTML5: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-09-21-refreshlx|RefreshLX]] in Lisbon, Portugal.
* 2012-07-21 <cite>[http://tantek.com/presentations/2012/07/html5-uf2/ HTML5 and microformats2: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-07-21-cascadesf|Innovators of the Web conference]] in San Francisco, CA.
* 2012-07-14 <cite>[http://tantek.com/presentations/2012/07/html5-microformats2/ HTML5 and microformats2: The Evolution Of Web Data]</cite> presentation by [[User:Tantek|Tantek Çelik]] ([http://twitter.com/t @t]) at [[events/2012-07-14-open-web-camp-4|Open Web Camp IV]] in San Jose, CA.

== Testimonials ==
* <blockquote class="twitter-tweet">To prove the web standards community can come up with better standards than the SE’s, compare this: http://microformats.org/wiki/microformats-2 with schema . org — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298907685452124160 2013-02-05 13:35]</blockquote>
* <blockquote class="twitter-tweet">... I’m hoping SE’s will pick up microformats2. It’s SO much cleaner. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298911287117758464 2013-02-05 13:49]</blockquote>
* <blockquote class="twitter-tweet">... But damn Microformats2 are sexy. — Joost de Valk (@yoast) [https://twitter.com/yoast/status/298912179292344320 2013-02-05 13:53]</blockquote>

== Origins ==
This page was originally used to brainstorm and develop microformats2 in an exploratory manner, with problem statements, questions, lessons learned from past and other formats.

Now that [[microformats2-parsing]] is a Microformats specification, the original brainstorming has been moved to a separate page for anyone who wants to understand more about how we came up with the design of microformats2, and how it evolved in the early years.
* [[microformats2-origins]]

== See Also ==
* [[microformats2]]
* [[microformats2-brainstorming]] - moving more experimental / undeveloped / and rejected thoughts ideas here to simplify/progress *this* page further.
* [[microformats2-experimental-properties]] - listing experimental (-x- prefixed) properties and their use
* [[microformats2-prefixes]]
* [[vendor-prefixes]]
* [[microformats2-faq]]
* [[microformats2-parsing]]
* 2010-05-02 [[events/2010-05-02-microformats-2-0|microformats 2.0 discussion session at FOO East]]

html5-fr

2023-07-26T21:28:22Z

GRegorLove: s/<source>/<syntaxhighlight>/

''Cette page a démarré sur [[html5]]. Traduction en cours.''

{{DISPLAYTITLE:Microformats en HTML 5}}

''Cette page est destinée à documenter l'usage '''futur''' des microformats en [http://www.w3.org/html/wg/html5 HTML 5]. Aucun des items documentés ne sont supportés à cette heure, et ils pourront changer pour un développement dans la communauté des microformats, ou selon les modifications dans la spécification HTML5. Cette page est destinée à suivre les améliorations offertes par HTML5 pour les microformats, et les problématiques que soulève HTML5. Elle peut être utilisée pour suivre les questions qui ont besoin d'être poussées dans le processus de développement du HTML5.''

S'il y a des choses que les Microformats aimeraient marquer qui ne sont pas gérées explicitement par HTML5, faites-le savoir svp au WHATWG, de façon à ce que nous puissions améliorer HTML5. Voici par exemple, comment le a émergé <code>time</code>.

==Nouvelles fonctionnalités dans le HTML5==
=== élément time ===
* L'élément '''<code>time</code> pour représenter les dates-heures'''. En HTML5, le format machine des dates-heures peut être représenté nativement. Dans certains cas, il peut être possible de remplacer le modèle de design date-time avec du HTML5 natif.

* Recommandation : Utilisez le [[value-class-pattern-fr|modèle-de-classe-value]], tout particulièrement et de préférence avec <strong>séparation-date-heure</strong> pour marquer les dates et heures avec accessibilité tout en suivant le [[principle-fr|principe]] <abbr title="Don't Repeat Yourself">DRY</abbr> autant que possible.

* Les [[parsers#HTML::Microformats|HTML::Microformats]] et ses prédécesseurs ont supporté l'élément <code>time</code> depuis juillet 2008.

* Essayez http://dev.h2vx.com/ (version beta de [[H2VX-fr|H2VX]]) car elle a désormais un support préliminaire pour <code><time datetime></code> tout comme pour les nouveaux éléments sémantiques HTML5.

Note : des propositions ont été [http://wiki.whatwg.org/wiki/Time documentées pour augmenter l'élément time]. Ajoutez SVP des opinions supplémentaires et des cas d'usages à cette page wiki de manière à ce que nous puissions améliorer l'élément time.

Il a existé rapidement un attribut optionnel <code>pubdate</code> pour indiquer la date de publication d'un <code>article</code>, mais il a été abandonné en 2012 parce qu'il était à la fois non nécessaire et insuffisant. Plutôt que d'utiliser l'attribut pubdate, il est mieux de faire ainsi :
* Utilisez le microformat [[hatom-fr|hAtom]] pour les articles, et la propriété hAtom <code>published</code>, tout comme la propriété hAtom <code>updated</code>.

==== hCalendar avec élément time ====
Voici un [[hcalendar-fr#Exemples|un exemple de spec hCalendar]] mis à jour pour utiliser section au lieu de div, et time au lieu de abbr.

<syntaxhighlight lang="html">
<section class="vevent">
<a class="url" href="http://conferences.oreillynet.com/pub/w/40/program.html">
http://conferences.oreillynet.com/pub/w/40/program.html
</a>
<span class="summary">Web 2.0 Conference</span>:
<time class="dtstart" datetime="2005-10-05">5 octobre</time>-
<time class="dtend" datetime="2005-10-07">7</time>,
at the <span class="location">Argent Hotel, San Francisco, CA</span>
</section>
</syntaxhighlight>

=== élément article ===
L'élément '''<code>article</code>''' pour des compositions majeures, indépendantes de contenu dans une page. Peut-être synonyme avec [[hatom-fr|hAtom]] <code>hentry</code>. Pourrait être parsé sous <code>hentry</code> dans des blocs explicites <code>hfeed</code> ?

=== attributs data ===
'''La convention de nommage <code>data-</code> pour les attributs de tag'''. la spécification draft déclare qeu tout attribut qui démarre avec "data-" sera traité comme une aire de stockage pour la data privée.
* Notez que le truc data-* n'est explicitement <em>pas</em> pour les microformats. Ces attributs sont définis de telle sorte que les navigateurs ne feront jamais rien de spécial avec eux. Ils sont conçus pour les auteurs de scripts qui disposent d'un espace dans lequel ils peuvent jouer sans même rencontrer quelque conflit avec tout ce que peut faire le navigateur. Il peut y avoir des cas de [[poshformats]] privés qui ne sont jamais conçus pour l'interchagement qui peuvent être utilisés dans les attributs data-*.

=== nouveaux éléments sémantiques ===
HTML5 a de nombreux et nouveaux éléments sémantiques.

La plupart des [[parsers-fr|parseurs]] microformats ne reconnaîtront probablement pas ces éléments et peuvent les ignorer - ainsi évitez d'utiliser les classes microformats sur de nouveaux éléments sémantiques HTML5 en production.

NÉANMOINS, essayez vraiment d'expérimenter avec des microformats et le nouveau HTML5 sémantique,

ET essayez http://dev.h2vx.com/ (la version beta de [[H2VX-fr|H2VX]]) parce qu'il a maintenant un support préliminaire pour les nouveaux éléments sémantiques HTML5 tout comme <code><time datetime></code>.

== Modifications en HTML5 ==
=== Les attributs rel/rev ===
L'attribut <code>rev</code> a été retiré du HTML5. L'attribut <code>rel</code> peut encore être utilisé de la même façon, mais les microformats qui supposaient l'existence de <code>rev</code> et par conséquent définissait uniquement une relation unique, peuvent avoir besoin d'être changés pour inclure tout aussi bien une relation inverse. Ce qui veut dire, pour chaque relation qui va dans une direction (par ex. [[rel-parent]] de [[xfn)-fr|xfn]]), vous devez nommer explicitement et définir la relation inverse (par ex. [[rel-child]] de [[xfn-fr|xfn]]) si la relation inverse est vraiment utile.

== Additions au delà du HTML5 ==
=== microdata ===
{{main|microdata}}
'''[[microdata]]''' est une extension du HTML5 qui fournit un ensemble d'attributs et des APIs DOM associées pour marquer sémantiquement et extraire les data du contenu existant dans les pages web, similaire aux microformats mais avec de nouveaux attributs.

== compatibilité actuelle microformat ==
Il ne semble pas y avoir de problème avec l'implémentation des microformats suivants en HTML5 :
* [[hcard-fr|hcard]]
* [[xfn-fr|xfn]]

== Requêtes ==
* "Comment utiliser avec HTML5" des sections qui comprennent (a) des exemples de microformats qui utilisent [[HTML5-fr|HTML5]], et (b) des détails de parsage microformats qui spécifient quoi faire (si quelque chose de spécial est requis) avec les éléments HMTL5 (par ex. comment parser l'élément <code>time</code> pour les dates et heures pour les microformats). Voir (et ajoutez si nécessaire) :
** [[hcard-brainstorming#how_to_use_with_HTML5|hCard brainstorming - how to use with HTML5]]
** [[hcalendar-brainstorming#how_to_use_with_HTML5|hCalendar brainstorming - how to use with HTML5]] e.g. hCalendar with the <code>time</code> element
** [[citation-brainstorming#how_to_use_with_HTML5|citation brainstorming - how to use with HTML5]]
** si rien de spécial n'est requi pour HTML5, alors après avoir exécuté l'analyse, ceci devrait être noté pour des besoins de clarté.

==Problématiques ==
<div class='discussion issues'>
* '''The <code>profile</code> attribute has been removed'''. In HTML, the <code>profile</code> attribute from the <code>head</code> has been removed, with no direct replacement. This causes issues for GRDDL support. It's been suggested that profile URLs be represented in <code>link</code> elements instead, or even as a custom HTTP header. See [[grddl]] and [[profile-uris]]
** See [[rel-profile]] which is the replacement for the profile attribute. [[User:Tantek|Tantek]] 23:24, 5 November 2009 (UTC)
* '''Microdata <code>itemprop</code> duplicates <code>class</code> data'''. the new attribute itemprop is designed to hold some meaningful data about an element, but class already exists to hold this data. Unsure of reasons why itemprop required?
** This is because microdata is designed to be generically parsable, even when the parser does not understand the vocabulary. As such, property names have to be on an explicit attribute, not shared with other, non-data classnames. --[[User:BenWard|BenWard]] 21:12, 4 September 2009 (UTC)
* '''The [http://microformats.org/wiki/value-class-pattern#Date_and_time_parsing recommended removal of the colon in timezone] doesn’t validate''' The relevant uF wiki text is “However the colons ":" separating the hours and minutes of any timezone offset are optional and discouraged in order to make it less likely that a timezone offset will be confused for a time.” ref: [http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#global-dates-and-times HTML5 time microsyntax for <time>] --[[User:Oli|Oli]] 14:40, 14 February 2010 (+9)
* '''Some websites are not ready to upgrade to HTML5''' and must stick with HTML4 (or XHTML1 served/interpreted as HTML4) for now. For example:
** http://www.ascentsir.com/eng - according to [[IRC]] "ChiefRA" on 2011-06-30
</div>

== voir aussi ==
* [[HTML3]]

html5

2023-07-26T21:27:28Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:Microformats in HTML5}}

''This page is to document '''future''' use of microformats in [http://www.w3.org/html/wg/html5 HTML5]. None of the items documented are supported now, and may change upon proper development within the microformats community, or changes in the HTML 5 specification. This page is to track HTML5 enabled enhancements to microformats, and issues that HTML5 raises. It may be used to track issues which we need to push back into the HTML 5 development process.''

If there are things that microformats would like to mark up that aren't handled by HTML5 explicitly, please let the WHATWG know, so we can improve HTML5. This is how the <code>time</code> element came to be, for instance.

==New features in HTML5==

=== time element ===
'''<code>time</code> element for representing date times'''. In HTML5, the machine form of datetimes can be represented natively. In some cases it may be possible to replace the date-time design pattern with native HTML5.

* Recommendation: Use the [[value-class-pattern]], in particular preferably <strong>date-time-separation</strong> for accessibly marking up dates and times while following the <abbr title="Don't Repeat Yourself">DRY</abbr> [[principle]] as much as possible.

* [[parsers#HTML::Microformats|HTML::Microformats]] and its predecessors have supported the <code>time</code> element since July 2008.

* Try http://dev.h2vx.com/ (the beta version of [[H2VX]]) as it now has preliminary support for <code><time datetime></code> as well as the new semantic HTML5 elements.

Note: that there are documented [http://wiki.whatwg.org/wiki/Time proposals to extend the time element]. Please add additional opinions and use cases to that wiki page so that we can help improve the time element.

There was briefly an optional <code>pubdate</code> attribute, to indicate the publication date of an <code>article</code>, but it was dropped in 2012 since it is both unnecessary and insufficient. Rather than use the one-off pubdate attribute, it's much better to:
* Use the [[hAtom]] microformat for articles, and the hAtom <code>published</code> property, as well as the hAtom <code>updated</code> property.

==== hCalendar with time element ====
Here is the [[hcalendar#Examples|hCalendar spec example]] updated to use section instead of div, and time instead of abbr.

<syntaxhighlight lang="html">
<section class="vevent">
<a class="url" href="http://conferences.oreillynet.com/pub/w/40/program.html">
http://conferences.oreillynet.com/pub/w/40/program.html
</a>
<span class="summary">Web 2.0 Conference</span>:
<time class="dtstart" datetime="2005-10-05">October 5</time>-
<time class="dtend" datetime="2005-10-07">7</time>,
at the <span class="location">Argent Hotel, San Francisco, CA</span>
</section>
</syntaxhighlight>

=== article element ===
'''<code>article</code>''' element for major, independent compositions of content within a page. Perhaps synonymous with [[hAtom]] <code>hentry</code>. Could be parsed as <code>hentry</code> within explicit <code>hfeed</code> blocks?

=== data attributes ===
'''<code>data-</code> naming convention for tag attributes'''. the draft specification states that any attribute that starts with "data-" will be treated as a storage area for private data.
* Note that the data-* stuff is explicitly <em>not</em> for microformats. Those attributes are defined in such a way that browsers will never do anything special with them, ever. They are intended for script authors to have a space in which they can play without ever clashing with anything the browser does. There may be some cases of private [[poshformats]] that are never intended for interchange that may be used in data-* attributes.

Since data-* attributes are not for general data interchange or generic APIs supported by multiple sites / pieces of software, what are actual valid uses of data-* attributes? One example (feel free to add more)
* Twitter's use of data-* attributes in markup to be picked up only by Twitter's javascript [https://dev.twitter.com/docs/tweet-button library for Tweet buttons], e.g. <code>data-related="indiewebcamp"</code> - indicates [https://twitter.com/indiewebcamp @indiewebcamp] is a related Twitter account for a tweet button.

=== new semantic elements ===
HTML5 has numerous new semantic elements.

Most microformats [[parsers]] probably won't recognize those elements and may ignore them - so avoid using microformats classes on new HTML5 semantic elements for anything in production.

HOWEVER, do try experimenting with microformats and new semantic HTML5,

AND try http://dev.h2vx.com/ (the beta version of [[H2VX]]) as it now has preliminary support for the new semantic HTML5 elements as well as <code><time datetime></code>.

== Changes in HTML5 ==
=== The rel/rev attributes ===
The <code>rev</code> attribute has been removed from HTML5. The <code>rel</code> attribute can be still be used in the same way, but microformats that assumed the existence of <code>rev</code> and thus only defined a single forward-facing relation may need to be changed to include an opposite relation as well. That is, for every relation that goes in one direction (e.g. [[rel-parent]] of [[xfn]]), you must explicitly name and define the inverse relationship (e.g. [[rel-child]] of [[xfn]]) if the inverse relation is indeed useful.

== Additions beyond HTML5 ==
=== microdata ===
{{main|microdata}}
'''[[microdata]]''' is an extension to HTML5 that provides a set of attributes and associated DOM APIs for semantically marking up and extracting data from existing content in web pages, similar to microformats but with new attributes.

== Current microformat compatibility ==
There seems to be no issue with current implementation of the following microformats in HTML 5:
* [[hcard]]
* [[xfn]]

== Requests ==
* "how to use with HTML5" sections that include (a) microformats examples that use [[HTML5]], and (b) microformats parsing details that specify what to do (if anything special is required) with HTML5 elements (e.g. how to parse the <code>time</code> element for dates and times for microformats). See (and add to if necessary) :
** [[hcard-brainstorming#how_to_use_with_HTML5|hCard brainstorming - how to use with HTML5]]
** [[hcalendar-brainstorming#how_to_use_with_HTML5|hCalendar brainstorming - how to use with HTML5]] e.g. hCalendar with the <code>time</code> element
** [[citation-brainstorming#how_to_use_with_HTML5|citation brainstorming - how to use with HTML5]]
** if nothing special is required for HTML5, then after performing the analysis, that should be noted as well, for the purpose of clarity.

==Issues==
<div class='discussion issues'>
* '''The <code>profile</code> attribute has been removed'''. In HTML, the <code>profile</code> attribute from the <code>head</code> has been removed, with no direct replacement. This causes issues for GRDDL support. It's been suggested that profile URLs be represented in <code>link</code> elements instead, or even as a custom HTTP header. See [[grddl]] and [[profile-uris]]
** See [[rel-profile]] which is the replacement for the profile attribute. [[User:Tantek|Tantek]] 23:24, 5 November 2009 (UTC)
* '''Microdata <code>itemprop</code> duplicates <code>class</code> data'''. the new attribute itemprop is designed to hold some meaningful data about an element, but class already exists to hold this data. Unsure of reasons why itemprop required?
** This is because microdata is designed to be generically parsable, even when the parser does not understand the vocabulary. As such, property names have to be on an explicit attribute, not shared with other, non-data classnames. --[[User:BenWard|BenWard]] 21:12, 4 September 2009 (UTC)
* '''The [http://microformats.org/wiki/value-class-pattern#Date_and_time_parsing recommended removal of the colon in timezone] doesn’t validate''' The relevant uF wiki text is “However the colons ":" separating the hours and minutes of any timezone offset are optional and discouraged in order to make it less likely that a timezone offset will be confused for a time.” ref: [http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#global-dates-and-times HTML5 time microsyntax for <time>] --[[User:Oli|Oli]] 14:40, 14 February 2010 (+9)
* '''Some websites are not ready to upgrade to HTML5''' and must stick with HTML4 (or XHTML1 served/interpreted as HTML4) for now. For example:
** http://www.ascentsir.com/eng - according to [[IRC]] "ChiefRA" on 2011-06-30
</div>

== see also ==
* [[HTML3]]

h-adr-fr

2023-07-26T21:26:19Z

GRegorLove: s/<source>/<syntaxhighlight>/

''Cette page a démarré sur [[h-adr]]''

{{DISPLAYTITLE:h-adr}}
* <span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editeur</span>)</span>
* <span class="h-card vcard"><span class="p-name fn">[[User:ChristopheDucamp|Christophe Ducamp]]</span> (<span class="p-role role">Traducteur</span>)</span>

----
<dfn style="font-style:normal;font-weight:bold">h-adr</dfn> est un format simple, ouvert pour publier des endroits structurés tels que des adresses, physiques et/ou postales. h-adr est l'un des nombreux standards ouverts [[microformats|microformat]] draft adaptés pour embarquer de la data en HTML/HTML5 sur le web.

h-adr est la mise à jour [[microformats-2-fr|microformats-2]] de [[adr-fr|adr]]. Il est le plus communément utilisé comme partie d'une [[h-card-fr|h-card]] ou d'un [[h-event-fr|h-event]].

== Exemple ==
Voic un exemple simple d'adresse postale :

<syntaxhighlight lang="html">
<p class="h-adr">
<span class="p-street-address">17 Austerstræti</span>
<span class="p-locality">Reykjavík</span>
<span class="p-country-name">Iceland</span>
<span class="p-postal-code">107</span>
</p>
</syntaxhighlight>

=== Pour démarrer ===
La classe '''<code>h-adr</code>''' est un ''nom de classe racine'' qui indique la présence d'un h-adr.

'''p-street-address''', '''p-locality''', '''p-country-name''', '''p-postal-code''' et tous les autres noms de classes propriétés listés ci-dessous définissent les propriétés d'un h-adr.

Voir [[microformats-2-parsing-fr|microformats-2-parsing]] pour en savoir plus sur les noms de classes propriétés.

== Propriétés ==
Les propriétés h-adr, dans un élément avec la classe '''h-adr''' :
* '''<code>p-street-address</code>''' - numéro de maison/appartement, étage, nom de rue
* '''<code>p-extended-address</code>''' - détails additionnels sur la rue
* '''<code>p-post-office-box</code>''' - numéro de boîte postale
* '''<code>p-locality</code>''' - ville/village/localité
* '''<code>p-region</code>''' - état/pays/province
* '''<code>p-postal-code</code>''' - code postal, par ex. ZIP aux USA
* '''<code>p-country-name</code>''' - nom du pays
* '''<code>p-label</code>''' - une étiquette de mailing, en plein texte, peut-être avec pré-formatage
* '''<code>p-geo</code>''' (ou u-geo avec un geo RFC 5870 : URL), embarqué optionnellement avec [[h-geo]]
* '''<code>p-latitude</code>''' - latitude en décimales
* '''<code>p-longitude</code>''' - longitude en décimales
* '''<code>p-altitude</code>''' - altitude en décimales - nouveau dans vCard4 (RFC6350)

Toutes les propriétés sont optionnelles.

== Statut ==
'''h-adr''' est une spécification draft microformats. La discussion publique sur h-adr à lieu sur [[h-adr-feedback]], le canal [[irc]] #microformats sur irc.freenode.net, et la [http://microformats.org/discuss/mail/microformats-new/ microformats-new liste de diffusion]].

h-adr est prêt à être utilisé et implémenté dans la jungle, mais pour de la rétro-compatibilité, vous devriez aussi marquer et enrichir les h-adrs avec les noms de classes [[adr]].

== Détails de propriété ==
(ébauche, ajoutez ici toutes les explications de propriétés)

== Exemples dans la jungle ==
* … ajouter ici tout exemple que vous trouverez dans la jungle

{{h-spec-section-validating}}

== Rétro-compatibilité ==
=== Compatibilité pour Auteurs ===
Pour une rétro-compatibilité, vous pourriez vouloir utiliser les noms de classes classiques [[adr-fr|adr]] en plus des propriétés futures h-adr, par exemple :

<syntaxhighlight lang="html">
<p class="h-adr adr">
<span class="p-street-address street-address">123 rue Principale.</span>,
<span class="p-locality locality">VilleSympa</span>
...
</p>
</syntaxhighlight>

Le '''<code>adr</code>''' est un ''nom de classe racine rétro-compatible'' qui indique la présence d'un [[adr-fr|adr]].

'''street-address''', '''locality''', et tous les noms de classes propriétés rétro-compatibles sont listés en dessous.

=== Compatibilité Parseurs ===
Les parseurs microformats devraient détecter les propriétés classiques et les parser comme des propriétés microformats-2. SI un "h-adr" est trouvé, ne pas chercher un "adr" sur le même élément.

Le nom de classe racine compatible : adr

Les propriétés : (parsées comme p - plein texte à moins qu'autre chose ne soit spécifié)

* post-office-box
* extended-address
* street-address
* locality
* region
* postal-code
* country-name

== Historique==
h-adr est basé sur la spécification [[adr-fr|adr]], qui a été extraite de [[hcard-fr|hCard]] afin de l'autoriser à être utilisé pour des applications autres que l'information de contact.

== Voir aussi ==
* [[microformats2-fr|microformats-2]]
* [[h-geo-fr|h-geo]] peut être embarqué dans h-adr
* [[h-card-fr|h-card]] et [[h-event-fr|h-event]] contiennent souvent h-adr

[[Category:Draft Specifications]]

h-review-aggregate

2023-07-26T21:24:57Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{stub}}

This page is a placeholder for the [[h-review-aggregate]] specification, an upgrade of [[hReview-aggregate]] to [[microformats2]]. Please refer to the [[#Todo]] section.

----
{{DISPLAYTITLE:h-review-aggregate}}
<dfn style="font-style:normal;font-weight:bold">h-review-aggregate</dfn> is a simple, open format for embedding review information (of products, services, businesses, etc). Whereas [[h-review]] is intended for an individual review, h-review-aggregate is meant for summary information about a collection of user or critic reviews about an item.

h-review-aggregate is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML and is the [[microformats2]] update to [[hReview-aggregate]].

;<span id="Status">Status</span>
:This is a '''Draft Specification'''.
;Participate
:[[IRC]]: [irc://irc.libera.chat/microformats #microformats on Libera]
<div class="p-author h-card vcard">
;<span class="p-role role">Editor</span>
:<span class="p-name fn">[[User:GRegorLove|gRegor Morrill]]</span>
</div>
;License
: {{cc0-owfa-license}}
__TOC__

== Example ==
Here is a simple example showing aggregate review information for a restaurant:

<syntaxhighlight lang="html">
<article class="h-review-aggregate">
<h1 class="p-item">Mediterranean Wraps</h1>
<p class="p-name">Customers flock to this small restaurant for their
tasty falafel and shawerma wraps and welcoming staff.</p>
<span class="p-average">4.5</span> out of 5
based on <span class="p-count">17</span> reviews
</article>
</syntaxhighlight>

== Properties ==
=== Proposed Properties ===
Proposed properties from [[hReview-aggregate]] awaiting citations of publishing and consuming examples.

* '''<code>p-item</code>''' - Required: the 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-average</code>''' - Required: the fixed point integer [1.0-5.0] of the average rating (5.0 best)
* '''<code>p-best</code>''' - Optionally define best rating value. can be numerically lower than worst.
* '''<code>p-worst</code>''' - Optionally define worst rating value. can be numerically higher than best.
* '''<code>p-count</code>''' - the total number of reviews
* '''<code>p-votes</code>''' - the total number of users who have rated the product or service, contributing to the average rating. For some sites, the number of votes is equal to the number of reviews, so <code>count</code> may be used and this property omitted.
* '''<code>p-name</code>''' - This optional property can be the title for the review collection or a very short summary of the consensus opinion from the collection.

== Property Details ==

== Examples in the wild ==
Add any h-review-aggregate examples you find in the wild:

* [https://breakfastand.coffee Breakfast and Coffee] publishes h-review-aggregate on pages that aggregate all of the reviews for a coffee shop or eatery. The h-review-aggregate is updated automatically when a new, valid h-review [https://indieweb.org/Webmention Webmention] is sent to the page.
** Example: https://breakfastand.coffee/Fortitude_Coffee_-_Newington_Road_-_Edinburgh

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

== Implementations ==

== Backward Compatibility ==
=== Parser Compatibility ===
This is a '''draft''' based on reviewing [[hreview-aggregate-examples-in-wild#Reviewed_Examples|hReview-aggregate examples]], pending parser implementations and feedback.

Microformats parsers {{should}} detect classic properties only if a classic root class name is found and parse them as microformats2 properties.

If an <code>h-review-aggregate</code> is found, don't look for an <code>hreview-aggregate</code> on the same element.

Compat root class name: <code id="hreview-aggregate">hreview-aggregate</code><br>
Properties: (parsed as '''p-''' plain text unless otherwise specified):

* <code>item</code> - parse as '''<code>p-item</code>'''
* <code>average</code> - parse as '''<code>p-average</code>'''
* <code>best</code> - parse as '''<code>p-best</code>'''
* <code>worst</code> - parse as '''<code>p-worst</code>'''
* <code>count</code> - parse as '''<code>p-count</code>'''
* <code>votes</code> - parse as '''<code>p-votes</code>'''
* <code>summary</code> - parse as '''<code>p-name</code>'''

==== Notes ====
Based on [[hreview-aggregate-examples-in-wild#Reviewed_Examples|hReview-aggregate examples]], this is how many times each property appeared.

<pre>item: 10
rating: 10
average: 8
best: 8
count: 5
votes: 5
worst: 0
summary: 0</pre>

== Todo ==
Tasks for this page.

In summary:
* copy [[h-review]]
* use root class name "h-review-aggregate" instead of "h-review"
* add "p-count", "p-votes" properties as defined in [[hReview-aggregate]]
* prune set of properties to those listed in [[hReview-aggregate]]
* change backcompat parsing for root class name to "hreview-aggregate"
* change backcompat parsing property class names to those listed in [[hReview-aggregate]]

== See Also ==
* [[microformats2]]
* [[h-review]]
* [[hReview-aggregate]]

h-review

2023-07-26T21:23:50Z

GRegorLove: s/<source>/<syntaxhighlight>/

<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]].

;<span id="Status">Status</span>
:This is a '''Draft Specification'''
;Participate
:[[IRC]]: [irc://irc.libera.chat/microformats #microformats on Libera]
;Editor
:<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
;License
:{{cc0-owfa-license}}
__TOC__

== Example ==
Here is a simple review example:

<syntaxhighlight lang="html">
<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>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="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>"
}
]
}
}
]
}
</syntaxhighlight>

=== Get started ===
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-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-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.

== Properties ==
h-review properties, inside an element with class '''h-review''':

* '''<code>p-name</code>''' - name of the review
* '''<code>p-item</code>''' - thing being reviewed, including embedded microformat for e.g. business or person ([[h-card]]), event ([[h-event]]), place ([[h-adr]] or [[h-geo]]), product ([[h-product]]), recipe ([[h-recipe]]), website, url, or other item ([[h-item]]).
* '''<code>p-author</code>''' - person who authored the review, optionally with an embedded [[h-card]]
* '''<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-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>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>u-url</code>''' - 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]]:

* '''<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 ==
'''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 ==
* … 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}}

== 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:

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

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 ===
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)

* <code>summary</code> parse as '''<code>p-name</code>'''
* <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</code> (without vcard, vevent, hproduct) - parse as '''p-item h-item''' including backcompat nested properties:
** <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>best</code>
* <code>worst</code>
* <code>description</code> - parse as '''e-content'''
* <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.

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 ==
h-review is based on the existing [[hReview]] specification.

== See Also ==
* [[microformats2]]
* [[h-card]]
* [[h-event]]
* [[h-adr]]
* [[h-geo]]
* [[h-product]] can all be embedded in h-review as the p-item
* [[h-item]] is a minimal microformat in case none of the others suitably represent the item being reviewed

[[Category:Draft Specifications]]

h-item

2023-07-26T21:22:21Z

GRegorLove: s/<source>/<syntaxhighlight>/

<dfn style="font-style:normal;font-weight:bold">h-item</dfn> is a simple, open format for publishing details about arbitrary items. h-item is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.

In practice, h-item is almost never used on its own, but rather as the '''p-item''' in an [[h-review]] if the item being reviewed cannot otherwise be represented by either an [[h-card]], [[h-product]], [[h-event]], or other specific microformat.

;<span id="Status">Status</span>
:This is a '''Draft Specification'''
;Participate
:[[IRC]]: [irc://irc.libera.chat/microformats #microformats on Libera]
;Editor
:<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
;License
:{{cc0-owfa-license}}
__TOC__

== Example ==
As the only properties defined by h-item are '''p-name''', '''u-url''' and '''u-photo''', in practice only the root class name is ever actually required thanks to [[microformats-2-implied-properties]]. Explicit properties may be needed for unusual markup structures or to represent multiple values, e.g. multiple URLs, photos. etc..

<syntaxhighlight lang="html">
<a class="h-item" href="http://example.org/items/1">
<img src="http://example.org/items/1/photo.png" alt="" />
The Item Name
</a>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [
{
"type": [
"h-item"
],
"properties": {
"name": [
"The Item Name"
],
"photo": [
"http://example.org/items/1/photo.png"
],
"url": [
"http://example.org/items/1"
]
}
}
]
}
</syntaxhighlight>

== Properties ==
* '''<code>p-name</code>''' - item name
* '''<code>u-url</code>''' - permalink URL
* '''<code>u-photo</code>''' - photo URL

All properties are optional.

== Status ==

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

== Property Details ==

(stub, add any property explanations here)

== Examples in the Wild ==
* … add any h-item examples you find in the wild

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

== Background ==
h-item was extracted from the classic [[hReview]] microformat as a way of referring to arbitrary reviewed items which cannot be represented by other microformats but which required a “shell” microformat due to the flat property requirement of microformats 2.

== See Also ==
* [[microformats2]]
* [[h-review]]

[[Category:Draft Specifications]]

h-geo

2023-07-26T21:21:09Z

GRegorLove: s/<source>/<syntaxhighlight>/

<dfn style="font-style:normal;font-weight:bold">h-geo</dfn> is a simple, open format for publishing [http://en.wikipedia.org/wiki/WGS84 WGS84] geographic coordinates. h-geo is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.

h-geo is the [[microformats2]] update to [[geo]]. It is most commonly used as part of an [[h-card]] or [[h-event]].

;<span id="Status">Status</span>
:This is a '''Draft Specification'''
;Participate
:[[IRC]]: [irc://irc.libera.chat/microformats #microformats on Libera]
;Editor
:<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
;License
:{{cc0-owfa-license}}
__TOC__

== Example ==
Here is a simple h-geo example:

<syntaxhighlight lang="html">
<p class="h-geo">
<span class="p-latitude">-27.116667</span>,
<span class="p-longitude">-109.366667</span>
</p>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [
{
"type": [
"h-geo"
],
"properties": {
"latitude": [
"-27.116667"
],
"longitude": [
"-109.366667"
],
"name": [
"-27.116667, -109.366667"
]
}
}
]
}
</syntaxhighlight>

=== Get started ===
The class '''<code>h-geo</code>''' is a ''root class name'' that indicates the presence of an h-geo.

'''p-latitude''', '''p-longitude''' and '''p-altitude''' classnames define an element as a ''property'' of the h-geo.

See [[microformats2-parsing]] to learn more about property classnames.

== Properties ==
h-geo properties, inside an element with class '''h-geo''':
* '''<code>p-latitude</code>''' - decimal latitude
* '''<code>p-longitude</code>''' - decimal longitude
* '''<code>p-altitude</code>''' - decimal altitude

All properties are optional.

== Status ==

'''h-geo''' is a microformats.org draft specification. Public discussion on h-geo takes place on [[h-geo-feedback]] and the #microformats [[irc]] channel on libera.chat.

h-geo is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-geos up with classic [[geo]] classnames.

== Property Details ==

'''p-altitude''' refers to the distance in metres from the nominal sea level along the tangent of the earth’s curve, i.e. the geoid height. For more information refer to the [http://en.wikipedia.org/wiki/WGS84 WGS84] specification and the [https://en.wikipedia.org/wiki/Geo_URI_scheme geo URI scheme].

== FAQ ==

'''How should I mark up lat/long coordinates without them looking messy and confusing?'''

Unless your content is targeted at an audience with a high leg authoring '''p-latitude''' and '''p-longitude''' as plain numbers on a webpage may not be the best approach. In addition to this there may be accessibility issues due to the potentially long strings of numbers being read out.

You could present the coordinates in a more human-readable form, retaining the decimal coordinates inside data value attributes:

<syntaxhighlight lang="html">
<p class="h-geo">
<data class="p-longitude" value="-27.116667">27° 7′ 0″ S</data>,
<data class="p-latitude" value="-109.366667">109° 22′ 0″ W</data>
</p>
</syntaxhighlight>

Alternatively you could not show coordinates at all and simply show a human-readable representation of the location, with the lat/long in value attributes of empty data elements.

== Examples in the Wild ==
* … add any h-geo examples you find in the wild

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

== Backward Compatibility ==
=== Publisher Compatibility ===
For backward compatibility, you may wish to use classic [[geo]] classnames in addition to the more future-proof h-geo properties, for example:

<syntaxhighlight lang="html">
<p class="h-geo geo">
<span class="p-latitude latitude">-27.116667</span>,
<span class="p-longitude longitude">-109.366667</span>
</p>
</syntaxhighlight>

=== Parser Compatibility ===
Microformats parsers {{should}} detect classic properties only if a classic root class name is found and parse them as microformats2 properties.

If an "h-geo" is found, don't look for an "geo" on the same element.

Compatibility root class name: geo

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

* latitude
* longitude

== Background ==

h-geo is based on the [http://en.wikipedia.org/wiki/WGS84 WGS84] standard, as well as existing [[geo]] specification, which was extracted from [[hCard]] in order to allow it to be used for applications other than contact information.

== See Also ==
* [[microformats2]]
* [[h-card]] and [[h-event]] often contain h-geo
* [[h-adr]] is used to mark up human-readable structured addresses

[[Category:Draft Specifications]]

h-feed

2023-07-26T21:19:49Z

GRegorLove: s/<source>/<syntaxhighlight>/

<dfn style="font-style:normal;font-weight:bold">h-feed</dfn> is a simple, open format for publishing a stream or feed of [[h-entry]] posts, like complete posts on a home page or archive pages, or summaries or other brief lists of posts. h-feed is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.

h-feed is the [[microformats2]] update to [[hAtom]], and in particular its "hfeed" root class.

;<span id="status">Status</span>
:'''h-feed''' is a microformats.org draft specification.
:h-feed is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-feed up as a classic [[hAtom]] "hfeed".

;<span id="participate">Participate</span>
:[https://github.com/microformats/h-feed/issues Open Issues]
:[[IRC]]
;Editor
:<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
;License
: {{cc0-owfa-license}}
__TOC__

== Properties ==
h-feed properties, inside an element with class '''h-feed'''. All properties are optional.

root class name: h-feed

=== Core Properties ===
The following ''core'' h-feed properties have broad consensus:
* '''<code>p-name</code>''' - name of the feed
* '''<code>p-author</code>''' - author of the feed, optionally embed an [[h-card]] {{main|h-card}}
* '''<code>u-url</code>''' - URL of the feed
* '''<code>u-photo</code>''' - representative photo / icon for the feed

children:
* nested [[h-entry]] objects representing the items of the feed

=== Draft Properties ===
None currently.

=== Proposed Properties ===
The following properties are proposed additions based on various observed examples in the wild, but are awaiting at least one reader / real world consuming code example to become a draft property:
* '''<code>p-summary</code>''' - based on non-trivial actual content usage of "atom:subtitle" on Blogger and WordPress.com featured blogs's Atom feeds.
* '''<code>p-entry</code>''' - to be more consistent with the cascading of p-author or [http://microformats.org/wiki/comment-brainstorming#Proposal p-comment].

== Proposed Additions ==

* Proposal that h-feed not be limited to h-entry, due use cases for feeds of h-cards or h-events https://github.com/microformats/h-feed/issues/3
* Proposal to add implied h-feed in cases where no h-feed is explicitly marked up. https://github.com/microformats/h-feed/issues/1

== Discovery ==
Implementations may discover one or more h-feeds in several ways.

* If the implementation is given a URL (e.g. from a user entering it) to do h-feed discovery, it:
** SHOULD do traditional feed discovery by looking through link elements with a rel value of "alternate"
** For each link alternate with a media type of <code>[https://indieweb.org/text/mf2%2Bhtml text/mf2+html]</code>
**# get its href,
**# do any relative-URL resolution needed on that href to construct an absolute URL
**# fetch that absolute URL and [[microformats2-parsing|parse it]] (within a specific element matching a fragment in the URL if any) for microformats2 items,
**# look for top-level items (within that fragment element subtree if any) of type "h-feed"
** ALSO implementations MAY [[microformats2-parsing|parse the whole document]] and look in its top level items for those of type "h-feed"

* If the implementation has already parsed an HTML document, it may look for elements with a class name of "h-feed"

Details:
* Implementations may fetch public h-feeds without having to pass cookies or any other user-identifying information
* Implementations should parse h-feed documents without executing any scripts (parse as if scripting is disabled or unimplemented)
* If an implementation needs only one h-feed, it should take the first one found per the above methods

=== Implied h-feed ===
In the absence of an explicit "h-feed" element, implementations may infer an h-feed of all top level microformats items in the document (as determined by [[microformats2-parsing]] the document). Among those top level items, if precisely one of them is an "h-card" then it is used to imply a "p-author h-card" property of the implied "h-feed" and is removed from the "children" array of the implied "h-feed".

E.g. if an archive page has a collection of h-entry elements at the top level, implementations may imply an h-feed container for all of them and treat the entire document as a feed.

== Examples in the wild ==

See https://indieweb.org/h-feed#IndieWeb_Examples for examples of h-feed in the wild.

== Consumers ==

See https://indieweb.org/h-feed#Consumers_of_H-Feed for examples of implementations that consume h-feed.

== Backward Compatibility ==
=== Publisher Compatibility ===
For backward compatibility, you may wish to use classic [[hAtom]] classnames in addition to the more future-proof h-feed properties, for example:

<syntaxhighlight lang="html">
<div class="h-feed hfeed">
<h1 class="p-name site-title">The Markup Blog</h1>
<p class="p-summary site-description">Stories of elements of their attributes.</p>

<article class="h-entry hentry">
<a class="u-url" rel="bookmark" href="2020/06/22/balanced-divisive-complementary">
<h2 class="p-name entry-title">A Tale Of Two Tags: Part 2</h2>
</a>
<address class="p-author author h-card vcard">
<a href="https://chandra.example.com/" class="u-url url p-name fn" rel="author">Chandra</a>
</address>
<time class="dt-published published" datetime="2012-06-22T09:45:57-07:00">June 21, 2012</time>
<div class="p-summary entry-summary">
<p>From balanced harmony, to divisive misunderstandings, to complementary roles.</p>
</div>
<a href="/category/uncategorized/" rel="category tag" class="p-category">General</a>
</article>

<article class="h-entry hentry">
<a class="u-url" rel="bookmark" href="2020/06/20/best-visible-alternative-invisible">
<h2 class="p-name entry-title">A Tale Of Two Tags: Part 1</h2>
</a>
<address class="p-author author h-card vcard">
<a href="https://chandra.example.com/" class="u-url url p-name fn" rel="author">Chandra</a>
</address>
<time class="dt-published published" datetime="2012-06-20T08:34:46-07:00">June 20, 2012</time>
<div class="p-summary entry-summary">
<p>It was the best of visible tags, it was the alternative invisible tags.</p>
</div>
<a href="/category/uncategorized/" rel="category tag" class="p-category">General</a>
</article>

</div>
</syntaxhighlight>

{{note|Note: you may use any valid HTML5 elements. The <code>article h1 h2 address time</code> elements are used in the example as semantically richer suggestions, however in general <code>div span</code> work fine too. The <code>time</code> element is special though in that its <code>datetime</code> attribute provides a more author/user friendly way of separating a machine readable ISO8601 datetime from a human readable summary.
}}

The class '''<code>hfeed</code>''' is a ''backward compatible root class name'' that indicates the presence of an [[hAtom]] feed.

Backward compatibility hAtom property class names and rel values are listed below.

=== Parser Compatibility ===
Microformats parsers {{should}} detect classic properties only if a classic root class name is found and parse them as microformats2 properties.

If an "h-feed" is found, don't look for an "hfeed" on the same element.

Compat root class name: <code id="hfeed">hfeed</code><br/>
Properties: (parsed as '''p-''' plain text unless otherwise specified):

(this section is a stub and needs review and citations to note what real world examples would each of these backcompat parsing rules actually help parse)

* <code>rel=tag</code> - parse as '''<code>p-category</code>'''. While not a class name nor typical microformats property, rel=tag was the defined way to tag an hfeed. Thus parsers should look for rel=tag hyperlinks inside an hfeed, and take the last path segment of their "href" value as a value for a '''<code>p-category</code>''' property.
* <code>site-title</code> - parse as '''<code>p-name</code>''' [WordPress (Core? Typical themes?) has this class name by default, and without it buggy parsers may imply p-name as the whole h-feed ([http://microformats.org/wiki/microformats2-parsing#parsing_for_implied_properties implied properties only apply to actual h-x roots, not backcompat]).]
* <code>site-description</code> - parse as '''<code>p-summary</code>''' [WordPress (Core? Typical themes?) has this class name by default]

If no "h-feed" nor "hfeed" element is found, however multiple top-level [[h-entry]] elements (explicit or backcompat) are found, implementations may use:
* top level [[h-entry]] elements as items in a synthetic h-feed.
* <code><title></code> of the page or the URL of the page as '''<code>p-name</code>'''
* https://indieweb.org/authorship on the page to discover default authorship for any h-entry posts lacking explicit parsed <code>author</code> properties.

== FAQ ==
=== How do I avoid duplicating the page title ===
''I want to use the name (title) of my page as the name of my feed, how do I avoid duplicating the page title somewhere invisibly on the page as the feed name?''

If you want re-use the <title> of your page as the name of your feed, you can do so by putting the h-feed root class name on the <html> element, and the p-name property class name on the <title> element, e.g. here's a snippet showing how those tags would look:

<syntaxhighlight lang="html">
<html class="h-feed">
…
<title class="p-name">The Markup Blog</title>
…
</syntaxhighlight>

== See Also ==
* [[h-entry]]
* [[microformats2]]
* [[hAtom]]

[[Category:Draft Specifications]]

h-event

2023-07-26T21:18:23Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:h-event}}
<dfn style="font-style:normal;font-weight:bold">h-event</dfn> is a simple, open format for events on the web. h-event is often used with both event listings and individual event pages. h-event is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.

h-event is the [[microformats2]] update to [[hCalendar]].

;<span id="status">Status</span>
:This is a '''Living Specification''' yet mature enough to encourage additional implementations and [https://github.com/microformats/h-event/issues feedback].
;<span id="participate">Participate</span>
:[https://github.com/microformats/h-event/issues Open Issues]
:[[IRC]]
:Advance the spec by contributing to a consensus in [https://github.com/microformats/h-event/issues/1 issue: adopt same change control as h-entry]
<div class="p-author h-card vcard">
;<span class="p-role role">Editor</span>
:<span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span>
</div>
;License
: {{cc0-owfa-license}}
<span style="float:right">__TOC__</span>

== Example ==
Here is a simple event example:

<syntaxhighlight lang="html">
<div class="h-event">
<h1 class="p-name">Microformats Meetup</h1>
<p>From
<time class="dt-start" datetime="2013-06-30 12:00">30<sup>th</sup> June 2013, 12:00</time>
to <time class="dt-end" datetime="2013-06-30 18:00">18:00</time>
at <span class="p-location">Some bar in SF</span></p>
<p class="p-summary">Get together and discuss all things microformats-related.</p>
</div>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [
{
"type": [
"h-event"
],
"properties": {
"name": [
"Microformats Meetup"
],
"start": [
"2013-06-30 12:00:00"
],
"end": [
"2013-06-30 18:00:00"
],
"location": [
"Some bar in SF"
],
"summary": [
"Get together and discuss all things microformats-related."
]
}
}
]
}
</syntaxhighlight>

=== Get started ===
The class '''<code>h-event</code>''' is a ''root class name'' that indicates the presence of an h-event.

'''p-name''', '''dt-start''', '''dt-end''', '''p-location''', '''p-summary''', and the other h-event property class names listed below define ''properties'' of the h-event.

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

== Properties ==
h-event properties, inside an element with class '''h-event''':
* '''<code>p-name</code>''' - event name (or title)
* '''<code>p-summary</code>''' - short summary of the event
* '''<code>dt-start</code>''' - datetime the event starts
* '''<code>dt-end</code>''' - datetime the event ends
* '''<code>dt-duration</code>''' - duration of the event
* '''<code>p-description</code>''' - more detailed description of the event
** '''WARNING:''' Proposed to be replaced by '''<code>e-content</code>''' (re-used from [[h-entry]])
** See and follow-up: https://github.com/microformats/h-event/issues/3
* '''<code>u-url</code>''' - permalink for the event
* '''<code>p-category</code>''' - event category(ies)/tag(s)
* '''<code>p-location</code>''' - where the event takes place, optionally embedded [[h-card]], [[h-adr]], or [[h-geo]]

All properties are optional.

=== Experimental Properties ===

These properties are currently in use in the wild but not (yet) part of the draft h-event spec:

* '''<code>p-attendee</code>''' - a person attending the event, optionally embed [[h-card]]
<div class="discussion">
* This draft has not been updated in almost 2 years. During this period, <code>h-entry</code> <code>p-rsvp</code> has been standardised, thus making it robust and mature enough for the addition. I guess it's about time to unlabel <code>p-attendee</code> as experimental.
** I've filed https://github.com/microformats/h-event/issues/2 to track advancing this draft as a whole. Let's do that with the existing draft before discussing p-attendee in particular. And rather than guessing, take a look at the vocabulary maturity levels in h-entry and perhaps help evaluate (in another issue) p-attendee according to those criteria. [[User:Tantek|Tantek]] 01:10, 28 February 2017 (UTC)
* I would also suggest to extend expected value to [[h-entry]], so that, while the personal info can be preserved, the attendee can also support p-rsvp property of h-entry.
** I don't understand this. p-attendee is supposed to represent a person, e.g. an [[h-card]]. How would it having that be an [[h-entry]] make sense and work (from a publishing and consuming code perspective)? This proposed extension to p-attendee may be worth its own issue as well. [[User:Tantek|Tantek]] 01:10, 28 February 2017 (UTC)
</div>
* '''<code>p-organizer</code>''' - a person organizing an event, optionally embedded [[h-card]]. Used in Indieweb events, but not consumed. https://github.com/microformats/h-event/issues/10
* '''<code>u-rsvp</code>''' - similar to the proposed u-comment on h-entry, this would be the proposed property to mark up displayed RSVPs on an h-event. https://github.com/microformats/h-event/issues/9

== Status ==
'''h-event''' is a microformats.org draft specification. Public discussion on h-event takes place on the [[irc|#microformats channel on irc.freenode.net]] ([https://chat.indieweb.org/microformats view recent discussions]), and specific issues [https://github.com/microformats/h-event/issues may be filed on GitHub].

h-event is ready to use and implemented in the wild. For backwards compatibility you should also mark up top-level h-events as classic [[hCalendar]] events.

== Property Details ==
(stub, to be expanded)

=== p-location ===
<code>p-location</code> is typically a physical address, optionally marked up with [[h-adr]], for example:

<syntaxhighlight lang="html">
<p class="p-location h-adr">
<span class="p-street-address">17 Austerstræti</span>
<span class="p-locality">Reykjavík</span>
<span class="p-country-name">Iceland</span>
</p>
</syntaxhighlight>

=== Reserved Properties ===
Reserved properties:
* '''<code>p-organizer</code>''' - a person (co-)organizing the event, optionally embed [[h-card]] {{main|h-card}}
** proposed as way to [https://github.com/snarfed/bridgy/issues/275 implement copying an event organizer to Eventbrite]

== Examples in the wild ==
Real world in the wild examples:

* ... add uses of h-event you see in the wild here.
* [http://www.w3.org/conf/ W3Conf 2013] uses h-event for the main event, and h-card for all the speakers and notable attendees. The h-cards make particularly good use of implied name, url, and photo properties.
* [http://tantek.com/ Tantek Çelik] uses h-event on his home page
* [http://tantek.com/presentations/2012/06/microformats microformats.org at 7 years] presentation with h-event
* [http://tantek.com/presentations/2012/06/pdf2012-indieweb.html Rise of the Indie Web hCards] (from Personal Democracy Forum 2012 #pdf12 #pdf2012) has [[microformats2]] h-event and h-card markup
* WebMaker by Mozilla has h-event and h-card on event search (e.g. [https://webmaker.org/en-US/events/near/?lat=45.5234515&lng=-122.6762071 search near Portland Oregon]) and event pages (e.g. [https://webmaker.org/en-US/events/192f56eb9/ IndieWebCamp 2012]).[https://twitter.com/microformats/status/212207925643587585]
* [http://indiewebcamp.com IndieWebCamp] has [[microformats2]] h-event markup with embedded h-cards for the organizers and the location.
* [https://wiki.mozilla.org/Events Mozilla Events] page has [[microformats2]] h-event markup with attendees marked up with h-card.
* https://gregorlove.com/events has h-event markup, for example: https://gregorlove.com/2017/06/homebrew-website-club/
** has additional property from [[h-entry]]: <code>dt-published</code>
* https://oauth.net/events/ has a list of h-event marked up events relating to OAuth, both future and past
* http://68middle.st/events has events marked up in h-event
* [https://www.gov.uk/government/publications/open-standards-for-government/exchange-of-calendar-events gov.uk] mentions that iCalendar can be translated into h-event microformats in their "Exchange of calendar events" guidance.
<blockquote>You can map events to and from iCalendar from other formats, such as h-event.</blockquote>

See [[microformats2#Examples_in_the_wild|microformats2 examples in the wild]] for more

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

== Implementations ==
Software implementations that publish or consume h-event, including themes, plugins, or extensions:

When adding an implementation, please provide and link to its home page and open source repo if any.

* [https://github.com/gRegorLove/mf2-to-iCalendar mf2 to iCalendar]: Convert microformats h-event to iCalendar. Example: https://gregorlove.com/calendar/

== Backward Compatibility ==
=== Publisher Compatibility ===
For backward compatibility, you may wish to use classic [[hCalendar]] classnames in addition to the more future-proof h-event properties, for example:

<syntaxhighlight lang="html">
<div class="h-event vevent">
<h1 class="p-name summary">Some great event</h1>
</div>
</div>
</syntaxhighlight>

=== Parser Compatibility ===
Microformats parsers {{should}} detect classic properties only if a classic root class name is found and parse them as microformats2 properties.

If an "h-event" is found, don't look for a "vevent" on the same element.

Compat root class name: <code id="vevent">vevent</code><br/>
Properties: (parsed as '''p-''' plain text unless otherwise specified)
* <code>summary</code> - parse as '''<code>p-name</code>'''
* <code>dtstart</code> - parse as '''<code>dt-start</code>'''
* <code>dtend</code> - parse as '''<code>dt-end</code>'''
* <code>duration</code> - parse as '''<code>dt-duration</code>'''
* <code>description</code>
* <code>url</code> - parse as '''u-'''
* <code>category</code>
* <code>location</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>, and compat root <code>adr</code> in the absence of <code>h-adr</code>
* <code>geo</code> - parse as '''<code>p-location h-geo</code>''' including compat root <code>geo</code>

=== iCalendar Compatibility ===
hCalendar-specific implementations that perform custom display or translation to iCalendar .ics {{should}} prefer <code>p-name</code> over <code>p-summary</code>, and use <code>p-summary</code> value(s) as a fallback if there is no <code>p-name</code>.

== Background ==
This work is based on the existing [[hCalendar]] and [[iCalendar]] specifications.

== Design Principles ==
(stub, expand)

== See Also ==
* [[h-calendar-to-do]]
* [[h-event-brainstorming]]
* [[microformats2]]
* [[microformats2-parsing]]
* [[h-adr]]
* [[h-geo]]
* [[h-card]]
* [[hCalendar]]
* [[h-entry]]s can be RSVPs to events, using the p-rsvp property

[[Category:Draft Specifications]]

h-entry

2023-07-26T21:16:46Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:h-entry}}
<dfn style="font-style:normal;font-weight:bold">h-entry</dfn> is a simple, open format for episodic or datestamped content on the web. h-entry is often used with content intended to be syndicated, e.g. blog posts. h-entry is one of several open [[microformats|microformat]] standards suitable for embedding data in HTML.

h-entry is the [[microformats2]] update to [[hAtom]], in particular its "hentry" root class which itself was based on [[Atom]]'s "entry" element. For an update to "hfeed" see [[h-feed]].

;<span id="status">Status</span>
:This is a '''Living Specification''' yet mature enough to encourage additional implementations and [[h-entry-issues|feedback]]. This specification has portions that are stable, draft, and proposed. Features are stable unless explicitly labeled draft or proposed, or in draft or proposed sections. Draft and proposed features are likely to change substantively. While substantive changes to stable features are unexpected, it is a living specification subject to substantive change by issues and errata filed in response to implementation experience, requiring consensus among participating implementers as part of an explicit [[#change_control|change control]] process.
;<span id="participate">Participate</span>
:[https://github.com/microformats/h-entry/issues Open Issues]
:[[h-entry-issues|Resolved issues before 2012-246]]
:[[IRC]]
:Advance the spec by following explicit [[#change_control|change control]] process
<div class="p-author h-card vcard">
;<span class="p-role role">Editor</span>
:<span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span>
</div>
;License
: {{cc0-owfa-license}}
<span style="float:right">__TOC__</span>

== Example ==
Here is a simple blog post example:

<syntaxhighlight lang="html">
<article class="h-entry">
<h1 class="p-name">Microformats are amazing</h1>
<p>Published by <a class="p-author h-card" href="http://example.com">W. Developer</a>
on <time class="dt-published" datetime="2013-06-13 12:00:00">13<sup>th</sup> June 2013</time></p>

<p class="p-summary">In which I extoll the virtues of using microformats.</p>

<div class="e-content">
<p>Blah blah blah</p>
</div>
</article>
</syntaxhighlight>

Parsed JSON:
<syntaxhighlight lang="json">
{
"items": [
{
"type": [
"h-entry"
],
"properties": {
"name": [
"Microformats are amazing"
],
"author": [
{
"value": "W. Developer",
"type": [
"h-card"
],
"properties": {
"name": [
"W. Developer"
],
"url": [
"http://example.com"
]
}
}
],
"published": [
"2013-06-13 12:00:00"
],
"summary": [
"In which I extoll the virtues of using microformats."
],
"content": [
{
"value": "Blah blah blah",
"html": "<p>Blah blah blah</p>"
}
]
}
}
]
}
</syntaxhighlight>

== Get started ==
The class '''<code>h-entry</code>''' is a ''root class name'' that indicates the presence of an h-entry.

'''p-name''', '''p-author''', '''dt-published''' and the other h-entry property classnames listed below define properties of the h-entry.

Note: The purpose of an entry is to place it around both the explicitly written content (in the content property or in other specific properties for non-textual content or responses) and whatever else is the context for that content, including properties for when it was published and/or updated, who created it, tags or categorization, and links to what the content is a response to (perhaps with a quoted excerpt) and/or links to syndicated copies.

== Properties ==
h-entry properties, inside an element with class '''h-entry'''. All properties are optional and may be plural.
* See [[microformats2-parsing]] to learn more about property classnames.

=== Core Properties ===
The following ''core'' h-entry properties have broad consensus and are broadly interoperably published and consumed:
* '''<code>p-name</code>''' - entry name/title
* '''<code>p-summary</code>''' - short entry summary
* '''<code>e-content</code>''' - full content of the entry
* '''<code>dt-published</code>''' - when the entry was published
* '''<code>dt-updated</code>''' - when the entry was updated
* '''<code>p-author</code>''' - who wrote the entry, optionally embedded [[h-card]](s)
* '''<code>p-category</code>''' - entry categories/tags
* '''<code>u-url</code>''' - entry permalink URL
* '''<code>u-uid</code>''' - universally unique identifier, typically canonical entry URL
* '''<code>p-location</code>''' - location the entry was posted from, optionally embed [[h-card]], [[h-adr]], or [[h-geo]]
* '''<code id="u-syndication">u-syndication</code>''' - URL(s) of syndicated copies of this post. The property equivalent of [[rel-syndication]] ([http://erinjo.is/2014/checked-into-rockit-colabs-23 example])
* '''<code>u-in-reply-to</code>''' - the URL which the h-entry is considered reply to (i.e. doesn’t make sense without context, could show up in comment thread), optionally an embedded [[h-cite]] ([http://indiewebcamp.com/reply-context reply-context]) ([https://kartikprabhu.com/notes/re-citizen-of-indieweb example])
* '''<code id="p-rsvp">p-rsvp</code>''' (enum, use <data> element or [[value-class-pattern]])
** "yes", "no", "maybe", "interested". Case-insensitive values, normalized to lowercase. Examples:
** <code><nowiki>... <data class="p-rsvp" value="YES">is going</data> to ...</nowiki></code>, or
** <code><nowiki>... <data class="p-rsvp" value="Maybe">might go</data> to ...</nowiki></code>
** <code><nowiki>... <data class="p-rsvp" value="no">unable to go</data> to ...</nowiki></code>
** <code><nowiki>... <data class="p-rsvp" value="interested">am interested/tracking/watching</data> ...</nowiki></code>
* '''<code id="u-like-of">u-like-of</code>''' - the URL which the h-entry is considered a “like” (favorite, star) of. Optionally an embedded [[h-cite]]
* '''<code id="u-repost-of">u-repost-of</code>''' - the URL which the h-entry is considered a “repost” of. Optionally an embedded [[h-cite]].

=== Draft Properties ===
The following draft properties are in use in the wild (published and consumed), and are under strong consideration, but are not yet part of the core:

* '''<code id="p-comment">p-comment</code>''' - optionally embedded (or nested?) [[h-cite]](s), each of which is a comment on/reply to the parent h-entry. See [[comment-brainstorming]] ([http://waterpigs.co.uk/notes/4V2DjG/ example])
** [https://github.com/microformats/h-entry/issues/20 Issue 20]
* '''<code id="u-photo">u-photo</code>''' - one or more photos that is/are considered the primary content of the entry, unless there is a <code>p-location h-card</code>, which is still considered a "checkin" (i.e. with a photo). Otherwise the presence of a u-photo means the name of the entry should be interpreted as a caption on the photo, and the summary/content should be interpreted as a description of the photo.
** [https://github.com/microformats/h-entry/issues/4 Issue 4: u-photo draft->core bc way more than 3+ pub and consuming impls/sites]
*** depends on: [https://github.com/microformats/h-entry/issues/24 Issue 24: Update Definition of Draft Property u-photo]
*** depends on: [https://github.com/microformats/h-entry/issues/23 Issue 23: E-Content Overlaps with u-photo and similar properties]
** Proposed (issue TBF): A <code>u-photo</code> property MUST be on an element that provides a text description for the image (e.g. <code><img alt=""></code>) UNLESS the image is already described inside the contents a text property such as <code>p-name</code>, <code>p-summary</code>, or <code>e-content</code>
* '''<code id="u-video">u-video</code>''' - special u- parsing rules for <code><video src> & <source src></code>
** [https://github.com/microformats/h-entry/issues/5 Issue 5]

=== Proposed Additions ===
The following properties are proposed additions based on various use-cases, such as existing [[link-preview-brainstorming|link preview]] markup conventions, but are awaiting citations of use across multiple sites in the wild, and at least one reader / real world consuming code example:
* '''<code>u-audio</code>''' - special u- parsing rules for <code><audio src> & <source src></code>. Examples: [http://transportini.com/ Transportini],[https://indieweb.org/podcast#How_to_podcast_with_h-feed possibly more]
** [https://github.com/microformats/h-entry/issues/6 Issue 6]
* '''<code>u-like</code>''' - similar to p-comment, URL to a like post of the current post, e.g. in a responses list or facepile.
** [https://github.com/microformats/h-entry/issues/31 Issue 32]
* '''<code>u-repost</code>''' - similar to u-like, URL to a repost of the current post, e.g. in a responses list or facepile.
** [https://github.com/microformats/h-entry/issues/30 Issue 30]
* '''<code>u-bookmark-of</code>''' - indicates this h-entry is a bookmark of another URL. Optionally an [[h-cite]]. See [https://indieweb.org/bookmark indieweb.org/bookmark] for examples in the wild.
** [https://github.com/microformats/h-entry/issues/12 Issue 12]
* '''<code>u-featured</code>''' - a representative photo or image for the entry, e.g. primary photo for an article or subject-cropped photo, suitable for use in a [[link-preview]].
** +1 sknebel: https://github.com/microformats/h-entry/issues/14
* Location Properties - https://github.com/microformats/h-entry/issues/29
** '''<code>p-latitude</code>''' - latitude of the location of the entry
** '''<code>p-longitude</code>''' - longitude of the location of the entry
** '''<code>p-altitude</code>''' - altitude of the location of the entry
* '''<code>p-duration</code>''' - duration of an audio or video file in the entry. https://indieweb.org/duration Multiple publishers and consumers in the wild; https://github.com/snarfed/granary/issues/169 more background.
** [https://github.com/microformats/h-entry/issues/21 Issue 21]
* '''<code>p-size</code>''' - size in bytes of an audio or video file in the entry. https://indieweb.org/size Multiple publishers and consumers in the wild; https://github.com/snarfed/granary/issues/169 more background.
* '''<code>u-listen-of</code>''' - also known as a 'scrobble', indicates this h-entry is a listen of another URL. Optionally an h-cite. https://github.com/microformats/h-entry/issues/11
* '''<code>u-watch-of</code>''' - indicates this h-entry is a watch of another URL, a visual version of the scrobble. Optionally an h-cite. https://github.com/microformats/h-entry/issues/17
* '''<code>p-read-of</code>''' - indicates this h-entry is a read post of some written work (book or other document). The value can be the title of the work or an h-cite. Proposal also mentions <code>u-read-of</code>, where the value would be a URL to the written work or a representative citation page. https://github.com/microformats/h-entry/issues/10
* '''<code>u-translation-of</code>''' - indicates this h-entry is a translation of the linked URL into another language. Can be used in the same way as the existing <code>u-like-of</code> and <code>u-repost-of</code> properties, with just the URL to the original h-entry, or (optionally) contain an embedded <code>h-cite</code>. https://github.com/microformats/h-entry/issues/26
* '''<code>u-checkin</code>''' - the URL of the venue/location h-card which the h-entry is considered a “checkin” of. Optionally an embedded h-card. https://github.com/microformats/h-entry/issues/15

The following interpretation is also proposed addition:
* if the <code>p-location</code> is also an embedded [[h-card]], the entry is treated as a "checkin".
** -1 [[User:Aaronpk|Aaronpk]] 14:22, 19 January 2017 (UTC) [https://aaronparecki.com/2017/01/13/21/ this post] is not a checkin, but has an h-card as the p-location property.

Note: As [[h-entry]] usage grows to express and consume different kinds of content, we expect additional properties may be proposed and iterated as demonstrated by real-world needs, usage, and interoperability.

=== Proposing and upgrading ===
How do you add proposed properties and then upgrade them to draft and then core properties?

See: [[h-entry#change_control|change control]]

== Property Details ==
This section is a stub.
=== p-location ===
'''<code>p-location</code>''' has been re-used from [[h-event]].

== FAQ ==
=== p-name of a note ===
<div class="discussion">
* '''What is the <code>p-name</code> of a [https://indieweb.org/note note]?'''
** You probably should avoid adding <code>p-name</code> to notes. See https://indieweb.org/note for more discussion of the topic.
</div>

=== venue an entry was posted from ===
<div class="discussion">
* '''How do you indicate a named venue where an entry was posted from? Like a restaurant or park.'''
** Use an embedded [[h-card]] microformat on a <code>p-location</code> property value.
</div>

=== address an entry was posted from ===
<div class="discussion">
* '''How do you indicate the address where an entry was posted from? Like a restaurant or park.'''
** If the address is just part of a named venue, see above, use an [[h-card]]
** Otherwise use an embedded [[h-adr]] microformat on a <code>p-location</code> property value.
</div>

=== lat long an entry was posted from ===
<div class="discussion">
* '''How do you indicate the latitude and longitude of where an entry was posted from?'''
** If the location has a name in addition to latitude and longitude, see above, use an [[h-card]]
** Otherwise if there is an address in addition to latitude and longitude, see above, use an [[h-adr]]
** Otherwise use an embedded [[h-geo]] microformat on a <code>p-location</code> property value.
</div>

=== dt-published property and HTML5 time element ===
<div class="discussion">
* '''Does the dt-published property need to be a time element?'''
** The <code>dt-published</code> property should be a <code><time></code> element so that you can take advantage of HTML5's "datetime" property.
** This lets you specify a human-readable date in the value of the attribute, and the ISO8601 machine-readable date in the "datetime" property.
</div>

=== what is the bare minimum list of required properties on an h-entry ===
; What is the bare minimum list of required properties on an h-entry?
: No properties are explicitly required, but in practice a h-entry should have the following properties at a minimum for consumers:
:* <code>url</code>
:* <code>published</code> — if there is no "published" date for the "entry", then reconsider whether it is correct (or worth) marking it up as an entry.

; What properties should an h-entry have in addition to the bare minimum?
: Beyond the bare minimum, a typical h-entry should have the following as well:
:* <code>content</code> (or <code>summary</code> at least) - especially for structured content. For a plain text note, the content/summary (whichever is used) should be the same as the <code>name</code>, otherwise it will be implied from the text content of the root element.
:* <code>name</code> - for explicitly named/titled entries like blog posts and articles. Otherwise the entry is assumed to be a "title-less" [https://indieweb.org/note note] (like a tweet).
:* <code>author</code> - including a nested <code>[[h-card]]</code> with author details like name, photo, url.

== Examples in the wild ==
Real world in the wild examples of sites and services that publish or consume h-entry:

* ... add uses of h-entry you see in the wild here.
* ind.ie mark up their [https://ind.ie/blog blog] listing and [https://ind.ie/blog/autumn-events-2014/ permalink] pages with h-entry
* David John Mead marks up his profile, blog posts and comments with h-card, h-entry and h-cite on [http://davidjohnmead.com davidjohnmead.com]
* [[User:Brian|Brian Suda]] marks up his blog posts up with h-entry and h-card on [http://optional.is/required/ optional.is]
* Ashton McAllen marks up his blog posts, reposts, comments and likes with h-entry, h-card and h-cite on [http://acegiak.net/ acegiak.net]
* Emma Kuo marks up her blog posts and notes with h-entry and h-card on [http://notenoughneon.com/ notenoughneon.com]
* Scott Jenson marks up his blog posts with h-entry and h-card on [http://jenson.org/ jenson.org]
* Emily McAllen marks up her blog posts with h-entry and h-card on [http://blackwoolholiday.com/ blackwoolholiday.com]
* Ryan Barrett marks up his blog posts, notes, replies and likes with h-entry and h-card on [https://snarfed.org/ snarfed.org]
* Barry Frost marks up his notes with h-entry, h-card and h-cite on [http://barryfrost.com/ barryfrost.com]
* Amber Case marks up her profile, blog posts, replies and notes with h-entry and h-card on [http://caseorganic.com/ caseorganic.com]
* Johannes Ernst marks up his blog posts with h-entry on [http://upon2020.com/blog/ upon2020.com]
* Michiel de Jong marks up his profile and notes with h-entry and h-card on [https://michielbdejong.com/ michielbdejong.com]
* Mike Taylor marks up his profile and blog posts with h-card and h-entry on [https://bear.im/bearlog/ bear.im]
* Erin Jo Ritchey marks up her profile, posts and comments using h-card, h-entry and h-cite with idno on [http://erinjo.is/ erinjo.is]
* Jeena Paradies marks up his profile, blog posts, notes and comments using h-card, h-entry and h-cite on [https://jeena.net/ jeena.net]
* Andy Sylvester marks up his profile, blog posts and comments using h-card and h-entry on [http://andysylvester.com/2014/03/01/howto-setting-up-the-selfoss-feed-reader-with-microformats-support/ andysylvester.com] (note: as of 2014-03-13 using h-entry for comments instead of correct h-cite --[[User:Barnabywalters|bw]] 14:44, 13 March 2014 (UTC))
* Chloe Weil marks up her blog posts with h-entry on [http://chloeweil.com/blog chloeweil.com]
* Christophe Ducamp marks up his blog posts and profile with h-entry and h-card on [http://christopheducamp.com/ christopheducamp.com]
* Glenn Jones marks up his blog posts, notes, replies, profile and comments with h-entry, h-card and h-cite on [http://glennjones.net/ glennjones.net]
* Marcus Povey marks up his blog posts and profile with h-entry and h-card on [http://www.marcus-povey.co.uk/ marcus-povey.co.uk]
* Matthias Pfefferle marks up his blog posts, comments and profile with h-card, h-cite and h-entry on [http://notizblog.org/ notizblog.org]
* Kyle Mahan marks up his profile and notes with h-card and h-entry on [http://kylewm.com/ kylewm.com]
* Okinawan-lyrics marks up his posts with h-entry and h-card ([http://www.okinawan-lyrics.com/ example])
* App.net marks up profile pages and permalink pages with h-entry as of 2013-08-06 ([https://alpha.app.net/voidfiles example])
* The Twitter archive browser UI uses h-entry and h-card internally, unfortunately it’s not exposed as HTML in static files anywhere
* Brett Comnes marks up his posts with h-entry and h-card ([http://bret.io/2013/06/29/getting-started-with-bower/ example])
* Ben Werdmuller marks up his posts with h-card and h-entry, u-in-reply-to and u-like ([http://werd.io/view/51d5097fbed7ded0633a5956 example])
* Sandeep Shetty marks his posts up with h-card and h-entry, as well as draft u-in-reply-to and experimental u-like properties ([http://sandeep.io/101 example])
* Laurent Eschenauer marks up his posts with h-entry ([http://eschnou.com/entry/first-autonomous-flight-of-my-nodecopter-62-24992.html example])
* Tom Morris marks up his posts using h-entry ([http://tommorris.org/posts/8417 example])
* Numerous newer W3C specs, e.g.
** [http://www.w3.org/TR/2013/CR-css3-values-20130404/ CSS Values and Units Module Level 3 - 2013-04-04]
** [http://www.w3.org/TR/2013/CR-css3-conditional-20130404/ CSS Conditional Rules Module Level 3 - 2013-04-04]
** [http://www.w3.org/TR/2013/WD-css3-page-20130314/ CSS Paged Media Module Level 3 - 2013-03-14]
** [http://www.w3.org/TR/2013/WD-css-counter-styles-3-20130221/ CSS Counter Styles Level 3 - 2013-02-21]
* [http://wordpress.org/extend/themes/sempress SemPress] is a WordPress theme that supports h-card, h-feed/h-entry.
* [http://the-pastry-box-project.net/ The Pastry Box Project] use h-card and h-entry markup on their homepage and individual thoughts pages
* Aaron Parecki uses h-entry to mark up notes, e.g. [http://aaronparecki.com/2012/230/reply/1 2012/230/reply/1].
* [http://tantek.com/ Tantek Çelik] uses h-entry on his home page, as well as h-entry on all post permalinks, e.g. [http://tantek.com/2012/243/t1/name-beats-title-modern-use-dubline-core-wrong-uf2 2012-243 post], with [[rel-prev]]/[[rel-next]] (if applicable) to indicate prev/next posts
* [http://waterpigs.co.uk/ Barnaby Walters] uses h-entry on all notes and articles, as well as nested within notes as reply contexts [http://waterpigs.co.uk/notes/1468/ example] and comments [http://waterpigs.co.uk/notes/1482/ example].

=== offline ===
* spreadly marks up share permalink pages with h-entry, as well as minimal h-cards and experimental p-like properties

== Validating ==
* '''[http://indiewebify.me/validate-h-entry/ indiewebify.me h-entry validator]''' parses [[h-entry]] markup, finds common errors and makes suggestions for things to add, with code samples
* '''[http://shrewdness.waterpigs.co.uk/test/ Shrewdness h-entry/h-feed validator]''' shows how shrewdness interprets+displays h-entries, with original source and interim formats, works for single h-entries and feed pages

{{h-spec-section-validating}}

== Implementations ==
Software implementations that publish or consume h-entry, including themes, plugins, or extensions:

(This section is a stub that needs expansion! In practice, nearly every CMS on every [https://indieweb.org/ indie web] site supports publishing h-entry by default.)

When adding an implementation, please provide and link to its home page and open source repo if any.
* [https://gnu.io/social/ GNUsocial] [https://git.gnu.io/gnu/gnu-social/ source code]
* [https://hubzilla.org/hubzilla/ Hubzilla] [https://github.org/redmatrix/hubzilla source code]
* [http://friendica.com/ Friendica] [https://github.org/friendica/friendica source code]
* [http://github.com/dissolve/inkblot InkBlot]
* ...

== Backward Compatibility ==
=== Publisher Compatibility ===
For backward compatibility with legacy [[hAtom]] consuming implementations, use [[hAtom]] classnames (or rel values) in addition to the more future-proof h-entry properties, for example:

<syntaxhighlight lang="html">
<article class="h-entry hentry">
<h1 class="p-name entry-title">A Tale Of Two Tags</h1>
<address class="p-author author h-card vcard">
<a href="https://chandra.example.com/" class="u-url url p-name fn" rel="author">Chandra</a>
</address>
<time class="dt-published published" datetime="2012-06-20T08:34:46-07:00">June 20, 2012</time>
<div class="e-content entry-content">
<p>It was the best of visible tags, it was the alternative invisible tags.</p>
<p>The a tag is perhaps the best of HTML, yet its corresponding invisible link tag has uses too.</p>
</div>
<a href="/category/uncategorized/" rel="category tag" class="p-category">General</a>
</article>
</syntaxhighlight>

{{note|Note: you may use any valid HTML5 elements. The <code>article h1 address time</code> elements are used in the example as semantically richer suggestions, however in general <code>div span</code> work fine too. The <code>time</code> element is special though in that its <code>datetime</code> attribute provides a more author/user friendly way of separating a machine readable ISO8601 datetime from a human readable summary.
}}

The list of equivalent [[hAtom]] classnames and rel values is provided below.

=== Parser Compatibility ===
Microformats parsers {{should}} detect classic properties only if a classic root class name is found and parse them as microformats2 properties.

If an "h-entry" is found, don't look for an "hentry" on the same element.

Compat root class name: <code id="hentry">hentry</code><br/>
Properties: (parsed as '''p-''' plain text unless otherwise specified):

* <code>entry-title</code> - parse as '''<code>p-name</code>'''
* <code>entry-summary</code> - parse as '''<code>p-summary</code>'''
* <code>entry-content</code> - parse as '''<code>e-content</code>'''
* <code>published</code> - parse as '''dt-'''
* <code>updated</code> - parse as '''dt-'''
* <code>author</code> - including compat root <code>vcard</code> in the absence of <code>h-card</code>
* <code>category</code>
* <code>rel=bookmark</code> - parse as '''<code>u-url</code>'''. While not a class name nor typical microformats property, rel=bookmark was the only way to indicate an hentry permalink. Thus parsers should look for rel=bookmark hyperlinks inside an hentry, and take their "href" value as a value for a '''<code>u-url</code>''' property, including handling any relative URL resolution.
* <code>rel=tag</code> - parse as '''<code>p-category</code>'''. While not a class name nor typical microformats property, rel=tag was the typical way to tag an hentry. Thus parsers should look for rel=tag hyperlinks inside an hentry, and take the last path segment of their "href" value as a value for a '''<code>p-category</code>''' property.

Proposed: ([https://github.com/microformats/h-entry/issues/7 follow-up in issue #7])
* <code>time.entry-date[datetime]</code> - in the absence of <code>published</code>, parse as '''<code>dt-published</code>'''. parse for the first <code><time></code> element with class name of <code>entry-date</code> and non-empty <code>datetime</code> attribute inside an hentry, if there is no <code>published</code> property, use that time element's <code>datetime</code> attribute value for the <code>dt-published</code> property. Evidence: default WordPress themes 2011-2014([https://wp-themes.com/twentyeleven/][https://wp-themes.com/twentytwelve/][https://wp-themes.com/twentythirteen/][https://wp-themes.com/twentyfourteen/]).
* <code>rel=author</code> - in the absence of <code>author</code>, parse as '''<code>u-author</code>'''. While not a class name nor typical microformats property, rel=author was commonly used to link to an author's URL. Thus parsers should look for rel=author hyperlinks inside an hentry (or even on the same page, preceding the hentry), use the absolute version of it as a value for the '''<code>u-author</code>''' property if there is no "author" property. (citations to "hentry" examples in the wild that <em>depend</em> on rel=author needed to accepted this proposal. Note: default WordPress themes twentyeleven, twentytwelve, twentythirteen, twentyfourteen all use rel=author but only inside class="author vcard", and thus rel=author can be ignored since authorship is already picked up by existing <code>author</code> backcompat parsing.)

=== Compat FAQ ===
==== What about rel bookmark ====
Also asked as: ''Why use an h-entry u-url u-uid for permalinks when I have [[rel-bookmark|rel=bookmark]]?''

A: tl;dr: use <code>class="u-url u-uid"</code> instead of <code>rel=bookmark</code> for post permalinks because it's simpler (fewer attributes), and works better across contexts (permalink page, recent posts on home page, collection of posts on archive pages).

rel=bookmark was the old [[hAtom]] way of marking up permalinks. Since then two factors have contributed to reducing use of rel inside microformats:
* rel by typically* document scoped in [[HTML5]] - thus making it inappropriate for use in microformats that are aggregated, e.g. a collection of posts on a home page or in monthly archives.
* it is easier to always use class names for properties. When formats use two (or more!) attributes in HTML to specify properties, confusion results in lower data quality (of the markup and thus the stuff that is marked up). Thus per the microformats [[principle]] of [[simplicity]], in [[microformats2]] we only use class names for properties.

<nowiki>*</nowiki> even though rel=bookmark in particular is article-element / sectioning scoped in HTML5[http://www.whatwg.org/specs/web-apps/current-work/multipage/links.html#link-type-bookmark], it's a detail that typical authors are not going to remember, and thus it's not good to depend on it for any kind of format.

==== Why rename entry-title entry-summary entry-content ====
The <code>entry-*</code> classnames in classic [[hAtom]] were prefixed as such due to concerns about vocabulary overlap with the title (as in job title, completely separate semantic) property in [[hCard]] and the summary property in [[hCalendar]] (see: [[hatom-faq#Could_hAtom_instead_use_title_content_and_summary|hAtom FAQ]]).

Following the [[simplicity]] principle, in microformats2, the aforementioned vagueness of '''title''' is dealt with by removing it. As '''name''' is now used consistently across all vocabularies as the property which “names” the microformat, it makes sense to use it to mark up the name of a post.

Likewise, adding entry- to '''summary''' doesn’t add any useful information, and in practice there have been no problems with blog post summaries overlapping with entry summaries, so it makes sense to simplify to '''summary'''. The same applies to '''entry-content''' simplified to '''content'''.

See also: [http://krijnhoetmer.nl/irc-logs/microformats/20120830#l-128 2012-08-30 IRC conversation].

== Related Work ==
Work that re-uses or builds upon h-entry:
* [https://mailpile.pagekite.me:8080/p/Open_Message_Format Mailpile Open Message Format] is using h-entry with structured properties, e.g. p-author h-card.

== Background ==
This work is based on the existing [[hAtom]] microformat, and extensive selfdogfooding in the [http://indiewebcamp.com indie web camp] community.

== change control ==
Minor editorial changes (e.g. fixing minor typos or punctuation) that do not change and preferably clarify the structure and existing intended meaning may be done by anyone without filing issues, requiring only a sufficient "Summary" description field entry for the edit. More than minor but still purely editorial changes may be made by an editor. Anyone may question such editorial changes by undoing corresponding edits without filing an issue. Any further reversion or iteration on such an editorial change must be done by filing an issue.

For the stable features of this document, substantive issue filing, resolution, and edits may be done by filing an [[h-entry-issues|issue]] and discussing them on the issue and on #microformats [[IRC]] with a link to the issue.

Because this is primarily a vocabulary specification, very few issues beyond the list of vocabulary have been filed or required any lengthy discussion. If such a non-trivial issue arises in the future, use the [[microformats2-parsing#change_control|microformats2-parsing change control process]] to resolve them.

In general, non-vocabulary related features or requirements should be avoided in this specification, e.g. changes to microformats2 syntax must be proposed as [[microformats2-parsing]] changes using the [[microformats2-parsing#change_control|microformats2-parsing change control process]].

Beyond that, the following requirements must be met for adding or moving features (e.g. properties and values) to proposed, draft, or stable. File an issue to collect necessary citations for the requirements for each property being proposed or upgraded, explain how citations fulfill the requirements for the phase(s), get consensus on both (resolve any implementer objections) in the issue.

;Proposed
:[[#Proposed_Additions|Proposed features]] must provide documentation of what specific real world use-cases they are solving, preferably with a link to a step-by-step user scenario, e.g. demonstratable using existing non-standard / single-site / single-implementation tools.
;Draft
:[[#Draft_Properties|Draft properties]] must in addition be published and consumed in the wild on the public web, demonstrate solving the use case for which they were proposed, and should provide citations of real world public web sites publishing and (other sites) consuming them, interoperably.
;Stable
:Stable features (e.g. [[#Core_Properties|Core Properties]]) must in addition be published and consumed in the wild on multiple sites by multiple implementations (3+ different sites and implementations for publishing and consuming). When a draft property reaches a critical mass of deployment by numerous sites and implementations (far beyond 3+), due to network effects and backward compatibility considerations it effectively becomes stable, since it becomes increasingly difficult to change it in any way and have so many sites and implementations also change.

For creating an entirely new vocabulary, and more details about how to research existing values, properties, document examples in the wild, etc., see the microformats [[process]].

== See Also ==
* [[h-feed]]
* [[microformats2]]
* [[microformats2-parsing]]
* [[h-geo]]
* [[hCard]]

[[Category:Specifications]]

h-cite

2023-07-26T21:14:45Z

GRegorLove: s/<source>/<syntaxhighlight>/

<dfn style="font-style:normal;font-weight:bold">h-cite</dfn> is a simple, open format for publishing citations and references to online and other publications. h-cite is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML/HTML5.

;<span id="Status">Status</span>
:This is a '''Draft Specification'''
;Participate
:[[IRC]]: [irc://irc.libera.chat/microformats #microformats on Libera]
;Editor
:<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
;License
:{{cc0-owfa-license}}
<span style="float:right">__TOC__</span>

== Example ==
Here is a simple minimal abstract web citation example:
<syntaxhighlight lang="html">
<span class="h-cite">
<time class="dt-published">YYYY-MM-DD</time>
<span class="p-author h-card">AUTHOR</span>:
<cite><a class="u-url p-name" href="URL">TITLE</a></cite>
</span>
</syntaxhighlight>

=== Get started ===
The class '''<code>h-cite</code>''' is a ''root class name'' that indicates the presence of an h-cite.

The classes '''<code>dt-published</code>''', '''<code>p-author</code>''', '''<code>p-name</code>''', and '''<code>u-url</code>''' define ''properties'' of the h-cite.

The class '''<code>h-card</code>''' on the same <code><span></code> as '''<code>p-author</code>''' indicates the presence of a nested [[h-card]] microformat as the '''author''' of the h-cite.

== Properties ==
h-cite properties (inside class <code>'''h-cite'''</code>)

* '''<code>p-name</code>''' - name of the work
* '''<code>dt-published</code>''' - date (and optionally time) of publication
* '''<code>p-author</code>''' - author of publication, with optional nested [[h-card]]
* '''<code>u-url</code>''' - a URL to access the cited work
* '''<code>u-uid</code>''' - a URL/URI that uniquely/canonically identifies the cited work, canonical permalink.
* '''<code>p-publication</code>''' - for citing articles in publications with more than one author, or perhaps when the author has a specific publication vehicle for the cited work. Also works when the publication is known, but the authorship information is either unknown, ambiguous, unclear, or collaboratively complex enough to be unable to list explicit author(s), e.g. like with many wiki pages.
* '''<code>dt-accessed</code>''' - date the cited work was accessed for whatever reason it is being cited. Useful in case online work changes and it's possible to access the dt-accessed datetimestamped version in particular, e.g. via the Internet Archive.
* '''<code>p-content</code>''' for when the citation includes the content itself, like when citing short text notes (e.g. tweets).

== Status ==
'''h-cite''' is a microformats.org draft specification. Public discussion on h-cite takes place on [[h-cite-feedback]] and the #microformats [[irc]] channel on irc.freenode.net.

== Property Details ==
(stub, to be expanded)

All web citation properties are derived from those implied in [[citation-formats#styles|existing citation styling guides]] for citing permalinks to articles and short text notes online.

Date-time properties (dt-published, dt-accessed) may optionally include time information in addition to the date if relevant to the citation (e.g. when citing short text notes (tweets) of which there may be several in a single day).

To be added:
* for each property, what equivalent TCMOS, APA, MLA terms/vocabulary is being expressed/captured as researched in the [[citation-formats#styles|citation formats styles]] section.
* transforms from the web citations proposal properties into each of those citation styles.
** for citations of blog posts / articles
** for citations of text notes / tweets
** see examples in wild below for markup samples to style in each of the TCMOS/APA/MLA styles for blog/note citations.

== Offline Citations ==
The web citation proposal can be used for simple web-to-off-web citation use cases. As suggested by Ed Summers, dropping the hyperlink to the cited web article provides a simple off-web citation, e.g. a citation of a physical book:

<syntaxhighlight lang="html">
<span class="h-cite">
<time class="dt-published">YYYY-MM-DD</time>
<span class="p-author h-card">AUTHOR</span>:
<cite class="p-name">TITLE</cite>
</span>
</syntaxhighlight>

Note: physical books typically only provide the YYYY (year) published, not the precise date.

Next steps:
* Try such markup with actual content being published on the web (perhaps a bibliography, list of papers in a resume, etc.)
* See how it works/feels there
* Determine what seems to be missing.
* See if the "p-publisher" property helps in some web-to-off-web citation use cases.

== Examples in the wild ==
Real world in the wild examples:
* ... add uses of h-cite you see in the wild here.

* <cite class="h-cite">[http://christopheducamp.com/blog/test-indieweb-parvenir-a-posser-un-article-vers-twitter/ Test #IndieWeb : Parvenir à « POSSEr » un article vers Twitter]</cite> ([http://web.archive.org/web/20130623202346/http://christopheducamp.com/blog/test-indieweb-parvenir-a-posser-un-article-vers-twitter/ archived]) has an h-cite of a short note:
<syntaxhighlight lang="html">
<blockquote><p>
<cite class="h-cite">
<a class="u-url p-name" href="http://tantek.com/2013/104/t2/urls-readable-speakable-listenable-retypable">
URLs should be readable, speakable, listenable, and unambiguously
retypable, e.g. from print: tantek.com/w/ShortURLPrintExample #UX
</a>
(<abbr class="p-author h-card" title="Tantek Çelik">Çelik</abbr>
<time class="dt-published">2013-04-14</time>)
</cite>
</p></blockquote>
</syntaxhighlight>

* Mastodon uses h-cite by default to show threads and replies to posts [https://github.com/tootsuite/mastodon/pull/1063 added in 2017]

See also examples documented here:
* https://indieweb.org/h-cite#Indieweb_Examples

Real but not quite wild (used by the specification author)
* Every blog post on http://tantek.com has a text field for copying h-cite markup for that blog post.
* <cite class="h-cite">[http://tantek.com/2012/353/b1/why-html-classes-css-class-selectors Why you should say HTML classes, CSS class selectors, or CSS pseudo-classes, but not CSS classes]</cite> has a couple of interesting uses of h-cite:
** properties used: p-name, u-url, p-author, p-publication, dt-published, dt-accessed (basically all proposed properties except p-content!)
** additional experimental property: p-x-translation - which refers to a nested h-cite with its own implied p-name and implied u-url.

== Background ==
This work is based on how existing [[citation-formats#styles|citation format ''styles'']] (APA, MLA, TCMOS) represent references to articles on the web, and is designed to match the implied schema of those styles. The web citations proposal defines how to markup such reference representation styles in order to satisfy the use-cases above.

=== Goal ===
A primary goal of the web citation effort is to both start small, and always "make small possible", that is, no matter how it is extended, continue permitting very small meaningful citations with perhaps only 2-3 properties (e.g. date published, author, name of work).

=== Previous Proposals ===
The biggest problem with all previous proposals is that they tried to do too much. They didn't design a citation ''micro''format that could be used as a building block, but rather, erred on the side of attempting to describe the myriad types of references to dead-tree resources. They were so over-designed that their authors didn't even dogfood them on their own sites. -- [[User:Tantek|Tantek]] 00:56, 7 August 2012 (UTC)

== FAQ ==
=== Why ===
''Why markup web citations? What problem does it solve?''

A: In the simplest form, marking up a web citation URL, name, date published, author etc. allow for processing of web citations into whatever "style" or "format" (MLA vs APA etc.) a user wishes to publish them themselves.

=== Why not just a href ===
''Doesn't <code><a href></code> solve the problem of marking up citations in an article on the web that refers to other articles on the web?''

A: No, <code><a href></code> is necessary but insufficient for marking up <em>citations</em> to articles on the web.

* '''Insufficient semantic.''' <code><a href></code> is sufficient only for providing a hyperlink (which may or may not be a citation, e.g. it may be a "see also" link rather than link to a source being cited for particular assertion or fact).
* '''A href only marks up article link and name''' An <code><a href></code> can only represent the "url" and "name" of a citation. Where as [[citation-formats#styles|published web citations]] typically also include:
** article author name (sometimes author photo and URL)
** article publication date
** article publication name
** article access date (sometimes, e.g. Wikipedia citations)

== Design Principles ==
Principles driving this proposal:
* '''solve a [[specific]] problem'''. In this case '''web citations''' seeks to solve a ''more'' specific problem than previous proposals, that of citations from the web to the web (more constrained than any publication to any publication).
* [[solve simpler problems first]]. Existing web-to-web citations contain very little information compared to generalized academic citations, thus '''web citations''' is greatly simplified compared to previous proposals by only starting with a handful of properties.
* [[humans first]] - '''web citations''' focuses on the human readability and writability aspects of citations in articles first and foremost, and only secondarily considers the machine readability/reusability of the data contained therein.
* [[reuse]] building blocks - by re-using the better designed aspects of [[citation-formats#styles|existing citation conventions]] for web resources, '''web citations''' builds on top of previous work to make citations human readable/writable, as well as what implied properties are commonly expressed by such previous work.
=== Focus ===
The <dfn>web citations</dfn> proposal uses a smaller, [[simpler]] set of only ''eight'' properties to solve the [[specific]] problem of how to markup citations in an article <em>on the web</em> that refers to other articles <em>on the web</em>. Offline to offline, and online to offline references were specifically not explicitly addressed in initial design.

== First Proposal ==
This design was first publicly proposed as the result of an interactive web citation design discussion during IndieWebCamp2012:
* <span class="h-cite"><time class="dt-published">2012-07-01</time> <span class="p-publisher">IndieWebCamp2012</span>: <cite class="p-name">[http://indiewebcamp.com/2012/Academic_Citations_Web Academic Citations for the Web]</cite></span>

[[Category:Draft Specifications]]

h-adr

2023-07-26T21:13:15Z

GRegorLove: s/<source>/<syntaxhighlight>/

<dfn style="font-style:normal;font-weight:bold">h-adr</dfn> is a simple, open format for publishing structured locations such as addresses, physical and/or postal. h-adr is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.

h-adr is the [[microformats-2]] update to [[adr]]. It is most commonly used as part of an [[h-card]] or [[h-event]].

For named addresses, e.g. people or venues, use [[h-card]].

;<span id="Status">Status</span>
:This is a '''Draft Specification'''
;Participate
:[[IRC]]: [irc://irc.libera.chat/microformats #microformats on Libera]
;Editor
:<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
;License
:{{cc0-owfa-license}}
__TOC__

== Example ==
Here is a simple postal address example:

<syntaxhighlight lang="html">
<p class="h-adr">
<span class="p-street-address">17 Austerstræti</span>
<span class="p-locality">Reykjavík</span>
<span class="p-country-name">Iceland</span>
<span class="p-postal-code">107</span>
</p>
</syntaxhighlight>

Parsed JSON:

<syntaxhighlight lang="json">
{
"items": [
{
"type": [
"h-adr"
],
"properties": {
"street-address": [
"17 Austerstræti"
],
"locality": [
"Reykjavík"
],
"country-name": [
"Iceland"
],
"postal-code": [
"107"
],
"name": [
"17 Austerstræti Reykjavík Iceland 107"
]
}
}
]
}
</syntaxhighlight>

The implicit "name" property that is generated from parsing an h-adr is there for consuming applications to have a simple flattened string representation of an h-adr.

For an explicitly named address (such as a mailing address to a specific person), use [[h-card]].

=== Get started ===
The class '''<code>h-adr</code>''' is a ''root class name'' that indicates the presence of an h-adr.

'''p-street-address''', '''p-locality''', '''p-country-name''', '''p-postal-code''' and all the other h-adr property class names listed below define properties of the h-adr.

See [[microformats-2-parsing]] to learn more about property class names.

== Properties ==
h-adr properties, inside an element with class '''h-adr''':
* '''<code>p-street-address</code>''' - house/apartment number, floor, street name
* '''<code>p-extended-address</code>''' - additional street details
* '''<code>p-post-office-box</code>''' - post office mailbox
* '''<code>p-locality</code>''' - city/town/village
* '''<code>p-region</code>''' - state/county/province
* '''<code>p-postal-code</code>''' - postal code, e.g. ZIP in the US
* '''<code>p-country-name</code>''' - should be full name of country, country code ok
* '''<code>p-label</code>''' - a mailing label, plain text, perhaps with preformatting
* '''<code>p-geo</code>''' (or u-geo with a RFC 5870 geo: URL), optionally embedded [[h-geo]]
* '''<code>p-latitude</code>''' - decimal latitude
* '''<code>p-longitude</code>''' - decimal longitude
* '''<code>p-altitude</code>''' - decimal altitude - new in vCard4 (RFC6350)

All properties are optional.

* '''<code>p-name</code>''' - there is no "p-name" property in h-adr. If your address has an explicit name, it's likely a venue, and you should use [[h-card]] instead.

== Status ==
'''h-adr''' is a microformats.org draft specification. Public discussion on h-adr takes place on [[h-adr-feedback]] and the #microformats [[irc]] channel on irc.freenode.net.

h-adr is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-adrs up with classic [[adr]] classnames.

== Property Details ==
(stub, add any property explanations here)

== Examples in the Wild ==
* … add any h-adr examples you find in the wild

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

== Backward Compatibility ==
=== Publisher Compatibility ===
For backward compatibility, you may wish to use classic [[adr]] classnames in addition to the more future-proof h-adr properties, for example:

<syntaxhighlight lang="html">
<p class="h-adr adr">
<span class="p-street-address street-address">123 Main St.</span>,
<span class="p-locality locality">Pleasantville</span>
...
</p>
</syntaxhighlight>

The class '''<code>adr</code>''' is a ''backward compatible root class name'' that indicates the presence of an [[adr]].

'''street-address''', '''locality''', and all the other backward compatibility adr property class names are listed below.

=== Parser Compatibility ===
Microformats parsers should detect classic properties only if a classic root class name is found and parse them as microformats2 properties.

If an "h-adr" is found, don't look for an "adr" on the same element.

Compatibility root class name: adr

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

* post-office-box
* extended-address
* street-address
* locality
* region
* postal-code
* country-name

== FAQ ==
=== What about country codes ===
Q: When marking up an address, can p-country-name be used to markup two letter country codes like "UK"? Or others like 3 letter Olympic country codes?

A: In short yes. You can do:
<syntaxhighlight lang="html">
<span class="p-country-name">UK</span>
</syntaxhighlight>
However it's better if you mark it up with the <code>abbr</code> element and provide the full name as well, e.g.
<syntaxhighlight lang="html">
<abbr class="p-country-name" title="United Kingdom">UK</abbr>
</syntaxhighlight>

Consuming applications may interpret any 2-3 character country-name per the table of 2-3 character [http://en.wikipedia.org/wiki/ISO_3166-1#Officially_assigned_code_elements country codes in ISO3166].

== Background ==
h-adr is based on the existing [[adr]] specification, which was extracted from [[hCard]] in order to allow it to be used for applications other than contact information.

== See Also ==
* [[microformats2]]
* [[h-geo]] can be embedded in h-adr
* [[h-card]] and [[h-event]] often contain h-adr
* [[vcard]] (most recently vCard4 RFC6350) vocabulary is re-used by h-adr.
* [[address-formats]]

[[Category:Draft Specifications]]

citation-brainstorming

2023-07-26T21:11:20Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE: Citation Brainstorming }}

Part of the overall effort to develop a [[citation]] microformat.

== Use Cases ==
To focus the discussion, please add use cases below that will help show what problems the citation microformat will be solving.

Use cases for both publishing and consuming citation information can help to focus citation brainstorming on efforts that provide real world utility to users.

For now, please add any uses cases you think of, however common or obscure (feel free to note opinions as to expected/known frequency of use of such use cases).

=== improve web citations ===
Articles on the web often cite other online articles with permalinks (e.g. <span id="Blogs_quoting_other_resources.2C_including_blogs">blogs quoting other resources, including blogs</span>). Such web citations could be improved both in content and interaction in a number of useful ways:
* '''richer citations.''' Existing web citations typically include only permalink URL and article title in a hyperlink. An explicit format (both in microformat and style) for web citations could encourage the use of richer citations with information like author and date(time) of publication. Author information is useful because it provides an immediate inline proxy for reputation, and date of publication is useful because it sets a context for the information backed by the citation.
* '''richer citation interfaces.''' Web articles sometimes provide an explicit user interface to copy/paste a permalink for reference purposes, or a hyperlink embed code for linking to the article from another web article. An explicit markup structure/format could encourage such interfaces to provide a richer citation structure (e.g. including author, date of publication) to copy/paste, with little to no change in overall UI. This is useful in that it would help propagate richer citations themselves, which have the advantages mentioned above.

Additional useful rich citation enhancements:
* '''access date.''' Rich citations could include the access date when an author (blogger) made a citation, because resources on the other side of those links can change without notice.
* ...

=== I read this ===
A reader wants to collect a set of things they've read (e.g. on the web), perhaps for the purposes of cataloging them, adding notes, and using the information to generate later citations, potentially in other forms, such as BibTeX or Docbook, for inclusion in a publication of their own.

If web articles (e.g. blog posts) contained discoverable descriptions of self-citations (e.g. permalinks plus authorship), browsers/aggregators could both automatically collect these, perhaps as part of an enhanced browser history functionality, or allow explicit collection, e.g. bookmarking with additional structure.

Notes: In this case, it isn't important to the user what style the citation takes as displayed on the page where they find it. What *is* important is that it contains enough information to allow generation of the format they will ultimately re-publish it in. This implies that it may be worthwhile to err a little on the side of verbosity, but at most enough to provide typical TCMOS/APA/MLA citations.

=== collect further reading ===
Was part of <span id="Acquiring_reference_information_from_the_web">Acquiring reference information from the web</span>.

A reader finds a list of citations (e.g. a paper's bibliography, an author's papers page, results of a search for academic papers), and wants to add them to a queue of things they'd like to read, perhaps as part of further research on whatever subject/person they were reading/researching.

Marking up the list of citations with a microformat would enable to browsers/aggregators to present an explicit list of structured citations with a user interface for one-click addition to a read it later list (or a local reference database).

Links to downloadable full representations of the cited work (e.g. link to the PDF of a journal article, or to a music file) would help the reader find cited works, and perhaps even have their browser/aggregator prefetch/cache/download them.

=== Subscribing to reading lists, periodicals, etc ===
I would like to be able to leverage my news aggregator with hAtom to subscribe to a remote source for citation information, for example:

* a reading list for a seminar
* The publication list for a conference (e.g., subscribe to SIGGRAPH and see the updated conference proceedings every year)
* the issues of a journal
* a particular research group or researcher's publications
* Not just research: a popular author's publications (e.g., [http://www.gladwell.com/archive.html Malcolm Gladwell's Archive])

=== Aggregating reading lists and reviews ===
A citation microformat-specific aggregator could provide a decentralized version of [http://citeulike.org/ CiteULike]. Libraries, authors, research groups, and publishers could mark up their collections, while other people on weblogs or review sites could add tags and reviews.

At least, having a well-adopted microformat would make writing tools like CiteULike much better, since it relies in some cases on screen-scraping publisher web-sites.

=== Cut & Paste from web pages ===
Capturing/copying HTML from web pages for use in other applications (especially when those apps present HTML as output), such as pasting into Word, or a specialized application like [http://www.google.com/notebook Google Notebook], [http://onfolio.com Onfolio] or [http://www.kaboodle.com Kaboodle]. When such captures are made, it makes sense to keep track of the full citation data, including the date it was accessed, which may or may not be the date it was published.

===Finding in Library===
Find a copy of the cited work in a nearby library (as with [http://ocoins.info/ OpenCOinS]).

===Buy a copy===
Find the cited work on, for example, Amazon or [http://www.abebooks.com/ ABE]; or subscribe to a journal via its own website.

===Find reviews===
Find third-party reviews of the cited work.

===Give citation data for the page being visited===
Adding a class of, say, "self" to an attribute of the proposed strawman would allow users (or user agents) to extract the data required to cite the page being visited, when referring to it elsewhere. There would be the added advantage of allowing the citation to be ignored by any parser which might be building a "tree" of citations, and preventing the setting up of an infinite loop.

For evidence of published "self citation" data (albeit on a secondary page) see the "cite this article" link on any Wikipedia entry, e.g. [http://en.wikipedia.org/w/index.php?title=Special:Cite&page=West_Midland_Bird_Club&id=115894372] from [http://en.wikipedia.org/wiki/West_Midland_Bird_Club].

See also [http://en.wikipedia.org/wiki/Wikipedia_talk:Citing_Wikipedia#Citation_data_should_be_on_the_page_concerned Proposal to include on-page citation data in Wikipedia]

=== Cite a journal on Wikipedia ===
* (from a mailing list):
:<blockquote>if you want to cite a [biomedical journal] journal article on Wikipedia [...] you can export a correctly-formatted citation for Wikipedia from HubMed using unAPI... http://hublog.hubmed.org/archives/001408.html</blockquote>

*[http://www.zotero.org/ Zotero], a Firefox extension to help collect, manage, and cite research sources.

== principles ==
Principles help guide and compare various different brainstorming proposals.

In the first three years of development the citation microformat effort generated a number of brainstorm proposals without clear consensus or adoption of any of them in particular. Thus any new (2012+) proposals must be written with references to particular principles for each design decision, justifying why/how the new proposal is an improvement upon previous proposals.

Principles to use:
* microformats design [[principles]]
* Semantic HTML Design Principles
* use as precise as HTML semantics as are available

=== Semantic HTML Design Principles ===
{{semantic-html-design-principles}}

Brainstorm proposals should take into account the Semantic HTML Design Principles.

=== semantic elements to consider ===
One of the guiding principles of Microformats is to encourage the use of the most precisely semantically rich element to describe each node (Point 2 of Semantic HTML Design Principles: Use the most accurately precise semantic HTML building block for each object etc). Since we are dealing with HTML and citations, several elements are candidates to be used to enrich the semantic meaning. [http://www.w3.org/TR/REC-html40/struct/text.html CITE, BLOCKQUOTE, Q, A], (are there more?)

== brainstorm proposals ==

=== web citations ===
{{main|h-cite}}

This brainstorm has now been moved to a draft microformat:
* [[h-cite]]

The remainder of this brainstorm proposal is left here for historical purposes:

The <dfn>web citations</dfn> proposal uses a smaller, [[simpler]] set of only ''eight'' properties to solve the [[specific]] problem of how to markup citations in an article <em>on the web</em> that refers to other articles <em>on the web</em>. Offline to offline, and online to offline references are specifically not addressed.

==== web citations background ====
This work is based on how existing [[citation-formats#styles|citation format ''styles'']] (APA, MLA, TCMOS) represent references to articles on the web, and is designed to match the implied schema of those styles. The web citations proposal defines how to markup such reference representation styles in order to satisfy the use-cases above.

==== web citation illustrative example ====
Here is a simple minimal abstract web citation example:

<syntaxhighlight lang="html">
<span class="h-cite">
<time class="dt-published">YYYY-MM-DD</time>
<span class="p-author h-card">AUTHOR</span>:
<cite><a class="u-url p-name" href="URL">TITLE</a></cite>
</span>
</syntaxhighlight>

==== web citation properties ====
root classname: '''<code>h-cite</code>'''

In rough order of presentation and relevance/frequency:

properties:
* '''<code>dt-published</code>''' - reused from [[uf2]] h-entry
* '''<code>p-author</code>''' - same, with optional substructured h-card
* '''<code>p-name</code>''' - common property instead of entry-title
* '''<code>u-url</code>''' - a URL to access the cited work
* '''<code>u-uid</code>''' - a URL/URI that uniquely/canonically identifies the cited work, canonical permalink.
* '''<code>p-publication</code>''' - for citing articles in publications with more than one author, or perhaps when the author has a specific publication vehicle for the cited work. Also works when the publication is known, but the authorship information is either unknown, ambiguous, unclear, or collaboratively complex enough to be unable to list explicit author(s), e.g. like with many wiki pages.
* '''<code>dt-accessed</code>''' - date the cited work was accessed for whatever reason it is being cited. Useful in case online work changes and it's possible to access the dt-accessed datetimestamped version in particular, e.g. via the Internet Archive.
* '''<code>p-content</code>''' for when the citation includes the content itself, like when citing short text notes (e.g. tweets).

==== web citations vs previous proposals ====
I think the biggest problem with all previous proposals is that they tried to do too much. They didn't design a citation ''micro''format that could be used as a building block, but rather, erred on the side of attempting to describe the myriad types of references to dead-tree resources. They were so over-designed that their authors didn't even dogfood them on their own sites. -- [[User:Tantek|Tantek]] 00:56, 7 August 2012 (UTC)

A primary goal of the web citation effort is to both start small, and always "make small possible", that is, no matter how it is extended, continue permitting very small meaningful citations with perhaps only 2-3 properties (e.g. date published, author, name of work).

==== web citations design principles ====
Principles driving this proposal:
* '''solve a [[specific]] problem'''. In this case '''web citations''' seeks to solve a ''more'' specific problem than previous proposals, that of citations from the web to the web (more constrained than any publication to any publication).
* [[solve simpler problems first]]. Existing web-to-web citations contain very little information compared to generalized academic citations, thus '''web citations''' is greatly simplified compared to previous proposals by only starting with a handful of properties.
* [[humans first]] - '''web citations''' focuses on the human readability and writability aspects of citations in articles first and foremost, and only secondarily considers the machine readability/reusability of the data contained therein.
* [[reuse]] building blocks - by re-using the better designed aspects of [[citation-formats#styles|existing citation conventions]] for web resources, '''web citations''' builds on top of previous work to make citations human readable/writable, as well as what implied properties are commonly expressed by such previous work.

==== web citation property details ====
(stub)

All web citation properties are derived from the implied schema in [[citation-formats#styles|existing citation styling guides]] for citing permalinks to articles and short text notes online.

Date-time properties (dt-published, dt-accessed) may optionally include time information in addition to the date if relevant to the citation (e.g. when citing short text notes (tweets) of which there may be several in a single day).

To be added:
* for each property, what equivalent TCMOS, APA, MLA terms/vocabulary is being expressed/captured as researched in the [[citation-formats#styles|citation formats styles]] section.
* transforms from the web citations proposal properties into each of those citation styles.
** for citations of blog posts / articles
** for citations of text notes / tweets
** see examples in wild below for markup samples to style in each of the TCMOS/APA/MLA styles for blog/note citations.

==== web citation additional uses ====
The web citation proposal could be used for simple web-to-off-web citation use cases. As suggested by Ed Summers, dropping the hyperlink to the cited web article provides a simple off-web citation:

<syntaxhighlight lang="html">
<span class="h-cite">
<time class="dt-published">YYYY-MM-DD</time>
<span class="p-author h-card">AUTHOR</span>:
<cite class="p-name">TITLE</cite>
</span>
</syntaxhighlight>

Next steps:
* Try such markup with actual content being published on the web (perhaps a bibliography, list of papers in a resume, etc.)
* See how it works/feels there
* Determine what seems to be missing.
* See if the "p-publisher" property helps in some web-to-off-web citation use cases.

==== web citation examples in the wild ====
Real world in the wild examples:
* ... add uses of h-cite you see in the wild here.

Real but not quite wild (use by the brainstorm author)
* Every blog post on http://tantek.com has a text field for copying h-cite markup for that blog post.
* <cite class="h-cite">[http://tantek.com/2012/353/b1/why-html-classes-css-class-selectors Why you should say HTML classes, CSS class selectors, or CSS pseudo-classes, but not CSS classes]</cite> has a couple of interesting uses of h-cite:
** properties used: p-name, u-url, p-author, p-publication, dt-published, dt-accessed (basically all proposed properties except p-content!)
** additional experimental property: p-x-translation - which refers to a nested h-cite with its own implied p-name and implied u-url.
* <cite class="h-cite">[http://christopheducamp.com/blog/test-indieweb-parvenir-a-posser-un-article-vers-twitter/ Test #IndieWeb : Parvenir à « POSSEr » un article vers Twitter]</cite> has an h-cite of a short note:

<syntaxhighlight lang="html">
<blockquote><p>
<cite class="h-cite">
<a class="u-url p-name" href="http://tantek.com/2013/104/t2/urls-readable-speakable-listenable-retypable">
URLs should be readable, speakable, listenable, and unambiguously
retypable, e.g. from print: tantek.com/w/ShortURLPrintExample #UX
</a>
(<abbr class="p-author h-card" title="Tantek Çelik">Çelik</abbr>
<time class="dt-published">2013-04-14</time>)
</cite>
</p></blockquote>
</syntaxhighlight>

==== web citation references ====
I've been iterating on this design for some time, however, first publicly proposed it as the result of an interactive web citation design discussion during IndieWebCamp2012:
* <span class="h-cite"><time class="dt-published">2012-07-01</time> <span class="p-publisher">IndieWebCamp2012</span>: <cite class="p-name">[http://indiewebcamp.com/2012/Academic_Citations_Web Academic Citations for the Web]</cite></span>

----

=== A Prescriptive Proposal ===
([http://microformats.org/wiki/index.php?title=citation&diff=31441&oldid=27502 Contributed 2008-07-09] by [[User:Paramaeleon]] to the [[citation]] page). [[User:Tantek|Tantek]] 19:31, 27 July 2012 (UTC)

Here is a proposal which was derived from what one actually has to give as information in a citation in university work. (I don't know where to put that, so I put it right here.)

First, we need a frame, let's say "hcitation". Multiple citations can be put in a "hcitation" frame. Inside there, we need to describe the type of citation; I suggest "monograph", "anthology", "periodical" , "reference", "thesis" , "standard", "internet", or "specialist".

If a "label" was used to refer to the resource in the text (often in square brackets) it can be named so.

Here comes the list of field names we need: "article", "atime", "author", "ctime", "department", "edition", "editor", "eligibility", "employer", "number", "overalltitle", "pagerange", "part", "place", "publisher", "subseries", "title", "type", "url", "volume", "volumetitle", "year".

The field "page" is to mark up which page you actually quote from. Marking up whatever as "prefix" should give you a hint that this is to be put at first place, but not to refer to when sorting. E.G. "The" should be marked as "prefix" either in "The Crocodile" and also in "Crocodile, the".

<table border="1">
<tr>
<th>Field</th>
<th>Description</th>
<th><code>monograph</code></th>
<th><code>anthology</code></th>
<th><code>periodical</code></th>
<th><code>thesis</code></th>
<th><code>standard</code></th>
<th><code>internet</code></th>
<th><code>specialist</code></th>
</tr>
<tr>
<td><code>article</code></td>
<td>Name of the Article in question</td>
<td align="center"> </td>
<td align="center">3</td>
<td align="center">3</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
</tr>
<tr>
<td><code>atime</code></td>
<td>Last access time for online resources. Use abbr convention for datetime encoding.</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">11</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">5</td>
<td align="center"> </td>
</tr>
<tr>
<td><code>author</code></td>
<td>Creator. Use fn or n markup for every single entity.</td>
<td align="center">1</td>
<td align="center">1</td>
<td align="center">1</td>
<td align="center">1</td>
<td align="center"> </td>
<td align="center">1</td>
<td align="center">1</td>
</tr>
<tr>
<td><code>ctime</code></td>
<td>Date / Last modification. Use abbr convention for datetime encoding.</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">8</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">4</td>
<td align="center">5</td>
</tr>
<tr>
<td><code>department</code></td>
<td>special field / faculty</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">6</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">3</td>
</tr>
<tr>
<td><code>edition</code></td>
<td>Edition information</td>
<td align="center">6</td>
<td align="center">8</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">2</td>
<td align="center"> </td>
<td align="center"> </td>
</tr>
<tr>
<td><code>editor</code></td>
<td>Editors of an anthology. Use fn or n markup for every single entity. Add "transl" for translators and "comp" for compilers</td>
<td align="center"> </td>
<td align="center">4</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
</tr>
<tr>
<td><code>eligibility</code></td>
<td>Qualification of a specialist</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">2</td>
</tr>
<tr>
<td><code>employer</code></td>
<td>Name of university eg.</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">4</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">4</td>
</tr>
<tr>
<td><code>number</code></td>
<td>Number</td>
<td align="center">10</td>
<td align="center">12</td>
<td align="center">9</td>
<td align="center"> </td>
<td align="center">1</td>
<td align="center"> </td>
<td align="center"> </td>
</tr>
<tr>
<td><code>overalltitle</code></td>
<td>Overall Title / Title of series</td>
<td align="center">9</td>
<td align="center">11</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">8</td>
</tr>
<tr>
<td><code>pagerange</code></td>
<td>Page range of an article in an anthology / periodical</td>
<td align="center"> </td>
<td align="center">13</td>
<td align="center">10</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
</tr>
<tr>
<td><code>part</code></td>
<td>Part of article (if having several parts)</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">4</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
</tr>
<tr>
<td><code>place</code></td>
<td>Place of publication</td>
<td align="center">7</td>
<td align="center">9</td>
<td align="center"> </td>
<td align="center">5</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
</tr>
<tr>
<td><code>publisher</code></td>
<td>Publication house</td>
<td align="center">8</td>
<td align="center">10</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
</tr>
<tr>
<td><code>subseries</code></td>
<td>Name of subseries, if any</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">6</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
</tr>
<tr>
<td><code>title</code></td>
<td>The main title. Anthology: name of anthology. Periodical: name of periodical</td>
<td align="center">3</td>
<td align="center">5</td>
<td align="center">5</td>
<td align="center">3</td>
<td align="center">3</td>
<td align="center">3</td>
<td align="center">6</td>
</tr>
<tr>
<td><code>type</code></td>
<td>Type (type of thesis or type of utterance (radio interview, e-mail, ...) of a specialist)</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">7</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">7</td>
</tr>
<tr>
<td><code>url</code></td>
<td>URL</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">12</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center">6</td>
<td align="center"> </td>
</tr>
<tr>
<td><code>volume</code></td>
<td>Volume information (eg. Vol. 22)</td>
<td align="center">4</td>
<td align="center">6</td>
<td align="center">7</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
</tr>
<tr>
<td><code>volumetitle</code></td>
<td>Volume title</td>
<td align="center">5</td>
<td align="center">7</td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
<td align="center"> </td>
</tr>
<tr>
<td><code>year</code></td>
<td>Year of appearance. 4 digit year. Use abbr convention for datetime encoding.</td>
<td align="center">2</td>
<td align="center">2</td>
<td align="center">2</td>
<td align="center">2</td>
<td align="center"> </td>
<td align="center">2</td>
<td align="center"> </td>
</tr>
</table>

This table shows what has to go together. Numbers give the typical ordered structure of the values. Other Information than given here (eg. ISBN, ...) actually has not to be put into citations, students would recive negative evaluations if they do so. (I hope this will help somehow. sorry for bad english.)

==== Sample Usage ====

<pre><nowiki>
<h1>The Bibliography</h1>

<table class="hcitation">
<tr>
<th scope="row" style="font-variant: small-caps; ">[MR06]</th>
<td class="monograph">
<a name="sr06">
<span class="author firstauthor">
<span class="family-name" style="font-variant: small-caps; ">Miller</span>,
<span class="given-name">Michael</span>
<span class="additional-name">C.</span>
</span> ;
<span class="author">
<span class="given-name">Mathew</span>
<span class="family-name" style="font-variant: small-caps; ">Roth</span>
</span>
(<span class="year">2006</span>):
<span style="font-style: italic; ">
<span class="title">Students' Jokes : A complete collection of jokes students laugh about</span>.
Vol. <span class="volume">23</span>:
<span class="volumetitle">Computational Linguists' Jokes</span>.
</span>
<span class="edition">4th completely revised Edition</span>.
<span class="place">München</span> :
<span class="publisher">Weltbild</span>
(<span class="overalltitle">Fictional publications of munich's students</span>
<span class="number">2675</span>)
</a>
</td>
</tr>
<tr>
<th scope="row" style="font-variant: small-caps; ">[R08a]</th>
<td class="anthology">
<a name="r08a">
<span class="author firstauthor">
<span class="family-name" style="font-variant: small-caps; ">Roth</span>,
<span class="given-name">Mathew</span>
</span>
(<span class="year">2008</span>):
&bdquo;<span class="article">Using semantic HTML for bibliographic citations</span>.“
In:
<span class="editor">
<span class="given-name">Michael</span>
<span class="additional-name">B.</span>
<span class="family-name" style="font-variant: small-caps; ">Smith</span>
</span> ;
<span class="editor">
<span class="given-name">John</span>
<span class="family-name" style="font-variant: small-caps; ">Miller</span>
</span>
(Eds.)
(<span class="year">2008</span>):
<span style="font-style: italic; ">
<span class="title">Being POSH : Usage of semantic HTML in web pages</span>.
Vol. <span class="volume">4</span>:
<span class="volumetitle">Whatever you read</span>.
</span>
<span class="edition">1st Edition</span>.
<span class="place">New York</span> :
<span class="publisher">Public Press</span>
(<span class="overalltitle">Books on data processing</span>
<span class="number">1435</span>)
</a>
</td>
</tr>
<tr>
<th scope="row" style="font-variant: small-caps; ">[R08b]</th>
<td class="periodical">
<a name="r08b">
<span class="author firstauthor">
<span class="family-name" style="font-variant: small-caps; ">Roth</span>,
<span class="given-name">Mathew</span>
</span>
(<span class="year">2008</span>):
&bdquo;<span class="article">Using semantic HTML in scientific work</span>.“
P. <span class="part">1</span>; P. <span class="part">2</span>.
In:
<span style="font-style: italic; ">
<span class="title">The Computational Linguist</span>.
</span>
<span class="subseries">Development of the Semantic Web</span>.
<span class="volume">2</span>
(<span class="ctime">2008</span>)
No. <span class="number">16</span>,
Pp. <span class="pagerange">124–131</span>
(Access: <span class="atime"><abbr title="20080714T1612+0200">14.07.2008 16:12 CEST</abbr></span>)
<<span class="url">http://www.sample.url/web/address/1234.pdf</span>>
</a>
</td>
</tr>
<tr>
<th scope="row" style="font-variant: small-caps; ">[S07]</th>
<td class="thesis">
<a name="s07">
<span class="author firstauthor">
<span class="family-name" style="font-variant: small-caps; ">Smith</span>,
<span class="given-name">John</span>
</span>
(<span class="year">2007</span>):
<span style="font-style: italic; ">
<span class="title">Semantic Data Extraction from the World Wide Web</span>.
</span>
<span class="employer">University of <span class="place">Munich</span></span>,
<span class="department">Department of Computational Linguistics</span>,
<span class="type">Diss.</span>
</a>
</td>
</tr>
<tr>
<th scope="row" style="font-variant: small-caps; ">[SVG11]</th>
<td class="standard">
<a name="svg11">
<span class="number">ISO 1234567</span>
(<span class="edition">1-2003</edition>):
<span style="font-style: italic; ">
<span class="title">Scalable Vector Graphics (SVG) 1.1 Specification</span>.
</span>
</a>
</td>
</tr>
<tr>
<th scope="row" style="font-variant: small-caps; ">[Wik08]</th>
<td class="internet">
<a name="wik08">
<span class="author firstauthor">
<span class="family-name" style="font-variant: small-caps; ">Wikipedia, the free encyclopedia</span>,
</span>
(<span class="year">2008</span>):
<span style="font-style: italic; ">
<span class="title">Microformat</span>.
</span>
(Version: <abbr class="ctime" title="2008-06-19">19th June 2008</abbr>.
Access: <abbr class="atime" title="20080703T1423+0200">3rd July 2008 14:23 CEST</abbr>)
<<a href="http://en.wikipedia.org/w/index.php?title=Microformat&oldid=220275451" class="url">http://en.wikipedia.org/w/index.php?title=Microformat&oldid=220275451</a>>
</a>
</td>
</tr>
<tr>
<th scope="row" style="font-variant: small-caps; ">[W08]</th>
<td class="specialist">
<a name="w08">
<span class="author firstauthor">
<span class="family-name" style="font-variant: small-caps; ">Wang</span>,
<span class="given-name">Wu</span>
</span>
(<span class="eligibility">Professor of Informatics</span>,
<span class="department">Department of Applied Sciences</span>,
<span class="employer">University of Michigan</span>)
(<abbr class="ctime" title="20000801T0918+0100D0007">01.08.2000, 9:18–9:25 MEZ</abbr>)
<span class="title">Science News</span>.
<span class="type">Interview</span>.
<span class="overalltitle">Michigan Television</span>
</a>
</td>
</tr>
</table>
</nowiki></pre>

----

=== XHTML Structure ===
With my exprience working X2V and hCa* has taught me what elememts are easy to find and which are not. Since the Citation microformat is very new it is possible to not make a lot of the same errors twice and to make things easier for extracting application to find and imply certain properties.

* There should be some sort of 'root node' that implies all child elements are for the hCitation microformat.
* Since most people will have multiple citations there should be away to represent each hCitation object as a unqiue block independent of another. This is to keep the parse from finding 'author' and applying that to all citations. Each citation should be in a container (class="hcite") that is separated from others.
* Perhaps class="hcite" with <code><cite></code> recommended as the root element. E.g. <code><cite class="hcite"></code>

'''Note: This section was the original content of the document. Since then, class='hcite' has been agreed on as the root class name. See [http://microformats.org/wiki?title=citation-brainstorming#.27hcite.27_as_Root_Element_name explanation].'''

----

=== how to use with HTML5 ===
Per [http://lists.w3.org/Archives/Public/public-html/2009Jun/0811.html Theresa O'Connor's email to public-html]:
Add a section in the citation microformat describing how to use the citation microformat in [[HTML5]], including optional use of HTML5's <time> element and microdata feature. Encourage [[HTML5]] to drop the "BibTeX" predefined microdata vocabulary and reference an updated citation microformat spec instead. [[User:Tantek|Tantek]]

----

=== OCLC's WorldCat for titles ===
Question: what about using something like OCLC's [http://www.oclc.org/worldcat/open/isbnissnlinking/default.htm WorldCat] for linking titles? - Tim White

----

=== This and That ===
After reading through alot of different citation encoding formats, i noticed that each format was being used in one of two ways. It was either to describe the Current page (THIS.PAGE) or being used to encode references that point to external resources (THAT.PAGE)

The informatation being encoded was identical for both resources (author, date, name, etc) they just reference different things. For this microformat, i'm not sure if we want to try to solve both problems, or just one? The meta tags in the head element would be the ideal place for information about the THIS.PAGE, but that is not in following with the ideals of microformats where information is human-readable. The THAT.PAGE idea where a list of references is at the end of a document in the form of a bibliography is more inline with the ideals of a microformat where the data is human-readable. That doesn't mean that data about the current document shouldn't be human-readable, so some of the same properties used to reference extermal resources can be used for the current document (THIS.PAGE). To do this a different root item could be used and transforming applications could either extract the citation data about the current page, or information about this page's references.

This is open for discussion, but either way, i believe that the properties used to describe a page will be the same for both THIS and THAT. [http://suda.co.uk/ brian suda]

==== More on This and That ====
Citation microformats are being explored as a possibility for citing genealogical information at [http://eatslikeahuman.blogspot.com Dan Lawyer's blog].

This is a case where frequently the citation would refer to (THIS.PAGE), but would have nested within it a reference to (THAT.PAGE), possibly a few levels deep. For instance, a web page might contain data extracted from a microfilm of a census. The citation would need to include information about the web page, information about the microfilm, and information about the census. Genealogical citations are expected to include the repository (where can this book or microfilm be found. Is this the same as ''venue''?). So, at each level the information should contain the repository of the referenced item. A nesting (recursive) mechanism for citation microformats would be useful in this case. Is this the function of the "container" element in the Straw Format?

----

=== MARC / MODS / Dublin Core ===
The MODS ([http://www.loc.gov/standards/marcxml/Sandburg/sandburgmods.xml example]) and Dublin Core ([http://www.loc.gov/standards/marcxml/Sandburg/sandburgdc.xml example]) transformations of MARC21 may contain some useful ideas.

Here's a first attempt at rewriting the linked examples in XHTML (written in response to a [http://microformats.org/discuss/mail/microformats-discuss/2005-December/002438.html mailing list query about encoding book information with microformats]):

<pre><nowiki>
<div class="book" lang="en">
<h3 class="fn">Arithmetic /</h3>
<p>By <span class="creator"><span class="fn">Sandburg, Carl</span>,
<span class="date">1878-1967</span></span>,
and <span class="illustrator">Rand, Ted</span></p>
<p>Publisher: <span class="publisher"><span class="fn">Harcourt Brace Jovanovich</span>,
<span class="locality">San Diego</span></span></p>
<p>Published: <span class="issued">1993</span></p>
<p class="description">A poem about numbers and their characteristics. Features
anamorphic, or distorted, drawings which can be restored to normal by viewing
from a particular angle or by viewing the image's reflection in the provided
Mylar cone.</p>
<p class="note">One Mylar sheet included in pocket.</p>
<p>Subjects:</p>
<ul>
<li class="subject">Arithmetic</li>
<li class="subject">Children's poetry, American.</li>
<li class="subject">Arithmetic</li>
<li class="subject">American poetry</li>
<li class="subject">Visual perception</li>
</ul>
</div>
</nowiki></pre>

== comparison and use of other microformats ==
=== Citation vs. [[media-info]] ===
What distinguishes a cite from say [[media-info]] (e.g. [[media-info-examples]]) is that a cite is a reference to something explicitly external to the current piece of content or document, whereas [[media-info]] describes information about content embedded or inline in the current document.

=== Date Formatting ===
Since microformats are all about re-use and the accepted way to encode Date-Time has been pretty much settled, then this is a good place to start when dealing with all the different date citation types.

These are all the different fields from various citation formats that are of temporal nature:
* Date (available | created | dateAccepted | dateCopyrighted | dateSubmitted | issued | modified | valid)
* originInfo/dateIssued
* originInfo/dateCreated
* originInfo/dateCaptured
* originInfo/dateOther
* month
* year
* Copyright Year
* Date - Generic
* Date of Confernce
* Date of Publication
* Date of update/revisou/issuance of database record
* Former Date
* Entry Date for Database Record
* Database Update
* Year of Publication

There are several common properties across several citation domains and will certainly be in the citation microformat, the unique instances will need further consideration, otherwise there could be no end to posiblities.

There are also several properties (year, month, Year of publication) that can be extracted from another source. Therefore, if you only encode a more specific property such as; Date of Publication, you can extract the 'year of publication' from that. Since the date-time format we are modeling after is the ISO date-time format, just the Year portion is an acceptable date. So if you ONLY know the year of publication, the you can form a valid 'Date of Publication' as a microformat (which inturn is a valid 'year of publication') - you milage may vary when it comes to importing into citation applications.

...

It seems to me that these can be collapsed to maybe one or two different date properties. As far as the specific human readable formatting of the date, that can be chosen per whatever the presentation style guide says, and the [[datetime-design-pattern]] used to simplify the markup. - Tantek

'''Important'''
Sometimes we need a date range and not simply a date (e.g. 4-6 May 2006). See ''Conference Citation'' examples later on this page. - Discoleo

'''Seasons'''
Some journals have seasonal issues (e.g. "Summer 2006 edition") instead of, or as well as, editions labelled by month or other calendar-date. [[User:AndyMabbett|AndyMabbett]] 05:05, 4 Nov 2006 (PST)

=== Tags ===
Some of the citation formats has a place for 'keywords' or 'generic tags', etc. This might be a good place to re-use the [http://microformats.org/wiki/rel-tag RelTag microformat]. The downside would be that they are then forced to be links, which might be the correct way to mark-up these terms.

== past discussions ==
=== Original hBib Discussion ===
During the WWW2005 Developer's Day [[microformats]] track, Rohit Khare gave a [[presentations|presentation]] where he discussed the microformats [[process]], and then did a quick demonstration wherein a bunch of us got on a shared Subethaedit document, and brainstormed some thoughts on what an "hBib" bibliography citation microformat would look like. Rohit placed the [http://cnlabs.commerce.net/~rohit/hBib%20Discussion.html document on his Commercenet site].

* [[hBib Discussion]]

''An attempt to summarize and inline the linked document follows. -Mike''

Two major goals were outlined by the group:

* Avoid re-keying references
* Adapt to new journal styles by changing CSS

The fundamental problem was discussed in terms of display - the ability to transform XHTML+hBib into the many journal-specific formats. For example, how to display "et.al" when all authors are present in the source, and how to re-order the elements if a style defines a set order of elements that conflicts with the ordering in the source. Using hCard for authors was agreed on, and the beginnings of an example were shown.

== Outstanding Issues ==
See [[citation-issues]].

== Examples in the wild ==
Pages which start to use the discussion above to create working examples in using hcite:
(This section could be used as a base for a page like "hcite-examples-in-wild" later).

Please add new examples to the top of this section.
* [http://www.demo.vorlagen.uni-erlangen.de/univis/mitarbeiter.shtml/georg-hager.shtml Example User Page] at the regional computer lab Erlangen, Germany, based on the universal information system UnivIS marked up with vcard, hcalender (optional, if user makes a lecture) and hcite.

== discussions ==
* [[citation-irc-notes-2006-04-09]]

== See also ==
{{citation-related-pages}}

measure-brainstorming

2023-07-26T21:06:07Z

GRegorLove: s/<source>/<syntaxhighlight>/

= Measure Microformat Brainstorming =

This page collects ideas on how to use semantic XHTML to represent unambiguously [[measure]]s.

== HTML proposals ==
There is some evidence of past proposals to add measures/quantities directly to HTML, which should be considered in the context of any overall markup solution:

=== quantity element ===
https://lists.w3.org/Archives/Public/public-whatwg-archive/2009Aug/0234.html proposed a quantity element
<pre>
[…]

I've been looking at the meter element, which specifically states that
"There is no explicit way to specify units in the meter element, but the
units may be specified in the title attribute in free-form text."

Having used the web for the past 15 years I've always felt that it's a
shame when you run into a page with a set of measurements and those
can't be interpreted automatically in a sensible fashion. Especially
with the fact that there are both imperial and metric units still around
in this day and age.

An backwards compatible inline element to specify a quantity would be
rather trivial:

<quantity unit="cm">12 cm</quantity>
<quantity unit="kg">2 kg</quantity>

With this implementation a number inside the quantity element would be
interpreted as the numerical value of the unit. Other characters would
be ignored.

[…]
</pre>

== microformats2 ==

Problem: no existing microformats-2 structures can represent [[measure]] values.

=== Proposal: <code>h-measure</code>, <code>h-angle</code>, <code>h-money</code> ===

Based on existing [[#Draft_Schema|old draft schema]]

==== Example Readable Text ====

<pre>
weighs 79.3kg

100W Light Bulb

Price: $9.90
</pre>

==== Example Markup ====
<syntaxhighlight lang="html">
<span class="h-measure">
<data class="p-type" value="weight">weighs</data>
<data class="p-num" value="79300">79.3</data><data class="p-unit" value="g">kg</data>
</span>

<span class="h-measure">
<span class="p-num">100</span><span class="p-unit">W</span>
<span class="item">Light Bulb</span>
</span>

<span class="h-money">
<span class="p-type">Price</span>:
<data class="p-unit" value="USD">$</data><span class="p-num">9.90</span>
</span>
</syntaxhighlight>

==== Example Parsed JSON ====
<syntaxhighlight lang="json">
{
"type": [
"measure"
],
"properties": {
"num": [79300],
"unit": ["g"],
"type": ["weight"]
}
}

{
"type": [
"measure"
],
"properties": {
"num": [100],
"unit": ["W"],
"item": ["Light Bulb"]
}
}

{
"type": [
"money"
],
"properties": {
"num": [9.90],
"unit": ["USD"]
"type": ["price"]
}
}
</syntaxhighlight>

==== Issues ====

* The type of measurement is not always written out in the english version. This requires the addition of a property that may not have been in the sentence to specify "weight" for example.
* Requires three new root-level definitions (measure, angle, money)

=== Proposal: <code>m-*</code> values ===

Based on the existing proposed <code>n-*</code> prefix documented here: [[microformats2-prefixes#prefixes_for_future_consideration]]

==== Example Readable Text ====

<pre>
79.3kg

100W Light Bulb

Price: $9.90
</pre>

==== Example Markup ====
<syntaxhighlight lang="html">
<span class="m-weight">
<data class="p-num" value="79300">79.3</data><data class="p-unit" value="g">kg</data>
</span>

<span class="m-power">
<span class="p-num">100</span><span class="p-unit">W</span> <span class="p-item">Light Bulb</span>
</span>

Price: <span class="m-price"><data class="p-unit" value="USD">$</data><span class="p-num">9.90</span></span>
</syntaxhighlight>

==== Example Parsed JSON ====
<syntaxhighlight lang="json">
{
"weight": [
{
"type": [
"measure"
],
"properties": {
"num": [79300],
"unit": ["g"]
}
}
]
}

{
"power": [
{
"type": [
"measure"
],
"properties": {
"num": [100],
"unit": ["W"],
"item": ["Light Bulb"]
}
}
]
}

{
"price": [
{
"type": [
"measure"
],
"properties": {
"num": [9.90],
"unit": ["USD"]
}
}
]
}
</syntaxhighlight>

==== Issues ====

* Requires the definition of a "type" in order for the value to have a property name in the parsed JSON.
* How to indicate the measure type (standard, angular, money)? Or is this distinction even important?

=== Proposal: <code>h-measure</code> named with <code>p-*</code> ===

This is basically a combination of the two above, dropping the individual types (standard, angular, money) in favor of just using "measure", and allowing these properties to be named the same way the author of an [[h-entry]] is named using <code>p-author</code>.

==== Example Readable Text ====

<pre>
weighs 79.3kg

100W Light Bulb

Price: $9.90
</pre>

==== Example Markup ====
<syntaxhighlight lang="html">
Standalone measure: <span class="h-measure">
<span class="p-name">Weight of a widget</span>: <data class="p-num">1.5</data><data class="p-unit">kg</data>
</span>

Example as properties of an h-card:

<div class="h-card">
<span class="p-name">Joe Bloggs</span>

weighs
<span class="h-measure p-weight">
<data class="p-num" value="79300">79.3</data><data class="p-unit" value="g">kg</data>
</span>
</div>

<div class="h-product">
Price as property of an h-product:
<span class="h-measure p-price">
<data class="p-unit" value="USD">$</data><span class="p-num">9.90</span>
</span>
</div>
</syntaxhighlight>

==== Example Parsed JSON ====
<syntaxhighlight lang="json">
{
"items": [
{
"type": [
"h-measure"
],
"properties": {
"name": [
"Weight of a widget"
],
"num": [
"1.5"
],
"unit": [
"kg"
]
}
},
{
"type": [
"h-card"
],
"properties": {
"weight": [
{
"type": [
"h-measure"
],
"properties": {
"num": [
"79300"
],
"unit": [
"g"
],
"name": [
"79.3kg"
]
},
"value": "79.3kg"
}
],
"name": [
"Joe Bloggs"
]
}
},
{
"type": [
"h-product"
],
"properties": {
"price": [
{
"type": [
"h-measure"
],
"properties": {
"unit": [
"USD"
],
"num": [
"9.90"
],
"name": [
"$9.90"
]
},
"value": "$9.90"
}
],
"name": [
"Price as property of an h-product: \r\n \r\n $9.90"
]
}
}
]
}</syntaxhighlight>

==== Issues ====

<div class="discussion">
* There is no distinction between "standard", "angular" and "money" types other than the units present. This may or may not be important, need to gather some use cases and examples for each. [[User:Aaronpk|Aaronpk]] 20:07, 16 June 2013 (UTC)
* If there is no <code>p-*</code> property defined, the <code>h-measure</code> will end up in the "children" array. [[User:Aaronpk|Aaronpk]] 20:07, 16 June 2013 (UTC)
* This only works when h-measure is a child microformat, i.e. the example given actually makes no sense. But otherwise I feel this is the sanest proposal --[[User:Barnabywalters|bw]] 20:05, 16 June 2013 (UTC)
** If the <code>p-*</code> property is omitted and the <code>h-measure</code>, wouldn't this just become a new top-level item in the <code>items</code> array? [[User:Aaronpk|Aaronpk]] 20:07, 16 June 2013 (UTC)
*** I updated the examples showing how this could work standalone and/or as a property with live output from php-mf2 --[[User:Barnabywalters|bw]] 20:23, 16 June 2013 (UTC)
</div>

=== Examples in the Wild ===

* [[User:Aaronpk|aaronpk]] publishes his weight: http://aaronparecki.com/metrics
* https://www.jerrysv.xyz/ publishes environmental measurements on the home page
** including radiation levels with an accuracy amount: <code>0.0785 +/- 0.0087</code>

= Old pre-mf2 brainstorming =

== Draft Schema==

Rationale: The names "type" and "item" are taken from [[hReview]].

{{OpenIssue}} Is <code>tolerance</code> needed? It is useful for some circumstances, but perhaps not common enough to be included in the spec.
{{OpenIssue}} A <code>dtmeasured</code> property may be useful, especially for <code>hmoney</code>, as prices fluctuate.

=== Standard Measure Schema ===

* '''<code>hmeasure</code>'''
** '''<code>num</code>''' {1} (numeric)
** '''<code>unit</code>''' {1} (unit)
** <code>item</code>? (text | [[hcard|hCard]] | [[hcalendar|hCalendar]])
** <code>type</code> ? (text, e.g. "height", "width", "weight")
** <code>tolerance</code> ? (percentage | hmeasure)

=== Angular Measure Schema ===

* '''<code>hangle</code>'''
** '''<code>num</code>''' {1} (degree)
** <code>item</code>? (text | [[hcard|hCard]] | [[hcalendar|hCalendar]])
** <code>type</code> ? (text, e.g. "angle of elevation")
** <code>tolerance</code> ? (percentage | hangle)

=== Money Schema ===

* '''<code>hmoney</code>'''
** '''<code>num</code>''' {1} (numeric)
** '''<code>unit</code>''' {1} ([http://en.wikipedia.org/wiki/ISO_4217 ISO 4217 code])
** <code>item</code>? (text | [[hcard|hCard]] | [[hcalendar|hCalendar]])
** <code>type</code> ? (text, e.g. "price", "salary", "exchange rate")
** <code>tolerance</code> ? (percentage | hmoney)

== <tt>num</tt>: The Value ==

Arbitrary white space {{may}} be included in the value to improve readability (but only when the <code>num</code> class is explicitly used — not when mimimisation is employed). Parsers {{must}} strip out all white space before further processing.

In the standard and money schemas, the value {{must}} be a number, formatted according to the following EBNF pattern:

<pre>non-zero-digit = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
digit = "0" | non-zero-digit ;
natural = non-zero-digit , {digit} ;
integer = "0" | [ "-" ] , natural ;
dot-decimal = integer , "." , {digit} ;
comma-decimal = integer , "," , {digit} ;
e-sign = "e" | "E" ;
mantissa = dot-decimal | comma-decimal | integer ;
sci-number = mantissa , e-sign , integer ;
number = dot-decimal | comma-decimal | integer | sci-number ;</pre>

This roughly corresponds to a subset of [http://en.wikipedia.org/wiki/C_syntax#Floating_point_types C syntax] for floating points and integers, excluding octal and hexadecimal representations. However, note that both commas and stops may be used as decimal points.

The Unicode minus sign (U+2212) and ASCII-compatible hyphen-minus (U+002D) {{must}} both be treated as acceptable indicators of a negative number. In addition, the symbols ¼ (U+00BC), ½ (U+00BD) and ¾ (U+00BE) {{should}} be supported as aliases for 0.25, 0.5 and 0.75 respectively.

In the angular measure schema, a measure is expressed as a combination of up to three numeric components: called degrees, minutes and seconds. Any combination of these components may be used, except when degrees and seconds are given minutes {{must}} be present. The components {{must}} appear in the correct order (degrees, minutes, seconds). Each component must match the production rule for "mantissa" above, with the following additional constraints:

* Only the first component can bear a minus sign. Subsequent components "inherit" the negativity (or lack thereof) from their predecessors.
* All components except the last must match the production rule for "integer".

The numeric components {{must}} be indicated by appending a suffix to each component. Valid suffixes are:

* degree: "deg", U+00B0 degree symbol (°)
* minute: "min", straight single quote ('), U+2032 prime (′)
* second: "sec", straight double quote ("), U+2033 double prime (″)

=== Examples ===

* 1729 (the smallest number that can be expressed as the sum of two cubes in two different ways)
* 1.61803399 (the golden ratio)
* 2,99792458e8 (the speed of light in a vacuum, measured in metres per second)
* -40 (value at which Celcius and Farenheit scales are equal)
* 1,000,000,000 (''Invalid:'' commas may be used as decimal points, but not for grouping thousands.)
* 57.2958 deg (1 radian, in degrees)
* -57° 17′ 45.1″ (-1 radian, in degrees, minutes and seconds)
* 4° 30″ (''Invalid'': no minutes)
* 4° -30′ (''Invalid'': only first component may be negative)

=== Issues ===

{{ClosedIssue}} Will the name of this class (<tt>value</tt>) cause problems for parsers due to [[hcard-parsing|value excerpting]]?
* Changed <tt>value</tt> to <tt>num</tt>

{{OpenIssue}} What about 5′ 10″ used to mean 5 foot, 10 inches?
* Possible solution:
<pre><abbr title="70 inch">5′ 10″</abbr></pre>

== <tt>unit:</tt> The Unit of Measurement ==

In the standard schema, the "unit" class is defined as an arbitrary string.

=== SI Units ===

Any unit may be used, but authors {{should}} attempt to use official SI units of measurement where appropriate.

Parsers that treat the unit as anything other than an opaque string {{should}} recognise the following case-sensitive list of units, derived from the SI list of base units and common derived units, with the addition of bits and bytes, which are commonly used on web pages. (Note that gram appears in this table instead of kilogram. This is deliberate.)

{| border="1" style="float:left"
|-
! Unit
! Symbols
! Aliases
|-
| metre
| m
| meter
|-
| gram
| g
| gramme
|-
| second
| s, sec
|-
| ampere
| A
| amp
|-
| candela
| cd
|-
| mole
| mol
|-
| kelvin
| K, K (U+212A)
|-
| newton
| N
|-
| pascal
| Pa
|-
| joule
| J
|-
| watt
| W
|-
| coulomb
| C
|-
| volt
| V
|-
| ohm
| Ω (U+03A9), Ω (U+2126)
|-
| siemens
| S
|-
| farad
| F
|-
| weber
| Wb
|-
| henry
| H
|-
| tesla
| T
|-
| hertz
| Hz
|-
| byte
| B
|-
| bit
| b
|-
| litre
| L, l, ℓ (U+2113)
| liter
|-
| Celsius
| ℃ (U+2103), °C (U+00B0 followed by captial C)
|-
| radian
| rad
|-
| lumen
| lx
|-
| becquerel
| Bq
|-
| gray
| Gy
|-
| sievert
| Sv
|-
| katal
| kat
|-
| steradian
| sr
|}

{| border="1" style="float:left;margin-left:1.5em;"
! 10<sup>n</sup>
! Prefix
! Symbol
|-
| 10<sup>24</sup>
| yotta-
| Y
|-
| 10<sup>21</sup>
| zetta-
| Z
|-
| 10<sup>18</sup>
| exa-
| E
|-
| 10<sup>15</sup>
| peta-
| P
|-
| 10<sup>12</sup>
| tera-
| T
|-
| 10<sup>9</sup>
| giga-
| G
|-
| 10<sup>6</sup>
| mega-
| M
|-
| 10<sup>3</sup>
| kilo-
| k
|-
| 10<sup>2</sup>
| hecto-
| h
|-
| 10<sup>1</sup>
| deca-
| da
|-
| 10<sup>0</sup>
| (none)
| (none)
|-
| 10<sup>−1</sup>
| deci-
| d
|-
| 10<sup>−2</sup>
| centi-
| c
|-
| 10<sup>−3</sup>
| milli-
| m
|-
| 10<sup>−6</sup>
| micro-
| µ (U+00B5), μ (U+03BC), u
|-
| 10<sup>−9</sup>
| nano-
| n
|-
| 10<sup>−12</sup>
| pico-
| p
|-
| 10<sup>−15</sup>
| femto-
| f
|-
| 10<sup>−18</sup>
| atto-
| a
|-
| 10<sup>−21</sup>
| zepto-
| z
|-
| 10<sup>−24</sup>
| yocto-
| y
|}

<br style="clear:both">

The full names and for SI prefixes {{should}} only be combined with the full names for the units (or their aliases). Likewise the symbols for SI prefixes {{should}} only be combined with the symbols for the units.

* kilometre
* milligramme
* μL
* mΩ
* microV (''not recommended'')
* kgram (''not recommended'')

==== Combining units ====

Units may be multiplied by separating with whitespace, or divided using a slash (/) or U+2215 division slash (∕). Units may be raised to an integer power using a caret character. The unicode superscript numerals 2 to 9 (U+00B2, U+00B3, U+2074-79) {{must}} be supported as aliases for raising to the appropriate integer powers. Multiplication is more associative than division.

Examples:

* <span class="unit">kg m / s</span>
* <span class="unit">m/s^2</span>
* <span class="unit">meter³</span>
* <abbr class="unit" title="μm">micron</abbr>

=== Angular units ===

Units {{must not}} be given for measurements expressed in the degree schema: the degree itself is the unit. If the standard schema is used, units may be given in radians (rad).

=== Other / Non-SI Units ===

Authors {{may}} specify units other than those defined above, but {{should not}} assume that parsers will be able to interpret them. Authors using other units {{may}} provide a [[existing-rel-values|rel=glossary]] link to a page or fragment that defines the units.

==== Explicitly Defining a Unit ====

hmeasure may be used with the <dfn> element to explicitly define a unit in terms of pre-defined units. The "title" attribute (if any) is taken to be an alias of the unit name.

<pre><p class="hmeasure" id="dfn-inch">
An <dfn class="item" title="in">inch</dfn> is defined as
<span class="num">0.0254</span> <span class="unit">m</span>.
</p></pre>

Other instances of hmeasure may then refer to this definition, implicitly:

<pre><p class="hmeasure">
The <span class="item">action figure</span> has a <span class="type">height</span> of
<span class="num">5</span> <span class="unit">in</span>.
</p></pre>

or explicitly:

<pre><p class="hmeasure">
The <span class="item">action figure</span> has a <span class="type">height</span> of
<span class="num">5</span>
<a class="unit" rel="glossary" href="#dfn-inch">in</a>.
</p></pre>

{{OpenIssue}} Farenheit is reasonably common in some parts of the world. As °C and °F do not share their zero points, it is impossible to use this pattern to define °F. °F thus remains an opaque string with no meaning assigned to it my this spec. Should we add it to the list of pre-defined units?

=== Currency Units ===

If the money schema is being used, the unit is not an arbitrary string. It {{must}} be a three-letter ISO 4217 code. The following aliases for the four largest reserve currencies (as of 2008) are allowed:

{| border="1"
|-
! Unit
! Aliases
|-
| EUR
| €
|-
| GBP
| £
|-
| JPY
| ¥
|-
| USD
| $
|}

Other currencies {{may}} be displayed using these symbols only through the [[abbr-design-pattern|ABBR design pattern]]:

<pre><span class="hmoney">
<abbr class="unit" title="AUD">$</abbr><span class="num">5.00</span>
</span></pre>

== <tt>item</tt>: The Thing Being Measured ==

An hCard, hCalendar event or textual description of the item being measured may be supplied.

<pre><p class="hmeasure">
<span class="item vcard">The <span class="fn">Great Wall</span>of
<span class="adr"><span class="country-name">China</span></span></span>
is about <span class="num">6 700</span> <abbr title="km">kilometres</abbr>
<abbr title="length" class="type">long</abbr>.
</p></pre>

If the item is not an hCard, hCalendar component or other recognised embedded microformat, then its contents are taken to be a string.

The item is optional.

=== The Item URI ===

If the item is not an embedded hCard or hCalendar event, and is an <code><a></code> element or other linking element, then parsers should parse the URI ''and'' the node contents. The item URI is considered a significant way of determining what entity the hmeasure is describing. For example:

* If the item URI matches the UID for a known contact (e.g. an hCard somewhere on the page, or another page being parsed) then the hmeasure is taken to describe this contact (i.e. person, organisation, etc).
* A similar meaning can be implied when the item URI matches the UID for a known hCalendar event.

For example:

<pre><nowiki>
<div class="vcard">
<a href="fn url uid" href="http://alice.example.net">Alice Jones</a>,
<span class="adr">
<span class="locality">Sydney</span>,
<span class="country-name">Australia</span>.
</span>
</div>
... further down the page ...
<span class="hmeasure">
<a class="item" href="http://alice.example.net">Alice's</a>
<span class="type">height</span> is
<span class="num">180</span> <span class="unit">cm</span>
</span>
</nowiki></pre>

== <tt>type</tt>: The Dimension ==

The type specifies the dimension being measured. A measurement in, say, metres may be ambiguous because it could refer to a depth, a height, a length or a width. The optional type parameter allows you to specify a human-readable dimension.

== <tt>tolerance</tt>: The Error Tolerance ==

An optional tolerance may be specified as a percentage or as a nested hmeasure/hmoney.

Examples:

<pre><span class="hmeasure">
<span class="type">Height</span>:
<span class="num">5</span> <span class="unit">m</span>
± <span class="tolerance">2%</span>
</span></pre>

<pre><span class="hmoney">
<span class="unit">$</span><span class="num">5.00</span>
± <span class="tolerance hmoney"><span class="unit">$</span><span class="num">1.00</span></span>
</span></pre>

When no tolerance is provided, a default tolerance of 0% {{must not}} be assumed — the tolerance is simply unknown.

== Minimisation Techniques ==

=== hmeasure ===

If no <tt>num</tt> is given, then the first number conforming to the EBNF above is taken to be the numerical value of the measurement. If no unit is given, then the entire string within the "hmeasure" (less the numerical value, item, type and tolerance) is taken to be the unit.

For example:
<pre><span class="hmeasure">3 pints <span class="item">beer</span></span></pre>
* '''Num:''' 3
* '''Unit:''' "pints"
* '''Item:''' "beer"

<pre><span class="hmeasure">4 m</span></pre>
* '''Num:''' 4
* '''Unit:''' metre

{{OpenIssue}} What about cases where there is no white space? SI says white space should always separate the quantity and unit, but in practice, many people do not include white space in measures.

{{ClosedIssue}} When no unit is explicitly given, how do we know which of the following two behaviors to take? Assume unit minimisation and follow the procedures here; or Assume angular schema and treat number as a degree/minute/second.
* Changed root element class for angular schema to <tt>hangle</tt>

=== hmoney ===

If no <tt>num</tt> is given, then the first number conforming to the EBNF above is taken to be the numerical value. If no <tt>unit</tt> is given, the first three-letter word (or single character alias) is taken to be the unit. White space between the implied unit and implied number is considered optional. The following are to be equivalent:

<pre>
<span class="hmoney"><span class="unit">EUR</span> <span class="num">1,00</span></span>
<span class="hmoney">EUR <span class="num">1,00</span></span>
<span class="hmoney">EUR1,00</span>
<span class="hmoney">1,00 EUR</span>
<span class="hmoney">1.00 <abbr class="unit" title="EUR">euro</abbr></span>
<span class="hmoney">€1,00</span>
<abbr class="hmoney" title="EUR 1,00">a euro</abbr>
</pre>

=== Minimising Tolerence ===

If the tolerance is not a percentage (i.e. it is a nested hmeasure/hmoney) and it does not contain a unit (either explicit, or by minimisation rules), then the unit is taken to be the unit of the parent hmeasure/hmoney.

If no explicit tolerance is given, the hmeasure string should be examined for an occurrence of the substring "±". If this is present, the substring after it, and continuing to the end of the hmeasure string is taken to be a tolerance. If the tolerance contains a "%" character, the tolerance is taken to be a percentage. Otherwise is it taken to be an implicit nested hmeasure/hmoney.

=== Implied Item ===

If no <tt>item</tt> is present, then the item {{may}} be inferred from nesting. If the <tt>hmeasure</tt> (or <tt>hangle</tt>, <tt>hmoney</tt>) is nested within an hCard or hCalendar event, then the implied item is the person, organisation or place represented by the hCard, or the event represented in hCalendar.

Future versions of this specification may add other implied item minimisation techniques.

=== Worked example ===

The following example shows a series of expansions taken by a parser encountering a minimised hmoney:

<pre><span class="hmoney">$1.54 ± 0.01</span></pre>

The "±" sign introduces a tolerance, which does not include a "%" symbol, so is treated as a nested hmoney.

<pre><span class="hmoney">$1.54 ±<span class="hmoney tolerance">0.01</span></span></pre>

No explicit units or values are given in either hmoney, so units and numerical values are extracted as per hmoney minimisation:

<pre><span class="hmoney"><span class="unit">$</span><span class="num">1.54</span>
±<span class="hmoney tolerance"><span class="num">0.01</span></span></span></pre>

The nested hmoney contains no unit, so it inherits its unit from the parent hmoney:

<pre><span class="hmoney"><span class="unit">$</span><span class="num">1.54</span>
±<span class="hmoney tolerance"><span class="unit">$</span> <span class="num">0.01</span></span></span></pre>

Parsed values:

* '''Unit:''' USD
* '''Num:''' 1.54
* '''Tolerance:'''
** '''Unit:''' USD
** '''Num:''' 0.01

== Examples ==

An example weather forecast using hmeasure, [[adr]], [[geo]] and [[hCalendar]] with the [[include-pattern|include pattern]]:

<pre><div>
Weather for
<span id="loc-lewes">
<span class="adr location">
<span class="locality">Lewes</span>,
<span class="region">East Sussex</span>
</span>
(<span class="geo">50.8730;0.005</span>)
</span>,
<span class="vevent item" id="day-20080325">
<a class="include" href="#loc-lewes"></a>
<span class="summary">Tuesday</span>
<abbr class="dtstart" title="2008-03-25">25 March</abbr>
<abbr class="dtend" title="2008-03-26"></abbr>
</span>:
<span class="hmeasure">
<a class="include" href="#day-20080325"></a>
<abbr title="Maximum temperature" class="type">High</abbr>
8 ℃
</span>,
<span class="hmeasure">
<a class="include" href="#day-20080325"></a>
<abbr title="Minimum temperature" class="type">Low</abbr>
0 ℃
</span>
</div></pre>

(The above example does not necessarily represent best practice. Authors should make themselves aware of the accessibility issues currently being discussed around the include and abbr design patterns.)

== Parsing Hints ==

This section is ''informative''.

=== num parsing ===

This Perl code shows how a number can be parsed according to the EBNF production in this spec. Its author (Toby Inkster) releases the following code into the public domain:

<pre><nowiki>#!/usr/bin/perl

my $nonZeroDigit = '[1-9]';
my $digit = '\d';
my $natural = "($nonZeroDigit)($digit)*";
my $integer = "(0|\-?($natural)+)";
my $decimal = "($integer)[\.\,]($digit)*";
my $mantissa = "($decimal|$integer)";
my $sciNumber = "($mantissa)[Ee]($integer)";
my $number = "($sciNumber|$decimal|$integer)";

print "/$number/\n";
while (<>)
{
s/\s*//g;
m/$number/;
print "Number found: $1\n";
}</nowiki></pre>

=== unit parsing ===

Parsers should note that (with the exception of certain non-ascii characters, which can be converted manually first) all the pre-defined non-currency units can be understood by the [http://www.gnu.org/software/units/ GNU units] program. A parser could act as a wrapper to a GNU units installation, or make use of a GNU units-based web service to convert between units.

== Guillaume Lebleu ==

Basic example with elementary unit using the abbr pattern and the UNECE code (see [[measure-formats]])

<pre>
<span class="length">5 <abbr class="unit" title="FOT">Feet</abbr></span>
</pre>

Optional "value" could be useful in some cases, for instance when the value is provided in plain text:

<pre>
<span class="length"><abbr class="value" title="5">Five</abbr> <abbr class="unit" title="FOT">Feet</abbr></span>
</pre>

==Andy Mabbett==

===Converter Extension===
This Firefox extension may be of interest. Note, though, that it's been criticised for having a "nag" screen: [https://addons.mozilla.org/firefox/2286/ Converter] [[User:AndyMabbett|AndyMabbett]] 15:32, 3 Oct 2006 (PDT)

:This is the author of that extension. I don't want to go much into this, but I just want to clarify this briefly. The part with the nag screen is wrong on two counts: (1) that dialog isn't there anymore, and (2) even if it was there, you only needed to read a paragraph and click a button to make it go away ''forever'' -- but you don't have to take my word for it, install it for yourselves and see. Andy's report is accurate however -- the extension '''''was''''' criticized for that dialog (that's what you get from your free extension's users when you ask for 15 seconds of their time in return for hundreds of hours of your time). --[[User:BogdanStancescu|BogdanStancescu]] 09:35, 9 Oct 2006 (PDT)

===Wikipedia converter===
Wikipedia's [http://en.wikipedia.org/wiki/Template:Convert Convert Template] automatically converts from metric to imperial and vice versa. It's worth noting the measurements it supports.

===Google calculator===
A Google search, e.g. for "0.6 miles" [http://www.google.co.uk/search?q=0.6+miles returns a metric conversion]. See also [http://www.google.co.uk/intl/en/help/calculator.html Google calculator help].

===HTML Entities===
*For squared and cubic values, the HTML entities <code>&sup2;</code> and <code>&sup3;</code> should be borne in mind.

*For temperatures and angels, the HTML entity <code>&deg;</code> exists.

*The following currency entities exist:
**<code>¤</code> - <code>&curren;</code> - currency
**<code>¢</code> - <code>&cent;</code> - cent
**<code>£</code> - <code>&pound;</code> - pound
**<code>¥</code> - <code>&yen;</code> - yen
**<code>€</code> - <code>&euro;</code> - Euro

==Bogdan Stăncescu==
Here are my findings related to automatic parsing of measurements on web pages while developing the [http://converter.mozdev.org Converter] extension. Please ask away if you want me to go into more detail on any of the topics -- I'm not sure which of my experiences are relevant to microformats, so I'm going to give you an overview of my conclusions.

By the way of an introduction, the Converter is a Firefox extension which tries to convert all measurements it finds in any web page to their Imperial or metric counterpart (e.g. Fahrenheit to Celsius, and Celsius to Fahrenheit; meters to feet and feet to meters). There are two steps to the conversion process: (1) identifying the measurements in the page, and (2) converting them. As expected, the conversion part is trivial, at least conceptually. The parsing is the tricky bit, and that's also where the Converter's challenges also become relevant for microformats.

Here are the main challenges I have encountered while writing the Converter:

;Presentation standardization: The first, biggest and most obvious challenge is lack of almost any ''de facto'' standardization in respect to data presentation. What I mean is that although the units themselves are more or less standardized (more on that later), they are ''presented'' in various ways within web pages. Take these examples: "50 foot monster", "50 ft monster", "50 feet monster", "50-foot monster", "50-feet monster" -- and my personal favorite, "fifty-foot monster" (more on this later);

:Note that using a microformat using in particular the [[abbr-design-pattern]] would make each of these examples less ambiguous if not unambiguous. See below --[[User:Guillaume_Lebleu|Guillaume_Lebleu]]:

<pre>
<span class="height"><span class="value">50</span><abbr class="unit" title="FOT">foot</abbr></span> monster
</pre>

<pre>
<span class="height"><span class="value">50</span><abbr class="unit" title="FOT">ft</abbr></span> monster
</pre>

<pre>
<span class="height"><span class="value">50</span>-<abbr class="unit" title="FOT">foot</abbr></span> monster
</pre>

<pre>
<span class="height"><span class="value">50</span><abbr class="unit" title="FOT">feet</abbr></span> monster
</pre>

<pre>
<span class="height"><abbr class="value" title="50">fifty</abbr><abbr class="unit" title="FOT">foot</abbr></span> monster
</pre>

:: Of course; as far as I could gather, that's actually the ''purpose'' of microformats -- bridging the gap between what humans and machines can understand, no? --[[User:BogdanStancescu|BogdanStancescu]] 00:30, 11 Oct 2006 (PDT)

;Unit standardization: I live in Europe, where I've always used the metric system. As such, this probably was a much bigger nasty surprise for me than it is for a user of the Imperial/U.S. Customary system: in the Imperial system, the units themselves vary depending on where you are -- miles, pints, and a whole lot of other units come in many different flavors, but they're all written the same in regular usage;

;Language: "1 meter" vs. "1 metre" is a reasonable difference -- but non-SI units are usually translated. Even some SI units have different plurals, depending on the language, although in theory SI units are actually denoted by ''symbols'', not "words", as to make them non-translatable, and truly international (hence the name of the SI). I haven't really given much thought to a solution towards parsing these, because I find it overwhelming for the time.

;The sheer number of units: surprisingly, most people don't realize just how many units we humans have invented. Just take a look here: [http://www.asknumbers.com/ asknumbers.com] -- see how many categories there are? Now click on Flow Rate -- a non-ubiquitous type of measurement. Three sub-categories only for flow rates! Now click on Volume Flow Rate and take a look at the number of units in those lists. Remember, those are just in one of the three categories for flow rate! The UNECE standard mentioned in the [[measure-formats#Measure_Formats|measure formats]] page is useful to define just that -- a ''standard'' set of units. But in practice there are a lot more being used out there.

:Do you have examples from the Web (a URL) of non-UNECE units. One possibility would be to provide the ability for a unit to be defined as a division of products of other units. This is consistent with the [[measure-formats#Systeme_International]], which defines 7 base units and all other units as derived units (of course some units, even though they are derived are much easily represented as simple ones). This is what XBRL has done for financial/accounting/reporting. See [[currency-formats#XBRL]] and theorical example (ampere acre per second) below --[[User:Guillaume_Lebleu|Guillaume_Lebleu]]:

::Unfortunately I don't have URLs -- almost at all -- with measurements, although I've been in the "business" for a while. The reason for this is that I collect URLs of pages I encounter which are not properly parsed by the Converter, and when I release a version which understands those, I delete the URLs. Also, I never intended to cover all units in the Converter myself, for a multitude of reasons -- therefore I was never interested in the more exotic ones.

<small>Guillaume Lebleu's example</small>
<pre>
<span class="unit">
<abbr class="unit" title="AMP">Ampere</abbr> <abbr class="unit" title="ACR">acre</abbr> <span class="divide">per</span> <abbr class="unit" title="SEC">second</abbr>
</span>
</pre>

::Regarding your idea of breaking down the units in base units, that's something I've also been toying with in my head for the Converter. For my particular application, it's technically more difficult to implement this breakdown. For microformats, it would be easier, but there still remains at least one potential problem: you end up with a huge mess in the page. If a standard is too complicated to follow, one tends to give up altogether.

::Consider a document which actually discusses some sort of current variation per farm, and therefore needs to repeatedly refer to ampere acres per second. For human use, they'd simply define the AAS somewhere at the top of the document, and then refer to AAS, KAAS or MAAS as needed. Maybe a similar approach should be considered for microformats as well:

<pre>
We define the
<span class="unit_definition">
<abbr class="unit_name">AAS</span>
as
<abbr class="unit" title="AMP">Ampere</abbr>
<abbr class="unit" title="ACR">acre</abbr>
<span class="divide">per</span>
<abbr class="unit" title="SEC">second</abbr>
</span>.
</pre>

::And then use the "AAS" throughout the document as any other pre-defined unit. How would you define (and use) the KAAS (1000 AAS) or MAAS (1,000,000 AAS) though? Is there any standard way already to use data multipliers in microformats? Or should we discuss that? Or is it out of scope? --[[User:BogdanStancescu|BogdanStancescu]] 00:30, 11 Oct 2006 (PDT)

That's all I can think of as major hurdles right now. If I remember anything else, I'll post here. Please do give me feedback here if you want to ask more about any of the topics I touched above, or if you have other questions I might be able to reply to. --[[User:BogdanStancescu|BogdanStancescu]] 12:08, 9 Oct 2006 (PDT)

==Discoleo==
=== Measurement Classification ===

Because it is easier to provide examples, I will first list examples.

==== Categorical vs Ordinal Data ====

Various measurements may produce '''NON-Numerical''' values:
* a pain scale: '''most severe''', '''very severe''', '''severe''', ...
* or the TNM tumour classification system: T0, Tx, T1, T2, T3, T4, N0, ...

There is even a more fundamental issue related to numbers themselves, e.g.:
* '''Lists''' or '''Years''' are sometimes written using '''Roman Numbers'''
** however, the strings corresponding to ''Roman Numbers'', when sorted alphabetically, do NOT retain the correct order
** i.e. C (100) preceds L (50), which preceds X (10)
* there are other numbering schemes

==== A Single Value / Data Point ====

This is the most simple data format and pretty straitforward to implement.

* the distance between 2 cities is '''40 km'''
* the velocity is '''62 mph'''
* most other simple entires (...)

==== An Interval Measurement ====

* time: the shop is open between '''6am - 18pm''' on every day of the week, exept Saturdays from '''9am - 16pm''' and Sundays from '''9am - 13pm'''
**[[hcalendar|hCalendar]]? [[User:AndyMabbett|Andy Mabbett]] 09:24, 22 Nov 2006 (PST)

This is more about an interval measurement. Every variable can have 2 (or more) values, e.g.:
* the levels of rain fall were between 25mm - 35mm
* the maximum velocity of various cars was 220 - 250 km/h

Should these values be stored as separate values? [e.g. low / high]
Or should the microformats be able to store an interval?

See also the examples for statistical summaries below.

*Mark up each as a separate measurement, and wrap them in a "range" microformat? [[User:AndyMabbett|Andy Mabbett]] 11:36, 22 Nov 2006 (PST)

==== Matrices ====

* the GPS coordinates are '''12°14' N and 25°55' E'''
**[[geo|Geo]]? [[User:AndyMabbett|Andy Mabbett]] 09:25, 22 Nov 2006 (PST)
* the dimension of the box is '''3m x 2m x 0.55m'''
**this is three separate, single measurements, surely? [[User:AndyMabbett|Andy Mabbett]] 09:21, 22 Nov 2006 (PST)
** 3 x 2 x 0.55 cubic meter, still 3 measurements, BUT given as cubic meter => ONE measurement?
***Who writes 3x2x0.55 cubic meter? You'd write "3.3m<sup>3</sup>" [[User:AndyMabbett|Andy Mabbett]] 11:36, 22 Nov 2006 (PST)
** the surface was 2 x 3 square feet ???
***Who writes 2x3 sq ft? You'd write "2ftx3ft" or "6ft<sup>2</sup>" [[User:AndyMabbett|Andy Mabbett]] 11:36, 22 Nov 2006 (PST)

* IF we write "3.3m<sup>3</sup>" or "6ft<sup>2</sup>", we '''loose information'''
* IF I want a surface, I would prefer the '''sqare feet''' unit, and NOT '''...feet x ...feet'''
* writing for every measure a markup, will '''bloat''' the code extensively
** data matrices would be very effective here
*** how would you make such a matrix? There are different ways how such information can be "compounded". (length per time = speed, length * length = area). Maybe a we can group those measurements by a surrounding information, what the context is. --Emil 02:50, 25 Dec 2006 (PST)

==== Statistical Measurements ====

Often, a group of data is summarized using a statistics:
* the mean length was 1.3m (SD 0.12m, group size 22)
* the median age was 42 years (interquartile range 95% 18 - 97)

==== Measurement Scales ====

===== Accuracy vs. Precision =====

'''QUESTIONS'''
* How detailed should a measurement be stored?
**Microformats aren't for storing measurements; they're for "labelling" the measurements that are already present. [[User:AndyMabbett|Andy Mabbett]] 09:23, 22 Nov 2006 (PST)
* If Accuracy and precision are relevant to the measurement, how do we store these?

===== Standardization of Measurement =====

* sometimes we may need to store the calibration information / calibration curves
* we may need to store the reference point the measurement is based on
* we may need to store the '''normal values'''
** biomedical measurements are often laboratory dependent, so it does NOT make sense to have the measurement without the corresponding normal values
** e.g. anti-Hepatitis B surface antigen antibody (anti-HBs) Titer: 32 MIU/ml
*** normal: 0 (non-infected, non-past infection, non-immunity)
*** protective immunity: >10 MIU/ml
*** interpretation is however more complex, depending on other tests as well

== Emil Thies ==

From my understanding, this microformat should concentrate on the notation of a measurement. So there will be some aspects, which has to be covered (elsewhere?) to improve the automatic use it or this microformat only uses some base informationens (units / dimensions) and derives all used from those base / build-in once.

=== Dimension vs. Unit vs. Scale vs. Measurement ===

A measurement is the combination of a number (value) and a unit (kind).
* 3km (3 Kilo Metre = 3.000 Metre)

A unit is a view for a measure of a dimension. There are two kinds how units can be different to each user:
* Units Differ by Scale (Prefix)
** 3km is the same as 3.000 meter or 300.000 cm (Its the same unit, with a different prefix, which works like a factor for the value, to lower the amount of symbols / numbers. The scale should be an own element and we can make use of the standard prefixes, like they are defined on [http://aurora.regenstrief.org/UCUM/ucum.html#section-Prefixes The Unified Code for Units of Measure] or [http://www.w3.org/TR/mathml-units/#SI-prefixes MathML]).
* Different units of the same dimension can be transferred into each other.
** Metre is a unit of the dimension length.
** Foot is a unit of the dimension length.

A Dimension is a base-dimension (see SI-System) or a compound dimension.
* length is a base dimension
* time is a base dimension
* speed is a compound dimension (length per time). There for a measurement of speed has one number and two unit by a math expression, which form their own unit. e.g. 10 m/s (10 Metre per second).

If we express a measurement in a microformat by the unit, the dimension is indirect provided by it. But a microformat, which uses measurement as a part, needs to define the dimension of it, to keep the use of the unit as an user choice. So, we could have a general measurement element, which allows all kinds of units to use. As a derived format, we can have sub-formats, which limit the list of units (or define an alternate list) by only allowing specific dimension(s).

E.G.
* [[currency-proposal]], with the money element which uses the same elements value (should then replace amount), scale (should be introduced), unit (should replace currency) which is limit to the ISO 4217 list.
* length, which only allows units which measures the dimension length, like FOT, MTR ...

=== Identification of Units ===

There are so many Units around - not only the existing one. There are deprecated ones like from Rome empire etc. For example "[http://en.wikipedia.org/wiki/Foot_(unit_of_length) Foot]" is not an unique identification of a unit. There is not only the British and U.S., there are for example same old German ones, before those areas joined the international metre convention in 1875:
* 25 cm in Hessen
* 28,935 cm in Bremen
* 29,641 cm in Oldenburg
* 29,1859 cm in Bayern
* 30,385 cm in Meiningen-Hildburghausen
* 31,385 cm in Preußen
* 31,608 cm in Wien/Österreich
* 32,61 cm in Bad Homburg vor der Höhe
* 33 1/3 cm in der Pfalz

So there is the need of a unique identification of those units. I found two approach right:

==== In MathML ====

MathML [http://www.w3.org/TR/mathml-units/#definitionURL defines] the construction of an URI like:

<nowiki>http://base/units/unit name[/context][/country][#prefix]</nowiki>

<pre>
http://.../units/foot/de
</pre>

But as you can see, there is right now no way to distinguish the different German foots based on the area inside Germany. Furthermore the context is so variable, that the same unit can be described by different URLs.

==== In OpenMath ====

OpenMath [http://www.openmath.org/cdgroups/units.html defines] the units inside of content directories:

<pre>
http://www.openmath.org/cd/units_us1.xhtml#foot_us_survey
</pre>

So there is a unique URLs for a Unit, but not every Unit is covered.

=== Transformation of Units ===

A real benefit is the automatic transformation of a unit, so that the write can write the measurement in his context (e.g. in the U.S. foot, or a quote from an antike text in Rome Empire foot) and the reader can get a transformation in his context (e.g. the value in metre). There fore there is the need of additional transformation information. And there are some different kinds of transformation:

==== units of same dimension ====

e.g. foot to metre

==== units of compound but same dimension ====

e.g. metre/s and mach-number

==== compound measurement context ====

<pre>This switch works up to 5 Ampere by 220 Volt</pre>

The reader might to now, which Watt device he can attach (1100 Watt would be the answer).

<pre>The dimension of the box is 3m x 2m x 0.55m</pre>

There might be some question like:
* volume (3,3 m³)
* surface (17,5 m²)

=== Approach ===

A general measurement should make use of the following informations:

value: a number, which represents the amount of the measurement. The number should follow one of the following representation:
* natural (positive and negative): e.g. -1, 0, 1
* decimal fraction (positive and negative): e.g. -2.5, 0.123
* natural fraction (positive and negative): e.g. -2/3, 3/7
scale: a factor used to lower the needed numbers of the value. The scale should be either
* a letter to refer a build-in factor, which is defined in [http://aurora.regenstrief.org/UCUM/ucum.html#section-Prefixes The Unified Code for Units of Measure] or [http://www.w3.org/TR/mathml-units/#SI-prefixes MathML]).
* a number like defined on value
unit: the unit used for the measurement. The unit should follow one of the following representation:
* build-in short-form like defined on [http://www.unece.org/etrades/units.htm Standards for Trade and Electronic Business] (or any other defined list which will be defined as the standard list for this format)
* a reference to a unit definition. (I think there is the need of a markup/language to define new units and/or the transformation between units).

<pre>
<span class="measurement"><abbr class="value" title="5">Five</abbr> <abbr class="scale" title="k">kilo</abbr> <abbr class="unit" title="MTR">metre</abbr></span>
</pre>

when we have a defined sub-measurement format for length, it could also be written:

<pre>
<span class="length"><abbr class="value" title="5">Five</abbr> <abbr class="scale" title="k">kilo</abbr> <abbr class="unit" title="MTR">metre</abbr></span>
</pre>

==== List of possible Sub-Formats ====

Here is a (first) list of possible keywords for sub-formats and their unit list or compound kind:

* money - unit limit to the ISO 4217 List (or could be a sparate [[currency]] microformat)
* '''length''' - unit limited to e.g. MTR (Metre), FOT (Foot) ....)
** '''area'''
*** Either a measurement with units like MTK (Square Metre), FTK (Square Foot)
*** or a compound format with elements (width:length, height:length)
** '''volume'''
*** Either a measurement with units like MTQ (Cubic Metre), FTQ (Cubic Foot), LTR (Litre) ...
*** or a compound format with elements (width:length, height:length, depth:length)
* time or duration or '''period''' - unit limited to e.g. sec (second), min (minute) ...
* '''frequency''' - unit limited to Hertz
* mass or '''weight''' - unit limited to GRM (Gram), ...
* power or '''electricity''' - unit limited to AMP (Ampere), OHM (Ohm), ...

==Straw man==
Based on [[currency-brainstorming#Taylor_Cowan|Taylor Cowan's currency suggestion]], and [http://microformats.org/discuss/mail/microformats-new/2007-September/000921.html subsequent mailing list discussion], the following straw man (rendering the above sub-formats unnecessary) is proposed:

<pre><nowiki>
<span class="hmeasure">
[value]
</span>

<abbr class="hmeasure" title="[value]">
[text]
</abbr>
</nowiki></pre>

Where "value" is a number-type pair ("3Kg", "456g") using [http://en.wikipedia.org/wiki/SI_units SI] or other standard unit-codes and where parsers must accept the formats:

*[unit-code][number]
*[unit-code][space][number]
*[number][unit-code]
*[number]space[unit-code]

and where the acceptable codes are to be determined.

Further comment is invited. A test page is available, at http://www.westmidlandbirdclub.com/test/measure.htm

===Notes===
*This is extensible, using agreed new codes for unusual or archaic measurements (say "FUR" for "furlong"); such codes could be contained in the microformat's profile.
*Otherwise, it works as-is for sub-divisions of currencies:

<pre><nowiki>
<abbr class="hmeasure" title="635mm">
2' 1"
</abbr>
</nowiki></pre>

:(2' 1" is "two feet one inch" in imperial measurement).

===Issues===
*is hmeasure the appropriate class-name?
*Is [[currency|money]] a separate microformat, or a measurement, with the ISO currency code as the unit-code?
*What standard sources for unit-codes exist?
**[http://www.bipm.org/en/si/ International System of Units]
*This is still susceptible to the [[accessibility-issues#abbr-design-pattern]]
*How should stops (.) and commas (,) be interpreted? [[User:TobyInk|TobyInk]] 04:13, 18 Nov 2007 (PST)
*Do we also need sub-classes?

<pre><nowiki>
<span class="hmeasure">
The <span class="unit-code">kg</span> weight was, in total <span class="value">5</span>.
</span>
</nowiki></pre>

*If so, where would this be used? And are "unit-code" and "value" appropriate class-names?
*<p>'''[http://en.wikipedia.org/wiki/Measurement Measurement errors]''' are fundamental in many technical and scientific fields, they must be supported. [[User:LucaPost|LucaPost]]

<pre><nowiki>
<span class="hmeasure">
<a href="/depth" rel="tag" class="data-name">Depth</a>:
( <span class="data-value">2.17</span> +/-
<span class="data-error"> 0.02</span> )
x 10<sup class="exp">3</sup>
<abbr class="unit-measure" title="m">meters</abbr>.
</span>
</nowiki></pre>
</p>
:#Here the actual physical quantity is better 'defined' with rel-tag, and the optional data-error is clearly identified with its own span; alternatively parsers might identify the data-error part by looking for the '±' html-entity.
:# The standard '''[http://en.wikipedia.org/wiki/Scientific_Notation scientific notation]''' requires the data and the error values to be rounded to the same number of digits; the exponential notation in powers of ten is useful to have a singular format for values of any order of magnitude.
:# data-error and exp are not needed outside scientific contexts, thus they would be optional; the above HTML still represents a semantic structure when they're left out.

===Suggested amendment 1===

*Use only:

<pre><nowiki>
<abbr class="hmeasure" title="[value]">
[text]
</abbr>
</nowiki></pre>

Where "value" is a number-type pair ("3 kg", "456 g") using [http://en.wikipedia.org/wiki/SI_units SI] or other standard unit-codes where the parser must accept the following formats:

*Single measurements - [number][space][[http://en.wikipedia.org/wiki/SI_prefix SI-prefix]][[http://www.bipm.org/en/si/si_brochure/chapter5/5-2.html SI-unit]]
*Compound measurements - [number][space][[http://en.wikipedia.org/wiki/SI_prefix SI-prefix]][[http://www.bipm.org/en/si/si_brochure/chapter5/5-2.html SI-unit]][/][[[http://en.wikipedia.org/wiki/SI_prefix SI-prefix]][[http://www.bipm.org/en/si/si_brochure/chapter5/5-2.html SI-unit]]

====Notes====
*The only values allowed are SI values and prefixes

<pre><nowiki>
<abbr class="hmeasure" title="635 mm">
2' 1"
</abbr>

<abbr class="hmeasure" title="635 km/s">
635 kilometers per second
</abbr>

<abbr class="hmeasure" title="0.5 m^3/s^2">
half a cubic metre per second squared
</abbr>
</nowiki></pre>

====Supported SI Prefixes====

* yotta Y Quadrillion -1 000 000 000 000 000 000 000 000
* zetta Z Trilliard (thousand trillion) - 1 000 000 000 000 000 000 000
* exa- E Quintillion Trillion 1 000 000 000 000 000 000
* peta- P Quadrillion Billiard (thousand billion) 1 000 000 000 000 000
* tera- T Trillion Billion 1 000 000 000 000
* giga- G Billion Milliard (thousand million) 1 000 000 000
* mega- M Million 1 000 000
* kilo- k Thousand 1 000
* hecto- h Hundred 100
* deca- da Ten 10
* deci- d Tenth 0.1
* centi- c Hundredth 0.01
* milli- m Thousandth 0.001
* micro- u Millionth 0.000 001
** There is already a unicode character for the micro, sign: µ (U+00B5). Better to use it than substituting a "u". [[User:TobyInk|TobyInk]] 03:56, 18 Nov 2007 (PST)
* nano- n Billionth Milliardth 0.000 000 001
* pico- p Trillionth Billionth 0.000 000 000 001
* femto- f Quadrillionth Billiardth 0.000 000 000 000 001
* atto- a Quintillionth Trillionth 0.000 000 000 000 000 001
* zepto- z Sextillionth Trilliardth 0.000 000 000 000 000 000 001
* yocto- y Septillionth Quadrillionth 0.000 000 000 000 000 000 000 001

====Supported SI Units====

*meter (m) - length
*gram (g) - mass
*kilogram (kg) - mass
*second (s) - time
*ampere (A) - electric current
*kelvin (K) - thermodynamic temperature
*mole (mol) - amount of substance
*candela (cd) - luminous intensity

====Supported Derived SI Units====
*hertz (Hz) - frequency
*newton - (N) force, weight
*pascal - (Pa) pressure, stress
*joule (J) - energy, work, heat
*watt (W) - power, radiant flux
*coulomb (C) - electric charge or electric flux
*volt (V) - voltage, electrical potential difference, electromotive force
*farad (F) - electric capacitance
*ohm (ohm) - electric resistance, impedance, reactance
*siemens (S) - electrical conductance
*weber (Wb) - magnetic flux
*tesla (T) - magnetic field
*henry (H) - inductance
*lumen (lm) - luminous flux
*lux (lx) - illuminance
*becquerel (Bq) - radioactivity (decays per unit time)
*sievert (Sv) - equivalent dose (of ionizing radiation)
*katal (kat) - catalytic activity

====Supported Non-SI Units====

*minute (min) - time
*hour (h) - time
*day (d) - time
*radian (rad) - angle
*degree of arc (deg) - angle
** Use instead U+00B0 (°, degree) [[User:TobyInk|TobyInk]] 04:06, 18 Nov 2007 (PST)
*minute of arc (') - angle
** Use instead U+2032 (′, prime) [[User:TobyInk|TobyInk]] 04:06, 18 Nov 2007 (PST)
*second of arc (<nowiki>''</nowiki>) - angle
** Use instead U+2033 (″, double-prime) [[User:TobyInk|TobyInk]] 04:06, 18 Nov 2007 (PST)
*steradian (sr) - solid angle
*square degree (deg^2) - solid angle
*litre (L) - volume
*tonne (t) - mass

====Units Defined by Microformats.org====

*celcius (cel) - temperature
** Use U+2103 (℃, degrees celcius) [[User:TobyInk|TobyInk]] 04:07, 18 Nov 2007 (PST)
*bit (bit) - computing
*year (y) - year
*inch (in) - inch
*foot (ft) - foot

====Supported SI Markup====

*solidus (/) - divisor
** Division slash (∕, U+2215) more appropriate [[User:TobyInk|TobyInk]] 04:09, 18 Nov 2007 (PST)
*caret (^) - exponentiation

==See also==
{{measure-related-pages}}

rel-me

2022-11-14T20:33:54Z

GRegorLove: /* implementations */ +Mastodon, mv App.net past, use IA link

{{DISPLAYTITLE:rel="me"}}
;short URL
:http://ufs.cc/w/relme

[[XFN]] 1.1 introduced the "me" [[rel]] value which is used to indicate profile equivalence and for [[identity-consolidation]].

== example ==
<code>rel="me"</code> is used on hyperlinks from one page about a person to other pages about that same person.

For example, [[User:Tantek|Tantek]]'s [https://tantek.com/ home page] has (markup simplified)

<syntaxhighlight lang="html"><a href="https://github.com/tantek" rel="me">@t</a></syntaxhighlight>

And his GitHub profile itself has (markup simplified)

<syntaxhighlight lang="html"><a href="https://tantek.com/" rel="me">https://tantek.com/</a></syntaxhighlight>

Thus establishing a bi-directional rel-me link and confirming that the two URLs represent the same person.

Publishers can use the [https://gmpg.org/xfn/creator XFN creator] form to create rel-me hyperlinks.

== screencast and videos ==
Watch some short videos:
* David Recordon's excellent *30 second* explanation of XFN rel="me"
** [http://web.archive.org/web/20090119054502/http://www.sixapart.com/static_news/opening_social_graph/xfn_links/xfn_links.html Archived page], though presentation requires Flash
** Original: http://www.sixapart.com/static_news/opening_social_graph/xfn_links/xfn_links.html
* [https://www.youtube.com/watch?v=LabCylbapuM Brad Fitzpatrick explains rel="me" and more XFN].
* [https://connectedsocialmedia.com/423/plaxo-to-ship-online-identity-aggregator-based-on-microformats/ Joseph Smarr's whiteboard explanation] of rel="me" as implemented in the Plaxo online identity aggregator. ([http://web.archive.org/web/20220708203538/https://connectedsocialmedia.com/423/plaxo-to-ship-online-identity-aggregator-based-on-microformats/ archived]) 

Longer:
* [https://www.youtube.com/watch?v=Q2WzVSVxrrI Gavin Bell on "What is your provenance?"] (40 minutes) - provides a much broader discussion of the problem statement of who is a person on the Web, and [https://youtu.be/Q2WzVSVxrrI?t=450 starting at about 0:07:30] explains how [[hCard]] + rel="me" helps solve this problem.

== tutorials ==
[http://ungeekdapo.wordpress.com/2008/04/29/a-simple-data-portability-project-or-is-it/ A simple data portability project or is it] ([http://web.archive.org/web/20221110203949/https://ungeekdapo.wordpress.com/2008/04/29/a-simple-data-portability-project-or-is-it/ archived]) rel=me summary by Bob Ngu

== domain verification ==
rel=me is the standard way to check that a website belongs to a user on a 3rd party site.

* read a user's website that they entered into their 3rd party site profile
* check for a rel=me hyperlink from their website to their 3rd party site profile
* if such a rel=me hyperlink is found, then the user has proven that they control that personal website sufficient to put a link back to their 3rd party site profile, and thus domain verification succeeds.

If you're the implementer of such a 3rd party site with user profiles, implement the above to implement a personal website domain verification feature.

== rel-me-auth ==
[[RelMeAuth]] is a proposed open standard for using [[rel-me]] links to profiles on [[OAuth]] supporting services to authenticate via either those profiles or your own site.

In short it is a combination of '''domain verification''' as documented above, and OAuth authorization on the 3rd party site that the user's domain links to.

Read more about how to implement [[RelMeAuth]] and [[web sign-in]].

----
----
'''TO BE UPDATED'''

The sections below this need to be updated (e.g. links verified, and deadlinks replaced with Internet Archive versions)

----
----

== implementations ==
Notable Sites:
* [https://indieweb.org/Mastodon#rel-me_support Mastodon] uses rel-me to support "verified" site links in a green box with a green checkmark next to the verified site.
* ...

Services:
* '''[https://indieauth.com/ IndieAuth]''' is perhaps the most comprehensive [[rel-me]] implementation, using it to implement [[RelMeAuth]] and a superset of [[web-sign-in]] that is focused on [http://indiewebcamp.com/ independent websites].

[[wordpress-plugins|WordPress plugins]]:
* [http://blog.maybe5.com/?page_id=94 Social Links Wordpress plugin] - supports rel-me links to other services
* [http://code.l0g.in/about-me/ About Me plugin] (on github) - supports creation of an About Me page with rel-me links to other profiles.

=== past implementations ===
* '''[https://web.archive.org/web/20170826050132/https://support.google.com/webmasters/answer/1229920 Google]''' used reciprocal rel=me links for domain verification, which it also used for independent site [[rel-author]] support.
* '''[http://web.archive.org/web/20140117144124/http://blog.app.net/2013/04/29/announcing-domain-verification App.net]''' implemented rel-me for officially connecting your domain to your app.net account, as well as publishing rel-me on your site.

=== advocacy ===
Advocating rel=me support can be done a few ways, if a site has:
* user profiles but no "website" field - ask them to add a "website" field and mark it up with rel=me.
* a "website" field on profiles - ask it to support publishing rel=me
* a notion of "verification" or "verified" profiles - ask it to do so via confirming reciprocal rel=me
* login/sign-in - ask it to support [[RelMeAuth]] with a [[Web sign-in]] user interface.

Current requests:
* [https://github.com/gittip/www.gittip.com/issues/2477 Gittip: Add "website" profile field #2477] - requested 2014-06-07 by Aaron Parecki.
* ...

== examples in the wild ==
Examples of sites publishing rel=me support, e.g. on user profiles.

See:
* [[hcard-xfn-supporting-friends-lists#Services_with_XFN_rel.3D.22me.22_to_multiple_external_sites|services supporting XFN rel=me]]

== articles ==
* 2018-04-26 [https://vanderven.se/martijn/ Martijn van der Ven]: [https://wiki.zegnat.net/media/the-real-deal-about-rel-me.html The Real Deal About <code>rel="me"</code>]

== see also ==
* [[hcard-xfn-supporting-friends-lists#Services_with_XFN_rel.3D.22me.22_to_multiple_external_sites|services that support rel="me"]]
* [[rel-me-faq]]
* [[xfn]]
* [[rel]]
* [[social network portability]]
* [https://gmpg.org/xfn/11 XFN 1.1 profile]

rel-tag

2022-11-13T21:59:38Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:rel="tag"}}
<span style="float:right">__TOC__</span>
== Draft Specification 2005-01-10 ==
* If you’re looking for <code>rel="me"</code>, see: '''[[rel-me]]'''.

; Editors/Authors
:[http://tantek.com/ Tantek Çelik]
:[http://epeus.blogspot.com/ Kevin Marks]

;Concept
:[http://powazek.com/ Derek Powazek]

;Incorporated into
:[https://www.w3.org/TR/html5/links.html#link-type-tag W3C HTML5]
=== Copyright ===
{{MicroFormatCopyrightStatement2004}}
* [[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.
* [[User:Kevin Marks|Kevin Marks]]: 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}}

== Abstract ==
[[Rel-Tag]] is one of several [[MicroFormats]]. By adding <code>rel="tag"</code> to a hyperlink, a page indicates that the destination of that hyperlink is an author-designated "tag" (or keyword/subject) for the current page. Note that a tag may just refer to a major portion of the current page (i.e. a blog post). e.g. by placing this link on a page,

<syntaxhighlight lang="html"><a href="http://technorati.com/tag/tech" rel="tag">tech</a></syntaxhighlight>

the author indicates that the page (or some portion of the page) has the tag "tech".

The linked page SHOULD exist, and it is the linked page, rather than the link text, that defines the tag. The last path component of the URL
is the text of the tag, so

<syntaxhighlight lang="html"><a href="http://technorati.com/tag/tech" rel="tag">fish</a></syntaxhighlight>

would indicate the tag "tech" rather than "fish".

== Scope ==
rel="tag" is specifically designed for "tagging" content, typically web pages (or portions thereof, like blog posts).

rel="tag" is NOT designed for "tagging" arbitrary URLs or external content. There is demand for a general decentralized syntax for tagging URLs external to the current page, but this is not meant for that. See [[xfolk|xFolk]] and [[hreview|hReview]] for ways to tag arbitrary URLs.

If you need to define tags as part of a more specialized format, rel="tag" is the recommended way to do so, and [[xfolk|xFolk]], [[hreview|hReview]], [[hcard |hCard]], [[hcalendar|hCalendar]] and [[hrecipe|hRecipe]] all do this.

== XMDP profile ==
See [[rel-tag-profile]].

== Tag Spaces ==

Tags are embedded in HTTP URIs in a well-defined manner so that the tag embedded in an HTTP URI can be mechanically extracted from that URI. Specifically, the last segment of the path portion of the URI (after the final "/" character) contains the tag value. For example, the URI <syntaxhighlight lang="html">http://www.example.com/tags/foo</syntaxhighlight> contains the tag "foo".

Thus, for the purposes of comparing two HTTP URIs as tags, the last segment of the path portion should be extracted and only that value (that value of the tag) should be compared.

''Need more formal language about comparison and extraction process.''

The destination of a rel="tag" hyperlink is required to be a tag space (a place that collates or defines tags), where the last segment of the path of the URL is the tag, e.g.

<syntaxhighlight lang="html">http://technorati.com/tag/tech</syntaxhighlight>

is a URL for the tag "tech".

Tags may only be placed in the URL path, and only in the last segment of the path. Tags may not be placed in query parameters or fragment identifiers. e.g.

<syntaxhighlight lang="html">http://technorati.com/tag/tech?tag=fish#emu</syntaxhighlight>

is still a URL for the tag "tech", not "fish" or "emu".

Since the only part of a tag space URL of which any structure is required is the last path segment, a tag space URL can be hosted at any domain. Authors may choose to link to a tag at a particular tag space in order to provide a specific meaning. E.g. a tag for technology could link to:

<syntaxhighlight lang="html"> http://en.wikipedia.org/wiki/Technology</syntaxhighlight>

Trailing slashes in tag URLs are ignored, that is:

<syntaxhighlight lang="html"> http://technorati.com/tag/Technology/</syntaxhighlight>
as a rel-tag URL is treated as:
<syntaxhighlight lang="html"> http://technorati.com/tag/Technology</syntaxhighlight>

== Encoding issues ==
Spaces can be encoded either as <code>+</code> or <code>%20</code>. Unicode characters are encoded as specified in [http://www.ietf.org/rfc/rfc3986.txt <nowiki>RFC 3986</nowiki>]. For example:

<syntaxhighlight lang="html"><a href="http://technorati.com/tag/Sant%C3%A9+et+bien-%C3%AAtre" rel="tag">Santé et bien-être</a></syntaxhighlight>

Note that if using Wikipedia as a tagspace, as discussed above, you should use <code>%20</code> as they remap '+' to <code>%2B</code>, causing a page with a plus sign in the title (which usually does not exist) to appear.

== Tags Are Visible Metadata ==
<code>rel="tag"</code> hyperlinks are intended to be visible links on pages and posts. This is in stark contrast to meta keywords (which were invisible and typically never revealed to readers), and thus is at least somewhat more resilient to the problems which plagued meta keywords.

Making tag hyperlinks visible has the additional benefit of making it more obvious to readers if a page is abusing tag links, and thus providing more peer pressure for better behavior. It also makes it more obvious to authors, who may not always be aware what invisible metadata is being generated on their behalf.

As a result the invisible tag link syntax variant: <code><link rel="tag" href="..." /></code> SHOULD NOT be supported by implementations.

== Examples in the wild ==
This section is '''informative'''. The number of rel-tag examples in the wild has expanded far beyond the capacity of being kept inline in this specification. They have been moved to a [[rel-tag-examples-in-wild|separate page]].

See [[rel-tag-examples-in-wild|rel-tag Examples in the wild]].

== Implementations ==
This section is '''informative'''.

The following implementations have been developed which either generate or parse rel-tag links. If you have a rel-tag implementation, please add it to the '''top''' of this list. Once the list grows too big, we'll make a separate wiki page like [[rel-tag-implementations]].

* [http://degoli.dajbych.net Degoli] is a simple experimental semantic web seach engine which is crawling rel-tag data. It orders search results by rel-tag data and displays a navigation tree containing relationships among tags.
* [http://b2evolution.net b2evolution] A blog platform which generates rel-tag for all tags on blog posts (starting from v3.x).
* [http://www.textcube.org Textcube.org] makes a blogging tool, Textcube which generates rel-tag for tags on blog posts.
* [http://hashtags.org/ HashTags] tags Twitter posts, converting "#example" into a tag of "example"
* [http://ikiwiki.info ikiwiki] generates rel-tag for all tagged pages (as of version 2.6)
* [http://www.hubtag.com HubTag] helps users find a unique tag across the web for their event - eg. JohnAndBettysWeddingWimbledonMarch07
* [http://www.necctar.com Necctar] is a search engine exclusively based on tag microformat parsing and processing. Necctar uses tags entered by bloggers to index the world wide web
* Nutch has a [[rel-tag]] parser [http://www.mail-archive.com/nutch-commits@lucene.apache.org/msg01014.html committed to their svn repository].
* [http://www.webstandards.org/action/dwtf/microformats/ Dreamweaver Extension suite] from the [http://webstandards.org/ Web Standards Project] enables rel-tagging from within Dreamweaver 8.
* [http://scooch.gr0w.com/ Scooch] slide show creator allows authors to generate rel-tags and group slide shows by rel-tag via a list or cloud with tag usage count.
* The Freetag plugin for the [http://www.s9y.org Serendipity] blog software supports rel-tags on a per-entry basis, as well as inside of its tag clouds. (The Freetag plugin is available inside of SPARTACUS)
* [http://placenamehere.com/TXP/pnh_mf/ pnh_mf] is a plugin for [http://textpattern.com/ Textpattern] that supports embedding rel-tags and other microformats in templates and blog posts. Written by [http://placenamehere.com/ Chris Casciano].
* [http://www.rainskit.com/blog/493/trutags-a-tagging-plugin-for-textpattern tru_tags] is a plugin for [http://textpattern.com/ Textpattern] that supports rel-tagging blog posts via the Keywords field.
* [http://clothesonline.info ClothesOnline] uses rel-tag for categorizing shops and brands, for example: [http://clothesonline.info/brands/canada-goose Canada Goose].
* [http://news.livejournal.com/86492.html?thread=24881884 LiveJournal] - see also [http://www.livejournal.com/support/faq.bml?cat=tags their FAQ regarding their tags support]
* [http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/TagsLinks TagsLinks] Turn each tag into links that let you find related content on tagging services.
* [http://www.octofinder.com OctoFinder] uses rel-tag for all live news tag clouds.
* [http://dev.wp-plugins.org/wiki/BunnysTechnoratiTags Tag plugin for WordPress]
** Note that some sites using WordPress (http://microformatique.com/ for instance) are getting incorrect tags. The tag is ?cat=12 instead of the actual tag value.
* [http://noone.org/blog/tags/Tagging Tag plugin for Blosxom]
* Technorati first implemented rel-tag in its [http://technorati.com/tag/ Technorati Tags] service. Technorati indexes rel-tag tags.
* [http://consumingexperience.blogspot.com/2005/12/updated-multiple-word-technorati-tag.html Greasemonkey script for Firefox that generates tags for Blogger]
* [http://tools.microformatic.com/help/xhtml/rel-lint/ rel-lint] is a validation tool by [[User:DrewMcLellan|Drew McLellan]] that will validate existence of rel-tag attributes.

== articles ==
This section is '''informative'''.

Articles about rel-tag, most recent first. When this section gets too big, we can move it to [[rel-tag-articles]].
* (undated) [http://reference.sitepoint.com/html/rel-mf#rel__tag SitePoint reference: rel- Microformats / tag] by Ian Lloyd

== References ==
=== Normative References ===
* [http://www.w3.org/TR/REC-html40/ HTML 4]
* [http://www.w3.org/TR/xhtml1/ XHTML 1]
* [http://gmpg.org/xmdp/ XMDP]
* RFC 3986 specifies URL syntax. Section 3.3 specifies URL paths and path segments.

=== Informative References ===
* [[hreview|hReview]] uses rel-tag for tags and scalar tags
* [[xfolk|xFolk]] uses rel-tag to build a distributed remote resource tagging construct
* [http://developers.technorati.com/wiki/attentionxml Attention.XML] uses rel-tag for reader tagging of pages, posts, feeds
* [[hcard|hCard]] can use rel-tag for categories
* [[hcalendar|hCalendar]] can use rel-tag for categories
* [http://technorati.com/help/tags.html Using Technorati Tags]
* Contributed from http://developers.technorati.com/wiki/RelTag
* [http://microformatique.com/?p=61 Know your rel-tag] at microformatique.com

== Discussions ==
* Feedback is encouraged on the [[rel-tag-feedback]] page.
* See also [http://www.technorati.com/cosmos/referer.html blogs discussing this page].
* History: [http://www.powazek.com/2005/07/000532.html How Tags Happened at Technorati] by [http://www.powazek.com/ Derek Powazek]

=== Q&A ===
* If you have any questions about rel-tag, check the [[rel-faq|rel FAQ]] first for general rel attribute questions, then check the [[rel-tag-faq|rel-tag FAQ]], and then if you don't find answers, ask your question on the [http://microformats.org/discuss microformats-discuss] mailing list.

==Related pages==
{{rel-tag-related-pages}}

[[Category:Specifications]]
[[Category:rel-tag]]

h-listing

2022-11-13T21:56:02Z

GRegorLove: s/<source>/<syntaxhighlight>/

{{DISPLAYTITLE:h-listing draft}}
{{DraftSpecification}}

<dfn style="font-style:normal;font-weight:bold">h-listing</dfn> is a simple, open format for publishing product data on the web. h-listing is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.

h-Listing is the [[microformats2]] update to [[hListing]].

{{cc0-owfa-license}}

== Draft Proposal ==

===Editors===
* [[User:Tantek|Tantek Çelik]]
* [[User:TomMorris|Tom Morris]]
* [[User:ChiefRA|Arthur Rădulescu]]

===Authors and Contributors===

==Introduction==
Individuals and professionals are increasingly publishing their offerings online: whether as items for sale or rent (cars, homes, apartments), services for hire (music lessons, dog walker, plumber), openings (jobs, volunteers, extra spot in a book club) or personals (people looking for dates, companions, roommates). The goal of publishing (and promoting) these listings online is to seek out interested parties, often within a limited time period.

While descriptions of products and services are common on the Web, particularly on e-commerce sites, we are proposing an hListing microformat for sharing, searching, and syndicating the information that helps match up buyers and sellers. This proposal follows the common practices of trading sites such as Craigslist, eBay and newspaper classifieds.

If [[hreview|hReview]] is about an item and what you think of it, h-listing is about an item and what you want to ''do'' with it.

=== Inspiration and Acknowledgments ===
Thanks to everyone who participated in the initial burst of hListing activity in August 2005, particularly Emiliano Martínez Luque and Trevor O'Reilly, for naming the effort and organizing the listing-{brainstorming, formats, examples} pages on the wiki. We would like to thank Tantek for an initial debate about whether to extend hReview or pursue an independent-though-similar hListing and later on, h-Listing for our proposal.

=== Scope ===

== Format ==

=== In General ===
The h-listing format is based on a set of fields common to numerous listing sites and formats in use today on the web. Where possible field names have been chosen based on those defined by the related [[hreview|hReview]], [[hcard|hCard]], [[hcalendar|hCalendar]] standards.

=== Properties ===
(Not yet finished)

The class '''<code>h-listing</code>''' is a ''root class name'' that indicates the presence of an h-Listing.

* <kbd>h-listing</kbd>: root
** <kbd>p-lister</kbd>: [[h-card]]
** <kbd>dt-listed</kbd>: datetime, optional
** <kbd>dt-expired</kbd>: datetime, optional
** <kbd>p-price</kbd>: text, optional (should include a floating-point number with optional ISO currency codes)
** <kbd>p-category</kbd>: text, optional, zero or more
** <kbd>p-action</kbd>: text, optional, one of the following values
*** sell, rent, trade, meet, announce, offer, wanted, event, service
** <kbd>u-url</kbd>

==== Summary of Changes ====
* Modified to use [[microformats-2]].
* The <kbd>version</kbd> property from [[hListing]] has been deprecated. No hListing markup (even in example files used by parsers) has ever been presented that actually uses the version property, nor any enumeration of valid values. No other microformat thus far has had a version property, and explicit versioning seems like clumsy design: any future changes to the specification should be made in such a way as to support existing content and degrade gracefully per the [http://www.w3.org/TR/html-design-principles/#compatibility design principles of HTML].
* The <kbd>dtlisted</kbd> and <kbd>dtexpired</kbd> properties are prefixed with <kbd>dt-</kbd> in microformats2 anyway, so no duplication of the <kbd>dt</kbd> is needed.
* <kbd>lister</kbd> must contain an embedded <kbd>[[h-card]]</kbd> object for simplicity—the [[microformats-2-parsing]] specification would need to be modified to specify any optimisations there.
* The use of [[rel-tag]] has been deprecated due to the <kbd>rel</kbd> attribute being defined as document scoped in HTML5. Following on from the example of <kbd>[[h-entry]]</kbd>, <kbd>category</kbd> seems the ideal mapping.
* <kbd>permalink</kbd> has been replaced with <kbd>url</kbd> following [[h-entry]].

==Property Details==

h-Listing property details:

==Authoring guidelines==

=== action type internationalisation ===
One issue with hard-coded action types is it prevents internationalisation.

The <kbd>p-</kbd> value [[microformats-2-parsing#parsing_a_p-_property|parsing algorithm]] can be used to provide an alternative text description in a non-English language, at the cost of introducing [[invisible data]].

For instance, one could use a <kbd>data</kbd> element.

<syntaxhighlight lang="html">
<section class="h-listing" lang="fr">
<h1><data class="action" value="sale">À vendre</data>! <span class="summary">Belle usine widget pour produire widgets magique et révolutionnaire</span></h1>
</section>
</syntaxhighlight>

==Examples==

=== Challenges and problems ===

See [[h-listing-challenges|h-Listing Challenge Problems]] for some hypothetical examples that illustrate corners of the specification.

* If no action is specified, should parsers assume the 'sale' property? A listing with no action seems less than useful.

== Examples in the Wild ==
This section is '''informative'''.

The following sites have implemented [[h-listing]], and thus are a great place to start for anyone looking for examples "in the wild" to try parsing, indexing, organizing etc. If your site is marked up with hListing, feel free to add it to the '''top''' of this list. Include both a URL to the top level site, and at least one URL to a specific hListing item on that site so that the hListing markup can be verified.

Once the list grows too big, we'll make a separate wiki page like [[h-listing-examples-in-wild]].

== implementations ==
Please add links to sites that consume h-listings, and tools which generate h-listings.
* ...

==Changes==

== Background ==
Unlike [[hCard]], [[hCalendar]], [[hReview]] and other microformats, hListing has not been nearly as widely adopted. A number of inconsistencies and unclear properties has led to difficulty by page authors to implement the microformat.

== Discussions ==
* Feedback is encouraged on the [[h-listing-feedback]] page.

===Internationalization===
''Internationalization:'' Though there are many English-language tokens, they are only used as class-names; user-visible listing information can be completely localized. N.b. that (X)HTML lang attribute rules still apply as usual, for multilingual aggregators of h-Listings.

== See also==
* [[h-listing]], a draft reboot of hListing based on [[microformats-2]]
* [[h-listing-issues]]
* [[h-listing-feedback]]
* [[h-listing-brainstorming]]
* [[commerce-examples]]
* [[currency]] proposal

[[Category:Draft Specifications]]