Web Services Transfer (WS-Transfer)
Latest version:
http://www.w3.org/TR/ws-transfer
Editors:
Doug Davis, IBM
Ashok Malhotra, Oracle
Katy Warr, IBM
Wu Chou, Avaya
Copyright ©
2009 W3C®
(MIT,
ERCIM,
Keio), All Rights Reserved. W3C liability,
trademark
and document
use rules apply.
This
specification describes a general SOAP-based protocol for accessing XML
representations of Web service-based resources.
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
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
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.
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.
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.
Table 2-1:
Prefixes and XML Namespaces used in this specification. |
||
Prefix |
XML
Namespace |
Specification(s)
|
wst |
This
specification |
|
s |
Either SOAP
1.1 or 1.2 |
SOAP |
s11 |
||
s12 |
||
wsa |
||
wsdl |
||
xs |
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
.
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.
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.
All
messages defined by this specification MUST be sent to a Web service that is
addressable by an EPR [WS-Addressing].
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>
<GetResponse>
<xxx:Customer>
<xxx:first>
<xxx:address>
<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>
<xxx:address>
<xxx:city>
<xxx:state>CA</xxx:state>
<xxx:zip>90266</xxx:zip>
</xxx:Customer>
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>
<xxx:address>
<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>
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>
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).
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.
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>
<xxx:address>
<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>
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:
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.
s:Sender |
|
[Subcode] |
wst:InvalidRepresentation |
[Reason] |
The supplied
representation is invalid |
[Detail] |
<wst:SideEffects>xs:boolean</wst:SideEffects>
? |
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.
s:Sender |
|
[Subcode] |
wst:UnsupportedDialectFault
|
[Reason] |
The requested dialect
is not supported |
[Detail] |
<wst:Dialect>xs:anyURI</wst:Dialect>
* |
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* |
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.
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)
Key
words for use in RFCs to Indicate Requirement Levels , S.
Bradner,
Simple Object Access Protocol (SOAP) 1.1 ,
D. Box, et al, May 2000. (See http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.)
SOAP
Version 1.2 Part 1: Messaging Framework , M. Gudgin, et al,
June 2003. (See http://www.w3.org/TR/soap12-part1/.)
W3C Recommendation, "Web Services Addressing 1.0
(WS-Addressing)" , May 2006. (See
http://www.w3.org/2005/08/addressing/.)
S. Bajaj, et al, "Web Services Policy Framework
(WS-Policy)," , September 2004. (See
http://schemas.xmlsoap.org/ws/2004/09/policy.)
href="http://schemas.xmlsoap.org/ws/2005/02/sc/">
Web Services Secure Conversation Language
(WS-SecureConversation) ,
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.)
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.)
Web Services Description Language (WSDL) 1.1 ,
E. Christensen, et al, March 2001. (See
http://www.w3.org/TR/2001/NOTE-wsdl-20010315.)
J. Cowan, et al, "XML Information Set" ,
February 2004. (See http://www.w3.org/TR/2004/REC-xml-infoset-20040204/.)
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: Datatypes ,
James Clark, et al, November 1999. (See http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.)
XML
Path Language (XPath) Version 1.0 , James Clark, et al,
November 1999. (See http://www.w3.org/TR/xpath.)
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.
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.
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.
(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.
(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.
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.
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> |
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.
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.
(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>
A
normative copy of the XML Schema [Schema1],
[Schema2]
description for this specification may 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/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>
A
normative copy of the WSDL [WSDL
1.1] description for this specification may be retrieved from the following
address:
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>
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 |
[Katy1]This means that there’s no need to check the body unless the dialect attribute is there.
[Katy2]This means that there’s no need to check the body unless the dialect attribute is there.
[Katy3]Adding this extensibility removes requirement for wsrt:PutFault and CreateFaults
[Katy4]I added this to enable use to extend wst fault for different dialects using the detail.
[Katy5]Was wsrt:PutFault
[Katy6]This was wsrt:CreateFault