W3C
Web Services Description Language (WSDL) Version 2.0 Part 0: Primer
W3C Working Draft 26 March 2007
This version:
http://www.w3.org/TR/2007/WD-wsdl20-primer-20070326
Latest version:
http://www.w3.org/TR/wsdl20-primer
Previous version:
http://www.w3.org/TR/2006/CR-wsdl20-primer-20060327
Editors:
David Booth, W3C Fellow / Hewlett-Packard
Canyang Kevin Liu, SAP Labs
This document is also available in these non-normative formats: PDF, PostScript
, XML, and plain text.
Copyright © 2007 W3C^® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability,
trademark and document use rules apply.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Abstract
This document is a companion to the WSDL 2.0 specification (Web Services
Description Language (WSDL) Version 2.0 Part 1: Core Language [WSDL 2.0 Core],
Web Services Description Language (WSDL) Version 2.0 Part 2: Adjuncts [WSDL 2.0
Adjuncts]). It is intended for readers who wish to have an easier, less
technical introduction to the main features of the language.
This primer is only intended to be a starting point toward use of WSDL 2.0, and
hence does not describe every feature of the language. Users are expected to
consult the WSDL 2.0 specification if they wish to make use of more
sophisticated features or techniques.
Finally, this primer is non-normative. Any specific questions of what WSDL 2.0
requires or forbids should be referred to the WSDL 2.0 specification.
Status of this Document
This section describes the status of this document at the time of its
publication. Other documents may supersede this document. A list of current W3C
publications and the latest revision of this technical report can be found in
the W3C technical reports index at http://www.w3.org/TR/.
This is a W3C Last Call Working of Web Services Description Language (WSDL)
Version 2.0 Part 0: Primer for review by W3C Members and other interested
parties. It has been produced by the Web Services Description Working Group,
which is part of the W3C Web Services Activity. This document is published to
give an opportunity to the community to review the new namespace for WSDL 2.0.
The Working Group plans to request to move to W3C Proposed Recommendation
shortly after the end of the Last Call period.
Individuals are invited to send feedback on this document to the public
public-ws-desc-comments@w3.org mailing list (public archive) through 15 April
2007.
The Working Group released a test suite along with an implementation report.
As a result of implementer and community feedback the Working Group made a
number of changes since the Candidate Recommendation publication. These changes
include:
• Removed sections associated with wsdl:feature and wsdl:property.
• Added guidance on simple operation dispatch when using the HTTP binding or
the SOAP binding with the SOAP Response MEP.
Issues about this document are recorded in the issues list maintained by the
Working Group. A diff-marked version against the previous version of this
document is available.
Publication as a Working Draft does not imply endorsement by the W3C
Membership. This is a draft document and may be updated, replaced or obsoleted
by other documents at any time. It is inappropriate to cite this document as
other than work in progress.
This document is governed by the 24 January 2002 CPP as amended by the W3C
Patent Policy Transition Procedure. W3C maintains a public list of any patent
disclosures made in connection with the deliverables of the group; that page
also includes instructions for disclosing a patent. An individual who has
actual knowledge of a patent which the individual believes contains Essential
Claim(s) must disclose the information in accordance with section 6 of the W3C
Patent Policy.
Table of Contents
1. Introduction
1.1 Prerequisites
1.2 Structure of this Primer
1.3 Use of URIs and IRIs
1.4 Notational Conventions
2. WSDL 2.0 Basics
2.1 Getting Started: The GreatH Hotel Example
2.1.1 Example Scenario: The GreatH Hotel Reservation Service
2.1.2 Defining a WSDL 2.0 Target Namespace
2.1.2.1 Explanation of Example
2.1.3 Defining Message Types
2.1.3.1 Explanation of Example
2.1.4 Defining an Interface
2.1.4.1 Explanation of Example
2.1.5 Defining a Binding
2.1.5.1 Explanation of Example
2.1.6 Defining a Service
2.1.6.1 Explanation of Example
2.1.7 Documenting the Service
2.1.7.1 Explanation of Example
2.2 WSDL 2.0 Infoset, Schema and Component Model
2.2.1 WSDL 2.0 Infoset
2.2.2 WSDL 2.0 Schema
2.2.2.1 WSDL 2.0 Element Ordering
2.2.3 WSDL 2.0 Component Model
2.2.3.1 WSDL 2.0 Import and Include
2.3 More on Message Types
2.3.1 Inlining XML Schema
2.3.2 Importing XML Schema
2.3.3 Summary of Import and Include Mechanisms
2.4 More on Interfaces
2.4.1 Interface Syntax
2.4.2 Interface Inheritance
2.4.3 Interface Faults
2.4.4 Interface Operations
2.4.4.1 Operation Attributes
2.4.4.2 Operation Message References
2.4.4.2.1 The messageLabel Attribute
2.4.4.2.2 The element Attribute
2.4.4.2.3 Multiple infault or outfault Elements
2.4.4.3 Understanding Message Exchange Patterns (MEPs)
2.5 More on Bindings
2.5.1 Syntax Summary for Bindings
2.5.2 Reusable Bindings
2.5.3 Binding Faults
2.5.4 Binding Operations
2.5.5 The SOAP Binding Extension
2.5.5.1 Explanation of Example
2.5.6 The HTTP Binding Extension
2.5.6.1 Explanation of Example
2.5.7 HTTP GET Versus POST: Which to Use?
3. Advanced Topics I: Importing Mechanisms
3.1 Importing WSDL
3.2 Importing Schemas
3.2.1 Schemas in Imported Documents
3.2.2 Multiple Inline Schemas in One Document
3.2.3 The schemaLocation Attribute
3.2.3.1 Using the id Attribute to Identify Inline Schemas
4. Advanced Topics II: Extensibility and Predefined Extensions
4.1 Extensibility
4.1.1 Optional Versus Required Extensions
4.2 Defining New MEPs
4.2.1 Confirmed Challenge
4.3 RPC Style
5. Advanced Topics III: Miscellaneous
5.1 Enabling Easy Message Dispatch
5.2 Web Service Versioning
5.2.1 Compatible Evolution
5.2.2 Big Bang
5.2.3 Evolving a Service
5.2.4 Combined Approaches
5.2.5 Examples of Versioning and Extending a Service
5.2.5.1 Additional Optional Elements Added in Content
5.2.5.2 Additional Optional Elements Added to a Header
5.2.5.3 Additional Mandatory Elements in Content
5.2.5.4 Additional Optional Operation Added to Interface
5.2.5.5 Additional Mandatory Operation Added to Interface
5.2.5.6 Indicating Incompatibility by Changing the Endpoint URI
5.2.5.7 Indicating Incompatibility by Changing the SOAP Action
5.2.5.8 Indicating Incompatibility by Changing the Element Content
5.3 Describing Web Service Messages That Refer to Other Web Services
5.3.1 The Reservation Details Web Service
5.3.2 The Reservation List Web Service
5.3.3 Reservation Details Web Service Using HTTP Transfer
5.3.4 Reservation List Web Service Using HTTP GET
5.4 Multiple Interfaces for the Same Service
5.5 Mapping to RDF and Semantic Web
5.5.1 RDF Representation of WSDL 2.0
5.6 Notes on URIs
5.6.1 XML Namespaces and Schema Locations
5.6.2 Relative URIs
5.6.3 Generating Temporary URIs
6. References
6.1 Normative References
6.2 Informative References
Appendix
A. Acknowledgements (Non-Normative)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Introduction
1.1 Prerequisites
This primer assumes that the reader has the following prerequisite knowledge:
• familiarity with XML (Extensible Markup Language (XML) 1.0 (Second Edition)
[XML 1.0], XML Information Set [XML Information Set]) and XML Namespaces (
Namespaces in XML [XML Namespaces]);
• some familiarity with XML Schema (XML Schema Part 1: Structures [XML
Schema: Structures] XML Schema Part 2: Datatypes [XML Schema: Datatypes]);
• familiarity with basic Web services concepts such as Web service, client,
and the purpose and function of a Web service description. (For an
explanation of basic Web services concepts, see Web Services Architecture [
WS Architecture] Section 1.4 and Web Services Glossary [WS Glossary]
glossary. However, note the Web Services Architecture document uses the
slightly more precise terms "requester agent" and "provider agent" instead
of the terms "client" and "Web service" used in this primer.)
No previous experience with WSDL is assumed.
1.2 Structure of this Primer
Section 2 starts with a hypothetical use case involving a hotel reservation
service. It proceeds step-by-step through the development of a simple example
WSDL 2.0 document that describes this service:
• The types element describes the kinds of messages that the service will
send and receive.
• The interface element describes what abstract functionality the Web service
provides.
• The binding element describes how to access the service.
• The service element describes where to access the service.
After presenting the example, it moves on to introduce the WSDL 2.0 infoset,
schema, and component model. Then it provides more detailed coverage on
defining message types, interfaces, bindings, and services.
Section 3 explains the WSDL 2.0 importing mechanisms in great details.
Section 4 talks about WSDL 2.0 extensibility and various predefined extensions.
Section 5 covers various topics that may fall outside the scope of WSDL 2.0,
but shall provide useful background and best practice guidances that may be
useful when authoring a WSDL 2.0 document or implementing the WSDL 2.0
specification.
1.3 Use of URIs and IRIs
The core specification of WSDL 2.0 supports Internationalized Resource
Identifiers or IRIs [IETF RFC 3987]. IRIs are a superset of URIs with added
support for internationalization. The URI syntax [IETF RFC 3986] only allows
the use of a small set of characters, including upper and lower case letters of
the English alphabet, European numerals and a few symbols. IRIs allow the use
of characters from a wider range of language scripts.
For simplicity, examples throughout this primer only use URIs. If you are
interested in learning more about the use of IRIs, you might care to read the
paper prepared by the W3C Internationalization Activity.
1.4 Notational Conventions
This document uses several XML namespaces, some of which are defined by
standards, and some are application-specific. Namespace names of the general
form "http://greath.example.com/..." represent application or context-dependent
URIs [IETF RFC 3986].Note also that the choice of any namespace prefix is
arbitrary and not semantically significant (see [XML Information Set]).
Following the convention for XML syntax summary in [WSDL 2.0 Core], this primer
uses an informal syntax to describe the XML grammar of a WSDL 2.0 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 "…" indicate that elements/attributes irrelevant
to the context are being omitted.
2. WSDL 2.0 Basics
2.1 Getting Started: The GreatH Hotel Example
This section introduces the basic concepts used in WSDL 2.0 through the
description of a hypothetical hotel reservation service. We start with a simple
scenario, and later add more requirements to illustrate how more advanced WSDL
2.0 features may be used.
2.1.1 Example Scenario: The GreatH Hotel Reservation Service
Hotel GreatH (a fictional hotel) is located in a remote island. It has been
relying on fax and phone to provide room reservations. Even though the
facilities and prices at GreatH are better than what its competitor offers,
GreatH notices that its competitor is getting more customers than GreatH. After
research, GreatH realizes that this is because the competitor offers a Web
service that permits travel agent reservation systems to reserve rooms directly
over the Internet. GreatH then hires us to build a reservation Web service with
the following functionality:
• CheckAvailability. To check availability, the client must specify a
check-in date, a check-out date, and room type. The Web service will return
a room rate (a floating point number in USD) if such a room is available,
or a zero room rate if not. If any input data is invalid, the service
should return an error. Thus, the service will accept a checkAvailability
message and return a checkAvailabilityResponse or invalidDataFault message.
• MakeReservation. To make a reservation, a client must provide a name,
address, and credit card information, and the service will return a
confirmation number if the reservation is successful. The service will
return an error message if the credit card number or any other data field
is invalid. Thus, the service will accept a makeReservation message and
return a makeReservationResponse or invalidCreditCardFault message.
We know that we will later need to build a complete system that supports
transactions and secured transmission, but initially we will implement only
minimal functionality. In fact, to simplify our first example, we will
implement only the CheckAvailability operation.
The next several sections proceed step-by-step through the process of
developing a WSDL 2.0 document that describes the desired Web service. However,
for those who can't wait to see a complete example, here is the WSDL 2.0
document that we'll be creating.
Example 2-1. WSDL 2.0 Document for the GreatH Web Service (Initial Example)
This document describes the GreatH Web service. Additional
application-level requirements for use of this service --
beyond what WSDL 2.0 is able to describe -- are available
at http://greath.example.com/2004/reservation-documentation.html
2.1.2 Defining a WSDL 2.0 Target Namespace
Before writing our WSDL 2.0 document, we need to decide on a WSDL 2.0 target
namespace URI for it. The WSDL 2.0 target namespace is analogous to an XML
Schema target namespace. Interface, binding and service names that we define in
our WSDL 2.0 document will be associated with the WSDL 2.0 target namespace,
and thus will be distinguishable from similar names in a different WSDL 2.0
target namespace. (This will become important if using WSDL 2.0's import or
interface inheritance mechanisms.)
The value of the WSDL 2.0 target namespace must be an absolute URI.
Furthermore, it should be dereferenceable to a WSDL 2.0 document that describes
the Web service that the WSDL 2.0 target namespace is used to describe. For
example, the GreatH owners should make the WSDL 2.0 document available from
this URI. (And if a WSDL 2.0 description is split into multiple documents, then
the WSDL 2.0 target namespace should resolve to a master document that includes
all the WSDL 2.0 documents needed for that service description.) However, there
is no absolute requirement for this URI to be dereferenceable, so a WSDL 2.0
processor must not depend on it being dereferenceable.
This recommendation may sound circular, but bear in mind that the client might
have obtained the WSDL 2.0 document from anywhere -- not necessarily an
authoritative source. But by dereferencing the WSDL 2.0 target namespace URI, a
user should be able to obtain an authoritative version. Since GreatH will be
the owner of the service, the WSDL 2.0 target namespace URI should refer to a
location on the GreatH Web site or otherwise within its control.
Once we have decided on a WSDL 2.0 target namespace URI, we can begin our WSDL
2.0 document as the following empty shell.
Example 2-2. An Initial Empty WSDL 2.0 Document
. . .
2.1.2.1 Explanation of Example
...
. . .
2.1.3.1 Explanation of Example
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"
We've added another namespace declaration. The ghns namespace prefix will
allow us (later, when defining an interface) to reference the XML Schema
target namespace that we define for our message types. Thus, the URI we
specify must be the same as the URI that we define as the target namespace
of our XML Schema types (below) -- not the target namespace of the WSDL 2.0
document itself.
targetNamespace="http://greath.example.com/2004/schemas/resSvc"
This is the XML Schema target namespace that we've created for use by the
GreatH reservation service. The checkAvailability,
checkAvailabilityResponse and invalidDataError element names will be
associated with this XML Schema target namespace.
checkAvailability, checkAvailabilityResponse and invalidDataError
These are the message types that we'll use. Note that these are defined to
be XML elements, as explained above.
Although we have defined several types, we have not yet indicated which ones
are to be used as message types for a Web service. We'll do that in the next
section.
2.1.4 Defining an Interface
WSDL 2.0 enables one to separate the description of a Web service's abstract
functionality from the concrete details of how and where that functionality is
offered. This separation facilitates different levels of reusability and
distribution of work in the lifecycle of a Web service and the WSDL 2.0
document that describes it.
A WSDL 2.0 interface defines the abstract interface of a Web service as a set
of abstract operations, each operation representing a simple interaction
between the client and the service. Each operation specifies the types of
messages that the service can send or receive as part of that operation. Each
operation also specifies a message exchange pattern that indicates the sequence
in which the associated messages are to be transmitted between the parties. For
example, the in-out pattern (see WSDL 2.0 Predefined Extensions [WSDL 2.0
Adjuncts] section 2.2.3 In-Out) indicates that if the client sends a message in
to the service, the service will either send a reply message back out to the
client (in the normal case) or it will send a fault message back to the client
(in the case of an error). We will explain more about message exchange patterns
in 2.4.4.3 Understanding Message Exchange Patterns (MEPs)
For the GreatH service, we will (initially) define an interface containing a
single operation, opCheckAvailability, using the checkAvailability and
checkAvailabilityResponse message types that we defined in the types section.
We'll use the in-out pattern for this operation, because this is the most
natural way to represent a simple request-response interaction. We could have
instead (for example) defined two separate operations using the in-only and
out-only patterns (see WSDL 2.0 Predefined Extensions [WSDL 2.0 Adjuncts]
section 2.2.1 In-Only and section 2.2.5 Out-Only), but that would just
complicate matters for the client, because we would then have to separately
indicate to the client developer that the two operations should be used
together as a request-response pair.
In addition to the normal input and output messages, we also need to specify
the fault message that we wish to use in the event of an error. WSDL 2.0
permits fault messages to be declared within the interface element in order to
facilitate reuse of faults across operations. If a fault occurs, it terminates
whatever message sequence was indicated by the message exchange pattern of the
operation.
Let's add these to our WSDL 2.0 document.
Example 2-4. GreatH Interface Definition
. . .
...
. . .
2.1.4.1 Explanation of Example
Interfaces are declared directly inside the description element. In this
example, we are declaring only one interface, but in general a WSDL 2.0
document may declare more than one interface. Thus, each interface must be
given a name that is unique within the set of interfaces defined in this
WSDL 2.0 target namespace. Interface names are tokens that must not contain
a space or colon (":").
The element attribute specifies the schema type of the fault message, as
previously defined in the types section.
This line indicates that this operation will not obligate the client in any
way, i.e., the client can safely invoke this operation without fear that it
may be incurring an obligation (such as agreeing to buy something). This is
further explained in 2.4.4 Interface Operations.
This specifies the message type for this input message, as defined
previously in the types section.
This associates an output fault with this operation. Faults are declared a
little differently than normal messages. The ref attribute refers to the
name of a previously defined fault in this interface -- not a message
schema type directly. Since message exchange patterns could in general
involve a sequence of several messages, a fault could potentially occur at
various points within the message sequence. Because one may wish to
associate a different fault with each permitted point in the sequence, the
messageLabel is used to indicate the desired point for this particular
fault. It does so indirectly by specifying the message that will either
trigger this fault or that this fault will replace, depending on the
pattern. (Some patterns use a message-triggers-fault rule; others use a
fault-replaces-message rule. See WSDL 2.0 Predefined Extensions [WSDL 2.0
Adjuncts] section 2.1.2 Message Triggers Fault and section 2.1.1 Fault
Replaces Message.)
Now that we've defined the abstract interface for the GreatH service, we're
ready to define a binding for it.
2.1.5 Defining a Binding
Although we have specified what abstract messages can be exchanged with the
GreatH Web service, we have not yet specified how those messages can be
exchanged. This is the purpose of a binding. A binding specifies concrete
message format and transmission protocol details for an interface, and must
supply such details for every operation and fault in the interface.
In the general case, binding details for each operation and fault are specified
using operation and fault elements inside a binding element, as shown in the
example below. However, in some cases it is possible to use defaulting rules to
supply the information. The WSDL 2.0 SOAP binding extension, for example,
defines some defaulting rules for operations. (See Web Services Description
Language (WSDL) Version 2.0 Part 2: Adjuncts [WSDL 2.0 Adjuncts], Default
Binding Rules.)
In order to accommodate new kinds of message formats and transmission
protocols, bindings are defined using extensions to the WSDL 2.0 language, via
WSDL 2.0's open content model. (See 4.1 Extensibility for more on
extensibility.) WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts] defines binding extensions
for SOAP 1.2 [SOAP 1.2 Part 1: Messaging Framework] and HTTP 1.1 [IETF RFC 2616
] as predefined extensions, so that SOAP 1.2 or HTTP 1.1 bindings can be easily
defined in WSDL 2.0 documents. However, other specifications could define new
binding extensions that could also be used to define bindings. (As with any
extension, other WSDL 2.0 processors would have to know about the new
constructs in order to make use of them.)
For the GreatH service, we will use SOAP 1.2 as our concrete message format and
HTTP as our underlying transmission protocol, as shown below.
Example 2-5. GreatH Binding Definition
. . .
. . .
...
. . .
2.1.5.1 Explanation of Example
xmlns:wsoap= "http://www.w3.org/ns/wsdl/soap"
We've added two more namespace declarations. This one is the namespace for
the SOAP 1.2 binding extension that is defined in WSDL 2.0 Part 3 [SOAP 1.2
Part 1: Messaging Framework]. Elements and attributes prefixed with wsoap:
are constructs defined there.
xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
This namespace is defined by the SOAP 1.2 specification itself. The SOAP
1.2 specification defines certain terms within this namespace to
unambiguously identify particular concepts. Thus, we will use the soap:
prefix when we need to refer to one of those terms.
This attribute is also specific to WSDL 2.0's SOAP binding extension. It
specifies the SOAP message exchange pattern (MEP) that will be used to
implement the abstract WSDL 2.0 message exchange pattern (in-out) that was
specified when the opCheckAvailability operation was defined.
When HTTP is used as the underlying transport protocol (as in this example)
the wsoap:mep attribute also controls whether GET or POST will be used as
the underlying HTTP method. In this case, the use of wsoap:mep="http://
www.w3.org/2003/05/soap/mep/soap-response" causes GET to be used by
default. See also 2.5.7 HTTP GET Versus POST: Which to Use?.
This attribute is also specific to WSDL 2.0's SOAP binding extension. This
specifies the SOAP 1.2 fault code that will cause this fault message to be
sent. If desired, a list of subcodes can also be specified using the
optional wsoap:subcodes attribute.
2.1.6 Defining a Service
Now that our binding has specified how messages will be transmitted, we are
ready to specify where the service can be accessed, by use of the service
element.
A WSDL 2.0 service specifies a single interface that the service will support,
and a list of endpoint locations where that service can be accessed. Each
endpoint must also reference a previously defined binding to indicate what
protocols and transmission formats are to be used at that endpoint. A service
is only permitted to have one interface. (See 5.4 Multiple Interfaces for the
Same Service for further discussion of this limitation.)
Here is a definition for our GreatH service.
Example 2-6. GreatH Service Definition
. . .
. . .
. . .
. . .
2.1.6.1 Explanation of Example
This specifies the name of the previously defined interface that these
service endpoints will support.
This specifies the physical address at which this service can be accessed
using the binding specified by the binding attribute.
That's it! Well, almost.
2.1.7 Documenting the Service
As we have seen, a WSDL 2.0 document is inherently only a partial description
of a service. Although it captures the basic mechanics of interacting with the
service -- the message types, transmission protocols, service location, etc. --
in general, additional documentation will need to explain other
application-level requirements for its use. For example, such documentation
should explain the purpose and use of the service, the meanings of all
messages, constraints on their use, and the sequence in which operations should
be invoked.
The documentation element allows the WSDL 2.0 author to include some
human-readable documentation inside a WSDL 2.0 document. It is also a
convenient place to reference any additional external documentation that a
client developer may need in order to use the service. It can appear in a
number of places in a WSDL 2.0 document (see 2.2.1 WSDL 2.0 Infoset), though in
this example we have only demonstrated its use at the beginning.
Example 2-7. Documenting the GreatH Service
This document describes the GreatH Web service. Additional
application-level requirements for use of this service --
beyond what WSDL 2.0 is able to describe -- are available
at http://greath.example.com/2004/reservation-documentation.html
. . .
2.1.7.1 Explanation of Example
This element is optional, but a good idea to include. It can contain
arbitrary mixed content.
at http://greath.example.com/2004/reservation-documentation.html
The most important thing to include is a pointer to any additional
documentation that a client developer would need in order to use the
service.
This completes our presentation of the GreatH example. In the following
sections, we will move on to look into more details of various aspects of WSDL
2.0 specification.
2.2 WSDL 2.0 Infoset, Schema and Component Model
In computer science theory, a language consists of a (possibly infinite) set of
sentences, and each sentence is a finite string of literal symbols or
characters. A language specification must therefore define the set of sentences
in that language, and, to be useful, it should also indicate the meaning of
each sentence. Indeed, this is the purpose of the WSDL 2.0 specification.
However, instead of defining WSDL 2.0 in terms of literal symbols or
characters, to avoid dependency on any particular character encoding, WSDL 2.0
is defined in terms of the XML Infoset [XML Information Set]. Specifically, a
WSDL 2.0 document consists of a description element information item (in the
XML Infoset) that conforms to the WSDL 2.0 specification. In other words, a
sentence in the WSDL 2.0 language is a description element information item
that obeys the additional constraints spelled out in the WSDL 2.0
specification.
Since an XML Infoset can be created from more than one physical document, a
WSDL 2.0 document does not necessarily correspond to a single physical
document: the word "document" is used figuratively, for convenience.
Furthermore, since WSDL 2.0 provides import and include mechanisms, a WSDL 2.0
document may reference other WSDL 2.0 documents to facilitate convenient
organization or reuse. In such cases, the meaning of the including or importing
document as a whole will depend (in part) on the meaning of the included or
imported document.
The XML Infoset uses terms like "element information item" and "attribute
information item". Unfortunately, those terms are rather lengthy to repeat
often. Thus, for convenience, this primer often uses the terms "element" and
"attribute" instead, as a shorthand. It should be understood, however, that
since WSDL 2.0 is based on the XML Infoset, we really mean "element information
item" and "attribute information item", respectively.
2.2.1 WSDL 2.0 Infoset
The following diagram gives an overview of the XML Infoset for a WSDL 2.0
document.
WSDL 2.0 Infoset Diagram
Figure 2-1. WSDL 2.0 Infoset Diagram
2.2.2 WSDL 2.0 Schema
The WSDL 2.0 specification supplies a normative WSDL 2.0 schema, defined in [
XML Schema: Structures], which can be used as an aid in validating WSDL 2.0
documents. We say "as an aid" here because WSDL 2.0 specification [WSDL 2.0
Core] often provides further constraints to the WSDL 2.0 schema. In addition to
being valid with the normative schema, a WSDL 2.0 document must also follow all
the constraints defined by the WSDL 2.0 specification.
2.2.2.1 WSDL 2.0 Element Ordering
This section gives an example of how WSDL 2.0 specification constrains the WSDL
2.0 schema about the ordering of top WSDL 2.0 elements.
Although the WSDL 2.0 schema does not indicate the required ordering of
elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 [WSDL 2.0 Core] section "
XML Representation of Description Component") clearly states a set of
constraints about how the child elements of the description element should be
ordered. Thus, the order of the WSDL 2.0 elements matters, even though the WSDL
2.0 schema does not capture this constraint.
The following is a pseudo-content model of description.
?
[ | ]*
?
[ | | ]*
In other words, the children elements of the description element should be
ordered as follows:
• An optional documentation comes first, if present.
• then comes zero or more elements from among the following, in any order:
□ include
□ import
□ extensions
• An optional types follows
• Zero or more elements from among the following, in any order:
□ interface
□ binding
□ service
□ extensions.
Note the term "extension" is used above as a convenient way to refer to
namespace-qualified extension elements. The namespace name of such extension
elements must not be"http://www.w3.org/ns/wsdl".
2.2.3 WSDL 2.0 Component Model
The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL
2.0 document, using the XML Infoset. However, the WSDL 2.0 language also
imposes many semantic constraints over and above structural conformance to this
XML Infoset. In order to precisely describe these constraints, and as an aid in
precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0
specification defines a component model as an additional layer of abstraction
above the XML Infoset. Constraints and meaning are defined in terms of this
component model, and the definition of each component includes a mapping that
specifies how values in the component model are derived from corresponding
items in the XML Infoset. The following diagram gives an overview of the WSDL
2.0 components and their containment hierarchy.
WSDL 2.0 Components Containment hierarchy
Figure 2-2. WSDL 2.0 Components Containment hierarchy
In general, the WSDL 2.0 component model parallels the structure of the
required XML Infoset illustrated above. For example, the Description, Interface
, Binding, Service and Endpoint components correspond to the description,
interface, binding, service, and endpoint element information items,
respectively. Since WSDL 2.0 relies heavily on the component model to convey
the meaning of the constructs in the WSDL 2.0 language, you can think of the
Description component as representing the meaning of the description element
information item, and hence, it represents the meaning of the WSDL 2.0 document
as a whole.
Furthermore, each of these components has properties whose values are (usually)
derived from the element and attribute information item children of those
element information items. For example, the Service component corresponds to
the service element information item, so the Service component has an
{endpoints} property whose value is a set of Endpoint components corresponding
to the endpoint element information item children of that service element
information item. (Whew!)
2.2.3.1 WSDL 2.0 Import and Include
The WSDL 2.0 component model is particularly helpful in defining the meaning of
import and include elements. The include element allows you to assemble the
contents of a given WSDL 2.0 namespace from several WSDL 2.0 documents that
define components for that namespace. The components defined by a given WSDL
2.0 document consist of those whose definitions are contained in the document
and those that are defined by any WSDL 2.0 documents that are included in it
via the include element. The effect of the include element is cumulative so
that if document A includes document B and document B includes document C, then
the components defined by document A consist of those whose definitions are
contained in documents A, B, and C.
In contrast, the import element does not define any components. Instead, the
import element declares that the components whose definitions are contained in
a WSDL 2.0 document for a given WSDL 2.0 namespace refer to components that
belong to a different WSDL 2.0 namespace. If a WSDL 2.0 document contains
definitions of components that refer to other namespaces, then those namespaces
must be declared via an import element. The import element also has an optional
location attribute that is a hint to the processor where the definitions of the
imported namespace can be found. However, the processor may find the
definitions by other means, for example, by using a catalog.
After processing any include elements and locating the components that belong
to any imported namespaces, the WSDL 2.0 component model for a WSDL 2.0
document will contain a set of components that belong to the document's WSDL
2.0 namespace and any imported namespaces. These components will refer to each
other, usually via QName references. A WSDL 2.0 document is invalid if any
component reference cannot be resolved, whether or not the referenced component
belongs to the same or a different namespace.
We will cover a lot more about how to use WSDL 2.0 import and include in 3.1
Importing WSDL
2.3 More on Message Types
Message types may be defined in various schema languages. In this primer, we
will only focus on the use of XML Schema [XML Schema: Structures] since it's
natively supported by WSDL 2.0. Message types defined in other languages may be
introduced into a WSDL 2.0 description via extensions, see the W3C notes [
Alternative Schema Languages Support] for more details.
The following is the XML syntax for the wsdl:types element:
*
[ |
|
other extension elements ]*
There are two ways to make XML Schema message definitions visible, or in other
words, available for reference by QName (see WSDL 2.0 Part 1 [WSDL 2.0 Core] "
QName Resolution") in a WSDL 2.0 document: inlining or importing. Inlining is
to put the schema definitions directly within an xs:schema element under types.
Importing is to have the schema defined in a separate document and then bring
it into the WSDL definition by using xs:import directly under types.
In the following sections, we will provide examples for the different
mechanisms.
2.3.1 Inlining XML Schema
We have already seen an example of using inlined schema definitions in section
2.1.3 Defining Message Types. When XML Schema is inlined directly in a WSDL 2.0
document, it uses the existing top-level xs:schema element defined by XML
Schema to do so, as though a schema file had been copied and pasted into the
types element. The schema components defined in the inlined schema are then
available to the containing WSDL 2.0 description for reference by QName. For
instance, in Example 2-1, the input message of the interface operation
"opCheckAvailability" is defined by the "ghns:checkAvailability" element in the
inlined schema.
2.3.2 Importing XML Schema
XML Schema components can be defined in separate schema files and be made
available to a WSDL2.0 description by using xs:import directly under types.
There are many cases where one would prefer having schema definitions in
separate schema files. One reason is the reusability of the schema definitions.
Inlined schema definitions are only available to the containing WSDL 2.0
description. Although WSDL 2.0 provides a wsdl:import mechanism for importing
other WSDL files, schema definitions inlined in an imported WSDL document are
NOT automatically made available to the importing WSDL 2.0 document, even
though other WSDL 2.0 components (such as Interfaces, Bindings, etc.) do become
available. Therefore, if one wishes to share schema definitions across several
WSDL 2.0 descriptions, these schema definitions should instead be placed in
separate XML Schema documents and imported into each WSDL 2.0 description using
xs:import directly under types.
Let's see an example. Assuming the message types in Example 2-3 are defined in
a separate schema file named "http://greath.example.com/2004/schemas/
resSvc.xsd" with a target namespace "http://greath.example.com/2004/schemas/
resSvc", the schema definition can then be brought into the WSDL 2.0
description using xs:import. Note that only components in the imported
namespace "http://greath.example.com/2004/schemas/resSvc" are available for
reference in the WSDL 2.0 document.
Example 2-8. xs:imported Message Definitions that Are Visible to the Containing
WSDL 2.0 Description
. . .
. . .
It's important to note that xs:import used directly under wsdl:types has been
given a different visibility than xs:import used inside an inlined schema. An
inlined schema may use native XML schema xs:import to bring in external schema
definitions that are in different namespaces; However, though this is the
schema importing mechanism recommended for WSDL 1.1 in WS-I Basic Profile,
according to XML Schema specification, such enclosed message definitions are
only visible to the importing schema (in this case, the inlined schema). They
are not visible to the containing WSDL 2.0 description.
If we change Example 2-8 to use XML Schema's native xs:import element in an
inlined schema, the schema components defined in the namespace http://
greath.example.com/2004/schemas/resSvc are not available to our example WSDL
2.0 definition any more.
Example 2-9. xs:imported Message Definitions in Inlined Schema Are Not Visible
to the Containing WSDL 2.0 Description
. . .
. . .
Of course, an inlined XML schema may also use XML Schema's native xs:include
element to refer to schemas defined in separate files when the included schema
has no namespace or has the same namespace as the including schema. In this
case, according to XML Schema, the included schema components become a part of
the including schema as though they had been copied and pasted into the
including schema. Hence, the included schema components are also available to
the containing WSDL 2.0 description for reference by QName.
The following example has the same effect as Example 2-3:
Example 2-10. xs:included Message Definitions in Inlined Schema Are Visible to
the Containing WSDL 2.0 Description
. . .
. . .
2.3.3 Summary of Import and Include Mechanisms
So far we have briefly covered both WSDL import and include and schema import
and include. The following table summarizes the similarities and differences
between the WSDL 2.0 and XML Schema include and import mechanisms. We will talk
a lot more about importing mechanisms in 3.1 Importing WSDL and 3.2 Importing
Schemas
Table 2-1. Summary of Import and Include Mechanisms
┌────────────┬─────────┬────────────────────────┬─────────────────────────────┐
│ Mechanism │ Object │ Meaning │ Visibility of Schema │
│ │ │ │ Components │
├────────────┼─────────┼────────────────────────┼─────────────────────────────┤
│ │ │Declare that WSDL 2.0 │XML Schema Components in the │
│ │WSDL 2.0 │components refer to WSDL│imported Description │
│wsdl:import │Namespace│2.0 components from a │component are NOT visible to │
│ │ │DIFFERENT │the containing description. │
│ │ │targetNamespace. │ │
├────────────┼─────────┼────────────────────────┼─────────────────────────────┤
│ │ │ │XML Schema components in the │
│ │ │Merge Interface, Binding│included Description │
│ │WSDL 2.0 │and Service components │component's {element │
│wsdl:include│Document │from another WSDL 2.0 │declarations} and {type │
│ │ │document that has the │definitions} properties are │
│ │ │SAME targetNamespace. │visible to the containing │
│ │ │ │description. │
├────────────┼─────────┼────────────────────────┼─────────────────────────────┤
│ │ │Declare that XML Schema │XML Schema components in the │
│wsdl:types/ │XML │components refer to XML │imported namespace are │
│xs:import │Schema │Schema components from a│visible to the containing │
│ │Namespace│DIFFERENT │description. │
│ │ │targetNamespace. │ │
├────────────┼─────────┼────────────────────────┼─────────────────────────────┤
│ │ │Declare that XML Schema │XML Schema components in the │
│wsdl:types/ │XML │components refer to XML │imported namespace are NOT │
│xs:schema/ │Schema │Schema components from a│visible to the containing │
│xs:import │Namespace│DIFFERENT │description. │
│ │ │targetNamespace. │ │
├────────────┼─────────┼────────────────────────┼─────────────────────────────┤
│ │ │Merge XML Schema │XML Schema components in the │
│wsdl:types/ │XML │components from another │included document are visible│
│xs:schema/ │Schema │XML Schema document that│to the containing │
│xs:include │Document │has the SAME or NO │description. │
│ │ │targetNamespace. │ │
└────────────┴─────────┴────────────────────────┴─────────────────────────────┘
2.4 More on Interfaces
We previously mentioned that a WSDL 2.0 interface is basically a set of
operations. However, there are some additional capabilities that we have not
yet covered. First, let's review the syntax for the interface element.
2.4.1 Interface Syntax
Below is the XML syntax summary of the interface element, simplified by
omitting optional elements:
. . .
*
*
*
*
*
*
*
. . .
The interface element has two optional attributes: styleDefault and extends.
The styleDefault attribute can be used to define a default value for the style
attributes of all operations under this interface (see WSDL 2.0 Part 1 "
styleDefault attribute information item"). The extends attribute is for
inheritance, and is explained next.
2.4.2 Interface Inheritance
The optional extends attribute allows an interface to extend or inherit from
one or more other interfaces. In such cases the interface contains the
operations of the interfaces it extends, along with any operations it defines
directly. Two things about extending interfaces deserve some attention.
First, an inheritance loop (or infinite recursion) is prohibited: the
interfaces that a given interface extends must NOT themselves extend that
interface either directly or indirectly.
Second, we must explain what happens when operations from two different
interfaces have the same target namespace and operation name. There are two
cases: either the component models of the operations are the same, or they are
different. If the component models are the same (per the component comparison
algorithm defined in WSDL 2.0 Part 1 [WSDL 2.0 Core] " Equivalence of
Components ") then they are considered to be the same operation, i.e., they are
collapsed into a single operation, and the fact that they were included more
than once is not considered an error. (For operations, component equivalence
basically means that the two operations have the same set of attributes and
descendants.) In the second case, if two operations have the same name in the
same WSDL 2.0 target namespace but are not equivalent, then it is an error. For
the above reason, it is considered good practice to ensure that all operations
within the same target namespace are named uniquely.
Finally, since faults can also be defined as children of the interface element
(as described in the following sections), the same name-collision rules apply
to those constructs.
Let's say the GreatH hotel wants to maintain a standard message log operation
for all received messages. It wants this operation to be reusable across the
whole reservation system, so each service will send out, for potential use of a
logging service, the content of each message it receives together with a
timestamp and the originator of the message. One way to meet such requirement
is to define the log operation in an interface which can be inherited by other
interfaces. Assuming a messageLog element is already defined in the ghns
namespace with the required content, the inheritance use case is illustrated in
the following example. As a result of the inheritance, the reservationInterface
now contains two operations: opCheckAvailability and opLogMessage
Example 2-11. Interface Inheritance
...
...
Now let's have a look at the element children of interface, beginning with
fault.
2.4.3 Interface Faults
The fault element is used to declare faults that may occur during execution of
operations of an interface. They are declared directly under interface, and
referenced from operations where they apply, in order to permit reuse across
multiple operations.
Faults are very similar to messages and can be viewed as a special kind of
message. Both faults and messages may carry a payload that is normally
described by an element declaration. However, WSDL 2.0 treats faults and
messages slightly differently. The messages of an operation directly refer to
their element declaration, however the faults of an operation indirectly refer
to their element declaration via a fault element that is defined on the
interface.
The reason for defining faults at the interface level is to allow their reuse
across multiple operations. This design is especially beneficial when bindings
are defined, since in binding extensions like SOAP there is additional
information that is associated with faults. In the case of SOAP, faults have
codes and subcodes in addition to a payload. By defining faults at the
interface level, common codes and subcodes can be associated with them, thereby
ensuring consistency across all operations that use the faults
The fault element has a required name attribute that must be unique within the
parent interface element, and permits it to be referenced from operation
declarations. The optional element attribute can be used to indicate a schema
for the content or payload of the fault message. Its value should be the QName
of a global element defined in the types section. Please note that when other
type systems are used to define the schema for a fault message, additional
attributes may need to be defined via WSDL 2.0's attribute extension mechanism
to allow the schema to be associated with the fault.
2.4.4 Interface Operations
As shown earlier, the operation element is used to indicate an operation
supported by the containing interface. It associates message schemas with a
message exchange pattern (MEP), in order to abstractly describe a simple
interaction with a Web service.
2.4.4.1 Operation Attributes
An operation has two required attributes and one optional attribute:
• A required name attribute, as seen already, which must be unique within the
interface.
• A required pattern attribute whose value must be an absolute URI that
identifies the desired MEP for the operation. MEPs are further explained in
2.4.4.3 Understanding Message Exchange Patterns (MEPs).
• An optional style attribute whose value is a list of absolute URIs. Each
URI identifies a certain set of rules that were followed in defining this
operation. It is an error if a particular style is indicated, but the
associated rules are not followed. [WSDL 2.0 Adjuncts] defines a set of
styles, including
□ RPC Style. The RPC style is selected when the style is assigned the
value http://www.w3.org/ns/wsdl/rpc. It places restrictions for Remote
Procedure Call-types of interactions.
□ IRI Style. The IRI style is selected when the style is assigned the
value http://www.w3.org/ns/wsdl/style/iri. It places restrictions on
message definitions so they may be serialized into something like HTTP
URL encoded.
□ The Multipart style. The Multipart style is selected when the style is
assigned the value http://www.w3.org/ns/wsdl/style/multipart. In the
HTTP binding, for XForms clients, a message must be defined following
the Multipart style and serialized as "Multipart/form-data".
You can find more details of these WSDL 2.0 predefined styles. Section 4.3
RPC Style provides an example of using the RPC style. [WSDL 2.0 Adjuncts]
provides examples for the IRI style and Multipart style.
Note that [WSDL 2.0 Adjuncts] provides a predefined extension for indicating
operation safety. The wsdlx:safe global attribute whose value is a boolean can
be used with an operation to indicate whether the operation is asserted to be
"safe" (as defined in Section 3.5 of the Web Architecture [Web Architecture])
for clients to invoke. In essence, a safe operation is any operation that does
not give the client any new obligations. For example, an operation that permits
the client to check prices on products typically would not obligate the client
to buy those products, and thus would be safe, whereas an operation for
purchasing products would obligate the client to pay for the products that were
ordered, and thus would not be safe.
An operation should be marked safe (by using the wsdlx:safe and by setting its
value to "true") if it meets the criteria for a safe interaction defined in
Section 3.5 of the Web Architecture [Web Architecture], because this permits
the infrastructure to perform efficiency optimizations, such as pre-fetch,
re-fetch and caching.
The default value of this attribute is false. If it is false or is not set,
then no assertion is made about the safety of the operation; thus the operation
may or may not be safe.
2.4.4.2 Operation Message References
An operation will also have input, output,infault, and/or outfault element
children that specify the ordinary and fault message types to be used by that
operation. The MEP specified by the pattern attribute determines which of these
elements should be included, since each MEP has placeholders for the message
types involved in its pattern.
Since operations were already discussed in 2.1.4 Defining an Interface, this
section will merely comment on additional capabilities that were not previously
explained.
2.4.4.2.1 The messageLabel Attribute
The messageLabel attribute of the input and output elements is optional. It is
not necessary to explicitly set the messageLabel when the MEP in use is one of
the eight MEPs predefined in WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts] and it has
only one message with a given direction.
2.4.4.2.2 The element Attribute
The element attribute of the input and output elements is used to specify the
message content schema (aka payload schema) when the content model is defined
using XML Schema. As we have seen already, it can specify the QName of an
element schema that was defined in the types section. However, alternatively it
can specify one of the following tokens:
#any
The message content is any single element.
#none
There is no message content, i.e., the message payload is empty.
#other
The message content is described by a non-XML type system. Extension
attributes specify the type.
The element attribute is also optional. If it is not specified, then the
message content is described by a non-XML type system.
Note that there are situations that the information conveyed in the element
attribute is not sufficient for a service implementation to uniquely identify
an incoming message and dispatch it to an appropriate operation. In such
situations, additional means may be required to aid identifying an incoming
message. See 5.1 Enabling Easy Message Dispatch for more detail.
2.4.4.2.3 Multiple infault or outfault Elements
When infault and/or outfault occur multiple times within an operation, they
define alternative fault messages.
2.4.4.3 Understanding Message Exchange Patterns (MEPs)
WSDL 2.0 message exchange patterns (MEPs) are used to define the sequence and
cardinality of the abstract messages in an operation. By design, WSDL 2.0 MEPs
are abstract. First of all, they abstract out specific message types. MEPs
identify placeholders for messages, and placeholders are associated with
specific message types when an operation is defined, which includes specifying
which MEP to use for that operation. Secondly, unless explicitly stated
otherwise, MEPs also abstract out binding-specific information like timing
between messages, whether the pattern is synchronous or asynchronous, and
whether the messages are sent over a single or multiple channels.
It's worth pointing out that WSDL 2.0 MEPs do not exhaustively describe the set
of messages that may be exchanged between a service and other nodes. By some
prior agreement, another node and/or the service may send other messages (to
each other or to other nodes) that are not described by the MEP. For instance,
even though an MEP may define a single message sent from a service to one other
node, a service defined by that MEP may multicast that message to other nodes.
To maximize reuse, WSDL 2.0 message exchange patterns identify a minimal
contract between other parties and Web Services, and contain only information
that is relevant to both the Web service and the client that engages that
service.
A total of eight MEPs are defined in [WSDL 2.0 Adjuncts]. These MEPs should
cover the most common use cases, but they are not meant to be an exhaustive
list of MEPs that can ever be used by operations. More MEPs can be defined for
particular application needs by interested parties. (See 2.4.4.3 Understanding
Message Exchange Patterns (MEPs) )
For the eight MEPs defined by WSDL 2.0, some of them are variations of others
based on how faults may be generated. For example, the In-Only pattern ("http:/
/www.w3.org/ns/wsdl/in-only") consists of exactly one message received by a
service from some other node. No fault can be generated. As a variation of
In-Only, Robust In-Only pattern ("http://www.w3.org/ns/wsdl/robust-in-only")
also consists of exactly one message received by a service, but in this case
faults can be triggered by the message and must be delivered to the originator
of the message. If there is no path to this node, the fault must be discarded.
For details about the common fault generation models used by the eight WSDL 2.0
MEPs, see [WSDL 2.0 Adjuncts].
Depending on how the first message in the MEP is initiated, the eight WSDL 2.0
MEPs may be grouped into two groups: in-bound MEPs, for which the service
receives the first message in the exchange, and out-bound MEPs, for which the
service sends out the first message in the exchange. (Such grouping is not
provided in the WSDL 2.0 specification and is presented here only for the
purpose of easy reference in this primer).
A frequently asked question about out-bound MEPs is how a service knows where
to send the message. Services using out-bound MEPs are typically part of large
scale integration systems that rely on mapping and routing facilities. In such
systems, out-bound MEPs are useful for specifying the functionality of a
service abstractly, including its requirements for potential customers, while
endpoint address information can be provided at deployment or runtime by the
underlying integration infrastructure. For example, the GreatH hotel
reservation system may require that every time a customer interacts with the
system to check availability, data about the customer must be logged by a CRM
system. At design time, it's unknown which particular CRM system would be used
together with the reservation system. To address this requirement, we may
change the "reservationInterface" in Example 2-1 to include an out-bound
logInquiry operation. This logInquiry operation advertises to potential service
clients that customer data will be made available by the reservation service at
run time. When the reservation service is deployed to GreatH's IT landscape,
appropriate configuration time and run time infrastructure will help determine
which CRM system will get the customer data and log it appropriately. It's
worth noting that in addition to being used by a CRM system for customer
management purpose, the same data may also be used by a system performance
analysis tool for different purpose. Providing an out-bound operation in the
reservation service enables loose coupling and so improves the overall GreatH
IT landscape's flexibility and scalability.
Example 2-12. Use of outbound MEPs
...
...
...
Although the eight MEPs defined in WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts] are
intended to cover most use cases, WSDL 2.0 has designed this set to be
extensible. This is why MEPs are identified by URIs rather than a fixed set of
tokens.
For more about defining new MEPs, see 4.2 Defining New MEPs.
2.5 More on Bindings
Bindings are used to supply protocol and encoding details that specify how
messages are to be sent or received. Each binding element uses a particular
binding extension to specify such information. WSDL 2.0 Part 2 [WSDL 2.0
Adjuncts] defines several binding extensions that are typically used. However,
binding extensions that are not defined in WSDL 2.0 Part 2 can also be used,
provided that client and service toolkits support them.
Binding information must be supplied for every operation in the interface that
is used in an endpoint. However, if the desired binding extension provides
suitable defaulting rules, then the information will only need to be explicitly
supplied at the interface level, and the defaulting rules will implicitly
propagate the information to the operations of the interface. For example, see
the Default Binding Rules of SOAP binding extension in WSDL 2.0 Part 2 [WSDL
2.0 Adjuncts].
2.5.1 Syntax Summary for Bindings
Since bindings are specified using extensions to the WSDL 2.0 language (i.e.,
binding extensions are not in the WSDL 2.0 namespace), the XML for expressing a
binding will consist of a mixture of elements and attributes from WSDL 2.0
namespace and from the binding extension's namespace, using WSDL 2.0's open
content model.
Here is a syntax summary for binding, simplified by omitting optional
documentation elements. Bear in mind that this syntax summary only shows the
elements and attributes defined within the WSDL 2.0 namespace. When an actual
binding is defined, elements and attributes from the namespace of the desired
binding extension will also be intermingled as required by that particular
binding extension.
. . .
*
*
*
*
*
*
*
. . .
The binding syntax parallels the syntax of interface: each interface construct
has a binding counterpart. Despite this syntactic similarity, they are indeed
different constructs, since they are in different symbol spaces and are
designed for different purposes.
2.5.2 Reusable Bindings
A binding can either be reusable (applicable to any interface) or non-reusable
(specified for a particular interface). Non-reusable bindings may be specified
at the granularity of the interface (assuming the binding extension provides
suitable defaulting rules), or on a per-operation basis if needed. A
non-reusable binding was demonstrated in 2.1.5 Defining a Binding.
To define a reusable binding, the binding element simply omits the interface
attribute and omits specifying any operation-specific and fault-specific
binding details. Endpoints can later refer to a reusable binding in the same
manner as for a non-reusable binding. Thus, a reusable binding becomes
associated with a particular interface when it is referenced from an endpoint,
because an endpoint is part of a service, and the service specifies a
particular interface that it implements. Since a reusable binding does not
specify an interface, reusable bindings cannot specify operation-specific
details. Therefore, reusable bindings can only be defined using binding
extensions that have suitable defaulting rules, such that the binding
information only needs to be explicitly supplied at the interface level.
2.5.3 Binding Faults
A binding fault associates a concrete message format with an abstract fault of
an interface. It describes how faults that occur within a message exchange of
an operation will be formatted, since the fault does not occur by itself.
Rather, a fault occurs as part of a message exchange specified by an interface
operation and its binding counterpart, the binding operation.
A binding fault has one required ref attribute which is a reference, by QName,
to an interface fault. It identifies the abstract interface fault for which
binding information is being specified. Be aware that the value of ref
attribute of all the faults under a binding must be unique. That is, one cannot
define multiple bindings for the same interface fault within a given binding.
2.5.4 Binding Operations
A binding operation describes a concrete binding of an interface operation to a
concrete message format. An interface operation is uniquely identified by the
WSDL 2.0 target namespace of the interface and the name of the operation within
that interface, via the required ref attribute of binding operation. As with
faults, for each operation within a binding, the value of the ref attribute
must be unique.
2.5.5 The SOAP Binding Extension
The WSDL 2.0 SOAP Binding Extension (see WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts])
was primarily designed to support the features of SOAP 1.2 [SOAP 1.2 Part 1:
Messaging Framework]. However, for backwards compatibility, it also provides
some support for SOAP 1.1 [SOAP 1.1].
An example using the WSDL 2.0 SOAP binding extension was already presented in
2.1.5 Defining a Binding, but some additional points are worth mentioning:
• Because the same binding extension is used for both SOAP 1.2 and SOAP 1.1,
a wsoap:version attribute is provided to allow you to indicate which
version of SOAP you want. If this attribute is not specified, it defaults
to SOAP 1.2.
• The WSDL 2.0 SOAP binding extension defines a set of default rules, so that
bindings can be specified at the interface level or at the operation level
(or both), with the operation level taking precedence. However, it does not
define default binding rules for faults. Thus, if a given interface defines
any faults, then corresponding binding information must be explicitly
provided for each such fault.
• If HTTP is used as the underlying protocol, then the binding can (and
should) control whether each operation will use HTTP GET or POST. (See
2.5.7 HTTP GET Versus POST: Which to Use?.)
Here is an example that illustrates both a SOAP 1.2 binding (as seen before)
and a SOAP 1.1 binding.
Example 2-13. SOAP 1.2 and SOAP 1.1 Bindings
....
2.5.5.1 Explanation of Example
Most lines in this example is the same as previously explained in 2.1.5
Defining a Binding, so we'll only point out lines that are demonstrating
something new for SOAP 1.1 binding.
This is the namespace for terms defined within the SOAP 1.1 specification [
SOAP 1.1].
This line specifies that HTTP should be used as the underlying transmission
protocol. See also 2.5.7 HTTP GET Versus POST: Which to Use?.
Note that wsoap:mep is not applicable to SOAP 1.1 binding.
This line specifies the SOAP 1.1 fault code that will be used in
transmitting invalidDataFault.
2.5.6 The HTTP Binding Extension
In addition to the WSDL 2.0 SOAP binding extension described above, WSDL 2.0
Part 2 [WSDL 2.0 Adjuncts] defines a binding extension for HTTP 1.1 [IETF RFC
2616] and HTTPS [IETF RFC 2818], so that these protocols can be used natively
to send and receive messages, without first encoding them in SOAP.
The HTTP binding extension provides many features to control:
• Which HTTP operation will be used. (GET, PUT, POST, DELETE, and other HTTP
operations are supported.)
• Input, output and fault serialization
• Transfer codings
• Authentication requirements
• Cookies
• HTTP over TLS (https)
As with the WSDL 2.0 SOAP binding extension, the HTTP binding extension also
provides defaulting rules to permit binding information to be specified at the
interface level and used by default for each operation in the affected
interface, however, defaulting rules are not provided for binding faults.
Here is an example of using the HTTP binding extension to check hotel room
availability at GreatH.
Example 2-14. HTTP Binding Extension
. . .
. . .
2.5.6.1 Explanation of Example
Most of this example is the same as previously explained in 2.1.5 Defining a
Binding, so we'll only point out lines that are demonstrating something new for
HTTP binding extension.
This defines the namespace prefix for elements and attributes defined by
the WSDL 2.0 HTTP binding extension.
The default method for operations in this interface will be HTTP GET.
whttp:location="{checkInDate}" >
The whttp:location attribute specifies a pattern for serializing input
message instance data into the path component of the request URI. The
default binding rules for HTTP specify that the default input serialization
for GET is application/x-www-form-urlencoded. Curly braces are used to
specify the name of a schema type in the input message schema, which
determines what input instance data will be inserted into the path
component of the request URI. The curly brace-enclosed name will be
replaced with instance data in constructing the path component. Remaining
input instance data (not specified by whttp:location) will either be
serialized into the query string portion of the URI or into the message
body, as follows: if a "/" is appended to a curly brace-enclosed type name,
then any remaining input message instance data will be serialized into the
message body. Otherwise it will be serialized into query parameters.
Thus, in this example, each of the elements in the tCheckAvailability type
will be serialized into the query parameters. A sample resulting URI would
therefore be http://greath.example.com/2004/checkAvailability/5-5-5?
checkOutDate=6-6-5&roomType=foo.
Here is an alternate example that appends "/" to the type name in order to
serialize the remaining instance data into the message body:
Example 2-15. Serializing a Subset of Types in the Path
. . .
. . .
This would instead serialize to a request URI such as: http://
greath.example.com/2004/checkAvailability/bycheckInDate/5-5-5. The rest of the
message content would go to the HTTP message body.
2.5.7 HTTP GET Versus POST: Which to Use?
When a binding using HTTP is specified for an operation, the WSDL 2.0 author
must decide which HTTP method is appropriate to use -- usually a choice between
GET and POST. In the context of the Web as a whole (rather than specifically
Web services), the W3C Technical Architecture Group (TAG) has addressed the
question of when it is appropriate to use GET, versus when to use POST, in a
finding entitled URIs, Addressability, and the use of HTTP GET and POST ([W3C
TAG Finding: Use of HTTP GET]). From the abstract:
". . . designers should adopt [GET] for safe operations such as simple queries.
POST is appropriate for other types of applications where a user request has
the potential to change the state of the resource (or of related resources).
The finding explains how to choose between HTTP GET and POST for an application
taking into account architectural, security, and practical considerations."
Recall that the concept of a safe operation was discussed in 2.4.4.1 Operation
Attributes. (Briefly, a safe operation is one that does not cause the invoker
to incur new obligations.) Although the wsdlx:safe attribute of an interface
operation indicates that the abstract operation is safe, it does not
automatically cause GET to be used at the HTTP level when the binding is
specified. The choice of GET or POST is determined at the binding level:
• If the WSDL 2.0 SOAP binding extension is used (2.5.5 The SOAP Binding
Extension), with HTTP as the underlying transport protocol, then GET may be
specified by setting:
wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP/"
on the binding element (to indicate the use of HTTP as the underlying
protocol); and
wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"
on the binding operation element, which causes GET to be used by
default.
• If the WSDL 2.0 HTTP binding extension is used directly (2.5.6 The HTTP
Binding Extension), GET may be specified by setting either:
whttp:methodDefault="GET"
on the binding element; or
whttp:method="GET"
on the binding operation element, which overrides whttp:methodDefault
if set on the binding element; or
wsdlx:safe="true"
on the bound interface operation . When the above two items are not
explicitly set, and when the bound interface operation is marked safe,
the HTTP Binding will by default set the method to GET.
For example, in the GreatH interface definition shown in Example 2-4, the
wsdlx:safe attribute is set to "true". The HTTP binding definition in Example
2-14 may take advantage of that and be simplified as below and still have the
http method set to GET by default:
Example 2-16. Safety and HTTP Binding
3. Advanced Topics I: Importing Mechanisms
3.1 Importing WSDL
In some circumstances WSDL authors may want to split up a Web service
description into two or more documents. For example, if a description is
getting long or is being developed by several authors, then it is convenient to
divide it into several parts. Another very important case is when you expect
parts of the description to be reused in several contexts. Clearly it is
undesirable to cut and paste sections of one document into another, since that
is error prone and leads to maintenance problems. More importantly, you may
need to reuse components that belong to a wsdl:targetNamespace that is
different than that of the document you are writing, in which case the rules of
WSDL 2.0 prevent you from simply cutting and pasting them into your document.
To solve these problems, WSDL 2.0 provides two mechanisms for modularizing Web
service description documents: import and include. This section discusses the
import mechanism and describes some typical cases where it may be used.
The import mechanism lets one refer to the definitions of Web service
components that belong to other namespaces. To illustrate this, consider the
GreatH hotel reservation service. Suppose that the reservation service uses a
standard credit card validation service that is provided by a financial
services company. Furthermore, suppose that companies in the financial services
industry decided that it would be useful to report errors in credit card
validation using a common set of faults, and have defined these faults in the
following Web service description:
Example 3-1. Standard Credit Card Validation Faults (credit-card-faults.wsdl)
This document describes standard faults for use
by Web services that process credit cards.
Thrown when the credit card has been cancelled.
Thrown when the credit card has expired.
Thrown when the credit card number is invalid.
This fault will occur if the wrong credit card type is specified.
Thrown when the expiration date is invalid.
This example defines an interface, creditCardFaults, that contains four faults,
cancelledCreditCard, expiredCreditCard, invalidCreditCardNumber, and
invalidExpirationDate. These components belong to the namespace http://
finance.example.com/CreditCards/wsdl.
Because these faults are defined in a different wsdl:targetNamespace than the
one used by the GreatH Web service description, import must be used to make
them available within the GreatH Web service description, as shown in the
following example:
Example 3-2. Using the Standard Credit Card Validation Faults
(use-credit-card-faults.wsdl)
Description: The definition of the reservation Web service of
GreatH hotel. Author: Joe Somebody Date: 05/17/2004
. . .
. . .
The hotel reservation service declares that it is using components from another
namespace via the import> element. The import element has a required namespace
attribute that specifies the other namespace, and an optional location
attribute that gives the processor a hint where to find the description of the
other namespace. The reservation interface extends the creditCardFault
interface from the other namespace in order to make the faults available in the
reservation interface. Finally, the makeReservation operation refers to the
standard faults in its outfault elements.
Another typical situation for using imports is to define a standard interface
that is to be implemented by many services. For example, suppose the hotel
industry decided that it was useful to have a standard interface for making
reservations. This interface would belong to some industry association
namespace, e.g. http://hotels.example.com/reservations/wsdl. Each hotel that
implemented the standard reservation service would define a service in its own
namespace, e.g. http://greath.example.com/2004/wsdl/resSvc. The description of
each service would import the http://hotels.example.com/reservations/wsdl
namespace and refer to the standard reservation interface in it.
3.2 Importing Schemas
WSDL 2.0 documents may contain one or more XML schemas defined within the
wsdl:types element. This section illustrates the correct way to refer to these
schemas, both from within the same document and from other documents.
3.2.1 Schemas in Imported Documents
In this example, we consider some GreatH Hotel Web services that retrieve and
update reservation details. The retrieval Web service is defined in the
retrieveDetails.wsdl WSDL 2.0 document, along with a schema for the message
format. The updating Web service is defined in the updateDetails.wsdl WSDL 2.0
document which imports the first document and refers to both WSDL 2.0 and
schema definitions contained in the imported document.
Example 3-3 shows the definition of the retrieval Web service in the http://
greath.example.com/2004/services/retrieveDetails namespace. This WSDL 2.0
document also contains an inline schema that describes the reservation detail
in the http://greath.example.com/2004/schemas/reservationDetails namespace.
This schema is visible to the retrieveDetailsInterface interface definition
which refers to it in the retrieve operation's output message.
Example 3-3. The Retrieve Reservation Details Web Service: retrieveDetails.wsdl
This document describes the GreatH Retrieve Reservation Details
Web service.
Example 3-4 shows the definition of the updating Web service in the http://
greath.example.com/2004/services/updateDetails namespace. The
updateDetailsInterface interface extends the retrieveDetailsInterface
interface. However, the retrieveDetailsInterface belongs to the http://
greath.example.com/2004/services/retrieveDetails namespace, so
updateDetails.wsdl must import retrieveDetails.wsdl to make that namespace
visible.
The updateDetailsInterface interface also uses the reservationDetails element
definition that is contained in the inline schema of the imported
retrieveDetails.wsdl document. However, this schema is not automatically
visible within the updateDetails.wsdl document. To make it visible, the
updateDetails.wsdl document must import the namespace of the inline schema
within the types element using the XML schema import element.
In this example, the schemaLocation attribute of the import element has been
omitted. The schemaLocation attribute is a hint to the WSDL 2.0 processor that
tells it where to look for the imported schema namespace. However, the WSDL 2.0
processor has already processed the retrieveDetails.wsdl document which
contains the imported namespace in an inline schema so it should not need any
hints. However, this behavior depends on the implementation of the processor
and so cannot be relied on.
Although the WSDL 2.0 document may validly omit the schemaLocation attribute,
it is a best practice to either provide a reliable value for it or move the
inline schema into a separate document, say reservationDetails.xsd, and
directly import it in the types element of both retrieveDetails.wsdl and
updateDetails.wsdl. In general, schemas that are expected to be referenced from
more than one WSDL 2.0 document should be defined in a separate schema document
rather than be inlined.
Example 3-4. The Update Reservation Details Web Service: updateDetails.wsdl
This document describes the GreatH Update Reservation Details
Web service.
3.2.2 Multiple Inline Schemas in One Document
A WSDL 2.0 document may define multiple inline schemas in its types element.
The two or more schemas may have the same target namespace provided that they
do not define the same elements or types. It is an error to define the same
element or type more than once, even if the definitions are identical.
Each namespace of an inline schema becomes visible to the Web service
definitions. However, the namespaces are not automatically visible to the other
inline schemas. Each inline schema must explicitly import any other namespace
it references. The schemaLocation attribute is not required in this case since
the WSDL 2.0 processor knows the location of each schema by virtue of having
processed the enclosing WSDL 2.0 document.
To illustrate this, consider Example 3-5 which contains two inline schemas. The
http://greath.example.com/2004/schemas/reservationItems namespace contains some
elements for items that appear in the reservation details. The http://
greath.example.com/2004/schemas/reservationDetails namespace contains the
reservationDetails element which refers to the item elements. The schema for
the http://greath.example.com/2004/schemas/reservationDetails namespace
contains an import element that imports the http://greath.example.com/2004/
schemas/reservationItems namespace. No schemaLocation attribute is required for
this import since the schema is defined inline in the importing document.
Example 3-5. Multiple Inline Schemas: retrieveItems.wsdl
This document describes the GreatH Retrieve Reservation Details
Web service.
3.2.3 The schemaLocation Attribute
In the preceding examples, schemas were defined inline in WSDL 2.0 documents.
This section discusses the correct way to specify a schemaLocation attribute on
a schema import element to provide a processor with a hint for locating these
schemas.
Example 3-4 shows how one WSDL 2.0 document imports a schema defined in
another, i.e. Example 3-3. Similarly, Example 3-5 shows how one schema in a
WSDL 2.0 document imports another schema defined in the same document. In both
of these examples, the schemaLocation attribute was omitted since the WSDL 2.0
processor was assumed to know how to locate the imported schemas because they
were part of the WSDL 2.0 documents being processed. The schemaLocation
attribute can be used to give the processor a URI reference that explicitly
locates the schemas. A URI reference is a URI plus an optional fragment
identifier that indicates part of the resource. For schemas, the fragment
should identify the schema element. The simplest way to accomplish this is to
use the id attribute, however XPointer (see [XPointer Framework]) can also be
used.
3.2.3.1 Using the id Attribute to Identify Inline Schemas
Example 3-6 shows the use of the id attribute. Both of the inline schemas have
id attributes. The id of the http://greath.example.com/2004/schemas/
reservationItems schema is items and the id of the http://greath.example.com/
2004/schemas/reservationDetails schema is details. The import element in the
http://greath.example.com/2004/schemas/reservationDetails schema uses the id of
the http://greath.example.com/2004/schemas/reservationItems schema in the
schemaLocation attribute, i.e. #items.
Example 3-6. Using Ids in Inline Schemas: schemaIds.wsdl
This document describes the GreatH Retrieve Reservation Details
Web service.
4. Advanced Topics II: Extensibility and Predefined Extensions
4.1 Extensibility
WSDL 2.0 provides an open content model, which allows XML elements and
attributes from other (non-WSDL 2.0) XML namespaces to be interspersed in a
WSDL 2.0 document. The qualified name (complete with namespace URI) of the
extension element or attribute acts as an unambiguous name for the semantics of
that extension.
The namespace URI of the extension element should be dereferenceable to a
document that describes the semantics of that extension. As of this writing,
there is no generally accepted standard for what kind of document that should
be. However, the W3C TAG has been discussing the issue (see TAG issue
namespaceDocument-8) and is likely to provide guidance at some point.
4.1.1 Optional Versus Required Extensions
Extensions can either be required or optional.
An optional extension is one that the client may either engage or ignore,
entirely at its discretion, and is signaled by wsdl:required="false" or the
absence of the wsdl:required attribute (because it defaults to false). Thus, a
WSDL 2.0 processor, acting on behalf of the client, that encounters an unknown
optional extension can safely ignore it and continue to process the WSDL 2.0
document. However, it is important to stress that optional extensions are only
optional to the client -- not the service. A service must support all optional
and required extensions that it advertises in its WSDL 2.0 document.
A required extension is one that must be supported and engaged by the client in
order for the interaction to proceed properly, and is signaled by wsdl:required
="true". If a WSDL 2.0 processor, acting on behalf of the client, encounters a
required extension that it does not recognize or does not support, then it
cannot safely continue to process the WSDL 2.0 document. In most practical
cases, this is likely to mean that the processor will require manual
intervention to deal with the extension. For example, a client developer might
manually provide an implementation for the required extension to the WSDL 2.0
processor.
4.2 Defining New MEPs
As we mentioned in 2.4.4.3 Understanding Message Exchange Patterns (MEPs), even
though the 8 MEPs defined by WSDL 2.0 are intended to cover most of the common
use cases, there are situations that require new MEPs to be defined. In this
section, we will explain how new MEPs can be defined to address special
business requirements.
Following the wild success of its reservation service, GreatH discovered that
it could radically increase tourist interest by supplying information on
weather conditions, both to travel agents and to the general touring public.
This produced a challenge for the service implementers: how could this
information be supplied to interested parties without requiring knowledge of
web service technology specifically, and of computers generally? At issue was
the desire to provide asynchronous updates to unsophisticated customers without
incurring onerous overheads for technical support.
The solution adopted was to create a standard mailing list, and to make
available a small cross-platform web service client (actually, a subscriber)
that could be installed on any computer with POP or IMAP access to a mailbox.
The mailbox, once signed up for the mailing list, could either be processed as
"dedicated" (to the GreatH weather service; travel agents did this) or as
"general purpose" (in which case the application would only examine those
emails that contained Subject headers associated with the service). This
required development of a binding to email, which is out of scope for this
example, but the resulting WSDL 2.0 was otherwise quite straightforward.
Note: the email binding in use here supports publish/subscribe, by supporting
the robust-out-only MEP as well as the client/server style in-out used for
subscribing and unsubscribing. Details of this binding would require a document
as long as the primer, so play along.
Example 4-1. Weather Notification Service (Initial)
. . .
. . .
Note: in the example, the messageLabels of all input and output elements have
been elided, as they are not necessary to disambiguate (but note that the order
of input and output elements is not significant).
Unfortunately, the service was soon highjacked for the purpose of annoyment.
Repeatedly, hotels in less salubrious climes, and the victims of various
natural climactic disasters (hurricanes, tornadoes) found themselves signed up
to receive material full of incomprehensible pointy brackets. They complained
to GreatH, who complained to their service designers.
Applying public key infrastructure to solving the problem was immediately
rejected as too complex and too heavyweight. Analysis showed that the problem
was simply to verify that the address requesting information actually wanted
that information. Consequently, a new message exchange pattern was defined.
4.2.1 Confirmed Challenge
This pattern consists of two or more messages in order as follows:
1. A message:
□ indicated by a Message Label component whose message label is "Request"
and direction is "in"
□ received from some node N1
2. A message:
□ indicated by a Message Label component whose message label is
"Challenge" and direction is "out"
□ sent to some node N2 (which may be the same node as N1)
3. An optional message:
□ indicated by a Message Label component whose message label is
"Confirmation" and direction is "in"
□ received from node N2
4. An optional message:
□ indicated by a Message Label component whose message label is
"Response" and direction is "out"
□ sent to node N2
This pattern uses the rule Message Triggers Fault.
An operation using this message exchange pattern has a pattern property with
the value "http://www.example.com/webservices/meps/confirmed-challenge".
Once the MEP had been defined (and the email binding specification
appropriately modified to indicate that this was a supported MEP), the service
was redefined and redeployed. Only the changed operations are shown in the
excerpt below.
Example 4-2. Weather Notification Service (Revised)
. . .
. . .
. . .
Note: in the second example, the input and output examples are not in the
sequence in which they occur in the pattern; this illustrates that the sequence
is not significant. Note, however, that for this pattern, the messageLabel
attribute is required on every input and output element.
4.3 RPC Style
Section 2.4.4.1 Operation Attributes mentioned that the (optional) style
attribute of an interface operation is used to indicate that the operation
conforms to a particular pre-defined operation style, or set of constraints.
Actually, if desired the style attribute can hold a list of URIs, indicating
that the operation simultaneously conforms to multiple styles.
Operation styles are named using URIs, in order to be unambiguous while still
permitted new styles to be defined without requiring updates to the WSDL 2.0
language. WSDL 2.0 Part 2 [WSDL 2.0 Adjuncts] defines three such operation
styles; one of these is the RPC Style (RPC Style).
The RPC Style is designed to facilitate programming language bindings to WSDL
2.0 constructs. It allows a WSDL 2.0 interface operation to be easily mapped to
a method or function signature, such as a method signature in Java(TM) or C#.
RPC Style is restricted to operations that use the In-Out or In-Only MEPs (see
2.4.4.3 Understanding Message Exchange Patterns (MEPs)).
A WSDL 2.0 document makes use of the RPC Style in an interface operation by
first defining the operation in conformance with all of the RPC Style rules,
and then setting that operation's style attribute to include the URI that
identifies the RPC Style, thus asserting that the operation does indeed conform
to the RPC Style. These rules permit the input and output message schemas to
map conveniently to inputs and outputs of a method signature. Roughly, input
elements map to input p