Web Service Description Requirements

Editors copy $Date: 2002/2/12 18:05:31 $ @@ @@ 2002

This version:
Latest version:
Previous versions:
@@@, @@@


This document describes the Web Service Description Working Group's requirements for the Web Service Description specification.

Status of this Document

This document is an editors' copy that has no official standing.

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This is the first W3C Working Draft of the Web Service Description requirements document. It is a chartered deliverable of the Web Service Description Working Group (WG), which is part of the Web Service Activity. The Working has agreed to publish this document, although this document does not necessarily represent consensus within the Working Group about Web Service Description requirements.

Comments on this document should be sent to ws-desc-comments@w3.org (public archive[1]). It is inappropriate to send discussion emails to this address.

Discussion of this document takes place on the public ws-desc@w3.org mailing list[2] per the email communication rules in the Web Service Description Working Group Charter[3].

This is a public W3C Working Draft. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". A list of all W3C technical reports can be found at http://www.w3.org/TR/.

Table of Contents

1 Notations
2 Relationship to WG Charter
3 Requirements on Requirements
4 Requirements
    4.1 General Requirements
    4.2 Simplicity
    4.3 Interface Description
    4.4 Description of Interactions with a Service
    4.5 Messages and Types
    4.6 Service Types
    4.7 Binding Description
    4.8 Mapping to the Semantic Web
    4.9 Reusability Requirements
    4.10 Extensibility Requirements
    4.11 Versioning Requirements
5 Requirements from other W3C WGs
    5.1 XML Protocol Requirements
    5.2 XForms Requirements
    5.3 RDF Requirements
    5.4 P3P Requirements
6 References

1 Notations

The following terminology and typographical conventions have been used in this document.

Each requirement and scenario has a three digit number with a prefix indicating the status as follows:

  1. A "DRnnn" notation indicates a requirement that the WG is actively considering (has not reached rough consensus within the WG).

  2. An "Rnnn" notation indicates a requirement that the WG is not actively considering at present (has reached rough consensus within the WG).

The numbers used to identify requirements are arbitrary and does not imply any ordering or significance.

The document includes several verbatim quotes from the Web Service Description WG Charter[3] which provide context for the requirements. The quoted text is emphasized and prefixed with "Charter".

2 Relationship to WG Charter

The Web Service Description WG Charter[3] has two sections describing what is in-scope and what is out-of-scope of the problem space defined for the WG. The WG considers all the requirements in section 4 to be in-scope per the Charter.

Reviewers and readers should be familiar with the Web Service Description WG Charter[3] because it provides the critical context for the requirements and any discussion of them.

3 Requirements on Requirements



4 Requirements

4.1 General Requirements


Charter: The language developed by the Working Group must not preclude any programming model, nor assume any particular mode of communication between peers.


JS: Coordinate with W3C XML Activity and XML Coordination Group.


JS: Use available XML technologies wherever possible.


JS: Describe constructs using the XML Infoset model.


KL: Correct errors/inconsistencies in WSDL1.1


KL: Better Specification for Document Name and Linking. WSDL1.1 section 2.1.1 is over simple. More detailed specification should be provided to define how the import mechanism works, especially how it's related to the import and include mechanism defined in the XML Schema specification.


KL: Best Practices and Conformance Test. Although a few examples are given in WSDL 1.1 specification, the examples are not sufficiently explained in the text, and no corresponding wired message examples are available for different binding definitions. To help clearer interpretation of the specification, more consistent and detailed examples should be provided. In addition, a technical report associated with the WSDL specification should be dedicated to provide: · Use cases which illustrate typical usage scenarios of WSDL · Best practices · Conformance test suite


KL: Up-to-date XML Schema Support. In all WSDL 1.1 examples, the October 2000 version of the XML schema is used: http://www.w3.org/2000/10/XMLSchema. We understand that the 10/2000 schema was the most up-to-dated schema available at the time WSDL1.1 was released. However, in future versions of WSDL specification, the W3C recommendation version of the XML schema should be used. The recommendation was released in May 2001: http://www.w3.org/2001/XMLSchema.


KL: Easy Interaction with Upper layers in the web services stack. Additional technologies will be required in the future to complete the web services architecture. As one of the fundamental layers of the web services stack, though WSDL should not depend on any other layers, one of the design goals of WSDL should be easy interaction with upper layers, such as services composition layers.


KL: Editorial Improvements. Consistent terminology should be used across all the sections of the specification. As one example, the usage of the terms "port" and "endpoint" is confusing to many readers. Though it states that "port" is "a single endpoint defined as a combination of a binding and a network address", the specification uses "port" and "endpoint" interchangeably in many places. Some diagrams that explain the structure of core WSDL elements and their relationship will help reduce misinterpretations.

4.2 Simplicity


Charter: Focus must be put on simplicity, modularity and decentralization.


Charter: The language proposed must support the kind of extensibility actually seen on the Web: disparity of document formats and protocols used to communicate, mixing of XML vocabularies using XML namespaces, development of solutions in a distributed environment without a central authority, etc. In particular, it must support distributed extensibility.


Charter: Simplicity is a key element in making distributed systems easy to understand, implement, maintain, and evolve. Although simplicity can only be measured in relative terms, the Working Group must ensure that the complexity of any solution produced is comparable to that of other current and widespread Web solutions.


Charter: Another important aspect of simplicity is ease of deployment. The Working Group will look at various ways of deploying the Web services descriptions in a manner that is compatible with the existing Web infrastructure.


Charter: Must support an open content model (charter says: "must support distributed extensibility" and "will look into extending interface descriptions in a decentralized fashion").


JS: Simple to understand and implement correctly; comparable to other widespread Web solutions.


JS: Specification shall be as lightweight as possible, keeping parts that are mandatory to a minimum.


JS: Optional parts of the specification should be orthogonal to each other allowing non-conflicting configurations to be implemented.


YF: Must facilitate the creation of simple applications (fast and easy writing for simple apps).


YF: Must be possible to compare easily two WSDL web services

4.3 Interface Description


Charter: The Working Group will define a description language expressed in XML. The description language must describe the messages available via the interface, accepted and generated by the Web service.


Charter: The language must also describe the error messages generated, if any.


Charter: The data exchanged is usually typed and structured. This increases interoperability by having applications agreeing on semantics and also provides some level of error detection. It is expected that developers will want to use different mechanisms for describing data types and structures, depending on the purpose of the Web service. The Working Group should allow different mechanisms, and must define one based on XML Schema.


Charter: The Working Group will also take into account the encoding work going on in the XML Protocol Working Group.


Charter: The Working Group will make sure that SOAP Version 1.2's extensibility mechanism can be expressed.


Charter: The description language designed will be used both by applications in order to automatically communicate between each other as well as by programmers developing Web services themselves. The language should therefore provide, in addition to the raw XML definition of the interface, human-readable comment capabilities to allow both applications and developers to make use of them.


Charter: Developers are likely to want to extend the functionality of an existing Web service. The Working Group will look into extending interface descriptions in a decentralized fashion, i.e. without priori agreement with the original interface designers.


Charter: Must describe SOAP 1.2 messages, including header, body, encoding, fault, RPC, actor (charter says: "must describe messages available via interface", "must describe error messages" and "make sure SOAP 1.2 extensibility mechanism can be expressed").


Charter: Must describe SOAP 1.2 header and body's content type (charter says: "must define [a mechanism for describing data types and structures] based on XML Schema" and "take into account ending work going on in XML Protocol").


Charter: Must describe SOAP 1.2 RPC parameters types (ibid.).


Charter: Must support SOAP 1.2 intermediairies (charter says: "make sure SOAP 1.2 extensibility mechanism can be expressed")


WS: In a lot of cases, it is important for the server to expose some service wide properties/attributes. These properties/attributes have the service-level scope and could be used to describe either some Qos parameters or some application specific characteristics. As an example, a service may want to expose an attribute which describes the version number of the service. Hence, a web service description language should be able to model service level attributes/properties.


YF: Must support abstract interfaces.


YF: Must support interfaces derived from abstract interfaces.


KL: Distinction between Interface definition and Implementation definition. A description of a web service can be logically divided into three parts: Data type definition, Service Interface definition and Service Implementation definition. The data type definition can be viewed as part of the Service Interface Definition. Analogous to defining an abstract interface in a programming language and having many concrete implementations, a service interface definition can be instantiated and referenced by multiple service implementers. WSDL 1.1 specification implies such a division by providing the mechanism for dividing a service definition into multiple WSDL documents. WSDL1.1 Section 2.1.2, Authoring Style, shows an example of separating a complete service definition into three documents: data type definition, abstract definitions and specific service bindings. However, this distinction is not clear and reference to each unit is very difficult. To facilitate easier allocation of responsibilities among different organizations (such as standard bodies and service providers) or among different teams within an organization (such as teams related to the different stages of a service's lifecycle: design time/development time, configuration time and run time), a better distinction between Interface definition and Implementation definition should be made in the specification. The final WSDL specification should be divided into two parts: the first part only focuses on the core interface definition language, and the second part addresses the binding extensions.

4.4 Description of Interactions with a Service


Charter: The Working Group will define a mechanism which will allow a Web service to describe the following set of operations: one-way messages (to and from the service described), request-response and solicit-response, as described in WSDL 1.1's port types.


Charter: Must describe SOAP 1.2 MEP (Message Exchange Pattern) (charter says: "must [...] describe [...] one-way messages, [...] request-response")


JS: Must be able to describe simple one-way messages, i.e., either incoming or outgoing (event) messages.


JS: Must be able to describe simple request-response-fault message exchange.


JS: (Not a requirement to describe arbitrary message exchanges.)


JS: Must be able to describe sets of messages that form a logical group (i.e., a port type).


JS: Must be able to derive a port type from another by extension of the logical group of messages.


JS: Must be able to extend protocol descriptions using mechanisms not explicitly identified in the spec.


PF: Context. WebServices requests often have an associated context -- such as the identity of the caller. This context has a logical component - typically a set of name-value pairs - and a binding into the particular format or transport. So for example, a userid and password may be bound into the HTTP transport using Basic Auth, or may be encoded in the SOAP header, and the Service implementation may be expecting that. Furthermore, there are some context items that the service may require, and there are others that are not required but may be understood. It is also possible that there are context items that are not required or understood, but the service may have a policy of passing on non-understood context items to other service it calls, or returning them to the client -- which may use them for correlation.


PF: WSDL is typically used to capture the server requirements on the client. For example, the server will expect to see certain SOAP headers. When WSDL is used in higher protocols, such as an orchestration language, each side of the exchange may wish to publish their requirements, and the "client" may have a requirement on the "server". For example, the client may require the server to set a particular header on the response. In WSDL today, there is an option to try to map this into the "Out-In" or "Out" interactions, by treating them as the "conjugates" of the corresponding "In-Out" or "In-only" operations. However, this is unsatisfactory, as these interactions are not well defined, and there is no way to specify that an Out-In is actually the conjugate of an In-Out, or simply another operation that has the same messages in the opposite order. It would be more satisfactory if the concept of "conjugates" was exposed directly so that the "client" side of an interaction could publish their requirements. This could be used by proposal such as flow or orchestration languages.

4.5 Messages and Types


JS: Must be able to describe messages independent of specific wire format.


JS: (No requirement to describe semantic content of messages.)


JS: Must be able to describe messages using XML Schema simple and complex types.


JS: Must be able to describe messages using other info sets.


JS: Must be able to extend message descriptions using mechanisms not explicitly identified in the spec.


JS: Must be able to describe messages that include arrays and nested arrays.


JS: Must be able to describe messages of other protocols.


JR: Must be able to classify/categorize operations. With the usage of XML schema in the ELEMENT attribute of the PART element (current WSDL spec) it is possible to use a type system as a kind of taxonomy for a semantical enriched description of parameters. To automatically search a suitable service respectively operation from a set of service descriptions it is not enough only to consider the parameters but also a kind of operation "type" (something like a taxonomy on operations). So I would suggest a kind of ELEMENT or TYPE attribute for operations.


YF: Must clearly separate the description of the operations (messages?) from the message exchange pattern and protocol binding.


YF: Must support grouping functionalities (operations) that share the same message-exchange pattern and transport binding

4.6 Service Types


JS: Must be able to describe a logical group of port type instances (i.e., a service type).


JS: Must be able to name an instance of a port type.


JS: Must be able to derive one service type from another by extension of the logical group of port instances.


JS: Must be able to extend service descriptions using mechanisms not explicitly identified in the spec.

4.7 Binding Description


Charter: The information exchanged to and from a Web service can be carried in a large number of different ways. The action of carrying some XML-based communication in an underlying protocol is called, in the XML Protocol jargon, a binding. The description language defined should therefore describe how to reach the Web Service in a form which is orthogonal to its message exchange patterns and its messages.


Charter: It is expected that in the near-term future, Web services will be accessed largely through SOAP Version 1.2 (the XML- based protocol produced by the XML Protocol Working Group) carried over HTTP/1.1, or by means of simple HTTP/1.1 GET and POST requests. The Working Group will describe the following bindings:

  1. SOAP Version 1.2; SOAP can be used over a variety of underlying protocols; the Working Group will provide a concrete SOAP Version 1.2 over HTTP binding.

  2. HTTP/1.1 GET and POST requests.


Charter: The Working Group will also ensure that other SOAP bindings can be described.


Charter: Must ensure that SOAP 1.2, e.g, SMTP or BEEP bindings can be described (charter says: "ensure that other SOAP bindings can be described").


JS: Must be able to describe the wire format of messages, whether XML, ASCII, binary, or some combination.


JS: Must provide a normative description of the binding for XML Protocol.


JS: Must be able to describe bindings to other transports.


JS: Must be able to extend transport binding descriptions using mechanisms not explicitly identified in the spec.


PF: A clearer separation of transport and binding in the spec. The current spec builds bindings that are tied to the transport, and therefore a hard link between the port and binding information. There are obviously cases where formatting information is specific to the transport, so it would be good to see the ability to define multiple bindings and to define bindings that are independent of transport, and also perhaps independent of the exact porttype. So an example would be --- define a porttype, then a binding for "soap-encoded rpc style", then a binding for SOAP/HTTP, then a port for HTTP, which points to both bindings.


KL: Better Specification for Binding Extensions. In addition to the core service definition framework, WSDL1.1 introduces specific binding extensions for SOAP 1.1, HTTP GET/POST and MIME, and nothing precludes the use of other binding extensions. To keep the core service definition framework simple, a separate and more detailed specification or technical report should be dedicated for various bindings.

4.8 Mapping to the Semantic Web


Charter: The Working Group will provide a mapping to RDF so that the information described can be easily merged with that of other applications. This mapping will be developed with the help of the RDF Interest Group.

4.9 Reusability Requirements


JS: Must be able to partition a description across multiple files.


JS: Must be able to use a description fragment in more than one description.


YF: Must support reusability of WSDL documents or parts of documents.

4.10 Extensibility Requirements


JS: Must define a set of constructions to indicate which extensions are optional versus mandatory.

4.11 Versioning Requirements


PF: Another requirement is to have a simple versioning tag to identify versions of WSDL documents or services.


FC: It would be good to allow for versioning of something smaller than a WSDL document.  I suspect that tools vendors will "compose" these documents, and they may sometimes contain information about a number of unrelated services (or, more correctly, services that are related in ways other than application semantics (tool vendor, server location,  etc.)).  It would be good if web services themselves were versioned, the web services being the semantic "unit" being defined.

5 Requirements from other W3C WGs

These are requirements submitted by other W3C Working Groups and Activities.

5.1 XML Protocol Requirements


JS: Must be able to describe XML Protocol messages.


JS: Must provide a normative description for XML Protocol messages.


JS: Must be able to describe XML Protocol Header elements and Body elements.


JS: Must be able to describe XML Protocol Faults.

5.2 XForms Requirements

5.3 RDF Requirements

5.4 P3P Requirements

6 References

Web Service Description Comments Archive (See http://lists.w3.org/Archives/Public/www-ws-desc-comments/.)
Web Service Discussion Archive (See http://lists.w3.org/Archives/Public/www-ws-desc/.)
Web Service Description Charter (See http://www.w3.org/2002/01/ws-desc-charter.)