R120: WSDL URI References

Arthur Ryman
2002-10-17

Status

This is the second draft of a proposal for satisfying R120.
 

Previous Versions

Change History

Second 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.)

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 an easy to understand and compare URI-reference to each WSDL conceptual element, 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 must introduce a new WSDL media type, application/wsdl+xml [IETF RFC 3023] and register it with IANA [IETF RFC 2048].

WSDL URIs

There are two main use cases for URIs: If the URI is the URL of a WSDL document, then it has a media type and it contributes component definitions to a single WSDL namespace. If the media type is set to application/wsdl+xml then the proposed fragment indentifiers can be used to identify the main components that are defined in the document.

If the URI is a WSDL namespace then it does not make sense to use fragment identifiers with it since it may not be dereferencable, and hence have no associated media type, or if it is dereferencable, then it may point to a document that describes the namespace rather than a WSDL document. A document that describes the namespace may have media type text/html for example.

Fragment Identifiers

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

The URI reference for a WSDL conceptual element is a 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>. If it is required to also describe WSDL 1.1 overloaded operations, then the fragment syntax can be extend as follows: operation(z/y/x[input=w,output=v]) where the predicate corresponds the order of declaration of the <input> and <output> elements within the <operation>. The WSDL 1.1 is somewhat vague on how much information is required to disambiguate <operation> when overloading occurs, but we can define precise rules here if deemed appropriate.

Note that 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>.

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://schemas.airlines.org/TicketAgent.wsdl#message(listFlightsRequest)
http://schemas.airlines.org/TicketAgent.wsdl#part(listFlightsRequest/depart)
http://schemas.airlines.org/TicketAgent.wsdl#part(listFlightsRequest/origin)
http://schemas.airlines.org/TicketAgent.wsdl#part(listFlightsRequest/destination)
http://schemas.airlines.org/TicketAgent.wsdl#message(listFlightsResponse)
http://schemas.airlines.org/TicketAgent.wsdl#part(listFlightsResponse/result)
http://schemas.airlines.org/TicketAgent.wsdl#message(reserveFlightRequest)
http://schemas.airlines.org/TicketAgent.wsdl#part(reserveFlightRequest/depart)
http://schemas.airlines.org/TicketAgent.wsdl#part(reserveFlightRequest/origin)
http://schemas.airlines.org/TicketAgent.wsdl#part(reserveFlightRequest/destination)
http://schemas.airlines.org/TicketAgent.wsdl#part(reserveFlightRequest/flight)
http://schemas.airlines.org/TicketAgent.wsdl#message(reserveFlightResponse)
http://schemas.airlines.org/TicketAgent.wsdl#part(reserveFlightResponse/result)
http://schemas.airlines.org/TicketAgent.wsdl#portType(TicketAgent)
http://schemas.airlines.org/TicketAgent.wsdl#operation(TicketAgent/listFlights)
http://schemas.airlines.org/TicketAgent.wsdl#input(TicketAgent/listFlights/listFlightsRequest)
http://schemas.airlines.org/TicketAgent.wsdl#output(TicketAgent/listFlights/listFlightsResponse)
http://schemas.airlines.org/TicketAgent.wsdl#operation(TicketAgent/lreserveFlight)
http://schemas.airlines.org/TicketAgent.wsdl#input(TicketAgent/lreserveFlight/lreserveFlightRequest)
http://schemas.airlines.org/TicketAgent.wsdl#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 unqiue, 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)