Copyright © 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
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.
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
A XML Schema
B Change Log
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.
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.
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.
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:
Unordered message headers.
The value to be used for the wsa:Action IRI.
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.
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.
A Language specific set of tokens that resolves to a location in a resource that contains a subset of the resource.
A subset of a resource.
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].
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.
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 .
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.
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.
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:
This element is used to serialize an attribute node in a node-set and MUST contain the value portion of the attribute node.
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:
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".
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:
This attribute MUST be set to http://www.w3.org/2011/03/ws-fra.
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.
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:
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.
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:
This attribute MUST be set to http://www.w3.org/2011/03/ws-fra.
This element contains an expression that identifies the location of a fragment in the resource and a value for the fragment.
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.
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.
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.
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.
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.
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.
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.
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.
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 | @Mode | Expression | Value | Final 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> |
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>
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:
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:
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:
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>
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:
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>
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. |
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. |
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.
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:
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.
When present, this OPTIONAL parameter indicates support for the specified Language IRI.
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.
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.
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).
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>
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 |