Abstract

This specification defines how metadata
associated with a Web service endpoint can be represented as
[WS-Transfer] resources, how metadata can
be embedded in [WS-Addressing 2004,
WS-Addressing
1.0 Core] endpoint references, and how metadata could be
retrieved from a Web service endpoint.

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 can
be found in the W3C technical reports index at http://www.w3.org/TR/.

This WS-MetadataExchange Specification is a public draft release and is provided for review and evaluation only. The
Authors hope to solicit your contributions and suggestions in the near future. The Authors make no warrantees or
representations regarding the specifications in any manner whatsoever.

By publishing this document, W3C acknowledges that the
Submitting Members
have made a formal Submission request to W3C for
discussion. Publication of this document by W3C indicates no
endorsement of its content by W3C, nor that W3C has, is, or will be
allocating any resources to the issues addressed by it. This document
is not the product of a chartered W3C group, but is published as
potential input to the W3C
Process. A W3C Team
Comment has been published in conjunction with this Member
Submission. Publication of acknowledged Member Submissions at the W3C
site is one of the benefits of W3C Membership. Please
consult the requirements associated with Member Submissions of section
3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member
Submissions.

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.

1. Introduction

Web services use metadata to describe what
other endpoints need to know to interact with them. Specifically,
WS-Policy [WS-Policy] describes the capabilities,
requirements, and general characteristics of Web services; WSDL
[WSDL
1.1] describes abstract message operations, concrete
network protocols, and endpoint addresses used by Web services; XML
Schema [XML
Schema Part 1, 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 [WS-Transfer]
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., [WS-Policy], 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.

1.1 Requirements

This specification intends to meet the
following requirements:

Define an encapsulation format for
metadata.

Treat the metadata about a Web service endpoint
as [WS-Transfer] resources.

The sample request message of Table 1 is a [WS-Transfer]
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 may be known to
the requestor but is not explicitly encoded in the request
message

The message of Table 2 is a [WS-Transfer]
response message to the request of Table 1. 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 WSDL [WSDL] of the Web service endpoint. The
second Metadata Section (lines 62-68) contains the location of the
XML Schemas [XML
Schema Part 1, Part 2] 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 WS-Addressing [WS-Addressing
1.0 Core] endpoint reference (lines 72-75) of a
WS-Transfer [WS-Transfer] resource the representation
of which is a WS-Policy [WS-Policy] 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 Table 2, some endpoints may choose to support explicit request
for metadata. Table 3 illustrates a sample Get Metadata request for the
WS-Policy [WS-Policy].

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

2. Notation

2.1 XML Namespaces

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

http://schemas.xmlsoap.org/ws/2004/09/mex

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

2.2 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. Additional children and/or attributes MAY be added
at the indicated extension points but MUST NOT contradict the
semantics of the parent and/or owner, respectively. By default, if
a receiver does not recognize an extension, the receiver SHOULD
ignore the extension; exceptions to this processing rule, if any,
are clearly indicated below.

XML namespace prefixes (see Table 5) are used to indicate
the namespace of the element being defined.

2.3 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
Section 2.2) within XML documents, SOAP
Envelopes, and [WS-Addressing 2004, WS-Addressing
1.0 Core] endpoint references unless it is compliant
with 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 [WS-Addressing
2004, WS-Addressing
1.0 Core] endpoint reference, then the Metadata
Reference MUST refer to a [WS-Transfer] resource. The referred
resource MAY also support other resource management and access
specifications (e.g. HTTP, WS-ResourceFramework).

Normative text within this specification takes
precedence over outlines, which in turn take precedence over the
XML Schema [XML
Schema Part 1, Part 2] and WSDL [WSDL 1.1]
descriptions (if any), which in turn take precedence over
examples.

3. Metadata Resources

A resource is a Web service that is addressable
by an endpoint reference [WS-Addressing
2004, WS-Addressing
1.0 Core] and can be represented by an XML Infoset. The
resource's representation can be retrieved using the Get operation
defined in [WS-Transfer].

When the representation of a resource is
mex:Metadata, as defined in Section 4, or any other document format
(e.g. [XML
Schema Part 1, Part 2], [WSDL], [WS-Policy]) 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
[WS-Transfer] resource. Specifically, the
representation of a metadata resource MUST be retrievable through a
[WS-Transfer] 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 Section 5.2.

A metadata resource MAY support other
operations defined by [WS-Transfer], 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).

4. Web Services Metadata

The Web service Metadata element is a
collection of metadata units such as [WSDL]
definitions, XML Schema [XML Schema Part 1, Part 2]
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 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 [WS-Addressing
2004, WS-Addressing
1.0 Core] (Metadata Reference) or a URL (Location).

The following describes additional constraints
on the outline listed above:

/mex:Metadata

This contains one Metadata Section child for
each distinct unit of metadata. When there is a large amount of
metadata, the [children] SHOULD contain Metadata References or
Locations 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 Metadata Section 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 Metadata Section (e.g., WSDL
version 1.1). Dialect is an absolute URI. This value should be
compared directly, as a case-sensitive string, with no attempt to
unescape or to otherwise canonicalize it.
This specification defines the following values for Dialect; other
specifications should define values for Dialect for their metadata
format(s).

This value indicates the type of the metadata
contained within the Metadata Section. When used in conjunction
with Metadata Reference or Location, this allows the inclusion of
metadata by reference.

/mex:Metadata/mex:MetadataSection/@Identifier

This indicates the Identifier for the
metadata unit in this Metadata Section. Identifier is an absolute
URI. This value should be compared directly, as a case-sensitive
string, with no attempt to unescape or to otherwise canonicalize
it. If omitted, there is no implied value.

The interpretation of Identifier is
Dialect-specific. While the Dialect attribute indicates the
metadata format and version of the metadata in the Metadata
Section, the Identifier attribute MAY be used to identify a
Metadata Section or to just differentiate between Metadata Sections
containing the same type of metadata. The value of the Identifier
MAY be the same as the value of one of the attributes or elements
of the metadata in the Metadata Section (if the metadata is
included by value) or in the representation of a metadata resource
(if the metadata is include by reference through Metadata Reference
or Location). A metadata publisher MAY choose any value for the
Identifier. The values of Identifier attributes in multiple
Metadata Section elements in the same Metadata element MAY be the
same. For well-known metadata formats, it is RECOMMENDED that the
value of the Identifier comes from the metadata when that is
possible, as the table below shows.

Dialect URI

@Identifier value

Dialect URI

@Identifier value

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

xs:schema/@targetNamespace

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

wsdl:definitions/@targetNamespace

http://schemas.xmlsoap.org/ws/2004/09/policy

wsp:Policy/@Name

http://schemas.xmlsoap.org/ws/2004/09/policy/attachment

Not defined

http://schemas.xmlsoap.org/ws/2004/09/mex

Not defined

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.

/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 2004,] or
EndpointReferenceType as defined by [WS-Addressing
1.0 Core]. The resource MUST support the GET operation
[WS-Transfer] to allow the retrieval of
the metadata unit for the Metadata Section's Dialect and Identifier
(if any). When this element is present, it MUST have no element
siblings.

/mex:Metadata/mex:MetadataSection/mex:Location

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 Metadata
Reference or Location is present, the element is to be interpreted
as the representation of the metadata unit associated with the
Metadata Section's Dialect and Identifier.

5. Retrieving Metadata

5.1 WS-Transfer Get

To retrieve the representation of a metadata
resource, a requester MAY send a WS-Transfer [WS-Transfer]
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. As a result, the metadata
returned by the Get request to a metadata resource's endpoint may
be limited to a particular metadata type (@Dialect) and identifier
(@Identifier).

The representation of a metadata resource MAY
be a mex:Metadata element or any other document format (e.g.
[XML Schema Part
1, Part 2], [WSDL], [WS-Policy]) for
which a mex:MetadataSection/@Dialect has been defined.

5.2 Get Metadata

When the metadata for an endpoint is not
available or is unknown and there is no information on how to
retrieve it (e.g. an endpoint reference to a [WS-Transfer]
resource representing the metadata), a requester MAY send a Get
Metadata request message to that endpoint to retrieve its metadata.
A service endpoint MAY support the Get Metadata request. 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 Get Metadata request is:

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

[Body]/mex:GetMetadata/mex:Dialect

When this element is present, the response
MUST include only Metadata Sections with the indicated dialect; if
the receiver does not have any Metadata Sections of the indicated
dialect, the response MUST include zero Metadata Sections. When
this element is not present, there is no implied value and so the
response may include Metadata Sections with any dialect.

[Body]/mex:GetMetadata/mex:Identifier

When this element is present, the response
MUST include only Metadata Sections with the indicated identifier;
if the receiver does not have any Metadata Sections of the
indicated identifier, the response MUST include zero Metadata
Sections. When this element is not present, the implied value is
any identifier. This element MUST NOT be present unless
./mex:Dialect is present. If multiple Metadata Sections have the
indicated Dialect and Identifier then all of them MUST be
returned.

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

6. Metadata in Endpoint
References

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 Section 4. The outline of a [WS-Addressing
2004] endpoint reference which includes Web services
metadata is as follows:

Lines 4-62 in Table 6 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 [WS-Transfer]
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 [WS-Transfer] Get request to the metadata
resource's endpoint, as defined in Section 7.

Table 7 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
[WS-Transfer] operations. Since the
Metadata 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.

7. Bootstrapping Metadata
Retrieval

This specification provides several mechanisms
to aid service endpoints and service requesters in bootstrapping
the interaction. In particular, the mechanisms described in Section
6 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.

8. Security

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
2004, WS-Addressing 1.0 Core], 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 WS-Trust [WS-Trust] and WS-SecureConversation
[WS-SecureConversation]. 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 [WS-Policy], 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:

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

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