Headers proposal revisited

= Header Extension =

 

This extension is a feature is identified with the URI

http://www.w3.org/@@@@/@@/features/Header

 

== Operation ==

 

This feature exists in order to enable the description of
application-defined additional data declarations outside of the normal
data channel (e.g. the SOAP body). The senders take the value of the
property http://www.w3.org/@@@@/@@/features/Header/data
<http://www.w3.org/@@@@/@@/features/AD/data> , which is defined below,
and passes it to the receiver in a manner to be defined by the
particular bindings/modules implementing this specification.

 

= AD/data Property =

 

This property is identified with the URI
http://www.w3.org/@@@@/@@/features/Header/data
<http://www.w3.org/@@@@/@@/features/AD/data> .

 

== Description ==

 

The data property consists of a sequence of elements, each of which
represents an individual piece of application data.  Implementations of
this feature must ensure that the runtime value of this property is
correctly transferred from the sender to the receiver.

 

Here is an example of using the data property in a WSDL:

 

<types>

 <schema targetNamespace="http://foo"

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

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

  <import namespace="http://www.w3.org/2003/05/soap-envelope"/>

  <!-- Define the data type we'll use later -->

  <complexType name="myDataType">

   <sequence>

 

    <!-- These elements are our data -->

    <element name="isGoldClubMember">

     <complexType>

      <simpleContent>

       <extension base="xs:boolean"/>

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

                  ref="soap:mustUnderstand"

                  fixed="true"/>

      </simpleContent>

     </complexType>

    </element>

 

    <element name="promotionalCode"

             type="xs:string"

             minOccurs="0"/>

 

   </sequence>

  </complexType>

 </schema>

</types>

<interface name="customerService">

 <operation name="reserveCar">

  <input element="myNS:reserveCarRequest"/>

  <header element="myNS:foo:myDataType"/>

</operation>

</interface>

 

This example defines two pieces of application data, and associates them
with the input message of the "reserveCar" operation.  Notice that the
"promotionalCode" element is optional (minOccurs="0"), and that the
"isGoldClubMember" element has fixed the value of the SOAP 1.2
"mustUnderstand" element to "true".

 

 

= Header SOAP Module =

 

This module is identified with the URI

http://www.w3.org/@@@@/@@/modules/Header
<http://www.w3.org/@@@@/@@/modules/AD> 

 

== Features Implemented ==

 

This module implements the feature

http://www.w3.org/@@@@/@@/features/Header
<http://www.w3.org/@@@@/@@/features/AD> .

 

== Operation ==

 

This module specifies how to transmit "out of band" application data, as
defined in the Application Data feature, as SOAP headers.  

As a SOAP sender, if the property
http://www.w3.org/@@@@/@@/features/Header/data
<http://www.w3.org/@@@@/@@/features/AD/data>  has a value then each of
the top-level child element information items in the value SHOULD [ed:

MUST?] be turned into a SOAP header.  The elements are serialized
according to their schemas, which might include the SOAP
"mustUnderstand" or "role" attributes, which will have the usual meaning
in the resultant headers.  SOAP senders SHOULD also add an additional
header, with namespace "http://www.w3.org/@@@@/@@/modules/Header
<http://www.w3.org/@@@@/@@/modules/AD> " and local name "dataHeaders" -
this header contains a list of element QNames, one for each application
data header created in the first step.

 

It is the responsibility of the receiving node to determine which, if
any, SOAP headers will populate the
http://www.w3.org/@@@@/@@/features/Header/data
<http://www.w3.org/@@@@/@@/features/AD/data>  property.  Typically this
will be accomplished via using some metadata, such as an understanding
of a <constraint> specified in WSDL, or out-of-band agreements.  If the
"dataHeaders" SOAP header (described above) is present, the QNames
inside that header indicate which other headers are application data.

The contents of each SOAP header identified as application data will be
placed in a child element of the data property [ed: should we define a
particular "wrapper" element here as the top level one?].

 

=== The following gets added to the SOAP binding === 

 

The soap binding implements the Header Module.  By default, the Header
module is enabled.  The Header module is turned off by setting the
"disableHeaderModule" to true, ie

 

<soap:binding name="StockQuoteSOAP" interface="StockQuote"
disableHeaderModule="true">

 

 

=== The following gets added to the HTTP binding === 

 

== Features Implemented ==

 

The HTTP binding implements the feature

http://www.w3.org/@@@@/@@/features/Header
<http://www.w3.org/@@@@/@@/features/AD> .

 

= Operation = 

 

This section specifies how to transmit "out of band" application data,
defined in the Application Data feature, as HTTP headers.  The HTTP
binding implements this feature.  By default, the is enabled.

 

As an HTTP sender, if the property

http://www.w3.org/@@@@/@@/features/Header/data
<http://www.w3.org/@@@@/@@/features/AD/data>  has a value then each of
the top-level child element information items indicates a possible
element information item that SHOULD [ed:

MUST?] be turned into an HTTP header.  The http header name is
serialized from the element information item local name.  The http
header content is serialized from the element information item value.

The data elements should only be "xs:string" type, including xs:anyURI.

Any attributes on data elements are ignored.

Any complex data types are ignored.  Where the element information item
contains content that cannot be directly encoded per the HTTP
specification, it MUST be escaped.

 

It is the responsibility of the receiving node to determine which, if
any, HTTP headers will populate the
http://www.w3.org/@@@@/@@/features/Header/data
<http://www.w3.org/@@@@/@@/features/AD/data>  property.  Typically this
will be accomplished via using some metadata, such as an understanding
of a <constraint> specified in WSDL, or out-of-band agreements.  The
contents of each such HTTP header will be placed in a child element of
the data property [should we define a particular "wrapper" element here
as the top level one?].  Each child element information item is
generated by using the http header name as the element information item
local name [ed: should we define a particular namespace?] and the http
header value as the element information item value.  Where the HTTP
header contains content that cannot be directly encoded in the element
information item, it MUST be escaped.

 

The Header module is turned off by setting the "disableHeaderFeature" to
true

 

Issue: compose http and soap headers? 

 

Cheers,

Dave (and Glenn?)