← 2.4 Common microsyntaxesTable of contents3 Semantics, structure, and APIs of HTML documents →
    1. 2.5 URLs
      1. 2.5.1 Terminology
      2. 2.5.2 Interfaces for URL manipulation
    2. 2.6 Common DOM interfaces
      1. 2.6.1 Reflecting content attributes in IDL attributes
      2. 2.6.2 Collections
        1. 2.6.2.1 HTMLCollection
        2. 2.6.2.2 HTMLAllCollection
        3. 2.6.2.3 HTMLFormControlsCollection
        4. 2.6.2.4 HTMLOptionsCollection
      3. 2.6.3 DOMTokenList
      4. 2.6.4 DOMSettableTokenList
      5. 2.6.5 DOMStringMap
      6. 2.6.6 DOM feature strings
      7. 2.6.7 Exceptions
    3. 2.7 Namespaces

2.5 URLs

ISSUE-56 (urls-webarch) blocks progress to Last Call

2.5.1 Terminology

A URL is a string used to identify a resource.

A URL is a valid URL if at least one of the following conditions holds:

A string is a valid non-empty URL if it is a valid URL but it is not the empty string.

A string is a valid URL potentially surrounded by spaces if, after stripping leading and trailing whitespace from it, it is a valid URL.

A string is a valid non-empty URL potentially surrounded by spaces if, after stripping leading and trailing whitespace from it, it is a valid non-empty URL.

A URL is an absolute URL if resolving it results in the same output regardless of what it is resolved relative to, and that output is not a failure.

An absolute URL is a hierarchical URL if, when resolved and then parsed, there is a character immediately after the <scheme> component and it is a U+002F SOLIDUS character (/).

An absolute URL is an authority-based URL if, when resolved and then parsed, there are two characters immediately after the <scheme> component and they are both U+002F SOLIDUS characters (//).


This specification defines the URL about:legacy-compat as a reserved, though unresolvable, about: URI, for use in DOCTYPEs in HTML documents when needed for compatibility with XML tools. [ABOUT]

This specification defines the URL about:srcdoc as a reserved, though unresolvable, about: URI, that is used as the document's address of iframe srcdoc documents. [ABOUT]

The term "URL" in this specification is used in a manner distinct from the precise technical meaning it is given in RFC 3986. Readers familiar with that RFC will find it easier to read this specification if they pretend the term "URL" as used herein is really called something else altogether. This is a willful violation of RFC 3986. [RFC3986]

2.5.2 Interfaces for URL manipulation

An interface that has a complement of URL decomposition IDL attributes has seven attributes with the following definitions:

           attribute DOMString protocol;
           attribute DOMString host;
           attribute DOMString hostname;
           attribute DOMString port;
           attribute DOMString pathname;
           attribute DOMString search;
           attribute DOMString hash;
o . protocol [ = value ]

Returns the current scheme of the underlying URL.

Can be set, to change the underlying URL's scheme.

o . host [ = value ]

Returns the current host and port (if it's not the default port) in the underlying URL.

Can be set, to change the underlying URL's host and port.

The host and the port are separated by a colon. The port part, if omitted, will be assumed to be the current scheme's default port.

o . hostname [ = value ]

Returns the current host in the underlying URL.

Can be set, to change the underlying URL's host.

o . port [ = value ]

Returns the current port in the underlying URL.

Can be set, to change the underlying URL's port.

o . pathname [ = value ]

Returns the current path in the underlying URL.

Can be set, to change the underlying URL's path.

o . search [ = value ]

Returns the current query component in the underlying URL.

Can be set, to change the underlying URL's query component.

o . hash [ = value ]

Returns the current fragment identifier in the underlying URL.

Can be set, to change the underlying URL's fragment identifier.

The table below demonstrates how the getter for search results in different results depending on the exact original syntax of the URL:

Input URL search value Explanation
http://example.com/ empty string No <query> component in input URL.
http://example.com/? ? There is a <query> component, but it is empty.
http://example.com/?test ?test The <query> component has the value "test".
http://example.com/?test# ?test The (empty) <fragment> component is not part of the <query> component.

The following table is similar; it provides a list of what each of the URL decomposition IDL attributes returns for a given input URL.

Input protocol host hostname port pathname search hash
http://example.com/carrot#question%3f http: example.com example.com (empty string) /carrot (empty string) #question%3f
https://www.example.com:4443? https: www.example.com:4443 www.example.com 4443 / ? (empty string)

2.6 Common DOM interfaces

2.6.1 Reflecting content attributes in IDL attributes

Some IDL attributes are defined to reflect a particular content attribute. This means that on getting, the IDL attribute returns the current value of the content attribute, and on setting, the IDL attribute changes the value of the content attribute to the given value.

2.6.2 Collections

The HTMLCollection, HTMLAllCollection, HTMLFormControlsCollection, HTMLOptionsCollection, interfaces represent various lists of DOM nodes. Collectively, objects implementing these interfaces are called collections.

When a collection is created, a filter and a root are associated with the collection.

For example, when the HTMLCollection object for the document.images attribute is created, it is associated with a filter that selects only img elements, and rooted at the root of the document.

The collection then represents a live view of the subtree rooted at the collection's root, containing only nodes that match the given filter. The view is linear.

2.6.2.1 HTMLCollection

The HTMLCollection interface represents a generic collection of elements.

interface HTMLCollection {
  readonly attribute unsigned long length;
  caller getter Element item(in unsigned long index);
  caller getter object namedItem(in DOMString name); // only returns Element
};
collection . length

Returns the number of elements in the collection.

element = collection . item(index)
collection[index]
collection(index)

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

Returns null if index is out of range.

element = collection . namedItem(name)
collection[name]
collection(name)

Returns the first item with ID or name name from the collection.

Returns null if no element with that ID or name could be found.

Only a, applet, area, embed, form, frame, frameset, iframe, img, and object elements can have a name for the purpose of this method; their name is given by the value of their name attribute.

2.6.2.2 HTMLAllCollection

The HTMLAllCollection interface represents a generic collection of elements just like HTMLCollection, with the exception that its namedItem() method returns an HTMLAllCollection object when there are multiple matching elements.

interface HTMLAllCollection : HTMLCollection {
  // inherits length and item()
  caller getter object namedItem(in DOMString name); // overrides inherited namedItem()
  HTMLAllCollection tags(in DOMString tagName);
};
collection . length

Returns the number of elements in the collection.

element = collection . item(index)
collection[index]
collection(index)

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

Returns null if index is out of range.

element = collection . namedItem(name)
collection = collection . namedItem(name)
collection[name]
collection(name)

Returns the item with ID or name name from the collection.

If there are multiple matching items, then an HTMLAllCollection object containing all those elements is returned.

Returns null if no element with that ID or name could be found.

Only a, applet, area, embed, form, frame, frameset, iframe, img, and object elements can have a name for the purpose of this method; their name is given by the value of their name attribute.

collection = collection . tags(tagName)

Returns a collection that is a filtered view of the current collection, containing only elements with the given tag name.

2.6.2.3 HTMLFormControlsCollection

The HTMLFormControlsCollection interface represents a collection of listed elements in form and fieldset elements.

interface HTMLFormControlsCollection : HTMLCollection {
  // inherits length and item()
  caller getter object namedItem(in DOMString name); // overrides inherited namedItem()
};

interface RadioNodeList : NodeList {
          attribute DOMString value;
};
collection . length

Returns the number of elements in the collection.

element = collection . item(index)
collection[index]
collection(index)

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

Returns null if index is out of range.

element = collection . namedItem(name)
radioNodeList = collection . namedItem(name)
collection[name]
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.

Returns null if no element with that ID or name could be found.

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.

2.6.2.4 HTMLOptionsCollection

The HTMLOptionsCollection interface represents a list of option elements. It is always rooted on a select element and has attributes and methods that manipulate that element's descendants.

interface HTMLOptionsCollection : HTMLCollection {
  // inherits item()
           attribute unsigned long length; // overrides inherited length
  caller getter object namedItem(in DOMString name); // overrides inherited namedItem()
  void add(in HTMLElement element, in optional HTMLElement before);
  void add(in HTMLElement element, in long before);
  void remove(in 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)
collection[index]
collection(index)

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

Returns null if index is out of range.

element = collection . namedItem(name)
nodeList = collection . namedItem(name)
collection[name]
collection(name)

Returns the item with ID or name name from the collection.

If there are multiple matching items, then a NodeList object containing all those elements is returned.

Returns null if no element with that ID could be found.

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 HIERARCHY_REQUEST_ERR exception if element is an ancestor of the element into which it is to be inserted. If element is not an option or optgroup element, then the method does nothing.

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.

2.6.3 DOMTokenList

The DOMTokenList interface represents an interface to an underlying string that consists of a set of space-separated tokens.

DOMTokenList objects are always case-sensitive, even when the underlying string might ordinarily be treated in a case-insensitive manner.

interface DOMTokenList {
  readonly attribute unsigned long length;
  getter DOMString item(in unsigned long index);
  boolean contains(in DOMString token);
  void add(in DOMString token);
  void remove(in DOMString token);
  boolean toggle(in DOMString token);
  stringifier DOMString ();
};
tokenlist . length

Returns the number of tokens in the string.

element = tokenlist . item(index)
tokenlist[index]

Returns the token with index index. The tokens are returned in the order they are found in the underlying string.

Returns null if index is out of range.

hastoken = tokenlist . contains(token)

Returns true if the token is present; false otherwise.

Throws a SYNTAX_ERR exception if token is empty.

Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.

tokenlist . add(token)

Adds token, unless it is already present.

Throws a SYNTAX_ERR exception if token is empty.

Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.

tokenlist . remove(token)

Removes token if it is present.

Throws a SYNTAX_ERR exception if token is empty.

Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.

hastoken = tokenlist . toggle(token)

Adds token if it is not present, or removes it if it is. Returns true if token is now present (it was added); returns false if it is not (it was removed).

Throws a SYNTAX_ERR exception if token is empty.

Throws an INVALID_CHARACTER_ERR exception if token contains any spaces.

2.6.4 DOMSettableTokenList

The DOMSettableTokenList interface is the same as the DOMTokenList interface, except that it allows the underlying string to be directly changed.

interface DOMSettableTokenList : DOMTokenList {
            attribute DOMString value;
};
tokenlist . value

Returns the underlying string.

Can be set, to change the underlying string.

2.6.5 DOMStringMap

The DOMStringMap interface represents a set of name-value pairs. It exposes these using the scripting language's native mechanisms for property access.

The dataset attribute on elements exposes the data-* attributes on the element.

Given the following fragment and elements with similar constructions:

<img class="tower" id="tower5" data-x="12" data-y="5"
     data-ai="robotarget" data-hp="46" data-ability="flames"
     src="towers/rocket.png alt="Rocket Tower">

...one could imagine a function splashDamage() that takes some arguments, the first of which is the element to process:

function splashDamage(node, x, y, damage) {
  if (node.classList.contains('tower') && // checking the 'class' attribute
      node.dataset.x == x && // reading the 'data-x' attribute
      node.dataset.y == y) { // reading the 'data-y' attribute
    var hp = parseInt(node.dataset.hp); // reading the 'data-hp' attribute
    hp = hp - damage;
    if (hp < 0) {
      hp = 0;
      node.dataset.ai = 'dead'; // setting the 'data-ai' attribute
      delete node.dataset.ability; // removing the 'data-ability' attribute
    }
    node.dataset.hp = hp; // setting the 'data-hp' attribute
  }
}

2.6.6 DOM feature strings

DOM3 Core defines mechanisms for checking for interface support, and for obtaining implementations of interfaces, using feature strings. [DOMCORE]

Authors are strongly discouraged from using these, as they are notoriously unreliable and imprecise. Authors are encouraged to rely on explicit feature testing or the graceful degradation behavior intrinsic to some of the features in this specification.

2.6.7 Exceptions

The following are DOMException codes. [DOMCORE]

  1. INDEX_SIZE_ERR
  2. DOMSTRING_SIZE_ERR
  3. HIERARCHY_REQUEST_ERR
  4. WRONG_DOCUMENT_ERR
  5. INVALID_CHARACTER_ERR
  6. NO_DATA_ALLOWED_ERR
  7. NO_MODIFICATION_ALLOWED_ERR
  8. NOT_FOUND_ERR
  9. NOT_SUPPORTED_ERR
  10. INUSE_ATTRIBUTE_ERR
  11. INVALID_STATE_ERR
  12. SYNTAX_ERR
  13. INVALID_MODIFICATION_ERR
  14. NAMESPACE_ERR
  15. INVALID_ACCESS_ERR
  16. VALIDATION_ERR
  17. TYPE_MISMATCH_ERR
  18. SECURITY_ERR
  19. NETWORK_ERR
  20. ABORT_ERR
  21. URL_MISMATCH_ERR
  22. QUOTA_EXCEEDED_ERR
  23. TIMEOUT_ERR
  24. DATA_CLONE_ERR

2.7 Namespaces

The HTML namespace is: http://www.w3.org/1999/xhtml

The MathML namespace is: http://www.w3.org/1998/Math/MathML

The SVG namespace is: http://www.w3.org/2000/svg

The XLink namespace is: http://www.w3.org/1999/xlink

The XML namespace is: http://www.w3.org/XML/1998/namespace

The XMLNS namespace is: http://www.w3.org/2000/xmlns/


Data mining tools and other user agents that perform operations on content without running scripts, evaluating CSS or XPath expressions, or otherwise exposing the resulting DOM to arbitrary content, may "support namespaces" by just asserting that their DOM node analogues are in certain namespaces, without actually exposing the above strings.


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.