This is a snapshot of an early working draft and has therefore been superseded by the HTML standard.

This document will not be further updated.

HTML 5

Call For Comments — 27 October 2007

3.7. Document metadata

Document metadata is represented by metadata elements in the document's head element.

3.7.1. The head element

Contexts in which this element may be used:
As the first element in an html element.
Content model:
In any order unless otherwise specified: optionally one meta element with a charset attribute, exactly one title element, optionally one base element, and zero or more other metadata elements (in particular, link, meta, style, and script).
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.

The head element collects the document's metadata.

3.7.2. The title element

Metadata element.

Contexts in which this element may be used:
In a head element containing no other title elements.
Content model:
Text (for details, see prose).
Element-specific attributes:
None.
DOM interface:
No difference from HTMLElement.

The title element represents the document's title or name. Authors should use titles that identify their documents even when they are used out of context, for example in a user's history or bookmarks, or in search results. The document's title is often different from its first header, since the first header does not have to stand alone when taken out of context.

Here are some examples of appropriate titles, contrasted with the top-level headers that might be used on those same pages.

  <title>Introduction to The Mating Rituals of Bees</title>
    ...
  <h1>Introduction</h1>
  <p>This companion guide to the highly successful
  <cite>Introduction to Medieval Bee-Keeping</cite> book is...

The next page might be a part of the same site. Note how the title describes the subject matter unambiguously, while the first header assumes the reader knowns what the context is and therefore won't wonder if the dances are Salsa or Waltz:

  <title>Dances used during bee mating rituals</title>
    ...
  <h1>The Dances</h1>

The title element must not contain any elements.

The string to use as the document's title is given by the document.title DOM attribute. User agents should use the document's title when referring to the document in their user interface.

3.7.3. The base element

Metadata element.

Contexts in which this element may be used:
In a head element, after the meta element with the charset attribute, if any, but before any other elements.
Content model:
Empty.
Element-specific attributes:
href
target
DOM interface:
interface HTMLBaseElement : HTMLElement {
           attribute DOMString href;
           attribute DOMString target;
};

The base element allows authors to specify the document's base URI for the purposes of resolving relative URIs, and the name of the default browsing context for the purposes of following hyperlinks.

There must be no more than one base element per document.

The href content attribute, if specified, must contain a URI (or IRI).

A base element, if it has an href attribute, must come before any other elements in the tree that have attributes with URIs.

User agents must use the value of the href attribute of the first base element that is both a child of the head element and has an href attribute, if there is such an element, as the document entity's base URI for the purposes of section 5.1.1 of RFC 3986 ("Establishing a Base URI": "Base URI Embedded in Content"). This base URI from RFC 3986 is referred to by the algorithm given in XML Base, which is a normative part of this specification. [RFC3986]

If the base URI given by this attribute is a relative URI, it must be resolved relative to the higher-level base URIs (i.e. the base URI from the encapsulating entity or the URI used to retrieve the entity) to obtain an absolute base URI. All xml:base attributes must be ignored when resolving relative URIs in this href attribute.

If there are multiple base elements with href attributes, all but the first are ignored.

The target attribute, if specified, must contain a valid browsing context name. User agents use this name when following hyperlinks.

A base element, if it has a target attribute, must come before any elements in the tree that represent hyperlinks.

The href and target DOM attributes must reflect the content attributes of the same name.

Metadata element.

Contexts in which this element may be used:
Where metadata elements are expected.
In a noscript element that is a child of a head element.
Content model:
Empty.
Element-specific attributes:
href (required)
rel (required)
media
hreflang
type
Also, the title attribute has special semantics on this element.
DOM interface:
interface HTMLLinkElement : HTMLElement {
           attribute boolean disabled;
           attribute DOMString href;
           attribute DOMString rel;
  readonly attribute DOMTokenList relList;
           attribute DOMString media;
           attribute DOMString hreflang;
           attribute DOMString type;
};

The LinkStyle interface must also be implemented by this element, the styling processing model defines how. [CSSOM]

The link element allows authors to indicate explicit relationships between their document and other resources.

The destination of the link is given by the href attribute, which must be present and must contain a URI (or IRI). If the href attribute is absent, then the element does not define a link.

The type of link indicated (the relationship) is given by the value of the rel attribute, which must be present, and must have a value that is an unordered set of space-separated tokens. The allowed values and their meanings are defined in a later section. If the rel attribute is absent, or if the value used is not allowed according to the definitions in this specification, then the element does not define a link.

Two categories of links can be created using the link element. Links to external resources are links to resources that are to be used to augment the current document, and hyperlink links are links to other documents. The link types section defines whether a particular link type is an external resource or a hyperlink. One element can create multiple links (of which some might be external resource links and some might be hyperlinks). User agents should process the links on a per-link basis, not a per-element basis.

The exact behaviour for links to external resources depends on the exact relationship, as defined for the relevant link type. Some of the attributes control whether or not the external resource is to be applied (as defined below). For external resources that are represented in the DOM (for example, style sheets), the DOM representation must be made available even if the resource is not applied. (However, user agents may opt to only fetch such resources when they are needed, instead of pro-actively downloading all the external resources that are not applied.)

Interactive user agents should provide users with a means to follow the hyperlinks created using the link element, somewhere within their user interface. The exact interface is not defined by this specification, but it should include the following information (obtained from the element's attributes, again as defined below), in some form or another (possibly simplified), for each hyperlink created with each link element in the document:

User agents may also include other information, such as the type of the resource (as given by the type attribute).

The media attribute says which media the resource applies to. The value must be a valid media query. [MQ]

If the link is a hyperlink then the media attribute is purely advisory, and describes for which media the document in question was designed.

However, if the link is an external resource link, then the media attribute is prescriptive. The user agent must only apply the external resource to views while their state match the listed media.

The default, if the media attribute is omitted, is all, meaning that by default links apply to all media.

The hreflang attribute on the link element has the same semantics as the hreflang attribute on hyperlink elements.

The type attribute gives the MIME type of the linked resource. It is purely advisory. The value must be a valid MIME type, optionally with parameters. [RFC2046]

For external resource links, user agents may use the type given in this attribute to decide whether or not to consider using the resource at all. If the UA does not support the given MIME type for the given link relationship, then the UA may opt not to download and apply the resource.

User agents must not consider the type attribute authoritative — upon fetching the resource, user agents must not use metadata included in the link to the resource to determine its type.

If the attribute is omitted, then the UA must fetch the resource to determine its type and thus determine if it supports (and can apply) that external resource.

If a document contains three style sheet links labelled as follows:

<link rel="stylesheet" href="A" type="text/css">
<link rel="stylesheet" href="B" type="text/plain">
<link rel="stylesheet" href="C">

...then a compliant UA that supported only CSS style sheets would fetch the A and C files, and skip the B file (since text/plain is not the MIME type for CSS style sheets). For these two files, it would then check the actual types returned by the UA. For those that are sent as text/css, it would apply the styles, but for those labelled as text/plain, or any other type, it would not.

The title attribute gives the title of the link. With one exception, it is purely advisory. The value is text. The exception is for style sheet links, where the title attribute defines alternative style sheet sets.

The title attribute on link elements differs from the global title attribute of most other elements in that a link without a title does not inherit the title of the parent element: it merely has no title.

Some versions of HTTP defined a Link: header, to be processed like a series of link elements. When processing links, those must be taken into consideration as well. For the purposes of ordering, links defined by HTTP headers must be assumed to come before any links in the document, in the order that they were given in the HTTP entity header. Relative URIs in these headers must be resolved according to the rules given in HTTP, not relative to base URIs set by the document (e.g. using a base element or xml:base attributes). [RFC2616] [RFC2068]

The DOM attributes href, rel, media, hreflang, and type each must reflect the respective content attributes of the same name.

The DOM attribute relList must reflect the rel content attribute.

The DOM attribute disabled only applies to style sheet links. When the link element defines a style sheet link, then the disabled attribute behaves as defined for the alternative style sheets DOM. For all other link elements it always return false and does nothing on setting.

3.7.5. The meta element

Metadata element.

Contexts in which this element may be used:
If the charset attribute is present: as the first element in a head element.
If the http-equiv attribute is present: in a head element.
If the http-equiv attribute is present: in a noscript element that is a child of a head element.
If the name attribute is present: where metadata elements are expected.
Content model:
Empty.
Element-specific attributes:
name
http-equiv
content
charset (HTML only)
DOM interface:
interface HTMLMetaElement : HTMLElement {
           attribute DOMString content;
           attribute DOMString name;
           attribute DOMString httpEquiv;
};

The meta element represents various kinds of metadata that cannot be expressed using the title, base, link, style, and script elements.

The meta element can represent document-level metadata with the name attribute, pragma directives with the http-equiv attribute, and the file's character encoding declaration when an HTML document is serialised to string form (e.g. for transmission over the network or for disk storage) with the charset attribute.

Exactly one of the name, http-equiv, and charset attributes must be specified.

If either name or http-equiv is specified, then the content attribute must also be specified. Otherwise, it must be omitted.

The charset attribute may only be specified in HTML documents, it must not be used in XML documents. If the charset attribute is specified, the element must be the first element in the head element of the file.

The content attribute gives the value of the document metadata or pragma directive when the element is used for those purposes. The allowed values depend on the exact context, as described in subsequent sections of this specification.

If a meta element has a name attribute, it sets document metadata. Document metadata is expressed in terms of name/value pairs, the name attribute on the meta element giving the name, and the content attribute on the same element giving the value. The name specifies what aspect of metadata is being set; valid names and the meaning of their values are described in the following sections. If a meta element has no content attribute, then the value part of the metadata name/value pair is the empty string.

If a meta element has the http-equiv attribute specified, it must be either in a head element or in a noscript element that itself is in a head element. If a meta element does not have the http-equiv attribute specified, it must be in a head element.

The DOM attributes name and content must reflect the respective content attributes of the same name. The DOM attribute httpEquiv must reflect the content attribute http-equiv.

3.7.5.1. Standard metadata names

This specification defines a few names for the name attribute of the meta element.

generator

The value must be a free-form string that identifies the software used to generate the document. This value must not be used on hand-authored pages. WYSIWYG editors have additional constraints on the value used with this metadata name.

dns

The value must be an ordered set of unique space-separated tokens, each word of which is a host name. The list allows authors to provide a list of host names that the user is expected to subsequently need. User agents may, according to user preferences and prevailing network conditions, pre-emptively resolve the given DNS names (extracting the names from the value using the rules for splitting a string on spaces), thus precaching the DNS information for those hosts and potentially reducing the time between page loads for subsequent user interactions. Higher priority should be given to host names given earlier in the list.

3.7.5.2. Other metadata names

Extensions to the predefined set of metadata names may be registered in the WHATWG Wiki MetaExtensions page.

Anyone is free to edit the WHATWG Wiki MetaExtensions page at any time to add a type. These new names must be specified with the following information:

Keyword

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

Brief description

A short description of what the metadata name's meaning is, including the format the value is required to be in.

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

A list of other names that have exactly the same processing requirements. Authors should not use the names defined to be synonyms, they are only intended to allow user agents to support legacy content.

Status

One of the following:

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

If a metadata name is added with the "proposal" status and found to be redundant with existing values, it should be removed and listed as a synonym for the existing value.

Conformance checkers must use the information given on the WHATWG Wiki MetaExtensions page to establish if a value not explicitly defined in this specification is allowed or not. 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 "proposal" status.

This specification does not define how new values will get approved. It is expected that the Wiki will have a community that addresses this.

Metadata names whose values are to be URIs must not be proposed or accepted. Links must be represented using the link element, not the meta element.

3.7.5.3. Pragma directives

When the http-equiv attribute is specified on a meta element, the element is a pragma directive.

The http-equiv attribute is an enumerated attribute. The following table lists the keywords defined for this attribute. The states given in the first cell of the the rows with keywords give the states to which those keywords map.

State Keywords
Refresh refresh
Default style default-style

When a meta element is inserted into the document, if its http-equiv attribute is present and represents one of the above states, then the user agent must run the algorithm appropriate for that state, as described in the following list:

Refresh state
  1. If another meta element in the Refresh state has already been successfully processed (i.e. when it was inserted the user agent processed it and reached the last step of this list of steps), then abort these steps.

  2. If the meta element has no content attribute, or if that attribute's value is the empty string, then abort these steps.

  3. Let input be the value of the element's content attribute.

  4. Let position point at the first character of input.

  5. Skip whitespace.

  6. Collect a sequence of characters in the range U+0030 DIGIT ZERO to U+0039 DIGIT NINE, and parse the resulting string using the rules for parsing non-negative integers. If the sequence of characters collected is the empty string, then no number will have been parsed; abort these steps. Otherwise, let time be the parsed number.

  7. Collect a sequence of characters in the range U+0030 DIGIT ZERO to U+0039 DIGIT NINE and U+002E FULL STOP ("."). Ignore any collected characters.

  8. Skip whitespace.

  9. Let url be the address of the current page.

  10. If the character in input pointed to by position is a U+003B SEMICOLON (";"), then advance position to the next character. Otherwise, jump to the last step.

  11. Skip whitespace.

  12. If the character in input pointed to by position is one of U+0055 LATIN CAPITAL LETTER U or U+0075 LATIN SMALL LETTER U, then advance position to the next character. Otherwise, jump to the last step.

  13. If the character in input pointed to by position is one of U+0052 LATIN CAPITAL LETTER R or U+0072 LATIN SMALL LETTER R, then advance position to the next character. Otherwise, jump to the last step.

  14. If the character in input pointed to by position is one of U+004C LATIN CAPITAL LETTER L or U+006C LATIN SMALL LETTER L, then advance position to the next character. Otherwise, jump to the last step.

  15. Skip whitespace.

  16. If the character in input pointed to by position is a U+003D EQUALS SIGN ("="), then advance position to the next character. Otherwise, jump to the last step.

  17. Skip whitespace.

  18. Let url be equal to the substring of input from the character at position to the end of the string.

  19. Strip any trailing space characters from the end of url.

  20. Strip any U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), and U+000D CARRIAGE RETURN (CR) characters from url.

  21. Resolve the url value to an absolute URI using the base URI of the meta element.

  22. Set a timer so that in time seconds, if the user has not canceled the redirect, the user agent navigates to url, with replacement enabled.

For meta elements in the Refresh state, the content attribute must have a value consisting either of:

In the former case, the integer represents a number of seconds before the page is to be reloaded; in the latter case the integer represents a number of seconds before the page is to be replaced by the page at the given URI.

Default style state
  1. ...
3.7.5.4. Specifying the document's character encoding

The meta element may also be used to provide UAs with character encoding information for HTML files, by setting the charset attribute to the name of a character encoding. This is called a character encoding declaration.

The following restrictions apply to character encoding declarations:

If the document does not start with a BOM, and if its encoding is not explicitly given by Content-Type metadata, then the character encoding used must be a superset of US-ASCII (specifically, ANSI_X3.4-1968) for bytes in the range 0x09 - 0x0D, 0x20, 0x21, 0x22, 0x26, 0x27, 0x2C - 0x3F, 0x41 - 0x5A, and 0x61 - 0x7A , and, in addition, if that encoding isn't US-ASCII itself, then the encoding must be specified using a meta element with a charset attribute.

Authors should not use JIS_X0212-1990, x-JIS0208, and encodings based on EBCDIC. Authors should not use UTF-32. Authors must not use the CESU-8, UTF-7, BOCU-1 and SCSU encodings. [CESU8] [UTF7] [BOCU1] [SCSU]

Authors are encouraged to use UTF-8. Conformance checkers may advise against authors using legacy encodings.

In XHTML, the XML declaration should be used for inline character encoding information, if necessary.

3.7.6. The style element

Metadata element.

Contexts in which this element may be used:
If the scoped attribute is absent: where metadata elements are expected.
If the scoped attribute is absent: in a noscript element that is a child of a head element.
If the scoped attribute is present: at the start of article, aside, div, and section elements.
Content model:
Depends on the value of the type attribute.
Element-specific attributes:
media
type
scoped
Also, the title attribute has special semantics on this element.
DOM interface:
interface HTMLStyleElement : HTMLElement {
           attribute boolean disabled;
           attribute DOMString media;
           attribute DOMString type;
           attribute boolean scoped;
};

The LinkStyle interface must also be implemented by this element, the styling processing model defines how. [CSSOM]

The style element allows authors to embed style information in their documents. The style element is one of several inputs to the styling processing model.

If the type attribute is given, it must contain a valid MIME type, optionally with parameters, that designates a styling language. [RFC2046] If the attribute is absent, the type defaults to text/css. [RFC2138]

When examining types to determine if they support the language, user agents must not ignore unknown MIME parameters — types with unknown parameters must be assumed to be unsupported.

The media attribute says which media the styles apply to. The value must be a valid media query. [MQ] User agents must only apply the styles to views while their state match the listed media. [DOM3VIEWS]

The default, if the media attribute is omitted, is all, meaning that by default styles apply to all media.

The scoped attribute is a boolean attribute. If the attribute is present, then the user agent must only apply the specified style information to the style element's parent element (if any), and that element's child nodes. Otherwise, the specified styles must, if applied, be applied to the entire document.

If the scoped attribute is not specified, the style element must be the child of a head element or of a noscript element that is a child of a head element.

If the scoped attribute is specified, then the style element must be the child of an article, aside, div, or section element, before any significant text or any elements other than style elements.

The title attribute on style elements defines alternative style sheet sets. If the style element has no title attribute, then it has no title; the title attribute of ancestors does not apply to the style element.

The title attribute on style elements, like the title attribute on link elements, differs from the global title attribute in that a style block without a title does not inherit the title of the parent element: it merely has no title.

All descendant elements must be processed, according to their semantics, before the style element itself is evaluated. For styling languages that consist of pure text, user agents must evaluate style elements by passing the concatenation of the contents of all the text nodes that are direct children of the style element (not any other nodes such as comments or elements), in tree order, to the style system. For XML-based styling languages, user agents must pass all the children nodes of the style element to the style system.

This specification does not specify a style system, but CSS is expected to be supported by most Web browsers. [CSS21]

The media, type and scoped DOM attributes must reflect the respective content attributes of the same name.

The DOM disabled attribute behaves as defined for the alternative style sheets DOM.

3.7.7. Styling

The link and style elements can provide styling information for the user agent to use when rendering the document. The DOM Styling specification specifies what styling information is to be used by the user agent and how it is to be used. [CSSOM]

The style and link elements implement the LinkStyle interface. [CSSOM]

For style elements, if the user agent does not support the specified styling language, then the sheet attribute of the element's LinkStyle interface must return null. Similarly, link elements that do not represent external resource links that contribute to the styling processing model (i.e. that do not have a stylesheet keyword in their rel attribute), and link elements whose specified resource has not yet been downloaded, or is not in a supported styling language, must have their LinkStyle interface's sheet attribute return null.

Otherwise, the LinkStyle interface's sheet attribute must return a StyleSheet object with the attributes implemented as follows: [CSSOM]

The content type (type DOM attribute)

The content type must be the same as the style's specified type. For style elements, this is the same as the type content attribute's value, or text/css if that is omitted. For link elements, this is the Content-Type metadata of the specified resource.

The location (href DOM attribute)

For link elements, the location must be the URI given by the element's href content attribute. For style elements, there is no location.

The intended destination media for style information (media DOM attribute)

The media must be the same as the value of the element's media content attribute.

The style sheet title (title DOM attribute)

The title must be the same as the value of the element's title content attribute. If the attribute is absent, then the style sheet does not have a title. The title is used for defining alternative style sheet sets.

The disabled DOM attribute on link and style elements must return false and do nothing on setting, if the sheet attribute of their LinkStyle interface is null. Otherwise, it must return the value of the StyleSheet interface's disabled attribute on getting, and forward the new value to that same attribute on setting.