This specification intends to meet the following requirements:

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-Metadata Exchange 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 16-79) is a mex:Metadata element with metadata about the Web service endpoint (lines 17-78). The mex:Metadata contains three Metadata Sections. The first Metadata Section (lines 18-61) contains the of the Web service endpoint. The second Metadata Section (lines 62-68) 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 65-67). The third Metadata Section (lines 69-77) contains the endpoint reference (lines 72-75) of a resource the representation of which is a document as indicated by the Dialect attribute (line 70). The WS-Policy document is the same as the one indicated in the WSDL document (lines 39-40).

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 72-76 of , some endpoints MAY choose to support explicit request for metadata. illustrates a sample GetMetadata request for the .

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

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 16-26 contain a single Metadata Section (lines 17-25); line 18 indicates that the metadata in this section is of type, or Dialect, WS-Policy while line 19 identifies a specific policy document. Line 22 would have contained the policy expressions for the Web service endpoint to which the GetMetadata request of was directed.

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 .

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

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 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 understand 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 Metadata Reference, which is a endpoint reference, then the Metadata Reference MUST refer to a resource. The referred resource MAY also support other resource management and access specifications (e.g. HTTP, WS-ResourceFramework).

To retrieve the representation of a metadata resource, a requester MAY send a Get request message to the metadata resource's endpoint. The WS-Transfer Get request fetches a one-time snapshot of the metadata. The metadata associated with a service endpoint MAY be available as multiple metadata resources.

The representation of a metadata resource MAY be a mex:Metadata element which MAY contain one or more mex:MetadataSection children. Each MetadataSection is identified by a specific Dialect and contains information whose format and content depend on the Dialect.

The representation of a metadata resource MAY also be any other document format (e.g. , , , ) for which a Dialect value is defined.

A requester MAY send a GetMetadata request message to an endpoint to retrieve the metadata associated with that endpoint. A service endpoint MAY support the GetMetadata request. 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:

Other message information headers defined by WS-Addressing MAY be included in the request and response messages, according to the usage and semantics defined in WS-Addressing.

An endpoint MAY respond with a fault message using the standard fault codes defined in WS-Addressing (e.g., wsa:ActionNotSupported).

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.

describes two mechanisms that allow requesters to retrieve ("pull metadata") Web services metadata from an endpoint (GetMetadata) or a metadata resource (WS-Transfer Get).

In addition to these mechanisms, the issuer of a service endpoint reference MAY include Web services metadata for that service inside the endpoint reference itself. This mechanism ("push metadata") simplifies the bootstrapping of the service interaction on the requester side by avoiding additional calls to retrieve (pull) the Web service metadata for the service endpoint.

Embedding a mex:Metadata element inside an endpoint reference allows the issuer of the endpoint reference to include metadata by value or by reference, according to the options described in . The outline of a endpoint reference which includes Web services metadata is as follows:

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

Lines 4-62 in show the way a Metadata element can be embedded in the endpoint reference of a service. The Metadata element contains two Metadata Sections. In the first one (lines 6-51) the WSDL of the Web service endpoint is included 'by value'. In the second Metadata Section (lines 52-60) an endpoint reference to a metadata resource is shown. The representation of the metadata resource is an XML Schema as hinted by the Dialect attribute (line 53) and is distinguished from other XML Schemas for that Web service endpoint by the value of Identifier attribute (line 54) which in this case happens to be the same as the value of the targetNamespace attribute of the XML Schema. The Get operation can be used to retrieve the referred XML Schema. Since no metadata is available about the metadata resource, it is assumed that binding-related information was communicated out-of-band (e.g. an application domain-specific specification has defined a binding for that domain) so that the requester could send a Get request to the metadata resource's endpoint, as defined in .

shows an example of a Web service endpoint reference in which the Metadata element contains a single Metadata Reference element to a metadata resource (lines 8-21) the representation of which is mex:Metadata as hinted by the value of the Dialect attribute (line 7). The Metadata Reference contains a Metadata element (lines 13-19) which contains the necessary metadata for interacting with the metadata resource through operations. Since the Metadata 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.

It is desirable for components that provide EPRs to other components to be able to communicate the effective policies of the endpoints referenced by those EPRs. For example, a subscriber may wish to indicate to an event source that the notification messages sent as part of a subscription must 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 as part of this single policy, the operators defined in can be used to specify such a structure.

The scope of a Policy in an EPR is the endpoint referenced by that EPR. The assertions within the alternatives contained by a Policy in an EPR MUST have endpoint policy subject. Policy scopes and subjects are defined in .

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

The specification discusses caveats to the validity of Metadata information. These apply to Policies embedded within the wsa:Metadata element as discussed in this section.

The mechanism for indicating that a binding or endpoint conforms to the WS-MetadataExchange specification is through the use of the Web Services Policy - Framework and Web Services Policy - Attachment specifications.

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

For WSDL 1.1, these assertions may be attached to wsdl11:port or wsdl11:binding. For WSDL 2.0, they may be attached to wsdl20:endpoint or wsdl20:binding. A policy expression containing the wsmxp:MetadataExchange policy assertion MUST NOT be attached to a wsdl:portType or wsdl20:interface.

The wsmxp:MetadataExchange policy assertion is a nested policy container assertion. 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:

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

Note: Metadata resources use the corresponding policy assertions for the WS-Transfer operation that they support.