This specification intends to meet the following requirements:

illustrates a sample GetWSDL request for the WSDL metadata document of a service.

lists a sample response to the request in .

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

illustrates a sample Get request for a resource' s representation.

The sample request message of is a 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.

illustrates a sample response to the request of .

The message of is a response message to the request of . The content of the [Body] (lines 18-44) is a mex:Metadata element with metadata about the Web service endpoint (lines 20-42). The mex:Metadata contains three MetadataSections. The first MetadataSection (lines 21-25) contains the of the Web service endpoint. The second MetadataSection (lines 26-32) contains the location of the XML Schemas , used by the WSDL document. The schemas can be retrieved through an HTTP GET request at the identified URL (lines 29-31). The third MetadataSection (lines 33-41) contains the endpoint reference (lines 36-40) of a resource the representation of which is a document as indicated by the Dialect attribute (line 34).

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 36-40 of , some endpoints MAY support explicit requests for metadata via the GetMetadata operation. illustrates a sample GetMetadata request for the .

Lines 8-10 in indicate this is a GetMetadata request. As lines 19-22 indicate, this request is for the policy of the Web service endpoint (line 7).

lists a sample response to the request in .

Lines 8-10 in indicate this message is a response to a GetMetadata request, and lines 11-13 indicate that it is a response to the request in . 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 was directed.

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 .

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

In addition to Message Information Header properties , this specification uses the following properties to define messages:

These properties bind to a SOAP Envelope as follows:

This specification can be used in terms of XML Information Set (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.

The term "generate" is used in relation to the various faults defined by this specification to imply that a fault is produced and no further processing SHOULD be performed. In these cases the fault SHOULD be transmitted. However, there might be reasons when a compliant implementation can choose not to transmit the fault - for example, security concerns - in these situations the service MAY choose not to transmit the fault.

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.

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.

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 ) 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 conform to the WS-Addressing specifications and be sent to a Web service that is addressable by an EPR (see ).

Unless otherwise noted, all IRIs are absolute IRIs and IRI comparison MUST be performed according to 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 endpoint reference, then the MetadataReference MUST refer to a resource. The referred resource MAY also support other resource management and access specifications (e.g. HTTP, WS-ResourceFramework).

Implementations are expected to support both UTF-8 and UTF-16 as described in XML 1.0.

Implementations of this specification MUST conform to the corrected version of WSDL as defined by the 'WSDL Correction' sections of WS-I Basic Profile 1.2 and WS-I Basic Profile 2.0 .

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

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 .

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

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

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

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.

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 resource, the 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:

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

Subject to authorization restrictions, services MUST return all the MetadataSections corresponding to the GetMetadata request. Note that there can be multiple MetadataSections returned for any one combination of Dialect, Identifier and Content values.

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

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

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.

A requester MAY send a PutMetadata request message to an endpoint to update 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 resource, the Put operation allows requesters to update the resource representation associated with that endpoint (i.e. the "data"), while the PutMetadata operation can be used to update that endpoint's metadata.

The normative outline for a PutMetadata request is:

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

An endpoint MUST reject a PutMetadata request if it is unable to process all of the metadata updates requested. If the dialect, identifier or content form specified in one or more MetadataSections is unsupported by the endpoint, the endpoint MUST generate a mex:UnsupportedMetadata fault. If the creation or update of the endpoint's Metadata will render the endpoint invalid (either because the metadata is of an invalid syntax for the dialect or because the metadata will cause a semantic conflict with the endpoint's definition), the endpoint MUST generate an mex:InvalidMetadata fault.

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

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

A requester MAY send a DeleteMetadata request message to an endpoint to delete 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 resource, the Delete operation allows requesters to update the resource representation associated with that endpoint (i.e. the "data"), while the DeleteMetadata operation can be used to update that endpoint's metadata.

The normative outline for a DeleteMetadata request is:

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

An endpoint MUST reject a DeleteMetadata request if it is unable to process all of the metadata deletes requested. If the dialect, identifier or content form specified in one or more of the Dialect elements is unsupported by the endpoint, the endpoint MUST generate a mex:UnsupportedMetadata fault. If the deletion of the specified Metadata will render the endpoint invalid, the endpoint MUST generate an mex:InvalidMetadata fault. Note that an otherwise valid request that refers to metadata that does not exist is not considered an error condition. Rather, the service MUST continue as if it had successfully processed that one delete request.

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

There are no additional, normative constraints on the outline listed above.

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:

The following describes additional constraints on the outline listed above:

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:

The following describes additional constraints on the outline listed above:

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

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 :

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:

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:

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

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 and . The outline of a endpoint reference which includes Web services metadata is as follows:

In example , a endpoint reference contains WSDL metadata by value that identifies the binding used to access the service endpoint:

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

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 operations. Since the mex:Reference is an endpoint reference to a resource, the embedded metadata includes the WSDL portType and the necessary binding information for communicating with that resource.

shows an alternative way to represent . 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 operations. Since the mex:Reference is an endpoint reference to a resource, the mex:Location element is a reference to the WSDL which includes the portType and the necessary binding information for communicating with that resource.

In example , an endpoint reference to a service endpoint contains the metadata to allow requesters to issue a GetWSDL request against it.

shows an example of an 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, could have been written with the WS-MetadataExchange Policy Assertion embedded directly into the EPR along with the necessary Policy Assertions, as shown in :

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, the Policy Assertion on line 6 might contain assertions to indicate how all WS-MetadataExchange messages are to be consturcted.

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

If multiple alternatives are desired, the operators defined in 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 specification. Policy attached to an EPR in this manner MUST be applicable to all message exchanges using the endpoint referenced by that EPR.

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.

Note that in some cases the context in which an EPR appears might imply the version of SOAP that messages addressed to that EPR are to use. In this example, without an explicit use of the SOAP assertion, the Notifications will most likely be sent using the same version of SOAP that was used to carry the Subscribe message.

The 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.

This fault MUST be generated when one or more metadata dialect(s) specified on the request message are unsupported by the endpoint.

This fault MUST be generated when the metadata passed on the PutMetadata request message is invalid or when the Metadata would render the endpoint invalid.

There are cases in which the metadata used to describe a service might be considered sensitive information. In these cases it is advisable for services to authenticate and authorize consumers as part of the processing of any requests for this metadata. However, because the security aspects of a service (e.g. supported protocols and token formats, cipher suites, etc.) are usually described using metadata (i.e. the constructs defined by WS-SecurityPolicy), there is an obvious dilemma when attempting to protect metadata in this way. Services wishing to protect access to their metadata are advised to use the mechanisms described in to advertise the security requirements for clients wishing to access metadata via the mechanisms defined in this specification.

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

This specification defines a policy assertion (mex:MetadataExchange). The normative outline of this assertion is:

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