WSDL contracts and code generation

Reading a WSDL top to bottom: types, messages, port types, bindings and services, and how a client is generated from it.

The parts of a WSDL

Element	Describes	Answers the question
`types`	XML Schema definitions	What do the data structures look like?
`message`	A named set of parts	What goes in and out of one operation?
`portType`	Abstract operations	What can the service do?
`binding`	Concrete protocol and style	How is it carried: SOAP over HTTP, document or rpc style?
`service` / `port`	Endpoint address	Where do I actually send the request?

<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:tns="urn:example:quotes"
             targetNamespace="urn:example:quotes">
  <types>
    <xsd:schema targetNamespace="urn:example:quotes">
      <xsd:element name="GetQuote">
        <xsd:complexType>
          <xsd:sequence><xsd:element name="symbol" type="xsd:string" /></xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </types>

  <message name="GetQuoteRequest">
    <part name="parameters" element="tns:GetQuote" />
  </message>

  <portType name="QuotePortType">
    <operation name="GetQuote">
      <input message="tns:GetQuoteRequest" />
      <output message="tns:GetQuoteResponse" />
    </operation>
  </portType>

  <binding name="QuoteBinding" type="tns:QuotePortType">
    <soap:binding style="document"
                  transport="http://schemas.xmlsoap.org/soap/http" />
  </binding>

  <service name="QuoteService">
    <port name="QuotePort" binding="tns:QuoteBinding">
      <soap:address location="https://api.example.com/quotes" />
    </port>
  </service>
</definitions>

document style with literal encoding is the interoperable default; rpc/encoded is legacy and should be avoided for new work.
A WSDL can import XSD files, so the real type definitions are often in a sibling .xsd rather than inline.
To read an unfamiliar service, start at service for the endpoint, then work backwards through binding, portType and types.

Generating a client

# Java: JDK ships wsimport; Jakarta's wsdl2java is the maintained option
wsimport -keep -p com.example.quotes -d out https://api.example.com/quotes?wsdl
wsdl2java -d out -p com.example.quotes https://api.example.com/quotes?wsdl

# .NET
dotnet svcutil https://api.example.com/quotes?wsdl

# Python: ask for a plain dictionary instead of a proxy class
python -m zeep https://api.example.com/quotes?wsdl

Generated code turns the contract into classes and a proxy whose methods look like local calls. The WSDL becomes your interface documentation: endpoint, operations, argument types and the exact fault types you must handle.

⚠️

A WSDL is a contract, so treat a change in it as a breaking API change. Keep a copy of the version you generated against; if the provider silently changes a type or a namespace, a regeneration can break your build for reasons that have nothing to do with your code.

FAQ

What is the difference between WSDL and XSD?

XSD defines the data types; the WSDL defines the service — operations, bindings and endpoint — and usually embeds or imports the XSD for its types.

Why does my generated client fail on a type mismatch?

Usually a namespace or element-name difference between the WSDL you generated from and the one the server now serves, or a nil versus missing-element distinction in the schema.

What SOAP is and how the envelope works Calling a SOAP service, and why REST usually wins

Last refreshed 2026-09-18.

WSDL contracts and code generation

The parts of a WSDL

Generating a client

FAQ

Related