The type Attribute #

While an ordered list’s counter style is generally presentational, in some documents it can be a part of the document’s meaning, as the specification for the type attribute notes:

Examples of this include legal or technical documents, which can contain references to non-decimal list items in prose:

We can specify the list’s style using the type attribute, with the following values:

Further emphasising that this is not a general alternative to list-style-type, only these five list styles are available, whereas CSS 2.1 defines eleven <ol> list styles. If you’re not referring to list counters in your prose, or even if you are but you’re just using the default decimal list counters, then you should use CSS over the type attribute. However, if the list counter type has a semantic meaning, HTML is the place to put it. Note that CSS list-style-type will override HTML type attribute values, so they’ll only work if you haven’t specified a list-style-type in your CSS.

The start and value Attributes #

The start attribute lets us set a list’s first counter. It’s handy for lists that must be split over several <ol> elements, by allowing us to continue the list item numbering from where the previous list left off. The related value attribute is used on an <li> element, and lets us manually number list items. value on the first list item also overrides start. A subsequent <li> element without value will increment the previous value by one.

Here’s an example of how you could use start or value to continue a list, which also demonstrates type:

<!-- Continuing a previous list with value="" -->
<ol type="I">
  <li value="7">seventh item</li>
  <li>eighth item</li>
  <li>ninth item</li>
</ol>
<!-- Continuing a previous list with start="" -->
<ol type="I" start="7">
  <li>seventh item</li>
  <li>eighth item</li>
  <li>ninth item</li>
</ol>

While both of these attributes give us more control, they unfortunately also mean adding or removing list items can make your start or value-based numbering appear broken, so in general you’ll probably want to avoid them and investigate CSS generated content counters instead. You’ll need to use generated content counters if you want to make “1.1.1”-style nested list counters too.

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.

<cite>’s rise to stardom as the semantic super-element #

In HTML 2 <cite> was used to indicate the title of a book or other citation. But in HTML 3.2 and HTML 4.01, <cite> was more loosely defined as

Cite: Contains a citation or a reference to other sources

We can define “citation” as:

• a reference to authority or precedent,
• a quotation that’s being cited, or
• a mention of someone or something

And “a reference to other sources” is even less specific [cue Jaws music]. The HTML 4.01 spec’s examples were:

As <CITE>Harry S. Truman</CITE> said…

More information can be found in <CITE>[ISO-0000]</CITE>

Sadly, an example of an academic-style citation wasn’t included.

Some standardistas enthusiastically adopted <cite> for its semantics, with the high point being Mark Pilgrim’s epic “Posts by citation” (the results of which are now sadly 404’ed). In those heady days, <cite> was used in three main ways:

1. To refer to a person, generally in connection with some reference or as the source of a quote:

   <!-- Not valid usage of cite in HTML5! -->
   <p>As <cite>George R. R. Martin</cite> wrote in…</p>

2. To contain the title of a work being referred to or quoted from (what <cite> is now used for in HTML5 — thanks Dylan!):

   <p><cite>A Game of Thrones</cite>, by George R. R. Martin</p>

3. To contain a full academic-style citation (title plus author, and maybe bibliographic information):

   <!-- Not valid usage of cite in HTML5! -->
   <p><cite>A Game of Thrones, by George R. R. Martin</cite></p>

   • Historically this might also be marked up as:

     <!-- Not valid usage of cite in HTML5! -->
     <p><cite class="book-title">A Game of Thrones</cite>, by <cite class="author">George R. R. Martin</cite></p>

   • or as Wikipedia does (with <cite> set to font-style: normal;):

     <!-- Not valid usage of cite in HTML5! -->
     <p><cite>George R. R. Martin, <i>A Game of Thrones</i></cite></p>

“Wow, what an all-rounder!” I hear you say. “Is there anything <cite> can’t do?” The dirty secret of all this is the <cite> element has historically been semantics for the sake of semantics. So far, the only non-site-specific application of <cite> is browser default stylesheets, which format it with font-style: italic;. This is not a bad thing, as using <cite> consistently on your own site allows you to do all kinds of fun stuff (as Pilgrim demonstrated). But in the past, it’s been used to refer to three related but quite different types of data: titles, full citations, and names. This makes web-wide use, such as by a search engine, tricky.

<cite> snorts too much semantics, checks into rehab #

So, in HTML5 this semantic over-achiever has ended up with a more … prosaic definition:

The cite element represents the title of a work (e.g. a book, a paper, an essay, a poem, a score, a song, a script, a film, a TV show, a game, a sculpture, a painting, a theatre production, a play, an opera, a musical, an exhibition, a legal case report, etc). This can be a work that is being quoted or referenced in detail (i.e. a citation), or it can just be a work that is mentioned in passing.

A person's name is not the title of a work — even if people call that person a piece of work — and the element must therefore not be used to mark up people's names

This restriction has been somewhat … unpopular. Arguments for using <cite> for names (now summarised on the WHATWG wiki) were addressed by Ian Hickson, who decided that historical use wasn’t enough to justify the wooly definition. Jeremy Keith’s 24 Ways article “Incite A Riot” called for civil disobedience and HTML 4.01-style <cite>-ing, but the HTML5 spec has not changed.

The in<cite>rs are irate that there are two use cases that <cite>’s new definition leaves semantically unfilled — to mark up speakers in a transcript or dialog, and to indicate the speaker or author of an inline quote (<q>). The HTML5 spec adds semantic insult to injury by saying:

In some cases, the <b> element might be appropriate for names; e.g. in a gossip article … In other cases, if an element is really needed, the <span> element can be used.

By better defining <cite>, we increase the odds of getting usable data from it, though we now need different methods to cover these other uses. For now, it seems that these use cases aren’t specific enough to warrant new elements.

Note that <cite> was never a general-purpose element for marking up a person. The still-born HTML 3.0 did try to introduce the <person> element, but if you’ve ever used hCard to semantically mark up a person’s name, you’ll know that we’d need way more than just one element to do names justice. The POSH way of marking up a name is to use hCard (in microformats, microdata or RDFa), or just with a plain old link.

Get ex<cite>d and quote stuff #

History and encouraging angry comments aside, let’s suture up and see some examples of HTML5-style <cite> action:

<p><cite>Aladdin</cite> is a great movie, even after 73 viewings. Aren’t kids great?</p>

<p><cite><a href="http://en.wikipedia.org/wiki/Aladdin_(1992_Disney_film)">Aladdin</a></cite> is a great movie, even after 73 viewings. Aren’t kids great?</p>

<p><cite>A Game of Thrones</cite>, by George R. R. Martin</p>

<p><cite>A Game of Thrones</cite>, by <span class="hcard"><span class="fn n"><span class="given-name">George</span> <span class="additional-name">R. R.</span> <span class="family-name">Martin</span></span></span></p>

In this example, the author and book title are only connected by proximity. You could connect them more explicitly using the hProduct microformat, RDFa’s GoodRelations, or to really bleed on the edge even Schema.org.

Note that you can’t use the now-Google-approved rel="author" attribute here, as George R. R. Martin is being referred to and isn’t writing the article. If you just wanted to style the author’s name, you could use <b class="author"> (gossip column style) or <span class="author"> with whatever CSS you like.

HTML5 — A vocabulary and associated APIs for HTML and XHTML by W3C

The HTML5 spec on the W3C site. It’s smaller than the other specs because several parts (including Microdata, Canvas 2D Context, and Web Messaging) have been turned into their own specifications.

I recommend this spec if you don’t follow HTML5 developments — e.g., if you’re not a reader of HTML5 Doctor. This is the specification being prepared for Last Call in May 2011, and it shouldn't change much from here on.

HTML — Living Standard by WHATWG

The HTML spec on the WHATWG site. It’s a superset of the HTML5 spec, including some things that the W3C has split into separate specs (see above). It also includes post-HTML5 features such as Web Video Text Tracks (WebVTT), but it doesn’t include non-HTML-specific specs like Web Storage, Web Sockets API, and Server-sent Events.

I recommend this spec if you are interested in HTML5 (and beyond) and wish to be actively involved. While it’s more liable to change (especially the new bits), it’s also likely to include improvements that haven’t made it into HTML5. It’s also what browser makers are looking at. You can also get to it quickly with the link http://whatwg.org/html.

Web Applications 1.0

This is everything the WHATWG is working on, including non-HTML-specific material (see above). It’s introduced with a photo of a kitchen sink ;)

While this is pretty much the same as HTML — Living Standard, I don’t recommend it because it doesn’t have the ability to hide implementor details. However you’ll need it if you’re interested in Web Storage, Web Sockets API, and Server-sent Events. You can get to it quickly with the link http://whatwg.org/C.

HTML5: The Markup Language Reference

A quick reference for authors describing the syntax, structure, and semantics of HTML5. It's intended to be as concise and readable as possible. From the legend and self-styled W3C HTML5 jackass himself, Mike™ Smith, who also gets bonus points for the initialism “H:TML”.

I recommend this as a quick reference or cheat sheet to remind yourself of the essentials (well, in addition to the HTML5 Doctor glossary, of course ;-). It doesn’t have the depth of guidance or the examples in the other specs (or the implementor details), but it has info links to HTML5 for Web Developers, so you can easily get more detailed information.

HTML5 (Edition for Web Authors)

HTML5 for Web Authors was Mike™ and Ben’s first collaboration. It removes the implementation details intended for browser makers and adds some style, and it’s more in line with W3C’s HTML5 in that it doesn’t include microdata. For the time being, it’s been superseded by HTML5 for Web Developers.

I recommend this for JavaScripters, as it includes more API information than HTML5 for Web Developers. Currently it’s not as up-to-date as HTML5 for Web Developers, but I expect it to receive some love in the future.

HTML5 for Web Developers

HTML5 for Web Developers also removes the implementation details intended for browser makers, but includes some parts like microdata that have been cut from W3C’s HTML5 spec. I’m very impressed with the functionality and design, and I expect it to keep improving.

I recommend this for anyone wanting a beautiful, readable version of HTML5. With local storage, it’s also perfect for adding to an iPad home screen. As it’s on GitHub, it’s also the only spec where you can easily contribute to the design and functionality.

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

CSS we can use

Having said that no browsers support the CSS3 Ruby module yet, there are still a few things we can do to style <ruby> and friends. Default browser styles use font-size and display, so we can safely change these to affect display in both supporting and non-supporting browsers.

If you want to de-emphasise the <rt> ruby text when it’s displayed inline in non-supporting browsers, you could do this via setting the size of <rt> and <rp>, as IE and Webkit do:

rt, rp {font-size: 60%;} /* = Webkit value */

You can also move ruby text and parentheses to after the base text, mimicking non-supporting browser rendering on supporting browsers:

rt, rp {display: inline; font-size: 100%;}

Finally, if you’re brave/foolish, you can implement ruby display yourself via CSS inline-table (CSS with explanation and demonstration (Hiragana.jp)). Note that this currently doesn’t work in Chrome because of a bug with display:inline-table on <ruby> (fixed in trunk), and as you’ll probably need per-browser style tweaks, I recommend against it.

<ruby> in Japanese — furigana and rōmaji

Using <ruby> without <rp>

<ruby>攻殻<rt>こうかく</rt>機動隊<rt>きどうたい</rt></ruby>

Using <ruby> with <rp>

<ruby>攻殻<rp>（</rp><rt>こうかく</rt><rp>）</rp>機動隊<rp>（</rp><rt>きどうたい</rt><rp>）</rp></ruby>

Nested <ruby> for multiple ruby texts

<ruby><ruby>攻<rp>（</rp><rt>こう</rt><rp>）</rp>殻<rp>（</rp><rt>かく</rt><rp>）</rp>機<rp>（</rp><rt>き</rt><rp>）</rp>動<rp>（</rp><rt>どう</rt><rp>）</rp>隊<rp>（</rp><rt>たい</rt><rp>）</rp></ruby><rp>（</rp><rt>Kōkakukidōtai</rt><rp>）</rp></ruby>

<ruby> in Chinese — Pīnyīn and zhùyīn fúhào (bopomofo)

Ruby is used to some extent in China (pīnyīn), and more so in Taiwan (zhùyīn fúhào), especially in textbooks and signage.

Pīnyīn

<p>The <b>Grass mud horse</b> — <ruby>草泥馬<rp>(</rp><rt>Cǎo Ní Mǎ</rt><rp>)</rp></ruby> — is … characterised as “lively, intelligent and tenacious”. However, their existence is said to be threatened by the “river crabs” — <ruby class="styled">河蟹<rp> (</rp><rt>héxiè</rt><rp>) </rp></ruby> — which are invading their habitat.</p>

Zhùyīn fúhào

<ruby><ruby>世<rp>（</rp><rt>ㄕˋ</rt><rp>）</rp>上<rp>（</rp><rt>ㄕㄤˋ</rt><rp>）</rp>無<rp>（</rp><rt>ㄨˊ</rt><rp>）</rp>難<rp>（</rp><rt>ㄋㄢˊ</rt><rp>）</rp>事<rp>（</rp><rt>ㄕˋ</rt><rp>）</rp>只<rp>（</rp><rt>ㄓˇ</rt><rp>）</rp>怕<rp>（</rp><rt>ㄆㄚˋ</rt><rp>）</rp>有<rp>（</rp><rt>ㄧㄡˇ</rt><rp>）</rp>心<rp>（</rp><rt>ㄒㄧㄣ</rt><rp>）</rp>人<rp>（</rp><rt>ㄖㄣˊ</rt><rp>）</rp></ruby><rp> （</rp><rt>Anything can be done with enough perseverance</rt><rp>）</rp></ruby>

Korean ruby

While the use of hanja (kanji) is decreasing in South Korea, they are still used for disambiguation and proper names.

<ruby>한자<rp>(</rp><rt>漢字</rt><rp>)</rp></ruby>

Using <ruby> for English

Not everyone is using East Asian languages, but any short annotation is (theoretically) applicable. While English doesn’t typically have pronunciation guidance, phonetic annotations are used in dictionaries:

<ruby><strong>cromulent</strong> <rp>(</rp><rt>crôm-yü-lənt</rt><rp>)</rp></ruby>