Web Services Metadata Exchange (WS-MetadataExchange)

2.1 Requirements

This specification intends to meet the following requirements:

• Define a mechanism for retrieving metadata about a Web service endpoint.

• Define an encapsulation format for metadata.

• Treat the metadata about a Web service endpoint as [WS-Transfer] resources, or as an HTTP reachable resource.

• Define a bootstrap mechanism for retrieving metadata.

• Support future versions of known metadata formats.

• Allow new metadata formats to be added.

2.2 Examples

Example 2-1 illustrates a sample GetWSDL request for the WSDL metadata document of a service.

(01)  <s11:Envelope
(02)     xmlns:s11='http://schemas.xmlsoap.org/soap/envelope/'
(03)     xmlns:wsa='http://www.w3.org/2005/08/addressing'>
(04)     xmlns:wst='http://www.w3.org/2010/03/ws-tra'>
(05)    <s11:Header>
(06)      <wsa:Action>
(07)        http://www.w3.org/2010/03/ws-mex/GetWSDL
(08)      </wsa:Action>
(09)      <wsa:To>http://services.example.org/stockquote</wsa:To>
(10)      <wsa:ReplyTo>
(11)        <wsa:Address>http://client.example.org</wsa:Address>
(12)      </wsa:ReplyTo>
(13)      <wsa:MessageID>
(14)        urn:uuid:1cec121a-82fe-41da-87e1-3b23f254f128
(15)      </wsa:MessageID>
(16)    </s11:Header>
(17)    <s11:Body>
(18)      <mex:GetWSDL/>
(19)    </s11:Body>
(20)  </s11:Envelope> 

Example 2-2 lists a sample response to the request in Example 2-1.

(01)   <s11:Envelope
(02)      xmlns:s11='http://schemas.xmlsoap.org/soap/envelope/'
(03)      xmlns:wsa='http://www.w3.org/2005/08/addressing'
(04)      xmlns:wsp='http://www.w3.org/ns/ws-policy'
(05)      xmlns:mex='http://www.w3.org/2010/03/ws-mex'>
(06)    <s11:Header>
(07)      <wsa:To>http://client.example.org</wsa:To>
(08)      <wsa:Action>
(09)        http://www.w3.org/2010/03/ws-mex/GetWSDLResponse
(10)      </wsa:Action>
(11)      <wsa:RelatesTo>
(12)        urn:uuid:73d7edfc-5c3c-49b9-ba46-2480caee43e9
(13)      </wsa:RelatesTo>
(14)    </s11:Header>
(15)    <s11:Body>
(16)      <mex:GetWSDLResponse>
(17)        <wsdl:definitions ...>
(18)          <!-- WSDL data removed for brevity -->
(19)        </wsdl:definitions>
(18)      </mex:GetWSDLResponse>
(19)    </s11:Body>
(20)  </s11:Envelope> 

Lines 17-19 in Example 2-2 is the WSDL of the service.

Example 2-3 illustrates a sample [WS-Transfer] Get request for a resource' s representation.

(01)  <s11:Envelope
(02)     xmlns:s11='http://schemas.xmlsoap.org/soap/envelope/'
(03)     xmlns:wsa='http://www.w3.org/2005/08/addressing'>
(04)     xmlns:wst='http://www.w3.org/2010/03/ws-tra'>
(05)    <s11:Header>
(06)      <wsa:Action>
(07)        http://www.w3.org/2010/03/ws-tra/Get
(08)      </wsa:Action>
(09)      <wsa:To>http://services.example.org/stockquote/metadata</wsa:To>
(10)      <wsa:ReplyTo>
(11)        <wsa:Address>http://client.example.org</wsa:Address>
(12)      </wsa:ReplyTo>
(13)      <wsa:MessageID>
(14)        urn:uuid:1cec121a-82fe-41da-87e1-3b23f254f128
(15)      </wsa:MessageID>
(16)    </s11:Header>
(17)    <s11:Body>
(18)      <wst:Get/>
(19)    </s11:Body>
(20)  </s11:Envelope>

The sample request message of Example 2-3 is a [WS-Transfer] request for the retrieval of a resource's representation. In this case, the requested representation is the WS-MetadataExchange Metadata element about a Web service endpoint. The fact that the resource's representation is a mex:Metadata element might be known to the requestor but is not explicitly encoded in the request message.

Example 2-4 illustrates a sample response to the request of Example 2-3.

(01)  <s11:Envelope
(02)      xmlns:s11='http://schemas.xmlsoap.org/soap/envelope/'
(03)      xmlns:wsa='http://www.w3.org/2005/08/addressing'
(04)      xmlns:mex='http://www.w3.org/2010/03/ws-mex'
(05)      xmlns:wsp='http://www.w3.org/ns/ws-policy'
(06)      xmlns:wst='http://www.w3.org/2010/03/ws-tra'
(07)      xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'>
(08)    <s11:Header>
(09)      <wsa:Action>
(10)        http://www.w3.org/2010/03/ws-tra/GetResponse
(11)      </wsa:Action>
(12)      <wsa:To>http://client.example.org</wsa:To>
(13)      <wsa:RelatesTo>
(14)        urn:uuid:1cec121a-82fe-41da-87e1-3b23f254f128
(15)      </wsa:RelatesTo>
(16)    </s11:Header>
(17)    <s11:Body>
(18)      <wst:GetResponse>
(19)        <mex:Metadata>
(20)          <mex:MetadataSection Dialect='http://schemas.xmlsoap.org/wsdl/'>
(21)            <wsdl:definitions>
(22)              <!-- WSDL data removed for brevity -->
(23)            </wsdl:definitions>
(24)          </mex:MetadataSection>
(25)          <mex:MetadataSection
(26)              Dialect='http://www.w3.org/2001/XMLSchema'
(27)              Identifier='http://services.example.org/stockquote/schemas'>
(28)            <mex:MetadataLocation>
(29)              http://services.example.org/stockquote/schemas
(30)            </mex:MetadataLocation>
(31)          </mex:MetadataSection>
(32)          <mex:MetadataSection
(33)              Dialect='http://www.w3.org/ns/ws-policy'
(34)              Identifier='http://services.example.org/stockquote/policy'>
(35)            <mex:MetadataReference>
(36)              <wsa:Address>
(37)                http://services.example.org/stockquote/policy
(38)              </wsa:Address>
(39)            </mex:MetadataReference>
(40)          </mex:MetadataSection>
(41)        </mex:Metadata>
(42)      </wst:GetResponse>
(43)    </s11:Body>
(44)  </s11:Envelope>

The message of Example 2-4 is a [WS-Transfer] response message to the request of Example 2-3. The content of the [Body] (lines 17-43) is a mex:Metadata element with metadata about the Web service endpoint (lines 19-41). The mex:Metadata contains three MetadataSections. The first MetadataSection (lines 20-24) contains the [WSDL11] of the Web service endpoint. The second MetadataSection (lines 25-31) contains the location of the XML Schemas [XMLSchema - Part 1], [XMLSchema - Part 2] used by the WSDL document. The schemas can be retrieved through an HTTP GET request at the identified URL (lines 28-30). The third MetadataSection (lines 32-40) contains the [WS-Addressing] endpoint reference (lines 35-39) of a [WS-Transfer] resource the representation of which is a [WS-Policy] document as indicated by the Dialect attribute (line 33).

While the WS-Policy of the Web service endpoint could be retrieved using a WS-Transfer Get request directed to the endpoint identified by the mex:MetadataReference element in lines 35-39 of Example 2-4, some endpoints MAY support explicit requests for metadata via the GetMetadata operation. Example 2-5 illustrates a sample GetMetadata request for the [WS-Policy].

(01)  <s11:Envelope
(02)      xmlns:s11='http://schemas.xmlsoap.org/soap/envelope/'
(03)      xmlns:wsa='http://www.w3.org/2005/08/addressing'
(04)      xmlns:mex='http://www.w3.org/2010/03/ws-mex' >
(05)    <s11:Header>
(06)      <wsa:To>http://services.example.org/stockquote</wsa:To>
(07)      <wsa:Action>
(08)        http://www.w3.org/2010/03/ws-mex/GetMetadata
(09)      </wsa:Action>
(10)      <wsa:MessageID>
(11)        urn:uuid:73d7edfc-5c3c-49b9-ba46-2480caee43e9
(12)      </wsa:MessageID>
(13)      <wsa:ReplyTo>
(14)        <wsa:Address>http://client.example.org</wsa:Address>
(15)      </wsa:ReplyTo>
(16)    </s11:Header>
(17)    <s11:Body>
(18)      <mex:GetMetadata>
(19)        <mex:Dialect URI='http://www.w3.org/ns/ws-policy'
(20)          Identifier='http://services.example.org/stockquote/policy'/>
(21)      </mex:GetMetadata>
(22)    </s11:Body>
(23)  </s11:Envelope>

Lines 7-9 in Example 2-5 indicate this is a GetMetadata request. As lines 18-21 indicate, this request is for the policy of the Web service endpoint (line 6).

Example 2-6 lists a sample response to the request in Example 2-5.

(01)   <s11:Envelope
(02)      xmlns:s11='http://schemas.xmlsoap.org/soap/envelope/'
(03)      xmlns:wsa='http://www.w3.org/2005/08/addressing'
(04)      xmlns:wsp='http://www.w3.org/ns/ws-policy'
(05)      xmlns:mex='http://www.w3.org/2010/03/ws-mex'>
(06)    <s11:Header>
(07)      <wsa:To>http://client.example.org</wsa:To>
(08)      <wsa:Action>
(09)        http://www.w3.org/2010/03/ws-mex/GetMetadataResponse
(10)      </wsa:Action>
(11)      <wsa:RelatesTo>
(12)        urn:uuid:73d7edfc-5c3c-49b9-ba46-2480caee43e9
(13)      </wsa:RelatesTo>
(14)    </s11:Header>
(15)    <s11:Body>
(16)      <mex:GetMetadataResponse>
(17)        <mex:Metadata>
(18)          <mex:MetadataSection
(19)              Dialect='http://www.w3.org/ns/ws-policy'
(20)              Identifier='http://services.example.org/stockquote/policy'>
(21)            <wsp:Policy>
(22)              <wsp:ExactlyOne>
(23)                <!-- Policy alternatives -->
(24)              </wsp:ExactlyOne>
(25)            </wsp:Policy>
(26)          </mex:MetadataSection>
(27)        </mex:Metadata>
(28)      </mex:GetMetadataResponse>
(29)    </s11:Body>
(30)  </s11:Envelope>

Lines 8-10 in Example 2-6 indicate this message is a response to a GetMetadata request, and lines 11-13 indicate that it is a response to the request in Example 2-5. Lines 17-26 contain a single MetadataSection (lines 18-26); line 19 indicates that the metadata in this section is of type, or Dialect, WS-Policy while line 20 identifies a specific policy document. Line 23 would have contained the policy expressions for the Web service endpoint to which the GetMetadata request of Example 2-5 was directed.

3.1 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC 2119].

This specification uses the following syntax to define outlines for messages:

• The syntax appears as an XML instance, but values in italics indicate data types instead of literal values.

• Characters are appended to elements and attributes to indicate cardinality:

  • "?" (0 or 1)

  • "*" (0 or more)

  • "+" (1 or more)

• The character "|" is used to indicate a choice between alternatives.

• The characters "(" and ")" are used to indicate that contained items are to be treated as a group with respect to cardinality or choice.

• The characters "[" and "]" are used to call out references and property names.

• Ellipses (i.e., "...") indicate points of extensibility.

• XML namespace prefixes (see Table 3-1) are used to indicate the namespace of the element being defined.

In addition to Message Information Header properties [WS-Addressing], this specification uses the following properties to define messages:

[Headers]

Unordered message headers.

[Action]

The value to be used for the wsa:Action IRI.

[Body]

A message body.

These properties bind to a SOAP Envelope as follows:

<s:Envelope>
  <s:Header>
    [Headers]
    <wsa:Action>[Action]</wsa:Action>
    ...
  </s:Header>
  <s:Body>[Body]</s:Body> 
</s:Envelope>

This specification can be used in terms of XML Information Set (Infoset) [XML Infoset], even though the specification uses XML 1.0 terminology. Valid Infoset for this specification is the one serializable in XML 1.0, hence the use of XML 1.0.

3.2 Considerations on the Use of Extensibility Points

The elements defined in this specification MAY be extended at the points indicated by their outlines and schema. Implementations MAY add child elements and/or attributes at the indicated extension points but MUST NOT contradict the semantics of the parent and/or owner, respectively. If a receiver does not recognize an extension, the receiver SHOULD ignore that extension. Senders MAY indicate the presence of an extension that has to be understood through the use of a corresponding SOAP Header with a soap:mustUnderstand attribute with the value "1".

In cases where it is either desirable or necessary for the receiver of a request that has been extended to indicate that it has recognized and accepted the semantics associated with that extension, it is RECOMMENDED that the receiver add a corresponding extension to the response message. The definition of an extension SHOULD clearly specify how the extension that appears in the response correlates with that in the corresponding request.

Extension elements and attributes MUST NOT use the Web Services Metadata Exchange namespace URI.

3.3 XML Namespaces

The XML namespace URI that MUST be used by implementations of this specification is:

http://www.w3.org/2010/03/ws-mex

Table 3-1 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.

The working group intends to update the value of the Web Services Metadata Exchange namespace URI each time a new version of this document is published until such time that the document reaches Candidate Recommendation status. Once it has reached Candidate Recommendation status, the working group intends to maintain the value of the Web Services Metadata Exchange namespace URI that was assigned in the Candidate Recommendation unless significant changes are made that impact the implementation or break post-CR implementations of the specification. Also see http://www.w3.org/2001/tag/doc/namespaceState.html and http://www.w3.org/2005/07/13-nsuri .

3.4 Terminology

Service Endpoint

A Web service that is addressable using a WS-Addressing endpoint reference. Within the context of this specification, it is assumed that the consumer's primary goal is to interact with this service.

Metadata Resource

A specialized Web service that is addressable using either a WS-Addressing endpoint reference or a URL and whose main purpose is to expose the XML representation of a piece of metadata associated with a Service Endpoint.

While technically a single Web service can be both a 'Service Endpoint' as well as a 'Metadata Resource', for the purposes of clarifying the various expectations of these two types Web services, this specification will discuss these two concepts (or roles) as distinct entities.

3.5 Compliance

An implementation is not compliant with this specification if it fails to satisfy one or more of the MUST or REQUIRED level requirements defined herein. A SOAP Node MUST NOT use the XML namespace identifier for this specification (listed in 3.3 XML Namespaces) within SOAP Envelopes unless it is compliant with this specification.

Normative text within this specification takes precedence over the XML Schema and WSDL descriptions, which in turn take precedence over outlines, which in turn take precedence over examples.

All messages defined by this specification MUST be sent to a Web service that is addressable by an EPR (see [WS-Addressing]).

Unless otherwise noted, all IRIs are absolute IRIs and IRI comparison MUST be performed according to [RFC 3987] section 5.3.1.

For any message defined by this specification, any OPTIONAL elements or attributes in the message MAY be used by senders of the message; however receivers of those messages MUST support those OPTIONAL elements and attributes, unless other behavior is explicitly defined by this specification.

Support for the GetMetadata operation by a Web service is OPTIONAL. If metadata about a Web service endpoint is referenced by a MetadataReference, which is a [WS-Addressing] endpoint reference, then the MetadataReference MUST refer to a [WS-Transfer] resource. The referred resource MAY also support other resource management and access specifications (e.g. HTTP, WS-ResourceFramework).

6.1 GetWSDL

A requester MAY send a GetWSDL request message to an endpoint to retrieve the service's WSDL metadata document. This operation MUST be supported by compliant WS-MetadataExchange service endpoints. Note, the GetWSDL operation is a SOAP-based equivalent feature to the commonly supported HTTP GET targeted at an endpoint's URL appended with "?wsdl".

Through examination of this WSDL document, and by following any references within it, a requester MUST be able to retrieve any metadata needed to interact with the service. For example, the schema used by the service might be embedded within the WSDL or could be available by following a xs:import element. Likewise, as discussed in 9 Exposing Metadata for Implicitly Defined Features through the inclusion of policy assertions and nested metadata (or metadata references) within those policy assertions, a requester MUST be able to determine the set of implicit features available and any related metadata associated with those features.

The normative outline for a GetWSDL request is:

[Action]
  http://www.w3.org/2010/03/ws-mex/GetWSDL

[Body]
  <mex:GetWSDL ...>
    xs:any*
  </mex:GetWSDL> 

If the endpoint accepts a GetWSDL request, it MUST reply with a GetWSDLResponse message. The normative outline for a GetWSDLResponse is:

[Action]
  http://www.w3.org/2010/03/ws-mex/GetWSDLResponse

[Body]
  <mex:GetWSDLResponse ...>
    xs:any*
  </mex:GetWSDLResponse> 

The following describes additional, normative constraints on the outline listed above:

[Body]/mex:GetWSDLResponse/wsdl:definitions

When present this OPTIONAL element contains the WSDL metadata document of the endpoint. The absence of this element indicates that the endpoint does not have any WSDL document, or additional metadata, associated with it.

This operation is safe; it will not result in any side effect imputable to the requester. This means that in case of an underlying protocol error that might get unnoticed, resending the same request can be done automatically.

6.2 GetMetadata

A requester MAY send a GetMetadata request message to an endpoint to retrieve the metadata associated with that endpoint. This operation MAY be supported by WS-MetadataExchange compliant service endpoints. Observe that, in the case where a service endpoint is also a [WS-Transfer] resource, the [WS-Transfer] Get operation allows requesters to retrieve the resource representation associated with that endpoint (i.e. the "data"), while the GetMetadata operation can be used to retrieve that endpoint's metadata. The normative outline for a GetMetadata request is:

[Action]
  http://www.w3.org/2010/03/ws-mex/GetMetadata

[Body]
  <mex:GetMetadata ...>
    <mex:Dialect URI='xs:anyURI'
                 Identifier='xs:anyURI' ?
                 Content='xs:anyURI' ? .../> *
    xs:any*
  </mex:GetMetadata> 

The following describes additional, normative constraints on the outline listed above:

[Body]/mex:GetMetadata/mex:Dialect

When this repeating OPTIONAL element is present, the response MUST include only MetadataSections corresponding to metadata specified by the combination of the URI, Identifier and Content attributes of each of the Dialect elements. For each Dialect element if there is no metadata for that combination of attributes then the response MUST NOT include any MetadataSections for that Dialect element.

When this element is not present, the endpoint MUST return all available metadata.

[Body]/mex:GetMetadata/mex:Dialect@URI

This REQUIRED attribute specifies the Metadata Dialect. The response MUST only include MetadataSections corresponding to the Dialect specified by this IRI. If the receiver does not have any MetadataSections of this indicated Dialect, the response MUST include zero MetadataSections for this IRI.

[Body]/mex:GetMetadata/mex:Dialect@Identifier

When this OPTIONAL attribute is present, the response MUST include only MetadataSections with the indicated identifier; if the receiver does not have any MetadataSections of the indicated identifier, the response MUST include zero MetadataSections for this IRI/Identifier pair. When this attribute is not present, the implied value is any identifier. If multiple MetadataSections have the indicated Dialect and Identifier then all of them MUST be returned.

[Body]/mex:GetMetadata/mex:Dialect@Content

When this OPTIONAL attribute is present, the response MUST include only MetadataSections of this specified content form. If the specified content form is not available, or not known, then the response MUST include zero MetadataSections of the specified form for this IRI/Identifier pair. This specification defines the following content form IRIs:

Content Form IRI	Form
http://www.w3.org/2010/03/ws-mex/Content/EPR	A MetadataReference element is returned
http://www.w3.org/2010/03/ws-mex/Content/URI	A MetadataLocation element is returned
http://www.w3.org/2010/03/ws-mex/Content/Metadata	The metadata is embedded
http://www.w3.org/2010/03/ws-mex/Content/Any	The service is free to choose any content form
http://www.w3.org/2010/03/ws-mex/Content/All	The service MUST return all available content forms

When not present the default value is "http://www.w3.org/2010/03/ws-mex/Content/Any".

If an endpoint accepts a GetMetadata request, it MUST reply with a GetMetadataResponse message. The normative outline for a GetMetadataResponse is:

[Action]
  http://www.w3.org/2010/03/ws-mex/GetMetadataResponse

[Body]
  <mex:GetMetadataResponse>
    <mex:Metadata ...> ...  </mex:Metadata>
    xs:any*
  </mex:GetMetadataResponse>

The following describes additional, normative constraints on the outline listed above:

[Body]/mex:GetMetadataResponse/mex:Metadata

The body of the response message MUST contain one mex:Metadata element as defined in 4 Web Services Metadata Collection.

This operation is safe; it will not result in any side effect imputable to the requester. This means that in case of an underlying protocol error that might get unnoticed, resending the same request can be done automatically.

7.1 mex:Location

The mex:Location element MAY be used to specify a reference to an HTTP metadata resource. A requester MAY use an HTTP GET to the indicated URL to retrieve the metadata.

The outline for the mex:Location element is:

<mex:Location URL="xs:anyURI" Type="xs:QName" 
              Identifier="xs:anyURI"? ...>
  xs:any*
<mex:Location> 

The following describes additional constraints on the outline listed above:

/mex:Location

This element contains a reference to an HTTP metadata resource.

/mex:Location@URL

This REQUIRED attribute contains the URL of an HTTP metadata resource. This resource MUST support retrieval of the metadata via an HTTP GET request.

/mex:Location@Type

This REQUIRED attribute indicates the QName of the referenced metadata. This can be used in deciding whether or not to retrieve the metadata.

/mex:Location@Identifier

This OPTIONAL attribute indicates the Identifier for the metadata being referenced. Identifier is an absolute IRI. If omitted, there is no implied value.

7.2 mex:Reference

The mex:Reference element MAY be used to specify a reference to a WS-Transfer metadata resource. A requester MAY use a WS-Transfer Get to the indicated EPR to retrieve the metadata

The outline for the mex:Reference element is:

<mex:Reference Type="xs:QName" 
               Identifier="xs:anyURI"? ...>
  endpoint-reference-type
<mex:Reference> 

The following describes additional constraints on the outline listed above:

/mex:Reference

This element is an endpoint reference to a metadata resource. This resource MUST support retrieval of the metadata via a WS-Transfer Get request.

/mex:Reference@Type

This REQUIRED attribute indicates the QName of the referenced metadata. This can be used in deciding whether or not to retrieve the metadata.

/mex:Reference@Identifier

This OPTIONAL attribute indicates the Identifier for the metadata being referenced. Identifier is an absolute IRI. If omitted, there is no implied value.

7.3 Examples

The following examples show how metadata might appear in various locations:

(01) <wsa:Endpoint ...>
(02)    <wsa:Address> http://example.com </wsa:Address>
(03)    <wsa:Metadata>
(04)      <wsdl:definitions>
(05)        ...
(06)      </wsdl:definitions>
(07)    </wsa:Metadata>
(08)  </wsa:Endpoint> 

Example 7-1 shows an endpoint reference with the endpoint's WSDL embedded. This saves the user of this EPR from having to retrieve the WSDL. This same endpoint reference might have been constructed by using a metadata reference instead, as shown in Example 7-2:

(01) <wsa:Endpoint ...>
(02)   <wsa:Address> http://example.com </wsa:Address>
(03)   <wsa:Metadata>
(04)     <mex:Location URL="http://example.com/?wsdl"
(05)                     Type="wsdl:definitions"/>
(06)   </wsa:Metadata>
(07) </wsa:Endpoint> 

Example 7-2 shows the same endpoint reference but rather than embedding the endpoint's WSDL directly in the EPR a mex:Location is used to indicate that if the user of the EPR needs the service's WSDL then it can retrieve it from the specified URL.

The following example WSDL shows how support for a particular feature might be indicated:

(01) <wsdl:definitions>
(02)   ...
(03)   <wsdl:service name="stockQuote">
(04)     <wsdl:port binding="..." name="...">
(05)       <soap:address location="http://example.com"/>
(06)     </wsdl:port>
(07)     <wsp:Policy>
(08)       <wse:EventSource>
(09)         <wse:FormatName uri="http://www.w3.org/2010/03/ws-evt/DeliveryFormats/Unwrap"/>
(10)         <wsdl:definitions>
(11)           ...
(12)           <wsdl:service ...>
(13)             ...
(14)             <wsp:Policy xmlns:wsp="..." wmlns:sp="...">
(15)               <sp:SymmetricBinding>
(16)                 <wsp:Policy>
(17)                   <sp:ProtectionToken>
(18)                     <wsp:Policy>
(19)                       <sp:SecureConversationToken ...>
(20)                         ...
(21)                       </sp:SecureConversationToken>
(22)                     </wsp:Policy>
(23)                   </sp:ProtectionToken>
(24)                 </wsp:Policy>
(25)               </sp:SymmetricBinding>
(26)             </wsp:Policy>
(27)           </service>
(28)         </wsdl:definitions>
(29)       </wse:EventSource>
(30)     </wsp:Policy>
(31)   </wsdl:service>
(32) </wsdl:definitions> 

This example shows the WSDL for a stockQuote service. As indicated on lines (08) through (29), this endpoint also acts as a WS-Eventing event source. The endpoint supports sending notification in the "Unwrapped" format - line (09). Line (10) through (28) provides the WSDL for the WS-Eventing features. In particular, lines (14) through (26) indicates that the WS-Eventing messages need to be protected using WS-SecureConversation.

This example could have also been written by using metadata references:

(01) <wsdl:definitions>
(02)   ...
(03)   <wsdl:service name="stockQuote">
(04)     <wsdl:port binding="..." name="...">
(05)       <soap:address location="http://example.com"/>
(06)     </wsdl:port>
(07)     <wsp:Policy>
(08)       <wse:EventSource>
(09)         <wse:FormatName uri="http://www.w3.org/2010/03/ws-evt/DeliveryFormats/Unwrap"/>
(10)         <mex:Location URL="http://example.com/EventingWSDL"
(11)                        Type="wsdl:definitions"/>
(12)       </wse:EventSource>
(13)     </wsp:Policy>
(14)   </wsdl:service>
(15) </wsdl:definitions> 

In this case the embedded WS-Eventing WSDL that is supported by the stockQuote service has been replaced by a mex:Location element. The WSDL can now be retrieved via an HTTP GET to the URL specified on line (10).

8.1 Endpoint References Containing Metadata

The issuer of a WS-Addressing endpoint reference MAY include metadata for that service inside the endpoint reference itself. This mechanism simplifies the bootstrapping of the service interaction on the requester side by avoiding additional calls to retrieve the Web service metadata for the service endpoint.

Embedding the metadata (including a mex:Metadata element) inside an endpoint reference's wsa:Metadata element allows the issuer of the endpoint reference to include metadata by value or by reference, according to the options described in 4 Web Services Metadata Collection and 7 Metadata References. The outline of a [WS-Addressing] endpoint reference which includes Web services metadata is as follows:

<wsa:EndpointReference ...>
     <wsa:Address>xs:anyURI</wsa:Address>
     <wsa:ReferenceParameters> xs:any* </wsa:ReferenceParameters> ?
     <wsa:Metadata>
       ( <mex:Location .../> |
         <mex:Reference ...> ... </mex:Reference> |
         <mex:Metadata ...> ... </mex:Metadata> ) *
         xs:any*
     </wsa:Metadata> ?
     xs:any*
</wsa:EndpointReference>

/wsa:EndpointReference/wsa:Metadata/mex:Location

This repeating OPTIONAL element MAY appear as a direct child of the wsa:Metadata endpoint reference element.

/wsa:EndpointReference/wsa:Metadata/mex:Reference

This repeating OPTIONAL element MAY appear as a direct child of the wsa:Metadata endpoint reference element.

/wsa:EndpointReference/wsa:Metadata/mex:Metadata

This repeating OPTIONAL element MAY appear as a direct child of the wsa:Metadata endpoint reference element. Note: It MAY also be possible to combine multiple mex:Metadata elements into one mex:Metadata element, however, it is RECOMMENDED that multiple mex:Metadata elements be used.

/wsa:EndpointReference/wsa:Metadata/xs:any

This extensibility point, defined by WS-Addressing, can be used for embedding additional metadata.

In example Example 8-1, a [WS-Addressing] endpoint reference contains WSDL metadata by value that identifies the binding used to access the service endpoint:

(01) <wsa:EndpointReference
(02)     xmlns:wsa='http://www.w3.org/2005/08/addressing'>
(03)   <wsa:Address>http://services.example.org/stockquote</wsa:Address>
(04)   <wsa:Metadata>
(05)     <wsdl:definitions
(06)         name='StockQuote'
(07)         targetNamespace='http://services.example.org/stockquote'
(08)         xmlns:tns='http://services.example.org/stockquote'
(09)         xmlns:wsoap='http://schemas.xmlsoap.org/wsdl/soap/'
(10)         xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'
(11)         xmlns:wsp='http://www.w3.org/ns/ws-policy'
(12)         xmlns:msgs='http://services.example.org/stockquote/schemas
(13)         xmlns:xs='http://www.w3.org/2001/XMLSchema'>
(14)       <wsdl:import
(15)           namespace='http://services.example.org/stockquote'
(16)           location='http://services.example.org/stockquote/schemas'/>
(17)       <wsdl:portType name='StockQuotePortType'>
(18)         <wsdl:operation name='GetLastTradePrice'>
(19)           <wsdl:input message='msgs:GetLastTradePriceInput'
(20)                       name='GetLastTradePriceInput'/>
(21)           <wsdl:output message='msgs:GetLastTradePriceOutput'
(22)                        name='GetLastTradePriceOutput'/>
(23)         </wsdl:operation>
(24)       </wsdl:portType>
(25)       <wsdl:binding name='StockQuoteBinding'
(26)             type='tns:StockQuotePortType'>
(27)         <wsp:PolicyReference
(28)             URI='http://services.example.org/stockquote/policy' />
(29)         <wsoap:binding style='document'
(30)                  transport='http://schemas.xmlsoap.org/soap/http'/>
(31)         <wsdl:operation name='GetLastTradePrice'>
(32)           <wsoap:operation soapAction='http://services.example.org/stockquote/GetLastTradePrice' />
(33)           <wsdl:input name='GetLastTradePriceInput'>
(34)             <wsoap:body use='literal'/>
(35)           </wsdl:input>
(36)           <wsdl:output name='GetLastTradePriceOutput'>
(37)             <wsoap:body use='literal'/>
(38)           </wsdl:output>
(39)         </wsdl:operation>
(40)       </wsdl:binding>
(41)       <wsdl:service name='StockQuoteService'>
(42)         <wsdl:port name='StockQuotePort'
(43)                    binding='tns:StockQuoteBinding' >
(44)           <wsoap:address
(45)                 location='http://services.example.org/stockquote'/>
(46)         </wsdl:port>
(47)       </wsdl:service>
(48)     </wsdl:definitions>
(49)   </wsa:Metadata>
(50) </wsa:EndpointReference> 

Lines 5-48 show the way the WSDL of the Web service endpoint is included 'by value'.

(01) <wsa:EndpointReference ...>
(02)   <wsa:Address>http://services.example.org/stockquote</wsa:Address>
(03)   <wsa:Metadata>
(04)     <mex:Reference Type="mex:Metadata" ...>
(05)       <wsa:Address>
(06)         http://services.example.org/stockquote/metadata
(07)       </wsa:Address>
(08)       <wsa:Metadata>
(09)         <wsdl:definitions ...>
(10)           <!-- WS-Transfer WSDL portType plus binding -->
(11)         </wsdl:definitions>
(12)       </wsa:Metadata>
(13)     </mex:Reference>
(14)   </wsa:Metadata>
(15) </wsa:EndpointReference> 

Example 8-2 shows an example of a Web service endpoint reference in which the Metadata element contains a single mex:Reference element to a metadata resource (lines 4-13) the representation of which is mex:Metadata as hinted by the value of the Type attribute (line 4). The metadata reference contains a Metadata element (lines 8-12) which contains the necessary metadata for interacting with the metadata resource through [WS-Transfer] operations. Since the mex:Reference is an endpoint reference to a [WS-Transfer] resource, the embedded metadata includes the [WS-Transfer] WSDL portType and the necessary binding information for communicating with that resource.

(01) <wsa:EndpointReference ...>
(02)   <wsa:Address>http://services.example.org/stockquote</wsa:Address>
(03)   <wsa:Metadata>
(04)     <mex:Reference Type='http://www.w3.org/2010/03/ws-mex'>
(05)       <wsa:Address>
(06)         http://services.example.org/stockquote/metadata
(07)       </wsa:Address>
(08)       <wsa:Metadata>
(09)         <!-- Ref to the WS-Transfer WSDL -->
(10)         <mex:Location URL='http://example.org/sq/TransferWSDL'
(11)                       Type='wsdl:definitions'/>
(12)       </wsa:Metadata>
(13)     </mex:Reference>
(14)   </wsa:Metadata>
(15) </wsa:EndpointReference> 

Example 8-3 shows an alternative way to represent Example 8-2. It shows an example of a Web service endpoint reference in which the Metadata element contains a single mex:Reference element to a metadata resource (lines 4-13) the representation of which is mex:Metadata as hinted by the value of the Type attribute (line 4). The metadata reference contains a Metadata element (lines 8-12) which contains the necessary metadata for interacting with the metadata resource through [WS-Transfer] operations. Since the mex:Reference is an endpoint reference to a [WS-Transfer] resource, the mex:Location element is a reference to the [WS-Transfer] WSDL which includes the portType and the necessary binding information for communicating with that resource.

In example Example 8-4, a endpoint reference to a service endpoint contains the metadata to allow requesters to issue a GetWSDL request against it.

(01) <wsa:EndpointReference ...>
(02)   <wsa:Address>http://services.example.org/stockquote</wsa:Address> 
(03)   <wsa:Metadata> 
(04)     <wsp:PolicyAttachment>
(05)       <wsp:AppliesTo>                       
(06)         <!-- Following according to: http://www.w3.org/TR/ws-policy-attach/#uri-domain-expression --> 
(07)         <!-- with URI syntax from:
(08)              http://www.w3.org/TR/wsdl11elementidentifiers/ -->
(09)         <wsp:URI> 
(10)           http://www.w3.org/2010/03/ws-mex#wsdl1.PortTypeOperation(GetWSDL) 
(11)         </wsp:URI>
(12)       </wsp:AppliesTo> 
(13)       <wsp:Policy> ... </wsp:Policy>  
(14)     </wsp:PolicyAttachment>            
(15)   </wsa:Metadata>
(16) </wsa:EndpointReference> 

Example 8-4 shows an example of a endpoint reference to a service endpoint. The endpoint reference contains metadata associated with the service endpoint (lines 3-15) and the Policy metadata (lines 4-14) which contains the necessary metadata for interacting with the endpoint through WS-MetadataExchange. The metadata for the WS-MetadataExchange interaction is of policy attachment (line 4). The policy attachment (lines 4-14) defines the policy (line 13) and the GetWSDL operation to which the policy applies (lines 5-12).

Alternatively, Example 8-4 could have been written with the WS-MetadataExchange Policy Assertion embedded directly into the EPR along with the necessary Policy Assertions, as shown in Example 8-5:

(01) <wsa:EndpointReference ...>
(02)   <wsa:Address>http://services.example.org/stockquote</wsa:Address> 
(03)   <wsa:Metadata> 
(04)     <wsp:Policy>
(05)       <mex:MetadataExchange>
(06)         <wsp:Policy> ... </wsp:Policy>
(07)       </mex:MetadataExchange>
(08)     </wsp:Policy>
(09)   </wsa:Metadata>
(10) </wsa:EndpointReference> 

Example 8-5 shows an example of a endpoint reference to a service endpoint. The endpoint reference contains Policy metadata that can be used to properly interact with the service. In this case the Policy contains the mex:MetadataExchange Policy Assertion (lines 5-7) indicating that it supports the WS-MetadataExchange specification. Line 6 contains a Policy Assertion that further qualifies how a requester would invoke the WS-MetadataExchange operations. For example, if the Policy Assertion on line 6 contains a security assertion then all WS-MetadataExchange message exchanges would need to be protected using the specified security mechanism.

Note: The WS-RA WG is interested in Last Call feedback on the use of nested policy expressions.

8.2 Associating Policies with Endpoint References

It is desirable for components that provide EPRs to other components to be able to efficiently communicate the effective policies of the endpoints referenced by those EPRs. For example, a subscriber might wish to indicate to an event source that the notification messages sent as part of a subscription needs to be digitally signed. Although the mechanisms described in 8.1 Endpoint References Containing Metadata can be used to communicate the complete set of policies associated with an endpoint, the relationship of these policies to specific bindings, operations, or messages cannot be determined without additional information such as WSDL documents or wsp:PolicyAttachment elements.

A single wsp:Policy or wsp:PolicyReference element MAY appear as a child of the /wsa:EndpointReference/wsa:Metadata element.

<wsa:EndpointReference>
  <wsa:Address> xs:anyURI </wsa:Address>
  <wsa:ReferenceParameters> xs:any* </wsa:ReferenceParameters>
    <wsa:Metadata>
      ( <wsp:Policy ...> ... </wsp:Policy> |
        <wsp:PolicyReference ...> ... </wsp:PolicyReference> ) ?
  </wsa:Metadata>
</wsa:EndpointReference>

If multiple alternatives are desired, the operators defined in [WS-Policy] can be used to specify such alternatives within the single wsp:Policy element or the element referenced by the wsp:PolicyReference.

Policies that appear in an endpoint reference in this manner have Endpoint Policy Subject. Endpoint Policy Subject is defined as follows:

The wsp:Policy or wsp:PolicyReference element, when present, represents the capabilities and requirements of the endpoint referenced by the EPR as defined by Section 3, "Policy Model", in the [WS-Policy] specification. Policy attached to an EPR in this manner MUST be applicable to all message exchanges using the endpoint referenced by that EPR.

(01) <wse:NotifyTo xmlns:wsa="http://www.w3.org/2005/08/addressing"
(02)               xmlns:wse="http://www.w3.org/2010/03/ws-evt">
(03)   <wsa:Address>http://www.example.com/EventSink/OnPriceChange</wsa:Address>
(04)   <wsa:RerenceParameters>
(05)     ...
(06)   </wsa:ReferenceParameters>
(07)   <wsa:Metadata>
(08)     <wsp:Policy xmlns:wsp="..." wmlns:sp="...">
(09)       <sp:SymmetricBinding>
(10)         <wsp:Policy>
(11)           <sp:ProtectionToken>
(12)             <wsp:Policy>
(13)               <sp:SecureConversationToken ...>
(14)                 ...
(15)               </sp:SecureConversationToken>
(16)             </wsp:Policy>
(17)           </sp:ProtectionToken>
(18)         </wsp:Policy>
(19)       </sp:SymmetricBinding>
(20)     </wsp:Policy>
(21)   </wsa:Metadata>
(22) </wse:NotifyTo>

Example 8-6 shows a WS-Eventing NotifyTo EPR that refers to the endpoint to which an event source sends notification messages. Attached to this EPR is a Policy (lines 8-20) that indicates that WS-SecureConversation needs to be used when sending messages to this endpoint.

The [WS-Addressing] specification discusses caveats to the validity of Metadata information. These apply to policies contained within the wsa:Metadata element as discussed in this section.

The relationship, if any, between policies contained within the wsa:Metadata element and any other policies that might apply to the endpoint referred to by the containing EPR (e.g. policies that might appear in a WSDL document that describes one or more of the services offered by that endpoint) is not defined by this specification.

11.1 MetadataExchange Assertion

Services indicate support for the WS-MetadataExchange specification through the use of the Web Services Policy - Framework [WS-Policy] and Web Services Policy - Attachment [WS-PolicyAttachment] specifications.

This specification defines a policy assertion (mex:MetadataExchange). The mex:MetadataExchange policy assertion applies to the endpoint policy subject.

For WSDL 1.1, these assertions MAY be attached to wsdl11:portType, wsdl11:port or wsdl11:binding. For WSDL 2.0, they MAY be attached to wsdl20:interface, wsdl20:endpoint or wsdl20:binding.

The meaning of this assertion, when present in a policy alternative, is that WS-MetadataExchange is REQUIRED to communicate with the subject and that the subject supports WS-MetadataExchange.

In order to indicate that the subject supports WS-MetadataExchange but does not require its use, an additional policy alternative SHOULD be provided which does not contain this assertion. The compact authoring style for an OPTIONAL policy assertion (the wsp:Optional attribute) provided by WS-Policy MAY be used to indicate two policy alternatives, one which contains the policy assertion, and another which does not.

The normative outline of this assertion is:

<mex:MetadataExchange ...>
  <mex:GetMetadataSupported ...>
    <mex:MetadataExchangeDialect URI="xs:anyURI" ...>
      <mex:MetadataContent URI="xs:anyURI" ...> 
        xs:any*
      </mex:MetadataContent> *
    </mex:MetadataExchangeDialect> * 
    xs:any*
  </mex:GetMetadataSupported> ?
  xs:any*
</mex:MetadataExchange>

The following describes additional, normative constraints on the outline listed above:

/mex:MetadataExchange

This policy assertion specifies that WS-MetadataExchange protocol MUST be used when communicating with this service endpoint. This assertion has Endpoint Policy Subject.

/mex:MetadataExchange/mex:GetMetadataSupported

When present, this OPTIONAL parameter indicates that the GetMetadata operation is supported by this endpoint.

/mex:MetadataExchange/mex:GetMetadataSupported/mex:MetadataExchangeDialect@URI

When present, this OPTIONAL parameter indicates support for the specified MetadataExchange Dialect IRI.

/mex:MetadataExchange/mex:GetMetadataSupported/mex:MetadataExchangeDialect/mex:MetadataContent

When present, this OPTIONAL parameter indicates support for the specified MetadataExchange content IRI.

/mex:MetadataExchange/mex:GetMetadataSupported/mex:MetadataExchangeDialect/mex:MetadataContent/xs:any

This extensibility point allows for additional MetadataContent specific metadata to be included within the policy assertion. Any metadata that appears is scoped to the use of the specified MetadataContent URI.

/mex:MetadataExchange/mex:GetMetadataSupported/mex:MetadataExchangeDialect/xs:any

This extensibility point allows for additional Metadata Dialect specific metadata to be included within the policy assertion. Any metadata that appears is scoped to the use of the specified Metadata Dialect URI.

/mex:MetadataExchange/mex:GetMetadataSupported/xs:any

This extensibility point allows for additional metadata specific to the GetMetadata operation to be included within the policy assertion. Any metadata that appears is scoped to the use of the GetMetadata operation.

/mex:MetadataExchange/xs:any

This extensibility point allows for additional WS-MetadataExchange specific metadata to be included within the policy assertion - e.g. WS-MetadataExchange WSDL, or nested policy assertions related to the WS-MetadataExchange message exchanges. Any metadata that appears is scoped to the operations and features of the WS-MetadataExchange specification.

Note: The WS-RA WG is interested in Last Call feedback on the use of nested policy expressions.

14.1 Normative References

RFC 2119

Key words for use in RFCs to Indicate Requirement Levels , S. Bradner, Author. Internet Engineering Task Force, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.

RFC 3986

Uniform Resource Identifier (URI): Generic Syntax , T. Berners-Lee, R. Fields and L. Masinter, Authors. Network Working Group, January 2005. Available at http://www.ietf.org/rfc/rfc3986.txt.

RFC 3987

Internationalized Resource Identifiers (IRIs) , M. Duerst and M. Suignard, Authors. Internet Engineering Task Force, January 2005. Available at http://www.ietf.org/rfc/rfc3987.txt.

SOAP11

W3C Note, "Simple Object Access Protocol (SOAP) 1.1" , D. Box, et al, Editors. World Wide Web Consortium (W3C), 8 May 2000. Available at http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.

SOAP12

W3C Recommendation, "SOAP Version 1.2 Part 1: Messaging Framework" , M. Gudgin, M. Hadley, N. Mendelsohn, J-J. Moreau, H. Frystyk Nielson, Editors. World Wide Web Consortium (W3C), 27 April 2007. Available at http://www.w3.org/TR/soap12-part1/.

WS-Addressing

W3C Recommendation, "Web Services Addressing 1.0 (WS-Addressing)" , M. Gudgin, M. Hadley, T. Rogers, Editors. World Wide Web Consortium (W3C), 9 May 2006. Available at http://www.w3.org/TR/ws-addr-core.

WS-Policy

W3C Recommendation, "Web Services Policy (WS-Policy) 1.5 - Framework" , A. Vedamuthu, et al., Editors. World Wide Web Consortium (W3C), 4 September 2007. Available at http://www.w3.org/TR/ws-policy/.

WS-PolicyAttachment

W3C Recommendation, "Web Services Policy (WS-Policy) 1.5 - Attachment" , A. Vedamuthu, et al., Editors. World Wide Web Consortium (W3C), 4 September 2007. Available at http://www.w3.org/TR/ws-policy-attach/.

WS-Transfer

W3C Working Group Draft, "Web Services Transfer (WS-Transfer)1.1" , D. Davis, et al., Editors. World Wide Web Consortium (W3C), 15 September 2009. Available at http://www.w3.org/TR/ws-transfer.

WSDL11

W3C Note, "Web Services Description Language (WSDL) 1.1" , E. Christensen, et al., Editors. World Wide Web Consortium (W3C), 15 March 2001 Available at http://www.w3.org/TR/2001/NOTE-wsdl-20010315.

XML Infoset

W3C Recommendation, "XML Information Set (Second Edition)" , J. Cowan, R. Tobin, Editors. World Wide Web Consortium (W3C), 4 February 2004. Available at http://www.w3.org/TR/xml-infoset.

XMLSchema - Part 1

W3C Recommendation, "XML Schema Part 1: Structures (Second Edition)" , H. Thompson, et al., Editors. World Wide Web Consortium (W3C), 28 October 2004. Available at http://www.w3.org/TR/xmlschema-1/.

XMLSchema - Part 2

W3C Recommendation, "XML Schema Part 2: Datatypes (Second Edition)" , P. Biron, A. Malhotra, Editors. World Wide Web Consortium (W3C), 28 October 2004. Available at http://www.w3.org/TR/xmlschema-2/.

14.2 Informative References

WS-SecureConversation

OASIS Standard, "Web Services Secure Conversation (WS-SecureConversation) 1.4" , A. Nadalin, et al., Editors. Organization for the Advancement of Structured Information Standards (OASIS), 2 February 2009. Available at http://docs.oasis-open.org/ws-sx/ws-secureconversation/v1.4/os/ws-secureconversation-1.4-spec-os.doc.

WS-Security

OASIS Standard, "Web Services Security: SOAP Message Security 1.1" , K. Lawrence, C. Kaler, Editors. Organization for the Advancement of Structured Information Standards (OASIS), 1 February 2006. Available at http://docs.oasis-open.org/wss/v1.1/wss-v1.1-spec-os-SOAPMessageSecurity.pdf.

WS-SecurityPolicy

OASIS Standard, "Web Services Security Policy (WS-SecurityPolicy) 1.3, Version 1.1" , K. Lawrence, C. Kaler, Editors. Organization for the Advancement of Structured Information Standards (OASIS), 2 February 2009. Available at http://docs.oasis-open.org/ws-sx/ws-securitypolicy/v1.3/os/ws-securitypolicy-1.3-spec-os.doc.

WS-Trust

OASIS Standard, "Web Services Trust (WS-Trust) 1.4" , K. Lawrence, C. Kaler, Editors. Organization for the Advancement of Structured Information Standards (OASIS), 2 February 2009. Available at http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/os/ws-trust-1.4-spec-os.doc.