Understanding WSDL

Understanding WSDL

WSDL (web service description language) is an XML family document describing how to interact with the web service described. Web services can be consumed by the code, generated using WSDL definition, that knows precisely how to interact with the web service. In a nutshell WSDL document contains details about data definition, operations, transport protocols and address of the web service.

WSDL document mainly consists of two sections – Abstract definitions and concrete descriptions. The abstract definition details about data definitions, messages and operations. Concrete section describes bindings or data format specification for operations, and the network address of the service host. A WSDL containing only abstract section is called an abstract WSDL and the one that contains bindings and network details as well is called a concrete WSDL. WSDL build during Oracle SOA development will be abstract in nature. The WSDL, obtained from the server, after deployment is concrete in nature.

Figure 1 WSDL Structure

Figure 1 WSDL Structure

Rest of this document discuss different sections of the WSDL in detail with code examples. During this walk through I have snipped code samples from WSDL provided by www.webservicex.com. To access the WSDL please click on below link. globalweather.asmx?wsdl

·       Abstract section

o   types: Types basically defines the data types used in the messages. A WSDL can have multiple types blocs, each of them can have multiple schema blocks (XSDs).

o   message: An abstract typed definition of the data that could be an input to or output from an operation. A WSDL can have multiple message blocks, each block containing one or more parts referring to elements defined in types block.

o   portType: portType defines an abstract set of operations. operation represents a method signature with parameters referring to the messages defined in message section. A WSDL can have multiple portType blocks, with multiple operations.

An operation block can have three types of parameters, input, output and fault. Every operation contains a mandatory input block, an optional output block, and multiple optional fault blocks followed by an existence of output block.

·       Concrete section

o   binding: binding implements portType. binding is a concrete protocol and data format specification for a particular portType. There could be more than one bindings for a given portType depending on the protocol and data format specification.  Below codes snippet shows that the same portType GlobalWeatherSoap (type = GlobalWeatherSoap in wsdl:binding element) has two different bindings one with soap protocol (targetNamespace = http://schemas.xmlsoap.org/wsdl/soap/) protocol and another with soap12 (targetNamespace = http://schemas.xmlsoap.org/wsdl/soap12/) protocol.

o   service: service is a collection of endpoints or ports. port is an end point, which is a combination of binding and a network address.

While invoking a webservice, the input XML data sent by the client is passed and validated against XSD (defined in types block) used for input message parameters in operation. The output XML data generated by the webservice is again parsed and validated against corresponding XSD defined in types block of the WSDL. In all the above XML code snippets each node has a tag that contains prefix, colon and element name. Here the prefix is called namespace qualifier. This qualifier plays a very important role in validating XMLs agains XSDs, and cross referencing the XML documents. We will understand more details about XML namespaces in the next post.

Understanding XML & XSD in SOAP webservice context

In the world of integration applications, we have been hearing about webservices mainly of types REST and SOAP. In general, a SOAP webservice publishes its definition file with WSDL (Webservice definition language) extension that belongs to XML (Extensible Markup Language) family. A typical webservice definition file contains details about services/operations, input & output definitions of these operations along with the network addresses. The input and output definitions are part of the WSDL and belong to XML family. As they are of family XML and defines a specific format, these files, if stored separately, uses XSD (XML schema definition) extension. In this post we will discuss basics of XML and XSD that are needed to work with webservices.

To consume a service defined in a webservice, users should have its definition WSDL file. While consuming the service, the input file has to follow the format defined by XSD inside the WSDL. Therefore, input XML, XSD and WSDL belong to XML family and the dependency moves in the direction of WSDL to XSD to XML. We will discuss about WSDL in detail in the next post. Any XML document should be well-formed in the sense every node should be closed properly. The nodes could be of type simple or complex. Complex node is a combination of a set of either simple or simple and complex nodes.

Figure 1 Simple element example from XSD file

Figure 2  Simple element example from input XML file

Figure 3  Complex element example from XSD file

Figure 4  Complex element example from input XML file

Usually in context of webservices input or output XMLs are well-formed and should be valid against the XSD definition. XMLs are created as per the definition provided by XSD file, that contains definition of simple and complex elements, their attributes and restrictions. To understand the relation between an XML and XSD consider a webservice that accepts as shown in below figure.

Figure 5 Relating XML and XSD elements

In this example inside XSD content the first node contains process instructions. Employee Information (EMPLOYEE_INFO) is a complex element of child elements - EMPLOYEE_ID, EMAIL_ADDRESS and MAIL_ADDRESS as input. Here MAIL_ADDRESS is another complex element containing further child elements. Each of these tags have proper logical closure, and therefore this XSD is well-formed. If you observer the element with name attribute equal to EMPLOYEE_ID, this element defines the data type to be an integer forcing the input XML defined over this XSD should have an integer value for element EMPLOYEE_ID.

Here the input XML on the right side of above figure is created based on the definition of XSD. As you can observe it is a well-formed document. In addition, this input XML document contains simple and complex elements with appropriate data types as forced by the XSD document. Therefore, this is a valid XML against the XSD document. We will discuss about WSDL in details in our next post.