microformats2

(Redirected from microformats 2)

Jump to: navigation, search

Welcome to the microformats2 home page.

Contents

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

<span class="h-card">Frances Berriman</span>

Parsed JSON:

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



hyperlinked person

<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

<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

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

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:

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)

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:

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

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)

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

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:

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:

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)

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:

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:

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)

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:

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)

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:

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:

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)

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:

Experimental properties with wide adoption

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)

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:

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)

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:

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)

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:

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)


v2 vocab notes

Notes:

v2 vocab to-do

To do:

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:

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>

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:

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?

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.

offline

Implementations

new! Test your microformatted web page with:

Live Textarea Input

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

Blogging tools

Converters

Parsers

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

Parsers in production

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

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

microformats2 was last modified: Tuesday, July 31st, 2018

Views