Web Services Fragment (WS-Fragment)

1 Introduction

This specification extends the WS-Transfer specification and defines a mechanism that allows clients to retrieve and manipulate subsets of a WS-Transfer enabled resource without needing to include the entire XML representation in a message exchange.

This specification defines a fragment transfer mechanism, an extension framework for defining expression languages, and a set of expression languages.

The fragment transfer mechanism is defined as an extension to WS-Transfer. This involves defining a WS-Transfer Dialect and corresponding XML elements that go into the SOAP Body of the Get, Put, Delete and Create WS-Transfer operations. This fragment transfer mechanism is designed so that it can be used with any number of expression languages to indentify a subset of the resource the operation is to operate over.

While other specifications can define other expression languages, it is RECOMMENDED that those languages reuse the fragment transfer framework that this specification defines.

2 Terminology and Notation

http://www.w3.org/2009/02/ws-fra

<s:Envelope>
  <s:Header>
    [Headers]
    <wsa:Action>[Action]</wsa:Action>
    ...
  </s:Header>
  <s:Body>[Body]</s:Body>
</s:Envelope>

3 Fragment WS-Transfer Dialect

This section defines the fragment transfer mechanism that the expression languages defined in subsequent sections will use. The following sections define the expected behavior when the WS-Fragment Dialect is used in each of the WS-Transfer operations.

Each Expression language that uses this transfer fragment mechanism MUST fully define how it behaves for each operation and for the language specific expression constructs it supports. For example, an XPath language will need to explain how a new XML element is inserted into an existing resource.

WS-Transfer defines what the expected behavior of a resource is with respect to modifications of the resource that might result in an invalid state or if the client does not have the authority to perform such operations. This specification only extends but does not modify the base WS-Transfer behavior.

[Action]
  http://www.w3.org/2009/02/ws-tra/Get

[Body]
  <wst:Get Dialect="http://www.w3.org/2009/02/ws-frag" ...>
    <wsf:Expression Language="xs:anyURI" ...>
      xs:any *
    </wsf:Expression>
    xs:any *
  </wst:Get>

[Action]
  http://www.w3.org/2009/02/ws-tra/GetResponse

[Body]
  <wst:GetResponse ...>
    <wsf:Value> xs:any * </wsf:Value>
    xs:any *
  </wst:GetResponse>

[Action]
  http://www.w3.org/2009/02/ws-tra/Put

[Body]
  <wst:Put Dialect="http://www.w3.org/2009/02/ws-frag" ...>
    <wsf:Fragment ...>
      <wsf:Expression Language="xs:anyURI" ...>
        xs:any *
      </wsf:Expression> 
      <wsf:Value ...>
        xs:any *
      </wsf:Value> 
    </wsf:Fragment>
    xs:any *
  </wst:Put>

[Action]
  http://www.w3.org/2009/02/ws-tra/PutResponse

[Body]
  <wst:PutResponse ...>
    xs:any *
  </wst:PutResponse>

[Action]
  http://www.w3.org/2009/02/ws-tra/Delete

[Body]
  <wst:Delete Dialect="http://www.w3.org/2009/02/ws-frag" ...>
    <wsf:Expression Language="xs:anyURI" ...>
      xs:any *
    </wsf:Expression>
    xs:any *
  </wst:Delete>

[Action]
  http://www.w3.org/2009/02/ws-tra/DeleteResponse

[Body]
  <wst:DeleteResponse ...>
    xs:any *
  </wst:DeleteResponse>

[Action]
  http://www.w3.org/2009/02/ws-tra/Create

[Body]
  <wst:Create Dialect="http://www.w3.org/2009/02/ws-frag" ...>
    <wsf:Fragment ...>
      <wsf:Expression Language="xs:anyURI" ...>
        xs:any *
      </wsf:Expression> 
      <wsf:Value ...>
        xs:any *
      </wsf:Value> 
    </wsf:Fragment>
    xs:any *
  </wst:Create>

[Action]
  http://www.w3.org/2009/02/ws-tra/CreateResponse

[Body]
  <wst:CreateResponse ...>
    <wst:ResourceCreated> endpoint-reference </wst:ResourceCreated>
    xs:any *
  </wst:CreateResponse>

4 Examples

<ab:AddressBook xmlns:ab="http://example.com/address">
  <ab:owner>Me</owner>
  <ab:size>2</size>
  <ab:contact>
    <ab:name>Joe Brown</name>
    <ab:address>123 Main Street</address>
    <ab:city>AnyTown</city>
    <ab:state>CA</state>
    <ab:zip>90210</zip>
    <ab:email>joe@example.com</email>
  </ab:contact>
  <ab:contact>
    <ab:name>Mary Smith</name>
    <ab:address>345 South Pine</address>
    <ab:city>AnyTown</city>
    <ab:state>CA</state>
    <ab:zip>90210</zip>
    <ab:email>mary@example.com</email>
  </ab:contact>
</ab:AddressBook>

<s:Envelope  
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:wsa="http://www.w3.org/2005/08/addressing" 
    xmlns:ex="http://www.example.com/" >
  <s:Header>
    <wsa:To>http://www.example.org/resourceABC</wsa:To>
    <wsa:Action>
      http://www.w3.org/2009/02/ws-tra/Get
    </wsa:Action>
    <wsa:MessageID>
      uuid:00000000-0000-0000-C000-000000000046
    </wsa:MessageID>
  </s:Header>
  <s:Body>
    <wst:Get>
      <wsf:Expression Language=".../ws-frag/QName">
        ab:contact
      </wsf:Expression>
    </wst:Get>
  </s:Body>
</s:Envelope>

<s:Envelope  
    xmlns:s="http://www.w3.org/2003/05/soap-envelope" 
    xmlns:wsa="http://www.w3.org/2005/08/addressing" 
    xmlns:ex="http://www.example.com/" >
  <s:Header>
    <wsa:Action>
      http://www.w3.org/2009/02/ws-tra/GetResponse
    </wsa:Action>
    <wsa:MessageID>
      uuid:0000010e-0000-0000-C000-000000000047
    </wsa:MessageID>
    <wsa:RelatesTo>
      uuid:00000000-0000-0000-C000-000000000046
    </wsa:RelatesTo>
  </s:Header>
  <s:Body>
    <wst:GetResponse>
      <wsf:Value>
        <ab:contact>
          <ab:name>Joe Brown</name>
          <ab:address>123 Main Street</address>
          <ab:city>AnyTown</city>
          <ab:state>CA</state>
          <ab:zip>90210</zip>
          <ab:email>joe@example.com</email>
        </ab:contact>
        <ab:contact>
          <ab:name>Mary Smith</name>
          <ab:address>345 South Pine</address>
          <ab:city>AnyTown</city>
          <ab:state>CA</state>
          <ab:zip>90210</zip>
          <ab:email>mary@example.com</email>
        </ab:contact>
      </wsf:Value>
    </wst:GetResponse>
  </s:Body>
</s:Envelope>

5 QName Expression Language

The QName expression language is a syntax for expressions that uses a single QName to reference the immediate children of the root element of the resource representation. The expression MUST evaluate to zero or more elements, each including the element name, any attributes and its entire content. This language can be implemented as a precise subset of the XPath language.

The QName language MUST be indicated by using the URI:

http://www.w3.org/2009/02/ws-fra/QName

6 XPath Level 1 Expression Language

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, and is used to identify or select a node within a resource representation or fragment. It is identified by the following URI:

http://www.w3.org/2009/02/ws-fra/XPath-Level-1

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 nonterminal 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 subrange (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 SHOULD 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.

Expressions in this language MUST NOT evaluate to more than a single node. The XPath Level 1 language does not support computed values. Text and attribute nodes MUST be serialized using the same serialization as for the XPath 1.0 language.

7 XPath 1.0 Expression Language

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 URI:

http://www.w3.org/2009/02/ws-fra/XPath

Implementations that support the full XPath 1.0 language MUST support the XPath Level 1 language.

Note that the expression MAY 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. They 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="attribute name">
(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 name portion 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.

The WS-Fragment global element definition wsf:NodeSet can also be used as the wrapper element when serializing these node-sets outside of a WS-RT result.

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.

8 Faults

All fault messages defined in this specification MUST be sent according to the rules and usage described in [WS-Addressing 1.0 SOAP Binding] Section 6 for encoding SOAP 1.1 and SOAP 1.2 faults. The [Action] property below MUST be used for faults defined in this specification:

http://www.w3.org/2009/02/ws-fra/fault

The definitions of faults in this section use the following properties:

[Code] The fault code.
[Subcode] The fault subcode.
[Reason] The English language reason element.
[Detail] The detail element. If absent, no detail element is defined for the fault.

For SOAP 1.2, the [Code] property MUST be either "Sender" or "Receiver". These properties are serialized into text XML as follows:

The properties above bind to a SOAP 1.2 fault as follows:

<s12:Envelope>
   <s12:Header>
     <wsa:Action> [Action] </wsa:Action>
     <!-- Headers elided for brevity. -->
   </s12:Header>
   <s12:Body>
     <s12:Fault>
       <s12:Code>
         <s12:Value>[Code]</s12:Value>
         <s12:Subcode>
           <s12:Value>[Subcode]</s12:Value>
         </s12:Subcode>
       </s12:Code>
       <s12:Reason>
         <s12:Text xml:lang="en">[Reason]</s12:Text>
       </s12:Reason>
       <s12:Detail>
         [Detail]
         ...
       </s12:Detail>
     </s12:Fault>
   </s12:Body>
 </s12:Envelope>

The properties bind to a SOAP 1.1 fault as follows:

<s11:Envelope>
   <s11:Body>
     <s11:Fault>
       <faultcode>[Subcode]</faultcode>
       <faultstring xml:lang="en">[Reason]</faultstring>
       <detail>
         [Detail]
         ...
       </detail>
     </s11:Fault>
   </s11:Body>
 </s11:Envelope>

9 WS-Fragment Policy Assertion(s)

An endpoint MAY indicate that it supports WS-Fragment, or its features, by including the WS-Fragment Policy assertion(s) within its WSDL. By doing so the endpoint is indicating that the corresponding WS-Fragment operations are supported by that endpoint even though they do not explicitly appear in its WSDL.

10 Acknowledgements

This specification has been developed as a result of joint work with many individuals and teams, including: Ashok Malhotra (Oracle Corp.), Asir Vedamuthu (Microsoft Corp.), Bob Freund (Hitachi, Ltd.), Doug Davis (IBM), Fred Maciel (Hitachi, Ltd.), Geoff Bullen (Microsoft Corp.), Gilbert Pilz (Oracle Corp.), Greg Carpenter (Microsoft Corp.), Jeff Mischkinsky (Oracle Corp.), Katy Warr (IBM), Li Li (Avaya Communications), Mark Little (Red Hat), Prasad Yendluri (Software AG), Ram Jeyaraman (Microsoft Corp.), Sreedhara Narayanaswamy (CA), Sumeet Vij (Software AG), Vikas Varma (Software AG), Wu Chou (Avaya Communications), Yves Lafon (W3C)

11 References

RFC 2119

Key words for use in RFCs to Indicate Requirement Levels , S. Bradner, Harvard University, March 1997. (See http://www.ietf.org/rfc/rfc2119.txt.)

RFC 3986

Uniform Resource Identifier (URI): Generic Syntax , T. Berners-Lee, W3C/MIT, January 2005. (See http://www.ietf.org/rfc/rfc3986.txt.)

SOAP 1.1

Simple Object Access Protocol (SOAP) 1.1 , D. Box, et al, May 2000. (See http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.)

SOAP 1.2

SOAP Version 1.2 Part 1: Messaging Framework , M. Gudgin, et al, June 2003. (See http://www.w3.org/TR/soap12-part1/.)

WS-Addressing

W3C Recommendation, "Web Services Addressing 1.0 (WS-Addressing)" , May 2006. (See http://www.w3.org/2005/08/addressing/.)

WS-Addressing 1.0 SOAP Binding

W3C Recommendation, "Web Services Addressing 1.0 - SOAP Binding" , May 2006. (See http://www.w3.org/TR/2006/REC-ws-addr-soap-20060509.)

WS-Policy

W3C Recommendation, "Web Services Policy 1.5 - Framework" , September 2007. (See http://www.w3.org/TR/ws-policy/.)

WS-Transfer

W3C Working Group Draft, "Web Services Transfer" , July 2009. (See http://www.w3.org/2009/02/ws-tra.)

WSDL 1.1

Web Services Description Language (WSDL) 1.1 , E. Christensen, et al, March 2001. (See http://www.w3.org/TR/2001/NOTE-wsdl-20010315.)

XML Infoset

J. Cowan, et al, "XML Information Set" , February 2004. (See http://www.w3.org/TR/2004/REC-xml-infoset-20040204/.)

XML Schema, Part 1

XML Schema Part 1: Structures , H. Thompson, et al, October 2004. (See http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/.)

XML Schema, Part 2

XML Schema Part 2: Datatypes , James Clark, et al, November 1999. (See http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.)