C. URI References for WSDL Components (Non-Normative)

This appendix provides a syntax for URI references for named components found in a WSDL document. This includes the top level components: interface, binding and service and the subordinate components: operation, fault, and endpoint. The URI references are easy to understand and compare, while imposing no burden on the WSDL author.

C.1 WSDL URIs

There are two main 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 the WSDL media type, then the fragment identifiers can be used to identify the named components that are defined in the document.

However, this appendix specifies the use of the namespace URI with the WSDL fragment identifiers to form a URI-reference.

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

It is RECOMMENDED that the namespace URI SHOULD be a dereferencible URI and that it resolve to a WSDL document that provides service description information for that namespace, in which case the use of WSDL fragment identifiers is in compliance with the definition of URI-reference.

C.2 Fragment Identifiers

The following fragment identifier syntax is compliant with the [XPointer Framework].

The URI in a URI-reference for a WSDL component is the {target namespace} property of either the component itself, in the case of interfaces, bindings, and services, or the {target namespace} property of an ancestor component. The URI provided by the {target namespace} property is combined with a fragment identifier, where the fragment identifier is constructed from the {name} property of the component and the {name} properties of its ancestors as a path according to Table C-1. In that table the first column gives the name of the WSDL component as the [local name] of the element information item that represents that construct in a WSDL document. Columns two and three populate the variables x and y respectively. These variables are then used to construct the fragment in column four.


Table C-1. Rules for determining fragments for WSDL components
Component x y Fragment
interface {name} property of interface n/a interface(x)
operation {name} property of operation {name} property of parent interface operation(y/x)
fault {name} property of  fault
 {name} property of parent interface fault(y/x)
binding {name} property of binding n/a binding(x)
service {name} property of service n/a service(x)
endpoint {name} property of endpoint {name} property of parent service endpoint(y/x)

Note that the above rules are defined in terms of component properties rather than transfer syntax. 

C.3 Extension Elements

WSDL has an open content model. It is therefore possible for an extension to define new components. The 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://www.w3.org/2003/06/wsdl/soap12, 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.

C.4 Example

Consider the following WSDL located at http://example.org/TicketAgent.wsdl20 (see TicketAgent.wsdl20 and TicketAgent.xsd for source):

Example C-1. URI References - Example WSDL

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions 
	targetNamespace="http://example.org/TicketAgent.wsdl20" 
	xmlns:xsTicketAgent="http://example.org/TicketAgent.xsd" 
	xmlns:wsdl="http://www.w3.org/@@@@/@@/wsdl" 
	xmlns:xs="http://www.w3.org/2001/XMLSchema" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xsi:schemaLocation="http://www.w3.org/@@@@/@@/wsdl wsdl20.xsd">
	
	<wsdl:types>
		<xs:import schemaLocation="TicketAgent.xsd" namespace="http://example.org/TicketAgent.xsd" />
	</wsdl:types>
	
	<wsdl:interface name="TicketAgent">
	
		<wsdl:operation name="listFlights" pattern="http://www.w3.org/@@@@/@@/wsdl/in-out">
			<wsdl:input messageLabel="In" element="xsTicketAgent:listFlightsRequest"/>
			<wsdl:output messageLabel="Out" element="xsTicketAgent:listFlightsResponse"/>
		</wsdl:operation>
		
		<wsdl:operation name="reserveFlight" pattern="http://www.w3.org/@@@@/@@/wsdl/in-out">
			<wsdl:input messageLabel="In" element="xsTicketAgent:reserveFlightRequest"/>
			<wsdl:output messageLabel="Out" element="xsTicketAgent:reserveFlightResponse"/>
		</wsdl:operation>
	</wsdl:interface>
	
</wsdl:definitions>

Its conceptual elements have the following URI-references:

Example C-2. URI References - Example URIs

http://example.org/TicketAgent.wsdl20#interface(TicketAgent) 

http://example.org/TicketAgent.wsdl20#operation(TicketAgent/listFlights) 

http://example.org/TicketAgent.wsdl20#operation(TicketAgent/reserveFlight)