W3C

Web Services Fragment (WS-Fragment)

W3C Proposed Recommendation 27 September 2011

This version:
http://www.w3.org/TR/2011/PR-ws-fragment-20110927
Latest version:
http://www.w3.org/TR/ws-fragment
Previous version:
http://www.w3.org/TR/2011/CR-ws-fragment-20110428
Editors:
Doug Davis, IBM
Ashok Malhotra, Oracle
Katy Warr, IBM
Wu Chou, Avaya

Abstract

This specification extends the WS-Transfer [WS-Transfer] specification to enable clients to retrieve and manipulate parts or fragments of a WS-Transfer enabled resource without needing to include the entire XML representation in a message exchange.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

The W3C Membership and other interested parties are invited to review the document and send comments to the Working Group's public mailing list public-ws-resource-access-comments@w3.org mailing list (public archive) until 4 November 2011. See W3C mailing list and archive usage guidelines. Advisory Committee Representatives should consult their WBS questionnaires.

No substantive changes were made as a result of the Candidate Recommendation phase (see also diff, test scenario and implementation report).

A Proposed Recommendation is a specification that is under review by the W3C Advisory Committee for endorsement as a W3C Recommendation. It is is a mature document that has been widely reviewed and has been shown to be implementable. W3C encourages everybody to implement this specification.

Publication as a Proposed Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

It has been produced by the Web Services Resource Access Working Group (WG), which is part of the W3C Web Services Activity.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1 Composable Architecture
2 Introduction
   2.1 Requirements
3 Terminology and Notation
   3.1 Notational Conventions
   3.2 Considerations on the Use of Extensibility Points
   3.3 Terminology
   3.4 Compliance
   3.5 XML Namespaces
4 Fragment WS-Transfer Dialect
   4.1 Identification of a Resource Subset
   4.2 Fragment Serialization
   4.3 Get
   4.4 Put
   4.5 Delete
   4.6 Create
5 Examples
   5.1 Examples
6 QName Expression Language
7 XPath 1.0 Expression Language
8 XPath 2.0 Expression Language
9 Faults
   9.1 UnsupportedLanguage
   9.2 InvalidExpression
   9.3 UnsupportedMode
10 WS-Fragment Metadata
   10.1 Fragment Assertion
11 Acknowledgements
12 References
   12.1 Normative References

Appendices

A XML Schema
B Change Log


1 Composable Architecture

By using the XML, SOAP [SOAP11], [SOAP12], and WSDL [WSDL11] extensibility models, the Web service specifications (WS-*) are designed to be composed with each other to provide a rich set of tools for the Web services environment. This specification specifically relies on other Web service specifications to provide secure, reliable, and/or transacted message delivery and to express Web service and client policy.

2 Introduction

This specification extends the WS-Transfer specification and defines a mechanism that allows clients to retrieve and manipulate subsets (parts or fragments) 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 and Put 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 on.

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

2.1 Requirements

This specification intends to meet the following requirements:

  • Provide an extension mechanism to WS-Transfer that allows for subsets (parts or fragments) of a resource to be retrieved or modified.

  • Provide an extension framework for defining expression languages.

  • Provide a set of expression languages that implementations can leverage.

3 Terminology and Notation

3.1 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC 2119].

This specification uses the following syntax to define outlines for messages:

  • The syntax appears as an XML instance, but values in italics indicate data types instead of literal values.

  • Characters are appended to elements and attributes to indicate cardinality:

    • "?" (0 or 1)

    • "*" (0 or more)

    • "+" (1 or more)

  • The character "|" is used to indicate a choice between alternatives.

  • The characters "(" and ")" are used to indicate that contained items are to be treated as a group with respect to cardinality or choice.

  • The characters "[" and "]" are used to call out references and property names.

  • Ellipsis (i.e. "...") indicate points of extensibility.

  • XML namespace prefixes (see Table 3-1) are used to indicate the namespace of the element being defined.

In addition to Message Information Header properties [WS-Addressing], this specification uses the following properties to define messages:

[Headers]

Unordered message headers.

[Action]

The value to be used for the wsa:Action IRI.

[Body]

A message body.

These properties bind to a SOAP Envelope as follows:

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

This specification can be used in terms of XML Information Set (Infoset) [XML Infoset], even though the specification uses XML 1.0 terminology. Valid Infoset for this specification is the one serializable in XML 1.0, hence the use of XML 1.0.

The term "generate" is used in relation to the various faults defined by this specification to imply that a fault is produced and no further processing SHOULD be performed. In these cases the fault SHOULD be transmitted. However, there might be reasons when a compliant implementation can choose not to transmit the fault - for example, security concerns - in these situations the service MAY choose not to transmit the fault.

In the outlines, bold text is used to indicate those parts of the message that are defined as part of this specification and are extensions to the WS-Transfer messages.

3.2 Considerations on the Use of Extensibility Points

The elements defined in this specification MAY be extended at the points indicated by their outlines and schema. Implementations MAY add child elements and/or attributes at the indicated extension points but MUST NOT contradict the semantics of the parent and/or owner, respectively. If a receiver does not recognize an extension, the receiver SHOULD ignore that extension. Senders MAY indicate the presence of an extension that has to be understood through the use of a corresponding SOAP Header with a soap:mustUnderstand attribute with the value "1".

In cases where it is either desirable or necessary for the receiver of a request that has been extended to indicate that it has recognized and accepted the semantics associated with that extension, it is RECOMMENDED that the receiver add a corresponding extension to the response message. The definition of an extension SHOULD clearly specify how the extension that appears in the response correlates with that in the corresponding request.

Extension elements and attributes MUST NOT use the Web Services Fragment namespace URI.

3.3 Terminology

Expression

A Language specific set of tokens that resolves to a location in a resource that contains a subset of the resource.

Fragment

A subset of a resource.

3.4 Compliance

An implementation is not compliant with this specification if it fails to satisfy one or more of the MUST or REQUIRED level requirements defined herein. A SOAP Node MUST NOT use the XML namespace identifier for this specification (listed in 3.5 XML Namespaces) within SOAP Envelopes unless it is compliant with this specification.

Normative text within this specification takes precedence over the XML Schema and WSDL descriptions, which in turn take precedence over outlines, which in turn take precedence over examples.

All messages defined by this specification MUST conform to the WS-Addressing specifications and be sent to a Web service that is addressable by an EPR (see [WS-Addressing]).

Unless otherwise noted, all IRIs are absolute IRIs and IRI comparison MUST be performed according to [RFC 3987] section 5.3.1.

For any message defined by this specification, any OPTIONAL elements or attributes in the message MAY be used by senders of the message; however receivers of those messages MUST support those OPTIONAL elements and attributes, unless other behavior is explicitly defined by this specification.

Implementations are expected to support both UTF-8 and UTF-16 as described in XML 1.0.

Implementations of this specification MUST conform to the corrected version of WSDL as defined by the 'WSDL Correction' sections of WS-I Basic Profile 1.2 [BP12] and WS-I Basic Profile 2.0 [BP20].

3.5 XML Namespaces

The XML Namespace URI that MUST be used by implementations of this specification is:

Table 3-1 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.

Table 3-1: Prefixes and XML Namespaces used in this specification.
Prefix XML Namespace Specification(s)
wsf http://www.w3.org/2011/03/ws-fra This specification
s Either SOAP 1.1 or 1.2 SOAP
s11 http://schemas.xmlsoap.org/soap/envelope/ [SOAP11]
s12 http://www.w3.org/2003/05/soap-envelope [SOAP12]
wsa http://www.w3.org/2005/08/addressing [WS-Addressing]
wst http://www.w3.org/2011/03/ws-tra [WS-Transfer]
wsp http://www.w3.org/ns/ws-policy [WS-Policy]
xs http://www.w3.org/2001/XMLSchema XML Schema [XMLSchema - Part 1], [XMLSchema - Part 2]

The working group intends to update the value of the Web Services Fragment namespace URI each time a new version of this document is published until such time that the document reaches Candidate Recommendation status. Once it has reached Candidate Recommendation status, the working group intends to maintain the value of the Web Services Fragment namespace URI that was assigned in the Candidate Recommendation unless significant changes are made that impact the implementation or break post-CR implementations of the specification. Also see http://www.w3.org/2001/tag/doc/namespaceState.html and http://www.w3.org/2005/07/13-nsuri .

4 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.

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.

4.1 Identification of a Resource Subset

The WS-Fragment Dialect is used to identify a portion of a resource representation to update. The WS-Transfer Get and Put operations have an Expression that allows a requester to specify which subset of the resource is being modified. Except in the cases listed below, the Expression MUST evaluate to a single node within the representation. This avoids any issues that might occur due to updating multiple portions of a resource within one invocation - in other words, "batching" is prohibited. There are however a few special cases that need to be taken into account:

  • An Expression that evaluates to the root of the resource representation might not result in any nodes being returned from the Expression processor. For example, an XPath expression of "/" on an empty resource would return an empty node-set. However, to allow for requesters to specify the root (implying the entire document), Expression Languages (and supporting services) that wish to support this concept might need to make special allowances for this situation. Each Expression Language would need to call out this special expression.

  • While WS-Fragment doesn't support batching, there are times when a requester might need to act upon an entire sequence of elements (i.e. a list of elements of the same QName that are all siblings). For example, a requester wanting to delete all children of an element. Rather than requiring the requester to send a series of WS-Transfer Put requests to delete each individual child element, WS-Fragment allows for Expression Languages (and services) to identify and act upon the sequence as one entity.

If an Expression does evaluate to more than one node then, except for the cases listed above, the implementation MUST process only the first selected node.

For the purposes of this specification, attributes are treated as single strings - multi-value attributes are not supported.

4.2 Fragment Serialization

When using the WS-Fragment Dialect, subsets of resource representations are serialized into the Get response and Put request messages. To ensure that the receiver of those messages can unambiguously parse the data into the proper XML entities, this specification defines the following rules for serializing XML fragments.

Expressions MUST 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 message they are serialized by performing the following conversion and then wrapping the result in the wsf:Value element:

  • Boolean - converted to an xs:boolean

  • Number - converted to an xs:double

  • String - converted to an xs:string

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.

The namespace bindings are evaluated against any namespace declarations that are in scope where the expression appears within the SOAP message. Note that the evaluation of expressions that rely on such context dependent bindings is fragile in the face of transformations that alter namespace prefixes. Such transformations might occur during the transmission, processing, storage, or retrieval of a request. Clients that wish to isolate expressions from the effects of any changes to the namespace prefixes in the containing SOAP message are advised to construct expressions in a manner that avoids the use of namespace prefixes. For example, use an expression such as "/a[namespace-uri()='http://www.example.com']" not "/ns1:a".

4.3 Get

To retrieve a subset of a resource a client MUST specify the WS-Fragment Dialect IRI in the wst:Get request.

The Get request message MUST be of the following form:

[Action]
  http://www.w3.org/2011/03/ws-tra/Get

[Body]
  <wst:Get Dialect="http://www.w3.org/2011/03/ws-fra" ...>
    <wsf:Expression Language="xs:anyURI"? ...>
      xs:any *
    </wsf:Expression>
    
    xs:any *
  </wst:Get>

The following describes additional, normative constraints on the outline listed above:

[Body]/wst:Get@Dialect

This attribute MUST be set to http://www.w3.org/2011/03/ws-fra.

[Body]/wst:Get/wsf:Expression

This element identifies which fragment in the resource this operation applies to. If the value of this element does not conform to the syntax of the language specified in the Language attribute, or is semantically invalid, a wsf:InvalidExpression fault MUST be generated.

[Body]/wst:Get/wsf:Expression@Language

Implied value is "http://www.w3.org/2011/03/ws-fra/XPath10".

This OPTIONAL IRI indicates which expression language will be used to identify the subset of the resource this operation applies to. A resource MUST generate a wsf:UnsupportedLanguage Fault if it does not support the specified Language.

If the resource accepts a Get request, it MUST reply with a response of the following form:

[Action]
  http://www.w3.org/2011/03/ws-tra/GetResponse

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

The following describes additional, normative constraints on the outline listed above:

[Body]/wst:GetResponse/wsf:Value

This element encompasses the fragment response corresponding to the wsf:Expression in the request and MUST contain the subset of the resource identified by the wsf:Expression element in the corresponding Get request. If the Expression evaluates to a fragment with no value, then this element MAY be empty.

Other components of the outline above are not further constrained by this specification.

4.4 Put

To update a subset of a resource a client MUST specify the WS-Fragment IRI in the wst:Put request.

The Put request message MUST be of the following form:

[Action]
  http://www.w3.org/2011/03/ws-tra/Put

[Body]
  <wst:Put Dialect="http://www.w3.org/2011/03/ws-fra" ...>
    <wsf:Fragment ...>
      <wsf:Expression Language="xs:anyURI"? Mode="xs:anyURI"? ...>
        xs:any *
      </wsf:Expression> 
      <wsf:Value ...>
        xs:any *
      </wsf:Value> ?
    </wsf:Fragment>
    
    xs:any *
  </wst:Put>

The following describes additional, normative constraints on the outline listed above:

[Body]/wst:Put@Dialect

This attribute MUST be set to http://www.w3.org/2011/03/ws-fra.

[Body]/wst:Put/wsf:Fragment

This element contains an expression that identifies the location of a fragment in the resource and a value for the fragment.

[Body]/wst:Put/wsf:Fragment/wsf:Expression

This element identifies which fragment in the resource this operation applies to. If the value of this element does not conform to the syntax of the language specified in the Language attribute, or is semantically invalid, a wsf:InvalidExpression fault MUST be generated.

[Body]/wst:Put/wsf:Fragment/wsf:Expression@Language

Implied value is "http://www.w3.org/2011/03/ws-fra/XPath10".

This OPTIONAL IRI indicates which expression language will be used to identify the subset of the resource this operation applies to. A resource MUST generate a wsf:UnsupportedLanguage fault if it does not support the specified Language.

[Body]/wst:Put/wsf:Fragment/wsf:Expression@Mode

This OPTIONAL attribute indicates the type of update to be performed on this fragment. The implied value for this attribute is "http://www.w3.org/2011/03/ws-fra/Modes/Replace". A resource MUST generate a wsf:UnsupportedMode fault if the specified Mode is not supported.

[Body]/wst:Put/wsf:Fragment/wsf:Expression@Mode="http://www.w3.org/2011/03/ws-fra/Modes/Replace"

This Mode value indicates that the children of the Value element MUST be added to the resource representation in place of the fragment referenced by the children of the Expression element.

This Mode value has the net effect of doing a "delete" on the referenced fragment, followed by an "insert" on the fragment's parent.

If the fragment is absent, or if the Expression evaluates to an empty fragment, then the "delete" portion of the operation MUST have no effect. If the implementation is schema aware and it detects that the Expression is not valid per the schema then a wsf:InvalidExpression fault MUST be generated.

When this Mode value is used the Value element MUST be present.

[Body]/wst:Put/wsf:Fragment/wsf:Expression@Mode="http://www.w3.org/2011/03/ws-fra/Modes/Add"

This Mode value indicates that the children of the Value element MUST be added to the resource representation relative to the fragment referenced by the children of the Expression element.

If the Value element contains an attribute node then the attribute MUST be added to the referenced element. If an attribute with that name already exists then a wst:InvalidRepresentation fault MUST be generated.

If the Value element contains a fragment that is not an attribute node, the children of the Value element are added as children to the referenced fragment.

When adding a child element and a child element of that QName already exists, the new element MUST be added to the end of that sequence of child elements. If the requester wants to ensure that only a single instance of that child element is present it can use the "Replace" instead.

While schema validation is not required of resource managers, since resources are only allowed to have a single root element, attempts to "Add" a second root element MUST generate a wst:InvalidRepresentation fault.

When this Mode value is used the Value element MUST be present.

[Body]/wst:Put/wsf:Fragment/wsf:Expression@Mode="http://www.w3.org/2011/03/ws-fra/Modes/InsertBefore"

This Mode value indicates that the children of the Value element MUST be inserted immediately before (as a sibling to) the fragment referenced by the children of the Expression element. Note, this Mode MUST NOT be used for attributes.

If the implementation is schema aware and it detects that the Expression does not reference a sequence then it MUST generate a wst:InvalidRepresentation fault.

When this Mode value is used the Value element MUST be present.

[Body]/wst:Put/wsf:Fragment/wsf:Expression@Mode="http://www.w3.org/2011/03/ws-fra/Modes/InsertAfter"

This Mode value indicates that the children of the Value element MUST be inserted immediately after (as a sibling to) the fragment referenced by the children of the Expression element. Note, this Mode MUST NOT be used for attributes.

If the implementation is schema aware and it detects that the Expression does not reference a sequence then it MUST generate a wst:InvalidRepresentation fault.

When this Mode value is used the Value element MUST be present.

[Body]/wst:Put/wsf:Fragment/wsf:Expression@Mode="http://www.w3.org/2011/03/ws-fra/Modes/Remove"

This Mode value indicates that the resource representation referenced by the children of the Expression element MUST be deleted from the resource representation. If the target fragment is not present then this operation MUST have no effect.

When this Mode value is used the Value element MUST NOT be present.

[Body]/wst:Put/wsf:Fragment/wsf:Value

This OPTIONAL element contains the fragment resource representation to be added to the resource representation. If the contents of this element are invalid, a wst:InvalidRepresentation fault MUST be generated.

Any optional values (element or attributes) within this subset that are not specified in the Value element MUST be set to a resource-specific default value.

The children of this element MUST be serialized according to the rules defined in 4.2 Fragment Serialization.

If the resource accepts a Put request, it MUST reply with a response of the following form:

[Action]
  http://www.w3.org/2011/03/ws-tra/PutResponse

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

There are no additional constraints beyond what WS-Transfer defines.

The following table elaborates on the expected behavior of a WS-Fragment Put request using the XPath language.

Given a resource whose schema is defined as:

<a foo="xs:integer"? bar="xs:integer"? >
  ( <b> <c/> </b> * | <c/> ) 
</a>

Note: for the sake of clarity, some element names have a ' or " to indicate that it is a different instance of that type of element.

Initial Representation@ModeExpressionValueFinal Represenation
Add/ or /*<a/><a/>
Replace/ or /*<a/><a/>
<a/>Add/ or /*<a'/>fault
<a/>Replace/a<a'/><a'/>
<a/>Add/a<wsf:AttributeNode name="foo">1</wsf:AttributeNode><a foo="1"/>
<a foo="1"/>Add/a<wsf:AttributeNode name="foo">2</wsf:AttributeNode>fault
<a foo="1"/>Replace/a@foo<wsf:AttributeNode name="foo">2</wsf:AttributeNode><a foo="2"/>
<a foo="1"/>Replace/a@foo<wsf:AttributeNode name="bar">2</wsf:AttributeNode><a bar="2"/>
<a/>Replace/a@foo<wsf:AttributeNode name="bar">2</wsf:AttributeNode><a bar="2"/>
<a foo="1"/>Remove/a@foo<a/>
<a/>Add/a<b/><a> <b/> </a>
<a> <b/> </a>Add/a<b'/><a> <b/> <b'/> </a>
<a> <b/> </a>Replace/a/b<b'/><a> <b'/> </a>
<a/>Replace/a/b<b/><a> <b/> </a>
<a> <b/> <b'> </a>InsertAfter/a/b or /a/b[last()]<b"/><a> <b/> <b'> <b"/> </a>
<a> <b/> <b'> </a>InsertBefore/a/b or /a/b[1]<b"/><a> <b"/> <b> <b'/> </a>
<a> <b/> <b'> </a>Replace/a/b<b"/><a> <b"/> </a>
<a> <b/> <b'> </a>Replace/a/b[1]<b"/><a> <b"/> <b'> </a>
<a> <b/> </a>Remove/a/b<a/>
<a> <b/> <b'> </a>Remove/a/b<a/>
<a> <b/> <b'> </a>Remove/a/b[1]<a> <b'> </a>
<a> <b/> <b'> </a>Replace/a/b<c/><a> <c> </a>
<a/>Replace/ or /*<a'/><a'/>
<a/>InsertBefore/ or /*<a'/>fault
<a/>InsertAfter/ or /*<a'/>fault
InsertBefore/ or /*<a/><a/>
InsertAfter/ or /*<a/><a/>
<a/>InsertBefore/a/b<b/><a> <b/> </a>
<a/>InsertAfter/a/b<b/><a> <b/> </a>

4.5 Delete

This specification does not extend the Delete operation defined in WS-Transfer.

4.6 Create

This specification does not extend the Create operation defined in WS-Transfer.

5 Examples

5.1 Examples

In the following examples, and Expression Language definitions, the following representation of a resource is used for informational purposes:

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

The following shows a sample SOAP envelope containing a Get request:

<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/2011/03/ws-tra/Get
    </wsa:Action>
    <wsa:MessageID>
      urn:uuid:00000000-0000-0000-C000-000000000046
    </wsa:MessageID>
  </s:Header>
  <s:Body>
    <wst:Get Dialect="http://www.w3.org/2011/03/ws-fra">
      <wsf:Expression Language="http://www.w3.org/2011/03/ws-fra/QName">
        ab:contact
      </wsf:Expression>
    </wst:Get>
  </s:Body>
</s:Envelope>

The following shows the corresponding response message:

<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/2011/03/ws-tra/GetResponse
    </wsa:Action>
    <wsa:MessageID>
      urn:uuid:0000010e-0000-0000-C000-000000000047
    </wsa:MessageID>
    <wsa:RelatesTo>
      urn: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>

6 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 1.0 [XPath1.0] language.

The QName language MUST be indicated by using the IRI:

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

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:

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. The XPath 1.0 language 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 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 needed:

(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>

8 XPath 2.0 Expression Language

The XPath 2.0 expression language is the same as the XPath 1.0 expression language except it uses [XPath2.0] as the expression language.

The XPath 2.0 language MUST be indicated by using the IRI:

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

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.

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>
  <s12:Header>
    <wsa:Action> [Action] </wsa:Action>
    <!-- Headers elided for brevity. -->
  </s12:Header>
  <s11:Body>
    <s11:Fault>
      <faultcode>[Subcode]</faultcode>
      <faultstring xml:lang="en">[Reason]</faultstring>
      <detail>
        [Detail]
        ...
      </detail>
    </s11:Fault>
  </s11:Body>
</s11:Envelope>

9.1 UnsupportedLanguage

This fault MUST be generated when a service detects an unknown or unsupported Language IRI in a request message.

[Code]s:Sender
[Subcode]wsf:UnsupportedLanguage
[Reason] The specified Language IRI is not supported.
[Detail]The unsupported Language IRI.

9.2 InvalidExpression

This fault MUST be generated when a service determines that the Language expression specified in a request does not conform to the syntax of the language specified in the Language attribute or is semantically invalid.

[Code]s:Sender
[Subcode]wsf:InvalidExpression
[Reason] The specified Language expression is invalid.
[Detail]The invalid language expression.

9.3 UnsupportedMode

This fault MUST be generated when a service detects a Mode in a Put request that is not supported.

[Code]s:Sender
[Subcode]wsf:UnsupportedMode
[Reason] The specified mode is not supported.
[Detail]The unsupported Mode.

10 WS-Fragment Metadata

An endpoint MAY indicate its support of WS-Fragment, or its features, by including the WS-Fragment FragmentAssertion Policy assertion within its WSDL. By doing so the endpoint is indicating that the corresponding WS-Fragment features are supported by that endpoint.

10.1 Fragment Assertion

Services indicate their support for the WS-Fragment specification through the use of the Web Services Policy - Framework [WS-Policy] and Web Services Policy - Attachment [WS-Policy Attachment] specifications.

This specification defines a policy assertion (wsf:FragmentAssertion). The normative outline of this assertion is:

<wsf:FragmentAssertion ...>
  <wsf:Language URI="xs:anyURI ...> 
    xs:any*
  </wsf:Language> * 
  xs:any*
</wsf:FragmentAssertion>

The following describes additional, normative constraints on the outline listed above:

/wsf:FragmentAssertion

This policy assertion has Endpoint Policy Subject. When present in a policy alternative, it indicates that the WS-Fragment protocol MUST be used when communicating with this endpoint.

/wsf:FragmentAssertion/wsf:Language

When present, this OPTIONAL parameter indicates support for the specified Language IRI.

/wsf:FragmentAssertion/wsf:Language/xs:any

This extensibility point allows for additional Language specific metadata to be included within the policy assertion. Any metadata that appears is scoped to the use of the specified Language URI.

/wsf:FragmentAssertion/xs:any

This extensibility point allows for additional WS-Fragment specific metadata to be included within the policy assertion. Any metadata that appears is scoped to the operations and features of the WS-Fragment specification.

11 Acknowledgements

This specification has been developed as a result of joint work with many individuals and teams, including: Alessio Soldano (Red Hat), Ashok Malhotra (Oracle Corp.), Asir Vedamuthu (Microsoft Corp.), Bob Freund (Hitachi, Ltd.), Bob Natale (MITRE Corp.), David Snelling (Fujitsu, 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), Martin Chapman (Oracle Corp.), Paul Fremantle (WSO2), Paul Nolan (IBM), Prasad Yendluri (Software AG), Ram Jeyaraman (Microsoft Corp.), Sreedhara Narayanaswamy (CA), Sumeet Vij (Software AG), Tom Rutt (Fujitsu, Ltd.), Vikas Varma (Software AG), Wu Chou (Avaya Communications), Yves Lafon (W3C/ERCIM).

12 References

12.1 Normative References

BP12
WS-I Profile, Basic Profile Version 1.2 , R. Chumbley, et al, Editors. Web Services Interoperability Organization (WS-I), 9 November 2010. Available at http://ws-i.org/profiles/BasicProfile-1.2-2010-11-09.html.
BP20
WS-I Profile, Basic Profile Version 2.0 , R. Chumbley, et al, Editors. Web Services Interoperability Organization (WS-I), 9 November 2010. Available at http://ws-i.org/profiles/BasicProfile-2.0-2010-11-09.html.
RFC 2119
Key words for use in RFCs to Indicate Requirement Levels , S. Bradner, Author. Internet Engineering Task Force, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
RFC 3987
Internationalized Resource Identifiers (IRIs) , M. Duerst and M. Suignard, Authors. Internet Engineering Task Force, January 2005. Available at http://www.ietf.org/rfc/rfc3987.txt.
SOAP11
W3C Note, "Simple Object Access Protocol (SOAP) 1.1" , D. Box, et al, Editors. World Wide Web Consortium (W3C), 8 May 2000. Available at http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.
SOAP12
W3C Recommendation, "SOAP Version 1.2 Part 1: Messaging Framework" , M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. Frystyk Nielson, Editors. World Wide Web Consortium (W3C), 27 April 2007. Available at http://www.w3.org/TR/soap12-part1/.
WS-Addressing
W3C Recommendation, "Web Services Addressing 1.0 (WS-Addressing)" , M. Gudgin, M. Hadley, T. Rogers, Editors. World Wide Web Consortium (W3C), 9 May 2006. Available at http://www.w3.org/TR/ws-addr-core.
WS-Addressing 1.0 SOAP Binding
W3C Recommendation, "Web Services Addressing 1.0 - SOAP Binding" , M. Gudgin, M. Hadley, T. Rogers, Editors. World Wide Web Consortium (W3C), 9 May 2006. Available at http://www.w3.org/TR/ws-addr-soap.
WS-Policy
W3C Recommendation, "Web Services Policy (WS-Policy) 1.5 - Framework" , A. Vedamuthu, et al., Editors. World Wide Web Consortium (W3C), 4 September 2007. Available at http://www.w3.org/TR/ws-policy/.
WS-Policy Attachment
W3C Recommendation, "Web Services Policy (WS-Policy) 1.5 - Attachment" , A. Vedamuthu, et al., Editors. World Wide Web Consortium (W3C), 4 September 2007. Available at http://www.w3.org/TR/ws-policy-attach.
WS-Transfer
W3C Working Group Draft, "Web Services Transfer (WS-Transfer)1.1" , D. Davis, et al., Editors. World Wide Web Consortium (W3C), 15 September 2009. Available at http://www.w3.org/TR/ws-transfer.
WSDL11
W3C Note, "Web Services Description Language (WSDL) 1.1" , E. Christensen, et al., Editors. World Wide Web Consortium (W3C), 15 March 2001 Available at http://www.w3.org/TR/2001/NOTE-wsdl-20010315.
XML Infoset
W3C Recommendation, "XML Information Set (Second Edition)" , J. Cowan, R. Tobin, Editors. World Wide Web Consortium (W3C), 4 February 2004. Available at http://www.w3.org/TR/xml-infoset.
XMLSchema - Part 1
W3C Recommendation, "XML Schema Part 1: Structures (Second Edition)" , H. Thompson, et al., Editors. World Wide Web Consortium (W3C), 28 October 2004. Available at http://www.w3.org/TR/xmlschema-1/.
XMLSchema - Part 2
W3C Recommendation, "XML Schema Part 2: Datatypes (Second Edition)" , P. Biron, A. Malhotra, Editors. World Wide Web Consortium (W3C), 28 October 2004. Available at http://www.w3.org/TR/xmlschema-2/.
XPath1.0
W3C Recommendation, "XML Path Language (XPath) Version 1.0" , J. Clark, S. DeRose, Editors. World Wide Web Consortium (W3C), 16 November 1999. Available at http://www.w3.org/TR/xpath.
XPath2.0
W3C Recommendation, "XML Path Language (XPath) 2.0" , A. Berglund, et al., Editors. World Wide Web Consortium (W3C), 23 January 2007. Available at http://www.w3.org/TR/xpath20/.

A XML Schema

A normative copy of the XML Schema [XMLSchema - Part 1], [XMLSchema - Part 2] description for this specification can be retrieved from the following address:

A non-normative copy of the XML schema is listed below for convenience.

<xs:schema 
  targetNamespace='http://www.w3.org/2011/03/ws-fra'
  xmlns:tns='http://www.w3.org/2011/03/ws-fra'
  xmlns:xs='http://www.w3.org/2001/XMLSchema'
  elementFormDefault='qualified'
  blockDefault='#all' >
 
  <xs:complexType name='ExpressionType'>
    <xs:sequence>
      <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
    </xs:sequence>
    <xs:attribute name='Language' type='xs:anyURI' use='optional'/>
    <xs:anyAttribute namespace='##other' processContents='lax'/>
  </xs:complexType>
  <xs:element name='Expression' type='tns:ExpressionType'/>

  <xs:complexType name='ValueType'>
    <xs:sequence>
      <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
    </xs:sequence>
    <xs:anyAttribute namespace='##other' processContents='lax'/>
  </xs:complexType>
  <xs:element name='Value' type='tns:ValueType'/>
  
  <xs:element name='Fragment'>
    <xs:complexType>
      <xs:sequence>
        <xs:element name='Expression' type='tns:ExpressionType'/>
        <xs:element name='Value' type='tns:ValueType' minOccurs='0'/>
        <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:anyAttribute namespace='##other' processContents='lax'/>
    </xs:complexType>
  </xs:element>

  <!-- Policy -->
  <xs:complexType name='URI'>
    <xs:simpleContent>
      <xs:extension base='xs:anyURI'>
        <xs:anyAttribute namespace='##other' processContents='lax'/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

  <xs:element name='FragmentAssertion'>
    <xs:complexType>
      <xs:sequence>
        <xs:element name='Language' minOccurs='0' maxOccurs='unbounded'>
          <xs:complexType>
            <xs:sequence>
              <xs:any namespace='##other' processContents='lax' minOccurs='0'
                                          maxOccurs='0'/>
            </xs:sequence>
            <xs:attribute name='URI' type='xs:anyURI' use='required' />
            <xs:anyAttribute namespace="##other" processContents='lax'/>
          </xs:complexType>
        </xs:element>
        <xs:any namespace='##other' processContents='lax' minOccurs='0'
                                    maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:anyAttribute namespace='##other' processContents='lax' />
    </xs:complexType>
  </xs:element>

</xs:schema>

B Change Log

Data Author Description
2009/08/01 DD Initial draft
2009/08/18 DD Added resolution of issue 7206
2009/08/18 DD Added resolution of issue 7197
2009/08/18 DD Added resolution of issue 7270
2009/09/01 DD Added resolution of issue 6700
2009/09/02 DD Added resolution of issue 6694
2009/09/30 DD Added resolution of issue 7088
2009/10/02 DD Added resolution of issue 7770
2009/10/02 DD Added resolution of issue 7426
2009/10/05 DD Added resolution of issue 6407, 6721
2009/10/20 DD Added resolution of issue 7068
2009/10/20 DD Added resolution of issue 7207
2009/11/06 DD Added resolution of issue 7969
2009/11/06 DD Added resolution of issue 8124
2009/11/17 DD Added resolution of issue 8280
2009/12/08 DD Added resolution of issue 8194
2009/12/08 DD Added resolution of issue 8195
2010/01/12 DD Added resolution of issue 8192
2010/01/19 DD Added resolution of issue 8283
2010/01/26 DD Added resolution of issue 8181
2010/01/26 DD Added resolution of issue 8257
2010/01/28 DD Added resolution of issue 8229
2010/01/28 DD Added resolution of issues 8302, 8180, 8299
2010/01/28 DD Added resolution of issue 8191
2010/01/28 DD Added resolution of issue 8196
2010/02/10 DD Added resolution of issue 8160
2010/02/10 DD Added resolution of issue 9032
2010/03/02 DD Added resolution of issues 8185, 8193
2010/03/09 DD Added resolution of issues 6463, 8031, 8198
2010/04/20 DD Added resolution of issue 9266
2010/05/04 DD Added resolution of issue 9588
2010/05/04 DD Added resolution of issue 9087
2010/05/11 DD Added resolution of issue 9699
2010/05/11 DD Added resolution of issue 9558
2010/05/12 DD Added resolution of issue 9717
2010/11/19 DD Added resolution of issue 8284
2011/02/01 DD Added resolution of issue 11882
2011/02/07 DD Added resolution of issue 11899
2011/02/15 DD Added resolution of issue 11724
2011/02/15 DD Added resolution of issue 11772
2011/02/15 DD Added resolution of issue 12042
2011/02/15 DD Added resolution of issue 12063