DITA linking

The @format attribute identifies the format of the referenced resource.

The following values are explicitly supported:

dita

Indicates that the target is a DITA topic or an element in a DITA topic. Unless otherwise specified, when @format is set to dita, the value for the @type attribute is treated as topic.

ditamap

Indicates that the target is a DITA map. References to submaps can occur at any point in a map.

When a topic reference specifies format="ditamap", the topic reference resolves in one of the following ways:

Target of <topicref>	Resolution of <topicref>
DITA map	The hierarchy of all the topic references in the targeted map
Map branch	The hierarchy of the targeted map branch

When a topic reference targets an entire DITA map and the referenced map contains a relationship table, there are special processing implications. Because relationship tables are only valid as direct children of the DITA map, referenced relationship tables are treated as children of the referencing map.

Note (non-normative):

If a <topicref> element that references a map contains child <topicref> elements, the processing behavior regarding the child <topicref> elements is undefined.

If no value is explicitly specified for the @format attribute, the following precedence rules apply:

1. If the @format attribute is specified on a containing element within the map or within the related-links section of a topic, the value cascades from the closest containing element.
2. If a value for the @format attribute does not cascade, the processing default is used. The processing default for the @format attribute is determined by inspecting the value of the @href attribute:
   1. If the @href attribute specifies a file extension, the processing default for the @format attribute is that extension, after conversion to lower-case and with no leading period. The only exception to this is if the extension is .xml, in which case the default value for @format is dita.
   2. If there is no file extension, but the @href value is an absolute URI whose scheme is http or https, then the processing default is html.
   3. In all other cases where no file extension is available, the processing default is dita.

If the actual format of the referenced content differs from the effective value of the @format attribute, and a processor is capable of identifying such cases, it MAY recover gracefully and treat the content as its actual format. The processor MAY also issue a message.

The @href attribute specifies the URI of the resource that is addressed. The referenced resource can be another DITA topic or map, an element inside a DITA topic or map, or a non-DITA resource.

The value of the @href attribute MUST be a valid URI reference [RFC 3986]. If the value of the @href attribute is not a valid URI reference, an implementation MAY generate an error message. It MAY also recover from this error condition by attempting to convert the value to a valid URI reference.

The value of the @href attribute can optionally contain a fragment identifier.

When an @href attribute references a DITA resource using a URI without a fragment identifier, the URI resolves to the root element in the referenced document. For the purposes of rendering, such as when a topic reference to a DITA document is used to render the content as HTML, this means that all topics in the target document are included in the reference. For the purpose of linking, the reference resolves to the first topic in the document.

When an @href attribute references a DITA resource using a URI with a fragment identifier, the portion after the hash must be a DITA local identifier. A DITA local identifier takes the following forms:

Where:

• topicID is the value of the @id attribute of the DITA topic. If the topic referenced by a DITA local identifier is the same topic that includes the reference, then topicID can be replaced by a period.
• elementID is the value of the @id attribute of the non-topic element within a DITA topic.
• mapElementID is the value of the @id attribute of the element within a DITA map document.

See Processing xrefs and conrefs within a conref for more information on how this syntax relates to conref resolution.

The @scope attribute identifies the closeness of the relationship between the current document and the target resource.

The @scope attribute takes the following values:

external

Indicates that the resource is not part of the current set of content.

local

Indicates that the resource is part of the current set of content.

peer

Indicates one of the following:

• The resource is part of the current set of content, but it might not be accessible at build time.
• The resource should be treated as a root map for the purpose of creating map-to-map key references (peer maps).
• The resource is a peer map. If @keyscope is also specified on the reference, it indicates that the map should be treated as a separate deliverable for the purposes of linking.

-dita-use-conref-target

See Using the -dita-use-conref-target value for more information on -dita-use-conref-target

If no value is specified for the @scope attribute, the following considerations apply:

• If the @scope attribute is specified on a containing element within a map or within the related-links section, the value cascades from the closest containing element.
• In most cases, the processing default is local. However the processing default is external whenever the absolute URI in the @href attribute begins with one of the following schemes: http, https, ftp, or mailto

For the @scope attribute, processors can consider additional URI schemes as external by default. Processors MUST always consider relative URIs as local by default.

On linking elements, the @type attribute describes the target of a reference. The @type attribute is also used on several non-linking elements for other purposes.

This topic describes how to interpret the @type attribute when it is used on linking elements. Usage information for the @type attribute on other elements, such as <note> or <copyright>, is described in the element reference topics for those elements.

If the @type attribute is specified on a linking element that references DITA content, the attribute value should reflect the @class attribute of the referenced element. The value can be an unqualified local name, for example, fig, or a qualified name exactly as specified in the @class attribute, for example, topic/fig. Processors might ignore qualified names or consider only the local name.

If not explicitly specified on an element, the @type attribute value cascades from the closest containing element. If there is no explicit value for the @type attribute specified on an ancestor element, the processor should retrieve the type from the target resource, if it is available. If the type cannot be determined, the processing default is topic.

Applications MAY issue a warning when the specified or inherited @type attribute value does not match the target or a specialization ancestor of the target. Applications MAY recover from this error condition by using the correct value detected.

Only the <xref> element can link to content below the topic level. The other linking elements only can link to topics.

The following table lists values for the @type attribute that are commonly used on <xref> elements:

An application might generate cross-reference text that is based the value of the @format attribute.

-dita-use-conref-target is also a valid value for the @type attribute. See Using the -dita-use-conref-target value for more information.