SCDJWS Study Guide: WSDL

Printer-friendly version | Mail this to a friend

WSDL Document Elements

The Web Services Description Language (WSDL) is an XML language for describing the syntax of Web Service interfaces and their locations. 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[Web Services Description Language (WSDL) 1.1].

Programmers or automated development tools can create WSDL files to describe a service and can make the description available over the Internet. Client-side programmers and development tools can use published WSDL descriptions to obtain information about available Web Services and to build and create proxies or program templates that access available services.

A WSDL document has a definitions root element that contains the types, message, portType, binding, and service five different subelements. The diagram below illustrates the elements that are present in a WSDL document, and shows how they are related (The origanl picture come from http://www.oracle.com/technology/tech/webservices/htdocs/wsvsm/wsdlover.html).

The following is an example of a WSDL document:

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="StockQuote"
       targetNamespace="http://example.com/stockquote.wsdl"
       xmlns:tns="http://example.com/stockquote.wsdl"
       xmlns:xsd="http://www.w3.org/2000/10/XMLSchema">
       xmlns:xsd1="http://example.com/stockquote.xsd"
       xmlns:soapbind="http://schemas.xmlsoap.org/wsdl/soap/"
       xmlns="http://schemas.xmlsoap.org/wsdl/">

    <types>
       <xsd:schema targetNamespace="http://example.com/stockquote.xsd"
              xmlns="http://www.w3.org/2000/10/XMLSchema">
           <element name="TradePriceRequest">
              <complexType>
                  <all>
                      <element name="tickerSymbol" type="string"/>
                  </all>
              </complexType>
           </element>
           <element name="TradePrice">
              <complexType>
                  <all>
                      <element name="price" type="float"/>
                  </all>
              </complexType>
           </element>
       </xsd:schema>
    </types>

    
    <message name="GetLastTradePriceInput">
        <part name="body" element="xsd1:TradePriceRequest"/>
    </message>
    <message name="GetLastTradePriceOutput">
        <part name="body" element="xsd1:TradePrice"/>
    </message>

    
    <portType name="StockQuotePortType">
        <operation name="GetLastTradePrice">
           <input message="tns:GetLastTradePriceInput"/>
           <output message="tns:GetLastTradePriceOutput"/>
        </operation>
    </portType>

    <binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
        <soapbind:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="GetLastTradePrice">
           <soapbind:operation soapAction="http://example.com/GetLastTradePrice"/>
           <input>
               <soapbind:body use="literal"/>
           </input>
           <output>
               <soapbind:body use="literal"/>
           </output>
        </operation>
    </binding>

    <service name="StockQuoteService">
        <documentation>My first service</documentation>
        <port name="StockQuotePort" binding="tns:StockQuoteBinding">
           <soapbind:address location="http://example.com/stockquote"/>
        </port>
    </service>
</definitions>

The XML Declaration

The XML Declaration always appears at first line to declare that the document is XML. Although it is not required, it helps the XML parser to determine whether to parse the WSDL file at all or signal an error. An example of XML declaration:

<?xml version="1.0" encoding="UTF-8"?>

Here are some of restrictions in WS-I Basic Profile 1.0:

5.16 XML Version Requirements

Neither WSDL 1.1 nor XML Schema 1.0 mandate a particular version of XML. For interoperability, WSDL documents and the schema they import expressed in XML must use version 1.0.

R4004

A DESCRIPTION MUST use version 1.0 of the eXtensible Markup Language W3C Recommendation.

5.1.7 WSDL and the Unicode BOM

XML 1.0 allows documents that use the UTF-8 character encoding to include a BOM; therefore, description processors must be prepared to accept them.

R4002

A DESCRIPTION MAY include the Unicode Byte Order Mark (BOM).

5.1.8 Acceptable WSDL Character Encodings

The Profile consistently requires either UTF-8 or UTF-16 encoding for both SOAP and WSDL (see also R1012)

R4003

A DESCRIPTION MUST use either UTF-8 or UTF-16 encoding.

The <definitions> Element

A WSDL definition is an XML document with a root element called definitions from the http://schemas.xmlsoap.org/wsdl/ namespace. The entire WSDL schema is available at http://schemas.xmlsoap.org/wsdl/ for your reference. The definitions element may contain several other elements including types, message, portType, binding, and service, all of which come from the http://schemas.xmlsoap.org/wsdl/ namespace. Declaring the WSDL namespace as the default namespace avoids having to qualify every WSDL element explicitly, with a prefix. The following XML document is a sample of WSDL document,

<definitions name="StockQuote"
    targetNamespace="http://example.com/stockquote.wsdl"
    xmlns:tns="http://example.com/stockquote.wsdl"
    xmlns:xsd1="http://example.com/stockquote.xsd"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns="http://schemas.xmlsoap.org/wsdl/">
          …………
   
    <message name="GetLastTradePriceInput">
        <part name="body" element="xsd1:TradePriceRequest"/>
    </message>
    <message name="GetLastTradePriceOutput">
        <part name="body" element="xsd1:TradePrice"/>
    </message>

   
    <portType name="StockQuotePortType">
        <operation name="GetLastTradePrice">
           <input message="tns:GetLastTradePriceInput"/>
           <output message="tns:GetLastTradePriceOutput"/>
        </operation>
    </portType>
          …………
</definitions>

The definitions element sets the name of the WSDL document and typically declares the namespaces used in the document. In the above sample, the StockQuote is a name for the WSDL definition as a whole. This name need not correspond to the name of any particular service in the WSDL definition.

Notice that you must specify a target namespace for your WSDL definition which identifies the namespace of elements defined in the WSDL document, just like you would for an XML Schema definition. Anything that you name in the WSDL definition (like a message, portType, binding, etc.) automatically becomes part of the WSDL definition's target namespace defined by the targetNamespace attribute. In the above sample, the targetNamespace attribute states that the elements within the WSDL definitions declare names in the namespace "http://example.com/stockquote.wsdl".

The message, portType, and binding elements must be named (by their name attributes) making it possible to refer to them from elsewhere in the WSDL definition. These "named" labels automatically take on the namespace specified by the targetNamespace attribute. You must use the fully qualify name (QName) to refer to them in you WSDL document.

Here are some of restrictions in WS-I Basic Profile 1.0.

5.1.1 WSDL Schema Definitions

The normative schemas for WSDL appearing in Appendix 4 of the WSDL 1.1 specification have inconsistencies with the normative text of the specification. The Profile references new schema documents that have incorporated fixes for known errors.

R2028	A DESCRIPTION using the WSDL namespace (prefixed "wsdl" in this Profile) MUST be valid according to the XML Schema found at "http://schemas.xmlsoap.org/wsdl/2003-02-11.xsd".
R2029	A DESCRIPTION using the WSDL SOAP binding namespace (prefixed "soapbind" in this Profile) MUST be valid according to the XML Schema found at "http://schemas.xmlsoap.org/wsdl/soap/2003-02-11.xsd".

Although the Profile requires WSDL descriptions to be Schema valid, it does not require consumers to validate WSDL documents. It is the responsibility of a WSDL document's author to assure that it is Schema valid.

WSDL <import> Element

The use of the import element allows the separation of the different elements of a service definition into independent documents, which can then be imported as needed. This technique helps writing clearer service definitions, by separating the definitions according to their level of abstraction. It also maximizes the ability to reuse service definitions of all kinds. As a result, WSDL documents structured in this way are easier to use and maintain. The following example shows how to use this authoring style to define the service presented in previous section.

Here we separate the definitions in three documents: data type definitions, abstract definitions, and specific service bindings. The use of this mechanism is of course not limited to the definitions explicitly presented in the example, which uses only language elements defined in this specification. Other types of definitions based on additional language extensions can be encoded and reused in a similar fashion.

For example:

http://example.com/stockquote/stockquote.xsd

<?xml version="1.0"?>
<schema targetNamespace="http://example.com/stockquote/schemas"
        xmlns="http://www.w3.org/2000/10/XMLSchema">
       <element name="TradePriceRequest">
          <complexType>
             <all>
                 <element name="tickerSymbol" type="string"/>
             </all>
          </complexType>
       </element>
       <element name="TradePrice">
          <complexType>
             <all>
                 <element name="price" type="float"/>
             </all>
          </complexType>
       </element>
</schema>

http://example.com/stockquote/stockquote.wsdl

<?xml version="1.0"?>
<definitions name="StockQuote"
     targetNamespace="http://example.com/stockquote/definitions"
     xmlns:tns="http://example.com/stockquote/definitions"
     xmlns:xsd1="http://example.com/stockquote/schemas"
     xmlns:xsd="http://www.w3.org/2000/10/XMLSchema"
     xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
     xmlns="http://schemas.xmlsoap.org/wsdl/">

    <types>
       <xsd:schema targetNamespace="http://example.com/stockquote/definitions">
       <!-- Import the stockquote XML schema document -- >
       <xsd:import namespace="http://example.com/stockquote/schemas"
           schemaLocation="http://example.com/stockquote/stockquote.xsd"/>
       </xsd:schema>
    </types>

    <message name="GetLastTradePriceInput">
        <part name="body" element="xsd1:TradePriceRequest"/>
    </message>

    <message name="GetLastTradePriceOutput">
        <part name="body" element="xsd1:TradePrice"/>
    </message>

    <portType name="StockQuotePortType">
        <operation name="GetLastTradePrice">
           <input message="tns:GetLastTradePriceInput"/>
           <output message="tns:GetLastTradePriceOutput"/>
        </operation>
    </portType>
</definitions>

http://example.com/stockquote/stockquoteservice.wsdl

<?xml version="1.0"?>
<definitions name="StockQuote"
    targetNamespace="http://example.com/stockquote/service"
    xmlns:tns="http://example.com/stockquote/service"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:defs="http://example.com/stockquote/definitions"
    xmlns="http://schemas.xmlsoap.org/wsdl/">

    <import namespace="http://example.com/stockquote/definitions"
           location="http://example.com/stockquote/stockquote.wsdl"/>

    <binding name="StockQuoteSoapBinding" type="defs:StockQuotePortType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <operation name="GetLastTradePrice">
           <soap:operation soapAction="http://example.com/GetLastTradePrice"/>
           <input>
               <soap:body use="literal"/>
           </input>
           <output>
               <soap:body use="literal"/>
           </output>
        </operation>
    </binding>

    <service name="StockQuoteService">
        <documentation>My first service</documentation>
        <port name="StockQuotePort" binding="tns:StockQuoteBinding">
           <soap:address location="http://example.com/stockquote"/>
        </port>
    </service>
</definitions>

The WS-I Basic Profile 1.0 provides a few guides to use wsdl:import to import WSDL files and use xs:import to import XML schemas.

5.1.2 WSDL and Schema Import

The Profile clarifies use of the import mechanisms to keep them consistent and confined to their respective domains. Imported schema documents are also constrained by XML version and encoding requirements consistent to those of the importing WSDL documents.

	R2001	A DESCRIPTION MUST only use the WSDL "import" statement to import another WSDL description.
	R2002	To import XML Schema Definitions, a DESCRIPTION MUST use the XML Schema "import" statement.
	R2003	A DESCRIPTION MUST use the XML Schema "import" statement only within the xsd:schema element of the types section.
	R2004	A DESCRIPTION MUST NOT use the XML Schema "import" statement to import a Schema from any document whose root element is not "schema" from the namespace "http://www.w3.org/2001/XMLSchema".
	R2009	An XML Schema directly or indirectly imported by a DESCRIPTION MAY include the Unicode Byte Order Mark (BOM).
	R2010	An XML Schema directly or indirectly imported by a DESCRIPTION MUST use either UTF-8 or UTF-16 encoding.
	R2011	An XML Schema directly or indirectly imported by a DESCRIPTION MUST use version 1.0 of the eXtensible Markup Language W3C Recommendation.

5.1.3 WSDL Import location Attribute Syntax

WSDL 1.1 is not clear about whether the location attribute of the wsdl:import statement is required, or what its content is required to be.

R2007

A DESCRIPTION MUST specify a non-empty location attribute on the wsdl:import element.

Although the wsdl:import statement is modeled after the xsd:import statement, the location attribute is required by wsdl:import while the corresponding attribute on xsd:import, schemaLocation is optional. Consistent with location being required, its content is not intended to be empty.

5.1.4 WSDL Import location Attribute Semantics

WSDL 1.1 is unclear about whether WSDL processors must actually retrieve and process the WSDL document from the URI specified in the location attribute on the wsdl:import statements it encounters.

R2008

In a DESCRIPTION the value of the location attribute of a wsdl:import element SHOULD be treated as a hint.

This means that WSDL processor may, but need not, retrieve a WSDL description from the URI specified in the location attribute on a wsdl:import element because a WSDL processor may have other ways of locating a WSDL description for a given namespace. For example, it may already have a cached or built-in representation, or it may retrieve a representation from a metadata repository or UDDI server.

5.1.5 Placement of WSDL import Elements

Example 3 in WSDL 1.1 Section 3.1 causes confusion regarding the placement of wsdl:import.

	R2022	When they appear in a DESCRIPTION, wsdl:import elements MUST precede all other elements from the WSDL namespace except wsdl:documentation.
	R2023	When they appear in a DESCRIPTION, wsdl:types elements MUST precede all other elements from the WSDL namespace except wsdl:documentation and wsdl:import.

WSDL import elemets are defined as direct children of WSDL definitions element, when appear in a WSDL document, they MUST precede all other elements from the WSDL namespace except WSDL i>documentation element.

The following example relate to "R2022" and "R2023":

INCORRECT:
<definitions name="StockQuote"
                ...
   xmlns="http://schemas.xmlsoap.org/wsdl/">

   <import namespace="http://example.com/stockquote/definitions"
         location="http://example.com/stockquote/stockquote.wsdl"/>

   <message name="GetLastTradePriceInput">
       <part name="body" type="tns:TradePriceRequest"/>
   </message>
               ...
   <service name="StockQuoteService">
      <port name="StockQuotePort" binding="tns:StockQuoteSoap">
           ....
      </port>
   </service>

   <types>
      <schema targetNamespace="http://example.com/stockquote/schemas"
               xmlns="http://www.w3.org/2001/XMLSchema">
           .......
      </schema>
   </types>
</definitions>

CORRECT:
   <definitions name="StockQuote"
      targetNamespace="http://example.com/stockquote/definitions">

     <import namespace="http://example.com/stockquote/base"
       location="http://example.com/stockquote/stockquote.wsdl"/>

      <message name="GetLastTradePriceInput">
         <part name="body" element="..."/>
      </message>
                  ...
   </definitions>

CORRECT:
<definitions name="StockQuote"
                ...
   xmlns="http://schemas.xmlsoap.org/wsdl/">

<types>
     <schema targetNamespace="http://example.com/stockquote/schemas"
          xmlns="http://www.w3.org/2001/XMLSchema">
           .......
     </schema>
   </types>

   <message name="GetLastTradePriceInput">
        <part name="body" element="tns:TradePriceRequest"/>
   </message>
               ...
   <service name="StockQuoteService">
      <port name="StockQuotePort" binding="tns:StockQuoteSoap">
           ....
      </port>
   </service>
</definitions>

WSDL import element can only be used to import other WSDL files. For example:

INCORRECT:
<definitions name="StockQuote"
   targetNamespace="http://example.com/stockquote/definitions"
   xmlns:xsd1="http://example.com/stockquote/schemas""
           ...
   xmlns="http://schemas.xmlsoap.org/wsdl/">

   <import namespace="http://example.com/stockquote/schemas"
         location="http://example.com/stockquote/stockquote.xsd"/>

   <message name="GetLastTradePriceInput">
        <part name="body" element="xsd1:TradePriceRequest"/>
    </message>
               ...
</definitions>

CORRECT:
<definitions name="StockQuote"
      targetNamespace="http://example.com/stockquote/definitions">
      <import namespace="http://example.com/stockquote/definitions"
           location="http://example.com/stockquote/stockquote.wsdl"/>
      <message name="GetLastTradePriceInput">
         <part name="body" element="..."/>
      </message>
                  ...
   </definitions>

CORRECT:
<definitions name="StockQuote"
   targetNamespace="http://example.com/stockquote/"
   xmlns:xsd1="http://example.com/stockquote/schemas"
           ...
   xmlns="http://schemas.xmlsoap.org/wsdl/">

   <import namespace="http://example.com/stockquote/definitions"
        location="http://example.com/stockquote/stockquote.wsdl"/>

   <message name="GetLastTradePriceInput">
      <part name="body" element="xsd1:TradePriceRequest"/>
   </message>
               ...
</definitions>

The WSDL import element MUST declare two attributes: namespace and location. The value of the namespace attribute must match the targetNamespace declared by the WSDL document being imported. The location attribute MUST point to an actual WSDL document; it CANNOT BE empty or null, but the location should only be used as a hint and processors are free to use other means to locate the imported WSDL file.

The imported wsdl can be either in the same or different namespace as the importing wsdl file. however, namespace coersion is disallowed. In other words, the targetNamespace attribute on the WSDL definitions element of a description that is being imported MUST have the same value as the namespace attribute on the WSDL import element in the importing description. Here is the restrictions in the WS-I Basic Profile 1.0.

5.1.9 Namespace Coercion

Namespace coercion on wsdl:import is disallowed by the Profile.

R2005

The targetNamespace attribute on the wsdl:definitions element of a description that is being imported MUST have same the value as the namespace attribute on the wsdl:import element in the importing DESCRIPTION.

The <documentation> Element

Any WSDL element can contain the documentation element.

5.1.10 WSDL documentation Element (WS-I Basic Profile 1.0)

The WSDL 1.1 schema and the WSDL 1.1 specification are inconsistent with respect to where wsdl:documentation elements may be placed.

R2020
The wsdl:documentation element MAY occur as a child of the wsdl:import element in a DESCRIPTION.

R2021
The wsdl:documentation element MAY occur as a child of the wsdl:part element in a DESCRIPTION.

R2024
The wsdl:documentation element MAY occur as a first child of the wsdl:definitions element in a DESCRIPTION.

The <types> Element

The <types> element comprises the Types section. This section may be omitted if there are no data types that need to be declared.

Officially, WSDL 1.1 allows the use of any type definition language, although it strongly encourages the use of the W3C XML Schema build-in types as its intrinsic type system. The WS-I enforces this by mandating the use of XML Schema in the WS-I Basic Profile 1.0.

The WSDL types element is a container for defining any data types (complex data types and custom simple types) that are not covered by the XML Schema build-in types. The type definitions you place here are referenced from higher-level message definitions in order to define the structural details of the message.

5.7 Use of XML Schema

The following specifications (or sections thereof) are referred to in this section of the Profile;

·XML Schema Part 1: Structures

·XML Schema Part 2: Datatypes

WSDL 1.1 uses XML Schema as one of its type systems. The Profile mandates the use of XML Schema as the type system for WSDL descriptions of Web Services.

	R2800	A DESCRIPTION MAY use any construct from XML Schema 1.0.
	R2801	A DESCRIPTION MUST use XML Schema 1.0 Recommendation as the basis of user defined datatypes and structures.

The types element contains zero or more schema elements from the http://www.w3.org/2001/XMLSchema namespace. The basic structure of the types element (with namespaces omitted) is as follows (* means zero or more):

You can use any XML Schema construct within the schema element, such as simple type definitions, complex type definitions, and element definitions.

The targetNamespace attribute of the XML schema must be a valid non-nul value, otherwise the types and element will not belong to a valid namespace. In addition, the XML schema defined in the types element must belong to a namespace specified by the WSDL document (usually in the definitions element) or to a namespace of an imported WSDL document. In other words, the WSDL document must be aware of any an all namespaces used in the document.

Here is some of restrictions from WS-I Basic Profile 1.0.

5.2 Types

The following specifications (or sections thereof) are referred to in this section of the Profile;

WSDL 1.1, Section 2.2

The wsdl:types element of WSDL 1.1 encloses data type definitions that are relevant to the Web service described. The Profile places the following constraints pertinent to those portions of the content of the >wsdl:types element that are referred to by WSDL elements that make Profile conformance claims:

5.2.1 QName References

XML Schema requires each QName reference to use either the target namespace, or an imported namespace (one marked explicitly with an xsd:import element). QName references to namespaces represented only by nested imports are not allowed.

WSDL 1.1 is unclear as to which schema target namespaces are suitable for QName references from a WSDL element. The Profile allows QName references from WSDL elements both to the target namespace defined by the xsd:schema element, and to imported namespaces. Similar to XML Schema, namespaces not referenced directly within the WSDL file (through the targetNamespace attribute on xsd:schema, or through the namespace attribute on xsd:import) are available for use in QName reference. QName references to namespaces that are only defined through a nested import are not allowed.

	R2101	A DESCRIPTION MUST NOT use QName references to elements in namespaces that have been neither imported, nor defined in the referring WSDL document.
	R2102	A QName reference to a Schema component in a DESCRIPTION MUST use the namespace defined in the `targetNamespace` attribute on the `xsd:schema` element, or to a namespace defined in the `namespace` attribute on an `xsd:import` element within the `xsd:schema` element.

5.2.2 Schema targetNamespace Syntax

Requiring a targetNamespace on all xsd:schema elements that are children of wsdl:types is a good practice, places a minimal burden on authors of WSDL documents, and avoids the cases that are not as clearly defined as they might be.

R2105

All xsd:schema elements contained in a wsdl:types element of a DESCRIPTION MUST have a targetNamespace attribute with a valid and non-null value, UNLESS the xsd:schema element has xsd:import and/or xsd:annotation as its only child element(s).

5.2.3 soapenc:Array

The recommendations in WSDL 1.1 Section 2.2 for declaration of array types have been interpreted in various ways, leading to interoperability problems. Further, there are other clearer ways to declare arrays.

	R2110	In a DESCRIPTION, array declarations MUST NOT extend or restrict the `soapenc:Array` type.
	R2111	In a DESCRIPTION, array declarations MUST NOT use `wsdl:arrayType` attribute in the type declaration.
	R2112	In a DESCRIPTION, array declaration wrapper elements SHOULD NOT be named using the convention ArrayOfXXX.
	R2113	A MESSAGE containing serialized arrays MUST NOT include the `soapenc:arrayType` attribute.

For example,

INCORRECT:
Given the WSDL Description:
<xsd:element name="MyArray2" type="tns:MyArray2Type"/>
<xsd:complexType name="MyArray2Type"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" >
<xsd:complexContent>
     <xsd:restriction base="soapenc:Array">
       <xsd:sequence>
          <xsd:element name="x" type="xsd:string"
           minOccurs="0" maxOccurs="unbounded"/>
       </xsd:sequence>
       <xsd:attribute ref="soapenc:arrayType"
        wsdl:arrayType="tns:MyArray2Type[]"/>
   </xsd:restriction>
</xsd:complexContent>
</xsd:complexType>

The SOAP message would serialize as (omitting namespace declarations for clarity):
<MyArray2 soapenc:arrayType="tns:MyArray2Type[]" >
<x>abcd</x>
<x>efgh</x>
</MyArray2>

CORRECT:
Given the WSDL Description:
<xsd:element name="MyArray1" type="tns:MyArray1Type"/>
<xsd:complexType name="MyArray1Type">
<xsd:sequence>
   <xsd:element name="x" type="xsd:string"
    minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>

The SOAP message would serialize as (omitting namespace declarations for clarity):
<MyArray1>
<x>abcd</x>
<x>efgh</x>
</MyArray1>

5.2.4 WSDL and Schema Definition Target Namespaces

The names defined by schemas and the names assigned to WSDL definitions are in separate symbol spaces.

R2114

The target namespace for WSDL definitions and the target namespace for schema definitions in a DESCRIPTION MAY be the same.

The <message> Element

The message element describes the payload of a message used by a Web service. A message element can describe the payloads of outgoing or incoming messages. In addition, the message element can describe the contents of SOAP header blocks and fault detail elements. WSDL messages don’t rely on any specific network protocol. The messages can ultimately be sent using SOAP, HTTP GET, SMTP, etc.

The <message> elements defines the data elements of an operation. Each <message> can consist of one or more <part> elements. If we consider operations as functions in a traditional programming language, then a <message> element defines the parameters to that function. Each <part> child element in the <message> element corresponds to a parameter.Input parameters are defined in a single <message> element, separate from output parameters, which are in their own <message> element. Parameters that are both input and output have their corresponding <part> elements in both input and output <message> elements.

Each <part> element has a name and type attribute, just as a function parameter has both a name and type.The type of a <part> element can be an XSD base type, a SOAP defined type (soapenc), a WSDL defined type (wsdl), or a Types section defined type.

The Message Element for RPC-Style Web Service

The Message Element for Document-Style Web Service

Notice from the above samples, the message part may declare either a type attribute or an element attribute, but not both. Which to use depends on the kind of messaging you are doing. If you are using RPC-Style messaging, the part elements must use the type attribute; otherwise use element attribute for the document-style messing.

5.4.5 Exclusivity of type and element Attributes

WSDL 1.1 does not clearly state that both type and element attribute cannot be specified to define a wsdl:part in a wsdl:message.

R2306

A wsdl:message in a DESCRIPTION MUST NOT specify both type and element attributes on the same wsdl:part.

The <portTyp> Element and <operation> Element

A PortType defines an abstract interface of a Web service. A portType element composes messages into operations. A portType may contain any number of operation elements. Operation elements within a PortType define the syntax for calling all methods in the PortType. Each operation element declares the name of the method, the parameters (using <message> elements), and types of each (<part> elements declared in every <message>).

There can be several <portType> elements within a WSDL document. Each <portType> element groups together a number of related operations that describe the abstratc interface to a different Web service.

An operation describes a pattern of interaction between a client and a server. A portType may contain any number of operation elements. In an <operation> element, there can be at most one <input> element (input message), at most one <output> element (output message), and any number of <fault> element (fault message). Each of these three elements has a name and a message attribute An input message is a message from a client to the server. An output message is a message from the server to the client. A fault message is a message that is used to report an error. The order of the input and output elements is the order in which those messages occur within the operation. The sample below shows the basic outline of a portType element:

The PortName sets the name of the port. The OperationName sets the name of the operation. The InputMessageRef, OutputMessageRef and FaultMessageRef each refer to a message defined elsewhere in the WSDL file. The message attribute must be specified as an XML Schema QName. This means that the value of the attribute must be namespace-qualified.

What is the purpose of the name attribute in the <input>, <output>, and <fault> elements? It can be used to distinguish between two operations that have the same name (overloading). In WSDL, two operations may have the same name, provide their inupt or output message differ. Unfortunately, this feature has caused enough interoperability problems that the WS-I Basic Profile prohibits operation overloading. Every operation defined by a particular portType element MUST have a unique name.

5.4.3 Distinctive Operations

Operation name overloading in a wsdl:portType is disallowed by the Profile.

R2304

A wsdl:portType in a DESCRIPTION MUST have operations with distinct values for their name attributes.

Note that this requirement applies only to the wsdl:operation(s) within a given wsdl:portType. A wsdl:portType may have wsdl:operation(s) with names that are the same as those found in other wsdl:portType(s).

In WSDL, when RPC-style messaging is used, it is assumed that the client uses procedure call semantics. For example, JAX-RPC uses Java RMI interfaces with the method calls to model RPC-Style SOAP-based Web service. In many cases the parameters of the input and output messages must be transferred in a specific order, the same order as the parameters of the procedure call. To enforce proper ordering of input or output message parameters, the operation element may declare named parameterOrder attribute. When the attribute is used, it must include all the input parts and only the output parts that are not the return type.

part name order reflects order of parameters in the RPC signature
return value part is not present
in/out parameters appear in both input and output, otherwise they are input or output parameters resp.

In WS-I Basic Profile 1.0, the single interpretation of the parameterOrder attribute defines as “the order of parameters transmitted from sender to receiver must follow the order of part declarations made in input and output message definitions. The purpose of the parameterOrder attribute is to indicate which part, if any, is the return type. Any part that is omitted from the list provided by the parameterOrder attribute is assumed to be the return type of the operation. A procedure call can have only one return type, so only a single output part may be omitted from the parameterOrder attribute.

5.4.1 Ordering of part Elements

Permitting the use of parameterOrder helps code generators in mapping between method signatures and messages on the wire.

	R2301	The order of the elements in the soap:body of a MESSAGE MUST be the same as that of the wsdl:parts in the wsdl:message that describes it.
	R2302	A DESCRIPTION MAY use the parameterOrder attribute of an wsdl:operation element to indicate the return value and method signatures as a hint to code generators.

5.4.4 parameterOrder Attribute Construction

WSDL 1.1 does not clearly state how the parameterOrder attribute of the wsdl:portType should be constructed.

R2305

A wsdl:portType in a DESCRIPTION MUST be constructed so that the parameterOrder attribute, if present, omits at most ONE wsdl:part from the output message.

If a wsdl:part from the output message is omitted from the list of wsdl:parts that is the value of the parameterOrder attribute, the single omitted wsdl:part is the return value. There are no restrictions on the type of the return value. If no part is omitted, there is no return value.

The <binding> and <operation> Elements

The Binding section is where the protocols such as SOAP and HTTP, messaging styles (RPC or document), and encoding styles (Literal or SOAP encoding) on the wire are fully specified. Whereas the Types, Messages, and PortType sections deal with data content in the abstract, the Binding section is where the physical details of data transmission is dealt with. The Binding section concretizes the abstractions made in the first three sections.

The binding element provides specific details on how a portType operation will actually be transmitted over the wire. The binding element and operation elements are used in combination with protocol-specific elements. The binding elements identify which portType and operation elements are being bound, while the protocol-specific elements declare the protocol and encoding style to be associated with the portTyp. Each type of protocol (SOAP, MIME, and HTTP) has its own set of protocol-specific elements and its own namespace.

The binding element uses its type attribute to references a particular portType. An operation element within a binding specifies binding information for the operation with the same name within the binding's portType. A binding MUST specify exactly one protocol and a binding MUST NOT specify address information.

The above example shows that the StockQuotePortType portType is bound to the SOAP 1.1 protocol using SOAP-specific protocol element.

In WS-I Basic Profile, Web services are required to use SOAP 1.1 binding:

5.5 Bindings

The following specifications (or sections thereof) are referred to in this section of the Profile;

WSDL 1.1, Section 2.5

In WSDL 1.1, the wsdl:binding element supplies the concrete protocol and data format specifications for the operations and messages defined by a particular wsdl:portType. The Profile places the following constraints on conformant binding specifications:

5.5.1 Use of SOAP Binding

The Profile limits the choice of bindings to the well defined and most commonly used SOAP binding. MIME and HTTP GET/POST bindings are not permitted by the Profile.

R2401

A wsdl:binding element in a DESCRIPTION MUST use WSDL SOAP Binding as defined in WSDL 1.1 Section 3

Note that this places a requirement on the construction of conformant wsdl:binding elements. It does not place a requirement on descriptions as a whole; in particular, it does not preclude WSDL documents from containing non-conformant wsdl:binding elements.

There may be any number of bindings for a given portType. The name attribute provides a unique name amongst bindings.

5.6.6 Multiple Bindings for portType Elements

The Profile explicitly permits multiple bindings for the same portType.

R2709

A wsdl:portType in a DESCRIPTION MAY have zero or more wsdl:bindings that refer to it, defined in the same or other WSDL documents

5.6.12 Consistency of portType and binding Elements

The WSDL description must be consistent at both wsdl:portType and wsdl:binding levels.

R2718

A wsdl:binding in a DESCRIPTION MUST have the same set of wsdl:operations as the wsdl:portType to which it refers

The SOAP Binding Elements

Several SOAP 1.1 specific binding elements are used in combination with the WSDL binding elements: soapbind:binding, soapbind:operation, soapbind:body, soapbind:fault, soapbind:header, and soapbind:headerfault. The soapbind:binding and soapbind:body elements are required, but the others are optional.

The SOAP Binding Element <binding>

The soapbind:binding element indicates that the binding will be made available via SOAP.

The style attribute indicates the overall style of the SOAP message format. The style attribute must be declared and only declared as either “rpc” or “document”. A style value of rpc specifies an RPC format. This means that the body of the SOAP request will include a wrapper XML element indicating the function name. Function parameters are then embedded inside the wrapper element. Likewise, the body of the SOAP response will include a wrapper XML element that mirrors the function request. Return values are then embedded inside the response wrapper element.

A style value of document specifies an XML document call format. This means that the request and response messages will consist simply of XML documents. The document style is flatter than the rpc style and does not require the use of wrapper elements.

The transport attribute indicates the transport of the SOAP messages and must be declared with an explicit value (there is no default). The value http://schemas.xmlsoap.org/soap/http indicates the SOAP HTTP transport, whereas http://schemas.xmlsoap.org/soap/smtp indicates the SOAP SMTP transport. According to BP, the HTTP is the only transport protocol allowed by Web services, the transport attribute must be declared to be HTTP, which means its value must be “http://schemas.xmlsoap.org/soap/http”.

5.6.1 Specifying the transport Attribute

There is an inconsistency between the WSDL 1.1 specification and the WSDL 1.1 schema regarding the transport attribute. The WSDL 1.1 specification requires it; however, the schema shows it to be optional.

R2701

The wsdl:binding element in a DESCRIPTION MUST be constructed so that its soapbind:binding child element specifies the transport attribute

5.6.2 HTTP Transport

The profile limits the underlying transport protocol to HTTP.

R2702

A wsdl:binding element in a DESCRIPTION MUST specify the HTTP transport protocol with SOAP binding. Specifically, the transport attribute of its soapbind:binding child MUST have the value "http://schemas.xmlsoap.org/soap/http"

Note that this requirement does not prohibit the use of HTTPS; See R5000.

The SOAP Binding Element <operation>

The soapbind:operation element indicates the binding of a specific operation to a specific SOAP implementation. It specifies the messaging style (RPC or document) for a specific operation and the value of the SOAPAction header field. The soapAction attribute specifies that the SOAPAction HTTP header be used for identifying the service.

In WSDL 1.1 the style attribute is optional. It can be used to override the default messaging style declared by the soapbind:binding element – a capability that has been a source of interoperability problems. Accordingly, the WS-I Basic Profile requires that style attributes declared by soapbind:operation elements have the same value as the style attribute of their soapbind:binding element.

5.6.3 Consistency of style Attribute

The style, "document" or "rpc", of an interaction is specified at the wsdl:operation level, permitting wsdl:bindings whose wsdl:operations have different styles. This has led to interoperability problems.

R2705

A wsdl:binding in a DESCRIPTION MUST use either be a rpc-literal binding or a document-literal binding

The soapAction attribute dictates the value that must be placed in the SOAPAction header field of the HTTP request message. You are not required o declare the WSDL soapAction attribute; it can be omitted. You can also declare the soapAction attribute’s value to be empty (indicated by two quotes “”), which is the same as omitting it. If this attribute is omitted or empty, then the SOAPAction HTTP header field must be present and must contain an empty string. The value of SOAPAction HTTP header field must exactly match the value of the corresponding soapAction attribute in the soapbind:operation element.

The SOAP Binding Element <body>

The soapbind:body element enables you to specify the details of the input and output messages. The soapbind:body element has four kinds of attributes: use, namespace, part, and encodingStyle.

The use attribute is required to be “literal” – and that value is assumed if the soapbind:body element fails to declare the use element.
The encodingStyle attribute is never used at all, because WS-I conformant Web services are based on the W3C XML schema, which is implied by the use=”literal” declaration. Other encoding styles, like SOAP 1.1 Encoding, are not used.
The part attribute specifies which part elements in the message definition are being used. The part attribute is necessary only if you are using a subset of the part elements declared by a message.
In “rpc”-style message, the namespace attribute MUST be specified with a valid URI. The URI can be the same as the targetNamepspace of the WSDL document. Please see the following example.
In “document”-style message, you MUST NOT specify the namespace attribute in the soapbind:body element. Please see the previous example.

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="HelloService"
   targetNamespace="http://www.ecerami.com/wsdl/HelloService.wsdl"
   xmlns="http://schemas.xmlsoap.org/wsdl/"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:tns="http://www.ecerami.com/wsdl/HelloService.wsdl"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">

   <message name="SayHelloRequest">
      <part name="firstName" type="xsd:string"/>
   </message>
   <message name="SayHelloResponse">
      <part name="greeting" type="xsd:string"/>
   </message>

   <portType name="Hello_PortType">
      <operation name="sayHello">
         <input message="tns:SayHelloRequest"/>
         <output message="tns:SayHelloResponse"/>
      </operation>
   </portType>

   <binding name="Hello_Binding" type="tns:Hello_PortType">
      <soap:binding style="rpc"
         transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="sayHello">
         <soap:operation style="rpc" soapAction="sayHello"/>
         <input>
            <soap:body use="literal"
               namespace="http://www.ecerami.com/wsdl/HelloService.wsdl"/>
         </input>
         <output>
            <soap:body use="literal"
               namespace="http://www.ecerami.com/wsdl/HelloService.wsdl"/>
         </output>
      </operation>
   </binding>

   <service name="Hello_Service">
      <documentation>WSDL File for HelloService</documentation>
      <port binding="tns:Hello_Binding" name="Hello_Port">
         <soap:address
            location="http://localhost:8080/soap/servlet/rpcrouter"/>
      </port>
   </service>
</definitions>

The <service> and <port> Elements

A service is a set of <port> elements. Each <port> element associates a location with a <binding> in a one-to-one fashion. In other words, each of them represents a different Web service. If there is more than one <port> element associated with the same <binding>, then the additional URL locations can be used as alternates such as load balancing or failover.

The basic structure of the service element is as follows:

You must give each port a name and assign it a binding. Then, within the port element, you use an extensibility element to define the address details specific to the binding.

There can be more than one <service> element in a WSDL document. There are many uses for allowing multiple <service> elements. One of them is to group together ports according to URL destination. Thus, I can redirect all my stock quote requests simply by using another <service>, and my client program would still work because in this type of service grouping the protocol is invariant with respect to different services. Another use of multiple <service> elements is to classify the ports according to the underlying protocol. For example, I can put all HTTP ports in one <service>, and all SMTP ports in another. My client can then search for the <service> that matches the protocol that it can deal with.

<definitions name="StockQuote"
     targetNamespace="http://example.com/stockquote/service"
     xmlns:tns="http://example.com/stockquote/service"
     xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
     xmlns:defs="http://example.com/stockquote/definitions"
     xmlns="http://schemas.xmlsoap.org/wsdl/">
        ……
    <service name="StockQuoteService">
      <documentation>My first service</documentation>
        <port name="StockQuotePort" binding="tns:StockQuoteBinding">
           <soap:address location="http://example.com/stockquote"/>
        </port>
    </service>
</definitions>

Within one WSDL document, the <service> "name" attribute distinguishes one service from another. Because there can be several ports in a service, the ports also have a "name" attribute.

The soapbind:address element is pretty straightforward; it simply assigns an internet address to a SOAP binding via its location attribute (its only attribute). Although WSDL allows any type of address (HTTP, FTP, SMTP, and so on), the Basic Profile allows only those URLs that use the HTTP or HTTPs schema.

Two or more port elements within the same WSDL document must not specify exactly the same URL value for the location attribute of the soapbind:address.

WSDL Document Elements

The XML Declaration

The <definitions> Element

WSDL <import> Element

The <documentation> Element

The <types> Element

The <message> Element

The Message Element for RPC-Style Web Service

The Message Element for Document-Style Web Service

The <portTyp> Element and <operation> Element

The <binding> and <operation> Elements

The SOAP Binding Elements

The SOAP Binding Element <binding>

The SOAP Binding Element <operation>

The SOAP Binding Element <body>

The <service> and <port> Elements