Some security service parameters accept an XPath expression to locate an element in the XML document. These parameters support the full syntax of the XPath engine that is selected by the XPath Version parameter. For convenience, the security services can construct the path to the element if it is not found in the XML document. This is useful to ensure that a parent element exists before a new XML child is inserted at that location. Unfortunately, XPath is ambiguous when describing the construction of a path. For example, the element name might be missing (/root/*), some parents might be unknown (//ds:Signature), or siblings might be unknown (/root/child[3]).

To allow the creation of the path, you must restrict the syntax to a subset of XPath 1.0. A Restricted XPath expression has the following form:

/step1/step2/...

A step has the following form:

ns:elem[predicate]

The predicate is optional and has the following form when it is present:

[@ns1:attr1='val1' and @ns2:attr2='val2' and ...]

The namespace prefixes are optional, but when present, they must be declared in the XML Namespace provider. To evaluate a step:

1. Look under the current node to find the first element named elem, in the namespace declared with the prefix ns, which has all the specified attributes equal to the given value.
2. If there is a match, make the child element the current node.
3. If there is no match, create a new child element with all the attributes assigned to the specified value and make the new child the current node.

Because Restricted XPath creates the missing nodes as it progresses, there is no backtracking to find alternative paths. Notice that the document root element cannot be constructed by Restricted XPath. This is to respect the XML limitation of a single root element in an XML document.

As a special case, a pair of consecutive steps can have the following form:

*[1]/self::ns:elem[predicate]

Similar to XPath 1.0, this indicates that the requested element must be the first child of its parent. If the first child does not match, then create a new child element as mentioned in step 3 and insert it first in the list of children.

The Create Parent Element parameter tells the service whether to construct the path leading to the parent element, and consequently tells the service which XPath syntax to accept. When the parameter is set to false, the full expressive power of the XPath engine is available. However, the parent element must already exist in the XML document, otherwise an exception is generated. When the parameter is set to true, the path to the element will be constructed if necessary, but the expression syntax must be Restricted XPath.

The following Restricted XPath expression can create a SOAP Header before an existing SOAP Body:

/soapenv:Envelope/*[1]/self::soapenv:Header/wsse:Security

It is sometimes desirable to create multiple WSSE Security Headers in the same document because they are destined for different actors. The services must choose the WSSE Security Header with the correct actor when inserting the new content. The solution is to write the XPATH expression with a predicate for the actor attribute. The following is an expression that selects the mandatory WSSE Security Header destined for the next role even if there are other WSSE Security headers present:

/soapenv:Envelope/*[1]/self::soapenv:Header/wsse:Security[soapenv:mustUnderstand='1' and
soapenv:actor='http://schemas.xmlsoap.org/soap/actor/next']

This expression is valid for full XPATH 1.0 or Restricted XPATH. When the Create Parent Element parameter is set to true and the WSSE Security Header is not found, then Restricted XPath creates a new WSSE Security Header and its two SOAP attributes.