HTML5 (including next generation additions still in development)

Draft Standard — 6 February 2010

5 Microdata

5.1 Introduction

5.1.1 Overview

This section is non-normative.

Sometimes, it is desirable to annotate content with specific machine-readable labels, e.g. to allow generic scripts to provide services that are customised to the page, or to enable content from a variety of cooperating authors to be processed by a single script in a consistent manner.

For this purpose, authors can use the microdata features described in this section. Microdata allows nested groups of name-value pairs to be added to documents, in parallel with the existing content.

5.1.2 The basic syntax

This section is non-normative.

At a high level, microdata consists of a group of name-value pairs. The groups are called items, and each name-value pair is a property. Items and properties are represented by regular elements.

To create an item, the itemscope attribute is used.

To add a property to an item, the itemprop attribute is used on one of the item's descendants.

Here there are two items, each of which has the property "name":

<div itemscope>
 <p>My name is <span itemprop="name">Elizabeth</span>.</p>
</div>

<div itemscope>
 <p>My name is <span itemprop="name">Daniel</span>.</p>
</div>

Properties generally have values that are strings.

Here the item has three properties:

<div itemscope>
 <p>My name is <span itemprop="name">Neil</span>.</p>
 <p>My band is called <span itemprop="band">Four Parts Water</span>.</p>
 <p>I am <span itemprop="nationality">British</span>.</p>
</div>

Properties can also have values that are URLs. This is achieved using the a element and its href attribute, the img element and its src attribute, or other elements that link to or embed external resources.

In this example, the item has one property, "image", whose value is a URL:

<div itemscope>
 <img itemprop="image" src="google-logo.png" alt="Google">
</div>

Properties can also have values that are dates, times, or dates and times. This is achieved using the time element and its datetime attribute.

In this example, the item has one property, "birthday", whose value is a date:

<div itemscope>
 I was born on <time itemprop="birthday" datetime="2009-05-10">May 10th 2009</time>.
</div>

Properties can also themselves be groups of name-value pairs, by putting the itemscope attribute on the element that declares the property.

Items that are not part of others are called top-level microdata items.

In this example, the outer item represents a person, and the inner one represents a band:

<div itemscope>
 <p>Name: <span itemprop="name">Amanda</span></p>
 <p>Band: <span itemprop="band" itemscope> <span itemprop="name">Jazz Band</span> (<span itemprop="size">12</span> players)</span></p>
</div>

The outer item here has two properties, "name" and "band". The "name" is "Amanda", and the "band" is an item in its own right, with two properties, "name" and "size". The "name" of the band is "Jazz Band", and the "size" is "12".

The outer item in this example is a top-level microdata item.

Properties that are not descendants of the element with the itemscope attribute can be associated with the item using the itemref attribute. This attribute takes a list of IDs of elements to crawl in addition to crawling the children of the element with the itemscope attribute.

This example is the same as the previous one, but all the properties are separated from their items:

<div itemscope id="amanda" itemref="a b"></div>
<p id="a">Name: <span itemprop="name">Amanda</span></p>
<div id="b" itemprop="band" itemscope itemref="c"></div>
<div id="c">
 <p>Band: <span itemprop="name">Jazz Band</span></p>
 <p>Size: <span itemprop="size">12</span> players</p>
</div>

This gives the same result as the previous example. The first item has two properties, "name", set to "Amanda", and "band", set to another item. That second item has two further properties, "name", set to "Jazz Band", and "size", set to "12".

An item can have multiple properties with the same name and different values.

This example describes an ice cream, with two flavors:

<div itemscope>
 <p>Flavors in my favorite ice cream:</p>
 <ul>
  <li itemprop="flavor">Lemon sorbet</li>
  <li itemprop="flavor">Apricot sorbet</li>
 </ul>
</div>

This thus results in an item with two properties, both "flavor", having the values "Lemon sorbet" and "Apricot sorbet".

An element introducing a property can also introduce multiple properties at once, to avoid duplication when some of the properties have the same value.

Here we see an item with two properties, "favorite-color" and "favorite-fruit", both set to the value "orange":

<div itemscope>
 <span itemprop="favorite-color favorite-fruit">orange</span>
</div>

It's important to note that there is no relationship between the microdata and the content of the document where the microdata is marked up.

There is no semantic difference, for instance, between the following two examples:

<figure>
 <img src="castle.jpeg">
 <figcaption><span itemscope><span itemprop="name">The Castle</span></span> (1986)</figcaption>
</figure>

<span itemscope><meta itemprop="name" content="The Castle"></span>
<figure>
 <img src="castle.jpeg">
 <figcaption>The Castle (1986)</figcaption>
</figure>

Both have a figure with a caption, and both, completely unrelated to the figure, have an item with a name-value pair with the name "name" and the value "The Castle". The only difference is that if the user drags the caption out of the document, in the former case, the item will be included in the drag-and-drop data. In neither case is the image in any way associated with the item.

5.1.3 Typed items

This section is non-normative.

The examples in the previous section show how information could be marked up on a page that doesn't expect its microdata to be re-used. Microdata is most useful, though, when it is used in contexts where other authors and readers are able to cooperate to make new uses of the markup.

For this purpose, it is necessary to give each item a type, such as "http://example.com/person", or "http://example.org/cat", or "http://band.example.net/". Types are identified as URLs.

The type for an item is given as the value of an itemtype attribute on the same element as the itemscope attribute.

Here, the item is "http://example.org/animals#cat":

<section itemscope itemtype="http://example.org/animals#cat">
 <h1 itemprop="name">Hedral</h1>
 <p itemprop="desc">Hedral is a male american domestic
 shorthair, with a fluffy black fur with white paws and belly.</p>
 <img itemprop="img" src="hedral.jpeg" alt="" title="Hedral, age 18 months">
</section>

In this example the "http://example.org/animals#cat" item has three properties, a "name" ("Hedral"), a "desc" ("Hedral is..."), and an "img" ("hedral.jpeg").

An item can only have one type. The type gives the context for the properties, thus defining a vocabulary: a property named "class" given for an item with the type "http://census.example/person" might refer to the economic class of an individual, while a property named "class" given for an item with the type "http://example.com/school/teacher" might refer to the classroom a teacher has been assigned.

5.1.4 Global identifiers for items

This section is non-normative.

Sometimes, an item gives information about a topic that has a global identifier. For example, books can be identified by their ISBN number.

Vocabularies (as identified by the itemtype attribute) can be designed such that items get associated with their global identifier in an unambiguous way by expressing the global identifiers as URLs given in an itemid attribute.

The exact meaning of the URLs given in itemid attributes depends on the vocabulary used.

Here, an item is talking about a particular book:

<dl itemscope
    itemtype="http://vocab.example.net/book"
    itemid="urn:isbn:0-330-34032-8">
 <dt>Title
 <dd itemprop="title">The Reality Dysfunction
 <dt>Author
 <dd itemprop="author">Peter F. Hamilton
 <dt>Publication date
 <dd><time itemprop="pubdate" datetime="1996-01-26">26 January 1996</time>
</dl>

The "http://vocab.example.net/book" vocabulary in this example would define that the itemid attribute takes a urn: URL pointing to the ISBN of the book.

5.1.5 Selecting names when defining vocabularies

This section is non-normative.

Using microdata means using a vocabulary. For some purposes, an ad-hoc vocabulary is adequate. For others, a vocabulary will need to be designed. Where possible, authors are encouraged to re-use existing vocabularies, as this makes content re-use easier.

When designing new vocabularies, identifiers can be created either using URLs, or, for properties, as plain words (with no dots or colons). For URLs, conflicts with other vocabularies can be avoided by only using identifiers that correspond to pages that the author has control over.

For instance, if Jon and Adam both write content at example.com, at http://example.com/~jon/... and http://example.com/~adam/... respectively, then they could select identifiers of the form "http://example.com/~jon/name" and "http://example.com/~adam/name" respectively.

Properties whose names are just plain words can only be used within the context of the types for which they are intended; properties named using URLs can be reused in items of any type. If an item has no type, and is not part of another item, then if its properties have names that are just plain words, they are not intended to be globally unique, and are instead only intended for limited use. Generally speaking, authors are encouraged to use either properties with globally unique names (URLs) or ensure that their items are typed.

Here, an item is an "http://example.org/animals#cat", and most of the properties have names that are words defined in the context of that type. There are also a few additional properties whose names come from other vocabularies.

<section itemscope itemtype="http://example.org/animals#cat">
 <h1 itemprop="name http://example.com/fn">Hedral</h1>
 <p itemprop="desc">Hedral is a male american domestic
 shorthair, with a fluffy <span
 itemprop="http://example.com/color">black</span> fur with <span
 itemprop="http://example.com/color">white</span> paws and belly.</p>
 <img itemprop="img" src="hedral.jpeg" alt="" title="Hedral, age 18 months">
</section>

This example has one item with the type "http://example.org/animals#cat" and the following properties:

Property	Value
name	Hedral
http://example.com/fn	Hedral
desc	Hedral is a male american domestic shorthair, with a fluffy black fur with white paws and belly.
http://example.com/color	black
http://example.com/color	white
img	.../hedral.jpeg

5.1.6 Using the microdata DOM API

This section is non-normative.

The microdata becomes even more useful when scripts can use it to expose information to the user, for example offering it in a form that can be used by other applications.

The document.getItems(typeNames) method provides access to the top-level microdata items. It returns a NodeList containing the items with the specified types, or all types if no argument is specified.

Each item is represented in the DOM by the element on which the relevant itemscope attribute is found. These elements have their element.itemScope IDL attribute set to true.

The type of items can be obtained using the element.itemType IDL attribute on the element with the itemscope attribute.

This sample shows how the getItems() method can be used to obtain a list of all the top-level microdata items of one type given in the document:

var cats = document.getItems("http://example.com/feline");

Once an element representing an item has been obtained, its properties can be extracted using the properties IDL attribute. This attribute returns an HTMLPropertiesCollection, which can be enumerated to go through each element that adds one or more properties to the item. It can also be indexed by name, which will return an object with a list of the elements that add properties with that name.

Each element that adds a property also has a itemValue IDL attribute that returns its value.

This sample gets the first item of type "http://example.net/user" and then pops up an alert using the "name" property from that item.

var user = document.getItems('http://example.net/user')[0];
alert('Hello ' + user.properties['name'][0].content + '!');

The HTMLPropertiesCollection object, when indexed by name in this way, actually returns a PropertyNodeList object with all the matching properties. The PropertyNodeList object can be used to obtain all the values at once using its values attribute, which returns an array of all the values.

In an earlier example, a "http://example.org/animals#cat" item had two "http://example.com/color" values. This script looks up the first such item and then lists all its values.

var cat = document.getItems('http://example.org/animals#cat')[0];
var colors = cat.properties['http://example.com/color'].values;
var result;
if (colors.length == 0) {
  result = 'Color unknown.';
} else if (colors.length == 1) {
  result = 'Color: ' + colors[0];
} else {
  result = 'Colors:';
  for (var i = 0; i < colors.length; i += 1)
    result += ' ' + colors[i];
}

It's also possible to get a list of all the property names using the object's names IDL attribute.

This example creates a big list with a nested list for each item on the page, each with of all the property names used in that item.

var outer = document.createElement('ul');
var items = document.getItems();
for (var item = 0; item < items.length; item += 1) {
  var itemLi = document.createElement('li');
  var inner = document.createElement('ul');
  for (var name = 0; name < items[item].properties.names.length; name += 1) {
    var propLi = document.createElement('li');
    propLi.appendChild(document.createTextNode(items[item].properties.names[name]));
    inner.appendChild(propLi);
  }
  itemLi.appendChild(inner);
  outer.appendChild(itemLi);
}
document.body.appendChild(outer);

If faced with the following from an earlier example:

<section itemscope itemtype="http://example.org/animals#cat">
 <h1 itemprop="name http://example.com/fn">Hedral</h1>
 <p itemprop="desc">Hedral is a male american domestic
 shorthair, with a fluffy <span
 itemprop="http://example.com/color">black</span> fur with <span
 itemprop="http://example.com/color">white</span> paws and belly.</p>
 <img itemprop="img" src="hedral.jpeg" alt="" title="Hedral, age 18 months">
</section>

...it would result in the following output:

- name
- http://example.com/fn
- desc
- http://example.com/color
- img

(The duplicate occurrence of "http://example.com/color" is not included in the list.)

5.2 Encoding microdata

5.2.1 The microdata model

The microdata model consists of groups of name-value pairs known as items.

Each group is known as an item. Each item can have an item type, a global identifier (if the item type supports global identifiers for its items), and a list of name-value pairs. Each name in the name-value pair is known as a property, and each property has one or more values. Each value is either a string or itself a group of name-value pairs (an item).

An item is said to be a typed item when either it has an item type, or it is the value of a property of a typed item. The relevant type for a typed item is the item's item type, if it has one, or else is the relevant type of the item for which it is a property's value.

5.2.2 Items

Every HTML element may have an itemscope attribute specified. The itemscope attribute is a boolean attribute.

An element with the itemscope attribute specified creates a new item, a group of name-value pairs.

Elements with an itemscope attribute may have an itemtype attribute specified, to give the item type of the item.

The itemtype attribute, if specified, must have a value that is a valid URL that is an absolute URL for which the string "http://www.w3.org/1999/xhtml/microdata#" is not a prefix match.

The item type of an item is the value of its element's itemtype attribute, if it has one and its value is not the empty string. If the itemtype attribute is missing or its value is the empty string, the item is said to have no item type.

The item type must be a type defined in an applicable specification.

Except if otherwise specified by that specification, the URL given as the item type should not be automatically dereferenced.

A specification could define that its item type can be derefenced to provide the user with help information, for example. In fact, vocabulary authors are encouraged to provide useful information at the given URL.

Item types are opaque identifiers, and user agents must not dereference unknown item types, or otherwise deconstruct them, in order to determine how to process items that use them.

The itemtype attribute must not be specified on elements that do not have an itemscope attribute specified.

Elements with an itemscope attribute and an itemtype attribute that references a vocabulary that is defined to support global identifiers for items may also have an itemid attribute specified, to give a global identifier for the item, so that it can be related to other items on pages elsewhere on the Web.

The itemid attribute, if specified, must have a value that is a valid URL.

The global identifier of an item is the value of its element's itemid attribute, if it has one, resolved relative to the element on which the attribute is specified. If the itemid attribute is missing or if resolving it fails, it is said to have no global identifier.

The itemid attribute must not be specified on elements that do not have both an itemscope attribute and an itemtype attribute specified, and must not be specified on elements with an itemscope attribute whose itemtype attribute specifies a vocabulary that does not support global identifiers for items, as defined by that vocabulary's specification.

Elements with an itemscope attribute may have an itemref attribute specified, to give a list of additional elements to crawl to find the name-value pairs of the item.

The itemref attribute, if specified, must have a value that is an unordered set of unique space-separated tokens consisting of IDs of elements in the same home subtree.

The itemref attribute must not be specified on elements that do not have an itemscope attribute specified.

5.2.3 Names: the `itemprop` attribute

Every HTML element may have an itemprop attribute specified, if doing so adds a property to one or more items (as defined below).

The itemprop attribute, if specified, must have a value that is an unordered set of unique space-separated tokens representing the names of the name-value pairs that it adds. The attribute's value must have at least one token.

Each token must be either:

A valid URL that is an absolute URL for which the string "http://www.w3.org/1999/xhtml/microdata#" is not a prefix match, or
If the item is a typed item: a defined property name allowed in this situation according to the specification that defines the relevant type for the item, or
If the item is not a typed item: a string that contains no U+002E FULL STOP characters (.) and no U+003A COLON characters (:).

When an element with an itemprop attribute adds a property to multiple items, the requirement above regarding the tokens applies for each item individually.

The property names of an element are the tokens that the element's itemprop attribute is found to contain when its value is split on spaces, with the order preserved but with duplicates removed (leaving only the first occurrence of each name).

Within an item, the properties are unordered with respect to each other, except for properties with the same name, which are ordered in the order they are given by the algorithm that defines the properties of an item.

In the following example, the "a" property has the values "1" and "2", in that order, but whether the "a" property comes before the "b" property or not is not important:

<div itemscope>
 <p itemprop="a">1</p>
 <p itemprop="a">2</p>
 <p itemprop="b">test</p>
</div>

Thus, the following is equivalent:

<div itemscope>
 <p itemprop="b">test</p>
 <p itemprop="a">1</p>
 <p itemprop="a">2</p>
</div>

As is the following:

<div itemscope>
 <p itemprop="a">1</p>
 <p itemprop="b">test</p>
 <p itemprop="a">2</p>
</div>

And the following:

<div itemscope itemref="x">
 <p itemprop="b">test</p>
 <p itemprop="a">2</p>
</div>
<div id="x">
 <p itemprop="a">1</p>
</div>

5.2.4 Values

The property value of a name-value pair added by an element with an itemprop attribute depends on the element, as follows:

If the element also has an itemscope attribute: The value is the item created by the element.
If the element is a meta element: The value is the value of the element's content attribute, if any, or the empty string if there is no such attribute.
If the element is an audio, embed, iframe, img, source, or video element: The value is the absolute URL that results from resolving the value of the element's src attribute relative to the element at the time the attribute is set, or the empty string if there is no such attribute or if resolving it results in an error.
If the element is an a, area, or link element: The value is the absolute URL that results from resolving the value of the element's href attribute relative to the element at the time the attribute is set, or the empty string if there is no such attribute or if resolving it results in an error.
If the element is an object element: The value is the absolute URL that results from resolving the value of the element's data attribute relative to the element at the time the attribute is set, or the empty string if there is no such attribute or if resolving it results in an error.
If the element is a time element with a datetime attribute: The value is the value of the element's datetime attribute.
Otherwise: The value is the element's textContent.

The URL property elements are the a, area, audio, embed, iframe, img, link, object, source, and video elements.

If a property's value is an absolute URL, the property must be specified using a URL property element.

If a property's value represents a date, time, or global date and time, the property must be specified using the datetime attribute of a time element.

5.2.5 Associating names with items

To find the properties of an item defined by the element root, the user agent must try to crawl the properties of the element root, with an empty list as the value of memory: if this fails, then the properties of the item defined by the element root is an empty list; otherwise, it is the returned list.

To crawl the properties of an element root with a list memory, the user agent must run the following steps:

If root is in memory, then the algorithm fails; abort these steps.
Collect all the elements in the item root, and let results be the result.
If root is in results, then the algorithm fails; abort these steps.
If any elements are listed in results more than once, then the algorithm fails; abort these steps.
Remove any elements from results that do not have an itemprop attribute specified.
Let new memory be a new list consisting of the old list memory with the addition of root.
For each element in results that has an itemscope attribute specified, crawl the properties of the element, with new memory as the memory. If this fails, then this instance of the algorithm fails as well; abort these steps. (If it succeeds, the return value is discarded.)
Sort results in tree order.
Return results.

To collect all the elements in the item root, the user agent must run these steps:

Let results and pending be empty lists of elements.
Add all the children elements of root to pending.
If root has an itemref attribute, split the value of that itemref attribute on spaces. For each resulting token ID, if there is an element in the home subtree of root with the ID ID, then add the first such element to pending.
Loop: Remove an element from pending and let current be that element.
Add current to results.
If current does not have an itemscope attribute, then: add all the child elements of current to pending.
End of loop: If pending is not empty, return to the step marked loop.
Return results.

An item is a top-level microdata item if its element does not have an itemprop attribute.

An item is a used microdata item if it is a top-level microdata item, or if it has an itemprop attribute and would be found to be the property of an item that is itself a used microdata item.

A document must not contain any items that are not used microdata items.

A document must not contain any elements that have an itemprop attribute that would not be found to be a property of any of the items in that document were their properties all to be determined.

A document must not contain any items for which crawling the properties of the element, with an empty list as the value of memory, fails.

The algorithms in this section are especially inefficient, in the interests of keeping them easy to understand. Implementors are strongly encouraged to refactor and optimise them in their user agents.

In this example, a single license statement is applied to two works, using itemref from the items representing the works:

<!DOCTYPE HTML>
<html>
 <head>
  <title>Photo gallery</title>
 </head>
 <body>
  <h1>My photos</h1>
  <figure itemscope itemtype="http://n.whatwg.org/work" itemref="licenses">
   <img itemprop="work" src="images/house.jpeg" alt="A white house, boarded up, sits in a forest.">
   <figcaption itemprop="title">The house I found.</figcaption>
  </figure>
  <figure itemscope itemtype="http://n.whatwg.org/work" itemref="licenses">
   <img itemprop="work" src="images/mailbox.jpeg" alt="Outside the house is a mailbox. It has a leaflet inside.">
   <figcaption itemprop="title">The mailbox.</figcaption>
  </figure>
  <footer>
   <p id="licenses">All images licensed under the <a itemprop="license"
   href="http://www.opensource.org/licenses/mit-license.php">MIT
   license</a>.</p>
  </footer>
 </body>
</html>

The above results in two items with the type "http://n.whatwg.org/work", one with:

work: images/house.jpeg
title: The house I found.
license: http://www.opensource.org/licenses/mit-license.php

...and one with:

work: images/mailbox.jpeg
title: The mailbox.
license: http://www.opensource.org/licenses/mit-license.php

In the following invalid example, the items are all empty, because the itemref attribute on the inner nested item indirectly references the same element twice in the same item:

<!-- invalid example - do not copy -->
<div itemscope>
 <span itemprop="example">This is <em>not</em> a property of the
 <code>div</code> element.</span>
 <p itemprop="demo" itemscope itemref="test thing"> <!-- "thing" is a descendant
                   of "test", which leads to it being included twice, which is invalid -->
  <span itemprop="sample">This isn't part of anything either.</span>
 </p>
</div>
<p id="test">
 <span id="thing">(this element is referenced twice by the
 <code>p</code> above, causing all the items that involve that
 <code>itemref=""</code> attribute to act as if they had no
 properties.)</span>
</p>

5.3 Microdata DOM API

document . getItems( [ types ] )

Returns a NodeList of the elements in the Document that create items, that are not part of other items, and that are of one of the types given in the argument, if any are listed.

The types argument is interpreted as a space-separated list of types.

element . properties

If the element has an itemscope attribute, returns an HTMLPropertiesCollection object with all the element's properties. Otherwise, an empty HTMLPropertiesCollection object.

element . itemValue [ = value ]

Returns the element's value.

Can be set, to change the element's value. Setting the value when the element has no itemprop attribute or when the element's value is an item throws an INVALID_ACCESS_ERR exception.

The document.getItems(typeNames) method takes an optional string that contains an unordered set of unique space-separated tokens representing types. When called, the method must return a live NodeList object containing all the elements in the document, in tree order, that are each top-level microdata items with a type equal to one of the types specified in that argument, having obtained the types by splitting the string on spaces. If there are no tokens specified in the argument, or if the argument is missing, then the method must return a NodeList containing all the top-level microdata items in the document.

The itemScope IDL attribute on HTML elements must reflect the itemscope content attribute. The itemType IDL attribute on HTML elements must reflect the itemtype content attribute, as if it was a regular string attribute, not a URL string attribute. The itemId IDL attribute on HTML elements must reflect the itemid content attribute. The itemProp IDL attribute on HTML elements must reflect the itemprop content attribute. The itemRef IDL attribute on HTML elements must reflect the itemref content attribute.

The properties IDL attribute on HTML elements must return an HTMLPropertiesCollection rooted at the Document node, whose filter matches only elements that have property names and are the properties of the item created by the element on which the attribute was invoked, while that element is an item, and matches nothing the rest of the time.

The itemValue IDL attribute's behavior depends on the element, as follows:

If the element has no itemprop attribute: The attribute must return null on getting and must throw an INVALID_ACCESS_ERR exception on setting.
If the element has an itemscope attribute: The attribute must return the element itself on getting and must throw an INVALID_ACCESS_ERR exception on setting.
If the element is a meta element: The attribute must act as it would if it was reflecting the element's content content attribute.
If the element is an audio, embed, iframe, img, source, or video element: The attribute must act as it would if it was reflecting the element's src content attribute.
If the element is an a, area, or link element: The attribute must act as it would if it was reflecting the element's href content attribute.
If the element is an object element: The attribute must act as it would if it was reflecting the element's data content attribute.
If the element is a time element with a datetime attribute: The attribute must act as it would if it was reflecting the element's datetime content attribute.
Otherwise: The attribute must act the same as the element's textContent attribute.

When the itemValue IDL attribute is reflecting a content attribute or acting like the element's textContent attribute, the user agent must, on setting, convert the new value to the IDL DOMString value before using it according to the mappings described above.

In this example, a script checks to see if a particular element element is declaring a particular property, and if it is, it increments a counter:

if (element.itemProp.contains('color'))
  count += 1;

This script iterates over each of the values of an element's itemref attribute, calling a function for each referenced element:

for (var index = 0; index < element.itemRef.length; index += 1)
  process(document.getElementById(element.itemRef[index]));

5.4 Microdata vocabularies

5.4.1 vCard

An item with the item type http://microformats.org/profile/hcard represents a person's or organization's contact information.

This vocabulary supports global identifiers for items.

The following are the type's defined property names. They are based on the vocabulary defined in the vCard specification and its extensions, where more information on how to interpret the values can be found. [RFC2426] [RFC4770]

fn

Gives the formatted text corresponding to the name of the person or organization.

The value must be text.

Exactly one property with the name fn must be present within each item with the type http://microformats.org/profile/hcard.

n

Gives the structured name of the person or organization.

The value must be an item with zero or more of each of the family-name, given-name, additional-name, honorific-prefix, and honorific-suffix properties.

Except when one of the conditions given below applies, exactly one property with the name n must be present within each item with the type http://microformats.org/profile/hcard.

If one of the following conditions does apply, then the n may be omitted:

The item with the type vcard has both an fn property and an org property, and they both have values that are strings and those strings are identical when compared in a case-sensitive manner.

The contact information must be for an organization.

The item with the type vcard has an fn property whose value consists of a string with zero space characters.

The value of the fn property must be a nickname.

The item with the type vcard has an fn property whose value consists of a string with exactly one sequence of space characters, which occurs neither at the immediate start nor the immediate end of the string.

The value of the fn property must be a name in one of the following forms:

Last, First
Last F.
Last F
First Last

family-name (inside n)

Gives the family name of the person, or the full name of the organization.

The value must be text.

Any number of properties with the name family-name may be present within the item that forms the value of the n property of an item with the type http://microformats.org/profile/hcard.

given-name (inside n)

Gives the given-name of the person.

The value must be text.

Any number of properties with the name given-name may be present within the item that forms the value of the n property of an item with the type http://microformats.org/profile/hcard.

additional-name (inside n)

Gives the any additional names of the person.

The value must be text.

Any number of properties with the name additional-name may be present within the item that forms the value of the n property of an item with the type http://microformats.org/profile/hcard.

honorific-prefix (inside n)

Gives the honorific prefix of the person.

The value must be text.

Any number of properties with the name honorific-prefix may be present within the item that forms the value of the n property of an item with the type http://microformats.org/profile/hcard.

honorific-suffix (inside n)

Gives the honorific suffix of the person.

The value must be text.

Any number of properties with the name honorific-suffix may be present within the item that forms the value of the n property of an item with the type http://microformats.org/profile/hcard.

nickname

Gives the nickname of the person or organization.

The nickname is the descriptive name given instead of or in addition to the one belonging to a person, place, or thing. It can also be used to specify a familiar form of a proper name specified by the fn or n properties.

The value must be text.

Any number of properties with the name nickname may be present within each item with the type http://microformats.org/profile/hcard.

photo

Gives a photograph of the person or organization.

The value must be an absolute URL.

Any number of properties with the name photo may be present within each item with the type http://microformats.org/profile/hcard.

bday

Gives the birth date of the person or organization.

The value must be a valid date string.

A single property with the name bday may be present within each item with the type http://microformats.org/profile/hcard.

adr

Gives the delivery address of the person or organization.

The value must be an item with zero or more type, post-office-box, extended-address, and street-address properties, and optionally a locality property, optionally a region property, optionally a postal-code property, and optionally a country-name property.

If no type properties are present within an item that forms the value of an adr property of an item with the type http://microformats.org/profile/hcard, then the address type strings intl, postal, parcel, and work are implied.

Any number of properties with the name adr may be present within each item with the type http://microformats.org/profile/hcard.

type (inside adr)

Gives the type of delivery address.

The value must be text that, when compared in a case-sensitive manner, is equal to one of the address type strings.

Within each item with the type http://microformats.org/profile/hcard, there must be no more than one adr property item with a type property whose value is pref.

Any number of properties with the name type may be present within the item that forms the value of an adr property of an item with the type http://microformats.org/profile/hcard, but within each such adr property item there must only be one type property per distinct value.

post-office-box (inside adr)

Gives the post office box component of the delivery address of the person or organization.

The value must be text.

Any number of properties with the name post-office-box may be present within the item that forms the value of an adr property of an item with the type http://microformats.org/profile/hcard.

extended-address (inside adr)

Gives an additional component of the delivery address of the person or organization.

The value must be text.

Any number of properties with the name extended-address may be present within the item that forms the value of an adr property of an item with the type http://microformats.org/profile/hcard.

street-address (inside adr)

Gives the street address component of the delivery address of the person or organization.

The value must be text.

Any number of properties with the name street-address may be present within the item that forms the value of an adr property of an item with the type http://microformats.org/profile/hcard.

locality (inside adr)

Gives the locality component (e.g. city) of the delivery address of the person or organization.

The value must be text.

A single property with the name locality may be present within the item that forms the value of an adr property of an item with the type http://microformats.org/profile/hcard.

region (inside adr)

Gives the region component (e.g. state or province) of the delivery address of the person or organization.

The value must be text.

A single property with the name region may be present within the item that forms the value of an adr property of an item with the type http://microformats.org/profile/hcard.

postal-code (inside adr)

Gives the postal code component of the delivery address of the person or organization.

The value must be text.

A single property with the name postal-code may be present within the item that forms the value of an adr property of an item with the type http://microformats.org/profile/hcard.

country-name (inside adr)

Gives the country name component of the delivery address of the person or organization.

The value must be text.

A single property with the name country-name may be present within the item that forms the value of an adr property of an item with the type http://microformats.org/profile/hcard.

label

Gives the formatted text corresponding to the delivery address of the person or organization.

The value must be either text or an item with zero or more type properties and exactly one value property.

If no type properties are present within an item that forms the value of a label property of an item with the type http://microformats.org/profile/hcard, or if the value of such a label property is text, then the address type strings intl, postal, parcel, and work are implied.

Any number of properties with the name label may be present within each item with the type http://microformats.org/profile/hcard.

type (inside label)

Gives the type of delivery address.

The value must be text that, when compared in a case-sensitive manner, is equal to one of the address type strings.

Within each item with the type http://microformats.org/profile/hcard, there must be no more than one label property item with a type property whose value is pref.

Any number of properties with the name type may be present within the item that forms the value of a label property of an item with the type http://microformats.org/profile/hcard, but within each such label property item there must only be one type property per distinct value.

value (inside label)

Gives the actual formatted text corresponding to the delivery address of the person or organization.

The value must be text.

Exactly one property with the name value must be present within the item that forms the value of a label property of an item with the type http://microformats.org/profile/hcard.

tel

Gives the telephone number of the person or organization.

The value must be either text that can be interpreted as a telephone number as defined in the CCITT specifications E.163 and X.121, or an item with zero or more type properties and exactly one value property. [E163] [X121]

If no type properties are present within an item that forms the value of a tel property of an item with the type http://microformats.org/profile/hcard, or if the value of such a tel property is text, then the telephone type string voice is implied.

Any number of properties with the name tel may be present within each item with the type http://microformats.org/profile/hcard.

type (inside tel)

Gives the type of telephone number.

The value must be text that, when compared in a case-sensitive manner, is equal to one of the telephone type strings.

Within each item with the type http://microformats.org/profile/hcard, there must be no more than one tel property item with a type property whose value is pref.

Any number of properties with the name type may be present within the item that forms the value of a tel property of an item with the type http://microformats.org/profile/hcard, but within each such tel property item there must only be one type property per distinct value.

value (inside tel)

Gives the actual telephone number of the person or organization.

The value must be text that can be interpreted as a telephone number as defined in the CCITT specifications E.163 and X.121. [E163] [X121]

Exactly one property with the name value must be present within the item that forms the value of a tel property of an item with the type http://microformats.org/profile/hcard.

email

Gives the e-mail address of the person or organization.

The value must be either text or an item with zero or more type properties and exactly one value property.

If no type properties are present within an item that forms the value of an email property of an item with the type http://microformats.org/profile/hcard, or if the value of such an email property is text, then the e-mail type string internet is implied.

Any number of properties with the name email may be present within each item with the type http://microformats.org/profile/hcard.

type (inside email)

Gives the type of e-mail address.

The value must be text that, when compared in a case-sensitive manner, is equal to one of the e-mail type strings.

Within each item with the type http://microformats.org/profile/hcard, there must be no more than one email property item with a type property whose value is pref.

Any number of properties with the name type may be present within the item that forms the value of an email property of an item with the type http://microformats.org/profile/hcard, but within each such email property item there must only be one type property per distinct value.

value (inside email)

Gives the actual e-mail address of the person or organization.

The value must be text.

Exactly one property with the name value must be present within the item that forms the value of an email property of an item with the type http://microformats.org/profile/hcard.

mailer

Gives the name of the e-mail software used by the person or organization.

The value must be text.

Any number of properties with the name mailer may be present within each item with the type http://microformats.org/profile/hcard.

tz

Gives the time zone of the person or organization.

The value must be text and must match the following syntax:

Either a U+002B PLUS SIGN character (+) or a U+002D HYPHEN-MINUS character (-).
A valid non-negative integer that is exactly two digits long and that represents a number in the range 00..23.
A U+003A COLON character (:).
A valid non-negative integer that is exactly two digits long and that represents a number in the range 00..59.

Any number of properties with the name tz may be present within each item with the type http://microformats.org/profile/hcard.

geo

Gives the geographical position of the person or organization.

The value must be text and must match the following syntax:

Optionally, either a U+002B PLUS SIGN character (+) or a U+002D HYPHEN-MINUS character (-).
One or more digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).
Optionally*, a U+002E FULL STOP character (.) followed by one or more digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).
A U+003B SEMICOLON character (;).
Optionally, either a U+002B PLUS SIGN character (+) or a U+002D HYPHEN-MINUS character (-).
One or more digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).
Optionally*, a U+002E FULL STOP character (.) followed by one or more digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).

The optional components marked with an asterisk (*) should be included, and should have six digits each.

The value specifies latitude and longitude, in that order (i.e., "LAT LON" ordering), in decimal degrees. The longitude represents the location east and west of the prime meridian as a positive or negative real number, respectively. The latitude represents the location north and south of the equator as a positive or negative real number, respectively.

Any number of properties with the name geo may be present within each item with the type http://microformats.org/profile/hcard.

title

Gives the job title, functional position or function of the person or organization.

The value must be text.

Any number of properties with the name title may be present within each item with the type http://microformats.org/profile/hcard.

role

Gives the role, occupation, or business category of the person or organization.

The value must be text.

Any number of properties with the name role may be present within each item with the type http://microformats.org/profile/hcard.

logo

Gives the logo of the person or organization.

The value must be an absolute URL.

Any number of properties with the name logo may be present within each item with the type http://microformats.org/profile/hcard.

agent

Gives the contact information of another person who will act on behalf of the person or organization.

The value must be either an item with the type http://microformats.org/profile/hcard, or an absolute URL, or text.

Any number of properties with the name logo may be present within each item with the type http://microformats.org/profile/hcard.

org

Gives the name and units of the organization.

The value must be either text or an item with one organization-name property and zero or more organization-unit properties.

Any number of properties with the name org may be present within each item with the type http://microformats.org/profile/hcard.

organization-name (inside org)

Gives the name of the organization.

The value must be text.

Exactly one property with the name organization-name must be present within the item that forms the value of an org property of an item with the type http://microformats.org/profile/hcard.

organization-unit (inside org)

Gives the name of the organization unit.

The value must be text.

Any number of properties with the name organization-unit may be present within the item that forms the value of the org property of an item with the type http://microformats.org/profile/hcard.

categories

Gives the name of a category or tag that the person or organization could be classified as.

The value must be text.

Any number of properties with the name categories may be present within each item with the type http://microformats.org/profile/hcard.

note

Gives supplemental information or a comment about the person or organization.

The value must be text.

Any number of properties with the name note may be present within each item with the type http://microformats.org/profile/hcard.

rev

Gives the revision date and time of the contact information.

The value must be text that is a valid global date and time string.

The value distinguishes the current revision of the information for other renditions of the information.

Any number of properties with the name rev may be present within each item with the type http://microformats.org/profile/hcard.

sort-string

Gives the string to be used for sorting the person or organization.

The value must be text.

Any number of properties with the name sort-string may be present within each item with the type http://microformats.org/profile/hcard.

sound

Gives a sound file relating to the person or organization.

The value must be an absolute URL.

Any number of properties with the name sound may be present within each item with the type http://microformats.org/profile/hcard.

url

Gives a URL relating to the person or organization.

The value must be an absolute URL.

Any number of properties with the name url may be present within each item with the type http://microformats.org/profile/hcard.

class

Gives the access classification of the information regarding the person or organization.

The value must be text with one of the following values:

public
private
confidential

This is merely advisory and cannot be considered a confidentiality measure.

Any number of properties with the name class may be present within each item with the type http://microformats.org/profile/hcard.

impp

Gives a URL for instant messaging and presence protocol communications with the person or organization.

The value must be either an absolute URL or an item with zero or more type properties and exactly one value property.

If no type properties are present within an item that forms the value of an impp property of an item with the type http://microformats.org/profile/hcard, or if the value of such an impp property is an absolute URL, then no IMPP type strings are implied.

Any number of properties with the name impp may be present within each item with the type http://microformats.org/profile/hcard.

type (inside impp)

Gives the intended use of the IMPP URL.

The value must be text that, when compared in a case-sensitive manner, is equal to one of the IMPP type strings.

Within each item with the type http://microformats.org/profile/hcard, there must be no more than one impp property item with a type property whose value is pref.

Any number of properties with the name type may be present within the item that forms the value of an impp property of an item with the type http://microformats.org/profile/hcard, but within each such impp property item there must only be one type property per distinct value.

value (inside impp)

Gives the actual URL for instant messaging and presence protocol communications with the person or organization.

The value must be an absolute URL.

Exactly one property with the name value must be present within the item that forms the value of an impp property of an item with the type http://microformats.org/profile/hcard.

The address type strings are:

dom: Indicates a domestic delivery address.
intl: Indicates an international delivery address.
postal: Indicates a postal delivery address.
parcel: Indicates a parcel delivery address.
home: Indicates a residential delivery address.
work: Indicates a delivery address for a place of work.
pref: Indicates the preferred delivery address when multiple addresses are specified.

The telephone type strings are:

home: Indicates a residential number.
msg: Indicates a telephone number with voice messaging support.
work: Indicates a telephone number for a place of work.
voice: Indicates a voice telephone number.
fax: Indicates a facsimile telephone number.
cell: Indicates a cellular telephone number.
video: Indicates a video conferencing telephone number.
pager: Indicates a paging device telephone number.
bbs: Indicates a bulletin board system telephone number.
modem: Indicates a MODEM-connected telephone number.
car: Indicates a car-phone telephone number.
isdn: Indicates an ISDN service telephone number.
pcs: Indicates a personal communication services telephone number.
pref: Indicates the preferred telephone number when multiple telephone numbers are specified.

The e-mail type strings are:

internet: Indicates an Internet e-mail address.
x400: Indicates a X.400 addressing type.
pref: Indicates the preferred e-mail address when multiple e-mail addresses are specified.

The IMPP type strings are:

personal
business: Indicates the type of communication for which this IMPP URL is appropriate.
home
work
mobile: Indicates the location of a device associated with this IMPP URL.
pref: Indicates the preferred address when multiple IMPP URLs are specified.

5.4.1.1 Conversion to vCard

Given a list of nodes nodes in a Document, a user agent must run the following algorithm to extract any vCard data represented by those nodes (only the first vCard is returned):

If none of the nodes in nodes are items with the item type http://microformats.org/profile/hcard, then there is no vCard. Abort the algorithm, returning nothing.
Let node be the first node in nodes that is an item with the item type http://microformats.org/profile/hcard.
Let output be an empty string.
Add a vCard line with the type "BEGIN" and the value "VCARD" to output.
Add a vCard line with the type "PROFILE" and the value "VCARD" to output.
Add a vCard line with the type "VERSION" and the value "3.0" to output.
Add a vCard line with the type "SOURCE" and the result of escaping the vCard text string that is the document's current address as the value to output.
If the title element is not null, add a vCard line with the type "NAME" and with the result of escaping the vCard text string obtained from the textContent of the title element as the value to output.
If node has a global identifier, add a vCard line with the type "UID" and with the result of escaping the vCard text string of that global identifier as the value to output.
Let first-n, first-org, and first-fn be null.
For each element element that is a property of the item node: for each name name in element's property names, run the following substeps:
1. Let parameters be an empty set of name-value pairs.
2. Run the appropriate set of substeps from the following list. The steps will set a variable value, which is used in the next step.
  If the property's value is an item subitem and name is n
  1. If first-n is null, let first-n be element.
  2. Let value be the empty string.
  3. Append to value the result of collecting the first vCard subproperty named family-name in subitem.
  4. Append a U+003B SEMICOLON character (;) to value.
  5. Append to value the result of collecting the first vCard subproperty named given-name in subitem.
  6. Append a U+003B SEMICOLON character (;) to value.
  7. Append to value the result of collecting the first vCard subproperty named additional-name in subitem.
  8. Append a U+003B SEMICOLON character (;) to value.
  9. Append to value the result of collecting the first vCard subproperty named honorific-prefix in subitem.
  10. Append a U+003B SEMICOLON character (;) to value.
  11. Append to value the result of collecting the first vCard subproperty named honorific-suffix in subitem.
  If the property's value is an item subitem and name is adr
  1. Let value be the empty string.
  2. Append to value the result of collecting vCard subproperties named post-office-box in subitem.
  3. Append a U+003B SEMICOLON character (;) to value.
  4. Append to value the result of collecting vCard subproperties named extended-address in subitem.
  5. Append a U+003B SEMICOLON character (;) to value.
  6. Append to value the result of collecting vCard subproperties named street-address in subitem.
  7. Append a U+003B SEMICOLON character (;) to value.
  8. Append to value the result of collecting the first vCard subproperty named locality in subitem.
  9. Append a U+003B SEMICOLON character (;) to value.
  10. Append to value the result of collecting the first vCard subproperty named region in subitem.
  11. Append a U+003B SEMICOLON character (;) to value.
  12. Append to value the result of collecting the first vCard subproperty named postal-code in subitem.
  13. Append a U+003B SEMICOLON character (;) to value.
  14. Append to value the result of collecting the first vCard subproperty named country-name in subitem.
  15. If there is a property named type in subitem, and the first such property has a value that is not an item and whose value consists only of alphanumeric ASCII characters, then add a parameter named "TYPE" whose value is the value of that property to parameters.
  If the property's value is an item subitem and name is org
  1. If first-org is null, let first-org be element.
  2. Let value be the empty string.
  3. Append to value the result of collecting the first vCard subproperty named organization-name in subitem.
  4. For each property named organization-unit in subitem, run the following steps:
    
    If the value of the property is an item, then skip this property.
    
    Append a U+003B SEMICOLON character (;) to value.
    
    Append the result of escaping the vCard text string given by the value of the property to value.
  If the property's value is an item subitem with the item type http://microformats.org/profile/hcard and name is agent
  1. Let value be the result of escaping the vCard text string obtained from extracting a vCard from the element that represents subitem.
  2. Add a parameter named "VALUE" whose value is "VCARD" to parameters.
  If the property's value is an item and name is none of the above
  1. Let value be the result of collecting the first vCard subproperty named value in subitem.
  2. If there is a property named type in subitem, and the first such property has a value that is not an item and whose value consists only of alphanumeric ASCII characters, then add a parameter named "TYPE" whose value is the value of that property to parameters.
  Otherwise (the property's value is not an item)
  1. If name is fn and first-fn is null, let first-fn be element.
    
    Otherwise, if name is org and first-org is null, let first-org be element.
  2. Let value be the property's value.
  3. If element is one of the URL property elements, add a parameter with the name "VALUE" and the value "URI" to parameters.
  4. Otherwise, if element is a time element and the value is a valid date string, add a parameter with the name "VALUE" and the value "DATE" to parameters.
  5. Otherwise, if element is a time element and the value is a valid global date and time string, add a parameter with the name "VALUE" and the value "DATE-TIME" to parameters.
  6. Prefix every U+005C REVERSE SOLIDUS character (\) in value with another U+005C REVERSE SOLIDUS character (\).
  7. Prefix every U+002C COMMA character (,) in value with a U+005C REVERSE SOLIDUS character (\).
  8. Unless name is geo, prefix every U+003B SEMICOLON character (;) in value with a U+005C REVERSE SOLIDUS character (\).
  9. Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
  10. Replace every remaining U+000D CARRIAGE RETURN (CR) or U+000A LINE FEED (LF) character in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
3. Add a vCard line with the type name, the parameters parameters, and the value value to output.
If first-n is null, then run the following substeps:
1. If first-fn is also null, then skip the remainder of these substeps.
2. If first-fn has a value that is an item, then skip the remainder of these substeps.
3. If first-org is not null, and the value of first-org is not an item and is equal to first-fn, then add a vCard line with the type "N" whose value is four U+003B SEMICOLON characters (";;;;") to output. Then, skip the remainder of these substeps.
4. If the space characters in first-fn, if any, are not all contiguous, then skip the remainder of these substeps.
5. Split first-fn on spaces, and let part one be the first resulting token, and part two be the second, if any, or the empty string if there is no second token. (There cannot be three, given the previous step.)
6. If the last character of part one is a U+002C COMMA character (,), then remove that character from part one and add a vCard line with the type "N" whose value is the concatenation of the following strings:
  1. The result of escaping the vCard text string part one
  2. A U+003B SEMICOLON character (;)
  3. The result of escaping the vCard text string part two
  4. Three U+003B SEMICOLON characters (;)
  Then, skip the remainder of these substeps.
7. If part two is two Unicode code-points long and its second character is a U+002E FULL STOP character (.), then add a vCard line with the type "N" whose value is the concatenation of the following strings:
  1. The result of escaping the vCard text string part one
  2. A U+003B SEMICOLON character (;)
  3. The result of escaping the vCard text string consisting of the first character of part two
  4. Three U+003B SEMICOLON characters (;)
  Then, skip the remainder of these substeps.
8. If part two is one Unicode code-point long, then add a vCard line with the type "N" whose value is the concatenation of the following strings:
  1. The result of escaping the vCard text string part one
  2. A U+003B SEMICOLON character (;)
  3. The result of escaping the vCard text string part two
  4. Three U+003B SEMICOLON characters (;)
  Then, skip the remainder of these substeps.
9. Add a vCard line with the type "N" whose value is the concatenation of the following strings:
  1. The result of escaping the vCard text string part two
  2. A U+003B SEMICOLON character (;)
  3. The result of escaping the vCard text string part one
  4. Three U+003B SEMICOLON characters (;)
Add a vCard line with the type "END" and the value "VCARD" to output.

When the above algorithm says that the user agent is to add a vCard line consisting of a type type, optionally some parameters, and a value value to a string output, it must run the following steps:

Let line be an empty string.
Append type, converted to ASCII uppercase, to line.
If there are any parameters, then for each parameter, in the order that they were added, run these substeps:
1. Append a U+003B SEMICOLON character (;) to line.
2. Append the parameter's name to line.
3. Append a U+003D EQUALS SIGN character (=) to line.
4. Append the parameter's value to line.
Append a U+003A COLON character (:) to line.
Append value to line.
Let maximum length be 75.
If and while line is longer than maximum length Unicode code points long, run the following substeps:
1. Append the first maximum length Unicode code points of line to output.
2. Remove the first maximum length Unicode code points from line.
3. Append a U+000D CARRIAGE RETURN character (CR) to output.
4. Append a U+000A LINE FEED character (LF) to output.
5. Append a U+0020 SPACE character to output.
6. Let maximum length be 74.
Append (what remains of) line to output.
Append a U+000D CARRIAGE RETURN character (CR) to output.
Append a U+000A LINE FEED character (LF) to output.

When the steps above require the user agent to obtain the result of collecting vCard subproperties named subname in subitem, the user agent must run the following steps:

Let value be the empty string.
For each property named subname in the item subitem, run the following substeps:
1. If the value of the property is itself an item, then skip this property.
2. If this is not the first property named subname in subitem (ignoring any that were skipped by the previous step), then append a U+002C COMMA character (,) to value.
3. Append the result of escaping the vCard text string given by the value of the property to value.
Return value.

When the steps above require the user agent to obtain the result of collecting the first vCard subproperty named subname in subitem, the user agent must run the following steps:

If there are no properties named subname in subitem, then abort these substeps, returning the empty string.
If the value of the first property named subname in subitem is an item, then abort these substeps, returning the empty string.
Return the result of escaping the vCard text string given by the value of the first property named subname in subitem.

When the above algorithms say the user agent is to escape the vCard text string value, the user agent must use the following steps:

Prefix every U+005C REVERSE SOLIDUS character (\) in value with another U+005C REVERSE SOLIDUS character (\).
Prefix every U+002C COMMA character (,) in value with a U+005C REVERSE SOLIDUS character (\).
Prefix every U+003B SEMICOLON character (;) in value with a U+005C REVERSE SOLIDUS character (\).
Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Replace every remaining U+000D CARRIAGE RETURN (CR) or U+000A LINE FEED (LF) character in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Return the mutated value.

This algorithm can generate invalid vCard output, if the input does not conform to the rules described for the http://microformats.org/profile/hcard item type and defined property names.

5.4.1.2 Examples

This section is non-normative.

Here is a long example vCard for a fictional character called "Jack Bauer":

<section id="jack" itemscope itemtype="http://microformats.org/profile/hcard">
 <h1 itemprop="fn">Jack Bauer</h1>
 <img itemprop="photo" alt="" src="jack-bauer.jpg">
 <p itemprop="org" itemscope>
  <span itemprop="organization-name">Counter-Terrorist Unit</span>
  (<span itemprop="organization-unit">Los Angeles Division</span>)
 </p>
 <p>
  <span itemprop="adr" itemscope>
   <span itemprop="street-address">10201 W. Pico Blvd.</span><br>
   <span itemprop="locality">Los Angeles</span>,
   <span itemprop="region">CA</span>
   <span itemprop="postal-code">90064</span><br>
   <span itemprop="country-name">United States</span><br>
  </span>
  <span itemprop="geo">34.052339;-118.410623</span>
 </p>
 <h2>Assorted Contact Methods</h2>
 <ul>
  <li itemprop="tel" itemscope>
   <span itemprop="value">+1 (310) 597 3781</span> <span itemprop="type">work</span>
   <meta itemprop="type" content="pref">
  </li>
  <li><a itemprop="url" href="http://en.wikipedia.org/wiki/Jack_Bauer">I'm on Wikipedia</a>
  so you can leave a message on my user talk page.</li>
  <li><a itemprop="url" href="http://www.jackbauerfacts.com/">Jack Bauer Facts</a></li>
  <li itemprop="email"><a href="mailto:j.bauer@la.ctu.gov.invalid">j.bauer@la.ctu.gov.invalid</a></li>
  <li itemprop="tel" itemscope>
   <span itemprop="value">+1 (310) 555 3781</span> <span>
   <meta itemprop="type" content="cell">mobile phone</span>
  </li>
 </ul>
 <p itemprop="note">If I'm out in the field, you may be better off contacting <span
 itemprop="agent" itemscope itemtype="http://microformats.org/profile/hcard"><a
 itemprop="email" href="mailto:c.obrian@la.ctu.gov.invalid"><span
 itemprop="fn">Chloe O'Brian</span></a></span> if it's about work, or ask <span
 itemprop="agent">Tony Almeida</span> if you're interested in the CTU five-a-side football team we're trying to get going.</p>
 <ins datetime="2008-07-20T21:00:00+01:00">
  <span itemprop="rev" itemscope>
   <meta itemprop="type" content="date-time">
   <meta itemprop="value" content="2008-07-20T21:00:00+01:00">
  </span>
  <p itemprop="tel" itemscope><strong>Update!</strong>
  My new <span itemprop="type">home</span> phone number is
  <span itemprop="value">01632 960 123</span>.</p>
 </ins>
</section>

The odd line wrapping is needed because newlines are meaningful in microdata: newlines would be preserved in a conversion to, for example, the vCard format.

This example shows a site's contact details (using the address element) containing an address with two street components:

<address itemscope itemtype="http://microformats.org/profile/hcard">
 <strong itemprop="fn">Alfred Person</strong> <br>
 <span itemprop="adr" itemscope>
  <span itemprop="street-address">1600 Amphitheatre Parkway</span> <br>
  <span itemprop="street-address">Building 43, Second Floor</span> <br>
  <span itemprop="locality">Mountain View</span>,
   <span itemprop="region">CA</span> <span itemprop="postal-code">94043</span>
 </span>
</address>

The vCard vocabulary can be used to just mark up people's names:

<span itemscope itemtype="http://microformats.org/profile/hcard"
><span itemprop=fn>George Washington</span></span>

This creates a single item with a single name-value pair, with the name "fn" and the value "George Washington". This is defined to map to the following vCard:

BEGIN:VCARD
PROFILE:VCARD
VERSION:3.0
SOURCE:document's address
FN:George Washington
N:Washington;George;;;
END:VCARD

5.4.2 vEvent

An item with the item type http://microformats.org/profile/hcalendar#vevent represents an event.

This vocabulary supports global identifiers for items.

The following are the type's defined property names. They are based on the vocabulary defined in the iCalendar specification, where more information on how to interpret the values can be found. [RFC2445]

Only the parts of the iCalendar vocabulary relating to events are used here; this vocabulary cannot express a complete iCalendar instance.

attach

Gives the address of an associated document for the event.

The value must be an absolute URL.

Any number of properties with the name attach may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

categories

Gives the name of a category or tag that the event could be classified as.

The value must be text.

Any number of properties with the name categories may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

class

Gives the access classification of the information regarding the event.

The value must be text with one of the following values:

public
private
confidential

This is merely advisory and cannot be considered a confidentiality measure.

A single property with the name class may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

comment

Gives a comment regarding the event.

The value must be text.

Any number of properties with the name comment may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

description

Gives a detailed description of the event.

The value must be text.

A single property with the name description may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

geo

Gives the geographical position of the event.

The value must be text and must match the following syntax:

Optionally, either a U+002B PLUS SIGN character (+) or a U+002D HYPHEN-MINUS character (-).
One or more digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).
Optionally*, a U+002E FULL STOP character (.) followed by one or more digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).
A U+003B SEMICOLON character (;).
Optionally, either a U+002B PLUS SIGN character (+) or a U+002D HYPHEN-MINUS character (-).
One or more digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).
Optionally*, a U+002E FULL STOP character (.) followed by one or more digits in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9).

The optional components marked with an asterisk (*) should be included, and should have six digits each.

A single property with the name geo may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

location

Gives the location of the event.

The value must be text.

A single property with the name location may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

resources

Gives a resource that will be needed for the event.

The value must be text.

Any number of properties with the name resources may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

status

Gives the confirmation status of the event.

The value must be text with one of the following values:

tentative
confirmed
cancelled

A single property with the name status may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

summary

Gives a short summary of the event.

The value must be text.

User agents should replace U+000A LINE FEED (LF) characters in the value by U+0020 SPACE characters when using the value.

A single property with the name summary may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

dtend

Gives the date and time by which the event ends.

If the property with the name dtend is present within an item with the type http://microformats.org/profile/hcalendar#vevent that has a property with the name dtstart whose value is a valid date string, then the value of the property with the name dtend must be text that is a valid date string also. Otherwise, the value of the property must be text that is a valid global date and time string.

In either case, the value be later in time than the value of the dtstart property of the same item.

The time given by the dtend property is not inclusive. For day-long events, therefore, the dtend property's value will be the day after the end of the event.

A single property with the name dtend may be present within each item with the type http://microformats.org/profile/hcalendar#vevent, so long as that http://microformats.org/profile/hcalendar#vevent does not have a property with the name duration.

dtstart

Gives the date and time at which the event starts.

The value must be text that is either a valid date string or a valid global date and time string.

Exactly one property with the name dtstart must be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

duration

Gives the date and time at which the event starts.

The value must be text that is a valid vevent duration string.

The duration represented is the sum of all the durations represented by integers in the value.

A single property with the name duration may be present within each item with the type http://microformats.org/profile/hcalendar#vevent, so long as that http://microformats.org/profile/hcalendar#vevent does not have a property with the name dtend.

transp

Gives whether the event is to be considered as consuming time on a calendar, for the purpose of free-busy time searches.

The value must be text with one of the following values:

opaque
transparent

A single property with the name transp may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

contact

Gives the contact information for the event.

The value must be text.

Any number of properties with the name contact may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

url

Gives a URL for the event.

The value must be an absolute URL.

A single property with the name url may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

exdate

Gives a date and time at which the event does not occur despite the recurrence rules.

The value must be text that is either a valid date string or a valid global date and time string.

Any number of properties with the name exdate may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

exrule

Gives a rule for finding dates and times at which the event does not occur despite the recurrence rules.

The value must be text that matches the RECUR value type defined in the iCalendar specification. [RFC2445]

Any number of properties with the name exrule may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

rdate

Gives a date and time at which the event recurs.

The value must be text that is one of the following:

A valid date string.
A valid global date and time string.
A valid global date and time string followed by a U+002F SOLIDUS character (/) followed by a second valid global date and time string representing a later time.
A valid global date and time string followed by a U+002F SOLIDUS character (/) followed by a valid vevent duration string.

Any number of properties with the name rdate may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

rrule

Gives a rule for finding dates and times at which the event occurs.

The value must be text that matches the RECUR value type defined in the iCalendar specification. [RFC2445]

Any number of properties with the name rrule may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

created

Gives the date and time at which the event information was first created in a calendaring system.

The value must be text that is a valid global date and time string.

A single property with the name created may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

last-modified

Gives the date and time at which the event information was last modified in a calendaring system.

The value must be text that is a valid global date and time string.

A single property with the name last-modified may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

sequence

Gives a revision number for the event information.

The value must be text that is a valid non-negative integer.

A single property with the name sequence may be present within each item with the type http://microformats.org/profile/hcalendar#vevent.

A string is a valid vevent duration string if it matches the following pattern:

A U+0050 LATIN CAPITAL LETTER P character (P).
One of the following:
- A valid non-negative integer followed by a U+0057 LATIN CAPITAL LETTER W character (W). The integer represents a duration of that number of weeks.
- At least one, and possible both in this order, of the following:
  1. A valid non-negative integer followed by a U+0044 LATIN CAPITAL LETTER D character (D). The integer represents a duration of that number of days.
  2. A U+0054 LATIN CAPITAL LETTER T character (T) followed by any one of the following, or the first and second of the following in that order, or the second and third of the following in that order, or all three of the following in this order:
    1. A valid non-negative integer followed by a U+0048 LATIN CAPITAL LETTER H character (H). The integer represents a duration of that number of hours.
    2. A valid non-negative integer followed by a U+004D LATIN CAPITAL LETTER M character (M). The integer represents a duration of that number of minutes.
    3. A valid non-negative integer followed by a U+0053 LATIN CAPITAL LETTER S character (S). The integer represents a duration of that number of seconds.

5.4.2.1 Conversion to iCalendar

Given a list of nodes nodes in a Document, a user agent must run the following algorithm to extract any vEvent data represented by those nodes:

If none of the nodes in nodes are items with the type http://microformats.org/profile/hcalendar#vevent, then there is no vEvent data. Abort the algorithm, returning nothing.
Let output be an empty string.
Add an iCalendar line with the type "BEGIN" and the value "VCALENDAR" to output.
Add an iCalendar line with the type "PRODID" and the value equal to a user-agent-specific string representing the user agent to output.
Add an iCalendar line with the type "VERSION" and the value "2.0" to output.
For each node node in nodes that is an item with the type http://microformats.org/profile/hcalendar#vevent, run the following steps:
1. Add an iCalendar line with the type "BEGIN" and the value "VEVENT" to output.
2. Add an iCalendar line with the type "DTSTAMP" and a value consisting of an iCalendar DATE-TIME string representing the current date and time, with the annotation "VALUE=DATE-TIME", to output. [RFC2445]
3. If the item has a global identifier, add an iCalendar line with the type "UID" and that global identifier as the value to output.
4. For each element element that is a property of the item node: for each name name in element's property names, run the appropriate set of substeps from the following list:
  
  If the property's value is an item
  
  Skip the property.
  
  If element is a time element
  
  Let value be the result of stripping all U+002D HYPHEN-MINUS (-) and U+003A COLON (:) characters from the property's value.
  
  If the property's value is a valid date string then add an iCalendar line with the type name and the value value to output, with the annotation "VALUE=DATE".
  
  Otherwise, if the property's value is a valid global date and time string then add an iCalendar line with the type name and the value value to output, with the annotation "VALUE=DATE-TIME".
  
  Otherwise skip the property.
  
  Otherwise
  
  Add an iCalendar line with the type name and the property's value to output.
5. Add an iCalendar line with the type "END" and the value "VEVENT" to output.
Add an iCalendar line with the type "END" and the value "VCALENDAR" to output.

When the above algorithm says that the user agent is to add an iCalendar line consisting of a type type, a value value, and optionally an annotation, to a string output, it must run the following steps:

Let line be an empty string.
Append type, converted to ASCII uppercase, to line.
If there is an annotation:
1. Append a U+003B SEMICOLON character (;) to line.
2. Append the annotation to line.
Append a U+003A COLON character (:) to line.
Prefix every U+005C REVERSE SOLIDUS character (\) in value with another U+005C REVERSE SOLIDUS character (\).
Prefix every U+002C COMMA character (,) in value with a U+005C REVERSE SOLIDUS character (\).
Prefix every U+003B SEMICOLON character (;) in value with a U+005C REVERSE SOLIDUS character (\).
Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Replace every remaining U+000D CARRIAGE RETURN (CR) or U+000A LINE FEED (LF) character in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Append value to line.
Let maximum length be 75.
If and while line is longer than maximum length Unicode code points long, run the following substeps:
1. Append the first maximum length Unicode code points of line to output.
2. Remove the first maximum length Unicode code points from line.
3. Append a U+000D CARRIAGE RETURN character (CR) to output.
4. Append a U+000A LINE FEED character (LF) to output.
5. Append a U+0020 SPACE character to output.
6. Let maximum length be 74.
Append (what remains of) line to output.
Append a U+000D CARRIAGE RETURN character (CR) to output.
Append a U+000A LINE FEED character (LF) to output.

This algorithm can generate invalid iCalendar output, if the input does not conform to the rules described for the http://microformats.org/profile/hcalendar#vevent item type and defined property names.

5.4.2.2 Examples

This section is non-normative.

Here is an example of a page that uses the vEvent vocabulary to mark up an event:

<body itemscope itemtype="http://microformats.org/profile/hcalendar#vevent">
 ...
 <h1 itemprop="summary">Bluesday Tuesday: Money Road</h1>
 ...
 <time itemprop="dtstart" datetime="2009-05-05T19:00:00Z">May 5th @ 7pm</time>
 (until <time itemprop="dtend" datetime="2009-05-05T21:00:00Z">9pm</time>)
 ...
 <a href="http://livebrum.co.uk/2009/05/05/bluesday-tuesday-money-road"
    rel="bookmark" itemprop="url">Link to this page</a>
 ...
 <p>Location: <span itemprop="location">The RoadHouse</span></p>
 ...
 <p><input type=button value="Add to Calendar"
           onclick="location = getCalendar(this)"></p>
 ...
 <meta itemprop="description" content="via livebrum.co.uk">
</body>

The "getCalendar()" method could look like this:

function getCalendar(node) {
  // This function assumes the content is valid.
  // It is not a compliant implementation of the algorithm for extracting vEvent data.
  while (node && (!node.itemScope || !node.itemType == 'http://microformats.org/profile/hcalendar#vevent'))
    node = node.parentNode;
  if (!node) {
    alert('No event data found.');
    return;
  }
  var stamp = new Date();
  var stampString = '' + stamp.getUTCFullYear() + (stamp.getUTCMonth() + 1) + stamp.getUTCDate() + 'T' +
                         stamp.getUTCHours() + stamp.getUTCMinutes() + stamp.getUTCSeconds() + 'Z';
  var calendar = 'BEGIN:VCALENDAR\r\nPRODID:HTML\r\nVERSION:2.0\r\nBEGIN:VEVENT\r\nDTSTAMP:' + stampString + '\r\n';
  if (node.itemId)
    calendar += 'UID:' + node.itemId + '\r\n';
  for (var propIndex = 0; propIndex < node.properties.length; propIndex += 1) {
    var prop = node.properties[propIndex];
    var value = prop.itemValue;
    var parameters = '';
    if (prop.localName == 'time') {
      value = value.replace(/[:-]/g, '');
      if (value.match(/T/))
        parameters = ';VALUE=DATE';
      else
        parameters = ';VALUE=DATE-TIME';
    } else {
      value = value.replace(/\\/g, '\\n');
      value = value.replace(/;/g, '\\;');
      value = value.replace(/,/g, '\\,');
      value = value.replace(/\n/g, '\\n');
    }
    for (var nameIndex = 0; nameIndex < prop.itemProp.length; nameIndex += 1) {
      var name = prop.itemProp[nameIndex];
      if (!name.match(/:/) && !name.match(/\./))
        calendar += name.toUpperCase() + parameters + ':' + value + '\r\n';
    }
  }
  calendar += 'END:VEVENT\r\nEND:VCALENDAR\r\n';
  return 'data:text/calendar;component=vevent,' + encodeURI(calendar);
}

The same page could offer some markup, such as the following, for copy-and-pasting into blogs:

<div itemscope itemtype="http://microformats.org/profile/hcalendar#vevent">
 <p>I'm going to
 <strong itemprop="summary">Bluesday Tuesday: Money Road</strong>,
 <time itemprop="dtstart" datetime="2009-05-05T19:00:00Z">May 5th at 7pm</time>
 to <time itemprop="dtend" content="2009-05-05T21:00:00Z">9pm</time>,
 at <span itemprop="location">The RoadHouse</span>!</p>
 <p><a href="http://livebrum.co.uk/2009/05/05/bluesday-tuesday-money-road"
       itemprop="url">See this event on livebrum.co.uk</a>.</p>
 <meta itemprop="description" content="via livebrum.co.uk">
</div>

5.4.3 Licensing works

An item with the item type http://n.whatwg.org/work represents a work (e.g. an article, an image, a video, a song, etc). This type is primarily intended to allow authors to include licensing information for works.

The following are the type's defined property names.

work

Identifies the work being described.

The value must be an absolute URL.

Exactly one property with the name work must be present within each item with the type http://n.whatwg.org/work.

title

Gives the name of the work.

A single property with the name title may be present within each item with the type http://n.whatwg.org/work.

author

Gives the name or contact information of one of the authors or creators of the work.

The value must be either an item with the type http://microformats.org/profile/hcard, or text.

Any number of properties with the name author may be present within each item with the type http://n.whatwg.org/work.

license

Identifies one of the licenses under which the work is available.

The value must be an absolute URL.

Any number of properties with the name license may be present within each item with the type http://n.whatwg.org/work.

5.4.3.1 Conversion to RDF

For the purposes of RDF processors, the triples obtained from the following Turtle must be applied:

<http://www.w3.org/1999/xhtml/microdata#http%3A%2F%2Fn.whatwg.org%2Fwork%23%3Awork>
  <http://www.w3.org/2002/07/owl#equivalentProperty>
  <http://www.w3.org/2002/07/owl#sameAs> .
<http://www.w3.org/1999/xhtml/microdata#http%3A%2F%2Fn.whatwg.org%2Fwork%23%3Atitle>
  <http://www.w3.org/2002/07/owl#equivalentProperty>
  <http://purl.org/dc/terms/title> .
<http://www.w3.org/1999/xhtml/microdata#http%3A%2F%2Fn.whatwg.org%2Fwork%23%3Aauthor>
  <http://www.w3.org/2002/07/owl#equivalentProperty>
  <http://creativecommons.org/ns#attributionName> .
<http://www.w3.org/1999/xhtml/microdata#http%3A%2F%2Fn.whatwg.org%2Fwork%23%3Alicense>
  <http://www.w3.org/2002/07/owl#equivalentProperty>
  <http://www.w3.org/1999/xhtml/vocab#license> .

The subjects of the statements above are the predicates that result from converting to RDF an HTML page containing microdata with an item whose type is "http://n.whatwg.org/work".

5.4.3.2 Examples

This section is non-normative.

This example shows an embedded image entitled My Pond, licensed under the Creative Commons Attribution-Share Alike 3.0 United States License and the MIT license simultaneously.

<figure itemscope itemtype="http://n.whatwg.org/work">
 <img itemprop="work" src="mypond.jpeg">
 <figcaption>
  <p><cite itemprop="title">My Pond</cite></p>
  <p><small>Licensed under the <a itemprop="license"
  href="http://creativecommons.org/licenses/by-sa/3.0/us/">Creative
  Commons Attribution-Share Alike 3.0 United States License</a>
  and the <a itemprop="license"
  href="http://www.opensource.org/licenses/mit-license.php">MIT
  license</a>.</small>
 </figcaption>
</figure>

5 Microdata

5.1 Introduction

5.1.1 Overview

5.1.2 The basic syntax

5.1.3 Typed items

5.1.4 Global identifiers for items

5.1.5 Selecting names when defining vocabularies

5.1.6 Using the microdata DOM API

5.2 Encoding microdata

5.2.1 The microdata model

5.2.2 Items

5.2.3 Names: the itemprop attribute

5.2.4 Values

5.2.5 Associating names with items

5.3 Microdata DOM API

5.4 Microdata vocabularies

5.4.1 vCard

5.4.1.1 Conversion to vCard

5.4.1.2 Examples

5.4.2 vEvent

5.4.2.1 Conversion to iCalendar

5.4.2.2 Examples

5.4.3 Licensing works

5.4.3.1 Conversion to RDF

5.4.3.2 Examples

5.2.3 Names: the `itemprop` attribute