2.3.3 URI-based (direct) addressing
Content reference and link relationships can be established from DITA elements by using
URI references. DITA uses URI references in @href, @conref, and
other attributes for all direct addressing of resources.
URI references address resources and (in some cases) subcomponents of those resources. In this context, a resource is a DITA document (map, topic, or DITA base document) or a non-DITA resource (for example, an image, a Web page, or a PDF document).
URI references that are URLs must conform to the rules for URLs and URIs. Windows paths that contain a backslash (\) are not valid URLs.
URIs and fragment identifiers
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 (#),
for example, #topicid/elementid. URI references also can include a query
component that is introduced with a question mark (?). DITA processors MAY ignore queries on URI references to
DITA resources. URI references that address components in the same
document MAY consist of just the
fragment identifier.
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 can be relative or absolute. A relative URI reference can consist of just a fragment identifier. Such a reference is a reference to the document that contains the reference.
Addressing non-DITA targets using a URI
DITA can use URI references to directly address non-DITA resources. Any fragment identifier used must conform to the fragment identifier requirements that are defined for the target media type or provided by processors.
Addressing elements within maps using a URI
When addressing elements within maps, URI references can include a fragment identifier that
includes the ID of the map element, for example, filename.ditamap#mapId or
#mapId. The same-topic, URI-reference fragment identifier of a period
(.) can not be used in URI references to elements within
maps.
Addressing topics using a URI
When addressing a DITA topic element, URI references can
include a fragment identifier that includes the ID of the topic element
(filename.dita#topicId or #topicId). When addressing
the DITA topic element that contains the URI reference, the URI reference might include the same topic fragment identifier of "."
(#.).
Topics always can be addressed by a URI reference whose fragment identifier consists of the topic 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.
- Given a document whose root element is a topic, a URI reference (with no fragment identifier) that addresses that document implicitly references the topic element.
- Given a
<dita>document that contains multiple topics, for the purposes of linking, a URI reference that addresses the<dita>document implicitly references the first child topic. - Given a
<dita>document that contains multiple topics, for the purposes of rendering, a URI reference that addresses the<dita>document implicitly references all the topics that are contained by the<dita>element. This means that all the topics that are contained by the<dita>element are rendered in the result.
Addressing non-topic elements using a URI
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 slash ("/"), and the ID of the
non-topic element (filename.dita#topicId/elementId or
#topicId/elementId). When addressing a non-topic element within the topic that contains the URI reference, the
URI reference can use an abbreviated fragment-identifier syntax that replaces the topic ID
with "." (#./elementId).
This addressing model makes it possible to reliably address elements that have values for
the @id attribute that are unique within a single DITA topic, but which
might not be unique within a larger XML document that contains multiple DITA topics.
Examples: URI reference syntax
The following table shows the URI syntax for common use cases.
| Use case | Sample syntax |
|---|---|
| Reference a table in a topic at a network location |
"http://example.com/file.dita#topicID/tableID"
|
| Reference a section in a topic on a local file system |
"directory/file.dita#topicID/sectionID"
|
| Reference a figure contained in the same XML document |
"#topicID/figureID"
|
| Reference a figure contained in the same topic of an XML document |
"#./figureID"
|
| Reference an element within a map |
"http://example.com/map.ditamap#elementID" (and a value of
"ditamap" for the @format attribute) |
| Reference 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.example.com",
"http://www.example.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"
|
| Reference the same topic in the same XML document |
"#."
|
| Reference a peer map for cross-deliverable linking |
"../book-b/book-b.ditamap" (and a value of "ditamap" for the
@format attribute, a value of "peer" for the @scope
attribute, and a value for the @keyscope attribute) |