microformats2: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(moved redundant sections and secondary information (compatibility with other syntaxes etc.) to FAQ)
(→‎Implementations: microformats.io links, commented out Glenn's since it's not working currently)
 
(250 intermediate revisions by 30 users not shown)
Line 1: Line 1:
2004: In early February microformats were introduced as a concept at eTech, and in September [[hCard]] and [[hCalendar]] were proposed at FOO Camp.
<span style="float:right">__TOC__</span>
Welcome to the microformats2 home page.


2010:
== Summary ==
* 34% of webdevs use microformats ([http://www.webdirections.org/sotw10/markup/#semantics 2010 State of Web Development survey])
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).
* 1.88 billion hCards (per [[Yahoo]] SearchMonkey)
* 36 million hCalendar events (ibid)


* XFN -> Social Graph API -> Web as Social Network / Address Book
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]].


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


'''How can we make it easier for authors to publish microformats?'''
Parsed JSON:
<syntaxhighlight lang="json">
{
  "items": [{
    "type": ["h-card"],
    "properties": {
      "name": ["Frances Berriman"]
    }
  }]
}
</syntaxhighlight>


Currently the simplest hCard:
 
<source lang=html4strict>
----
<span class="vcard">
 
   <span class="fn">
==== hyperlinked person ====
     Chris Messina
* 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>&lt;audio></code>
* '''<code>u-video</code>''' - consider special u- parsing rules for <code>&lt;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> &amp; <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>
   </span>
</span>
</div>
</source>
</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>


requires 2 elements (nested, with perhaps at least one being pre-existing), and 2 class names
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>&lt;abbr&gt;</code> element.


Web authors/designers are used to the simplicity of most HTML tags, e.g. to mark up a heading:
=== 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:


<source lang=html4strict>
[http://blog.lizardwrangler.com Mitchell Baker] (Mozilla Foundation)
<h1>Chris Messina</h1>
</source>


requires just 1 element.
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>


'''How can we make microformats just as easy?'''
Parsed JSON:
<syntaxhighlight lang="json">
{
  "items": [{
    "type": ["h-card"],
    "properties": {
      "name": ["Mitchell Baker"],
      "url": ["http://blog.lizardwrangler.com/"],
      "org": ["Mozilla Foundation"]
    }
  }]
}
</syntaxhighlight>


'''Proposal: allow root class name only.'''
Sometimes such organization affiliations are hyperlinked to the website of the organization:


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


<source lang=html4strict>
You can mark that up with a nested h-card:
<h1 class="vcard">Chris Messina</h1>
<syntaxhighlight lang="html">
</source>
<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>


requiring only 1 class name for the simplest case.
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>


'''Can we do even better?'''
Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an <code>&lt;a href&gt;</code> would.


One of the most common questions asked about hCard is:


[[hcard-faq#Why_does_hCard_use_vcard_as_the_root_class_name|Why does hCard use vcard as the root class name?]]
'''FOR PARSERS ONLY:'''


This slight inconsistency between the name of the format and the name of the root class name consistently causes confusion in a large percentage of newcomers to microformats.
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'.
* Looks like a typo (just one letter difference)
* Ambiguity in discussions, e.g. put "vcard" in your HTML - meaning, class name, or a link to a .vcf file?
* Extra bit to remember when marking up a microformat
** in contrast to [[hReview]], [[hListing]], [[hRecipe]], etc. which all have root class name same as name of microformat (lowercased).


Though in microformats we believe very strongly in the [[principle]] of [[reuse]], we have to admit that in this case experience/evidence has shown that this may be a case where we re-used something too far beyond it's original meaning. Thus:
<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>


'''Proposal: use root class name "hcard" instead of "vcard" for future hCards.'''
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>


This would result in:


<source lang=html4strict>
'''FOR PARSERS ONLY:'''
<h1 class="hcard">Chris Messina</h1>
</source>


making the simple case even simpler:
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:


Just 1 additional class name, named the same as the format you're adding. Think hCard, markup class="hcard".
<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>


It's very important for the simple case to be as simple as possible, to enable the maximum number of people to get started with minimum effort.
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>


From there on, it's ok to require incremental effort for incremental return.
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.


E.g. to add any additional information about a person, add explicit property names.
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.


'''How does this simple root-only case work?'''
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').


* root class name reflects name of the microformat
'''FOR PARSERS ONLY:'''
* every microformat must require at most 1 property (preferably 0)
** admit that requiring a field in an application just results in noise (the 90210 problem - apps which require zip code get lots of false 90210 entries), and specify that any application use cases which appear to "require" specific properties must instead define how to imply sensible defaults for them.
* when only a root class name is specified, imply the entire text contents of the element as the value of the primary property of the microformat. e.g.
** "hcard" implies "fn"
** hcalendar event - "hevent" - implies "summary"
** "hreview" implies "summary"
** "hentry" implies "entry-summary" (perhaps collapse into "summary" - in practice they're not sufficiently semantically distinct to require separate property names)
** '''OR''' instead of making the one implied property be vocabulary specific, introduce a new generic (applicable to all vocabularies) 'name' property (subsuming hCard's 'fn'). See [[microformats-2-brainstorming#further_simplifications|microformats 2 brainstorming: further simplifications]] for latest thoughts along these lines.


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


'''What more can we simplify about microformats?'''
<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>


Numerous individuals have provided the feedback that whenever there is more than one level of hierarchy in a microformat, many (most?) developers get confused - in particular Kavi Goel of Google / Rich Snippets provided this feedback at a microformats dinner.  Thus depending on multiple levels of hierarchy is likely resulting in a loss of authorability, perhaps even accuracy as confusion undoubtedly leads to more errors. Thus:
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>


'''Proposal: simplify all microformats to flat sets of properties. '''
'''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].'''


What this means:
== authoring ==
* all microformats are simply an object with a set of properties with values.
=== minimal markup ===
* no more subproperties- drop the notion of subproperties.
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.
* use composition of multiple microformats for any further hierarchy, e.g. the "location" of an hCalendar event can be an hCard, or the "agent" of one hCard can be another hCard.


For example for hCard this would mean the following specific changes to keep relevant functionality:
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.
* drop "n", promote all "n" subproperties to full properties
** given-name, family-name, additional-name, honorific-prefix, honorific-suffix
* treat "geo" as a nested microformat
* treat "adr" as a nested microformat (what to do about adr's "type"?)
* treat "org" as a flat string and drop "organization-name" and "organization-unit" (in practice rarely used, also not revealed or ignored in contact management user interfaces - e.g. Address Book)


Example: add a middle initial to the previous example Chris Messina's name, and markup each name component:
See the [[microformats-2#simple_microformats_2_examples|simple examples at the top]] for a start, e.g.


<source lang=html4strict>
Simple hCards work just by adding <code>class="h-card"</code> :
<h1 class="hcard">
<syntaxhighlight lang="html">
<span class="fn">
<span class="h-card">Frances Berriman</span>
  <span class="given-name">Chris</span>
  <abbr class="additional-name">R.</abbr>
  <span class="family-name">Messina</span>
</span>
</h1>
</source>


Note:
<a class="h-card" href="http://benward.me">Ben Ward</a>
# use of an explicit span with "fn" to markup his entire formatted name
# use of the abbr element to explicitly indicate the semantic that "R." is merely an abbreviation for his additional-name.


=== COMMUNITY and TOOLS ===
<img class="h-card" alt="Sally Ride"
(that) USE MICROFORMATS
    src="http://upload.wikimedia.org/wikipedia/commons/a/a4/Ride-s.jpg"/>
* parser / parsing
* structured
* getting the data out
* json - 1:1 mapping


[[parsing]] microformats currently requires
<a class="h-card" href="http://tantek.com">
# a list of root class names of each microformat to be parsed
<img alt="Tantek Çelik" src="http://ttk.me/logo.jpg"/>
# a list of properties for each specific microformats, along with knowledge of the type of each property in order to parse their data from potentially different portions of the HTML markup
</a>
# some number of format-specific specific rules (markup/content optimizations)
</syntaxhighlight>


This has meant that whenever a new microformat is drafted/specificied/adopted, parsers need to updated to handle it correctly, at a minimum to parse them when inside other microformats and avoid errantly implying properties from one to the other (containment, [[mfo]] problem).
* 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.


I think there is a fairly simple solution to #1 and #2 from the above list, and we can make progress towards minimizing #3. In short:
=== 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.


'''Proposal: a set of naming conventions for microformat root class names and properties that make it obvious when:'''
In short: use both sets of class names simultaneously.  
* a class name represents a microformat root class name
* a class name represents a microformat property name
* a class name represents a microformat property that needs special parsing (specific type of property).


In particular - derived from the real world examples of existing proven microformats (rather than any abstraction of what a schema should have)
When doing so, use them on the same element, with the microformats-2 class name first, followed immediately by the existing microformats class name.
* '''"h-*" for root class names''', e.g. "h-card", "h-event", "h-entry"
* '''"p-*" for simple (text) properties''', e.g. "p-fn", "p-summary"
** vocabulary generic parsing, element text in general, treat certain HTML element/attribute combination as special and use those first, e.g. img/alt, abbr/title.
* '''"u-*" for URL properties''', e.g. "u-url", "u-photo", "u-logo"
** special parsing required: prefer a/href, img/src, object/data etc. attributes to element contents.
* '''"d-*" for datetime properties''', e.g. "d-start", "d-end", "d-bday"  (initially I had proposed "dt-*" but Chris Messina suggested reducing it to "d-*" so that all prefixes were a single letter - made sense).
** special parsing required: [[value-class-pattern]], in particular separate date time value parsing for better human readabillity / DRY balance.
possibly also:
* '''"e-*" for properties''' where the entire contained element hierarchy is the value, e.g. "e-content" (formerly "entry-content") for [[hAtom]].
** unclear if this is necessary in general. and if so, if this is only for hAtom, that's insufficient to justify putting it in the generic syntax.
* '''"i-*" for ID properties''', e.g. "i-uid" (if this is the only one, then perhaps we just always re-use "uid" or collapse with "u-*" into "u-id".)
** parsing is no different than "u-*" parsing, thus no need to introduce for now.
* '''"n-*" for numbers''', e.g. "n-rating", "n-geo", where the numbers may have different human-readable-friendly and decimal/machine values (e.g. with geo lat/long degrees minutes seconds vs decimal).
** requires definition of how would different parsing work before worthy of consideration.
* '''"t-*" for time duration''', e.g. "t-duration" in [[hCalendar]], [[hAudio]], [[hRecipe]] (note also Google's hRecipe extensions "preptime", "cooktime", "totaltime")
** requires definition of how would different parsing work before worthy of consideration.
and:
* '''reserve all other single-letter-dash prefixes for future use.'''  In practice we have seen very little (if any) use of single-letter-dash prefixing of class names by web developers/designers, and thus in practice we think this will have little if any impact/collisions.  Certainly far fewer than existing generic microformat property class names like "title", "note", "summary".


Example: taking that simple heading hCard example forward:
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>&lt;span&gt;</code>) to separate the root class name element from explicit property class name elements:


<source lang=html4strict>
<syntaxhighlight lang="html">
<h1 class="h-card">Chris Messina</h1>
<span class="h-card vcard">
</source>
  <span class="p-name fn">Frances Berriman</span>
</span>


As part of microformats 2.0 we would immediately define root class names and property names for all existing microformats and drafts consistent with this naming convention, and require support thereof from all new implementations, as well as strongly encouraging existing implementations to adopt the simplified microformats 2.0 syntax and mechanism.
<span class="h-card vcard">
  <a class="p-name fn u-url url" href="http://benward.me">Ben Ward</a>
</span>


As a community we would continue to use the microformats [[process]] both for researching and determining the need for new microformats, and for naming new microformat property names for maximum re-use and interoperability of a shared vocabulary.
<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>


If it turns out we need a new property type in the future, we can use one of the remaining single-letter-prefixes to add it to microformats 2.0. This would require updating of parsers of course, but in practice the number of different types of properties has grown very slowly, and we know from other schema/programming languages that there's always some small limited number of scalar/atomic property types that you need, and using those you can create compound types/objects that represent richer / more complicated types of data.
<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>


==== ADVANTAGES ====
This has numerous advantages:
* '''better maintainability''' - much more obvious to web authors/designers/publishers which class names are for/from microformats.
* '''no chance of collision''' - for all practical purposes with existing class names and thus avoiding any need to add more complex CSS style rules to prevent unintended styling effects.
* '''simple universal parsing''' - parsers can now do a simple stream-parse (or in-order DOM tree walk) and parse out '''all''' microformat objects, properties, and values, without having to know anything about any specific microformats.


More examples: here is that same heading example with name components:
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>


<source lang=html4strict>
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.
<h1 class="h-card">
<span class="p-fn">
  <span class="p-given-name">Chris</span>
  <abbr class="p-additional-name">R.</abbr>
  <span class="p-family-name">Messina</span>
</span>
</h1>
</source>


with a hyperlink to Chris's URL:
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?]]


<source lang=html4strict>
== extensions ==
<h1 class="h-card">
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.
<a class="p-fn u-url" href="http://factoryjoe.com/">
  <span class="p-given-name">Chris</span>
  <abbr class="p-additional-name">R.</abbr>
  <span class="p-family-name">Messina</span>
</a>
</h1>
</source>


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


==== COMPATIBILITY ====
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.


microformats 2.0 is backwards compatible in that in permits content authors to markup with both old and new class names for compatibility with old tools.
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


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


<source lang=html4strict>
See [[microformats2-experimental-properties]] for more examples.
<h1 class="h-card vcard">
<span class="fn">Chris Messina</span>
</h1>
</source>


a microformats 2.0 parser would see the class name "h-card" and imply the one required property from the contents, while a microformats 1.0 parser would find the class name "vcard" and then look for the class name "fn". no data duplication is required. this is a very important continuing application of the <abbr title="don't repeat yourself">DRY</abbr> [[principle]].
=== <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'.


And the above hyperlinked example with both sets of class names:
* '*-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)


<source lang=html4strict>
Examples:
<h1 class="h-card vcard">
* "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "one-ring" microformat root class name.
<a class="p-fn u-url n fn url" href="http://factoryjoe.com/">
* "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.)
  <span class="p-given-name given-name">Chris</span>
  <abbr class="p-additional-name additional-name">R.</abbr>
  <span class="p-family-name family-name">Messina</span>
</a>
</h1>
</source>


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


==== VENDOR EXTENSIONS ====
=== 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]


(this section was only discussed verbally and not written up during discussions - capturing here as it is topical)
In particular:


Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.
Proprietary extensions to formats have typically been shortlived experimental failures with one big recent exception.
Line 252: Line 1,032:
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.
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 has in recent years allowed the larger web design/development/implementor communities to experiment and iterate on new CSS features while the features were being developed and standardized.
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:
The benefits have been two-fold:
Line 268: Line 1,048:
* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])
* image/x-png (standardized as image/png, both per [http://tools.ietf.org/html/rfc2083 RFC2083])


There have been times when specific sites have wanted to extend microformats beyond what the set of properties in the microformat, 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:
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")
<!-- * http://glennjones.net/tools/microformats/ -->
 
=== 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>


'''Proposal:'''
=== Converters ===
* '*-x-' + '-' + meaningful name for root and property class names
* '''[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.
** where "*" indicates the single-character-prefix as defined above
 
** where "x" indicates a literal 'x' for an experimental extension OR
* '''[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])
** OR "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-)
** e.g.
** "h-bigco-one-ring" - a hypothetical "bigco" vendor-specific "onering" 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.)
** "p-x-prep-time" - a possible experimental property name to be added to hRecipe upon consideration/documentation of real-world usage/uptake.


Background - this proposal is a composition of the following (at least somewhat) successful vendor extension syntaxes
* '''[https://xray.p3k.io XRay]''' ([https://github.com/aaronpk/XRay source code]) - Returns a normalized representation of the microformats data at a URL
* [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)


==== FURTHER THOUGHTS REGARDING HUNGARIAN PREFIXING ====
=== Parsers ===
Parsers, open source libraries, in alphabetical order by programming language:


Microformats 2.0 proposes using an explicit <code>[a-z]-</code> prefix on properties, to differentiate them from other uses of the class attribute, and identify them as microformat properties, such that they can be parsed generically.
If you are implementing a microformats2 parser, see:
* [[microformats2-parsing]]


* The differentiation use case is supported by anecdotal evidence of sites (such as Facebook, Twitter, Yahoo) removing microformats or breaking objects in page edits. The addition of a prefix assists self-documentation of code.
==== Parsers in production ====
* The generic parsing use case is supported by Google Rich Snippets, Yahoo Search Monkey, and extensible plugins like Operator and the Firefox microformats parser. Although these extract microformats from the page, they are intermediate systems between the page content and the actual interpretation of the data. They need to parse all objects from a page, and then another developer or application will interpret some of them into something else.
The following parsers are of very high quality, in active development, and use on live sites on the web in production.


(Note: the theoretical assertion "they need to parse all objects from a page" is not actually backed by *any* existing use of microformats/microdata/RDFa parsing - *none* of those parse "all objects from a page" if you consider every markup element an "object" - rather, one of the strength of microformats (mimicked by the others) is that the publisher is able to markup *just* the data to be extracted, rather than perhaps purely "presentational" content, ads, UI widgets etc. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC) )
===== 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


The µf2 proposal goes further, though, into a small vocabulary of [http://en.wikipedia.org/wiki/Hungarian_notation Hungarian] prefixes of properties based on data type. This increases the level of understanding required to read microformats, and reduces the benefit of all microformat properties having a consistent identifying prefix.
===== 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/


(Debatable assertion:"increases the level of understanding required to read microformats" - how? In microformats 2.0, authors/developers know that any single-letter-and-hyphen prefixed class name is for microformats 2.0, in contrast to today - developers have consistently given feedback that's hard to tell which generic class names (other than h* names) are microformat related and which are not. As for specific prefixes, "h-*" is special and follows the pattern of existing microformats. p = generic (p)roperty, and the other prefixes have trivial mnemonics as well, d for (d)atetimes etc. (so far, hopefully we can keep that up). -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC) )
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
<!-- glennjones.net expired SSL cert as of 2018-358 or earlier
** blog post: http://glennjones.net/2013/01/brand-new-microformats-2-parser/
** live: http://glennjones.net/tools/microformats/
-->
** command line: https://github.com/JerrySievert/mf2
* '''microformat-shiv'''  - cross browser javascript microformats2 parser which can also be used in browser extensions.
<!-- ** http://microformatshiv.com/  Unresponsive 2018-358  or earlier -->
** github open source: https://github.com/glennjones/microformat-shiv


Hungarian notation itself is controversial amongst programmers.  
===== PHP =====
Plenty find it uglifies their code, can be a cause of confusion (especially when very-short prefixes are used, or esoteric types, or where the declared set of types differs from the available types in other programming languages.) Others support its benefits to type identification.
* '''<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


(Programmers are not the priority here, rather, designers/authors/publishers are. We design microformats for them first as they're the common use case, and we should avoid making statements that seem to imply any priority for the aesthetic preferences of programmers. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC))
===== 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


Critically, however, there is no clear indication that either of the above use cases requires types to be strongly identified.
===== 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


<div class="discussion">
===== Haskell =====
* For identifying µf in pages, a differentiator is required from regular classnames. There is no evidence of further requirement to differentiate between properties beyond their name (and existing criticisms of Hungarian notation suggest it can harm understandability.)
* '''myfreeweb/microformats2-parser''' Haskell microformats2 parser
** There is such evidence, and perhaps thus this would be a good FAQ topic. The derivation is quite simple - it comes directly from minimally affecting existing markup, and maximally using existing semantic information. Example of special purpose parsing, URL-like properties use the value of the 'href' (or equivalent) attribute because that's where that data already is in pages. Similarly with dates and datetimes - special parsing rules for that data type have permitted us to design the [[value-class-pattern]] to take advantage of specially parsing date and time separation. By re-using data *where publishers already put it, including attributes vs inline* we minimize the risk of data drift. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
** github open source: https://github.com/myfreeweb/microformats2-parser
** Additionally, this special type-specific parsing of microformats properties conveys microformats advantages of markup brevity that other syntaxes lack. E.g. you can convey *multiple* properties and values from a single existing element, e.g. the *very* common real-world pattern <code><br/><nowiki><a href="http://example.com/user">User Name</a></nowiki><br/></code> is minimally marked up as <code><br/><nowiki><span class="h-card"><a class="p-name u-url" href="http://example.com/user">User Name</a></span></nowiki><br/></code>
** live textarea entry: https://unrelenting.technology/mf2/
* For generic parsing, there is no requirement that datatypes be established at extraction time. Data types will instead be applied by the developers of apps and widgets that build on the generic parsers.
** There are requirements based on experience with actual markup. In order to support the patterns of where content publishers put the data we want to extract, we have determined (based on those publishing patterns) a few different ways (types) of parsing this data. This is all captured in the [[hcard-parsing]] property-specific parsing rules each of which were added one at a time as Brian Suda and myself encountered real world sites wanting to use [[hCard]] but not wanting to have to rewrite their markup (adding one span and some class names was about the limit, moving tags/attributes around was a showstopper in many/most cases), and each of the microformats 2.0 "types" are directly derived from such special purpose data/type parsing across *multiple* microformats. -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
* A counter argument may be that special properties in microformats—such as URLs, or images—need to be identified because in microformats it is common to parse an attribute (href, or src) rather than inner text of an element for these properties. However, in the context of extracting and then interpreting HTML in other contexts this is insufficient: For example, though an image only exists as a single property in vcard, in HTML it is both a URL to a resource ''and'' and text string (alt) representing an accessible fallback. A ‘generic extracter’ of microformats from a page must capture all of this information from HTML, so that the interpreting application can choose which data type is most relevant to its context. Likewise, an application interpreting a URL may also consider using the original inner text as an inferred label. Both pieces of data are useful, and a generic parser should not discard elemental semantics at the extraction level.
** It's not just "*common* to parse an attribute rather than inner text of an element for these properties" - it is the vast overwhelming majority - if not all - such cases!
** One misconception: "image only exists as a single property". No, there is both 'photo' and 'logo'. The 'url' and 'sound' properties are also of type 'url'. For all of these, when parsing an "object" element, you must use the 'data' attribute first for example. hCalendar has "attachment" as well. Etc.
** Theoretical assertion: "A ‘generic extracter’ of microformats from a page must capture all of this information from HTML, so that the interpreting application can choose which data type is most relevant to its context." Why? There is no existing nor demonstrated use case for this requirement, even across other formats. While I agree it "might be nice" to develop a new "structured image" type - that's brand new work (deserving of research per the [[process]] etc.), and not a good source of reasoning to reject existing working patterns. I reject blocking microformats 2.0 on an as-yet-to-be-researched-enhancement. This is certainly a case where "better" is an enemy of the good.
** Theoretical assertion: "a generic parser should not discard elemental semantics at the extraction level" - already does for other syntaxes like both microdata and RDFa - so clearly this is not a reasonable "should not" assertion (and thus unnecessary) for development of a minimally competitive syntax. RDFa kind of cheats by overloading the 'rel' attribute in attempt to solve the name+url case as mentioned above, but that's only two types - and existing real world use of microformats has demonstrated utility of a few more.  -- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
</div>


Given this, hungarian prefixes are of no benefit to parsers (and may in fact harm applications down the chain if parsing is prematurely strict.) It would be sufficient then not to concern embedding data types in property names, and instead settle on one single property prefix to differentiate all properties consistently. This would reduce the prefixes to just 3:
==== 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!


* <code>h</code> would indicates a root class name. An ‘object in HTML’.
===== Erlang =====
* <code>p</code> would indicates a property within an object.
* '''hazybluedot/mf2erl''' Erlang microformats2 parser
* <code>x</code> would indicates an experimental extension to an object.
** github open source: https://github.com/hazybluedot/mf2erl


--[[User:BenWard|BenWard]] 01:16, 11 April 2011 (UTC)
===== Elixir =====
* '''ckruse/microformats-elixir''' Elixir microformats2 parser
** github open source: https://github.com/ckruse/microformats2-elixir


The primary benefit of type-specific parsing is *not* for parsers, but rather, publishers (who we still hold in higher priority than parsers).
===== Go =====
* '''willnorris/microformats''' Golang microformats2 parser
** github open source: https://github.com/willnorris/microformats
** live textarea entry: https://go.microformats.io/


I will also note that *each* of the type-specific parsing methods in [[hcard-parsing]] was added both conservatively, reluctantly, and only when it became clear that such type-specific publishing patterns existing across *multiple* sites that would otherwise be unable to change their markup to work with microformats (Yes, I'm wishing now that I better documented exactly *which* sites, precisely *when*, but like many startups, early on we didn't exactly know how much to document vs get things done - frankly I think we documented far more than any other comparable such efforts, e.g. we managed to at least capture/grow both an explicit [[process]] and [[principles]] in *far* greater detail than anything remotely comparable either before microformats or since!). The type-specific parsing features are certainly not overdesigned, on the contrary they've *slowly* evolved, adapting to real world data on the web.
===== 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}


While per the [[simplicity]] principle, I would actually *strongly* prefer to only have the three prefixes given above, or actually just *two* (I started with just two for the design of microformats 2.0 actually, just "h-*" and "p-*"), doing so would be a step *backwards* in terms of the adaptability of microformats to existing markup, and that's IMHO an unacceptable barrier, and  a sufficiently high barrier to hurt the adoption/applicability of microformats 2.0.  
===== Perl =====
* '''Web::Microformats2''' Perl microformats2 parser
** https://metacpan.org/pod/Web::Microformats2
** open source: https://github.com/jmacdotorg/microformats2-perl


(Aside: In addition, note that you still need h-x-* for experimental objects, and thus it's *simpler* to simply have *both* h-x-* and p-x-* rather than add x-*. Alternatively x-h-* and x-p-* is no better, in some ways worse, in that object vs. property is a more important distinction for parsers than established vs experimental, especially if/when an experimental property (or object) may be adopted. Also, mild precdent: PNG started with image/x-png, not x-image/png.).
==== Experiments ====
Experiments and other proof of concept microformat2 parsing support.
* '''Rust''' - https://gitlab.com/maxburon/microformats-parser
* ...


To put it in a positive way, type-specific parsing conveys microformats a publisher-markup-density (and re-use) advantage which neither microdata nor RDFa have, and it would behoove us to *keep* this significant real-world advantage as we evolve microformats.
=== Outreach ===
* [https://github.com/mozilla/fathom/issues/42 Mozilla Fathom:  examples with nested classes, e.g. microformats2]


-- [[User:Tantek|Tantek]] 02:15, 11 April 2011 (UTC)
== 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 &amp; 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.


=== USERS ===
== Testimonials ==
Need more tools and interfaces that:
* <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 &mdash; Joost de Valk (@yoast) [https://twitter.com/yoast/status/298907685452124160 2013-02-05 13:35]</blockquote>
* publish
* <blockquote class="twitter-tweet">... I’m hoping SE’s will pick up microformats2. It’s SO much cleaner. &mdash; Joost de Valk (@yoast) [https://twitter.com/yoast/status/298911287117758464 2013-02-05 13:49]</blockquote>
* copy/paste
* <blockquote class="twitter-tweet">... But damn Microformats2 are sexy. &mdash; Joost de Valk (@yoast) [https://twitter.com/yoast/status/298912179292344320 2013-02-05 13:53]</blockquote>
* right-click on a microformat
* share
* search results


discussed some existing like: [[H2VX]] converts hCard to vCard, hCalendar to iCalendar
== 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.


how would we re-implement Live Clipboard today, making it easier for publishers and developers?
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 ===
== See Also ==
* [[microformats-2-brainstorming]] - moving more experimental / undeveloped / and rejected thoughts ideas here to simplify/progress *this* page further.
* [[microformats2]]
* [[microformats-2-faq]]
* [[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]]

Latest revision as of 19:05, 1 March 2024

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 both authors (publishers) and developers (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 simple microformats2 examples along with canonical JSON.

person example

  • Simple person reference:
<span class="h-card">Frances Berriman</span>

Parsed JSON: 

{
  "items": [{ 
    "type": ["h-card"],
    "properties": {
      "name": ["Frances Berriman"] 
    }
  }]
}


hyperlinked person

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

Parsed JSON: 

{
  "items": [{ 
    "type": ["h-card"],
    "properties": {
      "name": ["Ben Ward"],
      "url": ["http://benward.me"]
    }
  }]
}


hyperlinked person image

  • Simple hyperlinked person image
<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>

Parsed 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"]
    }
  }]
}

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


detailed person example

  • More detailed person
<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>

Parsed 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"
      ]
    }
  }]
}


details from examples

Details demonstrated by the examples:

  1. The JSON "type" uses the full microformat root class name (e.g. "h-card") for consistent identification.
  2. 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.
  • h-* for root class names (e.g. h-card)
  • p-* for plain text properties (e.g. p-name)
  • u-* for URL properties (e.g. u-photo)
  • dt-* for date/time properties (e.g. dt-bday)
  • e-* for embedded markup properties (e.g. e-note)

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: name, url, photo. The simple microformats2 examples above demonstrate these.



Parsing each prefix (including generating canonical JSON) is detailed step-by-step in:

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: draft. Please review and provide feedback in IRC.

See below for vocabulary summaries.

h-adr

Main article: 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: h-adr
profile/itemtype: http://microformats.org/profile/h-adr

properties:

  • p-post-office-box
  • p-extended-address
  • p-street-address
  • p-locality
  • p-region
  • p-postal-code
  • p-country-name
  • p-label - new in vCard4 (RFC6350)
  • p-geo (or u-geo with a RFC 5870 geo: URL) - new in vCard4 (RFC6350)
  • p-latitude - new in vCard4 (RFC6350 from RFC 5870)
  • p-longitude - new in vCard4 (RFC6350 from RFC 5870)
  • p-altitude - 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: adr
properties: (parsed as p- plain text unless otherwise specified)

  • post-office-box
  • extended-address
  • street-address
  • locality
  • region
  • postal-code
  • country-name

h-card

Main article: h-card

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

root class name: h-card
profile/itemtype: http://microformats.org/profile/h-card

properties:

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

Reserved properties: (properties not used much (if at all) in practice)

  • p-organization-name
  • p-organization-unit
  • p-tz
  • dt-rev
  • ...

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: vcard
properties: (parsed as p- plain text unless otherwise specified)

  • fn - parse as p-name
  • honorific-prefix
  • given-name
  • additional-name
  • family-name
  • honorific-suffix
  • nickname
  • email - parse as u-
  • logo - parse as u-
  • photo - parse as u-
  • url - parse as u-
  • uid - parse as u-
  • category
  • adr - parse as p-adr h-adr including compat root class adr
  • extended-address
  • street-address
  • locality
  • region
  • postal-code
  • country-name
  • label
  • geo - parse as p-geo h-geo including compat root class geo
  • latitude
  • longitude
  • tel
  • note
  • bday - parse as dt-
  • key - parse as u-
  • org
  • organization-name
  • organization-unit
  • title - parse as p-job-title
  • role
  • ...

Reserved: (backward compat properties that parsers MAY implement, if they do, they MUST implement in this way:

  • tz
  • rev - 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 article: 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: h-entry
profile/itemtype: http://microformats.org/profile/h-entry

properties:

  • p-name (was p-entry-title, see issues)
  • p-summary (was p-entry-summary, see issues)
  • e-content (was e-entry-content, see issues)
  • dt-published
  • dt-updated
  • p-author
  • p-category
  • u-url
  • u-uid
  • p-geo
  • p-latitude
  • p-longitude

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:

  • u-photo
  • u-audio - consider special u- parsing rules for <audio>
  • u-video - consider special u- parsing rules for <video>
  • u-in-reply-to - 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 p-name over p-entry-title, and use p-entry-title value(s) as a fallback if there is no p-name.

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: hentry
properties: (parsed as p- plain text unless otherwise specified)

  • entry-title - parse as p-name
  • entry-summary
  • entry-content - parse as e-
  • published - parse as dt-
  • updated - parse as dt-
  • author - including compat root vcard in the absence of h-card
  • category
  • geo - parse as p-geo h-geo including compat root geo
  • latitude
  • longitude
  • ...

FAQ:

  • What is the p-name of a note?
    • A few options, from simplest to most detailed.
      • same as the p-content/e-content property.
      • same as the title 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 syndication and link-preview purposes to provide just the first sentence of the note as the p-name. Similarly if only a portion of the content is syndicated to other sites, that portion can be marked up as the p-summary.
  • ...

Resolved Issues:

  • 2012-245 Resolved. See 2012-243 IRC discussion/consensus for:
    • Use p-summary instead of p-entry-summary. 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 e-content instead of e-entry-content. Same point and advantage. In microformats2, entry-content is no more.
    • drop p-entry-title. 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 article: h-event

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

root class name: h-event
profile/itemtype: http://microformats.org/profile/h-event

properties:

  • p-name
  • p-summary(*)
  • dt-start
  • dt-end
  • dt-duration
  • p-description
  • u-url
  • p-category
  • p-location
  • p-geo
  • p-latitude
  • p-longitude
  • ...

This is an update to hCalendar.

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

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: vevent
properties: (parsed as p- plain text unless otherwise specified)

  • summary - parse as p-name
  • dtstart - parse as dt-start
  • dtend - parse as dt-end
  • duration - parse as dt-duration
  • description
  • url - parse as u-
  • category
  • location - including compat root vcard in the absence of h-card, and compat root adr in the absence of h-adr
  • geo - parse as p-geo h-geo including compat root geo
  • latitude
  • longitude
  • ...

h-geo

Main article: h-geo

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

root class name: h-geo
profile/itemtype: http://microformats.org/profile/h-geo

properties:

  • p-latitude
  • p-longitude
  • p-altitude - 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: geo properties: (parsed as p- plain text unless otherwise specified)

  • latitude
  • longitude

h-item

Main article: 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: h-item
profile/itemtype: http://microformats.org/profile/h-item

properties:

  • p-name
  • u-photo
  • u-url

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 article: h-product

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

root class name: h-product
profile/itemtype: http://microformats.org/profile/h-product

properties:

  • p-name - name of the product
  • u-photo - photo of the product
  • p-brand - manufacturer, can also be a nested h-card
  • p-category - freeform categories or tags applied to the item by the reviewer
  • e-description
  • u-url - URL of the product
  • u-identifier - includes type (e.g. mpn, upc, isbn, issn, sn, vin, sku etc.) and value.
  • p-review - a review of the product, can also be a nested h-review
  • p-price - 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: hproduct
properties: (parsed as p- plain text unless otherwise specified)

  • fn - parse as p-name
  • photo - parse as u-
  • brand
  • category
  • description
  • identifier - parse as u-
  • url - parse as u-
  • review - including compat root class hreview in the absence of h-review
  • price

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 article: h-recipe

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

root class name: h-recipe
profile/itemtype: http://microformats.org/profile/h-recipe

properties:

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

Experimental properties with wide adoption

  • p-summary - provides a short summary or introduction
  • p-author - the person who wrote the recipe with h-card
  • dt-published - the date the recipe was published
  • p-nutrition - 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: hrecipe
properties: (parsed as p- plain text unless otherwise specified)

  • fn - parse as p-name
  • ingredient
  • yield
  • instructions - parse as e-
  • duration - parse as dt-
  • photo - parse as u-
  • summary
  • author - including compat root vcard in the absence of h-card
  • nutrition

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 article: h-resume

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

root class name: h-resume
profile/itemtype: http://microformats.org/profile/h-resume

properties:

  • p-summary - overview of qualifications and objectives
  • p-contact - current contact info in an h-card
  • p-education - an education h-calendar event, years, nested h-card of the school, location.
  • p-experience - a job or other professional experience h-calendar event, years, nested h-card of the organization, location, job-title.
  • p-skill - a skill or ability, optionally including level and/or duration of experience
  • p-affiliation - an affiliation with an h-card 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: hresume
properties: (parsed as p- plain text unless otherwise specified)

  • summary
  • contact - including compat root vcard in the absence of h-card
  • education - including compat root vevent in the absence of h-event
  • experience - including compat root vevent in the absence of h-event
  • skill
  • affiliation - including compat root vcard in the absence of h-card

Note: skill has a 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 article: h-review

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

root class name: h-review
profile/itemtype: http://microformats.org/profile/h-review

properties:

  • p-name - name of the review
  • p-item - 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).
  • p-reviewer - person who authored the review
  • dt-reviewed - date time of when the review was written
  • p-rating - value from 1-5 indicating a rating for the item (5 best).
  • p-best - define best rating value. can be numerically lower than worst.
  • p-worst - define worst rating value. can be numerically higher than best.
  • e-description - the full text written evaluation and opinion of the reviewer
  • p-category - freeform categories or tags applied to the item by the reviewer
  • u-url - 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: hreview
properties: (parsed as p- plain text unless otherwise specified)

  • summary parse as p-name
  • fn - parse as p-name of the item being reviewed (p-item h-item p-name)
  • photo - parse as u-photo of the item being reviewed (p-item h-item u-photo)
  • url - parse as u-url of the item being reviewed (p-item h-item u-url)
  • reviewer - including compat root vcard in the absence of h-card
  • dtreviewed - parse as dt-
  • rating
  • best
  • worst
  • description - parse as e-
  • rel="tag" - parse as p-category
  • rel="self bookmark" - parse as u-url. note that rel attribute value is treated as a space separated set, thus any presence of "self" and "bookmark" within such a set in a rel value is accepted.

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

h-review-aggregate

Main article: 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: h-review-aggregate
profile/itemtype: http://microformats.org/profile/h-review-aggregate

properties:

  • p-name - name of the review
  • p-item - 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).
  • p-rating - value from 1-5 indicating average rating for the item (5 best).
  • p-best - define best rating value. can be numerically lower than worst.
  • p-worst - define worst rating value. can be numerically higher than best.
  • p-count - number of reviews aggregated.
  • p-votes - number of reviewers who have rated the product, thus contributing to the average rating.
  • p-category - freeform categories or tags applied to the item by the reviewer
  • u-url - 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: hreview-aggregate
properties: (parsed as p- plain text unless otherwise specified)

  • summary parse as p-name
  • fn - parse as p-name of the item being reviewed (p-item h-item p-name)
  • photo - parse as u-photo of the item being reviewed (p-item h-item u-photo)
  • url - parse as u-url of the item being reviewed (p-item h-item u-url)
  • rating
  • best
  • worst
  • count
  • votes
  • rel="tag" - parse as p-category
  • rel="self bookmark" - parse as u-url. note that rel attribute value is treated as a space separated set, thus any presence of "self" and "bookmark" within such a set in a rel value is accepted.


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 profile attribute, microdata itemtype attribute, and RDFa vocab & typeof 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 http://microformats.org/profile/h-* URLs mentioned above.
  • Provide any necessary microdata-specific language as needed (e.g. to be comparably understandable to the 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 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: 

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

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: 

{
  "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"]
        }
      }]
    }
  }]
}

Questions:

  • Should the nested hCard be present also as a top-level item in the JSON? - Tantek 02:02, 19 June 2012 (UTC)
    • My current (2012-243) leaning is no. - 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? - 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. - 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? - Tantek 02:02, 19 June 2012 (UTC)
      • If so, what convention does/do JSON follow for such synthetic local reference identifiers? - Tantek 02:02, 19 June 2012 (UTC)

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 title attribute of its <abbr> 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:

Mitchell Baker (Mozilla Foundation)

with source: 

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

Parsed JSON: 

{
  "items": [{ 
    "type": ["h-card"],
    "properties": {
      "name": ["Mitchell Baker"],
      "url": ["http://blog.lizardwrangler.com/"],
      "org": ["Mozilla Foundation"]
    }
  }]
}

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

Mitchell Baker (Mozilla Foundation)

You can mark that up with a nested h-card: 

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

Parsed 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/"]
        }
      }]
    }
  }]
}

Note: the nested h-card has implied 'name' and 'url' properties, just like any other root-class-name-only h-card on an <a href> 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'. 

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

Parsed 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/"]
        }
      }]
    }
  }]
}


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: 

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

Parsed 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/"]
      }  
    }]
  }]
}

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: 

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

Parsed 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/"]
      }  
    }]
  }]
}

TO DO: Add h-event h-card example and JSON, per real world publishing examples like 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 simple examples at the top for a start, e.g.

Simple hCards work just by adding class="h-card" : 

<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>
  • Tip: Inside an open tag, put the class attribute first, then any human text content attributes (e.g. alt), then URL attributes (e.g. href src), and lastly other attributes (e.g. style). 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 <span>) to separate the root class name element from explicit property class name elements: 

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


Tips:

  • use the microformats-2 class name first, e.g.
    • class="h-card vcard"
    • class="u-url url"
  • and pair them when using an element for multiple properties, e.g.:
    • class="p-name fn u-url url"
    • class="p-name fn u-photo photo"
  • 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:
    • class="event-page h-event vevent"

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: 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 -x- 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.

vendor extensions

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

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 Wikipedia: HTTP header fields - non-standard headers (could use RFC reference instead) respectively, like:

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

See microformats2-origins#VENDOR_EXTENSIONS for more background.

validators

microformats2 validators:

new! Test your microformatted web page with:

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:

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 davidjohnmead.com
  • Brian Suda marks up his blog posts up with h-entry and h-card on optional.is
  • Ashton McAllan marks up her blog posts, reposts, comments and likes with h-entry, h-card and h-cite on acegiak.net
  • Emma Kuo marks up her blog posts and notes with h-entry and h-card on notenoughneon.com
  • Scott Jenson marks up his blog posts with h-entry and h-card on jenson.org
  • Emily McAllen marks up her blog posts with h-entry and h-card on blackwoolholiday.com
  • Ryan Barrett marks up his blog posts, notes, replies and likes with h-entry and h-card on snarfed.org
  • Barry Frost marks up his notes with h-entry, h-card and h-cite on barryfrost.com
  • Amber Case marks up her profile, blog posts, replies and notes with h-entry and h-card on caseorganic.com
  • Johannes Ernst marks up his blog posts with h-entry on upon2020.com
  • Michiel de Jong marks up his profile and notes with h-entry and h-card on michielbdejong.com
  • Mike Taylor marks up his profile and blog posts with h-card and h-entry on bear.im
  • Erin Jo Ritchey marks up her profile, posts and comments using h-card, h-entry and h-cite with idno on erinjo.is
  • Jeena Paradies marks up his profile, blog posts, notes and comments using h-card, h-entry and h-cite on jeena.net
  • Andy Sylvester marks up his profile, blog posts and comments using h-card and h-entry on andysylvester.com (note: as of 2014-03-13 using h-entry for comments instead of correct h-cite --bw 14:44, 13 March 2014 (UTC))
  • Hakan Demir marks up his Coupon and Voucher blog posts with h-entry and h-card on gutscheinflagge.de
  • Chloe Weil marks up her blog posts with h-entry on chloeweil.com
  • Christophe Ducamp marks up his blog posts and profile with h-entry and h-card on christopheducamp.com
  • Glenn Jones marks up his blog posts, notes, replies, profile and comments with h-entry, h-card and h-cite on glennjones.net
  • Marcus Povey marks up his blog posts and profile with h-entry and h-card on marcus-povey.co.uk
  • Eugen Busoiu marks up his web profile with h-card on eugenbusoiu.com]
  • Matthias Pfefferle marks up his blog posts, comments and profile with h-card, h-cite and h-entry on notizblog.org
  • Kyle Mahan marks up his profile and notes with h-card and h-entry on kylewm.com
  • Emil Björklund marks up his blog posts with h-entry and h-card (example)
  • App.net rolled out support for h-card and h-entry on all profile pages and permalink pages as of 2013-08-06 (example)
  • Brett Comnes marks up his posts with h-entry and h-card (example)
  • Ben Werdmuller marks up his posts with h-card and h-entry, u-in-reply-to and u-like (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 (example)
  • Laurent Eschenauer marks up his posts with h-entry (example)
  • Tom Morris marks up his posts using h-entry (example)
  • Sinolandquality marks up some of their content using h-feed and h-entry on sinolandquality.com
  • 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.
  • SemPress is a WordPress theme that supports h-card, h-feed/h-entry and h-as-*
  • 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 his blogroll.
  • Aaron Parecki uses h-card to markup both authorship and references to people in his notes permalinks, e.g. 2012/230/reply/1.
  • 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. 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.
  • Barnaby Walters uses h-card on his home page, h-card, h-entry and XFN markup on his notes page.
    • 2013-01-25 Barnaby Walters: Experimental Markup - describes how he's using microformats2 vocabularies: h-adr, h-card, h-entry, h-event, h-geo, h-review, and experimental vocabularies: h-feed (embedded for update histories), activity-streams objects h-as-article, h-as-collection, h-as-note, h-as-update, as well as experimental properties: u-alternate and u-as-downstream-duplicate (links to POSSE copies), and u-in-reply-to (links to content that the posts are in reply to).
  • microformats.org at 7 years presentation with h-event and h-card markup for people and organizations.
  • 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. search near Portland Oregon) and event pages (e.g. IndieWebCamp 2012).[2]
  • WebFWD by Mozilla has microformats-2 h-card markup on experts and team pages
  • IndieWebCamp has microformats-2 h-event markup with nested h-cards for the organizers and the location.
  • Mozilla Events page has microformats-2 h-event markup with attendees marked up with h-card.
  • The Esri PDX Blog has h-entry markup on all blog posts (as of 2013-10-19), and h-product markup on 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!

Blogging tools

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.

Converters

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

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

Previously:

PHP
Python
Ruby
Haskell

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
Elixir
Go
Java
Perl

Experiments

Experiments and other proof of concept microformat2 parsing support.

Outreach

Presentations

Presentations about microformats2:

Testimonials

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.

See Also

Retrieved from "http://microformats.org/wiki/index.php?title=microformats2&oldid=70684"