WSDL - <documentation> element in WSDL
What is the <documentation> Element?
The <documentation> element in WSDL is used to insert human-readable notes into a WSDL file.
It does not affect how the service behaves or how clients interact with it — instead, it provides clarity, context, and explanation for developers or anyone reading the WSDL.
Think of it as comments inside WSDL, but written as XML elements rather than ignored text.
Where Can <documentation> Be Used?
The <documentation> element can appear inside most major WSDL elements, including:
-
<definitions>– to describe the overall service. -
<types>– to explain the purpose of defined data types. -
<message>– to describe the meaning of input/output messages. -
<portType>and<operation>– to clarify what the operation does. -
<binding>– to explain protocol-specific details. -
<service>and<port>– to describe endpoints.
Example of <documentation> in WSDL
<definitions name="WeatherService"
targetNamespace="http://example.com/weather"
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:tns="http://example.com/weather">
<documentation>
This WSDL describes the Weather Service, which provides weather forecasts based on city names.
</documentation>
<message name="GetWeatherRequest">
<part name="city" type="xsd:string"/>
<documentation>
The city for which the weather information is requested.
</documentation>
</message>
<message name="GetWeatherResponse">
<part name="forecast" type="xsd:string"/>
<documentation>
The weather forecast in text format.
</documentation>
</message>
</definitions>
Why is <documentation> Useful?
-
Improves Readability – Makes complex WSDL files easier to understand.
-
Aids Developers – Explains the purpose of operations, messages, and data types.
-
Acts as API Documentation – Serves as inline documentation that tools can extract and display.
-
Non-Intrusive – It does not affect execution or client code generation, only provides guidance.
In short:
The <documentation> element is not for machines but for humans. It helps developers quickly understand the why and how behind the service definitions inside WSDL.
