Abstract

This specification defines how metadata
associated with a Web service endpoint can be represented as
[WS-Transfer] resources or HTTP resources, how metadata can
be embedded in [WS-Addressing]
endpoint references, and how metadata could be
retrieved from a metadata resource, and how metadata associated with
implicit features can be advertised.

Status of this Document

This section describes the status of this document at the time
of its publication. Other documents may supersede this document.
A list of current W3C publications and the latest revision of
this technical report can be found in the
W3C technical reports index
at http://www.w3.org/TR/.

This document is the Last Call Working Draft of the Web Services Metadata Exchange (WS-MetadataExchange)
specification; It is intended to be published and maintained as a
W3C Recommendation after review and refinement.

The Web Services Resource Access Working Group (WSRA WG) believes to
have addressed all issues brought forth through previous
Working Draft iterations (See the [changelog]).
The Working Group encourages feedback about this document.
The Last Call period extends through 11 May 2010.

Publication as a Working Draft does not imply endorsement by the
W3C Membership. This is a draft document and may be updated, replaced
or obsoleted by other documents at any time. It is inappropriate to
cite this document as other than work in progress.

Appendices

1 Composable Architecture

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.

2 Introduction

Web services use metadata to describe what other endpoints need to know
to interact with them. Specifically, [WS-Policy]
describes the capabilities, requirements, and general characteristics
of Web services; [WSDL11] describes abstract message
operations, concrete network protocols, and endpoint addresses used
by Web services; XML Schema [XMLSchema - Part 1],
[XMLSchema - Part 2] 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 a HTTP resources or as
[WS-Transfer] resources
for retrieval purposes, how metadata can be embedded in WS-Addressing
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.,
[WS-Policy], a requester MAY indicate that only that
type is to 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.

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.

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.

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

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 Notations and Terminology

This section specifies the notations, namespaces, and
terminology used in this specification.

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:

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:

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

4 Web Services Metadata Collection

The WS-MetadataExchange Metadata element is a collection of metadata units
such as [WSDL11] definitions, [XMLSchema - Part 1]
documents, [WS-Policy] 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 MetadataSection elements.

To facilitate processing, MetadataSections are tagged with a
@Dialect and (OPTIONALLY) @Identifier of the metadata unit. To ensure
scalability, a unit of metadata MAY be embedded within its
MetadataSection or MAY be included by reference, either an endpoint
reference [WS-Addressing]
(MetadataReference) or a URL (MetadataLocation).

The following describes additional constraints on the outline listed
above:

/mex:Metadata

This contains one MetadataSection child for each distinct unit of
metadata. When there is a large amount of metadata, the children
SHOULD contain MetadataReferences or MetadataLocations instead of the
actual information.

/mex:Metadata/mex:MetadataSection

This represents a single unit of metadata (e.g., a WSDL
definitions, an XML Schema document) for a given scope, domain,
or namespace. A MetadataSection contains exactly one child
element, either the embedded XML for the metadata unit, an
endpoint reference to a Metadata Resource for the metadata
unit, or a URL to metadata unit.

/mex:Metadata/mex:MetadataSection/@Dialect

This indicates the format and version of the metadata unit
contained in this MetadataSection (e.g., WSDL version 1.1). Dialect
is an absolute IRI.

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

This Dialect value indicates that the type of the metadata contained
within the MetadataSection is itself a mex:Metadata element.
When the Dialect value is used in conjunction with
mex:MetadataReference or mex:MetadataLocation, the Dialect value
provides the ability to include metadata by reference (an endpoint
reference or a URL).
Example 8-2 illustrates the use of this Dialect.

/mex:Metadata/mex:MetadataSection/@Identifier

This indicates the Identifier for the metadata unit in this
MetadataSection. Identifier is an absolute IRI.
If omitted, there is no implied value.

The interpretation of Identifier is Dialect-specific.
If the Identifier attribute is present, and the value of the
Dialect attribute of the MetadataSection is one of the values in
the table below, the Identifier attribute MUST have the indicated,
corresponding value. In other cases the value of the Identifier
attribute is not constrained.

Dialect IRI

@Identifier value

http://www.w3.org/2001/XMLSchema

xs:schema/@targetNamespace

http://schemas.xmlsoap.org/wsdl/

wsdl:definitions/@targetNamespace

http://www.w3.org/ns/ws-policy

wsp:Policy/@Name

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

/mex:Metadata/mex:MetadataSection/mex:MetadataReference

This is an endpoint reference to a metadata resource and is
of type EndpointReferenceType as defined by [WS-Addressing].
The metadata resource MUST support the Get operation
[WS-Transfer] to allow the retrieval of the
metadata unit for the MetadataSection's Dialect and Identifier
(if any). When this element is present, it MUST have no
element siblings.

/mex:Metadata/mex:MetadataSection/mex:MetadataLocation

This contains a URL to metadata, and the metadata MUST be
retrievable from that URL using the primary access mechanism for
the scheme of the URL. For example, for an HTTP URL, the
metadata MUST be retrievable by sending an HTTP GET request to
the URL. When this element is present, it MUST have no
element siblings.

/mex:Metadata/mex:MetadataSection/DialectSpecificElement

When any element other than MetadataReference or MetadataLocation is
present, the element is to be interpreted as the representation of
the metadata unit associated with the MetadataSection's Dialect
and Identifier.

When a metadata resource is addressable by an endpoint reference
the resource's representation MUST be retrievable using the Get operation
defined in [WS-Transfer] and MAY be updated as any other
[WS-Transfer] resource. When the resource is addressed by
a URL the resource's representation MUST be retrievable using an
HTTP GET and MAY be updated as any other HTTP resource.

To retrieve the representation of a metadata resource, a requester MAY
send a [WS-Transfer] Get request message to the metadata
resource's endpoint reference, or it MAY send an HTTP GET to the metadata
resource's IRI. These will fetch 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.

A Web service endpoint MAY have one or more associated metadata
resources.

It is important to note that metadata resources are themselves services.
In other words, a metadata resource can still accept GetWSDL or
GetMetadata requests, but such requests would apply to the metadata
about the metadata resource and not the original service that the metadata
resource describes.

6 Retrieving Metadata about Service Endpoints

This specification defines two mechanism by which a requester can ask
a WS-MetadataExchange compliant 'service endpoint' for its metadata:
the GetWSDL operation and the GetMetadata
operation.

GetWSDL provides the means to obtain a starting point for constructing
the relationships between the metadata documents that apply to a
service. It is useful in situations when the requester has no prior
knowledge of these relationships. The GetMetadata operation is useful
in cases where the requester is already aware of these relationships
or when it wishes to obtain a specific metadata document.

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

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:

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 Metadata References

While a service's metadata can be embedded in many different places
(for example, within an EPR, or within a feature's policy assertion),
it might be more convenient to include a reference to the metadata rather
than include the actual metadata itself. This might be simply for
brevity's sake or so the same copy of metadata can be used in many
different locations without the overhead of duplicating it.

This specification defines two mechanisms by which a metadata reference
can be used in place of metadata. These mechanisms do not modify any
semantic meaning that might be associated with the presence of the
metadata at any particular location - they are simply a syntactical
alternative to embedding the referenced metadata.

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.

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:

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:

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

8 Metadata in Endpoint References

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:

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:

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.

Example 8-3: Endpoint reference with a reference to metadata about the Metadata Reference

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.

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:

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.

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.

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.

9 Exposing Metadata for Implicitly Defined Features

An endpoint MAY indicate that it supports a specific feature by
including the feature's policy assertion within its WSDL. By doing so,
the endpoint is indicating that feature operations are
supported by that endpoint even though they do not explicitly appear in
its WSDL. An example of this is an endpoint that indicates the use
of WS-Transfer [WS-Transfer] by the use of the
wst:TransferResource WS-Policy [WS-Policy] assertion.

The Feature WSDL (the WSDL associated with these implicit operations)
MAY appear within a Feature Policy assertion and can be annotated to
indicate any endpoint specific metadata that might be needed by clients
interacting with this service. For example, the WSDL can have policy
assertions that indicate a particular security mechanism used to protect
the feature's operations supported by this endpoint. When a Feature WSDL
does not provide a concrete endpoint, the consumer MUST use the
concrete aspects of the endpoint's WSDL.

An endpoint MAY choose to expose additional metadata about the feature
by including the feature specific metadata within the feature's policy
assertion. For example, an endpoint that also supports WS-Eventing
might choose to have the following WS-Eventing Policy assertion defined:

When this policy assertion appears in a service's WSDL it indicates that
the service supports WS-Eventing, it supports sending notifications using
the 'Unwrap' format, and that it generates exactly one type of event -
a <sq:Quote> event. The Policy Assertion on line 17 indicates that the
nested policy assertions apply to the WS-Eventing operations. For
example, if line 17 includes some security related assertions then the
WS-Eventing operations would need to be secured using those security
mechanisms.

When Feature Policy Assertions contain nested Policy Assertions (as
show above in line 17), those assertions have Endpoint Policy Subject
and apply to all message exchanges related to the feature.

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

If there were additional WS-Eventing metadata available, for example
a specialized Feature WSDL document, then they would appear as a child
of the wse:EventSource element as well.

The following shows the same WS-Eventing Policy Assertion from
Example 9-1 with an embedded copy of the
WS-Eventing WSDL. As discussed above, this WSDL might be annotated to
specify additional constrains on the WS-Eventing message exchanges.

The following shows a sample WS-Eventing wse:NotifyTo endpoint
reference that might appear as part of a Subscribe request. Lines 05-08
indicate that WS-ReliableMessaging is required when sending notifications
to this endpoint. The mex:Location element, lines 06-07, is a reference
to the WS-ReliableMessaging WSDL that the event source will need to use
when transmitting the WS-ReliableMessaging protocol messages for those
notifications. For example, this WSDL might include security policy
assertions or perhaps binding information that indicates there is a
specific endpoint to which those protocol messages are to be sent - if
it is different from the address specified on line 02.

10 Security Considerations

It is strongly RECOMMENDED that the communication between Web services
be secured using the mechanisms described in WS-Security
[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
[WS-Addressing], need to be signed with the body in
order to "bind" the two together.

Different security mechanisms might be desired depending on the
frequency of messages. For example, for infrequent messages, public key
technologies might be adequate for integrity and confidentiality.
However, for high-frequency events, it might be more performant to
establish a security context for the events using the mechanisms
described in [WS-Trust] and
[WS-SecureConversation]. Note 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 IRIs that might be outside the scope
of the sender.

Additionally, some metadata formats, such as policies
[WS-Policy], can 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:

Message alteration - Alteration is prevented by including
signatures of the message information using WS-Security.

Authentication - Authentication is established using the
mechanisms described in WS-Security and WS-Trust. Each message is
authenticated using the mechanisms described in WS-Security

Accountability - Accountability is a function of the type
of and strength of the key and algorithms being used. In many
cases, a strong symmetric key provides sufficient accountability.
However, in some environments, strong PKI signatures are needed.

Availability - Metadata services are subject to a variety
of availability attacks such as application-level denial of
service. It is RECOMMENDED that the mechanisms described in
WS-Security be considered as mitigations for some forms of
attacks. Other attacks, such as network-level denial of service
are harder to avoid. Note that both of these classes of attack
are outside the scope of this specification.

Replay - Messages can be replayed for a variety of
reasons. To detect and eliminate this attack, mechanisms SHOULD
be used to identify replayed messages such as the timestamp/nonce
outlined in WS-Security. Alternatively, and OPTIONALLY, other
technologies, such as sequencing, can also be used to prevent
replay of application messages.

11 WS-MetadataExchange Metadata

An endpoint MAY indicate that it supports WS-MetadataExchange, or its
features,
by including the MetadataExchange Policy assertion within its WSDL. By
doing so the endpoint is indicating that the corresponding
WS-MetadataExchange
operations are supported by that endpoint even though they do not
explicitly appear in its WSDL
(i.e. the WS-MetadataExchange operations do not appear in the WSDL that
MAY be retrievable by using a WS-MetadataExchange GetWSDL to that endpoint).

The WS-MetadataExchange WSDL containing the operations indicated by the
MetadataExchange Assertion MAY be exposed by including the WSDL as a
child of the MetadataExchange Policy assertion or by including a
reference to it using the mex:Location or mex:Reference elements
(as described in 7 Metadata References).

The WS-MetadataExchange WSDL can be annotated to indicate any endpoint
specific metadata that might be needed by clients interacting with
this service's WS-MetadataExchange operations. For example, the WSDL
MAY have policy assertions that
indicate a particular security mechanism used to protect the
WS-MetadataExchange operations supported by this endpoint.

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.

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.

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.

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.

The policy assertion at line 05 in Example 12-1
indicates to consumers of this EPR that the GetWSDL operation is
supported by the referenced Service Endpoint. The parameters described in
11 WS-MetadataExchange Metadata could be added to the policy assertion at
line 05 to indicate additional capabilities such as support for the
mex:GetMetadata operation.

Alternatively the EPR for a Service Endpoint can contain embedded
metadata or references to Metadata Resources that describe the
referenced service. Example 8-1 illustrated an EPR with
embedded WSDL metadata. Example 7-2 shows an EPR with a
reference to a Metadata Resource. The representation of this resource
(retrievable via HTTP GET) is a WSDL document that describes the
service at "http://example.com". Example 8-3 illustrates a
similar mechanism, except that the retrieval mechanism is WS-Transfer
and the representation will be a mex:Metadata document.

Extra binding information (such as SOAP version) could either be
implied by the context in which the EPR was provided or could be
conveyed as in Example 12-2.

Example 12-2: Endpoint reference to a Service Endpoint that supports mex:GetWSDL

When information about the availability of metadata is not present in
an EPR, requesters can use contextual or out-of-band information to
choose the mechanism most appropriate for retrieving the metadata.
Furthermore, specific mechanisms for metadata retrieval can be defined
by communities within the context of particular application domains.