URI-based (direct) addressing

Content reference and link relationships can be established from DITA elements using URI references to point directly to targets.

URI references address "resources" and, optionally, subcomponents of those resources. In the context of DITA, a resource is a DITA document (map, topic, or DITA base document) or a non-DITA resource (e.g., a Web page, a PDF document, etc.). For DITA resources, fragment identifiers can be used with the URI to address individual elements. The fragment identifier is the part of the URI that starts with a number sign ("#"), e.g., "#topicid/elementid". URI references may also include a query component, introduced with "?". DITA processors may ignore queries on URI references to DITA resources.

note

URI references that are URLs must conform to the rules for URLs and URIs. In particular, Windows paths with backslashes are not valid URLs.

URIs and DITA fragment identifiers

DITA uses URI references in @href, @conref, or other attributes for all direct addressing of resources.

For addressing DITA elements within maps and topics or individual topics within documents containing multiple topics, URI references must include the appropriate DITA-defined fragment identifier. URI references may be relative or absolute. A relative URI reference may consist of just a fragment identifier. Such a reference is a reference to the document that contains the reference.

When addressing a DITA topic element, URI references may include a fragment identifier that includes the ID of the topic element (filename.dita#topicId or #topicId).

When addressing a non-topic element within a DITA topic, a URI reference must use a fragment identifier that contains the ID of the ancestor topic element of the non-topic element being referenced, a solidus ("/"), and the ID of the non-topic element (filename.dita#topicId/elementId or #topicId/elementId).

This addressing model makes it possible to reliably address elements whose id attribute values are unique within a single DITA topic but which may not be unique within a larger XML document that contains multiple DITA topics. (See ID attribute for more information on ID attributes.)

When addressing a DITA map element, URI references may include a fragment identifier that includes the ID of the map element (filename.ditamap#mapId or #mapId).

If a target DITA element is within the same XML document as the element making the reference, the URI reference may consist of only the fragment identifier (including the "#" (number sign) character).

Addressing non-DITA targets via URI

All resources, regardless of type, are directly addressed by URI references from DITA elements. When addressing targets within non-DITA resources, any fragment identifier used must conform to the fragment identifier requirements defined for the target media type, including references to non-DITA XML resources.

Addressing DITA topics via URI

Topics can always be addressed by a URI reference whose fragment identifier consists of the topic's ID. For the purposes of linking, a reference to a topic-containing document addresses the first topic within that document in document order. For the purposes of rendering, a reference to a topic-containing document addresses the root element of the document.

note

For example, given a document whose root element is a topic, a URI reference (with no fragment identifier) addressing that document implicitly references the topic element. Given a <dita> document containing multiple topics, a URI reference addressing the <dita> document implicitly addresses the first child topic of the <dita> element for purposes of linking (for example, from a cross reference element) but addresses the <dita> element for the purposes of rendering (implying that all the topics contained by the <dita> element will be rendered in the result).

Addressing non-topic DITA elements via URI

To address non-topic elements within topics via URI, a topicID/elementID fragment identifier must be used.

To address elements within a DITA map via URI, an elementID fragment identifier must be used. The linking element must specify a value of "ditamap" for the format attribute.

URI reference syntax examples

The following table shows the URI syntax for common use cases.

Use case	Sample syntax
target a table in a topic at a network location	"http://example.com/file.dita#topicID/tableID"
target a section in a topic on a local file system	"directory/file.dita#topicID/sectionID"
target a figure contained in the same XML document	"#topicID/figureID"
target an element within an map	"http://example.com/map.ditamap#elementID" (and a value of "ditamap" for the format attribute)
target a map element within the same map document	"#elementID" (and a value of "ditamap" for the format attribute)
reference an external Web site	"http://www.somesite.com", "http://www.somesite.com#somefragment" or any other valid URI
reference an element within a local map	"filename.ditamap#elementid" (and a value of "ditamap" for the format attribute)
reference a local map	"filename.ditamap" (and a value of "ditamap" for the format attribute)
reference a local topic	reference a local topic "filename.dita" or "path/filename.dita"
reference a specific topic in a local document	"filename.dita#topicid" or "path/filename.dita#topicid"
reference a specific topic in the same file	"#topicid"