This specification might have certain additional requirements on character encodings, image formats, audio formats, and video formats in the respective sections.

Extensibility

Pages that use such attributes are by definition non-conforming.

Someone could write a specification that defines any arbitrary byte stream as conforming, and then claim that their random junk is conforming. However, that does not mean that their random junk actually is conforming for everyone's purposes: if someone else decides that the specification does not apply to their work, then they can quite legitimately say that the aforementioned random junk is just that, junk, and not conforming at all. As far as conformance goes, what matters in a particular community is what that community agrees is applicable.

As a suggested but not required convention, such specifications might define conformance terminology such as: "Conforming HTML+XXX document", where XXX is a short name for the applicable specification. (Example: "Conforming HTML+AutomotiveExtensions document").

a consequence of the rule given above is that certain syntactically correct HTML documents may not be conforming HTML documents in the presence of applicable specifications. (Example: the applicable specification defines <table> to be a piece of furniture — a document written to that specification and containing a <table> element is NOT a conforming HTML document, even if the element happens to be syntactically correct HTML.)

Interactions with XPath and XSLT

A QName in the node test is expanded into an expanded-name using the namespace declarations from the expression context. This is the same way expansion is done for element type names in start and end-tags except that the default namespace declared with <{xmlns/xmlns}> is not used: if the QName does not have a prefix, then the namespace URI is null (this is the same way attribute names are expanded). It is an error if the QName has a prefix for which there is no namespace declaration in the expression context.

A QName in the node test is expanded into an expanded-name using the namespace declarations from the expression context. If the QName has a prefix, then there must be a namespace declaration for this prefix in the expression context, and the corresponding namespace URI is the one that is associated with this prefix. It is an error if the QName has a prefix for which there is no namespace declaration in the expression context. If the QName has no prefix and the principal node type of the axis is element, then the default element namespace is used. Otherwise if the QName has no prefix, the namespace URI is null. The default element namespace is a member of the context for the XPath expression. The value of the default element namespace when executing an XPath expression through the DOM3 XPath API is determined in the following way: 1. If the context node is from an HTML DOM, the default element namespace is "http://www.w3.org/1999/xhtml". 2. Otherwise, the default element namespace URI is null.

This is equivalent to adding the default element namespace feature of XPath 2.0 to XPath 1.0, and using the HTML namespace as the default element namespace for HTML documents. It is motivated by the desire to have implementations be compatible with legacy HTML content while still supporting the changes that this specification introduces to HTML regarding the namespace used for HTML elements, and by the desire to use XPath 1.0 rather than XPath 2.0.

This change is a willful violation of the XPath 1.0 specification, motivated by desire to have implementations be compatible with legacy content while still supporting the changes that this specification introduces to HTML regarding which namespace is used for HTML elements. [[!XPATH]]

This requirement is a willful violation of the XSLT 1.0 specification, required because this specification changes the namespaces and case-sensitivity rules of HTML in a manner that would otherwise be incompatible with DOM-based XSLT transformations. (Processors that serialize the output are unaffected.) [[XSLT]]

There are also additional non-normative comments regarding the interaction of XSLT and HTML in the script element section, and of XSLT, XPath, and HTML in the template element section.

Case-sensitivity and string comparison

Common microsyntaxes

Implementors are strongly urged to carefully examine any third-party libraries they might consider using to implement the parsing of syntaxes described below. For example, date libraries are likely to implement error handling behavior that differs from what is required in this specification, since error-handling behavior is often not defined in specifications that describe date syntaxes similar to those used in this specification, and thus implementations tend to vary greatly in how they handle errors.

Common parser idioms

This should not be confused with the "White_Space" value (abbreviated "WS") of the "Bidi_Class" property in the Unicode.txt data file.

For the special cases of splitting a string on spaces and on commas, this algorithm does not apply (those algorithms also perform white space trimming).

Boolean attributes

A boolean attribute without a value assigned to it (e.g. checked) is implicitly equivalent to one that has the empty string assigned to it (i.e. checked=""). As a consequence, it represents the true value.

The values "true" and "false" are not allowed on boolean attributes. To represent a false value, the attribute has to be omitted altogether.

      <label><input type="checkbox" checked name="cheese" disabled> Cheese</label>
    

      <label><input type="checkbox" checked="checked" name="cheese" disabled="disabled"> Cheese</label>
    

Keywords and enumerated attributes

The empty string can be a valid keyword.

Numbers

Signed integers

Non-negative integers

Floating-point numbers

The Infinity and Not-a-Number (NaN) values are not valid floating-point numbers.

Percentages and lengths

Non-zero percentages and lengths

Lists of floating-point numbers

Lists of dimensions

Dates and times

While the formats described here are intended to be subsets of the corresponding ISO8601 formats, this specification defines parsing rules in much more detail than ISO8601. Implementors are therefore encouraged to carefully examine any date parsing libraries before using them to implement the parsing rules described below; ISO8601 libraries might not parse dates and times in exactly the same manner. [[ISO8601]]

Months

For example, February 2005 is encoded 2005-02, and March of the year 33AD (as a proleptic gregorian date) is encoded 0033-03. The expression 325-03 does not mean March in the year 325, it is an error, because it does not have 4 digits for the year.

Dates

For example, 29 February 2016 is encoded 2016-02-29, and 3 March of the year 33AD (as a proleptic gregorian date) is encoded 0033-03-03. The expression 325-03-03 does not mean 3 March in the year 325, it is an error, because it does not have 4 digits for the year.

Yearless dates

In other words, if the month is "02", meaning February, then the day can be 29, as if the year was a leap year.

For example, 29 February is encoded 02-29, and 3 March is encoded 03-03.

Times

The second component cannot be 60 or 61; leap seconds cannot be represented.

Times are encoded using the 24 hour clock, with optional seconds, and optional decimal fractions of seconds. Thus 7.45pm is encoded as 19:45. Note that parsing that time will return 19:45:00, or 7.45pm and zero seconds. 19:45:45.456 is 456 thousandths of a second after 7.45pm and 45 seconds.

Floating dates and times

Time zones

This format allows for time-zone offsets from -23:59 to +23:59. In practice, however, right now the range of offsets of actual time zones is -12:00 to +14:00, and the minutes component of offsets of actual time zones is always either 00, 30, or 45. There is no guarantee that this will remain so forever, however; time zones are changed by countries at will and do not follow a standard.

See also the usage notes and examples in the global date and time section below for details on using time-zone offsets with historical times that predate the formation of formal time zones.

Global dates and times

The zone offset is not a complete time zone specification. When working with real date and time values, consider using a separate field for time zone, perhaps using IANA time zone IDs. [[TIMEZONE]]

Weeks

The week-year number of a particular day can be different than the number of the year that contains that day in the proleptic Gregorian calendar. The first week in a week-year y is the week that contains the first Thursday of the Gregorian year y.

For modern purposes, a week as defined here is equivalent to ISO weeks as defined in ISO 8601. [[ISO8601]] A string is a valid week string representing a week-year year and week week if it consists of the following components in the given order:

Durations

Since months and seconds are not comparable (a month is not a precise number of seconds, but is instead a period whose exact length depends on the precise day from which it is measured) a duration as defined in this specification cannot include months (or years, which are equivalent to twelve months). Only durations that describe a specific number of seconds can be described.

This, as with a number of other date- and time-related microsyntaxes defined in this specification, is based on one of the formats defined in ISO 8601. [[ISO8601]]

This is not based on any of the formats in ISO 8601. It is intended to be a more human-readable alternative to the ISO 8601 duration format.

This flag's other value is months. It is used to disambiguate the "M" unit in ISO8601 durations, which use the same unit for months and minutes. Months are not allowed, but are parsed for future compatibility and to avoid misinterpreting ISO8601 durations that would be valid in other contexts.

Vaguer moments in time

Colors

CSS2 System Colors are not recognized.

Space-separated tokens

How tokens in a set of space-separated tokens are to be compared (e.g., case-sensitively or not) is defined on a per-set basis.

Comma-separated tokens

For instance, the string " a ,b, ,d d " consists of four tokens: "a", "b", the empty string, and "d d". Leading and trailing white space around each token doesn't count as part of the token, and the empty string can be a token.

References

Media queries

URLs

Terminology

Parsing URLs

This wrapper is only useful when the character encoding for the URL parser has to match that of the document or environment settings object for legacy reasons. When that is not the case the URL parser can be used directly.

Dynamic changes to base URLs

If the element creates a hyperlink

If the [=url/URL=] identified by the hyperlink is being shown to the user, or if any data derived from that [=url/URL=] is affecting the display, then the <{links/href}> attribute should be reparsed relative to the element's node document and the UI updated appropriately.

For example, the CSS '':link''/'':visited'' pseudo-classes might have been affected.

If the element is a <{q}>, <{blockquote}>, <{ins}>, or <{del}> element with a cite attribute

If the [=url/URL=] identified by the cite attribute is being shown to the user, or if any data derived from that [=url/URL=] is affecting the display, then the [=url/URL=] should be reparsed relative to the element's node document and the UI updated appropriately.

Otherwise

The element is not directly affected.

For instance, changing the base URL doesn't affect the image displayed by img elements, although subsequent accesses of the src IDL attribute from script will return a new absolute URL that might no longer correspond to the image being shown.

Fetching resources

Terminology

Processing model

If there is a specific override referrer source

The override referrer source.

When navigating

The active document of the source browsing context.

When fetching resources for an element

The element's {{Document}}.

If the force same-origin flag is set and the [=url/URL=] of the target of the redirect does not have the same origin as the [=url/URL=] for which the fetch algorithm was invoked

Abort these steps and return failure from this algorithm, as if the remote host could not be contacted.

If the manual redirect flag is set

Continue, using the fetched resource (the redirect) as the result of the algorithm. If the calling algorithm subsequently requires the user agent to transparently follow the redirect, then the user agent must resume this algorithm from the main step, but using the target of the redirect as the resource to fetch, rather than the original resource.

Otherwise

First, apply any relevant requirements for redirects (such as showing any appropriate prompts). Then, redo main step, but using the target of the redirect as the resource to fetch, rather than the original resource. For HTTP requests, the new request must include the same headers as the original request, except for headers for which other requirements are specified (such as the Host header). [[!HTTP]]

The HTTP specification requires that 301, 302, and 307 redirects, when applied to methods other than the safe methods, not be followed without user confirmation. That would be an appropriate prompt for the purposes of the requirement in the paragraph above. [[!HTTP]]

The navigation processing model handles redirects itself, overriding the redirection handling that would be done by the fetching algorithm.

Whether the type sniffing rules apply to the fetched resource depends on the algorithm that invokes the rules — they are not always applicable.

Encrypted HTTP and related security concerns

User agents should report certificate errors to the user and must either refuse to download resources sent with erroneous certificates or must act as if such resources were in fact served with no encryption.

Determining the type of a resource

It is imperative that the rules in the MIME Sniffing specification be followed exactly. When a user agent uses different heuristics for content type detection than the server expects, security problems can occur. For more details, see the MIME Sniffing specification. [[!MIMESNIFF]]

Extracting character encodings from <{meta}> elements

If it is a U+0022 QUOTATION MARK character (") and there is a later U+0022 QUOTATION MARK character (") in s

If it is a U+0027 APOSTROPHE character (') and there is a later U+0027 APOSTROPHE character (') in s

Return the result of getting an encoding from the substring that is between this character and the next earliest occurrence of this character.

If it is an unmatched U+0022 QUOTATION MARK character (")

If it is an unmatched U+0027 APOSTROPHE character (')

If there is no next character

Return nothing.

Otherwise

Return the result of getting an encoding from the substring that consists of this character up to but not including the first space character or U+003B SEMICOLON character (;), or the end of s, whichever comes first.

This algorithm is distinct from those in the HTTP specification (for example, HTTP doesn't allow the use of single quotes and requires supporting a backslash-escape mechanism that is not supported by this algorithm). While the algorithm is used in contexts that, historically, were related to HTTP, the syntax as supported by implementations diverged some time ago. [[!HTTP]]

CORS settings attributes

Referrer policy attributes

Nonce attributes

A nonce content attribute represents a cryptographic nonce ("number used once") which can be used by Content Security Policy to determine whether or not a given fetch will be allowed to proceed. The value is text. [[!CSP3]]

Elements that have a nonce content attribute ensure that the crytographic nonce is only exposed to script (and not to side-channels like CSS attribute selectors) by extracting the value from the content attribute, moving it into an internal slot named [[CryptographicNonce]], and exposing it to script via the {{HTMLOrSVGElement}} interface defined below. Unless otherwise specified, the slot's value is the empty string.

element . nonce

Returns the value of the element's [[CryptographicNonce]] internal slot.

Can be set, to update that slot's value.

The nonce IDL attribute must, on getting, return the value of this element's [[CryptographicNonce]]; and on setting, set this element's [[CryptographicNonce]] to the given value.

Whenever an element including {{HTMLOrSVGElement}}'s nonce attribute is set or changed, set this element's [[CryptographicNonce]] to the given value.

Whenever an element including {{HTMLOrSVGElement}} becomes connected to a browsing context, the user agent must execute the following steps on the element:

1. Let [=response/CSP list=] be element's shadow-including root's [=response/CSP list=].

2. If [=response/CSP list=] contains a header-delivered Content Security Policy, and element has a nonce content attribute attr whose value is not the empty string, then:

   1. Set an attribute value for element using "nonce" and the empty string.

As each {{Document}}'s [=response/CSP list=] is append-only, user agents can optimize away the contains a header-delivered Content Security Policy check by, for example, holding a flag on the {{Document}}, set when initializing a new document object.

The cloning steps for elements that include {{HTMLOrSVGElement}} must set the [[CryptographicNonce]] slot on the copy to the value of the slot on the element being cloned.

Common DOM interfaces

Reflecting content attributes in IDL attributes

The values Infinity and Not-a-Number (NaN) values throw an exception on setting, as defined in the Web IDL specification. [[!WEBIDL]]

Collections

The HTMLAllCollection interface

All {{HTMLAllCollection}} objects are rooted at a {{Document}} and have a filter that matches all elements, so the elements represented by the collection of an {{HTMLAllCollection}} object consist of all the descendant elements of the root {{Document}}.

    [LegacyUnenumerableNamedProperties]
    interface HTMLAllCollection {
      readonly attribute unsigned long length;
      getter Element (unsigned long index);
      getter (HTMLCollection or Element)? namedItem(DOMString name);
      legacycaller (HTMLCollection or Element)? item(optional DOMString nameOrItem);
    };
  

collection . {{HTMLAllCollection/length}}

Returns the number of elements in the collection.

element = collection . {{HTMLAllCollection/item()|item}}(index)

element = collection(index)

element = collection[index]

Returns the item with index index from the collection (determined by tree order.

element = collection . {{HTMLAllCollection/item()|item}}(name)

collection = collection . {{HTMLAllCollection/item()|item}}(name)

element = collection . {{HTMLAllCollection/namedItem()|namedItem}}(name)

collection = collection . {{HTMLAllCollection/namedItem()|namedItem}}(name)

element = collection(name)

collection = collection(name)

element = collection[name]

collection = collection[name]

Returns the item with ID or name name from the collection. If there are multiple matching items, then an {{HTMLCollection}} object containing all those elements is returned. The <{formelements/name}> attribute's value provides a name for <{button}>, <{input}>, <{select}>, and <{textarea}>. Similarly, <{iframe}>'s <{iframe/name}>, <{object}>'s <{object/name}>, <{meta}>'s <{meta/name}>, <{map}>'s <{map/name}>, and <{form}>'s <{form/name}> attribute's value provides a name for their respective elements. Only the elements mentioned have a name for the purpose of this method.

The HTMLFormControlsCollection interface

    interface HTMLFormControlsCollection : HTMLCollection {
      // inherits length and item()
      getter (RadioNodeList or Element)? namedItem(DOMString name); // shadows inherited namedItem()
    };
  

    interface RadioNodeList : NodeList {
      attribute DOMString value;
    };
  

collection . length

Returns the number of elements in the collection.

element = collection . item(index)

element = collection[index]

Returns the item with index index from the collection. The items are sorted in tree order.

element = collection . namedItem(name)

radioNodeList = collection . namedItem(name)

element = collection[name]

radioNodeList = collection[name]

Returns the item with ID or name name from the collection. If there are multiple matching items, then a RadioNodeList object containing all those elements is returned.

radioNodeList . {{RadioNodeList/value}} [ = value ]

Returns the value of the first checked radio button represented by the object. Can be set, to check the first radio button with the given value represented by the object.

The HTMLOptionsCollection interface

    interface HTMLOptionsCollection : HTMLCollection {
      // inherits item(), namedItem()
      attribute unsigned long length; // shadows inherited length
      setter void (unsigned long index, HTMLOptionElement? option);
      void add((HTMLOptionElement or HTMLOptGroupElement) element, optional (HTMLElement or long)? before = null);
      void remove(long index);
      attribute long selectedIndex;
    };
  

collection . length [ = value ]

Returns the number of elements in the collection. When set to a smaller number, truncates the number of <{option}> elements in the corresponding container. When set to a greater number, adds new blank <{option}> elements to that container.

element = collection . item(index)

element = collection[index]

Returns the item with index index from the collection. The items are sorted in tree order.

collection[index] = element

When index is a greater number than the number of items in the collection, adds new blank <{option}> elements in the corresponding container. When set to null, removes the item at index index from the collection. When set to an <{option}> element, adds or replaces it at index index from the collection.

element = collection . namedItem(name)

element = collection[name]

Returns the item with ID or name name from the collection. If there are multiple matching items, then the first is returned.

collection . add(element [, before ] )

Inserts element before the node given by before. The before argument can be a number, in which case element is inserted before the item with that number, or an element from the collection, in which case element is inserted before that element. If before is omitted, null, or a number out of range, then element will be added at the end of the list. This method will throw a {{HierarchyRequestError}} exception if element is an ancestor of the element into which it is to be inserted.

collection . remove(index)

Removes the item with index index from the collection.

collection . selectedIndex [ = value ]

Returns the index of the first selected item, if any, or -1 if there is no selected item. Can be set, to change the selection.

Setting {{HTMLOptionsCollection/length}} never removes or adds any <{optgroup}> elements, and never adds new children to existing <{optgroup}> elements (though it can remove children from them).

The {{DOMStringList}} interface

    interface DOMStringList {
      readonly attribute unsigned long length;
      getter DOMString? item(unsigned long index);
      boolean contains(DOMString string);
    };
  

New APIs must use `sequence` or equivalent rather than {{DOMStringList}}.

: |strings| . {{DOMStringList/length}} :: Returns the number of strings in |strings|. : |strings|[|index|] : |strings| . {{DOMStringList/item()}}(|index|) :: Returns the string with index |index| from |strings|. : |strings| . {{DOMStringList/contains()}}(|string|) :: Returns true if |strings| contains |string|, and false otherwise.

Garbage collection

Namespaces

In the HTML syntax, namespace prefixes and namespace declarations do not have the same effect as in XML. For instance, the colon has no special meaning in HTML element names.

Safe passing of structured data

Serializable objects

Originally, this specification defined the concept of "cloneable objects", which could be cloned from one JavaScript Realm to another. However, to better specify the behavior of certain more complex situations, the model was updated to make the serialization and deserialization explicit.

Transferable objects

Transferring is an irreversible and non-idempotent operation. Once an object has been transferred, it cannot be transferred, or indeed used, again.

StructuredSerializeInternal ( value, forStorage [ , memory ] )

The purpose of the memory map is to avoid serializing objects twice. This ends up preserving cycles and the identity of duplicate objects in graphs.

This can throw a RangeError exception upon allocation failure.

For instance, a \[[PromiseState]] or \[[WeakMapData]] internal slot.

For instance, a proxy object.

The key collection performed above is very similar to the JavaScript specification's EnumerableOwnProperties operation, but crucially it uses the deterministic ordering provided by the \[[OwnPropertyKeys]] internal method, instead of reordering the keys in an unspecified manner as EnumerableOwnProperties does. [[!ECMA-262]] 25. Return serialized.

const o = {};
o.myself = o;

{
  \[[Type]]: "Object",
  \[[Properties]]: «
    {
      \[[Key]]: "myself",
      \[[Value]]: <a pointer to this whole structure>
    }
  »
}

StructuredSerialize ( value )

StructuredSerializeForStorage ( value )

StructuredDeserialize ( serialized, targetRealm [ , memory ] )

The purpose of the memory map is to avoid deserializing objects twice. This ends up preserving cycles and the identity of duplicate objects in graphs.

In cases where the original memory occupied by \[[ArrayBufferData]] is accessible during the deserialization, this step is unlikely to throw an exception, as no new memory needs to be allocated: the memory occupied by \[[ArrayBufferData]] is instead just getting transferred into the new ArrayBuffer. This could be true, for example, when both the source and target Realms are in the same process.

This step might throw an exception if there is not enough memory available to create such an ArrayBuffer object.

StructuredSerializeWithTransfer ( value, transferList )

In addition to how it is used normally by StructuredSerializeInternal, in this algorithm memory is also used to ensure that StructuredSerializeInternal ignores items in transferList, and let us do our own handling instead.

StructuredDeserializeWithTransfer ( serializeWithTransferResult, targetRealm )

In addition to how it is used normally by StructuredDeserialize, in this algorithm memory is also used to help us determine the list of transferred values.

Performing serialization and transferring from other specifications

messagePort.postMessage() uses this pair of abstract operations, as the destination Realm is not known until the MessagePort has been shipped.

history.pushState() and history.replaceState() use StructuredSerializeForStorage on author-supplied state objects, storing them as serialized state in the appropriate session history entry. Then, StructuredDeserialize is used so that the history.state property can return a clone of the originally-supplied state object.

broadcastChannel.postMessage() uses StructuredSerialize on its input, then uses StructuredDeserialize multiple times on the result to produce a fresh clone for each destination being broadcast to. Note that transferring does not make sense in multi-destination situations.

Any API for persisting JavaScript values to the filesystem would also use StructuredSerializeForStorage on its input and StructuredDeserialize on its output.

This specification used to define a "structured clone" algorithm, and more recently a StructuredClone abstract operation. However, in practice all known uses of it were better served by separate serialization and deserialization steps, so it was removed.

window.postMessage() performs [$StructuredSerializeWithTransfer$] on its arguments, but is careful to do so immediately, inside the synchronous portion of its algorithm. Thus it is able to use the algorithms without needing to prepare to run script and prepare to run a callback.

In contrast, a hypothetical API that used StructuredSerialize to serialize some author-supplied object periodically, directly from a task on the event loop, would need to ensure it performs the appropriate preparations beforehand. As of this time, we know of no such APIs on the platform; usually it is simpler to perform the serialization ahead of time, as a synchronous consequence of author code.