R120: WSDL URI References

2002-10-17

Status

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

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 Namespace URN Scheme

There are two main use cases:

the URI is the URL of a WSDL document
the URI is the namespace of one or more WSDL documents

A namespace URI may look like a URL. Therefore, in order to make it clear that a URI refers to a namespace, we introduce the URN scheme urn:wsdl: and register it with IANA [IETF RFC 2611].

For example, if http://airline.wsdl/ticketagent/ is a namespace URI, then urn:wsdl:http://airline.wsdl/ticketagent/ is the URI we use in a URI reference to a component defined in the http://airline.wsdl/ticketagent/ namespace.

Fragment Identifiers

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:
<?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:

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

Related Proposals

The following alternatives have been discussed:

require that each element have a unique ID attribute
require that all NCNames be unique
use XPointer
use the same approach as XML Schema Normalized Universal Names (NUN)

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 is 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 NUN proposal is more complex, due to the greater complexity of XSD, and is still under development.