Web
Services Metadata Exchange (WS-MetadataExchange)
Latest version:
http://www.w3.org/TR/ws-metadata-exchange
Previous
version:
http://www.w3.org/TR/2009/WD-ws-metadata-exchange-20090317
Editors:
Doug Davis, IBM
Ashok Malhotra, Oracle
Katy Warr, IBM
Wu Chou, Avaya
Copyright © 2009 W3C®
(MIT,
ERCIM,
Keio), All Rights Reserved. W3C liability,
trademark
and document
use rules apply.
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] endpoint references, and
how metadata could be retrieved from a Web service endpoint.
This document is an
editors' copy that has no official standing.
1 Composable Architecture
2 Introduction
2.1 Requirements
2.2 Example
3 Notation
3.1 XML Namespaces
3.2 Notational Conventions
3.3 Considerations on the Use of
Extensibility Points
3.4 Compliance
4 Metadata Resources
5 Web Services Metadata
6 Retrieving Metadata
6.1 WS-Transfer Get
6.2 Get Metadata
7 Metadata in Endpoint References
8 Bootstrapping Metadata Retrieval
9 Security
10 Acknowledgements
11 References
A XML Schema
B WSDL
C Change Log
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, [WS-Policy]
describes the capabilities, requirements, and general characteristics of Web
services; [WSDL 1.1] describes abstract message
operations, concrete network protocols, and endpoint addresses used by Web
services; XML Schema [XML Schema: Structures], [XML Schema: Datatypes] 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
MAY indicate that only that type should 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 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.
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.
·
Define an optional bootstrap mechanism for
metadata-driven [XML Schema: Structures], [WSDL 1.1], [WS-Policy] message
exchange.
·
Support future versions of known metadata
formats.
·
Allow new metadata formats to be added.
·
Leverage other Web service specifications for
secure, reliable, transacted message delivery.
·
Support both [SOAP 1.1]
and [SOAP 1.2] Envelopes.
·
Enable description in [WSDL
1.1] of the optional request-response interaction.
Example 2-1 illustrates a
sample [WS-Transfer] Get request for a resource' s representation.
(01) <s11:Envelope
(02) xmlns:s11='http://schemas.xmlsoap.org/soap/envelope/'
(03) xmlns:wsa='http://www.w3.org/2005/08/addressing'>
(04) <s11:Header>
(05)
<wsa:Action>
(06)
http://www.w3.org/2009/02/ws-tra/Get
(07)
</wsa:Action>
(08) <wsa:To>http://services.example.org/stockquote/metadata</wsa:To>
(09)
<wsa:ReplyTo>
(10) <wsa:Address>http://client.example.org</wsa:Address>
(11)
</wsa:ReplyTo>
(12)
<wsa:MessageID>
(13) urn:uuid:1cec121a-82fe-41da-87e1-3b23f254f128
(14)
</wsa:MessageID>
(15) </s11:Header>
(16) <s11:Body />
(17) </s11:Envelope>
The sample request message of Example 2-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 might be
known to the requestor but is not explicitly encoded in the request message.
Example 2-2 illustrates a
sample response to the request of Example 2-1.
(01) <s11:Envelope
(02) xmlns:s11='http://schemas.xmlsoap.org/soap/envelope/'
(03) xmlns:wsa='http://www.w3.org/2005/08/addressing'
(04) xmlns:mex='http://www.w3.org/2009/02/ws-mex'
(05) xmlns:wsp='http://www.w3.org/ns/ws-policy'
(06) xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'>
(07) <s11:Header>
(08)
<wsa:Action>
(09)
http://www.w3.org/2009/02/ws-tra/GetResponse
(10)
</wsa:Action>
(11)
<wsa:To>http://client.example.org</wsa:To>
(12)
<wsa:RelatesTo>
(13) urn:uuid:1cec121a-82fe-41da-87e1-3b23f254f128
(14)
</wsa:RelatesTo>
(15) </s11:Header>
(16) <s11:Body>
(17)
<mex:Metadata>
(18) <mex:MetadataSection
Dialect='http://schemas.xmlsoap.org/wsdl/'>
(19)
<wsdl:definitions
(20)
name='StockQuote'
(21)
targetNamespace='http://services.example.org/stockquote'
(22)
xmlns:tns='http://services.example.org/stockquote'
(23)
xmlns:msgs='http://services.example.org/stockquote/schemas'
(24)
xmlns:wsoap='http://schemas.xmlsoap.org/wsdl/soap/'
(25)
xmlns:xs='http://www.w3.org/2001/XMLSchema'>
(26)
<wsdl:import
(27)
namespace='http://services.example.org/stockquote'
(28)
location='http://services.example.org/stockquote/schemas'
/>
(29)
<wsdl:portType
name='StockQuotePortType'>
(30)
<wsdl:operation
name='GetLastTradePrice'>
(31)
<wsdl:input
message='msgs:GetLastTradePriceInput'
(32)
name='GetLastTradePriceInput'/>
(33)
<wsdl:output
message='msgs:GetLastTradePriceOutput'
(34)
name='GetLastTradePriceOutput'/>
(35)
</wsdl:operation>
(36)
</wsdl:portType>
(37)
<wsdl:binding
name='StockQuoteBinding'
(38)
type='tns:StockQuotePortType'>
(39)
<wsp:PolicyReference
(40)
URI='http://services.example.org/stockquote/policy'
/>
(41)
<wsoap:binding
style='document'
(42)
transport='http://schemas.xmlsoap.org/soap/http'/>
(43)
<wsdl:operation
name='GetLastTradePrice'>
(44)
<wsoap:operation
soapAction='http://services.example.org/stockquote/GetLastTradePrice' />
(45)
<wsdl:input name='GetLastTradePriceInput'>
(46)
<wsoap:body
use='literal'/>
(47)
</wsdl:input>
(48)
<wsdl:output name='GetLastTradePriceOutput'>
(49)
<wsoap:body
use='literal'/>
(50)
</wsdl:output>
(51)
</wsdl:operation>
(52)
</wsdl:binding>
(53)
<wsdl:service
name='StockQuoteService'>
(54)
<wsdl:port name='StockQuotePort'
(55)
binding='tns:StockQuoteBinding'
>
(56)
<wsoap:address
(57)
location='http://services.example.org/stockquote'
/>
(58)
</wsdl:port>
(59)
</wsdl:service>
(60)
</wsdl:definitions>
(61)
</mex:MetadataSection>
(62) <mex:MetadataSection
(63)
Dialect='http://www.w3.org/2001/XMLSchema'
(64)
Identifier='http://services.example.org/stockquote/schemas'>
(65)
<mex:Location>
(66)
http://services.example.org/stockquote/schemas
(67)
</mex:Location>
(68)
</mex:MetadataSection>
(69) <mex:MetadataSection
(70) Dialect='http://www.w3.org/ns/ws-policy'
(71)
Identifier='http://services.example.org/stockquote/policy'>
(72)
<mex:MetadataReference>
(73)
<wsa:Address>
(74)
http://services.example.org/stockquote/policy
(75)
</wsa:Address>
(76)
</mex:MetadataReference>
(77)
</mex:MetadataSection>
(78)
</mex:Metadata>
(79) </s11:Body>
(80) </s11:Envelope>
The message of Example 2-2 is a [WS-Transfer]
response message to the request of Example 2-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 1.1] of the Web service endpoint. The
second Metadata Section (lines 62-68) contains the location of the XML Schemas [XML Schema: Structures], [XML Schema: Datatypes] 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]
endpoint reference (lines 72-75) of a [WS-Transfer]
resource the representation of which is a [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 Example 2-2, some endpoints may MAY choose
to support explicit request for metadata. Example 2-3
illustrates a sample Get Metadata request for the [WS-Policy].
(01) <s11:Envelope
(02) xmlns:s11='http://schemas.xmlsoap.org/soap/envelope/'
(03) xmlns:wsa='http://www.w3.org/2005/08/addressing'
(04) xmlns:mex='http://www.w3.org/2009/02/ws-mex'
>
(05) <s11:Header>
(06)
<wsa:To>http://services.example.org/stockquote</wsa:To>
(07)
<wsa:Action>
(08)
http://www.w3.org/2009/02/ws-mex/GetMetadata
(09)
</wsa:Action>
(10)
<wsa:MessageID>
(11) urn:uuid:73d7edfc-5c3c-49b9-ba46-2480caee43e9
(12)
</wsa:MessageID>
(13)
<wsa:ReplyTo>
(14) <wsa:Address>http://client.example.org</wsa:Address>
(15)
</wsa:ReplyTo>
(16) </s11:Header>
(17) <s11:Body>
(18)
<mex:GetMetadata>
(19) <mex:Dialect
URI="http://www.w3.org/ns/ws-policy"
(20)
Identifier="http://services.example.org/stockquote/policy"/>
(21)
</mex:GetMetadata>
(22) </s11:Body>
(23) </s11:Envelope>
Lines 7-9 in Example 2-3 indicate this is a Get Metadata request. As
lines 18-21 indicate, this request is for the policy of the Web service
endpoint (line 6).
Example 2-4 lists a sample
response to the request in Example 2-3.
(01) <s11:Envelope
(02) xmlns:s11='http://schemas.xmlsoap.org/soap/envelope/'
(03) xmlns:wsa='http://www.w3.org/2005/08/addressing'
(04) xmlns:wsp='http://www.w3.org/ns/ws-policy'
(05) xmlns:mex='http://www.w3.org/2009/02/ws-mex'>
(06) <s11:Header>
(07)
<wsa:To>http://client.example.org</wsa:To>
(08)
<wsa:Action>
(09)
http://www.w3.org/2009/02/ws-mex/GetMetadataResponse
(10)
</wsa:Action>
(11)
<wsa:RelatesTo>
(12) urn:uuid:73d7edfc-5c3c-49b9-ba46-2480caee43e9
(13)
</wsa:RelatesTo>
(14) </s11:Header>
(15) <s11:Body>
(16)
<mex:Metadata>
(17) <mex:MetadataSection
(18)
Dialect='http://www.w3.org/ns/ws-policy'
(19)
Identifier='http://services.example.org/stockquote/policy'>
(20)
<wsp:Policy>
(21)
<wsp:ExactlyOne>
(22)
<!-- Policy alternatives -->
(23)
</wsp:ExactlyOne>
(24)
</wsp:Policy>
(25)
</mex:MetadataSection>
(26)
</mex:Metadata>
(27) </s11:Body>
(28) </s11:Envelope>
Lines 8-10 in Example 2-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 Example 2-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
Example 2-3 was directed.
The XML namespace URI that MUST be used by
implementations of this specification is:
Table 3-1 lists XML namespaces that
are used in this specification. The choice of any namespace prefix is arbitrary
and not semantically significant.
|
Table 3-1: Prefixes and XML namespaces used in
this specification |
||
|
Prefix |
XML Namespaces |
Specification(s) |
|
s
|
(Either
SOAP 1.1 or 1.2) |
(Either
SOAP 1.1 or 1.2) |
|
s11
|
http://schemas.xmlsoap.org/soap/envelope/
|
|
|
s12 |
http://www.w3.org/2003/05/soap-envelope |
|
|
wsa |
http://www.w3.org/2005/08/addressing |
|
|
wsdl |
http://schemas.xmlsoap.org/wsdl/ |
|
|
wsp |
http://www.w3.org/ns/ws-policy |
|
|
mex |
http://www.w3.org/2009/02/ws-mex |
This specification |
|
xs |
http://www.w3.org/2001/XMLSchema |
|
|
wst |
http://www.w3.org/2009/02/ws-tra |
|
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 [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:
o "?" (0 or 1)
o "*" (0 or more)
o "+" (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:
[Headers]
Unordered message headers.
[Action]
The value to be used for the wsa:Action URI.
[Body]
A message body.
These properties bind to a SOAP Envelope as follows:
<s:Envelope>
<s:Header>
[Headers]
<wsa:Action>[Action]</wsa:Action>
...
</s:Header>
<s:Body>[Body]</s:Body>
</s:Envelope>
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".
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 3.1 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]).
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] 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).
A
resource is a Web service that is addressable by an endpoint reference [WS-Addressing] 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:
Structures],[XML Schema: Datatypes],
[WSDL 1.1], [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 6.2 Get Metadata.
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).
The
Web service Metadata element is a collection of metadata units such as [WSDL 1.1] definitions, [XML
Schema: Structures] 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 MAY be included
in-line within its Metadata Section or may MAY be included by
reference, either an endpoint reference [WS-Addressing]
(Metadata Reference) or a URL (Location).
The outline for the Metadata element is:
<mex:Metadata
...>
<mex:MetadataSection
Dialect="xs:anyURI"
(Identifier="xs:anyURI")? ...>
(
<mex:MetadataReference ...>
endpoint-reference-type
</mex:MetadataReference>
|
<mex:Location> xs:anyURI </mex:Location>
|
DialectSpecificElement
)
</mex:MetadataSection>
*
xs:any*
</mex:Metadata>
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 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 SHOULD define values
for Dialect for their metadata format(s).
|
Dialect URI |
Metadata Format |
|
http://www.w3.org/2001/XMLSchema |
xs:schema [XML Schema: Structures] |
|
http://schemas.xmlsoap.org/wsdl/ |
wsdl:definitions [WSDL 1.1] |
|
http://www.w3.org/ns/ws-policy |
wsp:Policy [WS-Policy] |
|
http://www.w3.org/TR/ws-policy-attach |
wsp:PolicyAttachment [WS-PolicyAttachment] |
|
http://www.w3.org/2009/02/ws-mex/Dialects/ws-mex
|
mex:Metadata [Defined in this specification] |
|
http://www.w3.org/2009/02/ws-mex/Dialects/ws-mex-all
|
None. [Defined in this specification for use
in GetMetadata requests. See 6.2
Get Metadata.] |
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.
/mex:Metadata/mex:MetadataSection/@Dialect
="http://www.w3.org/2009/02/ws-mex/Dialects/ws-mex"
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
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 |
|
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 |
|
http://www.w3.org/TR/ws-policy-attach |
Not defined |
|
http://www.w3.org/2009/02/ws-mex/Dialects/ws-mex
|
Not defined |
|
http://www.w3.org/2009/02/ws-mex/Dialects/ws-mex-all
|
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]. 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.
To retrieve the
representation of a metadata resource, a requester MAY send a [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 MAY be
available as multiple metadata resources. As a result, the metadata returned by
the Get request to a metadata resource's endpoint may 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: Structures], [XML Schema: Datatypes], [WSDL 1.1], [WS-Policy]) for which
a mex:MetadataSection/@Dialect has been defined.
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:
[Action]
http://www.w3.org/2009/02/ws-mex/GetMetadata
[Body]
<mex:GetMetadata
... >
<mex:Dialect URI="xs:anyURI"
Identifier="xs:anyURI" ?
Content="xs:anyURI" ? .../> *
xs:any*
</mex:GetMetadata>
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 Metadata Sections corresponding to the dialect specified by the URI
attribute; 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, the
endpoint SHOULD return all the types of metadata that it deems necessary to
communicate with it.
[Body]/mex:GetMetadata/mex:Dialect@URI
This REQUIRED attribute specifies the
Metadata dialect. The response MUST only include Metadata Sections
corresponding to the dialect specified by this URI. If the receiver does not
have any Metadata Sections of this indicated dialect, the response MUST include
zero Metadata Sections for this URI.
[Body]/mex:GetMetadata/mex:Dialect@URI="http://www.w3.org/2009/02/ws-mex/Dialects/ws-mex-all"
This value returns all known metadata. The
endpoint has the option to optimize the format in which it returns the data.
[Body]/mex:GetMetadata/mex:Dialect@URI="http://www.w3.org/2009/02/ws-mex/Dialects/ws-mex"
This value returns no metadata sections.
[Body]/mex:GetMetadata/mex:Dialect@Identifier
When this OPTIONAL attribute 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 for this URI/Identifier pair.
When this attribute is not present, the implied value is any identifier. If
multiple Metadata Sections 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 Metadata Sections of this specified content form. If
the specified content form is not available, or not known, then the response
MUST include zero Metadata Sections of the specified form for this
URI/Identifier pair. This specification defines the following content form
URIs:
|
Content Form URI |
Form |
|
http://www.w3.org/2009/02/ws-mex/Content/EPR |
A MetadataReference
element is returned |
|
http://www.w3.org/2009/02/ws-mex/Content/URI |
A Location element is returned |
|
http://www.w3.org/2009/02/ws-mex/Content/Metadata
|
The metadata is inlined
|
|
http://www.w3.org/2009/02/ws-mex/Content/Any |
The service is free to chose any content form |
|
http://www.w3.org/2009/02/ws-mex/Content/All |
The service MUST return all available content
forms |
When not present the default value is
"http://www.w3.org/2009/02/ws-mex/Content/Any".
Other message information headers defined by
WS-Addressing [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 [WS-Addressing]
(e.g., wsa:ActionNotSupported).
If an endpoint accepts a Get Metadata request, it MUST
reply with a Get Metadata response message. The normative outline for a Get
Metadata response is:
[Action]
http://www.w3.org/2009/02/ws-mex/GetMetadataResponse
[Body]
<mex:GetMetadataResponse>
<mex:Metadata
...>
xs:any*
</mex:Metadata>
xs:any*
</mex:GetMetadataResponse>
The following describes additional, normative constraints
on the outline listed above:
[Body]/mex:GetMetadataResponse/mex:Metadata
The body of the response message MUST contain
one mex:Metadata element as
defined in Section 4 of this specification.
6 Retrieving Metadata
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 5 Web Services
Metadata. The outline of a [WS-Addressing]
endpoint reference which includes Web services metadata is as follows:
<wsa:EndpointReference
...>
<wsa:Address>xs:anyURI</wsa:Address>
<wsa:ReferenceParameters> xs:any* lt;/wsa:ReferenceParameters> ?
<wsa:Metadata>
<mex:Metadata> xs:any*
</mex:Metadata>?
xs:any*
</wsa:Metadata> ?
xs:any*
</wsa:EndpointReference>
/wsa:EndpointReference/wsa:Metadata/mex:Metadata
A unique mex:Metadata element appearing as a direct child of the wsa:Metadata endpoint reference element.
In the example of Example 7-1, a [WS-Addressing] endpoint reference contains WSDL metadata
by value that identifies the binding used to access the service endpoint:
(01) <wsa:EndpointReference
(02) xmlns:wsa='http://www.w3.org/2005/08/addressing'>
(03)
<wsa:Address>http://services.example.org/stockquote</wsa:Address>
(04) <wsa:Metadata>
(05)
<mex:Metadata xmlns:mex='http://www.w3.org/2009/02/ws-mex'>
(06) <mex:MetadataSection
Dialect='http://schemas.xmlsoap.org/wsdl/'>
(07)
<wsdl:definitions
(08)
name='StockQuote'
(09)
targetNamespace='http://services.example.org/stockquote'
(10)
xmlns:tns='http://services.example.org/stockquote'
(11)
xmlns:wsoap='http://schemas.xmlsoap.org/wsdl/soap/'
(12)
xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'
(13)
xmlns:wsp='http://www.w3.org/ns/ws-policy'
(14)
xmlns:msgs='http://services.example.org/stockquote/schemas
(15)
xmlns:xs='http://www.w3.org/2001/XMLSchema'>
(16)
<wsdl:import
(17)
namespace='http://services.example.org/stockquote'
(18)
location='http://services.example.org/stockquote/schemas'
/>
(19)
<wsdl:portType
name='StockQuotePortType'>
(20)
<wsdl:operation
name='GetLastTradePrice'>
(21)
<wsdl:input
message='msgs:GetLastTradePriceInput'
(22) name='GetLastTradePriceInput'/>
(23)
<wsdl:output
message='msgs:GetLastTradePriceOutput'
(24)
name='GetLastTradePriceOutput'/>
(25)
</wsdl:operation>
(26)
</wsdl:portType>
(27)
<wsdl:binding
name='StockQuoteBinding'
(28)
type='tns:StockQuotePortType'>
(29)
<wsp:PolicyReference
(30)
URI='http://services.example.org/stockquote/policy'
/>
(31)
<wsoap:binding
style='document'
(32)
transport='http://schemas.xmlsoap.org/soap/http'/>
(33)
<wsdl:operation
name='GetLastTradePrice'>
(34)
<wsoap:operation
soapAction='http://services.example.org/stockquote/GetLastTradePrice' />
(35)
<wsdl:input name='GetLastTradePriceInput'>
(36)
<wsoap:body
use='literal'/>
(37)
</wsdl:input>
(38)
<wsdl:output
name='GetLastTradePriceOutput'>
(39)
<wsoap:body
use='literal'/>
(40)
</wsdl:output>
(41)
</wsdl:operation>
(42)
</wsdl:binding>
(43)
<wsdl:service
name='StockQuoteService'>
(44)
<wsdl:port name='StockQuotePort'
(45)
binding='tns:StockQuoteBinding'
>
(46)
<wsoap:address
(47)
location='http://services.example.org/stockquote'
/>
(48)
</wsdl:port>
(49)
</wsdl:service>
(50)
</wsdl:definitions>
(51)
</mex:MetadataSection>
(52) <mex:MetadataSection
(53)
Dialect='http://www.w3.org/2001/XMLSchema'
(54)
Identifier='http://services.example.org/stockquote/schemas'>
(55)
<mex:MetadataReference>
(56)
<wsa:Address>
(57)
http://services.example.org/stockquote/schemas
(58)
</wsa:Address>
(59)
</mex:MetadataReference>
(60)
</mex:MetadataSection>
(61)
</mex:Metadata>
(62) </wsa:Metadata>
(63) </wsa:EndpointReference>
Lines 4-62 in Example 7-1 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 8 Bootstrapping
Metadata Retrieval.
(01) <wsa:EndpointReference
(02) xmlns:wsa='http://www.w3.org/2005/08/addressing'>
(03)
<wsa:Address>http://services.example.org/stockquote</wsa:Address>
(04) <wsa:Metadata>
(05)
<mex:Metadata xmlns:mex='http://www.w3.org/2009/02/ws-mex'>
(06) <mex:MetadataSection
(07)
Dialect='http://www.w3.org/2009/02/ws-mex'>
(08)
<mex:MetadataReference>
(09)
<wsa:Address>
(10)
http://services.example.org/stockquote/metadata
(11)
</wsa:Address>
(12)
<wsa:Metadata>
(13)
<mex:Metadata>
(14)
<mex:MetadataSection
(15)
Dialect='http://schemas.xmlsoap.org/wsdl/'>
(16)
<!-- Reference to WS-Transfer WSDL wst:Resource portType
(17)
plus binding -->
(18)
</mex:MetadataSection>
(19)
</mex:Metadata>
(20)
</wsa:Metadata>
(21)
</mex:MetadataReference>
(22)
</mex:MetadataSection>
(23)
</mex:Metadata>
(24) </wsa:Metadata>
(25) </wsa:EndpointReference>
Example 7-2 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.
This
specification provides several mechanisms to aid service endpoints and service
requesters in bootstrapping the interaction. In particular, the mechanisms
described in 7
Metadata in Endpoint References 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
will 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 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 [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 may might be
desired depending on the frequency of messages. For example, for infrequent
messages, public key technologies may might be adequate
for integrity and confidentiality. However, for high-frequency events, it may might be
more performant to establish a security context for
the events using the mechanisms described in [WS-Trust]
and [WS-SecureConversation].
NIt 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 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.
·
Message disclosure -
Confidentiality is preserved by encrypting sensitive data using WS-Security.
·
Key integrity -
Key integrity is maintained by using the strongest algorithms possible (by
comparing secured policies - see [WS-Policy] and [WS-SecurityPolicy])
·
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
can be replayed for a variety of
reasons. To detect and eliminate this attack, mechanisms should 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.
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)
Key words for
use in RFCs to Indicate Requirement Levels , S. Bradner, Harvard University, March
1997. (See http://www.ietf.org/rfc/rfc2119.txt.)
Simple Object
Access Protocol (SOAP) 1.1 , D. Box,
et al, May 2000. (See http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.)
"SOAP Version 1.2 Part 1:
Messaging Framework , M. Gudgin, et
al, June 2003. (See http://www.w3.org/TR/2003/REC-soap12-part1-20030624/.)
W3C Recommendation, "Web Services
Addressing 1.0 (WS-Addressing)" , May 2006. (See
http://www.w3.org/2005/08/addressing/.)
W3C Recommendation, "Web Services
Policy 1.5 - Framework" , September 2007. (See
http://www.w3.org/TR/ws-policy/.)
WS-PolicyAttachment
W3C Recommendation, "Web Services
Policy 1.5 - Attachment" , September 2007. (See
http://www.w3.org/TR/ws-policy-attach/.)
WS-SecureConversation
Web Services Secure Conversation
Language (WS-SecureConversation) , S. Anderson, et al,
February 2005. (See http://www.oasis-open.org/committees/download.php/17364..)
Web Services Security: SOAP Message
Security 1.0 (WS-Security 2004) , A. Nadalin,
et al, March 2004. (See http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.)
WS-SecurityPolicy
Web Services Security Policy Language
(WS-SecurityPolicy) , G. Della-Libera,
et al, July 2005. (See http://www.oasis-open.org/committees/download.php/16569/.)
Web Services Transfer (WS-Transfer) ,
J. Alexander, et al, September 2004. (See
http://www.w3.org/Submission/2006/SUBM-WS-Transfer-20060315/.)
Web Services Trust Language (WS-Trust)
, S. Anderson, et al, February 2005. (See
http://www.oasis-open.org/committees/download.php/17364.)
Web Services
Description Language (WSDL) 1.1 , E.
Christensen, et al, March 2001 (See
http://www.w3.org/TR/2001/NOTE-wsdl-20010315.)
XML Schema Part 1: Structures , H. Thompson, et al, October 2004. (See
http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/.)
XML Schema: Datatypes
XML Schema Part 2: Datatypes , P. Biron, et al, October 2004.
(See http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.)
A normative copy of the XML Schema [XML Schema: Structures], [XML
Schema: Datatypes] description for this
specification may can be retrieved
from the following address:
A non-normative copy of the XML Schema description is
listed below for convenience.
<xs:schema
targetNamespace='http://www.w3.org/2009/02/ws-mex'
xmlns:tns='http://www.w3.org/2009/02/ws-mex'
xmlns:wsa='http://www.w3.org/2005/08/addressing'
xmlns:xs='http://www.w3.org/2001/XMLSchema'
elementFormDefault='qualified'
blockDefault='#all'>
<xs:import
namespace="http://www.w3.org/2005/08/addressing"
schemaLocation="http://www.w3.org/2006/03/addressing/ws-addr.xsd"/>
<!-- Get Metadata request -->
<xs:element name='GetMetadata'>
<xs:complexType>
<xs:sequence>
<xs:element ref='tns:Dialect' minOccurs='0' maxOccurs='unbounded'/>
<xs:any namespace='##other' processContents='lax' minOccurs='0'
maxOccurs='unbounded'/>
</xs:sequence>
<xs:anyAttribute
namespace='##other' processContents='lax'/>
</xs:complexType>
</xs:element>
<!-- Get Metadata response -->
<xs:element name='GetMetadataResponse'>
<xs:complexType>
<xs:sequence>
<xs:element ref='tns:Metadata'/>
<xs:any namespace='##other' processContents='lax' minOccurs='0'
maxOccurs='unbounded'/>
</xs:sequence>
<xs:anyAttribute
namespace='##other' processContents='lax'/>
</xs:complexType>
</xs:element>
<xs:element
name='Dialect'>
<xs:complexType>
<xs:attribute name='URI' type='xs:anyURI' use='required'/>
<xs:attribute name='Identifier'
type='xs:anyURI'/>
<xs:attribute name='Content' type='xs:anyURI'/>
<xs:anyAttribute
namespace='##other' processContents='lax'/>
</xs:complexType>
</xs:element>
<!-- Metadata -->
<xs:element
name='Metadata'>
<xs:complexType>
<xs:sequence>
<xs:element ref='tns:MetadataSection'
minOccurs='0'
maxOccurs='unbounded'/>
<xs:any namespace='##other' processContents='lax'
minOccurs='0'
maxOccurs='unbounded'/>
</xs:sequence>
<xs:anyAttribute
namespace='##other' processContents='lax'/>
</xs:complexType>
</xs:element>
<xs:element name='MetadataSection'>
<xs:complexType>
<xs:choice>
<xs:any namespace='##other' processContents='lax'/>
<xs:element name='MetadataReference' type='wsa:EndpointReferenceType'
/>
<xs:element ref='tns:Location'/>
</xs:choice>
<xs:attribute name='Dialect' type='xs:anyURI' use='required'/>
<xs:attribute name='Identifier'
type='xs:anyURI'/>
<xs:anyAttribute
namespace='##other' processContents='lax'/>
</xs:complexType>
</xs:element>
<xs:element
name='Location' type='xs:anyURI'/>
</xs:schema>
A normative copy of the WSDL [WSDL 1.1] description for this specification may can be
retrieved from the following address:
A non-normative copy of the WSDL description is listed
below for convenience.
<wsdl:definitions
targetNamespace='http://www.w3.org/2009/02/ws-mex'
xmlns:tns='http://www.w3.org/2009/02/ws-mex'
xmlns:wsa='http://www.w3.org/2005/08/addressing'
xmlns:wsam='http://www.w3.org/2007/05/addressing/metadata'
xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'
xmlns:xs='http://www.w3.org/2001/XMLSchema'>
<wsdl:types>
<xs:schema
targetNamespace='http://www.w3.org/2009/02/ws-mex'>
<xs:include schemaLocation='metadataexchange.xsd'/>
</xs:schema>
</wsdl:types>
<wsdl:message
name='GetMetadataMsg'>
<wsdl:part name='body' element='tns:GetMetadata'/>
</wsdl:message>
<wsdl:message
name='GetMetadataResponseMsg'>
<wsdl:part name='body' element='tns:GetMetadataResponse'/>
</wsdl:message>
<wsdl:portType
name='MetadataExchange'>
<wsdl:operation name='GetMetadata'>
<wsdl:input
message='tns:GetMetadataMsg'
wsam:Action=
'http://www.w3.org/2009/02/ws-mex/GetMetadata'/>
<wsdl:output
message='tns:GetMetadataResponseMsg'
wsam:Action=
'http://www.w3.org/2009/02/ws-mex/GetMetadataResponse'/>
</wsdl:operation>
</wsdl:portType>
</wsdl:definitions>
|
Data |
Author |
Description |
|
2009/03/04 |
DD |
Added resolution of issue 6391 |
|
2009/03/04 |
DD |
Added resolution of issue 6519 |
|
2009/03/11 |
DD |
Added change log |
|
2009/03/11 |
DD |
Added resolution of issue 6639 |
|
2009/03/11 |
DD |
Added resolution of issue 6425 |
|
2009/03/16 |
KW |
Added resolution of issue 6587 |
|
2009/03/17 |
KW |
Added resolution of issue 6405 |
|
2009/03/17 |
KW |
Added resolution of issue 6604 |
|
2009/03/18 |
AM |
Added resolution of issue 6404 |
|
2009/03/23 |
DD |
Added resolution of issue 6666 |
|
2009/03/24 |
DD |
Added resolution of issue 6648 |
|
2009/04/07 |
DD |
Added resolution of issue 6728 |
|
2009/04/22 |
KW |
Added resolution of issue 6739 |
|
2009/04/28 |
DD |
Added resolution of issue 6787 |
|
2009/05/12 |
DD |
Added resolution of issue 6433 |
|
2009/05/21 |
DD |
Added resolution of issue 6674 |
|
2009/05/27 |
DD |
Added resolution of issue 6906 |
|
2009/07/21 |
DD |
Added resolution of issue 7122 |
|
2009/07/21 |
DD |
Added resolution of issue 6500 |