WSDL

WSDL [1] - Web Service Description Language - is the mechanism for specifying the contract that a service offers to its clients. It is an XML dialect and either pronounced with the letters in full or as "wiz-dul".

WSDL is most commonly automatically generated by the service software - this is the case with Visual DataFlex - but in some cases, where the software used does not provide this capability, it may be hand-written. This latter case can produce some very idiosyncratic and non-standard WSDL that causes problems for service consumers.

If your software platform or toolkit provides for automatic generation of WSDL from your own services, and for automatic creation of proxy or stub client code from other people's services, then it should never be necessary to understand the complexities of WSDL... until somethings goes wrong! Then you may have to "look under the hood".

(Note: I will be describing WSDL 1.x here - 2.0 is different in a number of regards. Mike)

Structure

WSDL can be quite formidable to understand for those not used to looking at such things. Probably the easiest way to get to grips with is is to break it down into its various components.

After any initial processing instruction (<?xml version="1.0" encoding="UTF-8"?> or similar) there will be the outer <description> element, which will typically also define a number of namespaces that will be used in the document.

Within that there will (usually, and in WSDL 1.1) be four or five main types of element, grouped together, in the following order:

• types - only one element (optional) describing the extended data types used by the service
• message - defining the in and out messages used by the service's operations
• portType - defining the abstract definition of the service
• binding - providing a link between the abstract definition and the concrete implementation
• service - the concrete specification of a service

This arrangement is convenient for machines to read, as each part is defined prior to encountering the parts that use it, but it is confusing for humans, so for that reason we will deal with those sections in reverse order.

The "description" element

The description element, as well as serving as the XML document root, also defines (some of) the namespaces used in the document. Typically these will include:

• The base WSDL namespace: ="xmlns="http://schemas.xmlsoap.org/wsdl/"
• The XML Schema namespace, where the base XML types are defined: ="xmlns:xs="http://www.w3.org/2001/XMLSchema"
• The SOAP namespace: ="xmlns:soap"http://schemas.xmlsoap.org/wsdl/soap/"
• The service's own namespace, which is usually associated with the namespace prefix "tns" - (this namespace): ="xmlns:tns="http://yourDomain/yourService/serviceName"
• The "target" namespace, which is often identical to the "tns" one: ="targetNamespace="http://yourDomain/yourService/serviceName"

There may be many more than these (look at any Microsoft .Net service WSDL), but most services will define at least these ones as a minimum, although not always in exactly that form. In particular, the choice of namespace prefixes is arbitrary, so the base namespace might be specified as "xmlns:wsdl", rather than just "xmlns"; "xmlns:xs" is often seen as "xmlns:xsd"; "xmlns:soap" might be "xmlns:soap12" (in reference to SOAP 1.2) or many other variations - remember that it is the actual namespace URI that is being referenced that is important, not the prefix used to represent it ikn the document, which can be anything.

The "service" element

Although the last of the children of the <description> element, the service element is the natural starting point for human WSDL readers. There can be more than one service defined in a single WSDL document, which is sometimes sensible for describing different physical services which share the same logical definition (a service provider might provide the same service from a number of different network locations - i.e. servers - to provide redundancy, or multiple services might share some aspects, in particular data types, in common), however most commonly only a single service will be described.

Like most of the WSDL main elements, the service element can have a <documentation> element within it. In Visual DataFlex you can set this via the "psDocumentation" property of the Web Service object. It will also have a name attribute, which will be whatever you set the psServiceName property of your Web Service object to.

The crucial element within the service is the <port>. This defines an implementation of the service as a network resource and has a "binding" attribute which will usually point to a <binding> element (see below) in the same WSDL document (and hence will tend to have the namespace prefix "tns": this nampespace). This will attribute will lead us on our trail, up the WSDL, to our next stop, the binding element.

While there are sometimes other protocols defined (HTTP, SMTP, FTP, etc.), the commonest by far is for SOAP, so within the <port> element it is common to find a <soap:address> element, specifying, via its "location" attribute, the actual URI through which the service can be invoked.

The "binding" element

The binding element is what joins the physical implementation of the secvice - a <port> element within the <service> element - to its logical (or abstarct) definition, which is represented by the <portType> element (see below).

The binding element will have two attributes which effect this joining: its name attribute, which is what is pointed to by the binding attribute of the service "port" element above, and its type attribute which in turn points to a "portType" (again, usually defined within the same WSDL document and hence having a "tns" prefix.

Within the binding element there will be one or more protocol binding elements, the most common of which is the <soap:binding>. This will define the SOAP style attribute, either "rpc" or "document", and a transport element, set to a URI defining that, such as "http://schemas.xmlsoap.org/soap/http".

Following this there will be the <operation> elements, each with a name attribute (in Visual DataFlex this will be the name of the published Function or Procedure).

Each of these will contain first a operation protocol binding, such as <soap:binding> which will again define a style attribute and also a soapAction attribute; this latter will appear as the HTTP Header field "SOAPAction" in the messages sent to and from the operation (in Visual DataFlex services this is set to an empty string).

Following this there will be <input> and <output> elements for the operation, containing a definition of the way data is to be passed in the messages. Typically this will take the form of a <soap:body> element with a use attribute specifying either "literal" or "encoded. If an "encoded" usage is specified then an encodingStyle attribute may be present, pointing to a URI defining the style, such as "http://schemas.xmlsoap.org/soap/encoding/". There may also be a namespace attribute, for specifying a specific namespace for the operation. Additionally may be a <soap:header> element, but discussion of this falls outside the scope of this article.

The "portType" element

The portType element is the abstract representation of the service and is identified by its name attribute (what the type attribute of a binding elememt points to).

It will contain a number of operation elements, one for each operation of the service.

Each operation may contain a documentation element, describing the operation (in Visual DataFlex you can set this through the "{ Description = }" meta-data tag that preceeds your published Function or Procedure).

There will then be <input> and <output> elements, each of which will contain a message attribute, pointing to (the name attribute of) a message element (see below) which will hold the definition of that input or output message. Such message elements will usually appear within the same WSDL document and thus will commonly have the "tns" prefix.

The "message" element

The message elements define the structure of the data which will be passed as the contents to and from the service.

Each message element has a name attribute (which is what the message attributes of the portType input/output message elements was pointing to).

Typically the message element will then contain <part> element(s). In the case of document-style services there will only be one of these, as in document-style all the data tends to be sent (or received) as a single XML document (hence the name), however for RPC-style services there may be any number, with each corresponding to a parameter passed to, or returned from, the implementing function or procedure. Each part element will have a name attribute - in Document-style this is usually always "parameters", while in RPC-style it will be the name of the argument to the function. Finally there will either be a type attribute (RPC only) or an element attribute (RPC or Document). If a type attribute is used then it will define the primitive XML data type of the parameter. If an element attribute is used then it will refer to a data type (complex or otherwise) defined elsewhere - typically in the <types> element (see below) of the same WSDL document and hence will have the "tns" prefix.