World Wide Webber

"Chewbacca is a Wookiee from the planet Kashyyyk who carried a gun and ran from the mob. But Chewbacca lives on the planet Endor. Now think about it. That does not make sense. Why would a Wookiee, an eight-foot-tall Wookiee, want to live on Endor with a bunch of two-foot-tall Ewoks. That does not make sense." [South Park]

Like a recurring bad dream I keep seeing this Chewbacca-esque document/literal wrapped convention being banded around (first pointed out to me in this IBM article - thanks Nigel!). Essentially it is a document (as in no method name), literal (as in uses its own schema) and then wrapped (as in, "oh yeah we really want a method name but we have to do doc/literal because RPC is bad"). For example, consider the following message definitions:

<!-- For rpc/literal -->
<message name="FooRequest">
  <part name="param" type="xsd:string"/>
</message>

<!-- For doc/literal -->
<types>
  <schema>
    <element name="Foo" type="xsd:string"/>
  </schema>
</types>

<message name="FooRequest">
  <part name="param" element="Foo"/>
</message>

<!-- For doc/literal + wrapped -->
<types>
  <schema>
    <element name="Foo"/>
      <complexType>
        <sequence>
          <element name="param" 
            type="xsd:string"
            minOccurs="1" maxOccurs="1"/>
        </sequence>
      </complexType>
    </element>
  </schema>
</types>

<message name="FooRequest">
  <part name="parameters" element="Foo"/>
</message>

And the following portType declaration:

<portType name="FooPT">
  <operation name="Foo">
    <input message="FooRequest"/>
  </operation>
</portType>

We get the following (pseudo) on-the-wire forms:

<!-- For rpc/literal -->
<Foo>
  <param>string</param>
</Foo>

<!-- For doc/literal -->
<Foo>
  string
</Foo>

<!-- For doc/literal + wrapped -->
<Foo>
  <param>string</param>
</Foo>

How annoying is that? Effectively doc/lit + wrapped is the same as rpc/lit with the exception that to get doc/lit + wrapped you have to do some unnatural things to your service's WSDL contract.

This does not make sense.

Your WSDL document should model the structure and exchange patterns of the documents exchanged in your real-world system, and should not be hacked like this to make your deficient Web Services tooling work! If you have to do this, you need to change your SOAP stack (and probably your project architect).

Use document/literal and let your service implementation work out how to dispatch the incoming message. It's none of the consumer's business how things get dispatched internally, so it doesn't make a great deal of sense to advertise your dispatch mechanism to the consumer (which is what rpc and document/literal + wrapped effectively do) only then to have consumers tell you how they want things dispatched in each message they send (yes Mark, before you ask I did read your comments :-)

Of course if you want to increase the level of coupling between consumers and services then this is a great way to do it...