Язык описания веб-сервисов WSDL (Web Services Description Language) основан на языке XML. В июне 2007 года была утверждена WSDL 2.0 в качестве стандарта W3C (World Wide Web Consortium), но несмотря на это версия WSDL 1.1 остается широко используемой формой описания Web-сервисов SOAP. WSDL 1.1 имеет определенные недостатки, включающие чрезмерно сложную структуру. Это серьезно затрудняет его чтение для начинающих.

На рисунке, позаимствованному из Wikipedia, представлены структуры WSDL для версий 1.1 и 2.0.

WSDL 1.1

В WSDL документах версии 1.1 используется корневая секция с названием <wsdl:definitions>, включающая один «пассивный» дочерний элемент (ссылка на отдельные документы WSDL 1.1) и пять «активных» дочерних элементов, составляющие описание сервиса :

Тег/секция	Назначение	Примечание
wsdl:import	Секция отдельного документа WSDL 1.1	Отдельный документ WSDL 1.1 с описаниями, включаемый в текущий документ
wsdl:types	Секция определения типов данных	Определение вида отправляемых и получаемых сервисом XML-сообщений
wsdl:message	Секция элементов данных	Описание используемых Web-сервисом сообщений
wsdl:portType	Секция абстрактных операций	Список операций, которые могут быть выполнены с сообщениями
wsdl:binding	Секция связывания сервисов	Описание способов доставки сообщений
wsdl:service	Секция определения сервиса	Описание сервиса в целом, как правило, включая один или несколько элементов <wsdl:port> с информацией доступа для элементов <wsdl:binding>

Первым дочерним элементом секции <wsdl:definitions> для документирования может быть использован не представленный в таблице элемент <wsdl:documentation>. Данный тег может быть также использован также для документирования любого из элементов описания сервиса.

Для полного описания сервиса требуется один элемент каждого из представленных в таблице типов, за исключением <wsdl:import>. Но не обязательно, чтобы все они находились в одном и том же документе. Элемент <wsdl:import> позволяет собирать полное описание WSDL из нескольких документов. Три элемента описания (<wsdl:types>, <wsdl:message> и <wsdl:portType>) формируют полное описание интерфейса сервиса. Элементы <wsdl:binding> и <wsdl:service> ориентированы на реализацию элементов сервиса.

Пример WSDL 1.1

На странице описания клиентов SOAP были использованы действующие WEB-сервисы получения значений кодов ZIP города Нью-Йорк и информации сервиса BELAVIA. В качестве примера описания WSDL рассмотрим WEB сервис BELAVIA. Следующий листинг представляет структуру сервиса wsdl :

Структура WSDL сервиса BELAVIA

Описания сервиса WSDL представлено одним документом и не включает секцию <wsdl:import>. В корневой секции <wsdl:definitions> определяются именованные пространства, используемые при описании элементов документа.


<wsdl:definitions 
        xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
        xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/"
        xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
        xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
        xmlns:tns="http://webservices.belavia.by/"
        xmlns:s="http://www.w3.org/2001/XMLSchema"
        xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
        xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
        targetNamespace="http://webservices.belavia.by/">
    <wsdl:documentation
        xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
        <img src="webservice.jpg" />
    </wsdl:documentation>

    <wsdl:types>
        <s:schema>
            . . .
            <s:element name="GetAirportsList">
                <s:complexType>
                    <s:sequence>
                        <s:element minOccurs="0" maxOccurs="1" 
                                   name="Language" type="s:string"/>
                    </s:sequence>
                </s:complexType>
            </s:element>
            <s:element name="GetAirportsListResponse">
                <s:complexType>
                    <s:sequence>
                        <s:element minOccurs="0" maxOccurs="1"
                                   name="GetAirportsListResult"
                                   type="tns:AirportsResponse"/>
                    </s:sequence>
                </s:complexType>
            </s:element>
            <s:complexType name="AirportsResponse">
                <s:sequence>
                    <s:element minOccurs="0" maxOccurs="unbounded"
                               name="Airport"
                               type="tns:Airport"/>
                </s:sequence>
            </s:complexType>
            <s:complexType name="Airport">
                <s:attribute name="IATA" type="s:string"/>
            <s:attribute name="Name" type="s:string"/>
            </s:complexType>
        </s:schema>
    </wsdl:types>

    <wsdl:message name="GetTimeTableSoapIn">
        <wsdl:part name="parameters"
                   element="tns:GetTimeTable"/>
    </wsdl:message>
    <wsdl:message name="GetTimeTableSoapOut">
        <wsdl:part name="parameters" 
                   element="tns:GetTimeTableResponse"/>
    </wsdl:message>
    <wsdl:message name="GetAirportsListSoapIn">
        <wsdl:part name="parameters"
                   element="tns:GetAirportsList"/>
    </wsdl:message>
    <wsdl:message name="GetAirportsListSoapOut">
        <wsdl:part name="parameters"
                   element="tns:GetAirportsListResponse"/>
    </wsdl:message>
 
    <wsdl:portType name="OnlineTimeTableSoap">
        <wsdl:operation name="GetTimeTable">
            <wsdl:documentation 
                xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
                Возвращает список рейсов с информацией о 
                прилёте / вылете и состоянии рейса.
                Входные параметры:
                    . . .  
            </wsdl:documentation>
            <wsdl:input message="tns:GetTimeTableSoapIn"/>
            <wsdl:output message="tns:GetTimeTableSoapOut"/>
        </wsdl:operation>
        <wsdl:operation name="GetAirportsList">
            <wsdl:documentation
                xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
                Возвращает список аэропортов, где есть 
                информация о выполняемых рейсах.
                Входные параметры:
                    . . .  
            </wsdl:documentation>
            <wsdl:input message="tns:GetAirportsListSoapIn"/>
            <wsdl:output message="tns:GetAirportsListSoapOut"/>
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="OnlineTimeTableSoap" 
                  type="tns:OnlineTimeTableSoap">
        <soap:binding 
              transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="GetTimeTable">
            <soap:operation
              soapAction="http://webservices.belavia.by/GetTimeTable"
              style="document"/>
            <wsdl:input>
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>
        <wsdl:operation name="GetAirportsList">
            <soap:operation
              soapAction="http://webservices.belavia.by/GetAirportsList"
              style="document"/>
            <wsdl:input>
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:binding name="OnlineTimeTableSoap12"
                  type="tns:OnlineTimeTableSoap">
        <soap12:binding 
            transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="GetTimeTable">
            <soap12:operation 
              soapAction="http://webservices.belavia.by/GetTimeTable"
              style="document"/>
            <wsdl:input>
                <soap12:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap12:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>
        <wsdl:operation name="GetAirportsList">
            <soap12:operation
              soapAction="http://webservices.belavia.by/GetAirportsList"
              style="document"/>
            <wsdl:input>
                <soap12:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap12:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>

    <wsdl:service name="OnlineTimeTable">
        <wsdl:documentation 
            xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
            <img src="webservice.jpg" />
        </wsdl:documentation>
        <wsdl:port name="OnlineTimeTableSoap" 
                   binding="tns:OnlineTimeTableSoap">
            <soap:address 
              location="http://86.57.245.235/TimeTable/Service.asmx"/>
        </wsdl:port>
        <wsdl:port name="OnlineTimeTableSoap12" 
                   binding="tns:OnlineTimeTableSoap12">
            <soap12:address 
              location="http://86.57.245.235/TimeTable/Service.asmx"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

Секция <wsdl:types> включает используемые для сообщений определения XML в виде одного или нескольких элементов <s:schema>. WSDL допускает альтернативы XML-схеме для этих определений, но большинство стеков поддерживает только XML-схемы. При необходимости элементы <s:schema> могут включать <s:import> или <s:include> для вставки внешних по отношению к WSDL других схем. В листинге приведен усеченный перечень элементов секции <wsdl:types>.

Компонентам документа WSDL присваиваются отдельные имена с использованием атрибута name. При использовании в корневом элементе документа <wsdl:definitions> атрибута targetNamespace, имена этих компонентов определены в этом пространстве имен. Это означает, что при определении имени достаточно присвоить простую, или «локальную», часть имени, но ссылки на этот компонент должны уточнять имя с помощью префикса пространства имен или с помощью пространства имен по умолчанию.

Представленные элементами <wsdl:message> сообщения расположены в ядре описаний сервисов WSDL. Элементы <wsdl:message> являются описаниями XML-данных, передаваемых между клиентом и поставщиком услуг. Каждый элемент <wsdl:message> содержит, как правило, один дочерний элемент <wsdl:part>, для которого требуется собственный уникальный в пределах <wsdl:message> атрибут name и один из атрибутов element или type, ссылающийся на определение схемы XML-данных.

Элементы <wsdl:portType> определяют абстрактный интерфейс сервиса в части сообщений, передаваемых сервису и принимаемых от него, и содержат любое количество дочерних элементов <wsdl:operation>. Дочерний элемент <wsdl:operation> имеет собственный атрибут name и включает один или несколько дочерних элементов с описанием сообщения. В зависимости от способа использования могут быть включены следующие типы дочерних элементов :

<wsdl:input> — входные данные, отправляемые клиентом поставщику услуг;
<wsdl:output> — возвращаемые клиенту поставщиком услуг данные;
<wsdl:fault> — возвращаемые клиенту поставщиком услуг данные при возникновении ошибки.

WSDL 1.1 определяет две модели взаимодействия клиента и поставщика услуг, представленных различными последовательностями дочерних элементов <wsdl:input> и <wsdl:output> : операций типа запрос-ответ, где за <wsdl:input> следует <wsdl:output>, и односторонние операции, содержащие только <wsdl:input>. В случае операций типа запрос-ответ за элементами <wsdl:input> и <wsdl:output> может следовать любое количество элементов <wsdl:fault>.

Каждый элемент <wsdl:input>, <wsdl:output> или <wsdl:fault> включает ссылку на описание сообщения в виде обязательного атрибута message. В данной ссылке уточняется пространство имен добавлением префикса.

Если рассмотреть элемент <wsdl:portType> с точки зрения Java как определение интерфейса, то элементы <wsdl:operation> будут эквивалентны методам, включающим в качестве параметров элементы <wsdl:input>; элементы <wsdl:output> будут определять результаты выполнения методов, а <wsdl:fault> соответствовать исключениям. Этот подход используется при генерировании кода Java из WSDL.

Дочерние элементы <wsdl:binding> содержат информацию о способе реализации. Элементы из пространства имен WSDL соответствуют элементам <wsdl:portType> и должны использовать то же значение name – а не ссылки с уточнением пространства имен, как в случае <wsdl:portType>. Та же связь по имени относится и к дочерним элементам <wsdl:input>/<wsdl:output>/<wsdl:fault> элементов <wsdl:operation>. Несмотря на повторное использование одних и тех же имен элементов, содержание этих элементов существенно отличается для дочерних элементов <wsdl:binding> относительно элементов <wsdl:portType>.

Расширения, определяемые WSDL, вступают в игру в <wsdl:binding>. Дочерний элемент <soap:binding> используется в определении сервиса SOAP и включает обязательный атрибут transport для определения вида транспорта, используемого привязкой. Необязательный атрибут style позволяет выбирать способ rpc или document для представления XML-данных. Наиболее распространенное значение document соответствует сообщениям с использованием элементов определения схемы, а не типа.

Элемент <wsdl:binding> включает дочерние элементы <wsdl:operation> внутри которого

тег <soap:operation> используется для значения SOAPAction с целью идентификации запросов,
дочерние элементы <wsdl:input>/<wsdl:output>/<wsdl:fault> содержат теги <soap:body>, указывающих, что данные сообщения передаются в теле сообщения SOAP.

Последним компонентом описания сервиса WSDL является элемент <wsdl:service> который состоит из группы элементов <wsdl:port>. Каждый элемент <wsdl:port> связывает адрес доступа с <wsdl:binding>. Адрес доступа определяется атрибутом тега<soap:address>.

WSDL 2.0

Описание документа WSDL 2.0 на странице не приводится, но желающие могут ознакомится с англо-язычной версией здесь.