W3C

SOAP Resource Representation Header

W3C Working Draft 28 April 2004

This version:
http://www.w3.org/TR/2004/WD-soap12-rep-20040428/
Latest version:
http://www.w3.org/TR/soap12-rep/
Editors:
Anish Karmarkar, Oracle Corp.
Martin Gudgin, Microsoft
Yves Lafon, W3C

Copyright ©2004 W3C®(MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.

Abstract

This document describes the semantics and serialization of a SOAP header block for carrying resource representations in SOAP messages.

Status of this Document

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 First Public 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.

The idea of a representation header idea was introduced in PASWA [PASWA] and the XML Protocol WG has worked on the header since the creation of the MTOM specification. This document is the first Working Draft to specify the representation header, however the XML Protocol WG considers the specification to be stable.

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 to xmlp-comments@w3.org mailing list (public archive). Note that all outstanding issues against this document are documented in the Working Group Issues List.

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.

Short Table of Contents

1. Introduction
2. Representation Header
A. References
B. Change Log (Non-Normative)

Table of Contents

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

Appendices

A. References
B. Change Log (Non-Normative)

1. Introduction

This document describes the semantics and serialization of a SOAP header block for carrying resource representations in SOAP messages.

1.1 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 a number of namespace prefixes throughout; they are listed in Table 1. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see XML Infoset [XML InfoSet]).

Table 1: Prefixes and Namespaces used in this specification.
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]).
xmime "[TBD]"
The namespace for representing MIME media-types in XML (see [????]).

1.2 Relation to other specifications

TBD

1.2.1 Relationship to the SOAP Processing model

This feature makes no changes to the SOAP processing model.

2. Representation Header

Editorial note: HR 
This whole section is new and comes from the resolution of 442. The original proposal was edited to better fit in the spec but this should not introduce any non-editorial changes (except the ones noted below).
Editorial note: HR 
The XML elements are described in term of Infoset contrary to the ones described in XOP which use the DM. Is this ok?

This section describes a SOAP header block, the Representation header block, that allows a SOAP message to carry representations of Web resources.

2.1 Introduction

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 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.

Example 1: Representation header block in a SOAP Envelope
<soap:Envelope xmlns:soap='http://www.w3.org/2002/12/soap-envelope' 
               xmlns:rep='http://www.w3.org/2004/02/representation' 
               xmlns:xmime='@@@@'>
  <soap:Header>
    <rep:Representation resource='http://example.org/me.png'>
      <rep:Data xmime:media-type='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>

2.2 Representation header block Constructs

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

  • One or more element information items in its [children] property in order as follows:

    1. A mandatory Data element information item (see 2.2.4 rep:Data element).

    2. 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.

2.2.2 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 identify the Web resource whose representation is carried in the rep:Representation element information item parent of the resource attribute information item.

2.2.3 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.

2.2.4 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.

2.3 Extensibility of the Representation header block

The Representation header block is built to be extensible. This section describes several possible usage of this extensibility.

2.3.1 SOAP header block Attributes

Attributes defined in [SOAP Part 1] 5. SOAP Message Construct for SOAP header block 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 ensure 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.

2.3.2 Specifying the media type

For a SOAP node receiving a SOAP Envelope containing a Representation header block, it can be helpful to know the media type of the representation in order to determine whether the representation is suitable for it or not.

To indicate the media type of the Web resource representation included in the SOAP Envelope, the sending SOAP node MAY add a xmime:media-type attribute information item (see ???) in the [attribute] property of the rep:Data element information item. An example of this usage is show in Example 1.

2.3.3 HTTP headers

A receiving SOAP node MAY want to act as a URI resolver and use the representation of a Web resource as a locally cached representation, with all the rules pertaining to HTTP caches. 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.

Editorial note: YL 
Fix the text regarding one or more, once the final proposal of the extension is there.

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.

Example 2: HTTP extension
<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>

[@@@ add definition of the different parts, and link to a schema to describe it]

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.

A. References

[SOAP Part 1]
W3C Recommendation "SOAP Version 1.2 Part 1: Messaging Framework", M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. F. Nielsen, May 2003. (See http://www.w3.org/TR/soap12-part1/.)
[SOAP Part 2]
W3C Recommendation "SOAP Version 1.2 Part 2: Adjuncts", M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. F. Nielsen, May 2003. (See http://www.w3.org/TR/soap12-part2/.)
[XOP]
W3C Working Draft "XML-binary Optimized Packaging", N. Mendelsohn, M. Nottingham, H. Ruellan, February 2004. (See http://www.w3.org/TR/2004/WD-xop10-20040209/.)
[SOAP 1.2 Attachment Feature]
W3C Working Draft "SOAP 1.2 Attachment Feature", H. F. Nielsen, H. Ruellan, September 2002. (See http://www.w3.org/TR/soap12-af/.)
[SOAP Attachment Requirements]
W3C Editors' copy "SOAP Attachment Feature Requirements", M. A. Jones, May 2003. (See http://www.w3.org/2000/xp/Group/3/02/24-soap-attachment-feature.html.)
[XML 1.0]
W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000. (See http://www.w3.org/TR/2000/REC-xml-20001006.)
[Namespaces in XML]
W3C Recommendation "Namespaces in XML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999. (See http://www.w3.org/TR/1999/REC-xml-names-19990114/.)
[XML InfoSet]
W3C Recommendation "XML Information Set", John Cowan, Richard Tobin, 24 October 2001. (See http://www.w3.org/TR/2001/REC-xml-infoset-20011024/.)
[XML Schema Part 1]
W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/.)
[XML Schema Part 2]
W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.)
[XML Schema Part 2 Errata]
W3C Internal Working Draft 7 March 2003 Id: datatypes-with-errata.xml,v 1.5 2003/03/07 19:54:00 (See http://www.w3.org/XML/Group/2002/09/xmlschema-2/datatypes-with-errata.html.)
[XML Query Data Model]
"XQuery 1.0 and XPath 2.0 Data Model", Mary Fernández, Ashok Malhotra, Jonathan Marsh, Marton Nagy, Norman Walsh, November 2003. (See http://www.w3.org/TR/xpath-datamodel/.)
[RFC 2119]
IETF "RFC 2119: Keywords for use in RFCs to Indicate Requirement Levels", S. Bradner, March 1997. (See http://www.ietf.org/rfc/rfc2119.txt.)
[RFC 2387]
IETF "The MIME Multipart/Related Content-type", E. Levinson, August 1998. (See http://www.ietf.org/rfc/rfc2387.txt.)
[PASWA]
"Proposed Infoset Addendum to SOAP Messages with Attachments", April 2003. (See http://www.gotdotnet.com/team/jeffsch/paswa/paswa61.html.)

B. Change Log (Non-Normative)

Table 2: Changes since first draft.
Who When What
ASK 20040414 Changed the [namespace name] property of reinsert attribute to be empty. Added Noah's ed change suggestions. Added 'SHOULD NOT' for multiple header blocks with same meta data, role and resource attr. values + behavior of nodes when this happens.
ASK 20040330 Added the resolution of issue 455 -- added new attribute reinsert and removed the sticky role + misc ed fixes.
ASK 20040316 Added resolution of issue 455 + misc cleanup.
YL 20040315 Tidied to look like a editor's copy
YL 20040305 Added HTTP extention.
MJG 20040301 Created skeleton document from MTOM draft (OptimizationMechanism.xml rev 1.29)