The href attribute

The value of a DITA href attribute must be a valid URI reference [RFC 3986]. It is an error if the value is not a valid URI reference. An implementation may (but need not) give an error message, and may (but need not) recover from this error condition by attempting to convert the value to a valid URI reference. Note that the path separator character in a URI is always the forward slash (“/”); the backward slash character (“\”) is not permitted unescaped within URIs.

In the case of a reference to a DITA resource, an href value consisting of a URI with no fragment identifier resolves to the document element in the referenced document. For the purposes of rendering, such as when a topicref reference to a DITA document is used to render the content as HTML, this means that all topics (and topic specializations) in the target document are included in the reference. For the purpose of linking, the reference resolves to the first (or only) topic (or topic specialization) in the document.

An href value consisting of a URI with a fragment identifier must have a valid DITA local identifier as the portion after the hash. A DITA local identifier consists of topicID/elementID for a subelement of a topic and of elementID for topics, maps, and map subelements.

Note that certain characters (including, but not limited to, #, ?, \, and space) are not permitted unescaped within URIs. Such characters must be percent-encoding (per RFC 3986) if there is a need to represent them within a string that is a URI. Also note that the “&” (ampersand) and “<” (greater than) characters are not permitted in XML attribute values, so they must be represented by appropriate character or entity references if there is a need to represent them within such a string. (Some tools may do the required encoding on the user's behalf while others may require the user to avoid the special characters or perform the encoding manually.)