If an a or area hyperlink element has a
ping attribute, and the
user follows the hyperlink, and the hyperlink's URL can
be resolved, relative to the
hyperlink element, without failure, then the user agent must take
the ping attribute's value,
split that string on
spaces, resolve each
resulting token relative to the hyperlink element, and then should
send a request (as described below) to each of the resulting absolute URLs. (Tokens that fail to
resolve are ignored.) This may be done in parallel with the primary
request, and is independent of the result of that request.
User agents should allow the user to adjust this behavior, for
example in conjunction with a setting that disables the sending of
HTTP Referer (sic) headers. Based
on the user's preferences, UAs may either ignore the
ping attribute altogether,
or selectively ignore URLs in the list (e.g. ignoring any
third-party URLs).
For URLs that are HTTP URLs, the requests must be performed by
fetching the specified URLs using the
POST method, with an entity body with the MIME type
text/ping consisting of the four-character string
"PING", from the origin of the
Document containing the hyperlink. All relevant cookie and HTTP
authentication headers must be included in the request. Which other
headers are required depends on the URLs involved.
Document object containing the hyperlink being
audited and the ping URL have the same originPing-From HTTP header with, as its
value, the address of
the document containing the hyperlink, and a Ping-To HTTP header with, as its value,
the address of the absolute URL of the target of the
hyperlink. The request must not include a Referer (sic) HTTP header. Referer (sic) HTTP header with, as its
value, the current
address of the document containing the hyperlink, a Ping-From HTTP header with the same
value, and a Ping-To HTTP header
with, as its value, the address of the target of the
hyperlink.Ping-To HTTP header with, as its value,
the address of the target of the hyperlink. The request must
neither include a Referer (sic)
HTTP header nor include a Ping-From HTTP header.To save bandwidth, implementors might also wish to
consider omitting optional headers such as Accept from
these requests.
User agents must, unless otherwise specified by the user, honor the HTTP headers (including, in particular, redirects and HTTP cookie headers), but must ignore any entity bodies returned in the responses. User agents may close the connection prematurely once they start receiving an entity body. [COOKIES]
For URLs that are not HTTP URLs, the requests must be performed by fetching the specified URL normally, and discarding the results.
When the ping attribute is
present, user agents should clearly indicate to the user that
following the hyperlink will also cause secondary requests to be
sent in the background, possibly including listing the actual target
URLs.
For example, a visual user agent could include the hostnames of the target ping URLs along with the hyperlink's actual URL in a status bar or tooltip.
The ping attribute is redundant
with pre-existing technologies like HTTP redirects and JavaScript
in allowing Web pages to track which off-site links are most
popular or allowing advertisers to track click-through rates.
However, the ping attribute
provides these advantages to the user over those alternatives:
Thus, while it is possible to track users without this feature,
authors are encouraged to use the ping attribute so that the user
agent can make the user experience more transparent.
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.
The link types that contain no U+003A COLON characters (:), including all those defined in this specification, are ASCII case-insensitive values, 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. |
archives |
Hyperlink | Hyperlink | Provides a link to a collection of records, documents, or other materials of historical interest. |
author |
Hyperlink | Hyperlink | Gives a link to the current document's author. |
bookmark |
not allowed | Hyperlink | Gives the permalink for the nearest ancestor section. |
external |
not allowed | Hyperlink | Indicates that the referenced document is not part of the same site as the current document. |
first |
Hyperlink | Hyperlink | Indicates that the current document is a part of a series, and that the first document in the series is the referenced document. |
help |
Hyperlink | Hyperlink | Provides a link to context-sensitive help. |
icon |
External Resource | not allowed | Imports an icon to represent the current document. |
index |
Hyperlink | Hyperlink | Gives a link to the document that provides a table of contents or index listing the current document. |
last |
Hyperlink | Hyperlink | Indicates that the current document is a part of a series, and that the last document in the series is the referenced 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 | Hyperlink | Indicates that the current document's original author or publisher does not endorse the referenced document. |
noreferrer |
not allowed | Hyperlink | Requires that the user agent not send an HTTP Referer (sic) header if the user follows the hyperlink. |
pingback |
External Resource | not allowed | Gives the address of the pingback server that handles pingbacks to the current document. |
prefetch |
External Resource | not allowed | 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. |
sidebar |
Hyperlink | Hyperlink | Specifies that the referenced document, if retrieved, is intended to be shown in the browser's sidebar (if it has one). |
tag |
Hyperlink | Hyperlink | Gives a tag (identified by the given address) that applies to the current document. |
up |
Hyperlink | Hyperlink | Provides a link to a document giving the context for 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.
alternate"The alternate keyword may be
used with link, a, and area
elements. For link elements, if the rel attribute does not also contain the
keyword stylesheet, it creates a
hyperlink; but if it
does also contain the keyword stylesheet, the alternate keyword instead modifies the
meaning of the stylesheet
keyword in the way described for that keyword, and the rest of this
subsection doesn't apply.
The alternate keyword
indicates that the referenced document is 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>
If the alternate keyword is
used with the type
attribute set to the value application/rss+xml
or the value application/atom+xml, then it
indicates that the referenced document is 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>
The alternate link
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.
archives"The archives keyword may be
used with link, a, and area
elements. For link elements, it creates a hyperlink.
The archives keyword indicates
that the referenced document describes a collection of records,
documents, or other materials of historical interest.
A blog's index page could link to an index of the
blog's past posts with rel="archives".
Synonyms: For historical reasons, user agents
must also treat the keyword "archive" like the
archives keyword.
author"The author keyword may be
used with link, a, and area
elements. For link elements, it 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.
bookmark"The bookmark keyword may be
used with a and area elements.
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>
...
external"The external keyword may be
used with a and area elements.
The external keyword indicates
that the link is leading to a document that is not part of the site
that the current document forms a part of.
help"The help keyword may be used with
link, a, and area
elements. For link elements, it 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.
icon"The icon keyword may be used with
link elements, for which it 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. 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.
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.
If specified, the attribute must have a value that is an
unordered set of unique space-separated tokens. The
values must all be either any or a value that consists of
two valid non-negative
integers that do not have a leading U+0030 DIGIT ZERO (0)
character and that are separated by a single U+0078 LATIN SMALL
LETTER X character (x).
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:
If the keyword doesn't contain exactly one U+0078 LATIN SMALL LETTER X character (x), then this keyword doesn't represent anything. Abort these steps for that keyword.
Let width string be the string before
the "x".
Let height string be the string after the
"x".
If either width string or height string start with a U+0030 DIGIT ZERO (0) character or contain any characters other than characters in the range U+0030 DIGIT ZERO (0) to U+0039 DIGIT NINE (9), then this keyword doesn't represent anything. Abort these steps for that keyword.
Apply the rules for parsing non-negative integers to width string to obtain width.
Apply the rules for parsing non-negative integers to height string to obtain height.
The keyword represents that the resource contains a bitmap icon with a width of width device pixels and a height of height device pixels.
The keywords specified on the sizes attribute must not represent
icon sizes that are not actually available in the linked
resource.
If the attribute is not specified, then the user agent must assume that the given icon is appropriate, but less appropriate than an icon of a known and appropriate size.
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="59x60" 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> ...
license"The license keyword may be used
with link, a, and area
elements. For link elements, it 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.
nofollow"The nofollow keyword may be
used with a and area elements.
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.
noreferrer"The noreferrer keyword may be
used with a and area elements.
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.
pingback"The pingback keyword may be
used with link elements, for which it creates an external resource link.
For the semantics of the pingback keyword, see the Pingback 1.0
specification. [PINGBACK]
prefetch"The prefetch keyword may be
used with link elements, for which it 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.
search"The search keyword may be used
with link, a, and area
elements. For link elements, it 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]
stylesheet"The stylesheet keyword may be
used with link elements, for which it 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.
Quirk: If the document has been set to
quirks mode 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.
sidebar"The sidebar keyword may be used
with link, a, and area
elements. For link elements, it creates a hyperlink.
The sidebar keyword indicates
that the referenced document, if retrieved, is intended to be shown
in a secondary browsing context (if possible), instead
of in the current browsing context.
A hyperlink element with the sidebar keyword specified is a sidebar hyperlink.
tag"The tag keyword may be used
with link, a, and area
elements. For link elements, it 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 tag across a set of pages.
Some documents form part of a hierarchical structure of documents.
A hierarchical structure of documents is one where each document can have various subdocuments. The document of which a document is a subdocument is said to be the document's parent. A document with no parent forms the top of the hierarchy.
A document may be part of multiple hierarchies.
index"The index keyword may be used with
link, a, and area
elements. For link elements, it creates a hyperlink.
The index keyword indicates that
the document is part of a hierarchical structure, and that the link
is leading to the document that is the top of the hierarchy. It
conveys more information when used with the up keyword (q.v.).
Synonyms: For historical reasons, user agents
must also treat the keywords "top", "contents", and "toc" like the
index keyword.
up"The up keyword may be used with
link, a, and area
elements. For link elements, it creates a hyperlink.
The up keyword indicates that the
document is part of a hierarchical structure, and that the link is
leading to a document that is an ancestor of the current
document.
The up keyword may be repeated within
a rel attribute to indicate
the hierarchical distance from the current document to the
referenced document. If it occurs only once, then the link is
leading to the current document's parent; each additional occurrence
of the keyword represents one further level. If the index keyword is also present, then the
number of up keywords is the depth of
the current page relative to the top of the hierarchy. Only one link
is created for the set of one or more up
keywords and, if present, the index
keyword.
If the page is part of multiple hierarchies, then they should be
described in different paragraphs. User agents
must scope any interpretation of the up
and index keywords together
indicating the depth of the hierarchy to the paragraph
in which the link finds itself, if any, or to the document
otherwise.
When two links have both the up and
index keywords specified together in
the same scope and contradict each other by having a different
number of up keywords, the link with the
greater number of up keywords must be
taken as giving the depth of the document.
This can be used to mark up a navigation style sometimes known as bread crumbs. In the following example, the current page can be reached via two paths.
<nav> <p> <a href="/" rel="index up up up">Main</a> > <a href="/products/" rel="up up">Products</a> > <a href="/products/dishwashers/" rel="up">Dishwashers</a> > <a>Second hand</a> </p> <p> <a href="/" rel="index up up">Main</a> > <a href="/second-hand/" rel="up">Second hand</a> > <a>Dishwashers</a> </p> </nav>
The relList IDL
attribute (e.g. on the a element) does not currently
represent multiple up keywords (the
interface hides duplicates).
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.
first"The first keyword may be used with
link, a, and area
elements. For link elements, it creates a hyperlink.
The first keyword indicates that
the document is part of a sequence, and that the link is leading to
the document that is the first logical document in the sequence.
Synonyms: For historical reasons, user agents
must also treat the keywords "begin" and
"start" like the first keyword.
last"The last keyword may be used with
link, a, and area
elements. For link elements, it creates a hyperlink.
The last keyword indicates that the
document is part of a sequence, and that the link is leading to the
document that is the last logical document in the sequence.
Synonyms: For historical reasons, user agents
must also treat the keyword "end" like the
last keyword.
next"The next keyword may be used with
link, a, and area
elements. For link elements, it 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.
prev"The prev keyword may be used with
link, a, and area
elements. For link elements, it 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 WHATWG Wiki RelExtensions page. [WHATWGWIKI]
Anyone is free to edit the WHATWG Wiki RelExtensions page at any time to add a type. Extension types must be specified with the following information:
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 COLON character (:), it must also be an absolute URL.
linkOne of the following:
link elements.link element;
it creates a hyperlink
link.link element;
it creates a external
resource link.a and areaOne of the following:
a
and area elements.a and
area elements.A short non-normative description of what the keyword's meaning is.
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.
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.
One of the following:
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 must use the information given on the WHATWG Wiki RelExtensions 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 not listed in either this specification or on the aforementioned page must be rejected as invalid. Conformance checkers may cache this information (e.g. for performance reasons or to avoid the use of unreliable network connectivity).
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 WHATWG Wiki
RelExtensions 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. [WHATWGWIKI]
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.
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.
The following extract shows how an IM conversation log could be marked up.
<p> <time>14:22</time> <b>egof</b> I'm not that nerdy, I've only seen 30% of the star trek episodes <p> <time>14:23</time> <b>kaj</b> if you know what percentage of the star trek episodes you have seen, you are inarguably nerdy <p> <time>14:23</time> <b>egof</b> it's unarguably <p> <time>14:23</time> <i>* kaj blinks</i> <p> <time>14:24</time> <b>kaj</b> you are not helping your case
HTML does not have a dedicated mechanism for marking up footnotes. Here are the recommended alternatives.
For short inline annotations, the title attribute should be used.
In this example, two parts of a dialogue are annotated with
footnote-like content using the title attribute.
<p> <b>Customer</b>: Hello! I wish to register a complaint. Hello. Miss? <p> <b>Shopkeeper</b>: <span title="Colloquial pronunciation of 'What do you'" >Watcha</span> mean, miss? <p> <b>Customer</b>: Uh, I'm sorry, I have a cold. I wish to make a complaint. <p> <b>Shopkeeper</b>: Sorry, <span title="This is, of course, a lie.">we're closing for lunch</span>.
For longer 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>
Attribute and element names of HTML elements in HTML documents must be treated as ASCII case-insensitive.
Classes from the class attribute
of HTML elements in documents that are in quirks
mode must be treated as ASCII
case-insensitive.
Attribute selectors on an HTML element in an HTML document must treat the values of attributes with the following names as ASCII case-insensitive:
accept
accept-charset
align
alink
axis
bgcolor
charset
checked
clear
codetype
color
compact
declare
defer
dir
direction
disabled
enctype
face
frame
hreflang
http-equiv
lang
language
link
media
method
multiple
nohref
noresize
noshade
nowrap
readonly
rel
rev
rules
scope
scrolling
selected
shape
target
text
type
valign
valuetype
vlink
All other attribute values on HTML elements must be treated as case-sensitive.
There are a number of dynamic selectors that can be used with HTML. This section defines when these selectors match HTML elements.
:link:visitedAll 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.
:activeThe :active pseudo-class
must match the following elements between the time the user begins
to activate the element and the time the user stops activating
the element:
a elements that have an href attributearea elements that have an href attributelink elements that have an href attributebutton elements that are not disabledinput elements whose type attribute is in the Submit Button, Image Button, Reset Button, or Button statecommand elements that do not have a disabled attributeFor 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.
:enabledThe :enabled pseudo-class
must match the following elements:
a elements that have an href attributearea elements that have an href attributelink elements that have an href attributebutton elements that are not disabledinput elements whose type attribute are not in the
Hidden state and that
are not disabledselect elements that are not disabledtextarea elements that are not disabledoption elements that do not have a disabled attributecommand elements that do not have a disabled attributeli elements that are children of
menu elements, and that have a child element that
defines a command, if the
first such element's Disabled State facet
is false (not disabled):disabledThe :disabled
pseudo-class must match the following elements:
button elements that are disabledinput elements whose type attribute are not in the
Hidden state and that
are disabledselect elements that are disabledtextarea elements that are disabledoption elements that have a disabled attributecommand elements that have a disabled attributeli elements that are children of
menu elements, and that have a child element that
defines a command, if the
first such element's Disabled State facet
is true (disabled):checkedThe :checked pseudo-class
must match the following elements:
input elements whose type attribute is in the Checkbox state and whose
checkedness state is
trueinput elements whose type attribute is in the Radio Button state and whose
checkedness state is
truecommand elements whose type attribute is in the Checkbox state
and that have a checked
attributecommand elements whose type attribute is in the Radio state and that
have a checked
attribute:indeterminateThe :indeterminate
pseudo-class must match input elements whose type attribute is in the Checkbox state and whose
indeterminate IDL
attribute is set to true.
:defaultThe :default pseudo-class
must match the following elements:
button elements that are their form's
default buttoninput elements whose type attribute is in the Submit Button or Image Button state, and that
are their form's default button:validThe :valid pseudo-class
must match all elements that are candidates for constraint validation
and that satisfy their
constraints.
:invalidThe :invalid pseudo-class
must match all elements that are candidates for constraint validation
but that do not satisfy their
constraints.
:in-rangeThe :in-range
pseudo-class must match all elements that are candidates for
constraint validation and that are neither suffering
from an underflow nor suffering from an
overflow.
:out-of-rangeThe :out-of-range
pseudo-class must match all elements that are candidates for
constraint validation and that are suffering from an
underflow or suffering from an overflow.
:requiredThe :required
pseudo-class must match the following elements:
:optionalThe :optional
pseudo-class must match the following elements:
:read-only:read-writeThe :read-write
pseudo-class must match the following elements:
input elements to which the readonly attribute applies,
but that are not immutable
(i.e. that do not have the readonly attribute specified
and that are not disabled)textarea elements that do not have a readonly attribute, and
that are not disabledThe :read-only
pseudo-class must match all other HTML elements.
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 :hover, :focus, or :lang() dynamic pseudo-classes, as
those are all defined in sufficient detail in a language-agnostic
fashion in the Selectors specification. [SELECTORS]
This section is non-normative.
Sometimes, it is desirable to annotate content with specific machine-readable labels, e.g. to allow generic scripts to provide services that are customised to the page, or to enable content from a variety of cooperating authors to be processed by a single script in a consistent manner.
For this purpose, authors can use the microdata features described in this section. Microdata allows nested groups of name-value pairs to be added to documents, in parallel with the existing content.
This section is non-normative.
At a high level, microdata consists of a group of name-value pairs. The groups are called items, and each name-value pair is a property. Items and properties are represented by regular elements.
To create an item, the itemscope attribute is used.
To add a property to an item, the itemprop attribute is used on one of
the item's descendants.
Here there are two items, each of which has the property "name":
<div itemscope> <p>My name is <span itemprop="name">Elizabeth</span>.</p> </div> <div itemscope> <p>My name is <span itemprop="name">Daniel</span>.</p> </div>
Properties generally have values that are strings.
Here the item has three properties:
<div itemscope> <p>My name is <span itemprop="name">Neil</span>.</p> <p>My band is called <span itemprop="band">Four Parts Water</span>.</p> <p>I am <span itemprop="nationality">British</span>.</p> </div>
Properties can also have values that are URLs. This is achieved using the a
element and its href
attribute, the img element and its src attribute, or other elements that
link to or embed external resources.
In this example, the item has one property, "image", whose value is a URL:
<div itemscope> <img itemprop="image" src="google-logo.png" alt="Google"> </div>
Properties can also have values that are dates, times, or dates
and times. This is achieved using the time element and
its datetime attribute.
In this example, the item has one property, "birthday", whose value is a date:
<div itemscope> I was born on <time itemprop="birthday" datetime="2009-05-10">May 10th 2009</time>. </div>
Properties can also themselves be groups of name-value pairs, by
putting the itemscope attribute
on the element that declares the property.
Items that are not part of others are called top-level microdata items.
In this example, the outer item represents a person, and the inner one represents a band:
<div itemscope> <p>Name: <span itemprop="name">Amanda</span></p> <p>Band: <span itemprop="band" itemscope> <span itemprop="name">Jazz Band</span> (<span itemprop="size">12</span> players)</span></p> </div>
The outer item here has two properties, "name" and "band". The "name" is "Amanda", and the "band" is an item in its own right, with two properties, "name" and "size". The "name" of the band is "Jazz Band", and the "size" is "12".
The outer item in this example is a top-level microdata item.
Properties that are not descendants of the element with the itemscope attribute can be associated
with the item using the itemref attribute. This attribute takes
a list of IDs of elements to crawl in addition to crawling the
children of the element with the itemscope attribute.
This example is the same as the previous one, but all the properties are separated from their items:
<div itemscope id="amanda" itemref="a b"></div> <p id="a">Name: <span itemprop="name">Amanda</span></p> <div id="b" itemprop="band" itemscope itemref="c"></div> <div id="c"> <p>Band: <span itemprop="name">Jazz Band</span></p> <p>Size: <span itemprop="size">12</span> players</p> </div>
This gives the same result as the previous example. The first item has two properties, "name", set to "Amanda", and "band", set to another item. That second item has two further properties, "name", set to "Jazz Band", and "size", set to "12".
An item can have multiple properties with the same name and different values.
This example describes an ice cream, with two flavors:
<div itemscope> <p>Flavors in my favorite ice cream:</p> <ul> <li itemprop="flavor">Lemon sorbet</li> <li itemprop="flavor">Apricot sorbet</li> </ul> </div>
This thus results in an item with two properties, both "flavor", having the values "Lemon sorbet" and "Apricot sorbet".
An element introducing a property can also introduce multiple properties at once, to avoid duplication when some of the properties have the same value.
Here we see an item with two properties, "favorite-color" and "favorite-fruit", both set to the value "orange":
<div itemscope> <span itemprop="favorite-color favorite-fruit">orange</span> </div>
It's important to note that there is no relationship between the microdata and the content of the document where the microdata is marked up.
There is no semantic difference, for instance, between the following two examples:
<figure> <img src="castle.jpeg"> <figcaption><span itemscope><span itemprop="name">The Castle</span></span> (1986)</figcaption> </figure>
<span itemscope><meta itemprop="name" content="The Castle"></span> <figure> <img src="castle.jpeg"> <figcaption>The Castle (1986)</figcaption> </figure>
Both have a figure with a caption, and both, completely unrelated to the figure, have an item with a name-value pair with the name "name" and the value "The Castle". The only difference is that if the user drags the caption out of the document, in the former case, the item will be included in the drag-and-drop data. In neither case is the image in any way associated with the item.
This section is non-normative.
The examples in the previous section show how information could be marked up on a page that doesn't expect its microdata to be re-used. Microdata is most useful, though, when it is used in contexts where other authors and readers are able to cooperate to make new uses of the markup.
For this purpose, it is necessary to give each item a type, such as "http://example.com/person", or "http://example.org/cat", or "http://band.example.net/". Types are identified as URLs.
The type for an item is given
as the value of an itemtype
attribute on the same element as the itemscope attribute.
Here, the item is "http://example.org/animals#cat":
<section itemscope itemtype="http://example.org/animals#cat"> <h1 itemprop="name">Hedral</h1> <p itemprop="desc">Hedral is a male american domestic shorthair, with a fluffy black fur with white paws and belly.</p> <img itemprop="img" src="hedral.jpeg" alt="" title="Hedral, age 18 months"> </section>
In this example the "http://example.org/animals#cat" item has three properties, a "name" ("Hedral"), a "desc" ("Hedral is..."), and an "img" ("hedral.jpeg").
An item can only have one type. The type gives the context for the properties, thus defining a vocabulary: a property named "class" given for an item with the type "http://census.example/person" might refer to the economic class of an individual, while a property named "class" given for an item with the type "http://example.com/school/teacher" might refer to the classroom a teacher has been assigned.
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.
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 |
This section is non-normative.
The microdata becomes even more useful when scripts can use it to expose information to the user, for example offering it in a form that can be used by other applications.
The document.getItems(typeNames) method provides access to the
top-level microdata items. It returns a
NodeList containing the items with the specified types,
or all types if no argument is specified.
Each item is represented in the
DOM by the element on which the relevant itemscope attribute is found. These
elements have their element.itemScope IDL attribute set to
true.
The type of items can be
obtained using the element.itemType IDL attribute on the
element with the itemscope
attribute.
This sample shows how the getItems() method can be used
to obtain a list of all the top-level microdata items of one type
given in the document:
var cats = document.getItems("http://example.com/feline");
Once an element representing an item has been obtained, its properties
can be extracted using the properties IDL attribute. This
attribute returns an HTMLPropertiesCollection, which can
be enumerated to go through each element that adds one or more
properties to the item. It can also be indexed by name, which will
return an object with a list of the elements that add properties
with that name.
Each element that adds a property also has a itemValue IDL attribute that returns
its value.
This sample gets the first item of type "http://example.net/user" and then pops up an alert using the "name" property from that item.
var user = document.getItems('http://example.net/user')[0];
alert('Hello ' + user.properties['name'][0].content + '!');
The HTMLPropertiesCollection object, when indexed by
name in this way, actually returns a PropertyNodeList
object with all the matching properties. The
PropertyNodeList object can be used to obtain all the
values at once using its values attribute, which
returns an array of all the values.
In an earlier example, a "http://example.org/animals#cat" item had two "http://example.com/color" values. This script looks up the first such item and then lists all its values.
var cat = document.getItems('http://example.org/animals#cat')[0];
var colors = cat.properties['http://example.com/color'].values;
var result;
if (colors.length == 0) {
result = 'Color unknown.';
} else if (colors.length == 1) {
result = 'Color: ' + colors[0];
} else {
result = 'Colors:';
for (var i = 0; i < colors.length; i += 1)
result += ' ' + colors[i];
}
It's also possible to get a list of all the property
names using the object's names IDL
attribute.
This example creates a big list with a nested list for each item on the page, each with of all the property names used in that item.
var outer = document.createElement('ul');
var items = document.getItems();
for (var item = 0; item < items.length; item += 1) {
var itemLi = document.createElement('li');
var inner = document.createElement('ul');
for (var name = 0; name < items[item].properties.names.length; name += 1) {
var propLi = document.createElement('li');
propLi.appendChild(document.createTextNode(items[item].properties.names[name]));
inner.appendChild(propLi);
}
itemLi.appendChild(inner);
outer.appendChild(itemLi);
}
document.body.appendChild(outer);
If faced with the following from an earlier example:
<section itemscope itemtype="http://example.org/animals#cat"> <h1 itemprop="name http://example.com/fn">Hedral</h1> <p itemprop="desc">Hedral is a male american domestic shorthair, with a fluffy <span itemprop="http://example.com/color">black</span> fur with <span itemprop="http://example.com/color">white</span> paws and belly.</p> <img itemprop="img" src="hedral.jpeg" alt="" title="Hedral, age 18 months"> </section>
...it would result in the following output:
(The duplicate occurrence of "http://example.com/color" is not included in the list.)
The microdata model consists of groups of name-value pairs known as items.
Each group is known as an item. Each item can have an item type, a global identifier (if the item type supports global identifiers for its items), and a list of name-value pairs. Each name in the name-value pair is known as a property, and each property has one or more values. Each value is either a string or itself a group of name-value pairs (an item).
An item is said to be a typed item when either it has an item type, or it is the value of a property of a typed item. The relevant type for a typed item is the item's item type, if it has one, or else is the relevant type of the item for which it is a property's value.
Every HTML element may have an
itemscope attribute
specified. The itemscope
attribute is a boolean attribute.
An element with the itemscope
attribute specified creates a new item, a group of name-value pairs.
Elements with an itemscope
attribute may have an itemtype attribute
specified, to give the item type of the item.
The itemtype attribute, if
specified, must have a value that is a valid URL that
is an absolute URL for which the string "http://www.w3.org/1999/xhtml/microdata#" is not a
prefix match.
The item type of an item is the value of its element's itemtype attribute, if it has one and
its value is not the empty string. If the itemtype attribute is missing or its
value is the empty string, the item is said to have no item
type.
The item type must be a type defined in an applicable specification.
Except if otherwise specified by that specification, the URL given as the item type should not be automatically dereferenced.
A specification could define that its item type can be derefenced to provide the user with help information, for example. In fact, vocabulary authors are encouraged to provide useful information at the given URL.
Item types are opaque identifiers, and user agents must not dereference unknown item types, or otherwise deconstruct them, in order to determine how to process items that use them.
The itemtype attribute must
not be specified on elements that do not have an itemscope attribute specified.
Elements with an itemscope
attribute and an itemtype
attribute that references a vocabulary that is defined to
support global identifiers for items may also have an
itemid attribute
specified, to give a global identifier for the item, so that it can be related to other
items on pages elsewhere on the
Web.
The itemid attribute, if
specified, must have a value that is a valid URL.
The global identifier of an item is the value of its element's itemid attribute, if it has one, resolved relative to the element on
which the attribute is specified. If the itemid attribute is missing or if
resolving it fails, it is said to have no global
identifier.
The itemid attribute must not be
specified on elements that do not have both an itemscope attribute and an itemtype attribute specified, and must
not be specified on elements with an itemscope attribute whose itemtype attribute specifies a
vocabulary that does not support global identifiers for
items, as defined by that vocabulary's specification.
Elements with an itemscope
attribute may have an itemref attribute specified,
to give a list of additional elements to crawl to find the
name-value pairs of the item.
The itemref attribute, if
specified, must have a value that is an unordered set of
unique space-separated tokens consisting of IDs of elements in the same home
subtree.
The itemref attribute must not
be specified on elements that do not have an itemscope attribute specified.
itemprop attributeEvery HTML element may have an
itemprop attribute specified, if
doing so adds a
property to one or more items (as defined below).
The itemprop attribute, if
specified, must have a value that is an unordered set of
unique space-separated tokens representing the names of the
name-value pairs that it adds. The attribute's value must have at
least one token.
Each token must be either:
http://www.w3.org/1999/xhtml/microdata#" is not a
prefix match, orWhen an element with an itemprop attribute adds a property to multiple items, the requirement above regarding
the tokens applies for each item
individually.
The property names of an element are the tokens that
the element's itemprop attribute
is found to contain when its value is split on spaces, with the order preserved but with
duplicates removed (leaving only the first occurrence of each
name).
Within an item, the properties are unordered with respect to each other, except for properties with the same name, which are ordered in the order they are given by the algorithm that defines the properties of an item.
In the following example, the "a" property has the values "1" and "2", in that order, but whether the "a" property comes before the "b" property or not is not important:
<div itemscope> <p itemprop="a">1</p> <p itemprop="a">2</p> <p itemprop="b">test</p> </div>
Thus, the following is equivalent:
<div itemscope> <p itemprop="b">test</p> <p itemprop="a">1</p> <p itemprop="a">2</p> </div>
As is the following:
<div itemscope> <p itemprop="a">1</p> <p itemprop="b">test</p> <p itemprop="a">2</p> </div>
And the following:
<div itemscope itemref="x"> <p itemprop="b">test</p> <p itemprop="a">2</p> </div> <div id="x"> <p itemprop="a">1</p> </div>
The property value of a
name-value pair added by an element with an itemprop attribute depends on the
element, as follows:
itemscope attributeThe value is the item created by the element.
meta elementThe value is the value of the element's content attribute, if any, or the empty
string if there is no such attribute.
audio, embed,
iframe, img, source, or
video elementThe 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.
a, area, or
link elementThe 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.
object elementThe 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.
time element with a datetime attributeThe value is the value of the element's datetime attribute.
The value is the element's
textContent.
The URL property elements are the a,
area, audio, embed,
iframe, img, link,
object, source, and video
elements.
If a property's value is an absolute URL, the property must be specified using a URL property element.
If a property's value
represents a date, time, or global date and time, the property
must be specified using the datetime attribute of a
time element.
To find the properties of an item defined by the element root, the user agent must try to crawl the properties of the element root, with an empty list as the value of memory: if this fails, then the properties of the item defined by the element root is an empty list; otherwise, it is the returned list.
To crawl the properties of an element root with a list memory, the user agent must run the following steps:
If root is in memory, then the algorithm fails; abort these steps.
Collect all the elements in the item root, and let results be the result.
If root is in results, then the algorithm fails; abort these steps.
If any elements are listed in results more than once, then the algorithm fails; abort these steps.
Remove any elements from results that do
not have an itemprop attribute
specified.
Let new memory be a new list consisting of the old list memory with the addition of root.
For each element in results that has an
itemscope attribute specified,
crawl the properties of the element, with new memory as the memory. If this fails, then this
instance of the algorithm fails as well; abort these steps. (If it
succeeds, the return value is discarded.)
Sort results in tree order.
Return results.
To collect all the elements in the item root, the user agent must run these steps:
Let results and pending be empty lists of elements.
Add all the children elements of root to pending.
If root has an itemref attribute, split the value of that itemref attribute on spaces. For
each resulting token ID, if there is an element
in the home subtree of root with
the ID ID, then
add the first such element to pending.
Loop: Remove an element from pending and let current be that element.
Add current to results.
If current does not have an itemscope attribute, then: add all
the child elements of current to pending.
End of loop: If pending is not empty, return to the step labeled loop.
Return results.
An item is a top-level microdata item if
its element does not have an itemprop attribute.
An item is a used microdata item if it is a top-level microdata item,
or if it has an itemprop
attribute and would be found
to be the property of an item that is itself a used microdata item.
A document must not contain any items that are not used microdata items.
A document must not contain any elements that have an itemprop attribute that would not be
found to be a property of any of the items in that document were their properties all to be
determined.
A document must not contain any items for which crawling the properties of the element, with an empty list as the value of memory, fails.
The algorithms in this section are especially inefficient, in the interests of keeping them easy to understand. Implementors are strongly encouraged to refactor and optimize them in their user agents.
In this example, a single license statement is applied to two
works, using itemref from the
items representing the works:
<!DOCTYPE HTML> <html> <head> <title>Photo gallery</title> </head> <body> <h1>My photos</h1> <figure itemscope itemtype="http://n.whatwg.org/work" itemref="licenses"> <img itemprop="work" src="images/house.jpeg" alt="A white house, boarded up, sits in a forest."> <figcaption itemprop="title">The house I found.</figcaption> </figure> <figure itemscope itemtype="http://n.whatwg.org/work" itemref="licenses"> <img itemprop="work" src="images/mailbox.jpeg" alt="Outside the house is a mailbox. It has a leaflet inside."> <figcaption itemprop="title">The mailbox.</figcaption> </figure> <footer> <p id="licenses">All images licensed under the <a itemprop="license" href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.</p> </footer> </body> </html>
The above results in two items with the type "http://n.whatwg.org/work", one with:
images/house.jpeg
http://www.opensource.org/licenses/mit-license.php
...and one with:
images/mailbox.jpeg
http://www.opensource.org/licenses/mit-license.php
In the following invalid example, the items are all empty,
because the itemref attribute on
the inner nested item indirectly references the same element twice
in the same item:
<!-- invalid example - do not copy -->
<div itemscope>
<span itemprop="example">This is <em>not</em> a property of the
<code>div</code> element.</span>
<p itemprop="demo" itemscope itemref="test thing"> <!-- "thing" is a descendant
of "test", which leads to it being included twice, which is invalid -->
<span itemprop="sample">This isn't part of anything either.</span>
</p>
</div>
<p id="test">
<span id="thing">(this element is referenced twice by the
<code>p</code> above, causing all the items that involve that
<code>itemref=""</code> attribute to act as if they had no
properties.)</span>
</p>
getItems( [ types ] )Returns a NodeList of the elements in the Document that create items, that are not part of other items, and that are of one of the types given in the argument, if any are listed.
The types argument is interpreted as a space-separated list of types.
propertiesIf the element has an itemscope attribute, returns an
HTMLPropertiesCollection object with all the element's
properties. Otherwise, an empty
HTMLPropertiesCollection object.
itemValue [ = value ]Returns the element's value.
Can be set, to change the element's value. Setting the value when the element has
no itemprop attribute or when
the element's value is an item
throws an INVALID_ACCESS_ERR exception.
The document.getItems(typeNames) method takes an optional
string that contains an unordered set of unique
space-separated tokens representing types. When called, the
method must return a live NodeList object
containing all the elements in the document, in tree
order, that are each top-level microdata items
with a type equal to one of the types
specified in that argument, having obtained the types by splitting the string on
spaces. If there are no tokens specified in the argument, or
if the argument is missing, then the method must return a
NodeList containing all the top-level microdata
items in the document.
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,
as if it was a regular string attribute, not a URL
string attribute. The itemId IDL attribute on
HTML elements must reflect the itemid content attribute. The itemProp IDL attribute on
HTML elements must reflect the itemprop content attribute. The itemRef IDL attribute on
HTML elements must reflect the itemref content attribute.
The properties IDL
attribute on HTML elements must return an
HTMLPropertiesCollection rooted at the
Document node, whose filter matches only elements that
have property names and are the properties of the item created by the element
on which the attribute was invoked, while that element is an item, and matches nothing the rest of
the time.
The itemValue IDL
attribute's behavior depends on the element, as follows:
itemprop attributeThe attribute must return null on getting and must throw an
INVALID_ACCESS_ERR exception on setting.
itemscope attributeThe attribute must return the element itself on getting and
must throw an INVALID_ACCESS_ERR exception on
setting.
meta elementThe attribute must act as it would if it was reflecting the element's content content
attribute.
audio, embed,
iframe, img, source, or
video elementThe attribute must act as it would if it was reflecting the element's src content attribute.
a, area, or
link elementThe attribute must act as it would if it was reflecting the element's href content attribute.
object elementThe attribute must act as it would if it was reflecting the element's data content attribute.
time element with a datetime attributeThe attribute must act as it would if it was reflecting the element's datetime content
attribute.
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]));
An item with the item type http://microformats.org/profile/hcard
represents a person's or organization's contact information.
This vocabulary supports global identifiers for items.
The following are the type's defined property names. They are based on the vocabulary defined in the vCard specification and its extensions, where more information on how to interpret the values can be found. [RFC2426] [RFC4770]
fnGives 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.
nGives the structured name of the person or organization.
The value must be
an item with zero or more of
each of the family-name, given-name, additional-name, honorific-prefix, and
honorific-suffix
properties.
Except when one of the conditions given below applies, exactly
one property with the name n must
be present within each item with
the type http://microformats.org/profile/hcard.
If one of the following conditions does apply, then the n may be omitted:
vcard has both an fn property and an org property, and they both have
values that are
strings and those strings are identical when compared in a
case-sensitive manner.The contact information must be for an organization.
vcard has an fn property whose value consists of a string
with zero space
characters.vcard has an fn property whose value consists of a string
with exactly one sequence of space
characters, which occurs neither at the immediate start
nor the immediate end of the string.The value of the
fn property must be a name in
one of the following forms:
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.
nicknameGives 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.
photoGives 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.
bdayGives 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.
adrGives 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.
labelGives 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.
telGives 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.
emailGives the e-mail address of the person or organization.
The value must be
either text or an item with zero
or more type properties
and exactly one value
property.
If no type properties
are present within an item that
forms the value of an
email property of an item with the type http://microformats.org/profile/hcard, or if the value of such an email property is text, then the
e-mail type string internet is
implied.
Any number of properties with the name email may be present within each
item with the type http://microformats.org/profile/hcard.
type (inside email)Gives the type of e-mail address.
The value must be text that, when compared in a case-sensitive manner, is equal to one of the e-mail type strings.
Within each item with the
type http://microformats.org/profile/hcard, there must be no more
than one email property item with a type property whose value is
pref.
Any number of properties with the name type may be present within the
item that forms the value of an email property of an item with the type http://microformats.org/profile/hcard, but within each such email property item there must only be one type property per distinct
value.
value (inside email)Gives the actual e-mail address of the person or organization.
The value must be text.
Exactly one property with the name value must be present within
the item that forms the value of an email property of an item with the type http://microformats.org/profile/hcard.
mailerGives the name of the e-mail software used by the person or organization.
The value must be text.
Any number of properties with the name mailer may be present within each
item with the type http://microformats.org/profile/hcard.
tzGives the time zone of the person or organization.
The value must be text and must match the following syntax:
Any number of properties with the name tz may be present within each item with the type http://microformats.org/profile/hcard.
geoGives the geographical position of the person or organization.
The value must be text and must match the following syntax:
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.
titleGives 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.
roleGives 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.
logoGives 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.
agentGives 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.
orgGives 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.
categoriesGives 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.
noteGives 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.
revGives the revision date and time of the contact information.
The value must be text that is a valid global date and time string.
The value distinguishes the current revision of the information for other renditions of the information.
Any number of properties with the name rev may be present within each item with the type http://microformats.org/profile/hcard.
sort-stringGives the string to be used for sorting the person or organization.
The value must be text.
Any number of properties with the name sort-string may be present
within each item with the type
http://microformats.org/profile/hcard.
soundGives 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.
urlGives 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.
classGives the access classification of the information regarding the person or organization.
The value must be text with one of the following values:
publicprivateconfidentialThis is merely advisory and cannot be considered a confidentiality measure.
Any number of properties with the name class may be present
within each item with the type
http://microformats.org/profile/hcard.
imppGives a URL for instant messaging and presence protocol communications with the person or organization.
The value must be
either an absolute URL or an item with zero or more type properties and exactly one
value property.
If no type properties
are present within an item that
forms the value of an
impp property of an item with the type http://microformats.org/profile/hcard, or if the value of such an impp property is an absolute
URL, then no IMPP type strings are
implied.
Any number of properties with the name impp may be present within each
item with the type http://microformats.org/profile/hcard.
type (inside impp)Gives the intended use of the IMPP URL.
The value must be text that, when compared in a case-sensitive manner, is equal to one of the IMPP type strings.
Within each item with the
type http://microformats.org/profile/hcard, there must be no more
than one impp property item with a type property whose value is
pref.
Any number of properties with the name type may be present within the
item that forms the value of an impp property of an item with the type http://microformats.org/profile/hcard, but within each such impp property item there must only be one type property per distinct
value.
value (inside impp)Gives the actual URL for instant messaging and presence protocol communications with the person or organization.
The value must be an absolute URL.
Exactly one property with the name value must be present within
the item that forms the value of an impp property of an item with the type http://microformats.org/profile/hcard.
The address type strings are:
domIndicates a domestic delivery address.
intlIndicates an international delivery address.
postalIndicates a postal delivery address.
parcelIndicates a parcel delivery address.
homeIndicates a residential delivery address.
workIndicates a delivery address for a place of work.
prefIndicates the preferred delivery address when multiple addresses are specified.
The telephone type strings are:
homeIndicates a residential number.
msgIndicates a telephone number with voice messaging support.
workIndicates a telephone number for a place of work.
voiceIndicates a voice telephone number.
faxIndicates a facsimile telephone number.
cellIndicates a cellular telephone number.
videoIndicates a video conferencing telephone number.
pagerIndicates a paging device telephone number.
bbsIndicates a bulletin board system telephone number.
modemIndicates a MODEM-connected telephone number.
carIndicates a car-phone telephone number.
isdnIndicates an ISDN service telephone number.
pcsIndicates a personal communication services telephone number.
prefIndicates the preferred telephone number when multiple telephone numbers are specified.
The e-mail type strings are:
internetIndicates an Internet e-mail address.
x400Indicates a X.400 addressing type.
prefIndicates the preferred e-mail address when multiple e-mail addresses are specified.
The IMPP type strings are:
personalbusinessIndicates the type of communication for which this IMPP URL is appropriate.
homeworkmobileIndicates the location of a device associated with this IMPP URL.
prefIndicates the preferred address when multiple IMPP URLs are specified.
Given a list of nodes nodes in a
Document, a user agent must run the following algorithm
to extract any vCard data
represented by those nodes (only the first vCard is
returned):
If none of the nodes in nodes are items with the item type
http://microformats.org/profile/hcard, then
there is no vCard. Abort the algorithm, returning nothing.
Let node be the first node in nodes that is an item with the item type
http://microformats.org/profile/hcard.
Let output be an empty string.
Add a vCard line with the type "BEGIN" and the value "VCARD"
to output.
Add a vCard line with the type "PROFILE" and the value "VCARD" to output.
Add a vCard line with the type "VERSION" and the value "3.0"
to output.
Add a vCard line with the type "SOURCE" and the result of escaping the vCard
text string that is the document's current
address as the value to output.
If the title element is not null,
add a vCard line with the type "NAME" and with the result of escaping the
vCard text string obtained from the textContent
of the title element as the value to output.
If node has a global
identifier, add a vCard line with the type
"UID" and with the result of escaping
the vCard text string of that global identifier
as the value to output.
Let first-n, first-org, and first-fn be null.
For each element element that is a property of the item node: for each name name in element's property names, run the following substeps:
Let parameters be an empty set of name-value pairs.
Run the appropriate set of substeps from the following list. The steps will set a variable value, which is used in the next step.
nIf first-n is null, let first-n be element.
Let value be the empty string.
Append to value the result of
collecting the first vCard subproperty named
family-name in
subitem.
Append to value the result of
collecting the first vCard subproperty named
given-name in subitem.
Append to value the result of
collecting the first vCard subproperty named
additional-name in
subitem.
Append to value the result of
collecting the first vCard subproperty named
honorific-prefix
in subitem.
Append to value the result of
collecting the first vCard subproperty named
honorific-suffix
in subitem.
adrLet value be the empty string.
Append to value the result of
collecting vCard subproperties named post-office-box
in subitem.
Append to value the result of
collecting vCard subproperties named extended-address
in subitem.
Append to value the result of
collecting vCard subproperties named street-address in
subitem.
Append to value the result of
collecting the first vCard subproperty named
locality in subitem.
Append to value the result of
collecting the first vCard subproperty named
region in subitem.
Append to value the result of
collecting the first vCard subproperty named
postal-code in
subitem.
Append to value the result of
collecting the first vCard subproperty named
country-name
in subitem.
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.
orgIf first-org is null, let first-org be element.
Let value be the empty string.
Append to value the result of
collecting the first vCard subproperty named
organization-name
in subitem.
For each property named organization-unit
in subitem, run the following steps:
If the value of the property is an item, then skip this property.
Append a U+003B SEMICOLON character (;) to value.
Append the result of escaping the vCard text string given by the value of the property to value.
http://microformats.org/profile/hcard
and name is agentLet value be the result of escaping the vCard text string obtained from extracting a vCard from the element that represents subitem.
Add a parameter named "VALUE"
whose value is "VCARD" to parameters.
Let value be the result of
collecting the first vCard subproperty named
value in subitem.
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 name is fn and first-fn is null, let first-fn be element.
Otherwise, if name is org and first-org is null, let first-org be element.
Let value be the property's value.
If element is one of the URL
property elements, add a parameter with the name "VALUE" and the value "URI" to parameters.
Otherwise, if element is a
time element and the value is
a valid date string, add a parameter with the name
"VALUE" and the value "DATE" to parameters.
Otherwise, if element is a
time element and the value is
a valid global date and time string, add a
parameter with the name "VALUE" and the
value "DATE-TIME" to parameters.
Prefix every U+005C REVERSE SOLIDUS character (\) in value with another U+005C REVERSE SOLIDUS character (\).
Prefix every U+002C COMMA character (,) in value with a U+005C REVERSE SOLIDUS character (\).
Unless name is geo, prefix every U+003B SEMICOLON
character (;) in value with a U+005C
REVERSE SOLIDUS character (\).
Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Replace every remaining U+000D CARRIAGE RETURN (CR) or U+000A LINE FEED (LF) character in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Add a vCard line with the type name, the parameters parameters, and the value value to output.
If first-n is null, then run the following substeps:
If first-fn is also null, then skip the remainder of these substeps.
If first-fn has a value that is an item, then skip the remainder of these substeps.
If first-org is not null, and the
value of first-org is not an item and is equal to first-fn, then add a vCard line with
the type "N" whose value is four U+003B
SEMICOLON characters (";;;;") to output. Then, skip the remainder of these
substeps.
If the space characters in first-fn, if any, are not all contiguous, then skip the remainder of these substeps.
Split first-fn on spaces, and let part one be the first resulting token, and part two be the second, if any, or the empty string if there is no second token. (There cannot be three, given the previous step.)
If the last character of part one is a
U+002C COMMA character (,), then remove that character from part one and add a vCard line with
the type "N" whose value is the
concatenation of the following strings:
Then, skip the remainder of these substeps.
If part two is two Unicode code-points
long and its second character is a U+002E FULL STOP character
(.), then add a vCard line with the type "N" whose value is the concatenation of the
following strings:
Then, skip the remainder of these substeps.
If part two is one Unicode code-point
long, then add a vCard line with the type "N" whose value is the concatenation of the
following strings:
Then, skip the remainder of these substeps.
Add a vCard line with the type "N" whose value is the concatenation of the
following strings:
Add a vCard line with the type "END" and the value "VCARD"
to output.
When the above algorithm says that the user agent is to add a vCard line consisting of a type type, optionally some parameters, and a value value to a string output, it must run the following steps:
Let line be an empty string.
Append type, converted to ASCII uppercase, to line.
If there are any parameters, then for each parameter, in the order that they were added, run these substeps:
Append a U+003B SEMICOLON character (;) to line.
Append the parameter's name to line.
Append a U+003D EQUALS SIGN character (=) to line.
Append the parameter's value to line.
Append a U+003A COLON character (:) to line.
Append value to line.
Let maximum length be 75.
If and while line is longer than maximum length Unicode code points long, run the following substeps:
Append the first maximum length Unicode code points of line to output.
Remove the first maximum length Unicode code points from line.
Append a U+000D CARRIAGE RETURN character (CR) to output.
Append a U+000A LINE FEED character (LF) to output.
Append a U+0020 SPACE character to output.
Let maximum length be 74.
Append (what remains of) line to output.
Append a U+000D CARRIAGE RETURN character (CR) to output.
Append a U+000A LINE FEED character (LF) to output.
When the steps above require the user agent to obtain the result of collecting vCard subproperties named subname in subitem, the user agent must run the following steps:
Let value be the empty string.
For each property named subname in the item subitem, run the following substeps:
If the value of the property is itself an item, then skip this property.
If this is not the first property named subname in subitem (ignoring any that were skipped by the previous step), then append a U+002C COMMA character (,) to value.
Append the result of escaping the vCard text string given by the value of the property to value.
Return value.
When the steps above require the user agent to obtain the result of collecting the first vCard subproperty named subname in subitem, the user agent must run the following steps:
If there are no properties named subname in subitem, then abort these substeps, returning the empty string.
If the value of the first property named subname in subitem is an item, then abort these substeps, returning the empty string.
Return the result of escaping the vCard text string given by the value of the first property named subname in subitem.
When the above algorithms say the user agent is to escape the vCard text string value, the user agent must use the following steps:
Prefix every U+005C REVERSE SOLIDUS character (\) in value with another U+005C REVERSE SOLIDUS character (\).
Prefix every U+002C COMMA character (,) in value with a U+005C REVERSE SOLIDUS character (\).
Prefix every U+003B SEMICOLON character (;) in value with a U+005C REVERSE SOLIDUS character (\).
Replace every U+000D CARRIAGE RETURN U+000A LINE FEED character pair (CRLF) in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Replace every remaining U+000D CARRIAGE RETURN (CR) or U+000A LINE FEED (LF) character in value with a U+005C REVERSE SOLIDUS character (\) followed by a U+006E LATIN SMALL LETTER N character (n).
Return the mutated value.
This algorithm can generate invalid vCard output, if
the input does not conform to the rules described for the http://microformats.org/profile/hcard
item type and defined property names.
This section is non-normative.
Here is a long example vCard for a fictional character called "Jack Bauer":
<section id="jack" itemscope itemtype="http://microformats.org/profile/hcard"> <h1 itemprop="fn">Jack Bauer</h1> <img itemprop="photo" alt="" src="jack-bauer.jpg"> <p itemprop="org" itemscope> <span itemprop="organization-name">Counter-Terrorist Unit</span> (<span itemprop="organization-unit">Los Angeles Division</span>) </p> <p> <span itemprop="adr" itemscope> <span itemprop="street-address">10201 W. Pico Blvd.</span><br> <span itemprop="locality">Los Angeles</span>, <span itemprop="region">CA</span> <span itemprop="postal-code">90064</span><br> <span itemprop="country-name">United States</span><br> </span> <span itemprop="geo">34.052339;-118.410623</span> </p> <h2>Assorted Contact Methods</h2> <ul> <li itemprop="tel" itemscope> <span itemprop="value">+1 (310) 597 3781</span> <span itemprop="type">work</span> <meta itemprop="type" content="pref"> </li> <li><a itemprop="url" href="http://en.wikipedia.org/wiki/Jack_Bauer">I'm on Wikipedia</a> so you can leave a message on my user talk page.</li> <li><a itemprop="url" href="http://www.jackbauerfacts.com/">Jack Bauer Facts</a></li> <li itemprop="email"><a href="mailto:j.bauer@la.ctu.gov.invalid">j.bauer@la.ctu.gov.invalid</a></li> <li itemprop="tel" itemscope> <span itemprop="value">+1 (310) 555 3781</span> <span> <meta itemprop="type" content="cell">mobile phone</span> </li> </ul> <p itemprop="note">If I'm out in the field, you may be better off contacting <span itemprop="agent" itemscope itemtype="http://microformats.org/profile/hcard"><a itemprop="email" href="mailto:c.obrian@la.ctu.gov.invalid"><span itemprop="fn">Chloe O'Brian</span></a></span> if it's about work, or ask <span itemprop="agent">Tony Almeida</span> if you're interested in the CTU five-a-side football team we're trying to get going.</p> <ins datetime="2008-07-20T21:00:00+01:00"> <span itemprop="rev" itemscope> <meta itemprop="type" content="date-time"> <meta itemprop="value" content="2008-07-20T21:00:00+01:00"> </span> <p itemprop="tel" itemscope><strong>Update!</strong> My new <span itemprop="type">home</span> phone number is <span itemprop="value">01632 960 123</span>.</p> </ins> </section>
The odd line wrapping is needed because newlines are meaningful in microdata: newlines would be preserved in a conversion to, for example, the vCard format.
This example shows a site's contact details (using the
address element) containing an address with two street
components:
<address itemscope itemtype="http://microformats.org/profile/hcard"> <strong itemprop="fn">Alfred Person</strong> <br> <span itemprop="adr" itemscope> <span itemprop="street-address">1600 Amphitheatre Parkway</span> <br> <span itemprop="street-address">Building 43, Second Floor</span> <br> <span itemprop="locality">Mountain View</span>, <span itemprop="region">CA</span> <span itemprop="postal-code">94043</span> </span> </address>
The vCard vocabulary can be used to just mark up people's names:
<span itemscope itemtype="http://microformats.org/profile/hcard" ><span itemprop=fn>George Washington</span></span>
This creates a single item with a single name-value pair, with the name "fn" and the value "George Washington". This is defined to map to the following vCard:
BEGIN:VCARD PROFILE:VCARD VERSION:3.0 SOURCE:document's address FN:George Washington N:Washington;George;;; END:VCARD
An item with the item type http://microformats.org/profile/hcalendar#vevent
represents an event.
This vocabulary supports global identifiers for items.
The following are the type's defined property names. They are based on the vocabulary defined in the iCalendar specification, where more information on how to interpret the values can be found. [RFC2445]
Only the parts of the iCalendar vocabulary relating to events are used here; this vocabulary cannot express a complete iCalendar instance.
attachGives 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.
categoriesGives 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.
classGives the access classification of the information regarding the event.
The value must be text with one of the following values:
publicprivateconfidentialThis 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.
commentGives 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.
descriptionGives 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.
geoGives the geographical position of the event.
The value must be text and must match the following syntax:
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.
locationGives 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.
resourcesGives 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.
statusGives the confirmation status of the event.
The value must be text with one of the following values:
tentativeconfirmedcancelledA single property with the name status may be present within each
item with the type http://microformats.org/profile/hcalendar#vevent.
summaryGives a short summary of the event.
The value must be text.
User agents should replace U+000A LINE FEED (LF) characters in the value by U+0020 SPACE characters when using the value.
A single property with the name summary may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent.
dtendGives 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.
dtstartGives 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.
durationGives the date and time at which the event starts.
The value must be text that is a valid vevent duration string.
The duration represented is the sum of all the durations represented by integers in the value.
A single property with the name duration may be present within
each item with the type http://microformats.org/profile/hcalendar#vevent,
so long as that http://microformats.org/profile/hcalendar#vevent
does not have a property with the name dtend.
transpGives 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:
opaquetransparentA single property with the name transp may be present within each
item with the type http://microformats.org/profile/hcalendar#vevent.
contactGives 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.
urlGives 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.
exdateGives 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.
exruleGives 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.
rdateGives 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.
rruleGives 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.
createdGives 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-modifiedGives 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.
sequenceGives 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.