Web Services Transfer (WS-Transfer)

Web Services Transfer (WS-Transfer)

Editor's Draft $Date: 2009/03/29 22:15:19 $

Latest version:

http://www.w3.org/TR/ws-transfer

Editors:

Doug Davis, IBM

Ashok Malhotra, Oracle

Katy Warr, IBM

Wu Chou, Avaya

Abstract

This specification describes a general SOAP-based protocol for accessing XML representations of Web service-based resources.

Status of this Document

This document is an editors' copy that has no official standing.

1 Introduction
   1.1 Requirements
2 Terminology and Notation
   2.1 Terminology
   2.2 XML Namespaces
   2.3 Notational Conventions
   2.4 Compliance
3 Resource Operations
   3.1 Get
   3.2 Put
   3.3 Delete
4 Resource Factory Operations
   4.1 Create
5 Faults
   5.1 InvalidRepresentation
5.2 UnsupportedDialect
5.3 DialectFault
6 Security Considerations
7 Acknowledgements
8 References

Appendices

A Dialects
A.1 XPath Level 1 Expression Dialect for Resource Fragments
A1.1 Get
A1.2 Put
A1.3 Delete
A1.4 Factory Create
A1.5 DialectFault Reason Codes
A.2 XPath Level 1 Expression Dialect Syntax
A.3 XPath 1.0 Expression Dialect Example

BA XML Schema
B C WSDL
C D Change Log

1 Introduction

This specification defines a mechanism for acquiring XML-based representations of entities using the Web service infrastructure. It defines two types of entities:

· Resources, which are entities addressable by an endpoint reference that provide an XML representation

· Resource factories, which are Web services that can create a new resource from an XML representation

Specifically, it defines two operations for sending and receiving the representation of a given resource and two operations for creating and deleting a resource and its corresponding representation.

It should be noted that the state maintenance of a resource is at most subject to the "best efforts" of the hosting server. When a client receives the server's acceptance of a request to create or update a resource, it can reasonably expect that the resource now exists at the confirmed location and with the confirmed representation, but this is not a guarantee, even in the absence of any third parties. The server may change the representation of a resource, may remove a resource entirely, or may bring back a resource that was deleted.

For instance, the server may store resource state information on a disk drive. If that drive crashes and the server recovers state information from a backup tape, changes that occurred after the backup was made will be lost.

A server may have other operational processes that change resource state information. A server may run a background process that examines resources for objectionable content and deletes any such resources it finds. A server may purge resources that have not been accessed for some period of time. A server may apply storage quotas that cause it to occasionally purge resources.

In essence, the confirmation by a service of having processed a request to create, modify, or delete a resource implies a commitment only at the instant that the confirmation was generated. While the usual case should be that resources are long-lived and stable, there are no guarantees, and clients should code defensively.

There is no requirement for uniformity in resource representations between the messages defined in this specification. For example, the representations required by Create or Put may differ from the representation returned by Get, depending on the semantic requirements of the service. Additionally, there is no requirement that the resource content is fixed for any given endpoint reference. The resource content may vary based on environmental factors, such as the security context, time of day, configuration, or the dynamic state of the service.

As per the SOAP processing model, other specifications may define SOAP headers which may be optionally added to request messages to require the transfer of subsets or the application of transformations of the resource associated with the endpoint reference. When the Action URIs defined by this specification are used, such extension specifications must also allow the basic processing models defined herein.

1.1 Requirements

This specification intends to meet the following requirements:

· Provide a SOAP-based protocol for managing resources and their representations.

· Minimize additional mechanism beyond the current Web Services architecture.

2 Terminology and Notation

2.1 Terminology

Resource

A Web service that is addressable by an endpoint reference as defined in WS-Addressing and that can be represented by an XML Infoset using the Get and Put operations defined in this specification.

Resource factory

A Web service that is capable of creating new resources using the Create operation defined in this specification.

2.2 XML Namespaces

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

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

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

Table 2-1: Prefixes and XML Namespaces used in this specification.
Prefix	XML Namespace	Specification(s)
wst	http://www.w3.org/2009/02/ws-tra	This specification
s	Either SOAP 1.1 or 1.2	SOAP
s11	http://schemas.xmlsoap.org/soap/envelope/	[SOAP 1.1]
s12	http://www.w3.org/2003/05/soap-envelope	[SOAP 1.2]
wsa	http://www.w3.org/2005/08/addressing	[WS-Addressing]
wsdl	http://schemas.xmlsoap.org/wsdl/	[WSDL 1.1]
xs	http://www.w3.org/2001/XMLSchema	XML Schema [XML Schema, Part 1], [XML Schema, Part 2]

The working group intends to update the value of the Web Services Enumeration 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 Enumeration 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 .

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

o "?" (0 or 1)

o "*" (0 or more)

o "+" (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.

· An ellipsis (i.e. "...") indicates a point of extensibility that allows other child or attribute content. Additional children and/or attributes MAY be added 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 it.

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

2.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 Table 2-1) within SOAP envelopes unless it is compliant with this specification.

Specifically, a compliant SOAP Node that implements a resource MUST provide the Get operation as defined in this specification, and MAY provide the Put and Delete operations.

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

In any given request-response message exchange, the responses generated by the service server MUST use the same WS-Addressing namespace binding that was used in the request.

3 Resource Operations

All messages defined by this specification MUST be sent to a Web service that is addressable by an EPR [WS-Addressing].

3.1 Get

This specification defines one Web service operation (Get) for fetching a one-time snapshot of the representation of a resource.

The Get request message MUST be of the following form:

<s:Envelope ...>

<s:Header ...>

<wsa:Action>

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

</wsa:Action>

<wsa:MessageID>xs:anyURI</wsa:MessageID>

<wsa:To>xs:anyURI</wsa:To>

...

</s:Header>

<s:Body ...>

<wst:Get Dialect="xs:anyURI"?...>

xs:any *

</wst:Get>

</s:Body>

</s:Envelope>

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

/s:Envelope/s:Header/wsa:Action

This required element MUST contain the value http://www.w3.org/2009/02/ws-tra/Get. If a SOAP Action URI is also present in the underlying transport, its value MUST convey the same value.

/s:Envelope/s:Body/wst:Get

This REQUIRED element MAY contain child elements that can be used for extensibility purposes.

/s:Envelope/s:Body/wst:Get@Dialect

This OPTIONAL attribute, when present, indicates the dialect to be used in order to process the child element(s) of the wst:Get and the format of the wst:GetResponse element that is returned. This specification defines a standard dialect in Appendix A. Other dialects may be defined by other specifications.

A resource MUST generate a wst:UnsupportedDialectFault if it does not support the specified dialect.

When this attribute is not present, child elements of the wst:Get MUST be ignored[Katy1] .

A Get request MUST be targeted at the resource whose representation is desired as described in 2 Terminology and Notation of this specification.

As per the SOAP processing model, other specifications may introduce various types of extensions to the semantics of this message which are enabled through headers tagged with s:mustUnderstand="true". Such extensions may define how resource or subsets of it are to be retrieved or transformed prior to retrieval. Specifications which define such extensions MUST allow processing the basic Get request message without those extensions. Since the response may not be sent to the original sender, extension specifications should consider adding a corresponding SOAP header value in the response to signal to the receiver that the extension is being used.

Implementations may respond with a fault message using the standard fault codes defined in WS-Addressing (e.g., wsa:ActionNotSupported). Other components of the outline above are not further constrained by this specification.

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

<s:Envelope ...>

<s:Header ...>

<wsa:Action>

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

</wsa:Action>

<wsa:RelatesTo>xs:anyURI</wsa:RelatesTo>

<wsa:To>xs:anyURI</wsa:To>

...

</s:Header>

<s:Body ...>

<wst:GetResponse ...>

xs:any +

</wst:GetResponse>

</s:Body>

</s:Envelope>

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

/s:Envelope/s:Header/wsa:Action

This required element MUST contain the value http://www.w3.org/2009/02/ws-tra/GetResponse. If a SOAP Action URI is also present in the underlying transport, its value MUST convey the same value.

/s:Envelope/s:Body/wst:GetResponse

This REQUIRED element MUST contain at least one child element - the representation of the resource. The presence of subsequent child elements is service-specific and MAY be controlled by the presence or extension-specific SOAP headers in the original request.

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

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:xxx="http://fabrikam123.example.com/resource-model" >

<s:Header>

<wsa:ReplyTo>

<wsa:Address>

http://www.fabrikam123.example.org/pullport

</wsa:Address>

</wsa:ReplyTo>

<wsa:To>http://www.example.org/repository</wsa:To>

<xxx:CustomerID>732199</xxx:CustomerID>

<xxx:Region>EMEA</xxx:Region>

<wsa:Action>

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

</wsa:Action>

<wsa:MessageID>

uuid:00000000-0000-0000-C000-000000000046

</wsa:MessageID>

</s:Header>

<s:Body>

<wst:Get/>

</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:xxx="http://fabrikam123.example.com/resource-model" >

<s:Header>

<wsa:To>http://www.fabrikam123.example.org/pullport</wsa:Address>

<wsa:Action>

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

</wsa:Action>

<wsa:MessageID>

uuid:0000010e-0000-0000-C000-000000000046

</wsa:MessageID>

<wsa:RelatesTo>

uuid:00000000-0000-0000-C000-000000000046

</wsa:RelatesTo>

</s:Header>

<s:Body>

<xxx:Customer>

<xxx:first>Roy</xxx:first><xxx:last>Hill</xxx:last>

<xxx:address>123 Main Street</xxx:address>

<xxx:city>Manhattan Beach</xxx:city>

<xxx:state>CA</xxx:state>

<xxx:zip>90266</xxx:zip>

</xxx:Customer>

</GetResponse>

</s:Body>

</s:Envelope>

In this example, the representation of the resource is the following XML element:

<xxx:Customer>

<xxx:first>Roy</xxx:first><xxx:last>Hill</xxx:last>

<xxx:address>123 Main Street</xxx:address>

<xxx:city>Manhattan Beach</xxx:city>

<xxx:state>CA</xxx:state>

<xxx:zip>90266</xxx:zip>

</xxx:Customer>

3.2 Put

This specification defines one Web service operation (Put) for updating a resource by providing a replacement representation. A resource MAY accept updates that provide different XML representations than that returned by the resource; in such a case, the semantics of the update operation is defined by the resource.

The Put request message MUST be of the following form:

<s:Envelope ...>

<s:Header ...>

<wsa:Action>

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

</wsa:Action>

<wsa:MessageID>xs:anyURI</wsa:MessageID>

<wsa:To>xs:anyURI</wsa:To>

...

</s:Header>

<s:Body...>

<wst:Put Dialect="xs:anyURI"?...>

xs:any +

>/wst:Put>

</s:Body>

</s:Envelope>

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

/s:Envelope/s:Header/wsa:Action

This required element MUST contain the value http://www.w3.org/2009/02/ws-tra/Put. If a SOAP Action URI is also present in the underlying transport, its value MUST convey the same value.

/s:Envelope/s:Body/Put

This REQUIRED element MUST contain at least one child element - the representation to be used for the update. All other children SHOULD be ignored by the service.

/s:Envelope/s:Body/wst:Put@Dialect

This OPTIONAL attribute, when present, indicates the dialect to be used in order to process the child element(s) of the wst:Put and the format of the wst:PutResponse element that is returned. This specification defines a standard dialect in Appendix A. Other dialects may be defined by other specifications.

A resource MUST generate a wst:UnsupportedDialectFault if it does not support the specified dialect.

A Put request MUST be targeted at the resource whose representation is desired to be replaced, as described in 2 Terminology and Notation of this specification. As per the SOAP processing model, other specifications MAY introduce various types of extensions to this message which are enabled through headers tagged with s:mustUnderstand="true". Such extensions may require that a full or partial update should be accomplished using symbolic, instruction-based, or other methodologies.

Extension specifications MAY also define extensions to the original Put request, enabled by OPTIONAL SOAP headers, which control the nature of the response, as discussed in remarks on the PutResponse below.

Specifications which define any of these extensions MUST allow processing the Put message without such extensions.

In addition to the standard fault codes defined in WS-Addressing, implementations MAY use the fault code wst:InvalidRepresentation if the presented representation is invalid for the target resource. See 5 Faults. Other components of the outline above are not further constrained by this specification.

A successful Put operation updates the current representation associated with the targeted resource.

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

<s:Envelope ...>

<s:Header ...>

<wsa:Action>

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

</wsa:Action>

<wsa:RelatesTo>xs:anyURI</wsa:RelatesTo>

<wsa:To>xs:anyURI</wsa:To>

...

</s:Header>

<s:Body ...>

<wst:PutResponse ...>

xs:any ?

</wst:PutResponse>

</s:Body>

</s:Envelope>

/s:Envelope/s:Header/wsa:Action

This required element MUST contain the value http://www.w3.org/2009/02/ws-tra/PutResponse. If a SOAP Action URI is also present in the underlying transport, its value MUST convey the same value.

/s:Envelope/s:Body/PutResponse

This REQUIRED element MUST contain at least one child element (the current representation of the resource) if the updated representation differs from the representation sent in the Put request message. The presence of additional child elements which contain other information pertaining to the update is service-specific.

As an optimization and as a service to the requester, this element SHOULD be empty if the updated representation does not differ from the representation sent in the Put request message; that is, if the service accepted the new representation verbatim.

Such a response (an empty wst:PutResponse) implies that the update request was successful in its entirety (assuming no intervening mutating operations are performed). A service MAY return the current representation of the resource as the initial child of the wst:PutResponse element even in this case, however.

Extension specifications MAY define extensions to the original Put request, enabled by OPTIONAL header values, which specifically control the presence, absence, or format of the updated representation or other child elements in the PutResponse in order to optimize the response. In the absence of such headers, the behavior MUST be as described above. Specifications which define any of these extensions MUST allow processing the Put message without such extensions. Since the response may not be sent to the original sender, extension specifications should consider adding a corresponding SOAP header value in the response to signal to the receiver that the extension is being used.

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

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

<s:Envelope

xmlns:s="http://www.w3.org/2003/05/soap-envelope"

xmlns:wsa="http://www.w3.org/2005/08/addressing"

xmlns:xxx="http://fabrikam123.example.com/resource-model" >

<s:Header>

<wsa:ReplyTo>

<wsa:Address>

http://www.fabrikam123.example.org/sender

</wsa:Address>

</wsa:ReplyTo>

<wsa:To>http://www.example.org/pushport</wsa:To>

<xxx:CustomerID>732199</xxx:CustomerID>

<xxx:Region>EMEA</xxx:Region>

<wsa:Action>

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

</wsa:Action>

<wsa:MessageID>

uuid:00000000-0000-0000-C000-000000000047

</wsa:MessageID>

</s:Header>

<s:Body>

<wst:Put>

<xxx:Customer>

<xxx:first>Roy</xxx:first><xxx:last>Hill</xxx:last>

<xxx:address>321 Main Street</xxx:address>

<xxx:city>Manhattan Beach</xxx:city>

<xxx:state>CA</xxx:state>

<xxx:zip>90266</xxx:zip>

</xxx:Customer>

</wst:Put>

</s:Body>

</s:Envelope>

The following shows the corresponding response message indicating success:

<s:Envelope

xmlns:s="http://www.w3.org/2003/05/soap-envelope"

xmlns:wsa="http://www.w3.org/2005/08/addressing"

xmlns:xxx="http://fabrikam123.example.com/resource-model" >

<s:Header>

<wsa:To>http://www.fabrikam123.example.org/sender</wsa:Address>

<wsa:Action>

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

</wsa:Action>

<wsa:MessageID>

uuid:0000010e-0000-0000-C000-000000000047

</wsa:MessageID>

<wsa:RelatesTo>

uuid:00000000-0000-0000-C000-000000000047

</wsa:RelatesTo>

</s:Header>

<s:Body>

<wst:PutResponse/>

</s:Body/>

</s:Envelope>

3.3 Delete

This specification defines one Web service operation (Delete) for deleting a resource in its entirety.

Extension specifications MAY define extensions to the Delete request, enabled by OPTIONAL header values, which specifically control preconditions for the Delete to succeed and which may control the nature or format of the response. Since the response may not be sent to the original sender, extension specifications should consider adding a corresponding SOAP header value in the response to signal to the receiver that the extension is being used.

The Delete request message MUST be of the following form:

<s:Envelope ...>

<s:Header ...>

<wsa:Action>

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

</wsa:Action>

<wsa:MessageID>xs:anyURI</wsa:MessageID>

<wsa:To>xs:anyURI</wsa:To>

...

</s:Header>

<s:Body ...>

<wst:Delete Dialect="xs:anyURI"?...>

xs:any *

</wst:Delete>

</s:Body>

</s:Envelope>

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

/s:Envelope/s:Header/wsa:Action

This required element MUST contain the value http://www.w3.org/2009/02/ws-tra/Delete. If a SOAP Action URI is also present in the underlying transport, its value MUST convey the same value.

/s:Envelope/s:Body/wst:Delete

This REQUIRED element MAY contain child elements that can be used for extensibility purposes.

/s:Envelope/s:Body/wst:Delete@Dialect

This OPTIONAL attribute, when present, indicates the dialect to be used in order to process the child element(s) of the wst:Delete and the format of the wst:DeleteResponse element that is returned. This specification defines a standard dialect in Appendix A. Other dialects may be defined by other specifications.

A resource MUST generate a wst:UnsupportedDialectFault if it does not support the specified dialect.

When this attribute is not present, child elements of the wst:Delete MUST be ignored[Katy2] .

A Delete request MUST be targeted at the resource to be deleted as described in 2 Terminology and Notation of this specification.

Implementations may respond with a fault message using the standard fault codes defined in WS-Addressing (e.g., wsa:ActionNotSupported). Other components of the outline above are not further constrained by this specification.

A successful Delete operation invalidates the current representation associated with the targeted resource.

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

<s:Envelope ...>

<s:Header ...>

<wsa:Action>

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

</wsa:Action>

<wsa:RelatesTo>xs:anyURI</wsa:RelatesTo>

<wsa:To>xs:anyURI</wsa:To>

...

</s:Header>

<s:Body ...>

<wst:DeleteResponse ...>

xs:any ?

</wst:DeleteResponse>

</s:Body>

</s:Envelope>

/s:Envelope/s:Header/wsa:Action

This required element MUST contain the value http://www.w3.org/2009/02/ws-tra/DeleteResponse. If a SOAP Action URI is also present in the underlying transport, its value MUST convey the same value.

/s:Envelope/s:Body/wst:DeleteResponse

This REQUIRED element MAY contain a child element that can be used for extensibility purposes.

Specifications which define extensions for use in the original Delete request which control the format of the response MUST allow processing the Delete message without such extensions.

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

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

<s:Envelope

xmlns:s="http://www.w3.org/2003/05/soap-envelope"

xmlns:wsa="http://www.w3.org/2005/08/addressing"

xmlns:xxx="http://fabrikam123.example.com/resource-model" >

<s:Header>

<wsa:ReplyTo>

<wsa:Address>

http://www.fabrikam123.example.org/sender

</wsa:Address>

</wsa:ReplyTo>

<wsa:To>http://www.example.org/pushport</wsa:To>

<xxx:CustomerID>732199</xxx:CustomerID>

<xxx:Region>EMEA</xxx:Region>

<wsa:Action>

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

</wsa:Action>

<wsa:MessageID>

uuid:00000000-0000-0000-C000-000000000049

</wsa:MessageID>

</s:Header>

<s:Body>

<wst:Delete/>

</s:Body>

</s:Envelope>

The following shows the corresponding response message indicating success:

<s:Envelope

xmlns:s="http://www.w3.org/2003/05/soap-envelope"

xmlns:wsa="http://www.w3.org/2005/08/addressing"

xmlns:xxx="http://fabrikam123.example.com/resource-model" >

<s:Header>

<wsa:To>http://www.fabrikam123.example.org/sender</wsa:Address>

<wsa:Action>

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

</wsa:Action>

<wsa:MessageID>

uuid:0000010e-0000-0000-C000-000000000049

</wsa:MessageID>

<wsa:RelatesTo>

uuid:00000000-0000-0000-C000-000000000049

</wsa:RelatesTo>

</s:Header>

<s:Body>

</wst:DeleteResponse>

</s:Body>

</s:Envelope>

4 Resource Factory Operations

4.1 Create

This specification defines one Web service operation (Create) for creating a resource and providing its initial representation. In some cases, the initial representation MAY constitute the representation of a logical constructor for the resource and may thus differ structurally from the representation returned by Get or the one required by Put. This is because the parameterization requirement for creating a resource is often distinct from the steady-state representation of the resource. Implementations should provide metadata which describes the use of the representation and how it relates to the resource which is created, but such mechanisms are beyond the scope of this specification. The resource factory that receives a Create request will allocate a new resource that is initialized from the presented representation. The new resource will be assigned a service-determined endpoint reference that is returned in the response message.

The Create request message MUST be of the following form:

<s:Envelope ...>

<s:Header ...>

<wsa:Action>

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

</wsa:Action>

<wsa:MessageID>xs:anyURI</wsa:MessageID>

<wsa:To>xs:anyURI</wsa:To>

...

</s:Header>

<s:Body ...>

<wst:Create Dialect="xs:anyURI"?...>

xs:any *

</wst:Create>

</s:Body>

</s:Envelope>

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

/s:Envelope/s:Header/wsa:Action

This required element MUST contain the value http://www.w3.org/2009/02/ws-tra/Create. If a SOAP Action URI is also present in the underlying transport, its value MUST convey the same value.

/s:Envelope/s:Body/Create

If this REQUIRED element contains children then the first child MUST be the information required by the service in order to create the resource according to the processing rules defined for the dialect atribute /s:Envelope/s:Body/wst:Create@Dialect. For example, the first child could be a representation of the constructor for the resource, or other instructions for creating the resource. ~~literal resource representation, a representation of the constructor for the resource, or other instructions for creating the resource.~~ ~~All other children SHOULD be ignored by the service.~~

If no dialect attribute is specified then the first child MUST contain a literal representation of the resource to be created and all other children SHOULD be ignored by the service. If no dialect attribute is specified andIf this element does not contain any children then the resource will be created using default values. .

/s:Envelope/s:Body/wst:Create@Dialect

This OPTIONAL attribute, when present, indicates the dialect to be used in order to process the child element(s) of the wst:Create and the format of the wst:CreateResponse element that is returned. This specification defines a standard dialect in Appendix A. Other dialects may be defined by other specifications.

A resource MUST generate a wst:UnsupportedDialectFault if it does not support the specified dialect.

Extensions specifications MAY also define extensions to the original Create request, enabled by OPTIONAL SOAP headers, which constrain the nature of the response, as discussed in remarks on the CreateResponse below.Similarly, they may require headers which control the interpretation of the wst:Create as part of the resource creation process.

Such specifications MUST also allow processing the Create message without such extensions.

A Create request MUST be targeted at a resource factory capable of creating the desired new resource. This factory is distinct from the resource being created (which by definition does not exist prior to the successful processing of the Create request message).

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

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

<s:Envelope ...>

<s:Header ...>

<wsa:Action>

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

</wsa:Action>

<wsa:RelatesTo>xs:anyURI</wsa:RelatesTo>

<wsa:To>xs:anyURI</wsa:To>

...

</s:Header>

<s:Body ...>

<wst:CreateResponse ...>

<wst:ResourceCreated>endpoint-reference</wst:ResourceCreated>

xs:any ?

</wst:CreateResponse>

</s:Body>

</s:Envelope>

/s:Envelope/s:Header/wsa:Action

This required element MUST contain the value http://www.w3.org/2009/02/ws-tra/CreateResponse. If a SOAP Action URI is also present in the underlying transport, its value MUST convey the same value.

/s:Envelope/wst:CreateResponse

This REQUIRED element MUST contain, at a minimum, a resource reference (wst:ResourceCreated element) to the newly created resource.

By default, a service MUST also return the current representation of the new resource as the second child of the wst:CreateResponse element if the created representation logically differs from the representation sent in the Create request message. That is, the initial representation is returned if one or more values present in Create message was specifically overridden with a different value during resource creation. If default values are used to complete a resource creation which were not present in the Create message, then this does not constitute a logical difference. The presence of additional child elements which contain other information pertaining to the result of the Create operation is service-specific.

As an optimization and as a service to the requestor, the wst:CreateResponse element of the response message SHOULD be empty, other than the ResourceCreated element, if the created representation does not logically differ from the representation sent in the Create request message; that is, if the service accepted the new representation or creation instructions verbatim. Such a response indicates that the request was completely successful (assuming no intervening mutating operations are performed). A service MAY return the current representation of the resource as the initial child of the wst:CreateResponse element even in this case, however.

Extension specifications MAY define extensions to the original Create request, enabled by OPTIONAL header values, which specifically control the presence, absence, or format of the initial representation or other child elements in the CreateResponse. These headers MAY override the default behavior if they are marked with s:mustUnderstand="true". In the absence of such OPTIONAL headers, the behavior MUST be as described in the previous paragraphs. Since the response may not be sent to the original sender, extension specifications should consider adding a corresponding SOAP header value in the response to signal to the receiver that the extension is being used.

/s:Envelope/wst:CreateResponse/wst:ResourceCreated

This required element MUST contain a resource reference for the newly created resource. This resource reference, represented as an endpoint reference as defined in WS-Addressing, MUST identify the resource for future Get, Put, and Delete operations.

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

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

<s:Envelope

xmlns:s="http://www.w3.org/2003/05/soap-envelope"

xmlns:wsa="http://www.w3.org/2005/08/addressing"

xmlns:xxx="http://fabrikam123.example.com/resource-model" >

<s:Header>

<wsa:ReplyTo>

<wsa:Address>

http://www.fabrikam123.example.org/sender

</wsa:Address>

</wsa:ReplyTo>

<wsa:To>http://www.example.org/pushport/CustomerSpace</wsa:To>

<wsa:Action>

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

</wsa:Action>

<wsa:MessageID>

uuid:00000000-0000-0000-C000-000000000048

</wsa:MessageID>

</s:Header>

<s:Body>

<wst:Create>

<xxx:Customer>

<xxx:first>Roy</xxx:first><xxx:last>Hill</xxx:last>

<xxx:address>123 Main Street</xxx:address>

<xxx:city>Manhattan Beach</xxx:city>

<xxx:state>CA</xxx:state>

<xxx:zip>90266</xxx:zip>

</xxx:Customer>

</wst:Create>

</s:Body>

</s:Envelope>

The following shows the corresponding response message indicating success:

<s:Envelope

xmlns:s="http://www.w3.org/2003/05/soap-envelope"

xmlns:wsa="http://www.w3.org/2005/08/addressing"

xmlns:wst="http://www.w3.org/2009/02/ws-tra"

xmlns:xxx="http://fabrikam123.example.com/resource-model" >

<s:Header>

<wsa:To>http://www.fabrikam123.example.org/sender</wsa:Address>

<wsa:Action>

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

</wsa:Action>

<wsa:MessageID>

uuid:0000010e-0000-0000-C000-000000000048

</wsa:MessageID>

<wsa:RelatesTo>

uuid:00000000-0000-0000-C000-000000000048

</wsa:RelatesTo>

</s:Header>

<s:Body>

<wst:CreateResponse>

<wst:ResourceCreated>

<wsa:Address>http://www.example.org/pushport</wsa:Address>

<wsa:ReferenceParameters>

<xxx:CustomerID>732199</xxx:CustomerID>

<xxx:Region>EMEA</xxx:Region>

</wsa:ReferenceParameters>

</wst:ResourceCreated>

</wst:CreateResponse>

</s:Body>

</s:Envelope>

5 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 SHOULD be used for faults defined in this specification:

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

5.1 InvalidRepresentation

This fault is returned when an incorrect representation is sent in a wst:Put or wst:Create message. The fault detail MAY contain information about the fault as defined by the message dialect. Fault details for the dialect defined by this specification are listed in Appendix A.

If the fault is returned when an incorrect representation is sent on a wst:Put message, the fault detail SHOULD include a wst:SideAffects element to indicat whether any changes occurred. A value of ‘true’ indicates that some changes occurred; a value of "false" indicates no changes occurred. Absence of the element indicates that changes may have occurred.

[Code]	s:Sender
[Subcode]	wst:InvalidRepresentation
[Reason]	The supplied representation is invalid
[Detail]	<wst:SideEffects>xs:boolean</wst:SideEffects> ? xs:any[Katy3] *~~none~~

5.2 UnsupportedDialectFault

This fault is generated by a resource to indicate that the dialect is not supported by the resource for the current operation. The fault detail SHOULD contain the Dialect values that the resource does support for the operation.

[Code]	s:Sender
[Subcode]	wst:UnsupportedDialectFault
[Reason]	The requested dialect is not supported
[Detail]	<wst:Dialect>xs:anyURI</wst:Dialect> *

5.3 DialectFault[Katy4]

This fault is generated by a resource to indicate an error that is specific to a dialect. The fault detail SHOULD contain the information about the fault as defined by the dialect in question. Fault details for dialects defined by this specification are listed in Appendix A.

[Code]	s:Sender
[Subcode]	wst:UnsupportedDialectFault
[Reason]	A fault specific to the dialect occurred
[Detail]	xs:any*

6 Security Considerations

It is strongly recommended that the communication between services be secured using the mechanisms described in [WS-Security].

In order to properly secure messages, the body (even if empty) and all relevant headers need to be included in the signature. Specifically, the WS-Addressing header blocks, WS-Security timestamp, and any header blocks resulting from a <wsa:ReferenceParameters> in references need to be signed along with the body in order to "bind" them together and prevent certain types of attacks.

If a requestor is issuing multiple messages to a resource reference, then it is recommended that a security context be established using the mechanisms described in WS-Trust and WS-SecureConversation. It is further recommended that if shared secrets are used, message-specific derived keys also be used to protect the secret from crypto attacks.

The access control semantics of resource references is out-of-scope of this specification and are specific to each resource reference. Similarly, any protection mechanisms on resource references independent of transfer (e.g. embedded signatures and encryption) are also out-of-scope.

It is recommended that the security considerations of WS-Security also be considered.

While a comprehensive listing of attacks is not feasible, the following list summarizes common classes of attacks that apply to this protocol and identifies the mechanism(s) to prevent/mitigate the attacks.

· Replay - Messages, or portions of messages, can be replayed in an attempt to gain access or disrupt services. Freshness checks such as timestamps, digests, and sequences can be used to detect duplicate messages.

· Invalid tokens - There are a number of token attacks including certificate authorities, false signatures, and PKI attacks. Care should be taken to ensure each token is valid (usage window, digest, signing authority, revocation, ...), and that the appropriate delegation policies are in compliance.

· Man-in-the-middle - The message exchanges in this specification could be subject to man-in-the-middle attacks so care should be taken to reduce possibilities here such as establishing a secure channel and verifying that the security tokens user represent identities authorized to speak for, or on behalf of, the desired resource reference.

· Message alteration - Alteration is prevented by including signatures of the message information using WS-Security. Care should be taken to review message part references to ensure they haven't been forged (e.g. ID duplication).

· Message disclosure - Confidentiality is preserved by encrypting sensitive data using WS-Security.

· Key integrity - Key integrity is maintained by using the strongest algorithms possible (by comparing secured policies - see [WS-Policy] and [WS-SecurityPolicy] and by using derived keys ([WS-SecureConversation]).

· Authentication - Authentication is established using the mechanisms described in WS-Security and WS-Trust. Each message is authenticated using the mechanisms described in WS-Security.

· Accountability - Accountability is a function of the type of and string of the key and algorithms being used. In many cases, a strong symmetric key provides sufficient accountability. However, in some environments, strong PKI signatures are required.

· Availability - All reliable messaging services are subject to a variety of availability attacks. Replay detection is a common attack and it is recommended that this be addressed by the mechanisms described in WS-Security. Other attacks, such as network-level denial of service attacks are harder to avoid and are outside the scope of this specification. That said, care should be taken to ensure that minimal state is saved prior to any authenticating sequences.

7 Acknowledgements

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

8 References

RFC 2119

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

SOAP 1.1

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

SOAP 1.2

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

WS-Addressing

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

WS-Policy

S. Bajaj, et al, "Web Services Policy Framework (WS-Policy)," , September 2004. (See http://schemas.xmlsoap.org/ws/2004/09/policy.)

WS-SecureConversation

href="http://schemas.xmlsoap.org/ws/2005/02/sc/"> Web Services Secure Conversation Language (WS-SecureConversation) , S. Anderson, et al, February 2005.

WS-Security

Web Services Security: SOAP Message Security 1.0 , OASIS standard. (See http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.)

WS-SecurityPolicy

G. Della-Libera, et al, "Web Services Security Policy Language (WS-SecurityPolicy), Version 1.1" , July 2005. (See http://schemas.xmlsoap.org/ws/2005/07/securitypolicy.)

WSDL 1.1

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

XML Infoset

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

XML Schema, Part 1

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

XML Schema, Part 2

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

XPath 1.0

XML Path Language (XPath) Version 1.0 , James Clark, et al, November 1999. (See http://www.w3.org/TR/xpath.)

A Dialects

This specification defines dialects as an extensible mechanism for designating the processing of extensibility elements within the body of an operation. Dialect definitions must clearly specify how extensibility elements should be processed and how the result is serialized to XML in the operation response. Dialect definitions should also specify any dialect-specific behavior for operations that access the resource representation.

The remainder of this section defines the XPath Level 1.0 Expression Dialect. Other specifications may define other dialects.

A.1 XPath Level 1 Expression Dialect for Resource Fragments

Since an EPR refers to a resource as a whole, techniques which are used to reference or access parts of the resource representation are referred to as "fragment access" in that they access fragments of the XML representing the resource.

The XPath Level 1 expression dialect 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. Appendix A3 shows an example usage of this dialect.

An implementation that uses the XPath Level 1 dialect MUST support the expressions whose syntax is described by the BNF in Appendix A2. It MAY support additional expressions defined by [add reference to] XPath 1.0].

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

The XPath Level 1 dialect can define references to any element, attribute or value in the resource representation.

The XPath Level 1 dialect MUST be indicated by using the URI:

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

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

For each Transfer operation, the following sections define the format of the child elements that appear in the extensibility point of the SOAP Body for the XPath Level 1 dialect.

A.1.1 Get

Expression dialects extend the "Get" operation to retrieve fragments of an existing representation. The extended outline for wst:Get operation with the XPath Level 1 expression dialect is:

(03) [Action]

(04) http://www.w3.org/2009/02/ws-tra/Get

(05) [Body]

(06) <wst:Get Dialect=”http://www.w3.org/2009/02/ws-tra/Dialect/XPath-Level-1”>

(07) <wst:Expression …>xs:any</wst:Expression>

(08) </wst:Get>

The following describes additional constraints on the outline listed above:

/s:Envelope/s:Body/wst:Get@Dialect=’http://www.w3.org/2009/02/ws-tra/Dialect/XPath-Level-1’

When this OPTIONAL attribute is present, and set to this value, it indicates that a single Expression element MUST be present as a child of the Get element. This Expression element MUST contain an XPath Level 1 expression that will be used to identify the fragment of the resource representation to be retrieved.

/s:Envelope/s:Body/wst:Get/wst:Expression

This element MUST be present if the dialect attribute corresponds to a dialect that requires the presence of this element. Only one expression may be specified. ,

When present, this optional element identifies a fragment in the resource to be sent in the response. The value of this element MUST conform to the dialect specified in /s:Envelope/s:Body/wst:Get@Dialect attribute. The Fragment element of the response may be empty if the Expression identifies a valid fragment with no value.

A resource MUST generate an DialectFault with InvalidExpression detailed (as defined in Appendix A1.5) if the expression is invalid.

If the resource accepts a wst:Get request and processes it successfully it MUST reply with a response of the following form:

(03) [Action]

(04) http://www.w3.org/2009/02/ws-tra/GetResponse

(05) [Body]

(06) <wst:GetResponse>

(07) <wst:Fragment…>xs:any*</wst:Fragment>

(08) </wst:GetResponse>

The following describes additional constraints on the outline listed above:

/s:Envelope/s:Body/wst:GetResponse/wst:Fragment

This element encompasses a single fragment response corresponding to the wst:Expression in the original request and MUST contain the fragment of the resource representation identified by the wst:Expression.

A.1.2 Put

Expression dialects extend the “Put” operation to update an existing resource representation by providing a fragment of the XML representation. The extended outline for wst:Put operation with the XPath Level 1 expression dialect is:

(03) [Action]

(04) http://www.w3.org/2009/02/ws-tra/Put

(05) [Body]

(06) <wst:Put Dialect=”http://www.w3.org/2009/02/ws-tra/Dialect/XPath-Level-1”>

(07) <wst:Fragment>

(08) <wst:Expression>xs:any</wst:Expression>

(09) <wst:Value …>xs:any</wst:Value>

(10) </wst:Fragment>

(11) </wst:Put>

The following describes additional constraints on the outline listed above:

/s:Envelope/s:Body/wst:Put@Dialect=’http://www.w3.org/2009/02/ws-tra/Dialect/XPath-Level-1’

When this OPTIONAL attribute is present, and set to this value, it indicates that a single Fragment element MUST be present as a child of the Put element. The Expression part of the Fragment element MUST contain an XPath Level 1 expression that will be used to identify the fragment of the resource representation to be updated.

/s:Envelope/s:Body/wst:Put/wst:Fragment

This element MUST only be present if the Dialect attribute corresponds to a dialect that requires the presence of this element. This element encompasses a single update to be performed on the resource

The fragment MUST be replaced by removing any fragment that already exists at the element defined by /s:Envelope/s:Body/wst:Put/wst:Fragment/wst:Expression and inserting the specified value /s:Envelope/s:Body/wst:Put/wst:Fragment/wst:Value in its place. If the expression resolves to nothing then this fragment element does not result in any change to the resource representation.

/s:Envelope/s:Body/wst:Put/wst:Fragment/wst:Expression

This REQUIRED element contains the expression that identifies a fragment of the resource representation to be updated.

The value of this element MUST conform to the dialect specified in the /s:Envelope/s:Body/wst:Put@Dialect attribute. A resource MUST generate an DialectFault with InvalidExpression detail as defined in Appendix A.1.5 if the expression is invalid.

/s:Envelope/s:Body/wst:Put/wst:Fragment/wst:Value

This REQUIRED element contains the data to be written to the resource representation and MUST be present in the /s:Envelope/s:Body/wst:Put/wst:Fragment element.

If a resource encounters a failure while processing the fragments in a Put request, it MUST generate an InvalidRepresentation[Katy5] fault. The resource SHOULD ensure that its representation is unchanged from prior to the request, although atomic behavior is not required of resource implementations. The resource SHOULD include a wst:SideAffects element in the fault detail to indicate whether any changes occurred.

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

(03) [Action]

(04) http://www.w3.org/2009/02/ws-tra/PutResponse

(05) [Body]

The following describes additional constraints on the outline listed above:

/s:Envelope/s:Body

If the request Body contained a /s:Envelope/s:Body/wst:Put@Dialect attribute representing an expression dialect, then the new representation MUST be omitted in the response. The absence of the resource representation in the response is in recognition of the potentially large amount of data that may be returned, which may have been the reason a fragment Put was used instead of sending the entire resource representation.

A.1.3 Delete

Expression dialects extend the “Delete” operation to update parts of an existing resource representation. The extended outline for wst:Delete operation with the XPath Level 1 expression dialect is:

(03) [Action]

(04) http://www.w3.org/2009/02/ws-tra/Delete

(05) [Body]

(06) <wst:Delete Dialect=”http://www.w3.org/2009/02/ws-tra/Dialect/XPath-Level-1”>

(07) <wst:Expression …>xs:any</wst:Expression>

(08) </wst:Delete>

The following describes additional constraints on the outline listed above:

/s:Envelope/s:Body/wst:Delete@Dialect=’http://www.w3.org/2009/02/ws-tra/Dialect/XPath-Level-1’

When this OPTIONAL attribute is present, and set to this value, it indicates that a single Expression element MUST be present as a child of the Delete element. This Expression element MUST contain an XPath Level 1 expression that will be used to identify the fragment of the resource representation to be deleted.

/s:Envelope/s:Body/wst:Delete/wst:Expression

This element MUST only be present if the Dialect attribute corresponds to a dialect that requires the presence of this element. When present, this optional element contains the expression that identifies a fragment of the resource representation to be deleted if it is present.

The value of this element MUST conform to the dialect specified in the /s:Envelope/s:Body/wst:Put@Dialect attribute. A resource MUST generate an DialectFault with InvalidExpression detail (as defined in Appendix A1.5) if the expression is invalid.

If a resource encounters a failure while processing the fragments in a Delete request, it MUST generate a DeleteFault. The resource SHOULD ensure that its representation is unchanged from prior to the request, although atomic behavior is not required of resource implementations. The resource SHOULD include a wst:SideAffects element in the fault detail to indicate whether any changes occurred.

If the resource accepts a Delete request and performs the requested update, the expression dialect introduces no additional constraints to the DeleteResponse.

A.1.4 Factory Create

Expression dialects extend the “Create” operation to insert a fragment of a resource into its XML representation. The extended outline for wst:Create operation with the XPath Level 1 expression dialect is:

(03) [Action]

(04) http://www.w3.org/2009/02/ws-tra/Create

(05) [Body]

(06) <wst:Create Dialect=”http://www.w3.org/2009/02/ws-tra/Dialect/XPath-Level-1”>

(08) <wst:Fragment>

(09) <wst:Expression>xs:any</wst:Expression>

(10) <wst:Value …>xs:any</wst:Value>

(11) </wst:Fragment>

(12) </wst:Create>

The following describes additional constraints on the outline listed above:

/s:Envelope/s:Body/wst:Create@Dialect=’http://www.w3.org/2009/02/ws-tra/Dialect/XPath-Level-1’

When this OPTIONAL attribute is present, and set to this value, it indicates that a single Fragment element MUST be present as a child of the Create element. The Expression part of the Fragment element MUST contain an XPath Level 1 expression that will be used to identify the fragment of the resource representation to be inserted.

/s:Envelope/s:Body/wst:Create/wst:Fragment

This element MUST only be present if the Dialect attribute corresponds to a dialect that requires the presence of this element. This element encompasses a single resource fragment to be inserted into an existing resource's XML representation.

/s:Envelope/s:Body/wst:Create/wst:Fragment/wst:Expression

This REQUIRED element contains an expression that identifies a fragment of the resource’s representation where the data contained in the Value element will be inserted. The expression identifies the fragment in the resource representation as it appears after successful processing of the current fragment.

The value of this element MUST conform to the dialect specified in the /s:Envelope/s:Body/wst:Create@Dialect attribute. A resource MUST generate an DialectFault with InvalidExpression detail (as defined in appendix A1.5) if the expression is invalid

/s:Envelope/s:Body/wst:Create/wst:Fragment/wst:Value

This REQUIRED element contains the data to be written to the resource representation. If the resource factory is unable to write the requested fragment then it MUST generate an InvalidRepresentation[Katy6] fault..

If the resource accepts a Delete request and performs the requested update, the expression dialect introduces no additional constraints to the DeleteResponse.

A.1.5 DialectFault fault details

Expression dialects define the following [Detail] for the wst:DialectFault.

InvalidExpression detail

This detail is sent by a resource if a <wst:Expression> element has an syntax that is invalid according to the definition of the expression dialect. If the expression syntax is not valid with respect to the dialect then a resource SHOULD specify a fault detail of "InvalidExpressionSyntax", indicating which expression this detail applies to. If the expression is not valid for the resource type then the resource SHOULD specify a fault detail of "InvalidExpressionValue", indicating which expression this detail applies to.

[Code]	s:Sender
[Subcode]	wst:DialectFault
[Reason]	A fault specific to the dialect occurred
[Detail]	<wst:InvalidExpressionSyntax> <wst:Expression>xs:any</wst:Expression> ? </wst:InvalidExpressionSyntax> \| <wst:InvalidExpressionValue> <wst:Expression>xs:any</wst:Expression> ? </wst:InvalidExpressionValue>

A.2 XPath 1.0 Expression Dialect Syntax

XPath Level 1 is a subset of the abbreviated relative syntax of XPath 1.0.

The following XPath Level 1 grammar is LL(1), and the nonterminal productions are in angle brackets. Terminal symbols are either literals, or in UPPERCASE:

(01) <xpath> ::= <context> <node_sequence>;

(02)

(03) <context> ::= '/' | <>;

(04)

(05) <node_sequence> ::=

(06) <element> <optional_collection_operator> <more>;

(07)

(08) <optional_collection_operator> ::= '[' <array_location> ']';

(09) <optional_collection_operator> ::= <>;

(10)

(11) <more> ::= '/' <follower> | <>;

(12)

(13) <follower> ::=

(14) <attribute> | <text_function> | <node_sequence>;

(15)

(16) <element> ::= <qualified_name>;

(17) <attribute> ::= '@' <qualified_name>;

(18)

(19) <qualified_name> ::= <name> <qname_follower>;

(20) <qname_follower> ::= ':' <name> | <>;

(21) <text_function> ::= "text()" ;

(22) <array_location> ::= NONZERO_DECIMAL_UNSIGNED_INTEGER;

(23) <name> ::= XML_TOKEN;

The terminal tokens which require further lexical specification are NONZERO_DECIMAL_UNSIGNED_INTEGER, whose values are in the subrange (1...4294967295), and XML_TOKEN whose values are equivalent to those for the XML Schema type xs:token. This grammar is small enough that it can be easily implemented in resource-constrained implementations.

The following comments on the grammar will clarify certain constructs within the BNF.

Most of the examples assume the following XML sample acting as a "resource" document:

(01) <a>

(02) <b>

(03) <c d="30"> 20 </c>

(04) </b>

(05) <e>

(06) <f/>

(07) <f/>

(08) </e>

(09) </a>

The context and document root node need clarification. XPath Level 1 assumes that the root is the root node of the resource document, not the SOAP envelope or any other wrapper element which may 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 may 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) <wst:TextNode>20</wst: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) <wst:AttributeNode name="d">30</wst: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.

Appendix A3 - XPath Level 1 Expression Dialect - Example

This section contains a complete example of a WS-RT "Get" operation. This example is meant for illustration only and does not represent normative behavior or content.

Example 2-1 shows the XML representation of the example resource which will be accessed by the protocol operation. The example resource is a physical disk which has a number of logical volumes.

Example 2-1: Sample Resource

(01) <Disk xmlns="http://example.org/sample">

(02) <DiskCapacity>62500000000</DiskCapacity>

(03) <DiskFreeSpace>524182841</DiskFreeSpace>

(04) <SerialNumber>123-F2560</SerialNumber>

(05) <LastAuditDate>1998-05-25T13:30:15</LastAuditDate>

(06) <Volume>

(07) <Drive>C:</Drive>

(08) <Label>MyDrive-C</Label>

(09) <TotalCapacity>10000000000</TotalCapacity>

(10) <FreeSpace>6234794528</FreeSpace>

(11) </Volume>

(12) <Volume>

(13) <Drive>D:</Drive>

(14) <Label>MyDrive-D</Label>

(15) <TotalCapacity>30000000000</TotalCapacity>

(16) <FreeSpace>26462809800</FreeSpace>

(17) </Volume>

(18) <Volume>

(19) <Drive>E:</Drive>

(20) <Label>MyDrive-E</Label>

(21) <TotalCapacity>22500000000</TotalCapacity>

(22) <FreeSpace>16056784170</FreeSpace>

(23) </Volume>

(24) </Disk>

The protocol message for retrieving parts of the above resource representation is shown in Example 2-2. The response message of a WS-Transfer "Get" request message would return the entire representation of the resource, so this example illustrates a WS-RT "Get" request message augmented for extracting specific fragments of the representation:

Example 2-2: "Get" operation of resource content

(01) <s:Envelope

(02) xmlns:s="http://www.w3.org/2003/05/soap-envelope"

(03) xmlns:wsa="http://www.w3.org/2005/08/addressing"

(06) <s:Header>

(07) <wsa:To>http://www.example.org/disk</wsa:To>

(08) <wsa:Action s:mustUnderstand="true">

(09) http://www.w3.org/2009/02/ws-tra/Get

(10) </wsa:Action>

(12) ...

(13) </s:Header>

(14) <s:Body>

(15) <wst:Get

(16) Dialect="http://www.w3.org/2009/02/ws-tra/Dialect/XPath-Level-1"

(17) xmlns:d="http://example.org/sample">

(18) <wst:Expression>

(19) d:Volume[1]/d:Label

(20) </wst:Expression>

(27) </wst:Get>

(28) </s:Body>

(29) </s:Envelope>

In this example, the operation is a WS-Transfer "Get" as defined by the wsa:Action in line (09). The extended, fragment-aware Get behavior is indicated Dialect attribute on line 16. The resource being accessed is referenced by the WS-Addressing endpoint reference, implied by the wsa:To element on line (07). WS-T expression for extracting fragments of the resource representation is in the wst:Get block on lines (15) through (27). For the targeted fragment the value to be selected is specified in the wst:Expression element.

The response to the "Get" message is illustrated in Example 2-3.

Example 2-3: Example "Get" response

(01) <s:Envelope

(02) xmlns:s="http://www.w3.org/2003/05/soap-envelope"

(03) xmlns:wsa="http://www.w3.org/2005/08/addressing"

(06) <s:Header>

(07) <wsa:To>

(08) http://www.w3.org/2005/08/addressing/anonymous

(09) </wsa:To>

(10) <wsa:Action s:mustUnderstand="true">

(11) http://www.w3.org/2009/02/ws-tra/GetResponse

(12) </wsa:Action>

(13) <wst:ResourceTransfer/>

(14) ...

(15) </s:Header>

(16) <s:Body>

(17) <wst:GetResponse xmlns:d="http://example.org/sample">

(18) <wst:Result>

(19) <d:Label>MyDrive-C</d:Label>

(20) </wst:Result>

(28) </s:Body>

(29) </s:Envelope>

BA XML Schema

A normative copy of the XML Schema [Schema1], [Schema2] description for this specification may be retrieved from the following address:

http://www.w3.org/2009/02/ws-tra/transfer.xsd

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

<xs:schema

targetNamespace="http://www.w3.org/2009/02/ws-tra"

xmlns:tns="http://www.w3.org/2009/02/ws-tra"

xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:wsa="http://www.w3.org/2005/08/addressing"

elementFormDefault="qualified"

blockDefault="#all" >

<xs:import

namespace="http://www.w3.org/2005/08/addressing"

schemaLocation="http://www.w3.org/2006/03/addressing/ws-addr.xsd" />

<xs:element name="Get">

<xs:complexType>

<xs:sequence>

<xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other" processContents="lax" />

</xs:sequence>

<xs:anyAttribute namespace="##other" processContents="lax" />

</xs:complexType>

</xs:element>

<xs:element name="GetResponse">

<xs:complexType>

<xs:sequence>

<xs:any minOccurs="1" maxOccurs="unbounded" namespace="##other" processContents="lax" />

</xs:sequence>

<xs:anyAttribute namespace="##other" processContents="lax" />

</xs:complexType>

</xs:element>

<xs:element name="Put">

<xs:complexType>

<xs:sequence>

<xs:any minOccurs="1" maxOccurs="unbounded" namespace="##other" processContents="lax" />

</xs:sequence>

<xs:anyAttribute namespace="##other" processContents="lax" />

</xs:complexType>

</xs:element>

<xs:element name="PutResponse">

<xs:complexType>

<xs:sequence>

<xs:any minOccurs="1" namespace="##other" processContents="lax" />

</xs:sequence>

<xs:anyAttribute namespace="##other" processContents="lax" />

</xs:complexType>

</xs:element>

<xs:element name="Delete">

<xs:complexType>

<xs:sequence>

<xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other" processContents="lax" />

</xs:sequence>

<xs:anyAttribute namespace="##other" processContents="lax" />

</xs:complexType>

</xs:element>

<xs:element name="DeleteResponse">

<xs:complexType>

<xs:sequence>

<xs:any minOccurs="0" namespace="##other" processContents="lax" />

</xs:sequence>

<xs:anyAttribute namespace="##other" processContents="lax" />

</xs:complexType>

</xs:element>

<xs:element name="ResourceCreated">

<xs:complexType>

<xs:sequence>

<wsa:EndpointReferenceType minOccurs='1' maxOccurs='unbounded'/>

</xs:sequence>

</xs:complexType>

</xs:element>

<xs:element name="Create">

<xs:complexType>

<xs:sequence>

<xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other" processContents="lax" />

</xs:sequence>

<xs:anyAttribute namespace="##other" processContents="lax" />

</xs:complexType>

</xs:element>

<xs:element name="CreateResponse">

<xs:complexType>

<xs:sequence>

<xs:element ref="tns:ResourceCreated" />

<xs:any minOccurs="0" namespace="##other" processContents="lax" />

</xs:sequence>

<xs:anyAttribute namespace="##other" processContents="lax" />

</xs:complexType>

</xs:element>

</xs:schema>

CB WSDL

A normative copy of the WSDL [WSDL 1.1] description for this specification may be retrieved from the following address:

http://www.w3.org/2009/02/ws-tra/transfer.wsdl

A non-normative copy of the WSDL description is listed below for convenience.

<wsdl:definitions

targetNamespace="http://www.w3.org/2009/02/ws-tra"

xmlns:tns="http://www.w3.org/2009/02/ws-tra"

xmlns:wsa="http://www.w3.org/2005/08/addressing"

xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"

xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"

xmlns:xs="http://www.w3.org/2001/XMLSchema">

<wsdl:types>

<xs:schema>

<xs:import

namespace="http://www.w3.org/2009/02/ws-tra"

schemaLocation="http://www.w3.org/2009/02/ws-tra/transfer.xsd"

</xs:schema>

</wsdl:types>

<wsdl:message name="GetMessage">

<wsdl:part name="Body" element="tns:Get"/>

</wsdl:message>

<wsdl:message name="GetResponseMessage">

<wsdl:part name="Body" element="tns:GetResponse"/>

</wsdl:message>

<wsdl:message name="PutMessage">

<wsdl:part name="Body" element="tns:Put"/>

</wsdl:message>

<wsdl:message name="PutResponseMessage">

<wsdl:part name="Body" element="tns:PutResponse"/>

</wsdl:message>

<wsdl:message name="DeleteMessage">

<wsdl:part name="Body" element="tns:Delete"/>

</wsdl:message>

<wsdl:message name="DeleteResponseMessage">

<wsdl:part name="Body" element="tns:DeleteResponse"/>

</wsdl:message>

<wsdl:message name="CreateMessage">

<wsdl:part name="Body" element="tns:Create"/>

</wsdl:message>

<wsdl:message name="CreateResponseMessage">

<wsdl:part name="Body" element="tns:CreateResponse"/>

</wsdl:message>

<wsdl:portType name="Resource">

<wsdl:documentation>

This port type defines a resource that may be read,

written, and deleted.

</wsdl:documentation>

<wsdl:operation name="Get">

<wsdl:input

message="tns:GetMessage"

wsam:Action="http://www.w3.org/2009/02/ws-tra/Get"/>

<wsdl:output

message="tns:GetResponseMessage"

wsam:Action="http://www.w3.org/2009/02/ws-tra/GetResponse" />

</wsdl:operation>

<wsdl:operation name="Put">

<wsdl:input

message="tns:PutMessage"

wsam:Action="http://www.w3.org/2009/02/ws-tra/Put" />

<wsdl:output

message="tns:PutResponseMessage"

wsam:Action="http://www.w3.org/2009/02/ws-tra/PutResponse" />

</wsdl:operation>

<wsdl:operation name="Delete">

<wsdl:input

message="tns:DeleteMessage"

wsam:Action="http://www.w3.org/2009/02/ws-tra/Delete" />

<wsdl:output

message="tns:DeleteResponseMessage"

wsam:Action="http://www.w3.org/2009/02/ws-tra/DeleteResponse" />

</wsdl:operation>

</wsdl:portType>

<wsdl:portType name="ResourceFactory">

<wsdl:documentation>

This port type defines a Web service that can create new

resources.

</wsdl:documentation>

<wsdl:operation name="Create">

<wsdl:input

message="tns:CreateMessage"

wsam:Action="http://www.w3.org/2009/02/ws-tra/Create" />

<wsdl:output

message="tns:CreateResponseMessage"

wsam:Action="http://www.w3.org/2009/02/ws-tra/CreateResponse" />

</wsdl:operation>

</wsdl:portType>

</wsdl:definitions>

DC Change Log

Data	Author	Description
2009/03/04	DD	Added resolution of issue 6391
2009/03/04	DD	Added resolution of issue 6388
2009/03/04	DD	Added resolution of issue 6519
2009/03/09	DD	Added resolution of issue 6398
2009/03/11	DD	Added change log
2009/03/11	DD	Added resolution of issue 6641
2009/03/11	DD	Added resolution of issue 6425

Editor's Draft $Date: 2009/03/29 22:15:19 $

Abstract

Status of this Document

Table of Contents

Appendices

1 Introduction

1.1 Requirements

2 Terminology and Notation

2.1 Terminology

2.2 XML Namespaces

2.3 Notational Conventions

2.4 Compliance

3 Resource Operations

3.1 Get

3.2 Put

3.3 Delete

4 Resource Factory Operations

4.1 Create

5 Faults

5.1 InvalidRepresentation

5.2 UnsupportedDialectFault

5.3 DialectFault[Katy4]

6 Security Considerations

7 Acknowledgements

8 References

A Dialects

A.1 XPath Level 1 Expression Dialect for Resource Fragments

For each Transfer operation, the following sections define the format of the child elements that appear in the extensibility point of the SOAP Body for the XPath Level 1 dialect.

A.1.1 Get

A.1.2 Put

Expression dialects extend the “Put” operation to update an existing resource representation by providing a fragment of the XML representation. The extended outline for wst:Put operation with the XPath Level 1 expression dialect is:

A.1.3 Delete

Expression dialects extend the “Delete” operation to update parts of an existing resource representation. The extended outline for wst:Delete operation with the XPath Level 1 expression dialect is:

A.1.4 Factory Create

A.1.5 DialectFault fault details

A.2 XPath 1.0 Expression Dialect Syntax

Appendix A3 - XPath Level 1 Expression Dialect - Example

BA XML Schema

CB WSDL

DC Change Log