R120: WSDL URI References

Arthur Ryman
2002-12-04

Status

This is the third draft of a proposal for satisfying R120. This specification will be included in Part 1 of the WSDL 1.2 Specification as a non-normative appendix.
 

Previous Versions

Change History

Second draft: Third draft

Requirement

R120: The description language MUST ensure that all conceptual elements in the description of Messages are addressable by a URI reference [IETF RFC 2396]. (From the Semantic Web. Last discussed 11 June 2002.)

Relation to WSDL 1.1

This specification applies to WSDL 1.2. It is not backward compatible with WSDL 1.1. For example, the proposed syntax does not disambiguate overloaded operation names, which are permissible in WSDL 1.1, but not in WSDL 1.2.

Problem

Each top level WSDL element has a QName, but the QName is only unique within the type of element, e.g. each <message> has a unique QName and each <portType> has a unique QName, but it is possible for a <message> and a <portType> to have the same QName. Therefore, QName alone is not the basis for a suitable URI since it is missing the type information. Also, there are nested elements, e.g. <part>, that have unique NCNames within their parent element, but not across elements, e.g. two <message> elements may each contain a <part> with the same name.

The situation is discussed further by Eric Prud'hommeaux in Arguments for Keeping R120.

Proposed Solution

The following proposal assigns URI-reference to each WSDL conceptual element. The proposed URI-reference is easy to understand and compare, while imposing no burden on the WSDL author.

WSDL Media Type

According to RFC 2396 [3] a URI-reference is a URI with an optional fragment identifier. The fragment format and interpretation depends on the media type of the resource that is accessed via the URI. Therefore we will introduce new WSDL media types, application/wsdl+xml and text/wsdl+xml  [IETF RFC 3023] and register it with IANA [IETF RFC 2048].

Note: There is discussion whether the media types should be application, text, or both. Here I will assume both, since that is the case for XML.

WSDL URIs

There are two main use cases for WSDL URIs: The URI of a WSDL document can be dereferenced to give a resource representation that contributes component definitions to a single WSDL namespace. If the media type is set to a WSDL media type, then the proposed fragment identifiers can be used to identify the main components that are defined in the document.

However, the URI of a WSDL namespace may not be dereferencable, or if it is dereferencable, then it may not give a resource representation that is a WSDL media type. For example, a namespace URI may dereference to an HTML document that describes the namespace. Since the namespace URI does not necessarily reference a WSDL media type, the use of  WSDL fragment identifiers with it is not strictly in compliance with the definition of URI-reference.

Notwithstanding the above potential architectural objection, this proposal specifies the use of the namespace URI with the WSDL fragment identifiers to form a URI-reference. Comment from the W3C Technical Architecture Group on this point is invited.

Fragment Identifiers

The following fragment identifier proposal is compliant with the XPointer Framework.

The URI reference for a WSDL conceptual element is the namespace URI plus a fragment identifier, where the fragment identifier is constructed from the NCName of the element and its ancestors as a path according to the following table:
 
Element NCName NCName of Parent NCName of Grandparent Fragment
message x (required) n/a n/a message(x)
part x (optional) y (message) n/a part(y/x)
portType x (required) n/a n/a portType(x)
operation x (required) y (portType) n/a operation(y/x)
input x (optional) y (operation) z (portType) input(z/y/x)
output x (optional) y (operation) z (portType) output(z/y/x)
fault x (required) y (operation) z (portType) fault(z/y/x)
binding x (required) n/a n/a binding(x)
service x (required) n/a n/a service(x)
port x (required) y (service) n/a port(y/x)

If an element has an optional NCName, and no value is supplied, then its default value is used if one is defined. This rule means that a meaningful URI-reference can still be formed for elements like <input> and <output> when their name attribute is missing since WSDL 1.1 defines default NCName values for <input> and <output>. WSDL 1.2 should make the name attribute of <part> required to avoid possible ambiguity.

In WSDL 1.1, <operation> overloading is possible, i.e. a <portType> may have more than one <operation> with the same NCName. In this case, the <operation> is uniquely specified by giving the NCNames of  its <input> and <output> elements. WSDL 1.2 makes the <operation> name unique within a <portType>.

Note:  The WSDL 1.1 XSD schema has some irregularities which we should correct in WSDL 1.2 For example <port> is nested in <service> but its NCName is unique within the targetnamespace, unlike the case for <part> and <operation>. Also, the above table reflects the WSDL 1.1 and must be updated when the WSDL 1.2 schema is finalized.

Extension Elements

WSDL has an open content model. It is therefore possible for an extension to define new components. The proposed XPointer Framework scheme for components added by extensions is:
extension(extension-namespace, extension-specific-syntax)
where extension-namespace is the namespace that identifies the extension, e.g. for SOAP the namespace is http://schemas.xmlsoap.org/wsdl/soap/, and extension-specific-syntax is defined by the extension. The owner of the extension must define any components contributed by the extension and a syntax for identifying them.

Example

Consider the following WSDL located at http://schemas.airlines.org/TicketAgent.wsdl:

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="TicketAgent"
    targetNamespace="http://airline.wsdl/ticketagent/"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://airline.wsdl/ticketagent/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsd1="http://airline/">
    <import location="TicketAgent.xsd" namespace="http://airline/"/>
    <message name="listFlightsRequest">
        <part name="depart" type="xsd:dateTime"/>
        <part name="origin" type="xsd:string"/>
        <part name="destination" type="xsd:string"/>
    </message>
    <message name="listFlightsResponse">
        <part name="result" type="xsd1:ArrayOfString"/>
    </message>
    <message name="reserveFlightRequest">
        <part name="depart" type="xsd:dateTime"/>
        <part name="origin" type="xsd:string"/>
        <part name="destination" type="xsd:string"/>
        <part name="flight" type="xsd:string"/>
    </message>
    <message name="reserveFlightResponse">
        <part name="result" type="xsd:string"/>
    </message>
    <portType name="TicketAgent">
        <operation name="listFlights" parameterOrder="depart origin destination">
            <input message="tns:listFlightsRequest" name="listFlightsRequest"/>
            <output message="tns:listFlightsResponse" name="listFlightsResponse"/>
        </operation>
        <operation name="reserveFlight" parameterOrder="depart origin destination flight">
            <input message="tns:reserveFlightRequest" name="reserveFlightRequest"/>
            <output message="tns:reserveFlightResponse" name="reserveFlightResponse"/>
        </operation>
    </portType>
</definitions>

Its conceptual elements have the following URI-references:

http://airline.wsdl/ticketagent/#message(listFlightsRequest)
http://airline.wsdl/ticketagent/#part(listFlightsRequest/depart)
http://airline.wsdl/ticketagent/#part(listFlightsRequest/origin)
http://airline.wsdl/ticketagent/#part(listFlightsRequest/destination)
http://airline.wsdl/ticketagent/#message(listFlightsResponse)
http://airline.wsdl/ticketagent/#part(listFlightsResponse/result)
http://airline.wsdl/ticketagent/#message(reserveFlightRequest)
http://airline.wsdl/ticketagent/#part(reserveFlightRequest/depart)
http://airline.wsdl/ticketagent/#part(reserveFlightRequest/origin)
http://airline.wsdl/ticketagent/#part(reserveFlightRequest/destination)
http://airline.wsdl/ticketagent/#part(reserveFlightRequest/flight)
http://airline.wsdl/ticketagent/#message(reserveFlightResponse)
http://airline.wsdl/ticketagent/#part(reserveFlightResponse/result)
http://airline.wsdl/ticketagent/#portType(TicketAgent)
http://airline.wsdl/ticketagent/#operation(TicketAgent/listFlights)
http://airline.wsdl/ticketagent/#input(TicketAgent/listFlights/listFlightsRequest)
http://airline.wsdl/ticketagent/#output(TicketAgent/listFlights/listFlightsResponse)
http://airline.wsdl/ticketagent/#operation(TicketAgent/lreserveFlight)
http://airline.wsdl/ticketagent/#input(TicketAgent/lreserveFlight/lreserveFlightRequest)
http://airline.wsdl/ticketagent/#output(TicketAgent/lreserveFlight/lreserveFlightResponse)

Related Proposals

The following alternatives have been discussed: Requiring unique ID attributes is a burden to the author and is hard to manage across multiple documents with the same namespace. Also, the ID is not required to be descriptive so the URI-reference based on it would be hard to understand.

Unique NCNames are also harder to manage across documents and result in a slight burden to the author who is forced to make the names unique, e.g. by adding type-specific suffixes.

XPointer syntax is complex and does not result in easily compared or understood URI-references. The WSDL targetnamespace is not part of the fragment so the document must be retrieved to obtain it. This makes comparing URI-references harder. The current proposal shares this problem. However, it is fully general and applies equally to WSDL extensions. Its use does not require the definition of a WSDL media type.

The NUN proposal is more complex, due to the greater complexity of XSD, and is still under development. However, it will probably be released in time for use by us. It has the benefit of making the WSDL targetnamespace part of the fragment, which allows identifiers to be compared without retrieving the document.

The following table compares fragment identifiers for the listFlightsRequest input component defined above. The NUN example was provided by Jonathan Marsh.
 
Schema Fragment
Full XPointer #xmlns(w=http://schemas.xmlsoap.org/wsdl/) xpointer(//w:portType[@name="TicketAgent"]/w:operation[@name="listFlights"]/w:input[@name="listFlightsRequest"])
XML NUN #xmlns(ta=http://www.airline.wsdl/ticketagent/) wsdl(/portType(ta:TicketAgent)/operation(listFlights)/input(listFlightsRequest))
Proposal #input(TicketAgent/listFlights/listFlightsRequest)