Example One #

I’ve used CSS to create an obvious visual cue that this area of text is different from the rest. Note that I’ve future-proofed this with <style scoped>, which I covered in my previous article.

Example Two #

Chris Coyier of CSS-Tricks pointed out that you can let your users edit the CSS in real-time. Because the <style> element is set to display: none by the user agent, we need to set it to block for this code to work.

Try editing the CSS below:

Allow value on any element #

This conflicts with microdata, where the values of some elements are their URLs rather than their content. For example, currently <img itemprop="photo" src="http://oli.jp/photo.jpg"> gives the microdata output of photo = "http://oli.jp/photo.jpg". Adding value to the mix means there’d be two machine-readable values, so authors would need to know which elements couldn’t accept value.

Add a type attribute to <data> #

This means the HTML5 specification has to specify each approved type value. While not as much work for implementers as a new element for each type of data, it’s still a bunch of work if the browsers actually do anything with that knowledge (like auto-converting type="money" into your currency). If type is required it also limits <data> to the types that are defined.

Bring back <time> #

The easiest way to make everyone happy is to keep <time> in addition to adding <data>. However the cons for this are we’d have two confusingly similar but not always interchangeable ways to mark up datetimes, potentially with different rules on what’s a valid datetime. For example, we’d need to mark up an article’s published date and updated date using different syntax. Special cases and exceptions make things harder to teach and learn.

Our starting point

We’ll be using the following code sample as a starting point:

<article>
  <h1>Style Scoped</h1>
  <p>The scoped attribute for the style element will eventually allow for you to include style elements mid-document. To do this, you must mark up your style element with the scoped attribute.</p>
  <section>
    <h2>How does it work?</h2>
    <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>
  </section>
</article>

This is a basic example, with two headings and two paragraphs set within the article element.

Adding the scoped attribute

In the next example, we’ll change the foreground color of the second paragraph to red (from whatever was defined in the master CSS file):

<article>
  <h1>Style Scoped</h1>
  <p>The scoped attribute for the style element will eventually allow for you to include style elements mid-document. To do this, you must mark up your style element with the scoped attribute.</p>
  <section>
    <style scoped>
      p { color: red; }
    </style>
    <h2>How does it work?</h2>
    <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>
  </section>
</article>

This screenshot shows how things might render in the browser:

Overuse of header

As I’m sure you’re aware, the <header> element can be used multiple times in a document, which has popularized the following pattern:

<!-- Don’t copy this code! No need for header here -->
<article>
  <header>  
    <h1>My best blog post</h1>
  </header>
  <!-- Article content -->
</article>

If your <header> element only contains a single heading element, leave out the <header>. The <article> ensures that the heading will be shown in the document outline, and because the <header> doesn’t contain multiple elements (as the definition describes), why write code when you don’t need to? Simply use this:

<article>  
  <h1>My best blog post</h1>
  <!-- Article content -->
</article>

Incorrect use of <hgroup>

On the subject of headers, I also frequently see incorrect uses of <hgroup>. You should not use <hgroup> in conjunction with <header> when:

• there’s only one child heading, or
• the <hgroup> would work fine on its own (i.e., without the <header>).

The first problem looks like this:

<!-- Don’t copy this code! No need for hgroup here -->
<header>
  <hgroup>  
    <h1>My best blog post</h1>
  </hgroup>
  <p>by Rich Clark</p>
</header>

In that case, simply remove the <hgroup> and let the heading run free.

<header>
  <h1>My best blog post</h1>
  <p>by Rich Clark</p>
</header>

The second problem is another case of including elements when they’re not necessarily required.

<!-- Don’t copy this code! No need for header here -->
<header>
  <hgroup>  
    <h1>My company</h1>
    <h2>Established 1893</h2>
  </hgroup>
</header>

When the only child of the <header> is the <hgroup>, why include the <header>? If you don’t have additional elements within the <header> (i.e., siblings of the <hgroup>), simply remove the <header> altogether.

<hgroup>  
  <h1>My company</h1>
  <h2>Established 1893</h2>
</hgroup>

For more <hgroup> examples and explanations, read the detailed article about it in the archives.

Not every image is a figure

Earlier, I told you not to write extra code when it’s not necessary. This mistake is similar. I’ve seen sites where every image has been marked up as a <figure>. There’s no need to add extra markup around your images for the sake of it. You’re just creating more work for yourself and not describing your content any more clearly.

The spec describes <figure> as being some flow content, optionally with a caption, that is self-contained and is typically referenced as a single unit from the main flow of the document. Therein lies the beauty of <figure>, that it can be moved away from the primary content — to a sidebar, say — without affecting the document’s flow.

If it’s a purely presentational image and not referenced elsewhere in the document, then it’s definitely not a <figure>. Other use cases vary, but as a start, ask yourself, Is this image required to understand the current context? If not, it’s probably not a <figure> (an <aside>, perhaps). If so, ask yourself, Could I move this to an appendix? If the answer to both questions is ‘yes’, it’s probably a <figure>.

Your logo is not a figure

Segueing nicely on, the same applies to your logo. Here are a couple of snippets that I see regularly:

<!-- Don’t copy this code! It’s wrong! -->
<header>
  <h1>
    <figure>
      <img src="/img/mylogo.png" alt="My company" class="hide" />
    </figure>
    My company name
  </h1>
</header>

<!-- Don’t copy this code! It’s wrong! -->
<header>  
  <figure>
    <img src="/img/mylogo.png" alt="My company" />
  </figure>
</header>

There’s nothing else to say here. It’s just plain wrong. We could argue until the cows come home about whether your logo should be in an <h1>, but that’s not what we’re here for. The real issue is the abuse of the <figure> element. <figure> should be used only when referenced in a document or surrounding sectioning element. I think it’s fair to say that your logo is rarely going to be referenced in such a way. Quite simply, don’t do it. All you need is this:

<header>  
  <h1>My company name</h1>
  <!-- More stuff in here -->
</header>

Figure can be more than an image

Another common misconception regarding <figure> is that it can only be used for images. This isn’t the case. A <figure> could be video, audio, a chart (in SVG, for example), a quote, a table, a block of code, a piece of prose, or any combination of these and much more besides. Don’t limit your <figure>s to images. Our job as web standards affectionadoes is to accurately describe the content with our markup.

A while back, I wrote about <figure> in more depth. It’s worth a read if you want more detail or need a refresher.

Boolean attributes

Several of the new form attributes are boolean, meaning their mere presence in the markup ensures the behaviour is set. These attributes include:

• autofocus
• autocomplete
• required

Admittedly, I only rarely see this, but using required as an example, I’ve seen the following:

<!-- Don’t copy this code! It’s wrong! -->
<input type="email" name="email" required="true" />
<!-- Another bad example -->
<input type="email" name="email" required="1" />

Ultimately, this causes no harm. The client’s HTML parser sees the required attribute in the markup, so its function will still be applied. But what if you flip the code on its head and type required="false"?

<!-- Don’t copy this code! It’s wrong! -->
<input type="email" name="email" required="false" />

The parser will still see the required attribute and implement the behaviour even though you tried to tell it not to. Certainly not what you wanted.

There are three valid ways for a boolean attribute to be applied. (The second and third options only apply if you’re writing XHTML syntax.)

• required
• required=""
• required="required"

Applying that to our above example, we would write this (in HTML):

<input type="email" name="email" required />

itemscope and itemprop #

<p itemscope>I’m going to the <span itemprop="name">Salter Cane</span> gig next week.
Excited!</p>

The presence of itemscope on the <p> element makes it into a microdata item. The attribute itemprop on a descendent element defines a property of this item (in this case, name) and associates it with the value Salter Cane (the <span>’s content). An item must have at least one itemprop to be valid.

itemprop names can be words or URL strings. Using URLs makes the name globally unique. If you use words, it’s best to use a vocabulary and the names defined in the vocabulary, which also makes the names unique. We cover this in the section Typed items and globally unique names.

itemprop value from an attribute #

For some elements, an itemprop’s value comes from an attribute of the element, not the element’s text. This applies to values from attributes containing URLs, the datetime attribute, and the content attribute.

<p itemscope>I’m going to the <a itemprop="url"
  href="http://www.saltercane.com/">Salter Cane</a> gig 
  <time itemprop="date" datetime="2010-07-18">next week</time>. Excited!</p>

This defines an item with the properties url and date containing the values http://www.saltercane.com/ and 2010-07-18, respectively.

Note that the link’s itemprop="url" value is http://www.saltercane.com/ and not the element’s “Salter Cane” text content. In microdata, the following elements contribute their URLs as values:

• <a href="">
• <area href="">
• <audio src="">
• <embed src="">
• <iframe src="">
• <img src="">
• <link href="">
• <object data="">
• <source src="">
• <video src="">

Similarly, the <time> element’s value is 2010-07-18 and not its text content (i.e., “next week”).

Conversely, the URL-containing attributes of these HTML5 elements are not used as property values:

• <base href="">
• <script src="">
• <input src="">

It's still possible to use the text of one of these elements as its value — e.g., <a href="">desired value</a>. We just need to add an additional itemprop:

<p itemscope>I’m going to the <a itemprop="url" href="http://www.saltercane.com/"><span itemprop="name">Salter Cane</span></a> gig <time itemprop="date" datetime="2010-02-18">next week</time>. They’re gonna rawk!</p>

This defines an item with three properties: the url is http://www.saltercane.com/, the name is Salter Cane, and the date is 2010-07-18.

We’ll return to the <meta> element’s content attribute in just a moment.

Nested items #

We can make a property into a nested item by adding itemscope to an element with itemprop.

<p itemscope>The <span itemprop="name">Salter 
  Cane</span> drummer is <span itemprop="members"
  itemscope><span itemprop="name">Jamie
  Freeman</span>.</span></p>

This defines an item with two properties, name and members. The name is Salter Cane, and the members is a nested item, containing the property name with the value Jamie Freeman. Note that members doesn’t have a text value.

Items that aren’t part of other items (i.e., anything with itemscope but not itemprop, or the child of an element with itemprop) are called top-level microdata items. The microdata API returns top-level microdata items and their properties, which includes nested items.

Multiple properties #

Items can have multiple properties with the same name and different values:

<span itemprop="members" itemscope>The band members are
  <span itemprop="name">Chris Askew</span>,
  <span itemprop="name">Jeremy Keith</span>,
  <span itemprop="name">Jessica Spengler</span> and
  <span itemprop="name">Jamie Freeman</span>.</span>

This defines the property name with four values, Chris Askew, Jeremy Keith, Jessica Spengler and Jamie Freeman.

One element can also have multiple properties (multiple itemprop="" names separated by spaces) with the same value:

<p itemscope><span itemprop="guitar vocals">Chris Askew</span>
  is so dreamy.</p>

This defines the properties guitar and vocals, both of which have the value Chris Askew.

In-page references via itemref #

Items can use non-descendant properties (name-value pairs that aren’t children of the itemscope element) via the attribute itemref="". This attribute is a list of the IDs of properties or nested items elsewhere on the page.

<p itemscope itemref="band-members">I’m going to the
  <a itemprop="url" href="http://www.saltercane.com/">
  <span itemprop="name">Salter Cane</span></a> gig
  <time itemprop="date" datetime="2010-07-18">next 
  week</time>. Excited!</p>
  …
  <p>Salter Cane are <span id="band-members"
  itemprop="members" itemscope>
  <span itemprop="name">Chris Askew</span>, 
  <span itemprop="name">Jeremy Keith</span>, 
  <span itemprop="name">Jessica Spengler</span>
  and <span itemprop="name">Jamie Freeman</span>.</span></p>

This defines the properties url, name, and date. Additionally, it references the ID band-members, which contains the item members with four name properties, each of which have a different value.

Using <meta> to add content via attributes #

If the text you want to add isn’t already part of the page’s content, you can use the content attribute on the <meta> element (<meta itemprop="" content="">) to add it.

<p itemscope><span itemprop="name" itemscope>Jessica Spengler
  <meta itemprop="likes" content="Mameshiba"></span>’s fans are always
  really raucous.</p>

Unfortunately, some current browsers move <meta> elements into the document's <head>. The elegant workaround is to use an in-page reference via itemref, so it’ll be included by tools that understand microdata even if the browser has moved it.

<p itemscope><span itemprop="name" itemscope itemref="meta-likes">
  Jessica Spengler<meta id="meta-likes" itemprop="likes" content="Mameshiba">
  </span>’s fans are always really raucous.</p>

Both of these code snippets define the property name with the value Jessica Spengler and the nested property likes with the value Mameshiba.

While microdata is best suited for annotating your existing content, by using <meta>-based or hidden values, microdata doesn’t have to be tied to a page’s content. In general, adding hidden content to a page is a bad idea. It’s easy to forget about and not keep up-to-date. If the information would be useful to some users, add it to the page’s content. If it’s inconvenient to add the content inside an item, consider putting it in a <footer> and including via an in-page reference.

Typed items (itemtype) and globally unique names #

We can tie an item to a microdata vocabulary by giving it a type, specified via the attribute itemtype="" on an element with itemscope. The itemtype="" value is a URL representing the microdata vocabulary. Note that this URL is only a text string that acts as unique vocabulary identifier — it doesn’t actually need to link to an actual webpage (although it’s nice when it does). After doing this, we can use names in the vocabulary as itemprop names to apply vocabulary-defined semantics.

<p itemscope itemtype="http://schema.org/MusicGroup"> I went to
  hear <a itemprop="url" href="http://saltercane.com/"><span itemprop="name">
  Salter Cane</span></a> last night. They were great!</p>

This example defines the property url with the value http://saltercane.com/ and the property name with the value Salter Cane according to the http://schema.org/MusicGroup vocabulary (MusicGroup is a specialised kind of Organization vocabulary on schema.org).

Alternatively, you can use URLs for itemprop names. In this case, there’s no need to use itemtype as the vocabulary information is already contained in the name. These are referred to as globally unique names. While vocabulary-based names must be used inside a typed item to have the vocabulary-defined meaning, you can use a URL itemprop name anywhere.

Let’s rewrite the above example using URL-based names:

<p itemscope>I went to hear <a
  itemprop="http://schema.org/MusicGroup/url"
  href="http://saltercane.com/"><span
  itemprop="http://schema.org/MusicGroup/name">Salter Cane</span>
  </a> last night. They were great!</p>

This allows you to use multiple vocabularies in the same code snippet, even if they use the same property names.

Global identifiers with itemid #

Sometimes an item may be identified by a unique identifier, such as a book by its ISBN number. This can be done in microdata using a global identifier via the attribute itemid="", if specified by the vocabulary. itemid can only appear on an element with both itemscope and itemtype="", and must be a valid URL.

Using schema.org vocabularies #

2011-08-16 The schema.org vocabularies have now superseded the old Google vocabularies, so I’ve updated the article to reflect this.

Bing, Google and Yahoo have collaborated on a set of microdata vocabularies under the name schema.org. By using these vocabularies we can convey semantic information in our content in a way these search engines can understand. While adding semantics using these vocabularies won’t affect your search ranking, the included data may be shown in search results. The main vocabularies schema.org offers are:

• Creative works: CreativeWork, Book, Movie, MusicRecording, Recipe, TVSeries…
• Embedded non-text objects: AudioObject, ImageObject, VideoObject
• Event
• Organization
• Person
• Place, LocalBusiness, Restaurant…
• Product, Offer, AggregateOffer
• Review, AggregateRating

They’re the cross-search engine successors to Google’s earlier Rich Snippets vocabularies. Unlike Rich Snippets, which came in microformats and RDFa versions, schema.org vocabularies controversially only support microdata at the moment.

Taking our fairly standard HTML5 code for Oliver’s iPad event above, let’s add some microdata pixie dust using the schema.org vocabularies. First, the speaker (using the http://schema.org/Person vocabulary) and the venue (using the http://schema.org/Organization vocabulary):

<section>
  <h3><a href="http://atnd.org/events/5181" title="WDE-ex Vol11『iPad
  のウェブデザイン：私たちがみつけたこと 』 : ATND">WDE-ex Vol.11 — Designing
  for iPad: Our experience so far</a></h3>
  <p>On <time datetime="2010-07-21T19:00:00+09:00">July 21st 19:00
  </time>-<time datetime="2010-07-21T20:00:00+09:00">20:00</time> at
  <span itemscope itemtype="http://schema.org/Organization">
  <a itemprop="url" href="http://www.apple.com/jp/retail/ginza/map/">
  <span itemprop="name">Apple Ginza</span></a></span>,
  <span itemscope itemtype="http://schema.org/Person">
  <a itemprop="url" href="http://informationarchitects.jp/" title="iA">
  <span itemprop="name">Oliver Reichenstein</span>, CEO of iA</a>
  </span>, will share the lessons they’ve learned while creating three
  iPad apps and one iPad website.</p>
</section>

While this content will still look the same, adding these microdata items means the following information is now machine readable:

• A company’s name (name)
• That company’s URL (url on <a>)
• A person’s name (name)
• A URL associated with that person (url on <a>)

In JSON (ref: Live Microdata) this would be:

{
  "items": [
    {
      "type": "http://schema.org/Organization",
      "properties": {
        "url": [
          "http://www.apple.com/jp/retail/ginza/map/"
        ],
        "name": [
          "Apple Ginza"
        ]
      }
    },
    {
      "type": "http://schema.org/Person",
      "properties": {
        "url": [
          "http://informationarchitects.jp/"
        ],
        "name": [
          "Oliver Reichenstein"
        ]
      }
    }
  ]
}

So we now have a semantic association between a company and a URL and between a person and a URL. With the right tool, we could add this information to an address book automatically.

Next, let’s add microdata attributes to the event data, using the http://schema.org/Event vocabulary:

<section itemscope itemtype="http://schema.org/Event">
  <h3><a itemprop="url" href="http://atnd.org/events/5181" title="WDE-ex
  Vol11『iPad のウェブデザイン：私たちがみつけたこと 』 : ATND"><span
  itemprop="summary">WDE-ex Vol.11 — Designing for iPad: Our experience so
  far</span></a></h3>
  <p itemprop="description">On <time itemprop="startDate"
  datetime="2010-07-21T19:00:00+09:00">July 21st 19:00</time>-
  <time itemprop="endDate" datetime="2010-07-21T20:00:00+09:00">20:00
  </time> at <span itemprop="location" itemscope
  itemtype="http://schema.org/Organization"><a itemprop="url"
  href="http://www.apple.com/jp/retail/ginza/map/"><span itemprop="name">
  Apple Ginza</span></a></span>, <span itemscope
  itemtype="http://schema.org/Person"><a itemprop="url"
  href="http://informationarchitects.jp/" title="iA"><span itemprop="name">
  Oliver Reichenstein</span>, CEO of iA</a></span>, will share
  the lessons they’ve learned while creating three iPad apps and
  one iPad website.</p>
</section>

Now things are a lot more interesting! We can extract the following data:

• Event details
  • Event name (summary)
  • Event start and end time (startDate and endDate)
  • Event summary (summary)
  • Event URL (url on <a>)
  • Event location (location), which is represented by:
    • Company name (name)
    • Company URL (url on <a>)
• Speaker details (well, someone connected with the event, although this connection isn’t explicit)
  • A person’s name (name)
  • That person’s associated URL (url)

Google provides a Rich Snippet testing tool, which shows what data it can extract from the schema.org microdata:

Google could use this additional data in search results as follows:

The summary (linked to the event URL) and the date and venue are included. Nice! Just by using a vocabulary, Google (or a script supporting microdata) can discover lots of useful data about our event without needing one of those pesky natural language interpreters (otherwise known as humans).

Anyone who has used microformats before will also notice these vocabularies look very similar to hCard and hCalendar, although there are a couple of name changes — e.g., hCalendar’s class="dtstart" becomes itemprop="startDate".

While the schema.org vocabularies are all the search engines are promising to support, you can extend these vocabularies yourself. The safest ways to do this would be via:

• the Product Types Ontology for products or services, based on Wikipedia
• the GoodRelations vocabulary terms for e-commerce, which is supported (along with hProduct) by Rich Snippets
• making your own schema.org vocabulary extension collaboratively using the schema.org email list (although read Making your own vocabulary later in this article first)

Using Google’s Rich Snippets vocabularies #

Google also has some basic vocabularies (precursors of schema.org vocabularies) for the following kinds of data, under the moniker of Rich Snippets:

• people
• businesses and organizations
• events
• products
• reviews
• recipes

These vocabularies support microformats and RDFa, two other ways to add extra semantics to our content, in addition to microdata. Apart from this difference, they’re basically identical to the matching schema.org vocabularies, except they use www.data-vocabulary.org instead of schema.org in the itemtype. While Google still supports them, the newer schema.org offers more vocabularies that are also supported by Bing and Yahoo, so choose schema.org vocabularies as long as you’re happy with microdata. You might still want to check out the Rich Snippets documentation, as it includes code samples and is generally better than schema.org’s at the time of writing.

Using WHATWG/microformats.org vocabularies #

If you’re familiar with microformats or want more properties than Google’s vocabularies, the WHATWG HTML5 specification actually contains microdata vocabularies for both the vCard and vEvent specifications that hCard and hCalendar are based on, plus a licensing vocabulary.

Let’s take our earlier example and rewrite it using these vocabularies instead:

<section itemscope
  itemtype="http://microformats.org/profile/hcalendar#vevent">
  <h3><a itemprop="url" href="http://atnd.org/events/5181" title="WDE-ex
  Vol11『iPad のウェブデザイン：私たちがみつけたこと 』 : ATND"><span
  itemprop="summary">WDE-ex Vol.11 — Designing for iPad: Our experience so
  far</span></a></h3>
  <p itemprop="description">On <time itemprop="dtstart"
  datetime="2010-07-21T19:00:00+09:00">July 21st 19:00</time>-
  <time itemprop="dtend" datetime="2010-07-21T20:00:00+09:00">20:00</time>
  at <span itemprop="location" itemscope
  itemtype="http://microformats.org/profile/hcard"><a itemprop="url"
  href="http://www.apple.com/jp/retail/ginza/map/"><span itemprop="fn org">
  Apple Ginza</span></a></span>, <span itemscope
  itemtype="http://microformats.org/profile/hcard"><a itemprop="url"
  href="http://informationarchitects.jp/" title="iA"><span itemprop="fn">
  Oliver Reichenstein</span>, CEO of iA</a></span>, will share
  the lessons they’ve learned while creating three iPad apps and one
  iPad website.</p>
</section>

Currently, search engines don’t map these vocabularies to schema.org ones. It’s possible they will at some stage, so decide which vocabularies to use based on what information you want to mark up, as the data is accessible regardless.

Browser support #

The microdata specification describes the microdata DOM API, which allows us to access top-level items and their properties. Unfortunately, no browser supports this yet. Opera has experimental support in their latest snapshot, with support expected in Opera 12. It’s also being implemented by Mozilla.

But that’s okay because this data is still useful for search engine robots and third party tools. For example, Bing, Google, and Yahoo are using microdata with the schema.org vocabularies in search results.

Tools for making and using microdata #

With the right tools, we could use this data complete with its explicit semantics to, for example, add a microdata-annotated event directly into a calendar — very handy if you were planning to attend. With the release of schema.org, tools for microdata are starting to appear, but are still somewhat thin on the ground. (No Firefox plugin?! Inconceivable!). However we have libraries for three languages now:

• Live Microdata and the associated microdatajs by Philip Jägenstedt
• the PHP Microdata Parser by Alex Holt
• Mida, a Microdata parser/extractor library for Ruby and command line tool by Lawrence Woodman

Live Microdata converts microdata into JSON. If you’re using WHATWG/microformats.org vocabularies for vCard or vEvent, it also produces vCard and iCal output. The PHP Microdata library allows you to parse microdata in an HTML file, returning JSON or a PHP array. Mida allows you to extract microdata as JSON, and search for or inspect items. It supports defining vocabularies, and includes schema.org vocabularies. You can even use it from the command line.

Until there is native API support in browsers, we can use these libraries to access microdata. For example, you could put microdatajs on your own server to provide vCard and iCal file downloads, to allow adding the data to an address book or calendar app.

Validator.nu will validate your use of microdata, but not whether it conforms to a vocabulary. Google’s Rich Snippets testing tool also validates microdata. In addition, if you’re using the schema.org or Rich Snippets vocabularies it should display how that data could be incorporated into search results, as we saw in the Using schema.org vocabularies examples above. At the time of writing it isn’t, possibly due to this tool being updated for schema.org vocabularies.

If you have valid microdata in these vocabularies search engines will understand that data, but currently you have to “register your interest” in having your rich snippets actually be displayed (more information).

If you’d like a simple way to create microdata, with schema.org there are now several web-based form options:

• Schema Creator supports the schema.org vocabularies for Person, Product, Event, Organization, Movie, Book, and Review
• Schemafied supports the schema.org vocabularies for aggregate rating, article, contact point, creative work, event, local business, media object, nutrition information, offer, organization, person, place, postal address, product, rating, recipe, and thing, and also includes relevant items from other schemas
• Microdata Generator supports the schema.org vocabularies for Attorney, Auto Dealer, Dentist, HVAC, Local Business Schema (NAP), Locksmith, Physician, Plumber, Real Estate, and Restaurant
• HTML5 Microdata Templates supports the WHATWG and Rich Snippets vocabularies for events, organisations, people, reviews, and content

For CMSs, there’s a Schema for WordPress plugin, and initial work on adding microdata to Drupal too.

Other vocabularies #

Here's a short list of microdata vocabularies and their itemtypes:

Person

• schema.org Person — http://schema.org/Person
• vCard — http://microformats.org/profile/hcard
• Rich Snippets Person — http://data-vocabulary.org/Person

Organisation or business

• schema.org Organization — http://schema.org/Organization
• vCard (using fn org) — http://microformats.org/profile/hcard
• Rich Snippets Organization — http://data-vocabulary.org/Organization

Calendar

• schema.org Event — http://schema.org/Event
• vEvent — http://microformats.org/profile/hcalendar#vevent
• Rich Snippets Event — http://data-vocabulary.org/Event

Review

• schema.org Review — http://schema.org/Review
• schema.org AggregateRating — http://www.schema.org/AggregateRating (different to Rich Snippets itemtype)
• hReview — http://microformats.org/wiki/hreview
• Rich Snippets Review — http://data-vocabulary.org/Review
• Rich Snippets Review-aggregate — http://www.data-vocabulary.org/Review-aggregate

License

• Licensing works — http://n.whatwg.org/work

Products and services

• schema.org Product — http://schema.org/Product
  • This can be extended with productontology.org descriptions (example)
• hProduct — http://microformats.org/wiki/hproduct
• GoodRelations Product — http://purl.org/goodrelations/ (e.g. <a itemprop="http://purl.org/goodrelations/v1#availableDeliveryMethods" href="hhttp://purl.org/goodrelations/v1#UPS">via UPS</a>)
• Rich Snippets Product — http://data-vocabulary.org/Product

Atom feed

• hAtom — http://microformats.org/wiki/hatom

Recipes

• schema.org Recipe — http://schema.org/Recipe
• hRecipe — http://microformats.org/wiki/hrecipe
• Rich Snippets Recipe — http://data-vocabulary.org/Recipe

It’s also possible to use RDFa vocabularies by both specifying the itemtype and using URLs for itemprop names. Refer to schema.rdfs.org for Linked Data versions of schema.org vocabularies, and the RDF vocabulary clearing-house (“namespace lookup”) http://prefix.cc.

Making your own vocabulary #

If you don’t see a suitable vocabulary, you could make your own. The microdata vocabularies in the HTML5 spec are included as examples of how to do it. Basically:

1. Work out your vocabulary’s rules. This is a little like setting up a database — work out names for each type of data, then think what kind of data each name’s value should/must contain (URL, datetime, free text, text with restrictions…), and whether something needs to be the child of something else.
2. Make up a URL on a domain you control, and ideally put your vocabulary specification there.
3. Use the URL in itemtype="" to reference your vocabulary.

There are, however, very good reasons not to make your own vocabulary. They can be quite hard to create, as evidenced by the work that goes into microformats vocabularies. For truly site-specific data, you’re fine with HTML5 custom data-* attributes, or using microdata the same way. But to really get the quasi-API benefits of microdata, you need to use a vocabulary that’s on more than just your site. To make a vocabulary like that, you need to cover not just your own needs, but 80% of the needs of everyone else in the same subject area.

First, check out microformats.org to see if there’s anything in roughly the same area you can just microdata-ify. After that, try RDFa vocabularies. If you still have no luck, try collaborating on a vocabulary with other people in your subject domain. If you’re going to write your own microdata vocabulary from scratch, I’d recommend trying to write a microformat first, as you’ll get a lot of good feedback and they have good info on how to write one. It’s easy to then convert the resulting microformat vocabulary into a microdata vocabulary.

Further reading and related links #

• Dive into HTML5 — “Distributed,” “Extensibility,” & Other Fancy Words, by Mark Pilgrim
• Microformats vs RDFa vs Microdata by Philip Jägenstedt
• Google Help — Rich Snippets; contains a great introduction to microdata, microformats and RDFa, with code samples in each language
• Knol — Rich Snippets Tips and Tricks has more information on Google’s Rich Snippets

Microformat specifications

There are currently 34 microformats specifications (listed below) in varying levels of completion, and you can find out more about them on the microformats wiki.

These specifications and patterns cover many common types of data. They’ve been created by a grass-roots organisation of interested people, and anyone is welcome to contribute or even propose a new microformat.

Using rel-license for licensing information

Adding license information is quite a common activity, and while we can add a link to Creative Commons or another license easily enough, someone would have to read it to understand the content’s license:

<small>This article is licensed under a 
  <a href="http://creativecommons.org/licenses/by-nc-sa/2.0/">
  Creative Commons Attribution Non-commercial Share-alike 
  (By-<abbr>NC</abbr>-<abbr>SA</abbr>) license</a>.
</small>

If this information was machine-readable, search engines could use it to help consumers searching by license. By using the rel-license microformat to add rel="license" to the license link (indicating it’s the license for the page’s main content), we can do just that:

<small>This article is licensed under a 
  <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/2.0/">
  Creative Commons Attribution Non-commercial Share-alike 
  (By-<abbr>NC</abbr>-<abbr>SA</abbr>) license</a>.
</small>

This may be so easy you don’t even realise you’ve just microformatted the link! In fact, Google already uses this data to allow us to search by license (look in advanced search, in the extra options).

Using XHTML Friends Network (XFN)

Maybe we should term this one eXtensible Friends Network instead :-) XFN is a way of specifying your relationship with people — everything from “met” to “sweetheart” — using the rel attribute on a link to their homepage.

There are two main values: rel="contact" for someone you know how to get in touch with, and rel="me". The rel="me" value allows you to claim ownership of your various websites, including your accounts on social networks. For example, I could have a profile with a link to my Twitter account:

<p>Oli Studholme — <a href="http://twitter.com/boblet">follow me on
  Twitter (@boblet)</a></p>

A person can infer that @boblet is my Twitter username, but by adding rel="me" we can state this relationship in a machine-readable way.

<p>Oli Studholme — <a rel="me" href="http://twitter.com/boblet">follow me on
  Twitter (@boblet)</a></p>

In order to actually work, this would need to be on my personal homepage, with the same homepage added to my Twitter profile. By doing this, a social web app that understands XFN could confirm @boblet is me, check my friends on Twitter, check if those people are already registered, and then allow me to follow them all with one click — much easier.

For more on this idea, check out Identity consolidation and the XFN rel="me" value, the RelMeAuth proposal on the microformats wiki, and Google’s Social Graph API. It seems Facebook is supporting rel="me" too.

Using hCard for contact information

Almost every website has an about page with some contact information:

<p>Oli Studholme — <a href="http://oli.jp/">http://oli.jp</a>, or 
<a href="http://twitter.com/boblet">follow me on Twitter (@boblet)</a>.</p>

Unfortunately, adding someone’s contact information to your phone or address book generally involves a lot of copying and pasting. If the data was machine-readable, however, we could use a tool to do that. Let’s add the hCard microformat to this code snippet.

<p class="vcard"><span class="fn">Oli Studholme</span> — 
<a class="url" href="http://oli.jp/">http://oli.jp</a>, or 
<a class="url" href="http://twitter.com/boblet">follow me on Twitter 
(@<span class="nickname">boblet</span>)</a>.</p>

So we’ve added a bunch of classes. There’s nothing special about that, of course, until you realise they're all part of the hCard microformat. The first one is vcard on the containing <p> element, indicating that there's hCard data here. Then we have fn, which stands for full name, url for an associated homepage, and nickname for, well, a nickname.

This is a simple example, and in fact a valid hCard (generally) only requires vcard and fn. But hCard has much more depth. We can mark up all kinds of contact-related data: addresses, company information, even a profile photo. For example, we can explicitly specify a given name and family name (this is required for Chinese, Korean, Japanese and Vietnamese names), even middle names and titles.

<span class="vcard"><span class="fn n" lang="ja"><span class="family-name">
スタッドホルム</span>・<span class="given-name">オリ</span></span></span>

The additional n value is actually required, but can be inferred (the so-called “implied n optimisation”) and therefore omitted for names that follow these patterns:

• given-name family-name
• family-name, given-name

So what’s the benefit of this? Well, there are several tools that will convert this hCard-microformatted data into a vcard file we can download and automatically add to our address book. Nifty!

It’s also recognised by Google’s Rich Snippets and Yahoo’s SearchMonkey, useful for the contact information on any company website.

Organisations, addresses, and phone numbers

Smaller company websites often have the company name and contact details in the footer, so let’s briefly see how to do that.

<p class="vcard">
<a class="fn org url" href="http://www.w3.org/Consortium/contact-keio" title="Contact Information for W3C/Keio"><span class="organization-name">W3C</span>/<span class="organization-unit">Keio</span></a><br>
<span class="adr"><a class="extended-address" href="http://www.keio.ac.jp/english/about_keio/campus_info/sfc1.html">Keio University Shonan Fujisawa Campus</a><br>
<span class="street-address">5322 Endo</span>, <span class="locality">Fujisawa city</span>,<br>
<span class="region">Kanagawa prefecture</span> <span class="postal-code">252-8520</span> <b class="country">Japan</b><br>
<span class="tel">Telephone: <span class="value">+81-466-49-1170</span></span><br>
<span class="tel"><span class="type">Fax</span>: <span class="value">+81-466-49-1171</span></span></span>
</p>

W3C/Keio
Keio University Shonan Fujisawa Campus
5322 Endo, Fujisawa city,
Kanagawa prefecture 252-8520 Japan
Telephone: +81-466-49-1170
Fax: +81-466-49-1171

By using fn together with org we can create an hCard for an organisation. Each part of the address is specified (<span>licious!), and we’ve also included a phone number (tel’s default type is voice) and fax number (specifying type and using the value class pattern).

And with Operator, we can add this hCard to our computer’s address book in one click. If you’ve ever manually added an address to your address book, you’ll love this ;-)

Using hCalendar for event information

Let’s briefly look at marking up a simple event. Here’s one I’m involved with:

<h3><a href="http://atnd.org/events/5181">WDE-ex Vol.11 —
  Designing for iPad: Our experience so far</a></h3>
<p>July 21st 19:00-20:00 at 
<a href="http://www.apple.com/jp/retail/ginza/map/">Apple Ginza</a>.</p>

Just by reading, we understand the event name, date, time, and location. But this information is difficult for computers to extract. By using the hCard microformat, it will be machine-readable.

<div class="vevent">
  <h3><a class="url summary" href="http://atnd.org/events/5181">
  WDE-ex Vol.11 — Designing for iPad: Our experience so far</a></h3>
  <p><span class="dtstart"><abbr class="value" title="2010-07-21">
  July 21st</abbr> <span class="value">19:00</span></span>-
  <span class="dtend"><span class="value">20:00</span></span> at 
  <a class="location url" href="http://www.apple.com/jp/retail/ginza/map/">
  Apple Ginza</a></p>
</div>

We’ve added vevent on a wrapping element to indicate this is an hCalendar. Events are required to have a summary and a starting time, so we’ve added summary and indicated the starting date and time using dtstart. While historically datetimes were indicated using <abbr title="">, the required ISO 8601 format (for example “2010-07-10T19:01:29”) is very unfriendly to screen readers. Imagine having those numbers read to you! For this reason, the hCalendar specification recommends either breaking the datetime into separate date and time pieces, using the value class pattern, or possibly doing both. The specification is also smart enough to know that if the end datetime dtend is only a time, then it’s on the same day, so we don’t need to specify the date again, although tool support for this is spotty. Finally, we’ve added some URLs, one of which is for the event’s location.

With this data now being machine-readable, we can do things with it. For example, we can add the event to a calendar app with one click.

The rev-based VoteLinks microformat

One of the things that’s been cut in HTML5 is the rev attribute, which was the reverse relationship of rel. On the question of whether microformats should use rev, the microformats wiki states:

The short answer is unfortunately “NO”. Use of “rev” should be avoided. However, VoteLinks’ use of rev has been grandfathered since it was such an early use.

The VoteLinks specification mentioned here allowed us to add vote-for, vote-against, or vote-abstain values to a link via the rev attribute, indicating agreement, disagreement, or indifference (respectively) toward the destination URL. However, as the default state of a link is an implicit vote of agreement, and as the rel-nofollow link microformat is equivalent to vote-abstain, the only one we’re unable to replicate is vote-against (no link? ;-) ). I expect that the microformats community will eventually come up with rel-based equivalent names for VoteLinks, but until then you’ll need to avoid this microformat when using HTML5.

The profile attribute

The profile attribute is obsolete in HTML5, as it was determined unnecessary. Currently, microformat profiles are very rarely used in the wild and are not required, so this probably won’t affect you.

Microformats specifications vs HTML5

While microformats using class and rel work fine, some of the new features in HTML5 aren’t supported yet. The Microformats in HTML5 page on the microformats wiki currently begins:

This page is to document future use of microformats in HTML 5. None of the items documented are supported now, and may change upon proper development within the microformats community, or changes in the HTML 5 specification.

This includes the nifty new <time datetime=""> element, which would be perfect for microformat times, such as dtstart and dtend in the hCalendar microformat. It’s also true for adding microformats via microdata rather than class and rel. There has been talk of a general way to map any microformat into microdata, but this hasn’t eventuated as of yet.

Microformats-consuming tools (or, the problem with HTML Tidy)

The microformats wiki’s warning about <time> brings us to another caveat: tool support. Even if <time datetime=""> was valid in the microformats spec, at present most of the microformats tools can’t get this information from the datetime="" attribute. Now, you could wrap <time datetime=""> around a microformats dtstart or dtend:

<time datetime="2010-07-21T19:00:00+09:00"><span class="dtstart">
  <abbr class="value" title="2010-07-21">July 21st</abbr>
  <span class="value">19:00
</span></span></time>

However, as the <time datetime=""> data is then not explicitly part of the microformat, doing this isn’t really getting you anywhere, except bloated code-ville.

Books and DVDs

• Microformats: Empowering Your Markup for Web 2.0 — John Allsopp
  
  Amazon UK
  |
  Amazon US
  |
  Amazon DE
  |
  Amazon JP
  |
  Amazon JP (日本語版)
• Designing with Microformats for a Beautiful Web (DVD) — Andy Clarke
  
  Amazon UK
  |
  Amazon US
  |
  Amazon DE
  |
  Amazon JP
• Microformats Made Simple — Emily P. Lewis and Tantek Celik
  
  Amazon UK
  |
  Amazon US
  |
  Amazon DE
  |
  Amazon JP