XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (575 page)

Examples

See Also

days-from-duration()
on page 745

minutes-from-duration()
on page 832

seconds-from-duration()
on page 874

id

The
id()
function returns a sequence containing all the elements in a given document with given ID attribute values.

For example, if the
code
attribute is defined as an ID attribute, then the expression
id(‘A321-780’)
might return the single element

.

Changes in 2.0

A second optional argument has been added, to define which document is to be searched. The semantics of the function have been redefined in terms of the XPath 2.0 type system.

Signature

Effect

The function is designed to make it easy to find all the elements referenced in an element or attribute of type
xs:IDREF
or
xs:IDREFS
, but there is no requirement that it should be used this way. The rules are defined so that the supplied argument can be any of the following:

• A string containing an
  ID
  value
  
• A string containing a space-separated list of
  ID
  values
  
• A node containing an
  ID
  value
  
• A node containing a space-separated list of
  ID
  values
  
• A sequence of any of the above
  

Any nodes in the sequence are atomized as part of the function calling mechanism. The resulting strings are then tokenized by splitting their contents on whitespace boundaries. Each token is used as a candidate
ID
value. If there is a node in the selected document that has an
ID
attribute or
ID
content equal to this candidate
ID
value then this node is included in the result of the function.

The rules for this function say that the nodes that are selected must have the
is-id
property. There are various ways a node might acquire this property:

• With a schema-aware processor, an element or attribute acquires the
  is-id
  property if it is declared as having type
  xs:ID
  , or a type derived by restriction from
  xs:ID
  , or a complex type with simple content where the simple content is
  xs:ID
  or derived from
  xs:ID
  . (There's some ambiguity about list or union types constructed from
  xs:ID
  .)
  
• If the input document has a DTD, an attribute declared in the DTD as having type
  ID
  will normally acquire the
  is-id
  property. However this isn't 100% reliable; it may depend on how the XML parser has been configured, and some parsers don't report this information at all
  
• An attribute named
  xml:id
  will always have the
  is-id
  property.
  

By contrast, it is not necessary for the candidate
ID
s to be declared as type
IDREF
or
IDREFS
, though the function is designed to produce the expected result when they are, that is, it finds the nodes referenced by the
IDREF
or
IDREFS
values in the argument sequence.

It is not an error if there is no element with an
ID
equal to one of the candidate
ID
values. In this situation, there will simply be no node in the resulting sequence corresponding to this value. In the simplest case, where there is only one candidate
ID
value supplied, the resulting sequence will be empty if the
ID
is not present.

The second argument, if supplied, identifies the document to be searched. This does not have to be the document node, it can be any node within the target document. This argument defaults to the context node. Whether the argument is explicit or implicit, it must be a node in a tree whose root is a document node. If the argument is omitted, then a runtime error is reported if the context item is undefined, or if it is not a node. The nodes in the supplied
values
argument will often come from the same document, but this is not required.

IDs and Validation

ID
values only really work properly if the source document is valid (in the XML sense: meaning, loosely, that it obeys the rules in its own DTD or Schema). However, XPath is designed to allow invalid documents as well as valid ones to be processed. One possible kind of validity error is that
ID
values are not unique within the document. This is explicitly covered in the specification: the first node with that
ID
value is located. Other validity errors may also be present, for example an
ID
attribute may contain embedded spaces. In this case it will not be retrieved.

When no schema is used, a non-validating XML parser isn't required to read attribute definitions from an external DTD. In this situation the XSLT processor will assume there are no
ID
attributes present, and the
id()
function will always return an empty result. If this appears to be happening, check what options are available for configuring the XML parser, or try a different parser. Most good parsers will report the attribute type, even though it isn't absolutely required by the XML standard.

XML Schema introduces the ability for elements as well as attributes to be used as IDs, and the function supports this. There's a slight oddity, however. If the source document has an element of the form
...
, where
nr
is an
ID
attribute, then
id(‘e12345’)
will return the

element. However, if the source is
e12345....
, where
nr
is of type
xs:ID
, then
id(‘e12345’)
will return the

element, not the

.

Usage and Examples

The
id()
function provides an efficient means of locating nodes given the value of an
ID
attribute.

In a sense it is a convenience function, because if the attribute named
id
is always an
ID
attribute, then the expression:

is equivalent to the path expression:

However, the chances are that in most implementations, the
id()
function will be much more efficient than the straightforward path expression with a predicate, because the processor is likely to build an index rather than doing a sequential search.

In XSLT it is also possible to use
key()
in place of
id()
. The main advantage of the
id()
function over using
key()
is that it handles a whitespace-separated list of
ID
s in one go. The
key()
function cannot do this, because there is nothing to stop a key value containing a space.

The
id()
function when used with a single argument locates elements in the same document as the context node. XPath 2.0 provides two ways to locate elements in a different document. You can either use the
id()
function on the right-hand side of the
/
operator, for example
doc(“lookup.xml”)/id($param)
, or you can supply a second argument, like this:
id($param, doc(“lookup.xml”))
.