The XPath Level 1
expression language uses an XPath to reference
specific fragments of the resource representation. The XPath
is logically applied to the XML representation of the resource and the
resulting node-set is the resource fragment which is the subject of the message
containing the expression. This language is useful for resources with limited XPath processing capability which do not need to support
returning values computed from their resource representation.
XPath Level 1 is a subset of the abbreviated
relative syntax of XPath 1.0 [XPath1.0], and is used to identify or select a node
(element, attribute or value) within a resource representation or fragment. It
is identified by the following IRI:
An XPath Level 1 expression is
an expression whose context is:
·
Context Node: the root element of the XML
representation of the resource
·
Context Position: 1
·
Context Size: 1
·
Variable Binding: None
·
Node Tests: NameTest
and the text NodeType
·
Function Libraries: None
·
Namespace Declarations: Any namespace
declarations in-scope where the XPath expression
appears
An implementation that uses the XPath
Level 1 language MUST support the expressions whose syntax is described by the
following BNF. It MAY support additional expressions defined by XPath 1.0. The following XPath
Level 1 grammar is LL(1), and the non-terminal productions
are in angle brackets. Terminal symbols are either literals, or in UPPERCASE:
(01) <xpath> ::=
<context> <node_sequence>;
(02)
(03) <context>
::= '/' | <>;
(04)
(05) <node_sequence> ::=
(06) <element>
<optional_collection_operator> <more>;
(07)
(08) <optional_collection_operator> ::= '[' <array_location>
']';
(09) <optional_collection_operator> ::= <>;
(10)
(11) <more>
::= '/' <follower> | <>;
(12)
(13) <follower>
::=
(14) <attribute>
| <text_function> | <node_sequence>;
(15)
(16) <element>
::=
<qualified_name>;
(17) <attribute> ::= '@' <qualified_name>;
(18)
(19) <qualified_name> ::= <name> <qname_follower>;
(20) <qname_follower> ::= ':' <name> | <>;
(21) <text_function> ::=
"text()" ;
(22) <array_location> ::= NONZERO_DECIMAL_UNSIGNED_INTEGER;
(23) <name>
::= XML_TOKEN;
The terminal tokens which require further lexical
specification are NONZERO_DECIMAL_UNSIGNED_INTEGER, whose values are in the
sub-range (1...4294967295), and XML_TOKEN whose values are equivalent to those
for the XML Schema type xs:token. This grammar is small enough that
it can be easily implemented in resource-constrained implementations.
The following comments on the grammar will clarify
certain constructs within the BNF.
Most of the examples assume the following XML sample
acting as a "resource" document:
(01) <a>
(02) <b>
(03) <c
d="30"> 20 </c>
(04) </b>
(05) <e>
(06) <f/>
(07) <f/>
(08) </e>
(09) </a>
The context and document root node need clarification. XPath Level 1 assumes that the root is the root node of the
resource document, not the SOAP envelope or any other wrapper element which
might contain the resource.
Further, the default context is the root element and the
context position is 1.
In view of this, the / operator selects the containing
root, and the only valid operand which can follow it is the outermost element
of the resource:
(01) /a
The following paths are equivalent:
(01) /a/b
(02) b
Note that because the context node is the root element, a
relative path selects a matching child element.
The <node_sequence>
production provides the recursive behavior for the XPath:
(01) /a/b/c
(02) b/c
It also provides for selecting specific repeated elements
through the <optional_collection_operator>
production:
(01) /a/e/f[2]
The collection operator only takes unsigned nonzero
values, as defined above for NONZERO_DECIMAL_UNSIGNED_INTEGER. Thus, [1] is the
first of a repeating series of elements.
The <qualified_name>
production allows the XML naming tokens to be either namespace-qualified or
unqualified:
(01) /ns1:a/ns2:b/c
The namespace bindings are evaluated against any
namespace declarations that are in scope where the XPath
appears within the SOAP message.
NOTE: If the element name is unqualified, i.e. appears
without a namespace prefix, then the element name MUST be matched against a
matching element name in the resource document, regardless of namespace
bindings that are in effect, including default bindings. This allows
implementations to simply match element names in the majority of cases. If
namespace bindings are significant for all elements, then qualified names MUST
be used.
The <follower> production allows for special-casing
of the final tokens of the XPath allowing it to end
in either an attribute or text.
The text() NodeTest
MAY be applied as a final token to the selected element. This NodeTest selects any text nodes that are children of the
selected element. If the element only contains text content, the return value
will be a node-set containing a single text node.
(01) b/c/text()
The above expression would return a node-set containing a
single text node with the value 20
as its result. This text node would then be serialized into the
following XML representation:
(01) <wsf:TextNode>20</wsf:TextNode>
If accessed, attributes MUST be the final token in the
path and they MAY be namespace-qualified or unqualified names, as required:
(01) /a/b/c/@d
The above expression would return a node-set containing a
single attribute node with the value d="30"
as its result. This attribute node would then be serialized into the following
XML representation:
(01) <wsf:AttributeNode name="d">30</wsf:AttributeNode>
Selection of an element returns the element and its
entire content. The path /a/b
executed against the sample XML returns a node-set containing a
single element node which serializes directly:
(01) <b> <c d="30"> 20
</c> </b>
In the event that there is more than one node which would
match the XPath, the implementation MUST select or
return the first node only. This allows simple implementations to avoid the
overhead of checking the remainder of the resource document for a possible
match.
Conformant implementations MAY supply additional
functions and capabilities, but MUST adhere to the minimum behavior described
above.
The XPath Level 1 language does
not support computed values. Text and attribute nodes MUST be serialized in the GetResponse messaging using the same
serialization as for the XPath 1.0 language. This serialization mechanism MUST
NOT be used in the PutRequest
message.
The XPath 1.0
expression language uses an XPath to reference
specific fragments of the resource representation. The XPath
is logically applied to the XML representation of the resource and the result
of the XPath is returned as the value for that
expression. The XPath 1.0 language supports a wider
set of XPath function libraries than the XPath Level 1 language. This language is useful for resources
with full XPath processing capability or which need
to support returning values computed from their resource representation.
An XPath 1.0
expression is an expression whose context is:
·
Context Node: the root element of the XML
representation of the resource
·
Context Position: 1
·
Context Size: 1
·
Variable Binding: None
·
Function Libraries: Core function library
·
Namespace Declarations: Any namespace
declarations in-scope where the XPath expression
appears
The XPath 1.0
language can define references to any element, attribute or value in the
resource representation and can also be used to compute values from the
resource representation.
The XPath 1.0
language MUST be indicated by using the IRI:
Implementations that support the full XPath
1.0 language MUST support the XPath Level 1 language.
An XPath
1.0 expression MAY evaluate to multiple nodes; because of this the XPath 1.0 language MUST NOT be used with a "Put"
or "Create" operation.
The remainder of this section
defines an XML serialization mechanism that MUST be used when constructing a GetResponse message. Since the PutRequest message MUST NOT be used
to modify more than one target, these serialization rules MUST NOT be used in a PutRequest message.[DD1] . ENote that the expressions MUSTMAY
evaluate to one of four possible types: a node-set, a Boolean, a number or a
string. The latter three types are the results of evaluating a computed expression.
When they appear in a GetResponse
message. tThey
are serialized by performing the following conversion and then wrapping the
result in the wsf:Value element:
·
Boolean - converted to an xs:boolean
·
string - convert to an xs:string
·
number - convert to an xs:double
A node-set is zero or more elements, attributes or text
values of elements. A node-set is serialized into XML by concatenating each
node and enclosing it in the wsf:Value
wrapper XML element for which schema validation is suppressed. Element nodes in
a node-set are serialized directly into their XML representation. For
attributes and text nodes in the node-set, a wrapper element is used to enclose
these values to distinguish them from other such nodes in the serialized
result.
Attribute nodes in XPath are
represented in the following form:
name="value"
Serialization of an attribute node separates the name
from the value using the following element:
(01) <wsf:AttributeNode name="xs:QName">
(02) attribute value
(03) </wsf:AttributeNode>
The following describes additional constraints on the
outline listed above:
wsf:AttributeNode
This element is used to serialize an
attribute node in a node-set and MUST contain the value portion of the
attribute node.
wsf:AttributeNode/@name
This attribute MUST be the qualified name of
the attribute node.
Text nodes are serialized in the following form:
(01) <wsf:TextNode>
(02) text value
(03) </wsf:TextNode>
The following describes additional constraints on the
outline listed above:
wsf:TextNode
This element is used to serialize a text node
in a node-set and MUST contain the text value.
Given the following XML as an example
document.
(01) <a xmlns="example">
(02) <b>1</b>
(03) <c
x="y">2</c>
(04) </a>
The result of the XPath
"/a/b | /a/b/text() | /a/c/@x" would be
serialized as the following:
(01) <wsf:Value>
(02) <b>1</b>
(03) <wsf:TextNode>1</wsf:TextNode>
(04) <wsf:AttributeNode name="x">y</wsf:AttributeNode>
(05) </wsf:Value>
The nodes in the node-set MAY be serialized in any order.
An XPath 1.0 expression
MAY evaluate to multiple nodes; because of this the XPath 1.0 language MUST NOT
be used with a "Put" or "Create" operation.
[DD1]This sentence will only be included if we modify the previous paragraph so that XPath 1.0 can be used for Put. If not, then remove this sentence.