2.4 XPath 1.0-Derived Selection Language

Some Web Service protocols in the ADWS protocol set require the use of a selection language to specify which portion of the directory object to operate on. In other words, the selection language permits the requestor to specify that only certain attributes are to be retrieved from the directory object (rather than every attribute) or to specify that a particular attribute or attribute value is to be added, replaced, or removed from a directory object.

The ADWS protocol set uses a selection language that is derived from XPath 1.0 [XPATH] for this purpose. This selection language is applied to the XML view (described in section 2.3.2) of the directory object. A compliant implementation need only implement the subset of the language described in this section. This derived language is identified by the following URI:

http://schemas.microsoft.com/2008/1/ActiveDirectory/Dialect/XPath-Level-1

For simplicity, this language will be referred to as "XpathSelection" in the remainder of this section.

The grammar for XpathSelection is shown below in ABNF notation.

 XpathSelection = (root elements)
 root = "/"
 elements = (element [additional-element] [selection-predicate])
 additional-element = ("/" element)
 element = QName
 selection-predicate = ("[" value-element "=" value "]")
 value-element = (Prefix ":value") / "value"
 value = qdstring

Where qdstring is defined in [RFC2252] section 4.1 and QName and Prefix are defined in [XMLNS-2ED] section 4.

The value-element is the string literal "value" qualified with an XML namespace prefix that corresponds to the XML namespace URI "http://schemas.microsoft.com/2008/1/ActiveDirectory" in the scope of the XML node in which the XpathSelection expression appears. This is illustrated in the following example.

 <node1 xmlns:ad="http://schemas.microsoft.com/2008/1/ActiveDirectory">
     /element1/element2[ad:value="abc"]
 </node1>

Without the selection-predicate, an XpathSelection expression is analogous to an XPath 1.0 absolute location path with one or two location steps along the child axis. The expression "/X" selects the XML element named "X" whose parent is the root node of the XML document. The expression "/X/Y" selects the XML element named "Y" whose parent is the XML element named "X" whose parent, in turn, is the root node of the document. For example, given the following XML document:

 <addata:user>
     <addata:description LdapType="UnicodeString">
         <ad:value xsi:type="xsd:string">
             First sample description
         </ad:value>
         <ad:value xsi:type="xsd:string">
             Second sample description
         </ad:value>
     </addata:description>
 </addata:user>

The XpathSelection expression "/addata:user" selects the entire <addata:user> element (including child elements), while the XpathSelection expression "/addata:user/addata:description" selects the following portion.

 <addata:description LdapType="UnicodeString">
     <ad:value xsi:type="xsd:string">
         First sample description
     </ad:value>
     <ad:value xsi:type="xsd:string">
         Second sample description
     </ad:value>
 </addata:description>

However, unlike an XPath 1.0 expression, the comparison of the LocalPart of the QName is done in a case-insensitive manner. For example, the following XpathSelection expressions are equivalent:

/addata:user/addata:description

/addata:USER/addata:DESCRIPTION

/addata:User/addata:Description

The inclusion of a selection-predicate allows an individual <ad:value> element to be specified. The predicate "[ad:value="X"]" matches the <ad:value> element whose child text node is equal to "X". The equality comparison is done using a comparison operation appropriate to the attribute syntax of the directory attribute, as specified in [MS-ADTS] section 3.1.1.2.2.4 (for example, values for attributes that are of type String(case) in the directory are compared using a case-insensitive string comparison, while values of type Integer are compared as integers).

Using the previous XML document, the XpathSelection expression "/addata:user/addata:description[ad:value="First sample description"]" selects the following portion.

 <ad:value xsi:type="xsd:string">
     First sample description
 </ad:value>