Header/Body Style Proposal

Arguably the most common protocol design style for application protocols is
what this letter will refer to as the headerBody style. Protocols such as
HTTP, SOAP, FTP, IMAP, ACAP, SMTP, etc. all use application messages that
contain a single body and multiple headers.

Given the universal popularity of this design style this letter proposes
that WSDL 2.0 add direct support for this style to WSDL 2.0.

The headerBody style will use the message attribute to identify the
message's body. A new XML element, for use as a child of
input/output/infault/outfault in interface definitions, will be used to
specify one or more headers. The XML element is defined as headerDef and has
four attributes:

    * name - A NCNAME that uniquely identifies a header instance within a
specific input/output/infault/outfault within a specific operation within a
specific interface. Name is optional and is only needed if a binding will
need to provide additional information about the header.
    * header - The QNAME of a XML element schema definition that defines the
contents of the header.
    * max - An int which specifies the maximum number of times that header
instance can be repeated. Max is optional and its default value is 1.
    * min - An int which specifies the minimum number of times that header
instance can be repeated. Min is optional and its default value is 1.

max MUST be greater than or equal to min.

The headerDef XML element can be used 0 or more times.

For example:

<definitions...>
   <interface...>
      <operation...>
         <input message="My:body">
            <headerDef header="My:header"/>
            <headerDef header="My:otherHeader" min="3" max="7"/>
            <headerDef name="optheader" header="My:header" min="0"/>
         </input>
      </operation>
   </interface>
</definitions>

The headerBody style depends on the binding to define if the header ordering
is meaningful. In the previous example the first and third headers are of
the same type. Allowing types to repeat is useful for bindings where the
order of headers is meaningful.

The headerBody style will be useful with both of the bindings that WSDL 2.0
provides, SOAP and HTTP as both of these protocols are based on header/body
style messages. If this style is adopted then we can remove the element
attribute from the wsoap:header XML element and replace it with a name
attribute that would point to the name of the associated header in the
interface definition. The mustUnderstand and role attribute would remain the
same.

The SOAP binding for the headerBody style would specify that when sending a
message the header ordering SHOULD be maintained by the WSDL processor.

In the case of receiving a message the WSDL processor MUST be able to accept
SOAP headers in any arbitrary order and MUST be able to accept headers that
were not defined in the SOAP message's WSDL interface/binding definition.

SOAP headers MAY be implicitly rather than explicitly included in an
operation definition as a consequence of a WSDL function or a SOAP module.
In other words, rather than explicitly including a reliable messaging or
security header one can readily imagine such headers being added as a
consequence of a WSDL function/SOAP module that required reliability or
security of a certain type.

However, in many cases support for a particular function or module may not
be widespread amongst WSDL processors (even if the application layer above
the WSDL processor is aware of and able to handle the header implied by the
function/module) and so it may be necessary to include the SOAP header
definition explicitly, even if it is redundant to a particular
function/module, in order to allow for the widest syntactic compatibility.

The following is an example of a WSDL operation and SOAP binding that uses
the headerBody style.

<definitions xmlns:my="http://foo/bar">
   <types>
      <xs:scheme targetName="http://foo/bar">
         <xs:element name="headerOrBody" type="xs:string">/
      </xs:scheme>
   </types>
   <interface name="sample"
styleDefault="http://www.w3.org/@@@@/@@/wsdl/style/headerBody">
      <operation name="sampleOp1"
pattern="http://www.w3.org/@@@@/@@/wsdl/in-only">
         <input message="my:headerOrBody">
            <headerDef name="sampleOp1Header" header="my:headerOrBody"
min="0"/>
         </input>
      </operation>
   </interface>
   <binding name="soapSimplebind">
      <wsoap:binding
protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/"/>
      <operation name="sampleOp1Binding">
         <input messageReference="sampleOp1">
            <header name="sampleOp1Header" mustUnderstand="True"/>
         </input>
      </operation>
   </binding>
</definitions>

To save space I used the same element for the header and the body. What's
interesting about this example is that while sampleOp1Header is optional
(min="0"), the binding specifies that mustUnderstand = "True". What this
means is that IF the header is used THEN the mustUnderstand attribute MUST
be put on the header and assigned the value true.

Either of the following SOAP 1.2 messages would be legal using the previous
definition and binding:

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
                         xmlns:my="http://foo/bar">
   <env:Header>
      <my:headerOrBody mustUnderstand="true">really?</my:headerOrBody>
   </env:Header>
   <env:Body>
      <my:headerOrBody>Uh huh</my:headerOrBody>
   </env:Body>
</env:Envelope>

Or

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"
                         xmlns:my="http://foo/bar">
   <env:Body>
      <my:headerOrBody>Ahhh</my:headerOrBody>
   </env:Body>
</env:Envelope>

The HTTP binding would work similarly to SOAP but I'm waiting until the HTTP
POST/PUT proposal gets a bit firmer before I try to put in details. I think
the most interesting issue with HTTP header support is how to translate the
XML element name and body for the WSDL header into a HTTP header. One can
imagine a myriad of different encoding possibilities. A minimal encoding
would require the header body to be a string. But one could also imagine an
encoding that either strips out elements or replaces elements with a divider
character such as a ";". Perhaps we will need to support both and specify
which one to use on a header by header basis.

	Thanks,

			Yaron

Received on Tuesday, 20 January 2004 19:29:06 UTC