Web Service Description Requirements

2.1 Non-normative definitions

Web Service

A web service is is a software application or component that can be accessed over the Internet using a vendor/platform/language-neutral data interchange format to invoke the service and supply the response, using a rigorously defined message exchange pattern, and producing a result that is sufficiently well-defined to be processed by a software application.

Client

Software that makes use of a Web Service, acting as its 'user' or 'customer'.

2.2 Normative definitions

Message

The basic unit of communication between a Web Service and a Client: data to be communicated to or from a Web Service as a single logical transmission.

Operation

A set of messages related to a single Web Service action.

Interface (AKA Port Type)

A logical grouping of operations. An Interface represents an abstract Service type, independent of transmission protocol and data format.

Binding

An association between an Interface, a concrete protocol and a data format. A Binding specifies the protocol and data format to be used in transmitting messages defined by the associated Interface.

Port

An association between a Binding and a network address, specified by a URI, that may be used to communicate with an instance of a Service. A Port indicates a specific location for accessing a Service using a specific protocol and data format.

Service

A collection of ports.

4.1 General

R001

[MUST NOT] Charter: The language developed by the WG must not preclude any programming model, nor assume any transport or protocol for communication between peers. (Last revised 21 Feb 2002.)

R004

[MUST] JS: Describe constructs using the XML Infoset model. Similar to the SOAP 1.2 specifications, the WG specifications will use the XML Infoset model. (Last revised 21 Feb 2002.)

R099

[MUST] WG: WSDL 1.2 processors must support XML Schema (http://www.w3.org/2001/XMLSchema*). (Last discussed 21 Feb 2002.)

R100

[MUST] WG: The WG specifications must support other type systems (besides XML Schema http://www.w3.org/2001/XMLSchema*) via extensibility. (Last discussed 21 Feb 2002.)

R098

[MUST] WG: The schema and examples for the WG specifications must be written in XML Schema and should be written in the latest public XML Schema recommendation. (Last revised 28 Feb 2002.)

DR003

[SHOULD] JS: Use available XML technologies wherever possible.

DR005

[SHOULD] KL: Correct errors/inconsistencies in WSDL1.1

DR006

[SHOULD] KL: Provide 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.

DR007

[SHOULD] KL: Provide detailed examples including on-the-wire messages. (Was 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.)

DR009

[SHOULD] KL: Enable 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.

DR010

[SHOULD] 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.

DR103

[SHOULD] YF: The WSD specifications should be clear and easy to understand. This clarity implies that considerable editorial effort will be required in the structuring of the narrative through both outline/overview and normative reference material.

DR105

[SHOULD] YF: The WSD specification should make reasonable efforts to support applications that operate on resource constrained devices. Even though any practical device is resource constrained in any number of dimensions including but not limited to bandwidth, computational power and storage, the term "resource constrained device" often refers to hand-portable devices. This document does not attempt to define the term "resource constrained" nor what the constraints are for the available resources.

NR008

KL: Support up-to-date XML Schema. 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. (Last discussed 21 Feb 2002. Replaced with DR098, R099, and R100.)

4.2 Simplicity

R013

[MUST] Charter: The WG specifications must be simple to understand and implement correctly. The language defined by the WG specifications must be simple to use. (Last discussed 7 Mar 2002.)

R014

[SHOULD] Charter: The WG specifications must be compatible with the existing Web infrastructure. (Last discussed 7 Mar 2002.)

NR011

Charter: Focus must be put on simplicity, modularity and decentralization. (Last discussed 21 Feb 2002. Replaced with DR013, DR102, DR027.)

NR016

JS: Be simple to understand and implement correctly; comparable to other widespread Web solutions. (Last discussed 21 Feb 2002. Replaced with DR013.)

NR017

JS: Specification shall be as lightweight as possible, keeping parts that are mandatory to a minimum. (Last discussed 7 Mar 2002. Redundant with R013.)

NR018

JS: Optional parts of the specification should be orthogonal to each other allowing non-conflicting configurations to be implemented. (Last discussed 7 Mar 2002. Good goal, but unnecessary as a specific requirement.)

NR019

YF: Facilitate the creation of simple applications (fast and easy writing for simple apps). (Last discussed 7 Mar 2002. Merged in R013.)

NR020

YF: Be possible to compare easily two WSDL web services. (Last discussed 7 Mar 2002. May raise intractable semantic issues.)

NR102

YF: Since WSD is intended to be a foundation service description language, its definition should remain simple and stable over time. Explicit use of modularity and layering in the resulting design will help assure longevity. Such a framework will allow subsequent extension of the design while leaving the foundation of the design intact. (Last discussed 7 Mar 2002. Adequately covered by 'simple' in R013.)

NR104

YF: The WSD specification must clearly identify conformance requirements in a way that enables the conformance of an implementation of the specification to be tested (see also the W3C Conformance requirements (W3C members only)). (Last discussed 7 Mar 2002. Adequately covered by 'correct' in R013.)

4.3 Interface Description

R021

[MUST] Charter: The description language must describe the messages accepted and generated by the Web service. (Last revised 21 Feb 2002.)

R026

[MUST] 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. (Last discussed 28 Feb 2002.)

R022

[MUST] Charter: The language must allow describing application-level error messages (AKA faults) generated by the Web Service. (Last revised 28 Feb 2002.)

R041

[MUST] JS: The language must allow describing sets of operations that form a logical group. (Last revised 28 Feb 2002.)

DR027

[SHOULD] 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.

DR032

[SHOULD] 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.

DR035

[SHOULD] 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. Elements such as message, portType, operation are abstract interface definitions, and are usually defined at design time. Elements such as binding and services usually get their value at configuration/deployment/run time. Mixing all these elements together is at least confusing to many people.

NR023

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. (Last discussed 21 Feb 2002. Redundant with R021, R090, R100.)

NR033

YF: Support abstract interfaces. (Last discussed 28 Feb 2002. Replaced by DR109.)

NR034

YF: Support interfaces derived from abstract interfaces. (Last discussed 28 Feb 2002. Replaced by DR109.)

NR101

KL: 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. This requirement concurs with the Charter's requirement for two separate deliverables. (Last discussed 28 Feb 2002. Concern that this overconstraints the specification process.)

NR109

[MUST] JS: The language must describe interfaces separate from their concrete protocol, transport, data format or wire format deployment. (See also DR046.) (Last discussed 7 Mar 2002. Redundant with R071.)

4.4 Description of Interactions with a Service

R036

[MUST] Charter: The language will allow a Web Service to describe the functionality associated with one-way messages (to and from the service described), request-response, solicit-response, and faults. (Last revised 28 Feb 2002.)

DR042

[MUST] JS: Be able to derive a port type from another by extension of the logical group of messages.

DR043

[MUST] JS: Be able to extend protocol descriptions using mechanisms not explicitly identified in the spec.

DR040

[MUST NOT] JS: (Not a requirement to describe arbitrary message exchanges.)

DR094

[SHOULD] IS: Able to define events. WSDL should be very specific about events, defining a special type of a message or even a separate definition entity. Currently it is missing in WSDL 1.1.

DR097

[SHOULD] IS: Define operations that can be carried out synchronously (i.e. have a short expected reply cycle) and those messages that require asynchronous notification (i.e. have long expected reply cycle). Ability to differentiate such operations is a requirement of the service definition rather than application architecture. For the async operations, providing a reference to an event definition or status inquiry operation should be required.

DR044

[SHOULD] PF: Context. Web Services 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.

DR045

[SHOULD] 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.

DR095

[SHOULD] IS: Extensible metadefinitions. Be able to include *typed* metadata attributes for any definition element: message, part, port, operation, binding, service. The attributes may also be hierarchical (i.e. defined in another namespace).

DR110

[SHOULD] WV: Provide a way (optional) for the service to give an indication of how long it is going to take to process the request. This is just a hint to the client and the service is not obligated to respect what it advertised.

NR037

JJM: Must describe SOAP 1.2 MEP (Message Exchange Pattern) (charter says: "must [...] describe [...] one-way messages, [...] request-response") (Last discussed 28 Feb 2002. Duplicate of R036.)

NR038

JS: Must be able to describe simple one-way messages, i.e., either incoming or outgoing (event) messages. (Last discussed 28 Feb 2002. Duplicate of R036.)

NR039

JS: Must be able to describe simple request-response-fault message exchange. (Last discussed 28 Feb 2002. Duplicate of R036.)

4.5 Messages and Types

DR046

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

DR048

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

DR050

[MUST] JS: Be able to extend message descriptions using mechanisms not explicitly identified in the spec.

DR051

[MUST] JS: Be able to describe messages that include arrays and nested arrays.

DR052

[MUST] JS: Be able to describe messages of other protocols besides SOAP 1.2.

DR054

[MUST] YF: Clearly separate the description of the operations (messages?) from the message exchange pattern and protocol binding.

DR047

[MUST NOT] JS: (No requirement to describe semantic content of messages.)

DR049

[SHOULD] JS: Be able to describe messages using other info sets.

DR085

[SHOULD] PP: Be able to describe messages that include references (URIs) to strongly-typed referents.

DR096

[SHOULD] IS: Be able to describe references to other services (remote) or other interfaces (ports, local to this WSDL doc) that can be used as parts in message definitions. Currently (as of WSDL 1.1) message parts refer to data types (described in one or the other schema). The part must also be able to refer to a remote service (WSDL URL/Service/Port) or a local service/port qualified names. This has to be made clear as part of the standard for WS clients and service providers.

DR055

[SHOULD] YF: Support grouping functionalities (operations) that share the same message-exchange pattern and transport binding

DR053

[SHOULD] JR: Be able to classify/categorize [individual] 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 semantically 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.

4.6 Service Types

DR089

[MUST] KB: Describe Web services operations in an abstract format using the XML type system.

DR056

[MUST] JS: Be able to describe a logical group of port type instances (i.e., a service type).

DR058

[MUST] JS: Be able to derive one service type from another by extension of the logical group of port instances.

DR090

[MUST] KB: Group logically related operations together into abstract service types.

DR059

[MUST] JS: Be able to extend service descriptions using mechanisms not explicitly identified in the spec.

DR057

[SHOULD] JS: Be able to name an instance of a port type.

4.7 Bindings

DR060

[MUST] 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 [SOAP 1.2] 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.

DR091

[MUST] KB: Apply specific wire-format serializations (bindings) for service types.

DR081

[MUST] JS: Be able to describe endpoint location using URIs.

DR082

[MUST] JS: Be able to describe address for specific port instances within a service.

DR028

[MUST] JJM: 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").

DR077

[MUST] JS: Be able to describe SOAP 1.2 messages.

DR078

[MUST] JS: Provide a normative description for SOAP 1.2 messages.

DR079

[MUST] JS: Be able to describe SOAP 1.2 Header elements and Body elements.

DR080

[MUST] JS: Be able to describe SOAP 1.2 Faults.

DR029

[MUST] JJM: 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").

DR065

[MUST] JS: Provide a normative description of the binding for SOAP 1.2.

DR062

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

DR069

[MUST] 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.

DR092

[MUST] KB: Apply in an orthogonal manner specific transport(s) for a binding.

DR066

[MUST] JS: Be able to describe bindings to transports other than HTTP.

DR063

[MUST] JJM: Ensure that SOAP 1.2 bindings to SMTP or BEEP (for example) can be described (charter says: "ensure that other SOAP bindings can be described").

DR064

[MUST] JS: Be able to describe the wire format of messages, whether XML, ASCII, binary, or some combination.

DR108

[MUST] MW: Must be able to describe messages that include binary data, where the binary data is transmitted efficiently.

DR067

[MUST] JS: Be able to extend transport binding descriptions using mechanisms not explicitly identified in the spec.

DR083

[MUST] JS: Be able to separate design-time from run-time information.

DR061

[MUST/SHOULD] 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. [MUST] 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. [SHOULD] HTTP/1.1 GET and POST requests.

DR030

[SHOULD] JJM: Describe SOAP 1.2 RPC parameters types (ibid.).

DR031

[SHOULD] JJM: Support SOAP 1.2 intermediaries (charter says: "make sure SOAP 1.2 extensibility mechanism can be expressed")

DR086

[SHOULD] PP: Support all HTTP methods (verbs), including WebDAV and allow the use of non-standard HTTP methods.

DR068

[SHOULD] 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 port type. So an example would be --- define a port type, then a binding for "soap-encoded rpc style", then a binding for SOAP/HTTP, then a port for HTTP, which points to both bindings.

DR087

[SHOULD] FC: WSDL 1.1 defines services and operations and their bindings to various protocols. However, the details of how an operation is identified (either generally or specifically in particular bindings) is, shall we say, rather vague. As a result, some implementations use the namespace & element of the first child of Body (in SOAP RPC), others use SOAPAction header (in SOAP over Http), others use only the namespace, others the element name, others attempt to match the message type, etc. As a result, interoperability suffers.

It seems like a normative model (at least) for operation determination is necessary for interoperability between clients and servers from different vendors. This may be a requirement to define such a requirement for all defined bindings, as opposed to something that can be completely specified in the description. But I believe that such a requirement exists.

DR106

[SHOULD] PM: Ability to bind network address to the operation at runtime. For example, it is possible to have a service that supports operations like "Register" and "Notify" where a user will provide an email address that a Web Service can send notifications to when the user registers with the service. So the binding network address for the "Notify" operation needs to be dynamically populated at runtime. To achieve this it becomes necessary to allow a placeholder for dynamic bindings within the description of the Web Service.

DR107

[SHOULD] JJ: Based on the XML Protocol Usage Scenario (2.14 S21 Incremental parsing/processing of SOAP messages) and other requirements (a SOAP processor returning a large amount of data as attachment or message) there is a need for a SOAP processor and the SOAP client proxies to be constructed with the notion of data streaming in mind so that applications can scale well. (Especially in the case of dynamic proxy and stub creation scenarios.) This requirement for the SOAP processors imposed a requirement on the WSDL to be descriptive enough (like MIME binding or some kind of extension) to describe so that the Service Provider will do incremental parsing and processing of data (input) and the client can process the return message or attachment the same way. Without this description most of the toolkits will find it difficult to use this SOAP processor advantages for scalability and/or fail in interoperability.

4.8 Reusability

R071

[MUST] JS: Be able to partition a description across multiple files.

DR072

[MUST] JS: Be able to use a description fragment in more than one description.

DR073

[MUST] YF: Support reusability of WSDL documents or parts of documents.

DR093

[SHOULD] IS: Be able to accommodate namespace clusters with data types (schemas) and interface definitions (message/port/binding). I.e. service may have several namespaces with types and several other namespaces with message/port definitions. That is pretty important for expressing proper OO model of a service. Very few framework implementations pay attention to this (in many cases namespaces are flattened out which results in name conflicts). I guess it is so because namespaces of various type definitions and message/port/binding definitions have never been emphasized as a requirement really.

4.9 Extensibility

DR012

[MUST] 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.

DR015

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

DR025

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

DR074

[SHOULD] JS: Define a set of constructions to indicate which extensions are optional versus mandatory.

4.10 Versioning

DR075

[MUST] PF: Have a simple versioning tag to identify versions of WSDL documents or services.

DR076

[SHOULD] 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.

4.11 Security

DR084

[MUST NOT] JS: Compliance must not preclude building implementations that are resistant to attacks.

DR088

[SHOULD] DM: Should define best practice for signing descriptions using XML signatures, including canonicalization, transforms, XPath selectors, etc. I would probably be willing to leave this function out of the "core" functionality, because some client configuration WSDL driven tools might not care about issues of trusting WSDL input.

4.12 Mapping to the Semantic Web

DR070

[MUST] 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.

5.1 XML Protocol

5.2 XForms

5.3 RDF

5.4 P3P