Copyright © 2009 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.
1 Introduction
1.1 Requirements
2 Terminology and Notation
2.1 Terminology
2.2 XML Namespaces
2.3 Notational Conventions
2.4 Considerations on the Use of Extensibility Points
2.5 Compliance
3 Fragment WS-Transfer Dialect
3.1 Get
3.2 Put
3.3 Delete
3.4 Create
4 Examples
4.1 Examples
5 QName Expression Language
6 XPath Level 1 Expression Language
7 XPath 1.0 Expression Language
8 Faults
8.1 UnsupportedLanguage
8.2 InvalidFragment
8.3 InvalidExpression
8.4 UnsupportedMode
9 WS-Fragment Metadata
9.1 Fragment Assertion
10 Acknowledgements
11 References
11.1 Normative References
A XML Schema
B Change Log
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 requirement:
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.
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.
The XML Namespace URI that MUST be used by implementations of this specification is:
Table 2-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/2009/09/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] |
| xs | http://www.w3.org/2001/XMLSchema | XML Schema [XMLSchema - Part 1], [XMLSchema - Part 2] |
| wst | http://www.w3.org/2009/09/ws-tra | [WS-Transfer] |
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 .
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 2-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.
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.
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 2.2 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 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 understand those OPTIONAL elements and attributes, unless other behavior is explicitly defined by this specification.
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.
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/2009/09/ws-tra/Get
[Body]
<wst:Get Dialect="http://www.w3.org/2009/09/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/2009/09/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.
This 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/2009/09/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/2009/09/ws-tra/Put
[Body]
<wst:Put Dialect="http://www.w3.org/2009/09/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/2009/09/ws-fra.
This element contains an expression that identifies the location of a fragment in the resource and a value for the fragment. If the contents of this element are invalid a wsf:InvalidFragment fault MUST be generated.
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.
This element identifies the fragment in the resource as it appears after successfully processing the Put request.
This 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/2009/09/ws-fra/Modes/Replace". A resource MUST generate a wsf:UnsupportedMode fault if the specified Mode is not supported.
When the Mode attribute is set to a value of "http://www.w3.org/2009/09/ws-fra/Modes/Replace" the resource representation specified within the Value element MUST replace the entire resource representation referenced by the children of the Expression element, if it exists.
When the Mode attribute is set to a value of "http://www.w3.org/2009/09/ws-fra/Modes/Insert" the resource representation specified within the Value element MUST be added to the resource representation. If the expression targets a repeated element (maxOccurs > 1), the fragment MUST be added at the end. If the expression targets a non-repeated element (maxOccurrs = 1) that already exists, the resource MUST generate a wst:InvalidRepresentation fault. If the expression targets an existing item of a repeated element, the fragment MUST be added before the existing item.
When the Mode attribute is set to a value of "http://www.w3.org/2009/09/ws-fra/Modes/Remove" the resource representation referenced by the children of the Expression element MUST be deleted from the resource representation.
Note: the Value element MUST NOT be present if this attribute has a value of "http://www.w3.org/2009/09/ws-fra/Modes/Remove".
This OPTIONAL element contains the fragment resource representation corresponding to the subset of the resource identified by the wsf:Expression element.
When Mode is "http://www.w3.org/2009/09/ws-fra/Modes/Insert" or "http://www.w3.org/2009/09/ws-fra/Modes/Replace", any optional values (element or attributes) within this subset that are not specified in the Value element will be set to a resource-specific default value.
This element MUST NOT be present if the Mode attribute has a value of "http://www.w3.org/2009/09/ws-fra/Modes/Remove". This element MUST be present if the Mode attribute has a value of either "http://www.w3.org/2009/09/ws-fra/Modes/Replace" or "http://www.w3.org/2009/09/ws-fra/Modes/Insert". When present, this element can either be empty or non-empty.
If the resource accepts a Put request, it MUST reply with a response of the following form:
[Action]
http://www.w3.org/2009/09/ws-tra/PutResponse
[Body]
<wst:PutResponse ...>
xs:any *
</wst:PutResponse>There are no additional constraints beyond what WS-Transfer defines.
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/2009/09/ws-tra/Get
</wsa:Action>
<wsa:MessageID>
uuid:00000000-0000-0000-C000-000000000046
</wsa:MessageID>
</s:Header>
<s:Body>
<wst:Get Dialect="http://www.w3.org/2009/09/ws-fra">
<wsf:Expression Language="http://www.w3.org/2009/09/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/2009/09/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>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 Level 1 expression language uses an XPath to reference specific fragments of the resource representation. The XPath is logically applied to the XML representation of the resource and the resulting node-set is the resource fragment which is the subject of the message containing the expression. This language is useful for resources with limited XPath processing capability which do not need to support returning values computed from their resource representation.
XPath Level 1 is a subset of the abbreviated relative syntax of XPath 1.0 [XPath1.0], and is used to identify or select a node (element, attribute or value) within a resource representation or fragment. It is identified by the following IRI:
An XPath Level 1 expression is an expression whose context is:
Context Node: the root element of the XML representation of the resource
Context Position: 1
Context Size: 1
Variable Binding: None
Node Tests: NameTest and the text NodeType
Function Libraries: None
Namespace Declarations: Any namespace declarations in-scope where the XPath expression appears
An implementation that uses the XPath Level 1 language MUST support the expressions whose syntax is described by the following BNF. It MAY support additional expressions defined by XPath 1.0. The following XPath Level 1 grammar is LL(1), and the non-terminal productions are in angle brackets. Terminal symbols are either literals, or in UPPERCASE:
(01) <xpath> ::= <context> <node_sequence>; (02) (03) <context> ::= '/' | <>; (04) (05) <node_sequence> ::= (06) <element> <optional_collection_operator> <more>; (07) (08) <optional_collection_operator> ::= '[' <array_location> ']'; (09) <optional_collection_operator> ::= <>; (10) (11) <more> ::= '/' <follower> | <>; (12) (13) <follower> ::= (14) <attribute> | <text_function> | <node_sequence>; (15) (16) <element> ::= <qualified_name>; (17) <attribute> ::= '@' <qualified_name>; (18) (19) <qualified_name> ::= <name> <qname_follower>; (20) <qname_follower> ::= ':' <name> | <>; (21) <text_function> ::= "text()" ; (22) <array_location> ::= NONZERO_DECIMAL_UNSIGNED_INTEGER; (23) <name> ::= XML_TOKEN;
The terminal tokens which require further lexical specification are NONZERO_DECIMAL_UNSIGNED_INTEGER, whose values are in the sub-range (1...4294967295), and XML_TOKEN whose values are equivalent to those for the XML Schema type xs:token. This grammar is small enough that it can be easily implemented in resource-constrained implementations.
The following comments on the grammar will clarify certain constructs within the BNF.
Most of the examples assume the following XML sample acting as a "resource" document:
(01) <a> (02) <b> (03) <c d="30"> 20 </c> (04) </b> (05) <e> (06) <f/> (07) <f/> (08) </e> (09) </a>
The context and document root node need clarification. XPath Level 1 assumes that the root is the root node of the resource document, not the SOAP envelope or any other wrapper element which might contain the resource.
Further, the default context is the root element and the context position is 1.
In view of this, the / operator selects the containing root, and the only valid operand which can follow it is the outermost element of the resource:
(01) /a
The following paths are equivalent:
(01) /a/b (02) b
Note that because the context node is the root element, a relative path selects a matching child element.
The <node_sequence> production provides the recursive behavior for the XPath:
(01) /a/b/c (02) b/c
It also provides for selecting specific repeated elements through the <optional_collection_operator> production:
(01) /a/e/f[2]
The collection operator only takes unsigned nonzero values, as defined above for NONZERO_DECIMAL_UNSIGNED_INTEGER. Thus, [1] is the first of a repeating series of elements.
The <qualified_name> production allows the XML naming tokens to be either namespace-qualified or unqualified:
(01) /ns1:a/ns2:b/c
The namespace bindings are evaluated against any namespace declarations that are in scope where the XPath appears within the SOAP message.
NOTE: If the element name is unqualified, i.e. appears without a namespace prefix, then the element name MUST be matched against a matching element name in the resource document, regardless of namespace bindings that are in effect, including default bindings. This allows implementations to simply match element names in the majority of cases. If namespace bindings are significant for all elements, then qualified names MUST be used.
The <follower> production allows for special-casing of the final tokens of the XPath allowing it to end in either an attribute or text.
The text() NodeTest MAY be applied as a final token to the selected element. This NodeTest selects any text nodes that are children of the selected element. If the element only contains text content, the return value will be a node-set containing a single text node.
(01) b/c/text()
The above expression would return a node-set containing a single text node with the value 20 as its result. This text node would then be serialized into the following XML representation:
(01) <wsf:TextNode>20</wsf:TextNode>
If accessed, attributes MUST be the final token in the path and they MAY be namespace-qualified or unqualified names, as required:
(01) /a/b/c/@d
The above expression would return a node-set containing a single attribute node with the value d="30" as its result. This attribute node would then be serialized into the following XML representation:
(01) <wsf:AttributeNode name="d">30</wsf:AttributeNode>
Selection of an element returns the element and its entire content. The path /a/b executed against the sample XML returns a node-set containing a single element node which serializes directly:
(01) <b> <c d="30"> 20 </c> </b>
In the event that there is more than one node which would match the XPath, the implementation 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.
The XPath 1.0 expression language uses an XPath to reference specific fragments of the resource representation. The XPath is logically applied to the XML representation of the resource and the result of the XPath is returned as the value for that expression. The XPath 1.0 language supports a wider set of XPath function libraries than the XPath Level 1 language. This language is useful for resources with full XPath processing capability or which need to support returning values computed from their resource representation.
An XPath 1.0 expression is an expression whose context is:
Context Node: the root element of the XML representation of the resource
Context Position: 1
Context Size: 1
Variable Binding: None
Function Libraries: Core function library
Namespace Declarations: Any namespace declarations in-scope where the XPath expression appears
The XPath 1.0 language can define references to any element, attribute or value in the resource representation and can also be used to compute values from the resource representation.
The XPath 1.0 language MUST be indicated by using the IRI:
Implementations that support the full XPath 1.0 language MUST support the XPath Level 1 language.
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:
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 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:
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-Fragment 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.
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.
For SOAP 1.2, the [Code] property MUST be either "Sender" or "Receiver". These properties are serialized into text XML as follows:
| SOAP Version | Sender | Receiver |
|---|---|---|
| SOAP 1.2 | s12:Sender | s12:Receiver |
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>This fault is generated when a service detects an unknown or unsupported Language IRI in a request message.
| [Code] | s:Sender |
|---|---|
| [Subcode] | wst:UnsupportedLanguage |
| [Reason] | The specified Language IRI is not supported. |
| [Detail] | The unsupported Language IRI. |
This fault is generated when a service determines that the fragment (contents of the wsf:Fragment element) specified in a request is invalid.
| [Code] | s:Sender |
|---|---|
| [Subcode] | wst:InvalidFragment |
| [Reason] | The specific fragment is invalid. |
| [Detail] | The invalid fragment. |
This fault is 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] | wst:InvalidExpression |
| [Reason] | The specified Language expression is invalid. |
| [Detail] | The invalid language expression. |
An endpoint MAY indicate that it supports WS-Fragment, or its features, by including the WS-Fragment Policy assertion within its WSDL. By doing so the endpoint is indicating that the corresponding WS-Fragment features are supported by that endpoint.
The mechanism for indicating that a binding or endpoint conforms to the WS-Fragment specification is 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 wsf:FragmentAssertion policy assertion applies to the endpoint policy subject.
For WSDL 1.1, these assertions MAY be attached to wsdl11:port or wsdl11:binding. For WSDL 2.0, they MAY be attached to wsdl20:endpoint or wsdl20:binding. A policy expression containing the wsf:FragmentAssertion policy assertion MUST NOT be attached to a wsdl:portType or wsdl20:interface.
The wsf:FragmentAssertion policy assertion is a nested policy container assertion. The meaning of this assertion, when present in a policy alternative, is that WS-Fragment is required to communicate with the subject and that the subject is a WS-Transfer Resource.
In order to indicate that the subject supports WS-Fragment but does not require its use, an additional policy alternative SHOULD be provided which does not contain this assertion. The compact authoring style for an OPTIONAL policy assertion (the wsp:Optional attribute) provided by WS-Policy MAY be used to indicate two policy alternatives, one which contains the policy assertion, and another which does not.
The normative outline of this assertion is:
<wsf:FragmentAssertion ...> <wsf:Language ...> xs:anyURI </wsf:Language> * ... </wsf:FragmentAssertion>
The following describes additional, normative constraints on the outline listed above:
A policy assertion that specifies that WS-Fragment protocol MUST be used when communicating with this endpoint. This assertion has Endpoint Policy Subject.
When present, this OPTIONAL parameter indicates support for the specified Language IRI.
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).
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/2009/09/ws-fra"
xmlns:tns="http://www.w3.org/2009/09/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="required"/>
<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" type="tns:URI" minOccurs="0"
maxOccurs="unbounded"/>
<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 |