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.

(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 ant any Microsoft .Net service WSDL), but most services will define at least these ones as a minimum, although not always in exactly that form.

The "service" element

Although the last of the children of the <description> element, this 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.

The crucial element within the service is the <port>. This defines an implementation of the service as a network resource and has, as an attribute, a "binding", 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").

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.

Old Article

a wsdl file can be used to generate "stub" code that can access the webservice.

http://www.w3.org/TR/wsdl