Common WSDL Errors

James Pasley, Chief Architect for CapeStudio @ Cape Clear
July 16th, 2001

Introduction

As the number of developers creating WSDL increases, so too does the number of errors commonly found in WSDL files. Creating a valid WSDL file requires an understanding of the following World Wide Web Consortium (W3C) recommendations: WSDL, SOAP and XML Schema. Because of the steep learning curve involved in understanding these recommendations, a number of developers are adopting a "copy the existing examples" approach. This results in early errors being repeated from one implementation to another. Before long, these errors will become the de facto standard.

Despite the limited number of published WSDL files published so far and the lack of complicated constructs beyond arrays of basic types, a number of common errors have emerged. This has resulted in some companies publishing lists of the varieties of array definitions that only they support. Continued support for these invalid definitions will only serve to propagate the errors, increasing the complexity of implementing Web services and inevitably delaying their widespread adoption.

This paper details a number of these common errors, examples of which can be found on the XMethods site. Each item includes a description of the error, a recommended strategy to avoid or amend the error, and references to the relevant sections of the following W3C specifications:

• Simple Object Access Protocol (SOAP) 1.1
• Web Services Description Language (WSDL) 1.1
• XML Schema
• Namespaces in XML

Provide a SOAP Action

Description

Not providing a SOAPAction attribute or providing an empty one, when the HTTP protocol for SOAP is used.

Recommendation

Always provide a SOAPAction attribute.

Details

Both the WSDL and SOAP recommendations state that a SOAPAction attribute must be used.

Relevant sections from the recommendations

SOAP: http://www.w3.org/TR/SOAP/#_Toc478383528

An HTTP client must use this header field when issuing a SOAP HTTP Request.

WSDL: http://www.w3.org/TR/wsdl#_soap:operation

For the HTTP protocol binding of SOAP, this value is required.

[ Back To Top ]

Namespace handling

Description

Neglecting to use a namespace prefix when referring to basic types may cause the definition to be invalid. See the following example:

<part name= "return" type="string" />

Strings such as "SOAP-ENC" and "SOAP-ENV" are commonly used as  namespace prefixes. They have no inherent meaning and must be declared in each file in which they are used. They cannot be used as namespaces. This following is incorrect:

<part name= "result" type="t:ARRAY"
xmlns:t="SOAP-ENC" />

It should instead be as follows:

<part name="result" type="SOAP-ENC:ARRAY" 

xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" />

Recommendation

Follow the convention used in the WSDL recommendation, which is to set the default namespace for the root element to "http://schemas.xmlsoap.org/wsdl/" and the default namespace for the contained schema (if any) to "http://www.w3.org/2001/XMLSchema". In most cases this reduces the need for namespace prefixes.

Reasoning

There are two possible ways of referring to schema types. You can set the default namespace using the xmlns attribute (in which case the elements/attributes without a prefix will be assumed to be in this namespace), as follows:

<wsdl:definitions
 xmlns="http://www.w3.org/2001/XMLSchema"
 .....
<wsdl:part name="return" type=
 
 "string"/>< BR>

Alternately, you can declare a namespace prefix and use it explicitly, as follows:

<wsdl:definition
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 .....
<wsdl:part name="return" type=
 
 "xsd:string"/>< BR>

Either mechanism is valid. Note that the WSDL recommendation contains a number of examples where the type "string" is referenced without the prefix. In all cases this is because the default namespace has been set to "http://www.w3.org/2000/10/XMLSchema".

Relevant sections from the recommendations

Schema: http://www.w3.org/TR/xmlschema-0/#NS

[ Back To Top ]

Use the correct namespaces

Description

The namespaces defined in the WSDL recommendation are "http://schemas.xmlsoap.org/wsdl/" and "http://schemas.xmlsoap.org/wsdl/soap/". It is important to note that they end with the character "/". It is not valid to omit the final character.

Recommendation

Use the namespaces exactly as defined in the WSDL recommendation.

Reasoning

URI references which identify namespaces are considered identical when they are exactly the same character-for-character.

Relevant sections from the recommendations

Namespaces in XML: http://www.w3.org/TR/1999/REC-xml-names-19990114/#dt-identical

[ Back To Top ]

Declaring Arrays

Description

There is a great variety of invalid array declarations.

Recommendation

To avoid errors, copy the example in the SOAP recommendations. You should, however, note that WSDL adds a wsdl:arrayType attribute and that the example shown in the WSDL recommendation appears to be invalid.

Detail

The SOAP recommendation contains the following example:

<simpleType
name="phoneNumber" base="string"/>



<element name="ArrayOfPhoneNumbers">

  <complexType base="SOAP-ENC:Array">

    <element name="phoneNumber"
type="tns:phoneNumber" maxOccurs="unbounded"/>

  </complexType>

  <anyAttribute/>

</element>

Note that the default value for minOccurs is "1", so the above example actually declares an array that must always contain at least one element. If you wish to declare an array which may be empty, you must include minOccurs="0".

The WSDL recommendation adds a wsdl:arrayType attribute to the declaration. This contains the value to be placed in the SOAP:arrayType attribute when used in the SOAP message.

Adding these factors into the example given in the SOAP recommendation, gives us the following array definition:

<simpleType
name="phoneNumber" base="string"/>



<element name="ArrayOfPhoneNumbers">

  <complexType base="SOAP-ENC:Array">

    <element name="phoneNumber"
type="tns:phoneNumber" 
         minOccurs="0"
maxOccurs="unbounded"/>

  </complexType>
  attributeref="SOAP-ENC:arrayType" 
wsdl:arrayType="tns:phoneNumber[]"
/>

</element>

A Note on the WSDL example

The following example of an array definition is taken from the WSDL recommendation.

<schema
targetNamespace="http://example.com/stockquote/schema"
xmlns="http://www.w3.org/2000/10/XMLSchema">

<complexType
name="TimePeriod">
  <all>
   <element
name="startTime" type="xsd:timeInstant"/>
   <element name="endTime"
type="xsd:timeInstant"/>
  </all>
 </complexType>

<complexType
name="ArrayOfFloat">
  <complexContent>
   <restriction
base="soapenc:Array">
    <attribute
ref="soapenc:arrayType" wsdl:arrayType="xsd:float[]"/>
   </restriction>
  </complexContent>
 </complexType>
</schema>

Notice that this array definition does not declare the element that is to be contained within the array. The intention here is that is that the <xsd:any> element be inherited from the soapenc:Array definition. However, the inheritance rules for schemas state "types derived by restriction must repeat all the components of the base type definition that are to be included in the derived type."

It is worth noting that version 1.0 of the WSDL recommendation was based on the use of 1999 Schemas, which had different inheritance rules. The inheritance rules changed between the W3C Working Draft, 7 April 2000 and the W3C Candidate Recommendation 24 October 2000 versions of the schema recommendation. The authors of the WSDL recommendation may not have noticed this change when revising version 1.1 of the WSDL recommendation to use the later version of the schema recommendation.

Relevant sections from the recommendation

WSDL: http://www.w3.org/TR/wsdl#_types

WSDL 1.0: http://www.oasis-open.org/cover/wsdl20000929.html

SOAP: http://www.w3.org/TR/SOAP/#_Toc478383522

7 April 2000 Schema:  http://www.w3.org/TR/2000/WD-xmlschema-0-20000407/#DerivByRestrict

24 October 2000 Schema: http://www.w3.org/TR/2000/CR-xmlschema-0-20001024/#DerivByRestrict

[ Back To Top ]

Unbounded Arrays

Description

Use "*" and "unbounded" appropriately when specifying the value of maxOccurs.

Recommendation

When using February 2000 or earlier versions of schema recommendation use "*". When using later versions of the schema recommendation use "unbounded".

Reasoning

This is one of the items that changed between the February 2000 and later versions of the schema recommendation.

Relevant sections from the recommendations

Schema: http://www.w3.org/TR/xmlschema-1/#Particle_details

February 2000 Schema: http://www.w3.org/TR/2000/WD-xmlschema-1-20000225/#Particle_details

[ Back To Top ]

Specifying minOccurs when declaring Arrays

Description

By not specifying a value for minOccurs you may be inadvertently stating that the array must always contain at least one element.

Recommendation

Always include the minOccurs attribute when specifying arrays.

Reasoning

The default value for minOccurs is "1".

Relevant sections from the recommendations

Schema: http://www.w3.org/TR/xmlschema-1/#declare-element

[ Back To Top ]

Choose the schema version with care

Description

There have been a number of significant changes to the schema recommendation over the last couple of years. A common mistake is to persist with the older mechanism for writing schemas while claiming to provide support for the 2000 or 2001 schema. The namespace used when referencing schema definitions should indicate the version of the schema recommendation that is used.

Recommendation

Use the 2001 version of the schema standard.

Reasoning

The inheritance mechanism defined in 2001 for derived types is much easier for clients to process (see Observe the correct inheritance rules). As all clients will eventually have to support the newer versions of the schema recommendation, the sooner the old versions fall into disuse the better.

[ Back To Top ]

>Observe the correct inheritance rules

Description

The inheritance rules in schemas have changed radically over the last couple of years.

Recommendation

Use the 2001 schemas and always re-state everything that you wish to inherit from the parent type.

Reasoning

In 1999 schemas, when deriving by restriction from another type, only those elements that are to be changed need be restated in the derived type. In 2001, everything must be re-stated-elements that are not re-stated in the derived type are not inherited.

Consider the following array definition:

<complexType
name="ArrayOfInt">
    <complexContent>
        <restriction
base="soapenc:Array">
            <attribute
ref="soapenc:arrayType"
               wsdl:arrayType="xsd:int[]" />
        </restriction>
    </complexContent>

</complexType>

If observing the 1999 rules, then elements that are not re-stated are inherited unchanged. So this expands to the following:

<complexType
name="ArrayOfInt">
    <group ref="Array"
minOccurs="0" maxOccurs="1" />
    <attribute
ref="soapenc:arrayType" wsdl:arrayType="xsd:int[]" />
    <attributeGroup
ref="tns:arrayAttributes" />
    <attributeGroup
ref="tns:commonAttributes" />

</complexType>

So, as shown above, the declaration has succeeded in defining an array of xsd:any. There is no type information specified beyond that in the arrayType attribute, which is intended purely as a default value for the soapenc:arrayType attribute.

If observing the inheritance rules described in the 2001 schema recommendation, then elements that are not re-stated are not inherited. As a result, this array contains no elements at all.

Remember that when using 2001 schemas, if you want to use id and href as described in SOAP, these will also have to be repeated in the array declaration. Not restating them effectively prohibits their use-this may be a useful thing to do if you want to simplify your client or server. Be certain to ensure your WSDL is consistent with the behaviour of the service it describes.

Relevant sections from the recommendations

Schema: http://www.w3.org/TR/xmlschema-0/#DerivByRestrict

Notice that types derived by restriction must repeat all the components of the base type definition that are to be included in the derived type.

[ Back To Top ]

Defining the SOAP Header

Description

If your Web server expects specific fields in the soap header, then describe them in the WSDL.

Recommendation

Include all information necessary to communicate with the Web server in the WSDL file. Do not assume that the client has access to another source of information.

Relevant sections from the recommendations

WSDL: http://www.w3.org/TR/wsdl#_soap:header

SOAP: http://www.w3.org/TR/SOAP/#_Toc478383497

[ Back To Top ]

Specify the correct operation style

Description

If your Web server does not expect a wrapper element within the SOAP body, then set the operation style to "document".

Recommendation

Set the style attribute of the soap:binding to either "rpc" or "document" as appropriate for the Web service you are describing.

Details

If your server expects soap messages as shown as follows, then specify a style of "rpc":

<SOAP-ENV:Body>

<ns1:operationName
 
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <param1 xsi:type="xsd:string">value1</param1>
    <param2
xsi:type="xsd:string">value1</param2>

</ns1:operatonName>

</SOAP-ENV:Body>

However, if it expects soap messages as shown in figure 2, then specify a style of "document" as follows:

<SOAP-ENV:Body>
    <param1 xsi:type="xsd:string">value1</param1>
    <param2
xsi:type="xsd:string">value1</param2>

</SOAP-ENV:Body>

Relevant sections from the recommendations

WSDL: http://www.w3.org/TR/wsdl#_soap:body

If the operation style is "rpc" each part is a parameter or a return value and appears inside a wrapper element within the body (following Section 7.1 of the SOAP specification). The wrapper element is named identically to the operation name and its namespace is the value of the namespace attribute. Each message part (parameter) appears under the wrapper, represented by an accessor named identically to the corresponding parameter of the call. Parts are arranged in the same order as the parameters of the call.

If the operation style is "document" there are no additional wrappers, and the message parts appear directly under the SOAP Body element.

[ Back To Top ]

About the Author
James Pasley is a technical architect at Cape Clear Software. In recent years, he's worked on secure messaging for Siemens Nixdorf. Additionally, he was a primary developer of the CORBA conformance test suite for the OMG. In his spare time, he can be found playing and occasionally winning at obsolete console gaming systems. He frequently brings muffins and donuts to work.