First, in one paragraph, give me a quick introduction to WSDL.

Web Services Description Language (or WSDL and pronounced wiz-dull) is the text description that one computer program “reads” so that it knows how to talk to a given software program running on a remote computer (called a “web service”). WSDL is used to describe interfaces to web services. A set of WSDL files might include, for example, the names of routines that can be called on a given server, what parameters those routines expect, what values will be returned, and what underlying protocols you should use Footnote 1: “SOAP over HTTP” is almost always the underlying protocol, but a lesser known set of protocols like “XML-RPC over JMS” are theoretically possible too. to package up your information and ship it across. It also contains information about how data structures should look and what their schemas are.

So how does WSDL tie in to service oriented architectures?

WSDL files enable software applications to share their capabilities with each other without having to worry if they have compatible hardware, operating systems, or even if they have been implemented internally with different programming languages since a WSDL file is only about the interface and makes no assumptions about the implementation. WSDL files are themselves XML files (XML files are one giant string), so they can be easily passed between computers of different types. Sharing software capabilities inside and outside of a company, worrying only about what business capabilities are needed and not about technical details, is the lofty goal of service-oriented architectures, or “SOAs”, and WSDL is a key part of the SOA approach Footnote 2: Perhaps the most commonly plagiarized sentence in WSDL-related books and articles today is “WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information” (originally from the “W3C Note” WSDL specification at It’s amazing how many authors have used this sentence verbatim. Shhhhhh…it’s a trade secret… don’t tell anyone. .

So if WSDL is key to SOAs, what are the two other key parts?

UDDI, WSDL, and SOAP are the three primary components of web services and service oriented architectures and it helps to understand WSDL in the context of the others. UDDI is the piece no one ever seems to use. In brief, UDDI is a phone book style directory of web services that is used to find a server that provides a certain desired software capability. UDDI makes it so clients don’t have to know where the web service servers are – they just have to know where the UDDI server is so they can look up the service they need. Once the web server has been dynamically discovered at run time, a WSDL file(s) that describes the interface is passed back to the client from the desired server. The web service client interprets this WSDL file so that it knows how to bundle up SOAP messages to be sent to the server (a SOAP message is an XML document that contains instructions such as “call routine X with parameters Y and Z”). From that point on, the client and server just continually exchange SOAP messages.

Does anyone on this planet really use UDDI?

In practice, if UDDI is used at all, it’s used only at development time and not at run time. UDDI is usually omitted from SOA runtime operations since the location and message formats of the web servers is considered fixed and a dynamic look-up simply is not needed. Instead, the contents of the WSDL file just get “hard coded” and UDDI is completely bypassed. On the other hand, when UDDI is actually used at run time (virtually never in the real world), the WSDL file is interpreted on the fly at run time once it is retrieved from the UDDI server to dynamically figure out where the service is and how to talk to it. So WSDL files can be used at run time in the case of dynamic service discovery, or at compile time, in the case that the interfaces are considered fixed at a given server.

So what's the big deal about XML?

Service oriented architectures can be implemented using many combinations of underlying technologies, but it is common to choose ones that traverse well through firewalls. HTTP is firewall friendly because it is typically used to access web pages and system administrators assume that HTTP traffic is innocuous web page content (a questionable assumption especially when HTTP is being used to call internal software routines). WSDL, SOAP, and UDDI files are all XML files that differ only in their expected content. XML files are considered firewall friendly since XML contents are entirely made up of simple text, which is extremely portable across hardware platforms and much less likely to contain viruses than binary information. SOAs frequently uses these XML files and ship them over HTTP to communicate with web services on the other side of firewall boundaries – either inside or outside of an organization.

Since WSDL files are written in XML, they are… errrrrr… “easy” to read, especially if by “easy” you mean “impossible”. This is because WSDL files are almost always generated by software (not humans) and then later read and interpreted by software (not humans). Development tools are commonly used to generate WSDL files from some existing legacy code. For example, many tools exist to generate WSDL files from existing Java routines. Those WSDL files will be provided to web service clients later (either at run time or during development), and tools on the client side will read and interpret them in order to construct messages to the server.


Will anyone on my project ever need to read a WSDL file?

So even with the best tools, if your architecture relies in any way on WSDL files Footnote 3: It is possible to have a web service architecture that doesn’t use WSDL and just constructs and sends SOAP messages manually. , you’ll need a basic understanding of the contents of those files Footnote 4: and a bottle of pain killers. , even if only to understand the confusing error messages you’ll see at some point in the future. After all, when your development or runtime tools encounter a problem and can’t figure it out, they can only dump out the low level WSDL contents and say “here – you figure it out”. So let’s just cover the bare minimum of WSDL basics. Ah come on. It’ll be... errr... fun.

Just to help me understand, what are the basic parts of a WSDL file?

There are five basic parts to a WSDL file – types, messages, portTypes, bindings, and services. Consequently, the basic structure of a WSDL file looks like this:



Here’s where you put the definitions for your complex data types – like order, customer, or product objects. This section can also be empty if only simple data types are used, like integers and strings.



Here’s where you put the definitions of the messages that your services understand. The pieces of information passed in an incoming message are translated into function call parameters for the legacy code.



Here’s where you define what the names of the operations are and what messages they take and give back. This is usually the most interesting and comprehensible part. This section looks a lot like a Java or C++ class definition.



Here’s where you provide the low level details for each operation in every portType (for example, specifying that a given port’s communication will be SOAP messages sent over HTTP). The binding section also has information on how input and output should be encoded (meaning which technique should be used to serialize data into XML), and whether rpc or document style messages should be used (see the SOAP chapter).



The service element is really just a collection of ports


Here’s where you usually see the server name and URL hard coded. The URL for the server is mapped here to one of the bindings, which in turn, maps back to portTypes. The port->binding->portType mapping is extremely confusing.




In WSDL 2.0, the message section was eliminated and the porttype section was renamed to “interface”. But almost no one has upgraded to WSDL 2.0 yet.

Complicated? You bet. That’s why these files are always generated and interpreted by tools.


What are the common and serious mistakes that companies repeatedly make with WSDL?

There’s no shortage of complaints about WSDL out on the net, but the industry continually embraces it anyway.  Why?  Are the complaints unfounded or exaggerated?  What are the most common mistakes made with WSDL projects?  And what pitfalls are frequently encountered with all the other technologies that tend to accompany WSDL? As Ben Franklin once noted, an ounce of prevention is worth a pound of cure.  Franklin was obviously referring to learning the common WSDL mistakes early-on, before disaster sets in, and who are we to argue with a SOA expert like Ben Franklin?  Click on ye ol’ “Buyeth Now” button. Seriously - don't just settle for the excerpt from the "Overview" section of the WSDL chapter above. Understand the common mistakes for WSDL and for all of the SOA-related technologies. Act now to protect your career.