← 4.11.5 CommandsTable of contents4.19 Converting HTML to other formats →
    1. 4.12 Links
      1. 4.12.1 Introduction
      2. 4.12.2 Links created by a and area elements
      3. 4.12.3 Following hyperlinks
      4. 4.12.4 Link types
        1. 4.12.4.1 Link type "alternate"
        2. 4.12.4.2 Link type "author"
        3. 4.12.4.3 Link type "bookmark"
        4. 4.12.4.4 Link type "help"
        5. 4.12.4.5 Link type "icon"
        6. 4.12.4.6 Link type "license"
        7. 4.12.4.7 Link type "nofollow"
        8. 4.12.4.8 Link type "noreferrer"
        9. 4.12.4.9 Link type "prefetch"
        10. 4.12.4.10 Link type "search"
        11. 4.12.4.11 Link type "stylesheet"
        12. 4.12.4.12 Link type "tag"
        13. 4.12.4.13 Sequential link types
          1. 4.12.4.13.1 Link type "next"
          2. 4.12.4.13.2 Link type "prev"
        14. 4.12.4.14 Other link types
    2. 4.13 Common idioms without dedicated elements
      1. 4.13.1 The main part of the content
      2. 4.13.2 Bread crumb navigation
      3. 4.13.3 Tag clouds
      4. 4.13.4 Conversations
      5. 4.13.5 Footnotes
    3. 4.14 Matching HTML elements using selectors
      1. 4.14.1 Case-sensitivity
      2. 4.14.2 Pseudo-classes
      3. 4.14.3 Typed items
      4. 4.14.4 Global identifiers for items
      5. 4.14.5 Selecting names when defining vocabularies
      6. 4.14.6 Using the microdata DOM API
    4. 4.15 Encoding microdata
      1. 4.15.1 The microdata model
      2. 4.15.2 Items
      3. 4.15.3 Names: the itemprop attribute
      4. 4.15.4 Values
      5. 4.15.5 Associating names with items
      6. 4.15.6 Microdata and other namespaces
    5. 4.16 Microdata DOM API
    6. 4.17 Other changes to HTML5
      1. 4.17.1 Content models
      2. 4.17.2 Drag-and-drop
    7. 4.18 Microdata vocabularies
      1. 4.18.1 vCard
        1. 4.18.1.1 Conversion to vCard
        2. 4.18.1.2 Examples
      2. 4.18.2 vEvent
        1. 4.18.2.1 Conversion to iCalendar
        2. 4.18.2.2 Examples
      3. 4.18.3 Licensing works
        1. 4.18.3.1 Examples

4.12.1 Introduction

Links are a conceptual construct, created by a, area, and link elements, that represent a connection between two resources, one of which is the current Document. There are two kinds of links in HTML:

Links to external resources

These are links to resources that are to be used to augment the current document, generally automatically processed by the user agent.

Hyperlinks

These are links to other resources that are generally exposed to the user by the user agent so that the user can cause the user agent to navigate to those resources, e.g. to visit them in a browser or download them.

For link elements with an href attribute and a rel attribute, links must be created for the keywords of the rel attribute, as defined for those keywords in the link types section.

Similarly, for a and area elements with an href attribute and a rel attribute, links must be created for the keywords of the rel attribute as defined for those keywords in the link types section. Unlike link elements, however, a and area element with an href attribute that either do not have a rel attribute, or whose rel attribute has no keywords that are defined as specifying hyperlinks, must also create a hyperlink. This implied hyperlink has no special meaning (it has no link type) beyond linking the element's document to the resource given by the element's href attribute.

A hyperlink can have one or more hyperlink annotations that modify the processing semantics of that hyperlink.

The href attribute on a and area elements must have a value that is a valid URL potentially surrounded by spaces.

The href attribute on a and area elements is not required; when those elements do not have href attributes they do not create hyperlinks.

The target attribute, if present, must be a valid browsing context name or keyword. It gives the name of the browsing context that will be used. User agents use this name when following hyperlinks.

The rel attribute on a and area elements controls what kinds of links the elements create. The attribue's value must be a set of space-separated tokens. The allowed keywords and their meanings are defined below.

The rel attribute has no default value. If the attribute is omitted or if none of the values in the attribute are recognized by the user agent, then the document has no particular relationship with the destination resource other than there being a hyperlink between the two.

The media attribute describes for which media the target document was designed. It is purely advisory. The value must be a valid media query. The default, if the media attribute is omitted, is "all".

The hreflang attribute on a and area elements that create hyperlinks, if present, gives the language of the linked resource. It is purely advisory. The value must be a valid BCP 47 language tag. [BCP47] User agents must not consider this attribute authoritative — upon fetching the resource, user agents must use only language information associated with the resource to determine its language, not metadata included in the link to the resource.

The type attribute, if present, gives the MIME type of the linked resource. It is purely advisory. The value must be a valid MIME type. User agents must not consider the type attribute authoritative — upon fetching the resource, user agents must not use metadata included in the link to the resource to determine its type.

When a user follows a hyperlink created by an element, the user agent must resolve the URL given by the href attribute of that element, relative to that element, and if that is successful, must navigate a browsing context to the resulting absolute URL. In the case of server-side image maps, that absolute URL must have its hyperlink suffix appended to it before the navigation is started.

If resolving the URL fails, the user agent may report the error to the user in a user-agent-specific manner, may navigate to an error page to report the error, or may ignore the error and do nothing.

If the user indicated a specific browsing context when following the hyperlink, or if the user agent is configured to follow hyperlinks by navigating a particular browsing context, then that must be the browsing context that is navigated.

Otherwise, if the element is an a or area element that has a target attribute, then the browsing context that is navigated must be chosen by applying the rules for choosing a browsing context given a browsing context name, using the value of the target attribute as the browsing context name. If these rules result in the creation of a new browsing context, it must be navigated with replacement enabled.

Otherwise, if the element is an a or area element with no target attribute, but the Document contains a base element with a target attribute, then the browsing context that is navigated must be chosen by applying the rules for choosing a browsing context given a browsing context name, using the value of the target attribute of the first such base element as the browsing context name. If these rules result in the creation of a new browsing context, it must be navigated with replacement enabled.

Otherwise, the browsing context that must be navigated is the same browsing context as the one which the element itself is in.

The navigation must be done with the browsing context that contains the Document object with which the element in question is associated as the source browsing context.

4.12.4 Link types

The following table summarizes the link types that are defined by this specification. This table is non-normative; the actual definitions for the link types are given in the next few sections.

In this section, the term referenced document refers to the resource identified by the element representing the link, and the term current document refers to the resource within which the element representing the link finds itself.

To determine which link types apply to a link, a, or area element, the element's rel attribute must be split on spaces. The resulting tokens are the link types that apply to that element.

Except where otherwise specified, a keyword must not be specified more than once per rel attribute.

Link types are always ASCII case-insensitive, and must be compared as such.

Thus, rel="next" is the same as rel="NEXT".

Link type Effect on... Brief description
link a and area
alternate Hyperlink Hyperlink Gives alternate representations of the current document.
author Hyperlink Hyperlink Gives a link to the current document's author.
bookmark not allowed Hyperlink Gives the permalink for the nearest ancestor section.
help Hyperlink Hyperlink Provides a link to context-sensitive help.
icon External Resource not allowed Imports an icon to represent the current document.
license Hyperlink Hyperlink Indicates that the main content of the current document is covered by the copyright license described by the referenced document.
next Hyperlink Hyperlink Indicates that the current document is a part of a series, and that the next document in the series is the referenced document.
nofollow not allowed Annotation Indicates that the current document's original author or publisher does not endorse the referenced document.
noreferrer not allowed Annotation Requires that the user agent not send an HTTP Referer (sic) header if the user follows the hyperlink.
prefetch External Resource External Resource Specifies that the target resource should be preemptively cached.
prev Hyperlink Hyperlink Indicates that the current document is a part of a series, and that the previous document in the series is the referenced document.
search Hyperlink Hyperlink Gives a link to a resource that can be used to search through the current document and its related pages.
stylesheet External Resource not allowed Imports a stylesheet.
tag not allowed Hyperlink Gives a tag (identified by the given address) that applies to the current document.

Some of the types described below list synonyms for these values. These are to be handled as specified by user agents, but must not be used in documents.

4.12.4.1 Link type "alternate"

The alternate keyword may be used with link, a, and area elements.

The meaning of this keyword depends on the values of the other attributes.

If the element is a link element and the rel attribute also contains the keyword stylesheet

The alternate keyword modifies the meaning of the stylesheet keyword in the way described for that keyword. The alternate keyword does not create a link of its own.

The alternate keyword is used with the type attribute set to the value application/rss+xml or the value application/atom+xml

The keyword creates a hyperlink referencing a syndication feed (though not necessarily syndicating exactly the same content as the current page).

The first link, a, or area element in the document (in tree order) with the alternate keyword used with the type attribute set to the value application/rss+xml or the value application/atom+xml must be treated as the default syndication feed for the purposes of feed autodiscovery.

The following link element gives the syndication feed for the current page:

<link rel="alternate" type="application/atom+xml" href="data.xml">

The following extract offers various different syndication feeds:

<p>You can access the planets database using Atom feeds:</p>
<ul>
 <li><a href="recently-visited-planets.xml" rel="alternate" type="application/atom+xml">Recently Visited Planets</a></li>
 <li><a href="known-bad-planets.xml" rel="alternate" type="application/atom+xml">Known Bad Planets</a></li>
 <li><a href="unexplored-planets.xml" rel="alternate" type="application/atom+xml">Unexplored Planets</a></li>
</ul>
Otherwise

The keyword creates a hyperlink referencing an alternate representation of the current document.

The nature of the referenced document is given by the media, hreflang, and type attributes.

If the alternate keyword is used with the media attribute, it indicates that the referenced document is intended for use with the media specified.

If the alternate keyword is used with the hreflang attribute, and that attribute's value differs from the root element's language, it indicates that the referenced document is a translation.

If the alternate keyword is used with the type attribute, it indicates that the referenced document is a reformulation of the current document in the specified format.

The media, hreflang, and type attributes can be combined when specified with the alternate keyword.

For example, the following link is a French translation that uses the PDF format:

<link rel=alternate type=application/pdf hreflang=fr href=manual-fr>

This relationship is transitive — that is, if a document links to two other documents with the link type "alternate", then, in addition to implying that those documents are alternative representations of the first document, it is also implying that those two documents are alternative representations of each other.

The author keyword may be used with link, a, and area elements. This keyword creates a hyperlink.

For a and area elements, the author keyword indicates that the referenced document provides further information about the author of the nearest article element ancestor of the element defining the hyperlink, if there is one, or of the page as a whole, otherwise.

For link elements, the author keyword indicates that the referenced document provides further information about the author for the page as a whole.

The "referenced document" can be, and often is, a mailto: URL giving the e-mail address of the author. [MAILTO]

Synonyms: For historical reasons, user agents must also treat link, a, and area elements that have a rev attribute with the value "made" as having the author keyword specified as a link relationship.

The bookmark keyword may be used with a and area elements. This keyword creates a hyperlink.

The bookmark keyword gives a permalink for the nearest ancestor article element of the linking element in question, or of the section the linking element is most closely associated with, if there are no ancestor article elements.

The following snippet has three permalinks. A user agent could determine which permalink applies to which part of the spec by looking at where the permalinks are given.

 ...
 <body>
  <h1>Example of permalinks</h1>
  <div id="a">
   <h2>First example</h2>
   <p><a href="a.html" rel="bookmark">This</a> permalink applies to
   only the content from the first H2 to the second H2. The DIV isn't
   exactly that section, but it roughly corresponds to it.</p>
  </div>
  <h2>Second example</h2>
  <article id="b">
   <p><a href="b.html" rel="bookmark">This</a> permalink applies to
   the outer ARTICLE element (which could be, e.g., a blog post).</p>
   <article id="c">
    <p><a href="c.html" rel="bookmark">This</a> permalink applies to
    the inner ARTICLE element (which could be, e.g., a blog comment).</p>
   </article>
  </article>
 </body>
 ...

The help keyword may be used with link, a, and area elements. This keyword creates a hyperlink.

For a and area elements, the help keyword indicates that the referenced document provides further help information for the parent of the element defining the hyperlink, and its children.

In the following example, the form control has associated context-sensitive help. The user agent could use this information, for example, displaying the referenced document if the user presses the "Help" or "F1" key.

 <p><label> Topic: <input name=topic> <a href="help/topic.html" rel="help">(Help)</a></label></p>

For link elements, the help keyword indicates that the referenced document provides help for the page as a whole.

For a and area elements, on some browsers, the help keyword causes the link to use a different cursor.

4.12.4.5 Link type "icon"

The icon keyword may be used with link elements. This keyword creates an external resource link.

The specified resource is an icon representing the page or site, and should be used by the user agent when representing the page in the user interface.

Icons could be auditory icons, visual icons, or other kinds of icons. If multiple icons are provided, the user agent must select the most appropriate icon according to the type, media, and sizes attributes. If there are multiple equally appropriate icons, user agents must use the last one declared in tree order at the time that the user agent collected the list of icons. If the user agent tries to use an icon but that icon is determined, upon closer examination, to in fact be inappropriate (e.g. because it uses an unsupported format), then the user agent must try the next-most-appropriate icon as determined by the attributes.

User agents are not required to update icons when the list of icons changes, but are encouraged to do so.

There is no default type for resources given by the icon keyword. However, for the purposes of determining the type of the resource, user agents must expect the resource to be an image.

The sizes attribute gives the sizes of icons for visual media. Its value, if present, is merely advisory. User agents may use the value to decide which icon(s) to use if multiple icons are available.

If specified, the attribute must have a value that is an unordered set of unique space-separated tokens which are ASCII case-insensitive. Each value must be either an ASCII case-insensitive match for the string "any", or a value that consists of two valid non-negative integers that do not have a leading "0" (U+0030) character and that are separated by a single U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character.

The keywords represent icon sizes.

To parse and process the attribute's value, the user agent must first split the attribute's value on spaces, and must then parse each resulting keyword to determine what it represents.

The any keyword represents that the resource contains a scalable icon, e.g. as provided by an SVG image.

Other keywords must be further parsed as follows to determine what they represent:

The keywords specified on the sizes attribute must not represent icon sizes that are not actually available in the linked resource.

In the absence of a link with the icon keyword, for Documents obtained over HTTP or HTTPS, user agents may instead attempt to fetch and use an icon with the absolute URL obtained by resolving the URL "/favicon.ico" against the document's address, as if the page had declared that icon using the icon keyword.

The following snippet shows the top part of an application with several icons.

<!DOCTYPE HTML>
<html>
 <head>
  <title>lsForums — Inbox</title>
  <link rel=icon href=favicon.png sizes="16x16" type="image/png">
  <link rel=icon href=windows.ico sizes="32x32 48x48" type="image/vnd.microsoft.icon">
  <link rel=icon href=mac.icns sizes="128x128 512x512 8192x8192 32768x32768">
  <link rel=icon href=iphone.png sizes="57x57" type="image/png">
  <link rel=icon href=gnome.svg sizes="any" type="image/svg+xml">
  <link rel=stylesheet href=lsforums.css>
  <script src=lsforums.js></script>
  <meta name=application-name content="lsForums">
 </head>
 <body>
  ...

For historical reasons, the icon keyword may be preceded by the keyword "shortcut". If the "shortcut" keyword is present, it must be come immediately before the icon keyword and the two keywords must be separated by only a single U+0020 SPACE character.

The license keyword may be used with link, a, and area elements. This keyword creates a hyperlink.

The license keyword indicates that the referenced document provides the copyright license terms under which the main content of the current document is provided.

This specification does not specify how to distinguish between the main content of a document and content that is not deemed to be part of that main content. The distinction should be made clear to the user.

Consider a photo sharing site. A page on that site might describe and show a photograph, and the page might be marked up as follows:

<!DOCTYPE HTML>
<html>
 <head>
  <title>Exampl Pictures: Kissat</title>
  <link rel="stylesheet" href="/style/default">
 </head>
 <body>
  <h1>Kissat</h1>
  <nav>
   <a href="../">Return to photo index</a>
  </nav>
  <figure>
   <img src="/pix/39627052_fd8dcd98b5.jpg">
   <figcaption>Kissat</figcaption>
  </figure>
  <p>One of them has six toes!</p>
  <p><small><a rel="license" href="http://www.opensource.org/licenses/mit-license.php">MIT Licensed</a></small></p>
  <footer>
   <a href="/">Home</a> | <a href="../">Photo index</a>
   <p><small>© copyright 2009 Exampl Pictures. All Rights Reserved.</small></p>
  </footer>
 </body>
</html>

In this case the license applies to just the photo (the main content of the document), not the whole document. In particular not the design of the page itself, which is covered by the copyright given at the bottom of the document. This could be made clearer in the styling (e.g. making the license link prominently positioned near the photograph, while having the page copyright in light small text at the foot of the page.

Synonyms: For historical reasons, user agents must also treat the keyword "copyright" like the license keyword.

The nofollow keyword may be used with a and area elements. This keyword does not create a hyperlink, but annotates any other hyperlinks created by the element (the implied hyperlink, if no other keywords create one).

The nofollow keyword indicates that the link is not endorsed by the original author or publisher of the page, or that the link to the referenced document was included primarily because of a commercial relationship between people affiliated with the two pages.

The noreferrer keyword may be used with a and area elements. This keyword does not create a hyperlink, but annotates any other hyperlinks created by the element (the implied hyperlink, if no other keywords create one).

It indicates that no referrer information is to be leaked when following the link.

If a user agent follows a link defined by an a or area element that has the noreferrer keyword, the user agent must not include a Referer (sic) HTTP header (or equivalent for other protocols) in the request.

This keyword also causes the opener attribute to remain null if the hyperlink creates a new browsing context.

The prefetch keyword may be used with link, a, and area elements. This keyword creates an external resource link.

The prefetch keyword indicates that preemptively fetching and caching the specified resource is likely to be beneficial, as it is highly likely that the user will require this resource.

There is no default type for resources given by the prefetch keyword.

The search keyword may be used with link, a, and area elements. This keyword creates a hyperlink.

The search keyword indicates that the referenced document provides an interface specifically for searching the document and its related resources.

OpenSearch description documents can be used with link elements and the search link type to enable user agents to autodiscover search interfaces. [OPENSEARCH]

The stylesheet keyword may be used with link elements. This keyword creates an external resource link that contributes to the styling processing model.

The specified resource is a resource that describes how to present the document. Exactly how the resource is to be processed depends on the actual type of the resource.

If the alternate keyword is also specified on the link element, then the link is an alternative stylesheet; in this case, the title attribute must be specified on the link element, with a non-empty value.

The default type for resources given by the stylesheet keyword is text/css.

The appropriate time to obtain the resource is when the external resource link is created or when its element is inserted into a document, whichever happens last. If the resource is an alternative stylesheet then the user agent may defer obtaining the resource until it is part of the preferred style sheet set. [CSSOM]

Quirk: If the document has been set to quirks mode, has the same origin as the URL of the external resource, and the Content-Type metadata of the external resource is not a supported style sheet type, the user agent must instead assume it to be text/css.

The tag keyword may be used with a and area elements. This keyword creates a hyperlink.

The tag keyword indicates that the tag that the referenced document represents applies to the current document.

Since it indicates that the tag applies to the current document, it would be inappropriate to use this keyword in the markup of a tag cloud, which lists the popular tags across a set of pages.

Some documents form part of a sequence of documents.

A sequence of documents is one where each document can have a previous sibling and a next sibling. A document with no previous sibling is the start of its sequence, a document with no next sibling is the end of its sequence.

A document may be part of multiple sequences.

The next keyword may be used with link, a, and area elements. This keyword creates a hyperlink.

The next keyword indicates that the document is part of a sequence, and that the link is leading to the document that is the next logical document in the sequence.

The prev keyword may be used with link, a, and area elements. This keyword creates a hyperlink.

The prev keyword indicates that the document is part of a sequence, and that the link is leading to the document that is the previous logical document in the sequence.

Synonyms: For historical reasons, user agents must also treat the keyword "previous" like the prev keyword.

Extensions to the predefined set of link types may be registered in the microformats wiki existing-rel-values page. [MFREL]

Anyone is free to edit the microformats wiki existing-rel-values page at any time to add a type. Extension types must be specified with the following information:

Keyword

The actual value being defined. The value should not be confusingly similar to any other defined value (e.g. differing only in case).

If the value contains a ":" (U+003A) character, it must also be an absolute URL.

Effect on... link

One of the following:

Not allowed
The keyword must not be specified on link elements.
Hyperlink
The keyword may be specified on a link element; it creates a hyperlink.
External Resource
The keyword may be specified on a link element; it creates an external resource link.
Effect on... a and area

One of the following:

Not allowed
The keyword must not be specified on a and area elements.
Hyperlink
The keyword may be specified on a and area elements; it creates a hyperlink.
External Resource
The keyword may be specified on a and area elements; it creates an external resource link.
Hyperlink Annotation
The keyword may be specified on a and area elements; it annotates other hyperlinks created by the element.
Brief description

A short non-normative description of what the keyword's meaning is.

Specification

A link to a more detailed description of the keyword's semantics and requirements. It could be another page on the Wiki, or a link to an external page.

Synonyms

A list of other keyword values that have exactly the same processing requirements. Authors should not use the values defined to be synonyms, they are only intended to allow user agents to support legacy content. Anyone may remove synonyms that are not used in practice; only names that need to be processed as synonyms for compatibility with legacy content are to be registered in this way.

Status

One of the following:

Proposed
The keyword has not received wide peer review and approval. Someone has proposed it and is, or soon will be, using it.
Ratified
The keyword has received wide peer review and approval. It has a specification that unambiguously defines how to handle pages that use the keyword, including when they use it in incorrect ways.
Discontinued
The keyword has received wide peer review and it has been found wanting. Existing pages are using this keyword, but new pages should avoid it. The "brief description" and "specification" entries will give details of what authors should use instead, if anything.

If a keyword is found to be redundant with existing values, it should be removed and listed as a synonym for the existing value.

If a keyword is registered in the "proposed" state for a period of a month or more without being used or specified, then it may be removed from the registry.

If a keyword is added with the "proposed" status and found to be redundant with existing values, it should be removed and listed as a synonym for the existing value. If a keyword is added with the "proposed" status and found to be harmful, then it should be changed to "discontinued" status.

Anyone can change the status at any time, but should only do so in accordance with the definitions above.

Conformance checkers may use the information given on the microformats wiki existing-rel-values page to establish if a value is allowed or not: values defined in this specification or marked as "proposed" or "ratified" must be accepted when used on the elements for which they apply as described in the "Effect on..." field, whereas values marked as "discontinued" or values not containing a U+003A COLON character but not listed in either this specification or on the aforementioned page must be reported as invalid. The remaining values must be accepted as valid if they are absolute URLs containing US-ASCII characters only and rejected otherwise. Conformance checkers may cache this information (e.g. for performance reasons or to avoid the use of unreliable network connectivity).

Note: Even URL-valued link types are compared ASCII-case-insensitively. Validators might choose to warn about characters U+0041 (LATIN CAPITAL LETTER A) through U+005A (LATIN CAPITAL LETTER Z) (inclusive) in the pre-case-folded form of link types that contain a colon.

When an author uses a new type not defined by either this specification or the Wiki page, conformance checkers should offer to add the value to the Wiki, with the details described above, with the "proposed" status.

Types defined as extensions in the microformats wiki existing-rel-values page with the status "proposed" or "ratified" may be used with the rel attribute on link, a, and area elements in accordance to the "Effect on..." field. [MFREL]

4.13 Common idioms without dedicated elements

4.13.1 The main part of the content

The main content of a page — not including headers and footers, navigation links, sidebars, advertisements, and so forth — can be marked up in a variety of ways, depending on the needs of the author.

The simplest solution is to not mark up the main content at all, and just leave it as implicit. Another way to think of this is that the body elements marks up the main content of the page, and the bits that aren't main content are excluded through the use of more appropriate elements like aside and nav.

Here is a short Web page marked up along this minimalistic school of thought. The main content is highlighted. Notice how all the other content in the body is marked up with elements to indicate that it's not part of the main content, in this case header, nav, and footer.

<!DOCTYPE HTML>
<html>
 <head>
  <title> My Toys </title>
 </head>
 <body>
  <header>
   <h1>My toys</h1>
  </header>
  <nav>
   <p><a href="/">Home</a></p>
   <p><a href="/contact">Contact</a></p>
  </nav>
  <p>I really like my chained book and my telephone. I'm not such a
  fan of my big ball.</p>
  <p>Another toy I like is my mirror.</p>
  <footer>
   <p>© copyright 2010 by the boy</p>
  </footer>
 </body>
</html>

If the main content is an independent unit of content that one could imagine syndicating independently, then the article element would be appropriate to mark up the main content of the document.

The document in the previous example is here recast as a blog post:

<!DOCTYPE HTML>
<html>
 <head>
  <title> The Boy Blog: My Toys </title>
 </head>
 <body>
  <header>
   <h1>The Boy Blog</h1>
  </header>
  <nav>
   <p><a href="/">Home</a></p>
   <p><a href="/contact">Contact</a></p>
  </nav>
  <article>
   <header>
    <h1>My toys</h1>
    <p>Published August 4th</p>
   </header>
   <p>I really like my chained book and my telephone. I'm not such a
   fan of my big ball.</p>
   <p>Another toy I like is my mirror.</p>
  </article>
  <footer>
   <p>© copyright 2010 by the boy</p>
  </footer>
 </body>
</html>

If the main content is not an independent unit of content so much as a section of a larger work, for instance a chapter, then the section element would be appropriate to mark up the main content of the document.

Here is the same document, case as a chapter in an online book:

<!DOCTYPE HTML>
<html>
 <head>
  <title> Chapter 2: My Toys — The Book of the Boy </title>
 </head>
 <body>
  <header>
   <h1>Chapter 2: My Toys</h1>
  </header>
  <nav>
   <p><a href="/">Front Page</a></p>
   <p><a href="/toc">Table of Contents</a></p>
   <p><a href="/c1">Chapter 1</a> — <a href="/c3">Chapter 3</a></p>
  </nav>
  <section>
   <p>I really like my chained book and my telephone. I'm not such a
   fan of my big ball.</p>
   <p>Another toy I like is my mirror.</p>
  </section>
  <footer>
   <p>© copyright 2010 by the boy</p>
  </footer>
 </body>
</html>

If neither article nor section would be appropriate, but the main content still needs an explicit element, for example for styling purposes, then the div element can be used.

This is the same as the original example, but using div for the main content instead of leaving it implied:

<!DOCTYPE HTML>
<html>
 <head>
  <title> My Toys </title>
  <style>
   body > div { background: navy; color: yellow; }
  </style>
 </head>
 <body>
  <header>
   <h1>My toys</h1>
  </header>
  <nav>
   <p><a href="/">Home</a></p>
   <p><a href="/contact">Contact</a></p>
  </nav>
  <div>
   <p>I really like my chained book and my telephone. I'm not such a
   fan of my big ball.</p>
   <p>Another toy I like is my mirror.</p>
  </div>
  <footer>
   <p>© copyright 2010 by the boy</p>
  </footer>
 </body>
</html>

4.13.2 Bread crumb navigation

This specification does not provide a machine-readable way of describing bread-crumb navigation menus. Authors are encouraged to just use a series of links in a paragraph. The nav element can be used to mark the section containing these paragraphs as being navigation blocks.

In the following example, the current page can be reached via two paths.

<nav>
 <p>
  <a href="/">Main</a> >
  <a href="/products/">Products</a> >
  <a href="/products/dishwashers/">Dishwashers</a> >
  <a>Second hand</a>
 </p>
 <p>
  <a href="/">Main</a> >
  <a href="/second-hand/">Second hand</a> >
  <a>Dishwashers</a>
 </p>
</nav>

4.13.3 Tag clouds

This specification does not define any markup specifically for marking up lists of keywords that apply to a group of pages (also known as tag clouds). In general, authors are encouraged to either mark up such lists using ul elements with explicit inline counts that are then hidden and turned into a presentational effect using a style sheet, or to use SVG.

Here, three tags are included in a short tag cloud:

<style>
@media screen, print, handheld, tv {
  /* should be ignored by non-visual browsers */
  .tag-cloud > li > span { display: none; }
  .tag-cloud > li { display: inline; }
  .tag-cloud-1 { font-size: 0.7em; }
  .tag-cloud-2 { font-size: 0.9em; }
  .tag-cloud-3 { font-size: 1.1em; }
  .tag-cloud-4 { font-size: 1.3em; }
  .tag-cloud-5 { font-size: 1.5em; }
}
</style>
...
<ul class="tag-cloud">
 <li class="tag-cloud-4"><a title="28 instances" href="/t/apple">apple</a> <span>(popular)</span>
 <li class="tag-cloud-2"><a title="6 instances"  href="/t/kiwi">kiwi</a> <span>(rare)</span>
 <li class="tag-cloud-5"><a title="41 instances" href="/t/pear">pear</a> <span>(very popular)</span>
</ul>

The actual frequency of each tag is given using the title attribute. A CSS style sheet is provided to convert the markup into a cloud of differently-sized words, but for user agents that do not support CSS or are not visual, the markup contains annotations like "(popular)" or "(rare)" to categorize the various tags by frequency, thus enabling all users to benefit from the information.

The ul element is used (rather than ol) because the order is not particularly important: while the list is in fact ordered alphabetically, it would convey the same information if ordered by, say, the length of the tag.

The tag rel-keyword is not used on these a elements because they do not represent tags that apply to the page itself; they are just part of an index listing the tags themselves.

4.13.4 Conversations

This specification does not define a specific element for marking up conversations, meeting minutes, chat transcripts, dialogues in screenplays, instant message logs, and other situations where different players take turns in discourse.

Instead, authors are encouraged to mark up conversations using p elements and punctuation. Authors who need to mark the speaker for styling purposes are encouraged to use span or b. Paragraphs with their text wrapped in the i element can be used for marking up stage directions.

This example demonstrates this using an extract from Abbot and Costello's famous sketch, Who's on first:

<p> Costello: Look, you gotta first baseman?
<p> Abbott: Certainly.
<p> Costello: Who's playing first?
<p> Abbott: That's right.
<p> Costello becomes exasperated.
<p> Costello: When you pay off the first baseman every month, who gets the money?
<p> Abbott: Every dollar of it.

HTML does not have a good way to mark up graphs, so descriptions of interactive conversations from games are more difficult to mark up. This example shows one possible convention using dl elements to list the possible responses at each point in the conversation. Another option to consider is describing the conversation in the form of a DOT file, and outputting the result as an SVG image to place in the document. [DOT]

<p> Next, you meet a fisherman. You can say one of several greetings:
<dl>
 <dt> "Hello there!"
 <dd>
  <p> He responds with "Hello, how may I help you?"; you can respond with:
  <dl>
   <dt> "I would like to buy a fish."
   <dd> <p> He sells you a fish and the conversation finishes.
   <dt> "Can I borrow your boat?"
   <dd>
    <p> He is surprised and asks "What are you offering in return?".
    <dl>
     <dt> "Five gold." (if you have enough)
     <dt> "Ten gold." (if you have enough)
     <dt> "Fifteen gold." (if you have enough)
     <dd> <p> He lends you his boat. The conversation ends.
     <dt> "A fish." (if you have one)
     <dt> "A newspaper." (if you have one)
     <dt> "A pebble." (if you have one)
     <dd> <p> "No thanks", he replies. Your conversation options        
     at this point are the same as they were after asking to borrow
     his boat, minus any options you've suggested before.
    </dl>
   </dd>
  </dl>
 </dd>
 <dt> "Vote for me in the next election!"
 <dd> <p> He turns away. The conversation finishes.
 <dt> "Sir, are you aware that your fish are running away?"
 <dd>
  <p> He looks at you skeptically and says "Fish cannot run, sir".
  <dl>
   <dt> "You got me!"
   <dd> <p> The fisherman sighs and the conversation ends.
   <dt> "Only kidding."
   <dd> <p> "Good one!" he retorts. Your conversation options at this
   point are the same as those following "Hello there!" above.
   <dt> "Oh, then what are they doing?"
   <dd> <p> He looks at his fish, giving you an opportunity to steal
   his boat, which you do. The conversation ends.
  </dl>
 </dd>
</ul>

4.13.5 Footnotes

HTML does not have a dedicated mechanism for marking up footnotes. Here are the recommended alternatives.


For annotations, the a element should be used, pointing to an element later in the document. The convention is that the contents of the link be a number in square brackets.

In this example, a footnote in the dialogue links to a paragraph below the dialogue. The paragraph then reciprocally links back to the dialogue, allowing the user to return to the location of the footnote.

<p> Announcer: Number 16: The <i>hand</i>.
<p> Interviewer: Good evening. I have with me in the studio tonight
Mr Norman St John Polevaulter, who for the past few years has been
contradicting people. Mr Polevaulter, why <em>do</em> you
contradict people?
<p> Norman: I don't. <sup><a href="#fn1" id="r1">[1]</a></sup>
<p> Interviewer: You told me you did!
...
<section>
 <p id="fn1"><a href="#r1">[1]</a> This is, naturally, a lie,
 but paradoxically if it were true he could not say so without
 contradicting the interviewer and thus making it false.</p>
</section>

For side notes, longer annotations that apply to entire sections of the text rather than just specific words or sentences, the aside element should be used.

In this example, a sidebar is given after a dialogue, giving it some context.

<p> <span class="speaker">Customer</span>: I will not buy this record, it is scratched.
<p> <span class="speaker">Shopkeeper</span>: I'm sorry?
<p> <span class="speaker">Customer</span>: I will not buy this record, it is scratched.
<p> <span class="speaker">Shopkeeper</span>: No no no, this's'a tobacconist's.
<aside>
 <p>In 1970, the British Empire lay in ruins, and foreign
 nationalists frequented the streets — many of them Hungarians
 (not the streets — the foreign nationals). Sadly, Alexander
 Yalt has been publishing incompetently-written phrase books.
</aside>

For figures or tables, footnotes can be included in the relevant figcaption or caption element, or in surrounding prose.

In this example, a table has cells with footnotes that are given in prose. A figure element is used to give a single legend to the combination of the table and its footnotes.

<figure>
 <figcaption>Table 1. Alternative activities for knights.</figcaption>
 <table>
  <tr>
   <th> Activity
   <th> Location
   <th> Cost
  <tr>
   <td> Dance
   <td> Wherever possible
   <td> £0<sup><a href="#fn1">1</a></sup>
  <tr>
   <td> Routines, chorus scenes<sup><a href="#fn2">2</a></sup>
   <td> Undisclosed
   <td> Undisclosed
  <tr>
   <td> Dining<sup><a href="#fn3">3</a></sup>
   <td> Camelot
   <td> Cost of ham, jam, and spam<sup><a href="#fn4">4</a></sup>
 </table>
 <p id="fn1">1. Assumed.</p>
 <p id="fn2">2. Footwork impeccable.</p>
 <p id="fn3">3. Quality described as "well".</p>
 <p id="fn4">4. A lot.</p>
</figure>

4.14 Matching HTML elements using selectors

4.14.1 Case-sensitivity

The Selectors specification leaves the case-sensitivity of IDs, classes, element names, attribute names, and attribute values to be defined by the host language. [SELECTORS]

The unique identifier of HTML elements in documents that are in quirks mode must be treated as ASCII case-insensitive for the purposes of selector matching.

Classes from the class attribute of HTML elements in documents that are in quirks mode must be treated as ASCII case-insensitive for the purposes of selector matching.

Attribute and element names of HTML elements in HTML documents must be treated as ASCII case-insensitive for the purposes of selector matching.

Everything else (attribute values on HTML elements, IDs and classes in no-quirks mode and limited-quirks mode, and element names, attribute names, and attribute values in XML documents) must be treated as case-sensitive for the purposes of selector matching.

4.14.2 Pseudo-classes

There are a number of dynamic selectors that can be used with HTML. This section defines when these selectors match HTML elements. [SELECTORS] [CSSUI]

:link
:visited

All a elements that have an href attribute, all area elements that have an href attribute, and all link elements that have an href attribute, must match one of :link and :visited.

Other specifications might apply more specific rules regarding how these elements are to match these pseudo-elements, to mitigate some privacy concerns that apply with straightforward implementations of this requirement.

:active

The :active pseudo-class is defined to match an element while an element is being activated by the user. For the purposes of defining the :active pseudo-class only, an HTML user agent must consider an element as being activated if it is:

  • An element falling into one of the following categories between the time the user begins to indicate an intent to trigger the element's activation behavior and either the time the user stops indicating an intent to trigger the element's activation behavior, or the time the element's activation behavior has finished running, which ever comes first:

    For example, if the user is using a keyboard to push a button element by pressing the space bar, the element would match this pseudo-class in between the time that the element received the keydown event and the time the element received the keyup event.

  • An element that the user indicates using a pointing device while that pointing device is in the "down" state (e.g. for a mouse, between the time the mouse button is pressed and the time it is depressed).

  • An element that has a descendant that is currently matching the :active pseudo-class.

:hover

The :hover pseudo-class is defined to match an element while the user designates an element with a pointing device. For the purposes of defining the :hover pseudo-class only, an HTML user agent must consider an element as being one that the user designates if it is:

  • An element that the user indicates using a pointing device.

  • An element that has a descendant that the user indicates using a pointing device.

  • An element that is the labeled control of a label element that is currently matching :hover.

Consider in particular a fragment such as:

<p> <label for=c> <input id=a> </label> <span id=b> <input id=c> </span> </p>

If the user designates the element with ID "a" with their pointing device, then the p element (and all its ancestors not shown in the snippet above), the label element, the element with ID "a", and the element with ID "c" will match the :hover pseudo-class. The element with ID "a" matches it from condition 1, the label and p elements match it because of condition 2 (one of their descendants is designated), and the element with ID "c" matches it through condition 3 (its label element matches :hover). However, the element with ID "b" does not match :hover: its descendant is not designated, even though it matches :hover.

:enabled

The :enabled pseudo-class must match any element falling into one of the following categories:

:disabled

The :disabled pseudo-class must match any element falling into one of the following categories:

:checked

The :checked pseudo-class must match any element falling into one of the following categories:

:indeterminate

The :indeterminate pseudo-class must match any element falling into one of the following categories:

:default

The :default pseudo-class must match any element falling into one of the following categories:

:valid

The :valid pseudo-class must match any element falling into one of the following categories:

:invalid

The :invalid pseudo-class must match any element falling into one of the following categories:

:in-range

The :in-range pseudo-class must match all elements that are candidates for constraint validation, have range limitations, and that are neither suffering from an underflow nor suffering from an overflow.

:out-of-range

The :out-of-range pseudo-class must match all elements that are candidates for constraint validation, have range limitations, and that are either suffering from an underflow or suffering from an overflow.

:required

The :required pseudo-class must match any element falling into one of the following categories:

:optional

The :optional pseudo-class must match any element falling into one of the following categories:

:read-only
:read-write

The :read-write pseudo-class must match any element falling into one of the following categories:

The :read-only pseudo-class must match all other HTML elements.

:dir(ltr)

The :dir(ltr) pseudo-class must match all elements whose directionality is 'ltr'.

:dir(rtl)

The :dir(rtl) pseudo-class must match all elements whose directionality is 'rtl'.

Another section of this specification defines the target element used with the :target pseudo-class.

This specification does not define when an element matches the :focus or :lang() dynamic pseudo-classes, as those are all defined in sufficient detail in a language-agnostic fashion in the Selectors specification. [SELECTORS]

For date- and time-related data, the time element and its datetime attribute can be used instead.

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.

4.14.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's type 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").

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. Several types can share a vocabulary. For example, the types "http://example.org/people/teacher" and "http://example.org/people/engineer" could be defined to use the same vocabulary (though maybe some properties would not be especially useful in both cases, e.g. maybe the "http://example.org/people/engineer" type might not typically be used with the "classroom" property). Multiple types defined to use the same vocabulary can be given for a single item by listing the URLs as a space-separated list in the attribute' value. An item cannot be given two types if they do not use the same vocabulary, however.

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

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

4.14.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(s) 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 a particular 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].itemValue + '!');

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 getValues method, 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'].getValues();
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:

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

4.15 Encoding microdata

The following attributes are added as global attributes to HTML elements:

4.15.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 item types, a global identifier (if the vocabulary specified by the item types support global identifiers for 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). The names are unordered relative to each other, but if a particular name has multiple values, they do have a relative order.

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 types for a typed item is the item's item types, if it has one, or else is the relevant types of the item for which it is a property's value.

4.15.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 types of the item.

The itemtype attribute, if specified, must have a value that is an unordered set of unique space-separated tokens that are case-sensitive, each of which is a valid URL that is an absolute URL, and all of which are defined to use the same vocabulary. The attribute's value must have at least one token.

The item types of an item are the tokens obtained by splitting the element's itemtype attribute's value on spaces. If the itemtype attribute is missing or parsing it in this way finds no tokens, the item is said to have no item types.

The item types must all be types defined in applicable specifications and must all be defined to use the same vocabulary.

Except if otherwise specified by that specification, the URLs given as the item types 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 potentially surrounded by spaces.

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.

The exact meaning of a global identifier is determined by the vocabulary's specification. It is up to such specifications to define whether multiple items with the same global identifier (whether on the same page or on different pages) are allowed to exist, and what the processing rules for that vocabulary are with respect to handling the case of multiple items with the same ID.


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 that are case-sensitive, 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.

The itemref attribute is not part of the microdata data model. It is merely a syntactic construct to aid authors in adding annotations to pages where the data to be annotated does not follow a convenient tree structure. For example, it allows authors to mark up data in a table so that each column defines a separate item, while keeping the properties in the cells.

This example shows a simple vocabulary used to describe the products of a model railway manufacturer. The vocabulary has just five property names:

product-code
An integer that names the product in the manufacturer's catalog.
name
A brief description of the product.
scale
One of "HO", "1", or "Z" (potentially with leading or trailing whitespace), indicating the scale of the product.
digital
If present, one of "Digital", "Delta", or "Systems" (potentially with leading or trailing whitespace) indicating that the product has a digital decoder of the given type.
track-type
For track-specific products, one of "K", "M", "C" (potentially with leading or trailing whitespace) indicating the type of track for which the product is intended.

This vocabulary has four defined item types:

http://md.example.com/loco
Rolling stock with an engine
http://md.example.com/passengers
Passenger rolling stock
http://md.example.com/track
Track pieces
http://md.example.com/lighting
Equipment with lighting

Each item that uses this vocabulary can be given one or more of these types, depending on what the product is.

Thus, a locomotive might be marked up as:

<dl itemscope itemtype="http://md.example.com/loco 
                        http://md.example.com/lighting">
 <dt>Name:
 <dd itemprop="name">Tank Locomotive (DB 80)
 <dt>Product code:
 <dd itemprop="product-code">33041
 <dt>Scale:
 <dd itemprop="scale">HO
 <dt>Digital:
 <dd itemprop="digital">Delta
</dl>

A turnout lantern retrofit kit might be marked up as:

<dl itemscope itemtype="http://md.example.com/track
                       http://md.example.com/lighting">    
 <dt>Name:
 <dd itemprop="name">Turnout Lantern Kit
 <dt>Product code:
 <dd itemprop="product-code">74470
 <dt>Purpose:
 <dd>For retrofitting 2 <span itemprop="track-type">C</span> Track 
 turnouts. <meta itemprop="scale" content="HO">
</dl>

A passenger car with no lighting might be marked up as:

<dl itemscope itemtype="http://md.example.com/passengers">
 <dt>Name:
 <dd itemprop="name">Express Train Passenger Car (DB Am 203)
 <dt>Product code:
 <dd itemprop="product-code">8710
 <dt>Scale:
 <dd itemprop="scale">Z
</dl>

Great care is necessary when creating new vocabularies. Often, a hierarchical approach to types can be taken that results in a vocabulary where each item only ever has a single type, which is generally much simpler to manage.

4.15.3 Names: the itemprop attribute

Every HTML element may have an itemprop attribute specified, if doing so adds one or more properties 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 that are case-sensitive, 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:

Specifications that introduce defined property names that are not absolute URLs must ensure all such property names contain no "." (U+002E) characters, no ":" (U+003A) characters, and no space 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 id="x">
 <p itemprop="a">1</p>
</div>
<div itemscope itemref="x">
 <p itemprop="b">test</p>
 <p itemprop="a">2</p>
</div>

4.15.4 Values

The property value of a name-value pair added by an element with an itemprop attribute is as given for the first matching case in the following list:

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, track, 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 data element

The value is the value of the element's value attribute, if it has one, or the empty string otherwise.

If the element is a time element

The value is the element's datetime value.

Otherwise

The value is the element's textContent.

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

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

These requirements do not apply just because a property value happens to match the syntax for a URL. They only apply if the property is explicitly defined as taking such a value.

For example, a book about the first moon landing could be called "mission:moon". A "title" property from a vocabulary that defines a title as being a string would not expect the title to be given in an a element, even though it looks like a URL. On the other hand, if there was a (rather narrowly scoped!) vocabulary for "books whose titles look like URLs" which had a "title" property defined to take a URL, then the property would expect the title to be given in an a element (or one of the other URL property elements), because of the requirement above.

4.15.5 Associating names with items

To find the properties of an item defined by the element root, the user agent must run the following steps. These steps are also used to flag microdata errors.

  1. Let results, memory, and pending be empty lists of elements.

  2. Add the element root to memory.

  3. Add the child elements of root, if any, to pending.

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

  5. Loop: If pending is empty, jump to the step labeled end of loop.

  6. Remove an element from pending and let current be that element.

  7. If current is already in memory, there is a microdata error; return to the step labeled loop.

  8. Add current to memory.

  9. If current does not have an itemscope attribute, then: add all the child elements of current to pending.

  10. If current has an itemprop attribute specified and the element has one or more property names, then add the element to results.

  11. Return to the step labeled loop.

  12. End of loop: Sort results in tree order.

  13. Return results.

A document must not contain any items for which the algorithm to find the properties of an item finds any microdata errors.

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

All itemref attributes in a Document must be such that there are no cycles in the graph formed from representing each item in the Document as a node in the graph and each property of an item whose value is another item as an edge in the graph connecting those two 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.

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

4.15.6 Microdata and other namespaces

Currently, the itemscope, itemprop, and other microdata attributes are only defined for HTML elements. This means that attributes with the literal names "itemscope", "itemprop", etc, do not cause microdata processing to occur on elements in other namespaces, such as SVG.

Thus, in the following example there is only one item, not two.

<p itemscope></p> <!-- this is an item (with no properties and no type) -->
<svg itemscope></svg> <!-- this is not, it's just an svg element with an invalid unknown attribute -->

4.16 Microdata DOM API

partial interface Document { 
  NodeList getItems(optional DOMString typeNames); // microdata
};

partial interface HTMLElement {
  // microdata 
           attribute boolean itemScope;
  [PutForwards=value] readonly attribute DOMSettableTokenList itemType;
           attribute DOMString itemId;
  [PutForwards=value] readonly attribute DOMSettableTokenList itemRef;
  [PutForwards=value] readonly attribute DOMSettableTokenList itemProp;
  readonly attribute HTMLPropertiesCollection properties;
           attribute any itemValue;
};
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 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 InvalidAccessError exception.

The document.getItems(typeNames) method takes an optional string that contains an unordered set of unique space-separated tokens that are case-sensitive, 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 whose types include all the types specified in the method's 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. When the method is invoked on a Document object again with the same argument, the user agent may return the same object as the object returned by the earlier call. In other cases, a new NodeList object must be returned.

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. 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 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 InvalidAccessError exception on setting.

If the element has an itemscope attribute

The attribute must return the element itself on getting and must throw an InvalidAccessError 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, track, 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 data element

The attribute must act as it would if it was reflecting the element's value content attribute.

If the element is a time element

On getting, if the element has a datetime content attribute, the IDL attribute must return that content attribute's value; otherwise, it must return the element's textContent. On setting, the IDL 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]));

4.17 Other changes to HTML5

4.17.1 Content models

If the itemprop attribute is present on link or meta, they are flow content and phrasing content. The link and meta elements may be used where phrasing content is expected if the itemprop attribute is present.

If a link element has an itemprop attribute, the rel attribute may be omitted.

If a meta element has an itemprop attribute, the name, http-equiv, and charset attributes must be omitted, and the content attribute must be present.

If the itemprop is specified on an a or area element, then the href attribute must also be specified.

If the itemprop is specified on an iframe element, then the data attribute must also be specified.

If the itemprop is specified on an embed element, then the data attribute must also be specified.

If the itemprop is specified on an object element, then the data attribute must also be specified.

If the itemprop is specified on a media element, then the src attribute must also be specified.

4.17.2 Drag-and-drop

The drag-and-drop initialization steps are:

  1. The user agent must take the list of dragged nodes and extract the microdata from those nodes into a JSON form, and then must add the resulting string to the dataTransfer member, associated with the application/microdata+json format.

4.18 Microdata vocabularies

4.18.1 vCard

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

This vocabulary does not support 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. [RFC6350]

kind

Describes what kind of contact the item represents.

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

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

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.

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

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.

anniversary

Gives the birth date of the person or organization.

The value must be a valid date string.

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

sex

Gives the biological sex of the person.

The value must be one of F, meaning "female", M, meaning "male", N, meaning "none or not applicable", O, meaning "other", or U, meaning "unknown".

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

gender-identity

Gives the gender identity of the person.

The value must be text.

A single property with the name gender-identity 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 text.

Any number of properties with the name email 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 an absolute URL.

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

lang

Gives a language understood by the person or organization.

The value must be a valid BCP 47 language tag. [BCP47].

Any number of properties with the name lang 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:

  1. Either a "+" (U+002B) character or a "-" (U+002D) character.
  2. A valid non-negative integer that is exactly two digits long and that represents a number in the range 00..23.
  3. A ":" (U+003A) character.
  4. 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:

  1. Optionally, either a "+" (U+002B) character or a "-" (U+002D) character.
  2. One or more digits in the range ASCII digits.
  3. Optionally*, a "." (U+002E) character followed by one or more digits in the range ASCII digits.
  4. A ";" (U+003B) character.
  5. Optionally, either a "+" (U+002B) character or a "-" (U+002D) character.
  6. One or more digits in the range ASCII digits.
  7. Optionally*, a "." (U+002E) character followed by one or more digits in the range ASCII digits.

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.

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

member

Gives a URL that represents a member of the group.

The value must be an absolute URL.

Any number of properties with the name member may be present within each item with the type http://microformats.org/profile/hcard if the item also has a property with the name kind whose value is "group".

related

Gives a relationship to another entity.

The value must an item with one url property and one rel properties.

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

url (inside related)

Gives the URL for the related entity.

The value must be an absolute URL.

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

rel (inside related)

Gives the relationship between the entity and the related entity.

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

Exactly one property with the name rel must be present within the item that forms the value of an related 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.

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.

uid

Gives a globally unique identifier corresponding to the person or organization.

The value must be text.

A single property with the name uid 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.

The kind strings are:

individual

Indicates a single entity (e.g. a person).

group

Indicates multiple entities (e.g. a mailing list).

org

Indicates a single entity that is not a person (e.g. a company).

location

Indicates a geographical place (e.g. an office building).

The address type strings are:

home

Indicates a residential delivery address.

work

Indicates a delivery address for a place of work.

The telephone type strings are:

home

Indicates a residential number.

work

Indicates a telephone number for a place of work.

text

Indicates that the telephone number supports text messages (SMS).

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.

textphone

Indicates a telecommunication device for people with hearing or speech difficulties.

The relationship strings are:

emergency

An emergency contact.

agent

Another entity that acts on behalf of this entity.

contact
acquaintance
friend
met
worker
colleague
resident
neighbor
child
parent
sibling
spouse
kin
muse
crush
date
sweetheart
me

Has the meaning defined in XFN. [XFN]

4.18.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):

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

  2. Let node be the first node in nodes that is an item with the item type http://microformats.org/profile/hcard.

  3. Let output be an empty string.

  4. Add a vCard line with the type "BEGIN" and the value "VCARD" to output.

  5. Add a vCard line with the type "PROFILE" and the value "VCARD" to output.

  6. Add a vCard line with the type "VERSION" and the value "4.0" to output.

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

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

  9. Let sex be the empty string.

  10. Let gender-identity be the empty string.

  11. 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. Let value be the empty string.

      2. Append to value the result of collecting the first vCard subproperty named family-name in subitem.

      3. Append a ";" (U+003B) character to value.
      4. Append to value the result of collecting the first vCard subproperty named given-name in subitem.

      5. Append a ";" (U+003B) character to value.
      6. Append to value the result of collecting the first vCard subproperty named additional-name in subitem.

      7. Append a ";" (U+003B) character to value.
      8. Append to value the result of collecting the first vCard subproperty named honorific-prefix in subitem.

      9. Append a ";" (U+003B) character to value.
      10. 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) character to value.
      4. Append to value the result of collecting vCard subproperties named extended-address in subitem.

      5. Append a ";" (U+003B) character to value.
      6. Append to value the result of collecting vCard subproperties named street-address in subitem.

      7. Append a ";" (U+003B) character to value.
      8. Append to value the result of collecting the first vCard subproperty named locality in subitem.

      9. Append a ";" (U+003B) character to value.
      10. Append to value the result of collecting the first vCard subproperty named region in subitem.

      11. Append a ";" (U+003B) 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) 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. Let value be the empty string.

      2. Append to value the result of collecting the first vCard subproperty named organization-name in subitem.

      3. For each property named organization-unit in subitem, run the following steps:

        1. If the value of the property is an item, then skip this property.

        2. Append a ";" (U+003B) character to value.

        3. 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 related
      1. Let value be the empty string.

      2. If there is a property named url in subitem, and its element is a URL property element, then append the result of escaping the vCard text string given by the value of the first such property to value, and add a parameter with the name "VALUE" and the value "URI" to parameters.

      3. If there is a property named rel 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 "RELATION" whose value is the value of that property 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.

      If the property's value is not an item and its name is sex

      If this is the first such property to be found, set sex to the property's value.

      If the property's value is not an item and its name is gender-identity

      If this is the first such property to be found, set gender-identity to the property's value.

      Otherwise (the property's value is not an item)
      1. Let value be the property's value.

      2. If element is one of the URL property elements, add a parameter with the name "VALUE" and the value "URI" to parameters.

      3. Otherwise, if name is bday or anniversary and the value is a valid date string, add a parameter with the name "VALUE" and the value "DATE" to parameters.

      4. Otherwise, if name is rev 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.

      5. Prefix every "\" (U+005C) character in value with another "\" (U+005C) character.

      6. Prefix every "," (U+002C) character in value with a U+005C REVERSE SOLIDUS character (\).

      7. Unless name is geo, prefix every ";" (U+003B) character in value with a "\" (U+005C) character.

      8. Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in value with a "\" (U+005C) character followed by a "n" (U+006E) character.

      9. Replace every remaining "CR" (U+000D) or "LF" (U+000A) character in value with a "\" (U+005C) character followed by a "n" (U+006E) character.

    3. Add a vCard line with the type name, the parameters parameters, and the value value to output.

  12. If either of sex or gender-identity have a value that is not the empty string, add a vCard line with the type "GENDER" and the value consisting of the concatenation of sex, a ";" (U+003B) character, and gender-identity to output.

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

  1. Let line be an empty string.

  2. Append type, converted to ASCII uppercase, to line.

  3. If there are any parameters, then for each parameter, in the order that they were added, run these substeps:

    1. Append a ";" (U+003B) character to line.

    2. Append the parameter's name to line.

    3. Append a "=" (U+003D) character to line.

    4. Append the parameter's value to line.

  4. Append a ":" (U+003A) character to line.

  5. Append value to line.

  6. Let maximum length be 75.

  7. 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 "CR" (U+000D) character to output.

    4. Append a "LF" (U+000A) character to output.

    5. Append a U+0020 SPACE character to output.

    6. Let maximum length be 74.

  8. Append (what remains of) line to output.

  9. Append a "CR" (U+000D) character to output.

  10. Append a "LF" (U+000A) character 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:

  1. Let value be the empty string.

  2. 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) character to value.

    3. Append the result of escaping the vCard text string given by the value of the property to value.

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

  1. If there are no properties named subname in subitem, then abort these substeps, returning the empty string.

  2. If the value of the first property named subname in subitem is an item, then abort these substeps, returning the empty string.

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

  1. Prefix every "\" (U+005C) character in value with another U+005C REVERSE SOLIDUS character (\).

  2. Prefix every "," (U+002C) character in value with a U+005C REVERSE SOLIDUS character (\).

  3. Prefix every ";" (U+003B) character in value with a U+005C REVERSE SOLIDUS character (\).

  4. Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in value with a "\" (U+005C) character followed by a "n" (U+006E) character.

  5. Replace every remaining "CR" (U+000D) or "LF" (U+000A) character in value with a "\" (U+005C) character followed by a "n" (U+006E) character.

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

4.18.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">
  <span itemprop="n" itemscope>
   <span itemprop="given-name">Jack</span>
   <span itemprop="family-name">Bauer</span>
  </span>
 </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="voice">
  </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>
 <ins datetime="2008-07-20 21:00:00+01:00">
  <meta itemprop="rev" content="2008-07-20 21:00:00+01:00">
  <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"><span itemprop="n" itemscope><span itemprop="given-name">Alfred</span>
 <span itemprop="family-name">Person</span></span></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><span itemprop="n" itemscope><span itemprop="given-name"
>George</span> <span itemprop="family-name">Washington</span></span
></span></span>

This creates a single item with a two name-value pairs, one with the name "fn" and the value "George Washington", and the other with the name "n" and a second item as its value, the second item having the two name-value pairs "given-name" and "family-name" with the values "George" and "Washington" respectively. This is defined to map to the following vCard:

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

4.18.2 vEvent

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

This vocabulary does not support 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:

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:

  1. Optionally, either a "+" (U+002B) character or a "-" (U+002D) character.
  2. One or more digits in the range ASCII digits.
  3. Optionally*, a "." (U+002E) character followed by one or more digits in the range ASCII digits.
  4. A ";" (U+003B) character.
  5. Optionally, either a "+" (U+002B) character or a "-" (U+002D) character.
  6. One or more digits in the range ASCII digits.
  7. Optionally*, a "." (U+002E) character followed by one or more digits in the range ASCII digits.

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.

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:

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 "LF" (U+000A) 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 duration of the event.

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:

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.

uid

Gives a globally unique identifier corresponding to the event.

The value must be text.

A single property with the name uid 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:

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:

  1. A "P" (U+0050) character.
  2. One of the following:
4.18.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:

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

  2. Let output be an empty string.

  3. Add an iCalendar line with the type "BEGIN" and the value "VCALENDAR" to output.

  4. Add an iCalendar line with the type "PRODID" and the value equal to a user-agent-specific string representing the user agent to output.

  5. Add an iCalendar line with the type "VERSION" and the value "2.0" to output.

  6. 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. 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 the property is dtend
      If the property is dtstart
      If the property is exdate
      If the property is rdate
      If the property is created
      If the property is last-modified

      Let value be the result of stripping all "-" (U+002D) and ":" (U+003A) 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.

    4. Add an iCalendar line with the type "END" and the value "VEVENT" to output.

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

  1. Let line be an empty string.

  2. Append type, converted to ASCII uppercase, to line.

  3. If there is an annotation:

    1. Append a ";" (U+003B) character to line.

    2. Append the annotation to line.

  4. Append a ":" (U+003A) character to line.

  5. Prefix every "\" (U+005C) character in value with another "\" (U+005C) character.

  6. Prefix every "," (U+002C) character in value with a U+005C REVERSE SOLIDUS character (\).

  7. Prefix every ";" (U+003B) character in value with a U+005C REVERSE SOLIDUS character (\).

  8. Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in value with a "\" (U+005C) character followed by a "n" (U+006E) character.

  9. Replace every remaining "CR" (U+000D) or "LF" (U+000A) character in value with a "\" (U+005C) character followed by a "n" (U+006E) character.

  10. Append value to line.

  11. Let maximum length be 75.

  12. 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 "CR" (U+000D) character to output.

    4. Append a "LF" (U+000A) character to output.

    5. Append a U+0020 SPACE character to output.

    6. Let maximum length be 74.

  13. Append (what remains of) line to output.

  14. Append a "CR" (U+000D) character to output.

  15. Append a "LF" (U+000A) character 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.

4.18.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.contains('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';
  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" datetime="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>

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

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