Resource Representation SOAP Header Block

%entities; ]>

&status;

$Date: 2007/07/11 20:00:43 $ http://www.w3.org/TR/2005/REC-soap12-rep-20050125/ http://www.w3.org/TR/&shortname-rep;/ Anish Karmarkar Oracle Corp. Martin Gudgin Microsoft Yves Lafon W3C English

Last Modified: $Date: 2007/07/11 20:00:43 $

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

Introduction

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

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 .

This specification uses a number of namespace prefixes throughout; they are listed in . Note that the choice of any namespace prefix is arbitrary and not semantically significant (see XML Infoset ).

Prefixes and Namespaces used in this specification.
Prefix	Namespace
Prefix	Notes
env	http://www.w3.org/2003/05/soap-envelope
env	A normative XML Schema , 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/08/representation
rep	A normative XML Schema , document for the http://www.w3.org/2004/08/representation namespace can be found at http://www.w3.org/2004/08/representation.
xs	http://www.w3.org/2001/XMLSchema
xs	The namespace of XML Schema data types (see ).
xmime	&xmlmime;
xmime	The namespace for representing MIME media-types in XML (see ).

All parts of this specification are normative, with the exception of examples and sections explicitly marked as "Non-Normative".

Relation to other specifications

This document along with and has been produced in conjunction with the development of requirements, embodied in the requirements document .

This document defines a SOAP Feature, and a SOAP Module that realizes the SOAP Feature, as specified by SOAP 1.2 3.1 SOAP Features and 3.3 SOAP Modules.

Note: The Resource Representation header block is designed to optimize well when used with the SOAP Message Transmission Optimization Mechanism .

Note: The Resource Representation header block is designed, but not required, to be used in conjunction with the Describing Media Content of Binary Data in XML specification .

Relationship to the SOAP Processing model

This feature makes no changes to the SOAP processing model.

SOAP Feature Name

The Resource Representation header block defined by this document embodies the SOAP feature 3.1 SOAP Features identified by the URI:

http://www.w3.org/2004/08/representation

The above SOAP feature URI can be used to identify the semantics and serialization of the Resource Representation header block.

SOAP Module Name

The SOAP Module 3.3 SOAP Modules that realizes the SOAP feature defined in is identified by the URI:

http://www.w3.org/2004/08/representation

The above SOAP Module URI can be used to identify the semantics and serialization of the Resource Representation header block.

Representation Header Block

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

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 Representation header block is also useful when multiple references to the same resource are required but duplication of the resource is undesirable. See UC2 and UC6 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 obtain a representation of the 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.

Multiple occurrences of the Representation header block MAY be present in the same SOAP Message to carry representation of multiple Web resources or multiple representations of the same Web resource.

Several occurrences of the Representation header block having the same value for the role and resource attribute information item (see ) 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.

URIs that are character for character identical MUST be considered equal when using a representation header to resolve a web reference; URIs that are considered equal according to the URI scheme of the URI SHOULD be considered equal.

An example SOAP Envelope using the Representation header block is given below.

Representation header block in a SOAP Envelope <soap:Envelope xmlns:soap='http://www.w3.org/2003/05/soap-envelope' xmlns:rep='http://www.w3.org/2004/08/representation' xmlns:xmime='&xmlmime;'> <soap:Header> <rep:Representation resource='http://example.org/me.png'> <rep:Data xmime: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> Representation header block Constructs rep:Representation element

The Representation element information item has:

A [local name] of Representation.

A [namespace name] of http://www.w3.org/2004/08/representation.

One or more attribute information items amongst its [attributes] as follows:

A mandatory resource attribute information item (see ).

An optional reinsert attribute information item (see ).

Zero or more namespace qualified attribute information items whose [namespace name] is not http://www.w3.org/2004/08/representation.

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

A mandatory Data element information item (see ).

Zero or more element information items whose [namespace name] is not http://www.w3.org/2004/08/representation.

The rep:Representation element information item contains a representation of a Web resource. The value of the resource attribute information item is the identifier of 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 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 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/08/representation.

Zero or more namespace qualified attribute information items whose [namespace name] is not http://www.w3.org/2004/08/representation.

Any number of character 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.

Extensibility of the Representation header block

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

SOAP header block Attributes

Attributes defined in 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.

Specifying the media type

An xmime:contentType attribute information item (See ) 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 [attributes] property of the rep:Data element information item. If the media type identified by the value of an xmime:contentType attribute information item is a text based media type then the value of the xmime:contentType attribute information item SHOULD include a charset parameter.

An example that uses the xmime:contentType attribute information item is shown in .

Extension example: HTTP resolver extension

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

HTTP extension <soap:Envelope xmlns:soap='http://www.w3.org/2003/05/soap-envelope' xmlns:rep='http://www.w3.org/2004/08/representation' xmlns:xmime='&xmlmime;'> <soap:Header> <rep:Representation resource='http://example.org/me.png'> <rep:Data xmime:contentType='image/png'>/aWKKapGGyQ=</rep:Data> <htx:env xmlns:htx="http://www.w3.org/2004/08/representation/http"> <htx:request> <htx:request-line name="GET" version="HTTP/1.1"> /me.png </htx:request-line> <htx:header name="Host"> example.org </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> </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>

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.

References &name-part1;, Martin Gudgin, Marc Hadley, Noah Mendelsohn, Jean-Jacques Moreau, Henrik Frystyk Nielsen, Anish Karmarkar, Yves Lafon, Editors. World Wide Web Consortium, &draft.day; &draft.month; &draft.year;. This version is &dated-part1;. The latest version is available at http://www.w3.org/TR/soap12-part1/. XML-binary Optimized Packaging, Mark Nottingham, Noah Mendelsohn, Martin Gudgin, and Hervé Ruellan, Editors. World Wide Web Consortium, &xopdraft.dd; &xopdraft.month; &xopdraft.year;. This version is &dated-xop;. The latest version is available at http://www.w3.org/TR/xop10/. SOAP Message Transmission Optimization Mechanism, Hervé Ruellan, Noah Mendelsohn, Martin Gudgin, and Mark Nottingham, Editors. World Wide Web Consortium, &mtomdraft.dd; &mtomdraft.month; &mtomdraft.year;. This version is &dated-mtom;. The latest version is available at http://www.w3.org/TR/soap12-mtom/. SOAP Optimized Serialization Use Cases and Requirements, Tony Graham, Mark Jones, and Anish Karmarkar, Editors. World Wide Web Consortium, 08 June 2004. This version is http://www.w3.org/TR/2004/WD-soap12-os-ucr-20040608/. The latest version is available at http://www.w3.org/TR/soap12-os-ucr/. XML Information Set (Second Edition), Richard Tobin and John Cowan, Editors. World Wide Web Consortium, 04 February 2004. This version is http://www.w3.org/TR/2004/REC-xml-infoset-20040204. The latest version is available at http://www.w3.org/TR/xml-infoset. XML Schema Part 1: Structures Second Edition, David Beech, Murray Maloney, Henry S. Thompson, and Noah Mendelsohn, Editors. World Wide Web Consortium, 28 October 2004. This version is http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/ The latest version is available at http://www.w3.org/TR/xmlschema-1/. XML Schema Part 2: Datatypes Second Edition, Ashok Malhotra and Paul V. Biron, Editors. World Wide Web Consortium, 28 October 2004. This version is http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/. The latest version is available at http://www.w3.org/TR/xmlschema-2/. Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, Editor. IETF, March 1997. This RFC is available at http://www.ietf.org/rfc/rfc2119.txt. Describing Media Content of Binary Data in XML, Ümit Yalçınalp and Anish Karmarkar, Editors. World Wide Web Consortium, 04 May 2005. This version is http://www.w3.org/TR/2005/NOTE-xml-media-types-20050504/. The latest version is available at http://www.w3.org/TR/xml-media-types. Uniform Resource Identifiers (URI): Generic Syntax, T. Berners-Lee, R. Fielding and L. Masinter, Editors. IETF, January 2005. Obsoletes: RFC 2396, RFC 2732. This RFC is available at http://www.ietf.org/rfc/rfc3986.txt.

Acknowledgements

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): &wgmb;

Previous participants were: &prevwgmb;

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.