Simplified WSDL Syntax

INTRODUCTION

This letter proposes three new features for WSDL 2.0 intended to make it
much easier for users to directly interact with WSDL definitions. The first
feature allows for the use of inclusion by value as an addition to WSDL
2.0's current standard mechanism of inclusion by reference. The second
feature provides simplified elements that can be used to describe common
WSDL scenarios. The third feature provides a simplified serialization for
the WSDL 2.0 infoset that makes WSDLs easier to read and write.

MOTIVATION

Below is probably the simplest real world WSDL I could come up with.

<definitions targetNamespace="http://example.com/blip"
                     xmlns:my="http://example.com/blip">
   <types>
      <xs:schema targetNamespace="http://example.com/blip">
         <xs:element name="in" type="xs:string"/>
      </xs:schema>
   </types>
   <interface name="aninterface">
      <operation name="anoperation"
pattern="http://www.w3.org/@@@@/@@/wsdl/in-only">
         <input message="my:in"/>
      </operation>
   </interface>
   <binding name="abinding" interface="my:aninterface">
      <wsoap:binding protocol="http://whateveritis"/>
   </binding>
   <service name="aservice" interface="my:aninterface">
      <endpoint name="anendpoint" binding="my:abinding">
         <wsoap:address address="http://ickybick.com/boo"/>
      </endpoint>
   </service>
</definitions>

The previous WSDL has a single in-only operation that is bound to SOAP. It
took 11 Elements & 14 attributes to define this, if one ignores the contents
of the xs:schema element. Each element and attribute represents a choice
that the WSDL designer had to make for a total of 25 decisions.

A lot of the complexity in designing a WSDL comes from WSDL's flexibility.
Flexibility is a good thing but it isn't something one should be forced to
pay for when one doesn't need it. Put another way, a good design rule is
that one should only pay the cost for the features one needs.

INCLUSION BY VALUE

One basic flexibility that leads to a lot of cost is inclusion by reference.
In many cases the separation between service, binding and interface
definitions in a WSDL are really artificial. That is, the definitions will
only be used with each other so the flexibility of by-reference inclusion
adds complexity without benefit.

Therefore it would seem reasonable to allow implementers a choice between
including information by reference or by value.

SIMPLIFIED ELEMENTS FOR COMMON CASES

In addition our experience with WSDL 1.1 shows that a vast majority of
features are not used in a vast majority of circumstances. This is not an
argument to remove the minority features. The extensibility they represent
is important for WSDL to be able to grow and when they are needed they are
badly needed. But, requiring everyone, everywhere to pay the full complexity
of these features when they don't need them seems unfair. Therefore I think
it would be a reasonable act on the part of the working group to provide
certain shortened forms for very common scenarios. For example, a WSDL
interface containing nothing but in-out and in-only and bound to SOAP is
likely to be a hugely common scenario for the immediate future. So why not
provide a short cut that would make it easier to read and write such common
patterns?

Below I give an example of a WSDL defined using a combination of by-value
and simplified patterns for common usage scenarios.

<definitions targetNamespace="http://example.com/blip"
                     xmlns:my="http://example.com/blip">
   <service name="my:service">
      <interface>
         <soapinoperation protocol="http://whateveritis">
            <inmessage>
               <xs:schema targetNamespace="http://example.com/blip">
                  <xs:element name="in" type="xs:string"/>
               </xs:schema>
            </inmessage>
         </soapinoperation>
      </interface>
      <soapendpoint address="http://ickybick.com/boo"/>
   </service>
</definitions>

7 elements and 6 attributes = 13 decisions (ignoring the contents of the
xs:schema element)

This is a 48% reduction in complexity. The inevitable cost for reducing
complexity is a reduction in choice but given that the previous, if we threw
in in-out, represents the 80% case for Web Service WSDLs this seems a
reasonable price to pay.

SIMPLIFIED SERIALIZATION OF THE INFOSET

There is another step we can take, inspired by XQUERY, which is to provide
an alternate serialization to XML. Since WSDL is defined at the InfoSet
level providing such an alternate serialization is not a major challenge.

definitions targetNamespace = "http://example.com/blip"/
                   xmlns:my = "http://example.com/blip"
   service name="my:service"
      interface
         soapinoperation protocol="http://whateveritis"
            inmessage
               xs:schema targetNamespace = "http://example.com/blip"
                  <xs:element name="in" type="xs:string/>
      soapendpoint address="http://ickybick.com/boo"

The previous uses a strict positional system to encode element names. 3
spaces equal one 'level'. So you know that soapin is a child of interface
because soapin is 3 space farther in than interface. WSDL responds well to
such a system because most elements have relatively little content. For some
things, such as schema, one probably wants to just use XML and so that is
made possible. A simple encoding rule, that any child that starts with < is
XML, makes it trivial to mix XML and non-XML content.

Even the fully verbose WSDL benefits in terms of readability from this
encoding:

definitions targetNamespace="http://example.com/blip"/
                  xmlns:my="http://example.com/blip"
   types
      xs:schema targetNamespace="http://example.com/blip"
         <xs:element name="in" type="xs:string"/>

   interface name="aninterface"
      operation name="anoperation"/
                      pattern="http://www.w3.org/@@@@/@@/wsdl/in-only"
         input message="my:in"

   binding name="abinding" interface="my:aninterface"
      wsoap:binding protocol="http://whateveritis"

   service name="aservice" interface="my:aninterface"
      endpoint name="anendpoint" binding="my:abinding"
         wsoap:address address="http://ickybick.com/boo"

CONCLUSION

It is fair to ask - why do we care? What's the big deal of cutting the
number of attributes and elements in half? Byte bloat can't be that big a
deal, can it?

The answer is that our experience with WSDL 1.1 worries us deeply. We have
found that the majority of our customers cannot read or write a WSDL, not
even with a tool. The result is that customers are generally unwilling to
use WSDL outside of the very specific scenario of RPC/Encoded where they
treat WSDL as an opaque IDL definition.

We firmly believe that for Web Services to meet its promise users must start
to build loosely coupled/large grained messages and for that to happen users
must become comfortable with WSDL.

Therefore we believe it is crucial that normal users in normal circumstances
be able to both read and write WSDLs so that they will feel comfortable in
leaving behind RPC and moving towards real loose coupling and large grained
messaging.

Received on Tuesday, 20 January 2004 19:53:57 UTC