WSDL 2.0 Language Versus Processor

David Booth, W3C Fellow / Hewlett-Packard
dbooth@w3.org
This document: http://www.w3.org/2004/02/dbooth-wsdl-lang-vs-proc.htm
Last modified $Date: 2004/02/26 16:19:57 $

Abstract

The problem of defining the WSDL 2.0 language is different from the problem of defining a conformant class of WSDL 2.0 processors.  There may be many kinds of processors, and the language specification should not try to dictate what they do.  Thus, the WSDL 2.0 language specification should not intermingle conformance constraints that pertain to WSDL processors.    However, both are important.  A clear and precise definition of the WSDL 2.0 language is important because it enhances interoperability between requester and provider agents, which both depend on a common interpretation of the WSDL document that governs their interaction.  And it is important to define a class of conformant WSDL 2.0 processors, because this can help improve the usability of WSDL, by permitting WSDL processor substitutability.  This document recommends that the WSDL 2.0 specification include a section defining one or more classes of conformant WSDL 2.0 processors.

Status

This document has no official status.  Opinions are those of the author.  Comments are invited.

Table of Contents

  Definitions
    Logical WSDL Document
    What Is Interoperability?
      Disagreement about choice of WSD/endpoint
      Disagreement about meaning of WSD/endpoint
      Disagreement about application semantics
    Requester and Provider Agent Interoperability ("Agent Interop")
    WSDL Processor Substitutability
  Analysis of Current WSDL 2.0 Specification Draft
    The Meaning of a WSD
    Optional Extensions and the WSDL 2.0 Language
    Optional Extensions and WSDL 2.0 Processors
    Alignment with WebArch Recommendations on Extensions

  To Do List

Definitions

Logical WSDL Document

By "logical WSDL document" I mean the infoset or set of components obtained from a WSDL document (i.e., after expanding any imports, includes, etc.). See http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0085.html for further explanation.

Synonyms: "Sentence in the WSDL language", "WSDL sentence", "Web service description (WSD)", "logical WSD".

What Is Interoperability?

Roughly speaking, interoperability between a requester and provider agent occurs when they agree on both the mechanics and semantics of their intended interaction.  Since the problem we wish to avoid is actually the lack of interoperability, it is helpful to instead define what that means.

Non-interoperability occurs either when the requester and provider entities do not agree on the mechanics of the interaction (such as the syntax, protocol or sequence of messages), or when they do not agree on the semantics of the interaction.  There are three ways this can occur:
  1. (Disagreement about choice of WSD/endpoint)  The requester and provider entities are unable to agree on a WSD and endpoint that is to govern their agent interaction. 

  2. (Disagreement about meaning of WSD/endpoint)  The requester and provider entities agree on the WSD and endpoint that will govern their agent interaction.  However, they disagree about the intended interaction that the WSD denotes. 

  3. (Disagreement about application semantics)  The requester and provider entities agree on the WSD and endpoint, and they agree on the intended interaction that the WSD denotes.  However, they disagree on the application semantics of the interaction. 
These three cases are discussed below.

Disagreement about choice of WSD/endpoint

If the requester and provider entities do not agree on the choice of WSD and endpoint that is to govern their agent interaction, then their corresponding agents will not be able to interact.   One way that this can occur is if one party wishes to use one WSD, but the other party (for whatever reason) does not like that WSD, perhaps because it uses features or extensions that the second party does not support.

This can be viewed as a problem for negotiation between the requester and provider entities, just as these parties must agree on the application semantics of the interaction.  (If the parties cannot agree on what WSD and endpoint they will use for their corresponding agent interaction, then their agents cannot sensibly interact anyway.)

The typical way for the requester and provider entities to negotiate what WSD/endpoint to use is for the provider entity to offer the entire WSD and application semantics on a take-it-or-leave-it basis, with the WSD containing a choice of one or more endpoints.  By offering such a WSD, the provider entity is implicitly agreeing to interact with the requester entity via any of the endpoints listed in that WSD.  And by selecting a particular endpoint from this WSD, the requester entity is implicitly agreeing to interact through this chosen endpoint according to the WSD and application semantics that were offered.

Although this is not the primary issue of interop that we wish to address, it is important, and WSDL processor substitutability can help to address it, as explained below.

Disagreement about meaning of WSD/endpoint

If the requester and provider entities agree on what WSD and endpoint to use, but they disagree about the intended interaction that this WSD/endpoint denotes, then their corresponding requester and provider agents still will not be able to interact (at least not correctly).

Since the purpose of the WSD is to partially define the expected interaction between the requester and provider agents, this is the main kind of interop issue that this document addresses.  This is the issue of Requester and Provider Agent Interoperability ("Agent Interop"), discussed below.

Disagreement about application semantics

Even if the requester and provider entities agree on the WSD and endpoint to use, and they agree on the intended interaction that the WSD denotes, they can still fail to interoperate because they have different understanding of the semantics of the interaction.  For example, one party may interpret "25.00" as US dollars and the other party may interpret it as Euros. 

The WSDL 2.0 specification can partially address this kind of interop problem by reinforcing the TAG's advice on namespace documents and recommending that namespace documents SHOULD (directly or indirectly) contain definitive material on the meaning and purpose of the vocabularies that they define.  There are at least three kinds of namespaces pertaining to application semantics that WSDL authors are likely to introduce:
The current draft of the WSDL 2.0 Core spec already includes the following recommendation for the wsdl:targetNamespace:

The target namespace represents an unambiguous name for the intended semantics of the WSDL Infoset. The targetNamespace URI SHOULD point to a human or machine processable document that directly or indirectly defines the semantics of the WSDL Infoset.

The current draft of the WSDL 2.0 Core spec does not include such advice for message syntax namespaces or extension namespaces.  Similar advice could be added for them.

Suggested change: Add a statement along the lines of

For any namespace that is used any message syntax, the namespace URI SHOULD point to a document that directly or indirectly defines the semantics of the vocabulary defined that namespace.

Requester and Provider Agent Interoperability ("Agent Interop")

Agent interoperability is when the requester and provider agree on the intended interaction denoted by the WSD and endpoint that they have chosen to use.

If an endpoint e in a logical WSDL 2.0 document wsd describes the intended interaction between a requester agent ra and a provider agent pa, then ra and pa are agent interoperable if they agree on the intended interaction through e that is denoted by wsd.

(Of course, to have full interoperability, they will still need to agree on the application-defined semantics of the interaction.)

WSDL Processor Substitutability

WSDL processor substitutability refers to the ability, relative to a given task, to substitute a different WSDL processor and obtain substantially equivalent behavior.  In other words, if a WSDL processor p1 is used as part of a larger process that manipulates WSDL documents, then another WSDL processor p2 would be substitutable if p2 could be plugged into that larger process in place of p1, and p2 would behave equivalently with respect to that larger process.

It is worth noting that WSDL processor substitutability is not required to achieve agent interop.  Agent interop is about agreeing on the meaning of a WSD, whereas WSDL processor substitutability is about what a WSDL processor does with a given WSD.  However, WSDL processor substitutability can help the requester and provider entities negotiate which WSD and endpoint to use, because different processors may handle different sets of extensions or optional features: If the provider entity restricts itself to a certain well-known set X of features/extensions, and the requester entity uses an X-conformant WSDL processor (i.e., one that implements those feature/extensions), then the requester entity knows that it will be able to use the WSD offered by the provider entity.   (Or conversely, the provider entity knows that any requester entity with an X-conformant WSDL processor will be able to use its WSD.)

Analysis of Current WSDL 2.0 Specification Draft

WSDL 2.0 Part 1 (Core Language)

Version analyzed: http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20.html?rev=1.9&content-type=text/html;%20charset=iso-8859-1
Latest version: http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20.html

Section 2.3.1.1.1 RPC Style (Rules for RPC Signature)

The paragraph (with bullet items) beginning "Furthermore, the following rules MAY BE used to map between a message and a signature of a remote procedure call" proposes conventions for a WSDL processor. 

Suggested change: These should either be clearly marked as non-normative hints or moved to a conformance section.

Section 3.1 Using W3C XML Schema Description Language

The first paragraph states: "All processors MUST support XML Schema type definitions."

Suggested change: Move to a conformance section.

Section 6.1.1 Mandatory extensions

The first paragraph was:
Extension elements can be marked as mandatory by annotating them with a wsdl:required attribute information item (see 6.1.2 requiredattribute information item) with a value of "true". Mandatory extensions are those that MUST be processed correctly by the WSDL processor. If a mandatory extension element is processed, 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 the WSDL processor recognizes 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 fault.

Suggested changes:
1. State @@somewhere@@:
The extension is identified by the qname consisting of its namespace URI and its element name.    The meaning of the extension SHOULD be defined (directly or indirectly) in a document that is available at its namespace URI.

2. Reword the existing paragraph to:
Extension elements can be marked as mandatory by annotating them with a wsdl:required attribute information item (see 6.1.2 requiredattribute information item) with a value of "true". A mandatory extension is an extension that may change the meaning of the WSDL 2.0 component to which it is attached, such that the meaning of that component is no longer defined by the WSDL 2.0 language specification. Instead, the meaning of a WSDL 2.0 component containing a mandatory extension is governed by the meaning of that extension. Thus, the definition of the component's meaning is delegated to the specification that defines the extension.

3. Add to a conformance section:
Mandatory extensions are those that MUST be processed correctly by the WSDL processor. If a mandatory extension element is processed, 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 the WSDL processor recognizes 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 fault.

Section 6.1 Element based extensibility

The fifth paragraph is currently:
An extension element is said to be processed if a WSDL processor decides (through whatever means) that its parent (an element information item in the "http://www.w3.org/@@@@/@@/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 interfaces and operations only, and will consequently skip bindings.

Suggested changes:
@@unfinished@@

Section 6.2 Attribute-based extensibility

@@Add something to say what they mean?@@

The Meaning of a WSD

Add something like:
This specification defines both the WSDL 2.0 language (i.e., the set of legal sentences in this language and their semantics) and a class of WSDL 2.0 conformant processors.  A Web service description (WSD) is the set or components represented by a legal sentence in the WSDL 2.0 language, as specified in this document.  Endpoints in the WSD describe alternate ways for a provider agent and a hypothetical requester agent to interact.  Each endpoint partially defines the expected interaction betweenthe provider agent and the hypothetical requester agent.  @@ Need to explain why it only "partially defines" the interaction. @@

@@ Need to describe the dependency chain of meaning: The meaning of the endpoint depends on its constituents.  However, the meaning of the wsdl:definitions does not depend on the meaning of its endpoints. (Thus a processor only needs to process the endpoint that it needs.)  @@

@@ Need to say that a WSD makes a set of assertions about the interaction between the parties in the MEP. (Usually two parties)  @@


Optional Extensions and the WSDL 2.0 Language

The key to understanding optional extensions is to remember that we are using the "open world" assumption: the WSD does not fully define the behavior of interacting requester and provider agents, but only partially defines it.  In other words, if we assume that the WSD represents a set of assertions about the behavior of an interacting requester and provider agent, then those agents could have additional behavior (or additional assertions about their behavior) that is not described by the WSD. 

As a simple example, the WSD may contain a message schema that defines the type of the <price> element to be a number.  Effectively, it makes an assertion like:

"Element <price> contains a number."

However, the schema itself does not indicate that this number should be interpreted as US dollars.  Additional documentation may further define the application-defined semantics of the interaction, in essence adding assertions like:

"The units for <price> are US dollars."

Similarly, even the message exchange pattern (MEP) only partially constrains the sequence of messages between the requester and provider agents.  The MEP for a request-response interaction, for example, asserts:

"If the requester agent sends the provider agent a message, then the provider agent will send a reply message."

However, if the parties agree, then the requester and provider agents could have additional interaction beyond what the MEP describes.  For example, the WS could have a special feature such that every time the WS receives a request, it immediately sends back a preliminary reply message indicating how soon the full response can be expected.  Then, when the full response is ready, it sends back the full response in a separate message.  In other words, both the request and response messages are still present as asserted by the MEP, but the preliminary reply is inserted into the request-response pattern as additional behavior.  This additional behavior

"If the requester agent sends the provider agent a message, then the provider agent will also send a preliminary message, prior to sending the reply message."

Of course, the requester and provider agents will only be able to interoperate on this basis if: (a) the requester agent discards any unexpected messages; or (b) the parties have previously agreed to this special behavior (which would be no more encumbering that agreeing on the application-specific semantics of the interaction, which the parties must do out-of-band anyway).

As another example, suppose you have a WS that will happily speak SOAP 1.2 over HTTP, but you want to let users know that it can also speak some custom whiz-bang protocol.  To do so, the WSD should contain a SOAP 1.2 over HTTP binding and endpoint.  This endpoint effectively makes the assertion:

"This WS knows how to speak SOAP 1.2 over HTTP."

In addition, the WSD should specify an optional extension to indicate that this WS can also speak the whiz-bang protocol.  The optional extension effectively adds the assertion:

"This WS knows how to speak the whiz-bang protocol."

Any requester agent that understands the optional extension can use the whiz-bang protocol if it chooses.  But it can also safely ignore it and use the standard SOAP 1.2 over HTTP binding and endpoint.  The key point is that the optional extension has not changed the semantics of the rest of the WSD.  It has merely provided additional assertions about the capabilities of the WS. 

An optional extension therefore may provide additional information about the expected interaction of the requester and provider agents.  An optional extension DOES NOT invalidate or change the meaning of the component to which it is attached. 

Optional Extensions and WSDL 2.0 Processors

In defining a class of conformant WSDL 2.0 processors, what should we say about optional extensions?  It depends on what kind of processor we wish to define.

In some cases, catching as many errors as possible may be desired.  For example, a WSDL processor that is attempting to verify the complete validity of the WSD and check it for possible mistakes should NOT ignore an optional extension that it does not recognize, since the unrecognized extension may represent a spelling error.

In other cases, non-essential errors may be problematic to report.  In those cases, it may be preferable to stipulate that the WSDL processor MUST IGNORE any optional extension that it does not recognize, since the processor could safely ignore it without misunderstanding the meaning of the rest of the WSD.

Alignment with WebArch Recommendations on Extensions

The above approach to optional extensions aligns with the WebArch document's advice on the use of "MUST IGNORE" and "MUST UNDERSTAND" extensibility mechanisms ( http://www.w3.org/TR/2003/WD-webarch-20031209/#pr-unknown-extension ), though I think it provides more explanation of how/why these approaches work than the WebArch document includes.  Essentially, if a statement in a language is viewed as making a set of assertions, AND the language makes the "open world" assumption, then a "MUST IGNORE" extension is viewed as introducing additional assertions that must not contradict or invalidate any existing assertions that are defined by the language.  On the other hand, "MUST UNDERSTAND" may change the existing semantics of the language and thus may invalidate existing assertions.  

To Do

  1. Amy's message on conformance, and Jacek's proposal:
    http://lists.w3.org/Archives/Public/www-ws-desc/2004Feb/0110.html
    http://lists.w3.org/Archives/Public/www-ws-desc/2004Feb/0121.html
  2. Need to add something about delegation of specification authority.  I.e., WSDL 2.0 spec defines the meaning of a WSDL 2.0 document, but for an extension, the authority for defining the meaning of a component(?) is delegated to the definition of that extension.
  3. Add something about dependency graph determining what is
  4. Finish searching in the WSDL spec for all mentions of:
    MUST, SHOULD, MAY, error, processor, warning
  5. Mention conformance testing: (1) testing requester and provider agents; (2) testing WSDL processors.
  6. Add GlenD's other example (if he reminds me what it was).  :)