The Web services specifications (WS-*) are designed to be composed with each other to provide a rich set of tools for the Web services environment. This specification specifically relies on other Web services specifications to provide secure, reliable, and/or transacted message delivery and to express Web service metadata.

Web services use metadata to describe what other endpoints need to know to interact with them. Specifically, describes the capabilities, requirements, and general characteristics of Web services; describes abstract message operations, concrete network protocols, and endpoint addresses used by Web services; XML Schema , describes the structure and contents of XML-based messages received by and sent by Web services.

To bootstrap communication with Web services this specification defines how metadata can be treated as resources for retrieval purposes, how metadata can be embedded in Web service endpoint references, and how Web service endpoints can optionally support a request-response interaction for the retrieval of metadata. When the type of metadata sought is clearly known, e.g., , a requester may indicate that only that type should be returned; where additional types of metadata are being used, or are expected, or when a requester needs to retrieve all of the metadata relevant to subsequent interactions with an endpoint, a requester may indicate that all available metadata, regardless of their types, are expected.

The mechanisms defined herein are intended for the retrieval of metadata (i.e., Web service description information) only. They are not intended to provide a general purpose query or retrieval mechanism for other types of data associated with a Web service, such as state data, properties and attribute values, etc.

A resource is a Web service that is addressable by an endpoint reference and can be represented by an XML Infoset. The resource's representation can be retrieved using the Get operation defined in .

When the representation of a resource is mex:Metadata, as defined in Section 4, or any other document format (e.g. ,, , ) for which a mex:MetadataSection/@Dialect has been defined, then the resource is referred as 'metadata resource'. The representation of a metadata resource MAY be retrieved and/or updated as any other resource. Specifically, the representation of a metadata resource MUST be retrievable through a Get operation.

A Web service endpoint MAY have one or more associated metadata resources. A Web service endpoint MAY also support direct retrieval of metadata by requesters using a GetMetadata operation directed to the Web service endpoint itself, as described in .

A metadata resource MAY support other operations defined by , such as Put (e.g. to allow update of non-static metadata by authorized agents), or other resource management and access specifications (e.g. HTTP, WS-ResourceFramework).

The Web service Metadata element is a collection of metadata units such as definitions, documents, expressions, etc. Each unit corresponds to metadata for a given scope, domain, or namespace. The collection of units is represented by a Metadata element, and units within the collection are represented by Metadata Section elements.

To facilitate processing, Metadata Sections are tagged with a @Dialect and (optionally) @Identifier of the metadata unit. To ensure scalability, a unit of metadata may be included in-line within its Metadata Section or may be included by reference, either an endpoint reference (Metadata Reference) or a URL (Location).

The outline for the Metadata element is:

The following describes additional constraints on the outline listed above:

This specification defines the following values for Dialect; other specifications should define values for Dialect for their metadata format(s).

If there is more than one metadata unit with the same Dialect, e.g., more than one XML Schema document, including them all, one per Metadata Section, is explicitly encouraged.

If there is more than one metadata section with the same identifier, e.g., more than one XML Schema in the same target namespace, including them all, one per metadata section, is explicitly encouraged.

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.

This specification provides several mechanisms to aid service endpoints and service requesters in bootstrapping the interaction. In particular, the mechanisms described in allow issuers of endpoint references to include sufficient protocol binding information to allow requesters to issue a Get request against a metadata resource, or a GetMetadata request against a service endpoint, in order to retrieve all the information needed to use the service.

When that information is not available, however, requesters must rely on contextual or out-of-band information in order to choose the protocol binding most appropriate to use in retrieving Web service metadata. Furthermore, specific protocol bindings for metadata retrieval may be defined by communities within the context of particular application domains.

It is strongly RECOMMENDED that the communication between Web services be secured using the mechanisms described in WS-Security . In order to properly secure messages, the body and all relevant headers need to be included in the signature. Specifically, any standard messaging headers, such as those from WS-Addressing , need to be signed with the body in order to "bind" the two together.

Different security mechanisms may be desired depending on the frequency of messages. For example, for infrequent messages, public key technologies may be adequate for integrity and confidentiality. However, for high-frequency events, it may be more performant to establish a security context for the events using the mechanisms described in and . It should be noted that if a shared secret is used it is RECOMMENDED that derived keys be used to strengthen the secret as described in WS-SecureConversation.

Requests for metadata that are not available to anonymous parties are strongly RECOMMENDED to require usage of WS-Security so that the requester can be authenticated and authorized to access the indicated metadata. Similarly, integrity and confidentiality SHOULD be used whenever metadata has restricted access.

Recipients of metadata are RECOMMENDED to validate the signature to authenticate and verify the integrity of the data. Specifically, recipients SHOULD verify that the sender has the right to "speak" for the metadata. This is important because some metadata, such as schemas, have embedded target URIs that might be outside the scope of the sender.

Additionally, some metadata formats, such as policies , may have embedded security semantics. These SHOULD be verified using the same considerations outlined in this section.

The following list summarizes common classes of attacks that apply to this protocol and identifies the mechanism to prevent/mitigate the attacks:

This specification has been developed as a result of joint work with many individuals and teams, including: Ashok Malhotra (Oracle Corp.), Asir Vedamuthu (Microsoft Corp.), Bob Freund (Hitachi, Ltd.), Doug Davis (IBM), Fred Maciel (Hitachi, Ltd.), Geoff Bullen (Microsoft Corp.), Gilbert Pilz (Oracle Corp.), Greg Carpenter (Microsoft Corp.), Jeff Mischkinsky (Oracle Corp.), Katy Warr (IBM), Li Li (Avaya Communications), Mark Little (Red Hat), Prasad Yendluri (Software AG), Sreedhara Narayanaswamy (CA), Sumeet Vij (Software AG), Vikas Varma (Software AG), Wu Chou (Avaya Communications), Yves Lafon (W3C)