Copyright © 2004 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
This document describes the semantics and serialization of a SOAP header block for carrying resource representations in SOAP messages.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is the W3C Last Call Working Draft of the SOAP Resource Representation Header document. It has been produced by the XML Protocol Working Group (WG), which is part of the Web Services Activity.
Discussion of this document takes place on the public xml-dist-app@w3.org mailing list (public archive) under the email communication rules in the XML Protocol Working Group Charter .
Comments on this document are welcome. Send them before 29 June 2004 to xmlp-comments@w3.org mailing list (public archive). Note that all outstanding issues against this document are documented in the Working Group Last Call Issues List. If the feedback on this document is positive, the WG plans to submit it for consideration as a W3C Candidate Recommendation.
This document has been produced under the 24 January 2002 CPP as amended by the W3C Patent Policy Transition Procedure. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy. Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
1 Introduction
1.1 Notational Conventions
1.2 Relation to other specifications
1.2.1 Relationship to the SOAP Processing model
2 Representation Header
2.1 Introduction
2.2 Representation header block Constructs
2.2.1 rep:Representation element
2.2.2 resource attribute
2.2.3 reinsert attribute
2.2.4 rep:Data element
2.3 Extensibility of the Representation header block
2.3.1 SOAP header block Attributes
2.3.2 Specifying the media type
2.3.3 HTTP headers
A References
B Acknowledgements (Non-Normative)
This document describes the semantics and serialization of a SOAP header block for carrying resource representations in SOAP messages.
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 a number of namespace prefixes throughout; they are listed in [Prefixes and Namespaces used in this specification.]. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see XML Infoset [XML InfoSet]).
| Prefix | Namespace |
|---|---|
| Notes | |
| env | "http://www.w3.org/2003/05/soap-envelope" |
| A normative XML Schema [XML Schema Part 1], [XML Schema Part 2] document for the "http://www.w3.org/2003/05/soap-envelope" namespace can be found at http://www.w3.org/2003/05/soap-envelope. | |
| rep | "http://www.w3.org/2004/02/representation" |
| A normative XML Schema [XML Schema Part 1], [XML Schema Part 2] document for the "http://www.w3.org/2004/02/representation" namespace can be found at http://www.w3.org/2004/02/representation. | |
| xs | "http://www.w3.org/2001/XMLSchema" |
| The namespace of XML Schema data types (see [XML Schema Part 2]). | |
| xmlmime | "http://www.w3.org/2004/06/xmlmime" |
| The namespace for representing MIME media-types in XML (see [Assigning Media Types to Binary Data in XML]). |
This section describes a SOAP header block, the Representation header block, that allows a SOAP message to carry representations of Web resources.
The Representation header block is designed to allow applications to carry a representation of a Web resource in a SOAP message. Applications of this header include cases where the receiver has limited ability to get the representation using other means, for example because of access restrictions or because the overhead would be unacceptable. The representation header is also required when multiple references to the same extracted content are required but duplication of extracted content is undesirable. See UC2 and UC6 [SOAP Optimized Serialization Use Cases and Requirements] for details.
The meaning of the Representation header block, when present in a SOAP message, is to make available the contained representation of the resource it carries to the processing SOAP node. The SOAP node MAY use this representation when dereferencing the URI of the resource instead of making a network request to the given resource. Note that implementations MAY need to process a Representation header block before processing other header blocks that require dereferencing of a URI whose representation is carried in the Representation header block.
Several occurences of the Representation header block MAY be present in the same SOAP Message to carry representations of several Web resource or several representation of the same Web resource.
Several occurences of the Representation header block having the same
value for the role and resource
attribute information item
(see 2.2.2 resource attribute) MAY be present in the same SOAP
Message. Such Representation header blocks SHOULD NOT have the same
metadata (such as media-type). If such Representation header blocks
have the same metadata then any one of them may be used.
An example SOAP Envelope using the Representation header block is given below.
<soap:Envelope xmlns:soap='http://www.w3.org/2002/12/soap-envelope'
xmlns:rep='http://www.w3.org/2004/02/representation'
xmlns:xmlmime='http://www.w3.org/2004/06/xmlmime'>
<soap:Header>
<rep:Representation resource='http://example.org/me.png'>
<rep:Data xmlmime:contentType='image/png'>
/aWKKapGGyQ=
</rep:Data>
</rep:Representation>
</soap:Header>
<soap:Body>
<x:MyData xmlns:x='http://example.org/mystuff'>
<x:name>John Q. Public</x:name>
<x:img src='http://example.org/me.png'/>
</x:MyData>
</soap:Body>
</soap:Envelope>rep:Representation element
The Representation element information item
has:
A [local name] of Representation.
A [namespace name] of "http://www.w3.org/2004/02/representation".
One or more attribute information items amongst its [attributes] property as follows:
A mandatory resource attribute information
item (see 2.2.2 resource attribute).
An optional reinsert attribute information
item (see 2.2.3 reinsert attribute).
Any other namespace qualified attribute information items.
One or more element information items in its [children] property in order as follows:
A mandatory Data element information
item (see 2.2.4 rep:Data element).
Any other element information item with a [namespace name] different than "http://www.w3.org/2004/02/representation".
The rep:Representation element information
item contains a representation of a Web resource. The
value of the resource element information
item is the URI identifying the Web resource. The value of
the rep:Data element information item is a
base64-encoded representation of the Web resource.
resource attribute
The resource attribute information item
has:
A [local name] of resource.
An empty [namespace name].
A [specified] property with a value of "true".
The type of the resource attribute information
item is xs:anyURI. The value of the
resource attribute information item is a
URI that identifies the Web resource whose representation is carried
in the rep:Representation element information
item parent of the resource attribute
information item.
reinsert attribute
The reinsert attribute information item
has:
A [local name] of reinsert.
An empty [namespace name].
A [specified] property with a value of "true".
The type of the reinsert attribute information
item is xs:boolean. When this attribute is
specified on the Representation header block with a value of
"true", it indicates that a SOAP forwarding
intermediary node processing the
header block must reinsert the header block. This means that when
used in conjunction with the relay attribute, defined
in [SOAP Part 1]
5.2.4 SOAP Relay Attribute, with a value of
"true", the Representation header
block will always be relayed by a SOAP forwarding intermediary.
When this attribute is specified on the Representation header block
with a value of "false", the behavior of the SOAP
node processing the header block is the same as that when the
attribute is not specified, and normal SOAP processing rules
apply. The presence of this attribute has no effect on the
processing of a Representation header by a SOAP endpoint.
rep:Data element
The Data element information item has:
A [local name] of Data.
A [namespace name] of "http://www.w3.org/2004/02/representation".
Zero or more namespace qualified attribute information items amongst its [attributes] property.
Any number of charatecter information item in its [children] property. No other type of information item in its [children] property.
The type of a rep:Data element information
item is xs:base64Binary. The value of this
element information item is a base64-encoded
representation of the Web resource carried in the
rep:Representation element information item
parent of the resource attribute information
item.
The Representation header block is built to be extensible. This section describes several possible usage of this extensibility.
Attributes defined in [SOAP Part 1] 5. SOAP Message Construct for SOAP header blocks MAY be used with the Representation header block.
Adding a env:mustUnderstand attribute information
item with a value of "true" in the
[attributes] property of the rep:Representation
element information item ensures that the SOAP receiver
is aware that the Web resource representation is available to it.
A env:role attribute information item in
the [attributes] property of the rep:Representation
element information item indicates the SOAP node for
which the Web resource representation is intended.
An xmlmime:contentType attribute information item
(See [Assigning Media Types to Binary Data in XML]) MAY be used to convey the
media type of the representation conveyed by a header. Media type
information can be useful in determining whether a given representation
is suitable for processing and if it is, how best to interpret the
representation provided. If used, the xmime:contentType
attribute information item MUST appear within the
[attribute] property of the rep:Data
element information item. An example of this usage is show
in Example Example.
A receiving SOAP node MAY act as a resolver, with all the rules
pertaining to HTTP caches, for some or all of the http:
scheme URIs for which representations have been provided.
To enable this, one or more element information
items MAY be added to the [children] property of
the rep:Representation
element information item to transmit the information
needed at the HTTP level.
To avoid requiring that all SOAP senders understand HTTP caching mechanism, all the data required by a processor that wants to act as a local cache needs to be carried along with the message. This includes the complete request, reply as well as the time the original HTTP request has been sent and the time the HTTP response has been received.
<htx:env xmlns:htx="http://www.w3.org/2004/02/xop/http">
<htx:request>
<htx:request-line name="GET" version="HTTP/1.1">
/someuri/xmlp.png
</htx:request-line>
<htx:header name="Host">
www.example.com
</htx:header>
<htx:header name="Accept">
image/png,image/jpeg,image/gif
</htx:header>
<htx:header name="Accept-Encoding">
gzip,deflate,compress;q=0.9
</htx:header>
<htx:header name="Date">
Fri, 13 Feb 2004 11:23:28 GMT
</htx:header>
[...]
<htx:time>
Fri, 13 Feb 2004 11:23:28 GMT
</htx:time>
</htx:request>
<htx:reply>
<htx:status-line version="HTTP/1.1" status="200">
OK
</htx:status-line>
<htx:header name="Content-Type">
image/png
<htx:header>
<htx:header name="Date">
Fri, 13 Feb 2004 11:23:28 GMT
</htx:header>
[...]
<htx:time>
Fri, 13 Feb 2004 11:23:32 GMT
</htx:time>
</htx:reply>
</htx:env>
Note that if the clocks of the SOAP sender and the SOAP recipient are not synchronized, all the expiration/age computed at the receiving side will not accurately reflect what could have been computed at the SOAP sender side.
This specification is the work of the W3C XML Protocol Working Group.
Participants in the Working Group are (at the time of writing, and by alphabetical order): TBD
Previous participants were: TBD
This document has its genesis as a separate section in the SOAP Message Transmission Optimization Mechanism (MTOM) document. The editors of the MTOM document, specifically Mark Nottingham and Hervé Ruellan are gratefully acknowledged.
The people who have contributed to discussions on xml-dist-app@w3.org are also gratefully acknowledged.