Re: Why are key reference ID targets restricted to non-topics elements?

There are two reasons for the way key references work:

Topic references, which bind keys to resources, only address topics, not elements within topics, thus, keys defined on topic references can only be bound to DITA topics. Conversely, the only way to address a topic by key is to bind a key to that topic—you cannot address a literally-nested topic by key reference to an ancestor topic.
The ID name space for topics and the ID name space for elements within topics are separate ID name spaces. This means that the ID referenced on a key reference following the key can only refer to a non-topic element within the topic to which the key is bound.

For example, consider this topic, “topics/topic-01.dita”:

<topic id=”some-id”><title>Some Topic</title>
<body>

This paragraph has the ID value “some-id”

</body>

</topic>

And these topicrefs in some map:

And this key reference from topic topic-02.dita:

See <xref keyref=”topic-01/some-id”/>.

In the context of this map, the key reference “topic-01” resolves to the topic “topics/topic-01.dita” and the ID reference “some-id” can only resolve the non-topic element with the ID “some-id”—it could never refer to the topic element that happens to also have the ID value “some-id”.

This is also why you can’t use a key reference to a parent topic to refer to a child topic—the child topic must have its own key definition.

Within DITA topics, each topic defines a separate ID space, separate from the ID of the topic element itself and separate from the IDs of any nested topics. The @id attribute on topics is defined as type ID, meaning the IDs must be unique within the XML document that contains the topic, the but @id attribute on non-topic elements is defined as type NAME, so they do not have the usual uniqueness requirements of attributes of type ID.

As further example, consider this topic with a nested topic:

<topic id=”some-id”><title>Root Topic</title>

<body>

This paragraph has the ID value “some-id”

</body>

<topic id=”some-other-id”><title>Nested Topic</title>

<body>

This paragraph has the ID value “some-id”

</body>

</topic>

Here the two topic elements must have distinct @id values (“some-id” and “some-other-id”) but the elements within them can both have the ID value “some-id” because each topic establishes a separate ID name space, so there is no conflict with either the root topic’s @id value or the two elements with the same @id value in two different topics.

Using the same @id value on non-topic elements within the same topic is an error per the DITA specification, but one that will not be detected by normal grammar validation. Within a topic, the first @id in document order with a given value is used as the target.

Cheers,

Eliot Kimber

Member, DITA Technical Committee

Original request:

Chris Trenkamp writes (https://lists.oasis-open.org/archives/dita-comment/202304/msg00000.html)

For references to non-topic elements within topics, the value of the @keyref attribute is a key name, a slash ("/"), and the ID of the target element (for example, keyref="topic-key/some-element-id".)

http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/archSpec/base/using-keys-for-addressing.html

Why are keyref ID targets limited to non-topic elements? I can’t find an explanation for this in the specification, and I can’t think of a reason why this restriction would be in place.

In fact, this restriction seems to operate in direct contradiction to how the id attribute operates:

http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part3-all-inclusive/archSpec/base/id.html

The specification states that id attributes on topic elements are XML attribute type ID’s, so they are strictly required to be unique by the XML parser. All other id’s only have to be unique within the topic they are declared in.

It’s entirely possible to create a key reference to an element id that was declared multiple times in different sub-topics. I haven’t found anything in the specification that states how key references to an ID target that was redeclared multiple times is supposed to be resolved. Does it take the first one? Does it throw an error? Is it up to the individual processor?

At the very least, topic id’s are required to be unique by the XML parser, so you can be confident that when you create a key reference with an ID target to a topic, you know that target is unique.

Can someone explain why this restriction is in place? Is the reasoning still relevant?

_____________________________________________

Eliot Kimber

Sr Staff Content Engineer

O: 512 554 9368

M: 512 554 9368

servicenow.com

LinkedIn | Twitter | YouTube | Facebook

dita-comment message