Copyright © 2002 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use, and software licensing rules apply.
This document describes the Web Services Description Language (WSDL) Version 1.2, an XML language for describing Web services. This specification defines the core language which can be used to describe Web services based on an abstract model of what the service offers.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.
This is the first W3C Working Draft of the Web Services Description Language (WSDL) 1.2 document.
This document has been produced as part of the W3C Web Services Activity. The authors of this document are the Web Services Description Working Group members.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". This is work in progress and does not imply endorsement by, or the consensus of, either W3C or members of the Web Services Description Working Group.
Comments on this document are invited and are to be sent to public-ws-desc-comments@w3.org (public archive). It is inappropriate to send discussion emails to this address. Discussion of this document takes place on the public www-ws-desc@w3.org mailing list (public archive).
Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.
A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.
1. Introduction
2. Conceptual Framework
3. WSDL Documents
4. Language Extensibility and
Binding
5. Overall Issues
6. References
A. Acknowledgements (Non-Normative)
B. Part 1 Change Log (Non-Normative)
1. Introduction
1.1 Notational
Conventions
2. Conceptual Framework
2.1 Type
Description Component
2.2 Message Description Components
2.3 PortType Description Component
2.3.1 Parameter Order within an
Operation
2.4 ServiceType Description
Component
2.5 Binding Description Component
2.6 Service Description Component
3. WSDL Documents
3.1 Definitions
3.1.1 targetNamespace Attribute
3.1.2 name Attribute
3.2 Documentation
3.3 Importing
Documents
3.4 Types
3.4.1 Guidelines for Using XML Schema
3.4.2 Using Other Type Systems
3.5 Messages
3.6 Port
Types
3.6.1 Names of Elements within
an Operation
3.7 Service
Types
3.8 Bindings
3.9 Ports
3.10 Services
3.11 WSDL Document
Structure
4. Language Extensibility and
Binding
5. Overall Issues
6. References
6.1 Normative References
6.2 Informative References
A. Acknowledgements
(Non-Normative)
B. Part 1 Change Log (Non-Normative)
B.1 WSDL 1.2
Specification Changes
Web Services Description Language (WSDL) is an XML [XML 1.0] format for describing Web services. WSDL enables one to separate the description of the abstract functionality offered by a service from concrete details of a service description such as "how" and "where" that functionality is offered.
This specification defines a language for describing the abstract functionality of a service as well as a framework for describing the concrete details of a service description. The companion specification, WSDL Version 1.2: Bindings [WSDL 1.2 Bindings] defines a language for describing such concrete details for SOAP 1.2 [SOAP 1.2: Messaging Framework], HTTP [IETF RFC 2616] and MIME [IETF RFC 2045].
WSDL describes Web services starting with the messages that are exchanged between the service provider and requestor. The messages themselves are described abstractly and then bound to a concrete network protocol and message format. A message consists of a collection of typed data items. An exchange of messages between the service provider and requestor are described as an operation. A collection of operations is called a portType. Collections of portTypes are grouped and called a serviceType. A service represents an implementation of a serviceType and contains a collection of ports, where each port is an implementation of a portType, which includes all the concrete details needed to interact with the service.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [IETF RFC 2119].
This specification uses namespace prefixes throughout; they are listed in Table 1. Note that the choice of any namespace prefix is arbitrary and not semantically significant (see [XML Information Set]).
Prefix | Namespace | Notes |
---|---|---|
wsdl | "http://www.w3.org/2002/07/wsdl" | A normative XML Schema [XML Schema: Structures], [XML Schema: Datatypes] document for the "http://www.w3.org/2002/07/wsdl" namespace can be found at http://www.w3.org/2002/07/wsdl. |
soap12 | "http://www.w3.org/2002/07/wsdl/soap12" | Defined by WSDL 1.2: Bindings [WSDL 1.2 Bindings]. |
http | "http://www.w3.org/2002/07/wsdl/http" | Defined by WSDL 1.2: Bindings [WSDL 1.2 Bindings]. |
mime | "http://www.w3.org/2002/07/wsdl/mime" | Defined by WSDL 1.2: Bindings [WSDL 1.2 Bindings]. |
xsd | "http://www.w3.org/2001/XMLSchema" | Defined in the W3C XML Schema specification [XML Schema: Structures], [XML Schema: Datatypes]. |
xsi | "http://www.w3.org/2001/XMLSchema-instance" | Defined in the W3C XML Schema specification [XML Schema: Structures], [XML Schema: Datatypes]. |
Namespace names of the general form "http://example.org/..." and "http://example.com/..." represent application or context-dependent URIs [IETF RFC 2396].
All parts of this specification are normative, with the exception of examples and sections explicitly marked as "Non-Normative".
Editorial note: Jean-Jacques Moreau | June 26, 2002 |
WSDL 1.1 did not provide its own abstract model. The WSD WG has decided to provide an abstract model for WSDL 1.2; however, the WG has not reached consensus on what that abstract model should look like. This section is an attempt at providing such a model, but as said, it does not represent consensus, and is likely to be revised significantly in the a future revision of this specification. |
A WSDL definitions group consists a group or collection of description components that apply within a single target namespace. A description component is a description of some aspect of a Web service; it may be that of some data types involved with the messages exchange or the interfaces of a Web service, for example. We say that each description component is characterized by a set of properties that they exhibit. In the rest of this section we identify the kinds of description components present in WSDL, explain their role and identify all the properties of those components.
A WSDL definitions group MAY be the result of combining one or more XML documents using XML level inclusion mechanisms such as XLink [XML Linking]. It MAY also be the result of combining multiple XML documents in the WSDL namespace using the import mechanism defined in this specification (see 3.3 Importing Documents). The conceptual framework described in this section assumes that a group of description components is the result of processing all such inclusions.
A given definitions group is allowed not to describe all aspects of a service; i.e., a complete service description MAY be the result of combining information from several such definition groups.
WSDL defines six kinds of description components:
type description component
message description component
portType description component
serviceType description component
binding description component
service description component
A given WSDL definitions group MAY contain:
at most one type description component, and
zero or more message description components, and
zero or more portType description components, and
zero or more serviceType description components, and
zero or more binding description components, and
zero or more service description components.
A definitions group has a REQUIRED "targetNamespace" property identifying the namespace in which all description components contained within it will be defined. This property SHALL NOT apply to the type description component as type definition languages are assumed to have their own mechanism for this purpose.
Every description component, except type description components, has a REQUIRED "name" property. The value of this property combined with the value of the targetNamespace property of the containing description group forms a qualified name (QName) which MUST uniquely identify the definition component from amongst all other description components of the same kind. That is, each kind of description component has its own symbol space. For example, it MAY be the case that the value of the "name" property of a portType description component and that of a serviceType description component belonging to the same targetNamspace, are the same.
Every description component has an OPTIONAL "documentation" property. The value of this property is arbitrary and SHOULD be used to provide human or machine processable documentation about the description component.
Every description component MAY have additional properties identified by qualified names from namespaces other than the WSDL namespace (see Table 1). The semantics of those properties are NOT defined by this specification.
The type description component is where data types are defined. WSDL does not define its own data typing language. Instead, it defers that task to existing type languages such as XML Schema [XML Schema: Datatypes] and provides a mechanism to "host" any number of type definitions from such languages. A type description component MUST contain at least one set of type definitions so that those can be referred to from other parts of WSDL.
WSDL recognizes that using XML Schema [XML Schema: Datatypes] as the type system language will result in maximal interoperability of Web services described in WSDL. Thus, it is RECOMMENDED that the XML Schema type system be used to describe messages exchanged between Web services whenever possible.
A message description component is used to model messages exchanged between Web services. A message description component defines logically a "type" of a message which MAY be used to define the input, output or fault message of an operation of a portType description component (see 2.3 PortType Description Component).
A message description component has a REQUIRED "name" property which must be unique across all message description components defined in the same target namespace as this message description component. Thus, the qualified name formed by the value of the targetNamespace property and the name property uniquely identifies the message description component.
A message description component contains zero or more descriptions of "parts" of messages, where a message part is considered an atomic entity from WSDL's point of view. A part has a REQUIRED "name" property which must be unique within the message description component only. Additionally, the "type" of data that the part represents MUST be described using a mechanism specific to the type system in use (see 2.1 Type Description Component).
Message definitions are always considered to be an abstract definition of the message content. A message binding describes how the abstract content is mapped into a concrete format. However, in some cases, the abstract definition may match the concrete representation very closely or exactly for one or more bindings, so those binding(s) will supply little or no mapping information. However, another binding of the same message definition may require extensive mapping information. For this reason, it is not until the binding is inspected that one can determine "how abstract" the message really is.
WSDL makes special recognition of the XML Schema language as a RECOMMENDED type specification language (see 2.1 Type Description Component). A part MAY indicate its XML Schema nature using either the "type" or "element" property of a part description. The value of the "type" property MUST be a qualified name referring to a complex or simple type defined in some namespace. Similarly, the value of the "element" property MUST be a qualified name referring to a global element declaration in some namespace.
If a type system other than XML Schema is used, then a new property MUST be introduced to the part description to refer to types from that type system.
A portType description component adheres to the semantics commonly associated with an "interface." A portType description component contains one or more descriptions of operations offered by the service.
A portType description component has a REQUIRED "name" property which, along with its targetNamespace property uniquely identifies the portType description component.
An operation description has a REQUIRED "name" property, which must be unique within the names of all operations in this portType description component only.
An operation description has an OPTIONAL "documentation" property. The value of this property is arbitrary and SHOULD be used to provide human or machine processable documentation about the operation.
An operation MAY have an input message property, which refers to the qualified name of a message description component.
An operation MAY have an output message property, which similarly refers to the qualified name of a message description component.
An operation MAY have zero or more fault message properties, each of refers to the qualified name of a message description component.
An operation MUST have an input message property, an output message property or both. The input property represents the "input" message for the operation (if any), the output property the "output" message from the completion of the operation (if any) and the fault properties the fault messages that may be generated instead of the output message.
The various combinations of input and output messages of operations give rise to four kinds of operations:
Input-Output Operations: Operations which have both input and output messages listed in that order. The semantics are that when the input message is sent to the service, one of the following MUST happen: the output message is generated; or one of the fault messages listed is generated instead. It is an error for both an output message and a fault message to be generated in response to the same input message.
Input-Only Operations: Operations which have only an input message. The semantics are that when a message is sent to the service, the service consumes it but does not produce any output message. There MUST NOT be any fault messages indicated in this case.
Output-Input Operations: Operations which have both output and input messages listed in that order. The semantics are that the service will generate the output message and in return the input message MUST be received or one of the fault messages listed MUST be received.
Output-Only Operations: Operations which have only an output message. The semantics are that the service will generate the output message but does not expect to receive any response message or fault messages. There MUST NOT be any fault messages indicated in this case.
Editorial note: Editorial cleanup after finalizing issues. | June 27, 2002 |
If we remove parameterOrder then this section would go away. This section has not been edited pending resolution of issue issue-remove-parameter-order. |
Operations do not specify whether they are to be used with
RPC-like bindings or not. However, when using an operation with an
RPC-binding, it MAY be useful to be able to capture the original
RPC function signature. For this reason, an input-output or
output-input operation MAY specify a list of parameter names via
its parameterOrder
property. The value of the
attribute is a list of message part names separated by a single
space. The value of the parameterOrder attribute MUST follow the
following rules:
The part name order reflects the order of the parameters in the RPC signature
The return value part is not present in the list
If a part name appears in both the input and output message, it is an in/out parameter
If a part name appears in only the input message, it is an in parameter
If a part name appears in only the output message, it is an out parameter
Note that this information serves as a "hint" and may safely be ignored by those not concerned with RPC signatures. Also, it is not required to be present, even if the operation is to be used with an RPC-like binding.
A serviceType description component defines a grouping of a set of portTypes. A service description component (see 2.6 Service Description Component) refers to a serviceType description to indicate the abstract functionality offered by that service.
A serviceType description component has a REQUIRED "name" property which, along with its targetNamespace property uniquely identifies the serviceType description component.
A serviceType description component identifies one or more portType description components as being members of itself. PortType description components are identified by their QName and the same portType description component (as identified by its QName) MUST NOT appear more than once in a single serviceType description component.
A binding description component provides a framework for indicating binding details for a portType description component. Binding details SHOULD be used to indicate how messages MUST be formatted when they are sent to or from the service. They SHOULD also be used to indicate the transport protocol to be used to send the messages. A given binding description component MUST NOT indicate more than one protocol.
No concrete binding details are given in this specification. The companion specification, WSDL (Version 1.2): Bindings [WSDL 1.2 Bindings] defines such bindings for SOAP 1.1 [SOAP 1.1], SOAP 1.2 [SOAP 1.2: Messaging Framework], HTTP [IETF RFC 2616] and MIME [IETF RFC 2045]. Other specifications MAY define additional binding details.
Editorial note: Should WSDL 1.2 (part 2) including bindings for SOAP 1.1? | June 25, 2002 |
The WS Description WG currently investigating whether it will support SOAP 1.1 in this specification, as a W3C note, or otherwise. We will of course support SOAP 1.2. |
A binding description component has a REQUIRED "name" property which, along with its targetNamespace property uniquely identifies the binding description component.
A binding description component has a REQUIRED "type" property which MUST be the qualified name of a portType description component.
A binding description component MUST contain one or more binding detail properties. Binding detail properties MAY be specified as being applicable for all operations of the portType or on a per-operation basis. They MAY be further constrained as being applicable only for the input, output or faults of a given operation.
A service description component defines a Web service. A service is a collection of ports. A port is a bound portType, including a specific end-point (address) at which the service is available.
A service description component has a REQUIRED "name" property which, along with its targetNamespace property uniquely identifies the service description component.
A service description component has a REQUIRED "serviceType" property which MUST be the qualified name of a serviceType description component.
A service description component MUST contain one or more port description components. Properties of port description components are given below:
A port description component has a REQUIRED "name" property, which is used to identify this port. This name property MUST be unique across the entire descriptions group in which the containing service description component resides. Note that while the name property is of type NCName, it SHALL NOT be used as the localPart of a qualified name with the targetNamespace of the containing descriptions group as the namespace name.
A port description component has a REQUIRED "binding" property, which MUST be the name of a binding description component which indicates how messages sent to/from this port MUST be formatted.
A port description component MUST specify the end-point (address) to which messages MUST be sent to reach the operations of the portType description component referred to in the binding description component referred to be the "binding" property.
A port description component has an OPTIONAL "documentation" property. The value of this property is arbitrary and SHOULD be used to provide human or machine processable documentation about the port.
A service description component MAY contain one or more binding detail properties in addition to the port properties. The semantics of those binding details are defined by the specific binding detail.
A WSDL document defines a collection of description components.
A WSDL document is specified as an XML Infoset [XML Information Set] that consists of a
document information item with exactly one member in its
[children] property, which MUST be the WSDL
definitions
element information item (see 3.1 Definitions). This
element information item is also the value of the
[document element] property. The [notations] and [unparsed
entities] properties are both empty. The [base URI], [character
encoding scheme] and [version] properties can have any legal value.
The [standalone] property either has a value of "yes" or has no
value.
element information items defined by this specification can have zero or more character information item children whose character code is among the whitespace characters as defined by [XML 1.0]. Unless otherwise indicated, such character information items are considered insignificant. A WSDL processor MUST ignore such insignificant character information items.
The definitions
element information item
has:
A [local name] of definitions
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
Zero or more namespace qualified attribute information items amongst its [attributes] property.
One or more element information items in its [children] property from amongst the following:
An OPTIONAL documentation
element information
item (see 3.2
Documentation).
Zero or more import
element information
items (see 3.3 Importing
Documents).
At most one types
element information item
(see 3.4 Types).
Zero or more message
element information
items (see 3.5
Messages).
Zero or more portType
element information
items (see 3.6 Port
Types).
Zero or more serviceType
element information
items (see 3.7 Service
Types).
Zero or more binding
element information
items (see 3.8
Bindings).
Zero or more service
element information
items (see 3.10
Services).
The definitions
element information item
MUST contain at least one of the above element information
items in its [children] property. If it contains more than one
of the above element information items, then the following
order MUST be observed: all import
element
information items (if any), followed by the types
element information item (if present), followed by any
number of message
, portType
,
serviceType
, binding
and
service
element information items in any
order.
The targetNamespace
attribute information
item indicates the namespace in which all other definition
components found in this definitions group will be defined.
The targetNamespace
attribute information
item has:
A [local name] of targetNamespace
.
A [namespace name] which has no value.
The OPTIONAL name
attribute information
item can be used as a lightweight form of documentation for a
definitions group.
The name
attribute information item
has:
A [local name] of name
.
A [namespace name] which has no value.
WSDL uses the optional documentation
element as a
container for human readable documentation. The content of the
element is arbitrary text and elements ("mixed" in XML
Schema[XML Schema:
Structures]). The documentation
element is
allowed inside any WSDL language element.
The documentation
element information item
has:
A [local name] of documentation
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
Zero or more attribute information items in its [attributes] property.
Zero or more child element information items in its [children] property.
The WSDL import
element information item
allows the separation of the different elements of a service
definition into independent documents, which can be imported as
needed. This technique helps writing clearer service definitions,
by separation the definitions according to their level of
abstraction, and maximizes reusability. The WSDL
import
element information item is modeled
after the XML Schema import
element information
item (see [XML Schema:
Structures], section 4.2.3 "References to schema
components across namespaces").
The import
element information item
has:
A [local name] of import
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
A REQUIRED attribute information item which has:
A [local name] of namespace
.
A [namespace name] which has no value.
namespace
attribute information item is
of type anyURI
in the namespace named
"http://www.w3.org/2001/XMLSchema". Its actual value indicates that
the containing WSDL document can contain qualified references to
WSDL definitions in that namespace (via one or more prefixes
declared with namespace declarations in the normal way). This value
MUST NOT match the actual value of the enclosing WSDL document
targetNamespace
attribute information item.
It MUST be identical to the actual value of the referred WSDL
document's targetNamespace
attribute information
item.
A REQUIRED attribute information item which has:
A [local name] of location
.
A [namespace name] which has no value.
location
attribute information item is of
type anyURI
in the namespace named
"http://www.w3.org/2001/XMLSchema". Its actual value is the
location of some information for the namespace identified by the
targetNamespace
attribute information
item.The wsdl:types element encloses data type definitions that are relevant for the exchanged messages.
The types
element information item
has:
A [local name] of types
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
An OPTIONAL documentation
element information
item (see 3.2
Documentation) in its [children] property.
Zero or more attribute information items in its [attributes] property.
Zero or more child element information items in its [children] property.
The XSD type system MAY be used to define the types in a message regardless of whether or not the resulting wire format is actually XML, or whether the resulting XSD schema validates the particular wire format. This is especially interesting if there will be multiple bindings for the same message, or if there is only one binding but that binding type does not already have a type system in widespread use. In these cases, the recommended approach for encoding abstract types using XSD is as follows:
Use element form (not attribute).
Don't include attributes or elements that are peculiar to the wire encoding (i.e. have nothing to do with the abstract content of the message). Some examples are soap:root, soap:encodingStyle, xmi:id, xmi:name.
Array types should extend the Array type defined in the SOAP
v1.1 encoding schema "http://schemas.xmlsoap.org/soap/encoding/"
(regardless of whether the resulting form actually uses the
encoding specified in Section 5 of [SOAP
1.1]). Use the name ArrayOfXXX for array types (where
XXX is the type of the items in the array). The type of the
items in the array and the array dimensions are specified by using
a default value for the soapenc:arrayType attribute. At the
time of this writing, the XSD specification does not have a
mechanism for specifying the default value of an attribute which
contains a QName value. To overcome this limitation, WSDL
introduces the arrayType
attribute (from namespace
http://schemas.xmlsoap.org/wsdl/) which has the semantic of
providing the default value. If XSD is revised to support
this functionality, the revised mechanism SHOULD be used in favor
of the arrayType attribute defined by WSDL.
Use the xsd:anyType type to represent a field/parameter which can have any type.
When XSD is used as the type system, the [children] property of
the types
element information item SHOULD
contain the element information item with a [local name]
property of schema
and a namespace name of
"http://www.w3.org/2001/XMLSchema" which contains the schema
definition.
However, since it is unreasonable to expect a single type system
grammar can be used to describe all abstract types present and
future, WSDL allows type systems to be added via extensibility
elements. An extensibility element MAY appear under the
types
element information item to identify
the type definition system being used and to provide an XML
container element for the type definitions. The role of this
element can be compared to that of the schema
element
of the XML Schema language.
The message
element information item is
used to define a message description component (2.2 Message Description
Components) and has:
A [local name] of message
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
A REQUIRED attribute information item which has:
A [local name] of name
.
A [namespace name] which has no value.
One or more child element information items in its [children] property where each has:
A [local name] of part
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
A REQUIRED attribute information item which has:
A [local name] of name
.
A [namespace name] which has no value.
An OPTIONAL attribute information item which has:
A [local name] of type
.
A [namespace name] which has no value.
An OPTIONAL attribute information item which has:
A [local name] of element
.
A [namespace name] which has no value.
It MUST be the case that either the type
attribute information item is present or the
element
attribute information item is present
or some other attribute information item which indicates
the type of this message part is present.
A portType is a named set of operations offered by the Web service, where an operation itself is a name given to a correlated exchange of messages. Thus, an operation is defined by its name, the data or fault messages received by the service for this operation (if any) and the data or fault messages sent by the service for this operation (if any).
The portType
element information item is
used to define a portType component description (2.3 PortType Description
Component) and has:
A [local name] of portType
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
A REQUIRED attribute information item which has:
A [local name] of name
.
A [namespace name] which has no value.
One or more child element information items in its [children] property where each has:
A [local name] of operation
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
A REQUIRED attribute information item which has:
A [local name] of name
.
A [namespace name] which has no value.
An OPTIONAL element information item in its [children] property which has:
A [local name] of input
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
A REQUIRED attribute information item which has:
A [local name] of message
.
A [namespace name] which has no value.
An OPTIONAL element information item in its [children] property which has:
A [local name] of output
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
A REQUIRED attribute information item which has:
A [local name] of message
.
A [namespace name] which has no value.
Zero or more element information items in its [children] property where each has:
A [local name] of fault
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
A REQUIRED attribute information item which has:
A [local name] of name
.
A [namespace name] which has no value.
fault
element information
items in this operation
element information
item.
A REQUIRED attribute information item which has:
A [local name] of message
.
A [namespace name] which has no value.
operation
element information item MUST
have at least an input
or output
element information item in its [children] property. The
combinations of input
and output
element information items give rise to the different kinds
of operations identified in 2.3 PortType Description
Component.Editorial note: Editorial cleanup after removing operation overloading | June 27, 2002 |
If we remove support for operation overloading as we are currently orienting then this section would go away. |
The name
attribute of the input and output elements
provides a unique name among all input and output elements within
the enclosing port type.
In order to avoid having to name each input and output element within an operation, WSDL provides some default values based on the operation name. If the name attribute is not specified on a one-way or notification message, it defaults to the name of the operation. If the name attribute is not specified on the input or output messages of a request-response or solicit-response operation, the name defaults to the name of the operation with "Request"/"Solicit" or "Response" appended, respectively.
Each fault element must be named to allow a binding to specify the concrete format of the fault message. The name of the fault element is unique within the set of faults defined for the operation.
The serviceType
element information item
is used to define a serviceType component description and has:
A [local name] of serviceType
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
A REQUIRED attribute information item which has:
A [local name] of name
.
A [namespace name] which has no value.
One or more child element information items in its [children] property where each has:
A [local name] of portType
.
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
A REQUIRED attribute information item which has:
A [local name] of name
.
A [namespace name] which has no value.
Editorial note: Editorial cleanup after finalizing bindings | June 27, 2002 |
We expect some changes to occur here due to the need to support serviceTypes. We will be moving the description to be Infoset based after such changes have been done. |
A binding defines message format and protocol details for operations and messages defined by a particular portType. There may be any number of bindings for a given portType. The grammar for a binding is as follows:
<wsdl:definitions .... > <wsdl:binding name="ncname" type="qname"> * <-- extensibility element (1) --> * <wsdl:operation name="ncname"> * <-- extensibility element (2) --> * <wsdl:input name="ncname"? > ? <-- extensibility element (3) --> </wsdl:input> <wsdl:output name="ncname"? > ? <-- extensibility element (4) --> * </wsdl:output> <wsdl:fault name="ncname"> * <-- extensibility element (5) --> * </wsdl:fault> </wsdl:operation> </wsdl:binding> </wsdl:definitions>
The name
attribute provides a unique name among all
bindings defined within in the enclosing WSDL document.
A binding references the portType that it binds using the
type
attribute. This QName value follows the linking
rules defined by WSDL.
Binding extensibility elements are used to specify the concrete grammar for the input (3), output (4), and fault messages (5). Per-operation binding information (2) as well as per-binding information (1) may also be specified.
An operation element within a binding specifies binding
information for the operation with the same name within the
binding's portType. Since operation names are not required to be
unique (for example, in the case of overloading of method names),
the name attribute in the operation binding element might not be
enough to uniquely identify an operation. In that case, the correct
operation should be identified by providing the name
attributes of the corresponding wsdl:input and wsdl:output
elements.
A binding MUST specify exactly one protocol.
A binding MUST NOT specify address information.
Editorial note: Editorial cleanup after finalizing ports | June 27, 2002 |
We expect some changes to occur here due to the need to support serviceTypes. We will be moving the description to be Infoset based after such changes have been done. |
A port defines an individual endpoint by specifying a single address for a binding.
<wsdl:definitions .... > <wsdl:service .... > * <wsdl:port name="ncname" binding="qname"> + <-- extensibility element (1) --> </wsdl:port> </wsdl:service> </wsdl:definitions>
The name
attribute provides a unique name among all
ports defined within in the enclosing WSDL document.
The binding
attribute (of type QName) refers to the
binding using the linking rules defined by WSDL.
Binding extensibility elements (1) are used to specify the address information for the port.
A port MUST NOT specify more than one address.
A port MUST NOT specify any binding information other than address information.
Issue (issue-consistent-port-endpoint-use): Use of "port" / "endpoint" needs to be clarified. Source: Kevin Liu Consistent terminology should be used across all the sections of the specification. |
Editorial note: Editorial cleanup after finalizing services | June 27, 2002 |
We expect some changes to occur here due to the need to support serviceTypes. We will be moving the description to be Infoset based after such changes have been done. |
A service groups a set of related ports together and which is defined as implementing a certain serviceType:
<wsdl:definitions .... > <wsdl:service name="ncname" serviceType="qname"> * <wsdl:port .... />* </wsdl:service> </wsdl:definitions>
The name
attribute provides a unique name among all
services defined within in the enclosing WSDL document. The
serviceType
attribute allows one to indicate the
serviceType of this service by referring to a previously defined
serviceType.
Ports within a service have the following relationship:
None of the ports communicate with each other (i.e. the output of one port is not the input of another).
If a service has several ports that share a port type, but employ different bindings or addresses, the ports are alternatives. Each port provides semantically equivalent behavior (within the transport and message format limitations imposed by each binding). This allows a consumer of a WSDL document to choose particular port(s) to communicate with based on some criteria (protocol, distance, etc.).
By examining it's ports, we can determine a service's port types. This allows a consumer of a WSDL document to determine if it wishes to communicate to a particular service based whether or not it supports several port types. This is useful if there is some implied relationship between the operations of the port types, and that the entire set of port types must be present in order to accomplish a particular task.
This section is non-normative.
This section uses the following informal grammar syntax to provide a preview of the overall syntactic structure of a WSDL 1.2 document:
The syntax appears as an XML instance, but the values indicate the data types instead of values.
Characters are appended to elements and attributes as follows: "?" (0 or 1), "*" (0 or more), "+" (1 or more).
Elements names ending in "…" (such as <element…/> or <element…>) indicate that elements/attributes irrelevant to the context are being omitted.
The XML namespace prefixes (defined above) are used to indicate the namespace of the element being defined.
<wsdl:definitions name="nmtoken"? targetNamespace="uri"> <import namespace="uri" location="uri"/> * <wsdl:documentation .... /> ? <wsdl:types> ? <wsdl:documentation .... /> ? <xsd:schema .... /> * </wsdl:types> <wsdl:message name="ncname"> * <wsdl:documentation .... /> ? <part name="ncname" element="qname"? type="qname"?/> * </wsdl:message> <wsdl:portType name="ncname"> * <wsdl:documentation .... /> ? <wsdl:operation name="ncname"> * <wsdl:documentation .... /> ? <wsdl:input message="qname"> ? <wsdl:documentation .... /> ? </wsdl:input> <wsdl:output message="qname"> ? <wsdl:documentation .... /> ? </wsdl:output> <wsdl:fault name="ncname" message="qname"> * <wsdl:documentation .... /> ? </wsdl:fault> </wsdl:operation> </wsdl:portType> <wsdl:serviceType name="ncname"> * <wsdl:portType name="qname"/> + </wsdl:serviceType> <wsdl:binding name="ncname" type="qname"> * <wsdl:documentation .... /> ? <-- binding details --> * <wsdl:operation name="ncname"> * <wsdl:documentation .... /> ? <-- binding details --> * <wsdl:input> ? <wsdl:documentation .... /> ? <-- binding details --> </wsdl:input> <wsdl:output> ? <wsdl:documentation .... /> ? <-- binding details --> * </wsdl:output> <wsdl:fault name="ncname"> * <wsdl:documentation .... /> ? <-- binding details --> * </wsdl:fault> </wsdl:operation> </wsdl:binding> <wsdl:service name="ncname" serviceType="qname"> * <wsdl:documentation .... /> ? <wsdl:port name="ncname" binding="qname"> * <wsdl:documentation .... /> ? <-- address details --> </wsdl:port> </wsdl:service> </wsdl:definitions>
WSDL 1.2 allows one to insert elements and attributes from other namespaces to any WSDL 1.2 defined element (see 4. Language Extensibility and Binding). Only specific locations where such elements are required to make WSDL 1.2 complete are indicated above. These are given by the indicated by the XML comments "<-- binding details -->" and "<-- address details -->".
WSDL has an open content model: every element in the "http://www.w3.org/2002/07/wsdl" namespace allows arbitrary extension attributes and extension elements as long as their names are fully qualified and they are defined in a namespace other than "http://www.w3.org/2002/07/wsdl".
More formally, any element information item with a [namespace name] of "http://www.w3.org/2002/07/wsdl" MAY have:
Zero or more attribute information items with:
A [namespace name] with a value other than "http://www.w3.org/2002/07/wsdl".
Zero or more children element information items with:
A [namespace name] with a value other than "http://www.w3.org/2002/07/wsdl".
An OPTIONAL attribute information item which has:
A [local name] of "required".
A [namespace name] of "http://www.w3.org/2002/07/wsdl".
The type of the required
attribute information
item is boolean in the namespace
"http://www.w3.org/2001/XMLSchema".
Omitting this attribute information item is defined as being semantically equivalent to including it with a value of "false" or "0".
An extension attribute or an extension element is said to be processed if a WSDL processor decides (through whatever means) that its parent (an element in the "http://www.w3.org/2002/07/wsdl" namespace) will be processed. Note that it is possible for WSDL processors to process only a subset of a given WSDL document. For instance, a tool may wish to focus on portTypes and operations only, and will consequently skip bindings.
If an extension element is processed and has a
wsdl:required
attribute information item with
a boolean value of "true", the WSDL processor MUST either agree to
fully abide by all the rules and semantics signaled by the
extension element's qualified name, or immediate cease processing
(fault). In particular, if the WSDL processor does not recognize
the qualified name of the extension element, it MUST fault. If it
does recognize the qualified name, and determines that the
extension in question is incompatible with any other aspect of the
document (including other required extensions), it MUST also
fault.
Extensibility elements are commonly used to specify some technology specific binding. They allow innovation in the area of network and message protocols without having to revise the base WSDL specification. WSDL recommends that specifications defining such protocols also define any necessary WSDL extensions used to describe those protocols or formats.
This document is the work of the W3C Web Services Description Working Group.
Members of the Working Group are (at the time of writing, and by alphabetical order): Adi Sakala (IONA Technologies), Allen Brookes (Rogue Wave Softwave), Arthur Ryman (IBM), Dale Moberg (Cyclone Commerce), Dan Kulp (IONA Technologies), Daniel Schutzer (Citigroup), Dave Solo (Citigroup), David Booth (W3C), Dietmar Gaertner (Software AG), Don Mullen (TIBCO Software), Don Wright (Lexmark), Glen Daniels (Macromedia), Igor Sedukhin (Computer Associates), Jacek Kopecky (Systinet), Jean-Jacques Moreau (Canon), Jeff Mischkinsky (Oracle Corporation), Jeffrey Schlimmer (Microsoft Corporation), Jerry Thrasher (Lexmark), Jochen Ruetschlin (DaimlerChrysler Research and Technology), Johan Pauhlsson (L'Échangeur), Jonathan Marsh (Chair, Microsoft Corporation), Joyce Yang (Oracle Corporation), Kevin Canyang Liu (SAP), Laurent De Teneuille (L'Échangeur), Mario Jeckle (DaimlerChrysler Research and Technology), Martin Gudgin (Microsoft Corporation), Michael Champion (Software AG), Michael Mahan (Nokia), Michael Mealling (Verisign), Mike Ballantyne (Electronic Data Systems), Mike Davoren (W. W. Grainger), Mike McHugh (W. W. Grainger), Pallavi Malu (Intel Corporation), Philippe Le Hégaret (W3C), Prasad Yendluri (webMethods, Inc.), Roberto Chinnici (Sun Microsystems), Sandeep Kumar (Cisco Systems), Sandra Swearingen (U.S. Department of Defense, U.S. Air Force), Sanjiva Weerawarana (IBM), Stefano Pogliani (Sun Microsystems), Steve Graham (Global Grid Forum), Steve Lind (AT&T), Steve Tuecke (Global Grid Forum), Tim Finin (University of Maryland), Tom Jordahl (Macromedia), Waqar Sadiq (Electronic Data Systems), William Stumbo (Xerox), William Vambenepe (Hewlett-Packard Company), Youenn Fablet (Canon)
Previous members were: Aaron Skonnard (DevelopMentor), Krishna Sankar (Cisco Systems)
The people who have contributed to discussions on www-ws-desc@w3.org are also gratefully acknowledged.
Date | Author | Description |
---|---|---|
20020703 | JJM | Replaced "MAY NOT" by "is allowed not to", suggestion from TimBL. |
20020702 | JJM | Uncommented entry for Requirements document (informative references). |
20020702 | JJM | Made targetnamespace non-optional in grammar to reflect the prose. Incorporated over comments from Kevin Liu. |
20020702 | JJM | Replaced a few remaining AII by corresponding entity. |
20020702 | JJM | Added link to schema for wsdl prefix. |
20020702 | JJM | Removed prefix for soap11. Removed indication that Part 2 contains binding for SOAP 1.1, since Part 2 currently only mentions SOAP 1.2. |
20020702 | JJM | Moved AII and EII entity definitions to entities.dtd, so can be share with Part 2. |
20020702 | SW | Changes to address Kevin Liu's comments: moved doc structure section to inside the syntax section and some minor cleanup. |
20020630 | SW | Added missing "type" property of a service and introduced new issue on port names. |
20020628 | SW | Mods to resolve issue-operation-overloading. |
20020627 | SW | Incorporated JJM's <import> wording and added ednotes. |
20020627 | RRC | Updated the extensibility section. |
20020627 | SW | Added serviceType issues (2) and resolved optional targetNamespace issue. |
20020627 | RRC | Changed "name scope" to "symbol space" in section 2 to align with the terminology used in XML Schema. |
20020627 | JJM | Changed a few remaining <emph> to either <att> or <el>, depending on context. |
20020627 | SW | Converted portType stuff to be infoset based and improved doc structure more. |
20020627 | SW | Converted message stuff to be infoset based and improved doc structure more. |
20020625 | SW | Mods to take into account JJM comments. |
20020624 | JJM | Fixed spec so markup validates. |
20020624 | JJM | Upgraded the stylesheet and DTD |
20020624 | JJM | Added sections for references and change log. |
20020624 | JJM | Removed Jeffrey from authors :-( Added Gudge :-) |
20020620 | SW | Started adding abstract model |
20020406 | SW | Created document from WSDL 1.1 |