Web Services Metadata Exchange (WS-MetadataExchange)
Editor's Draft $Date$Date: 2010/05/11 23:27:53 $
Latest version:
Previous version:
Editors:
Doug Davis, IBM
Ashok Malhotra, Oracle
Katy Warr, IBM
Wu Chou, Avaya
Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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 document is an editors' copy that has no official standing.
Table of Contents
1 Composable Architecture
2 Introduction
2.1 Requirements
2.2 Examples
3 Notations and Terminology
3.1 Notational Conventions
3.2 Considerations on the Use of Extensibility Points
3.3 Terminology
3.4 Compliance
3.5 XML Namespaces
4 Web Services Metadata Collection
5 Metadata Resources
6 Retrieving Metadata about Service Endpoints
6.1 GetWSDL
6.2 GetMetadata
6.3
6.4
7 Metadata References
7.1 mex:Location
7.2 mex:Reference
7.3 Examples
8 Metadata in Endpoint References
8.1 Endpoint References Containing Metadata
8.2 Associating Policies with Endpoint References
9 Exposing Metadata for Implicitly Defined Features
10
10.1
10.2
11 Security Considerations
10.1 Metadata and Security Bootstrapping
11.1
12WS-MetadataExchange Metadata
11.1 MetadataExchange Assertion
12.1
13Boostrapping Metadata Retrieval
1413Acknowledgements
1514References
15.114.1Normative References
15.214.2Informative References
Appendices
A XML Schema
B WSDL
C Change Log
1 Composable Architecture
By using the XML, SOAP [SOAP11], [SOAP12], and WSDL [WSDL11] extensibility models, the Web service 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 service specifications to provide secure, reliable, and/or transacted message delivery and to express Web service and client policy.
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.
Example 2-1: Sample GetWSDL request message
(01) <s11:Envelope
(02) xmlns:s11='
(03) xmlns:wsa='
(04) xmlns:wst='
(05) <s11:Header>
(06) <wsa:Action>
(07)
(08) </wsa:Action>
(09) <wsa:To>
(10) <wsa:ReplyTo>
(11) <wsa:Address>
(12) </wsa:ReplyTo>
(13) <wsa:MessageID>
(14) urn:uuid:1cec121a-82fe-41da-87e1-3b23f254f128
(15) </wsa:MessageID>
(16) </s11:Header>
(17) <s11:Body>
(18) <mex:GetWSDL/>
(19) </s11:Body>
(20) </s11:Envelope>
Example 2-2 lists a sample response to the request in Example 2-1.
Example 2-2: Sample GetWSDLResponse message
(01) <s11:Envelope
(02) xmlns:s11='
(03) xmlns:wsa='
(04) xmlns:wsp='
(05) xmlns:mex='
(06) <s11:Header>
(07) <wsa:To>
(08) <wsa:Action>
(09)
(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:GetWSDLResponse>
(17) <wsdl:definitions ...>
(18) <!-- WSDL data removed for brevity -->
(19) </wsdl:definitions>
(18) </mex:GetWSDLResponse>
(19) </s11:Body>
(20) </s11:Envelope>
Lines 17-19 in Example 2-2 is the WSDL of the service.
Example 2-3 illustrates a sample [WS-Transfer] Get request for a resource' s representation.
Example 2-3: Sample Get request message
(01) <s11:Envelope
(02) xmlns:s11='
(03) xmlns:wsa='
(04) xmlns:wst='
(05) <s11:Header>
(06) <wsa:Action>
(07)
(08) </wsa:Action>
(09) <wsa:To>
(10) <wsa:ReplyTo>
(11) <wsa:Address>
(12) </wsa:ReplyTo>
(13) <wsa:MessageID>
(14) urn:uuid:1cec121a-82fe-41da-87e1-3b23f254f128
(15) </wsa:MessageID>
(16) </s11:Header>
(17) <s11:Body>
(18) <wst:Get/>
(19) </s11:Body>
(20) </s11:Envelope>
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.
Example 2-4 illustrates a sample response to the request of Example 2-3.
Example 2-4: Sample response message with metadata
(01) <s11:Envelope
(02) xmlns:s11='
(03) xmlns:xs='
(04) xmlns:wsa='
(05) xmlns:mex='
(06) xmlns:wsp='
(07) xmlns:wst='
(08) xmlns:wsdl='
(09) <s11:Header>
(10) <wsa:Action>
(11)
(12) </wsa:Action>
(13) <wsa:To>
(14) <wsa:RelatesTo>
(15) urn:uuid:1cec121a-82fe-41da-87e1-3b23f254f128
(16) </wsa:RelatesTo>
(17) </s11:Header>
(18) <s11:Body>
(19) <wst:GetResponse>
(20) <mex:Metadata>
(21) <mex:MetadataSection Dialect='wsdl:definitions'>
(22) <wsdl:definitions>
(23) <!-- WSDL data removed for brevity -->
(24) </wsdl:definitions>
(25) </mex:MetadataSection>
(26) <mex:MetadataSection
(27) Dialect='xs:schema'
(28) Identifier='
(29) <mex:MetadataLocation>
(30)
(31) </mex:MetadataLocation>
(32) </mex:MetadataSection>
(33) <mex:MetadataSection
(34) Dialect='wsp:Policy'
(35) Identifier='
(36) <mex:MetadataReference>
(37) <wsa:Address>
(38)
(39) </wsa:Address>
(40) </mex:MetadataReference>
(41) </mex:MetadataSection>
(42) </mex:Metadata>
(43) </wst:GetResponse>
(44) </s11:Body>
(45) </s11:Envelope>
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 18-44) is a mex:Metadata element with metadata about the Web service endpoint (lines 20-42). The mex:Metadata contains three MetadataSections. The first MetadataSection (lines 21-25) contains the [WSDL11] of the Web service endpoint. The second MetadataSection (lines 26-32) 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 29-31). The third MetadataSection (lines 33-41) contains the [WS-Addressing] endpoint reference (lines 36-40) of a [WS-Transfer] resource the representation of which is a [WS-Policy] document as indicated by the Dialect attribute (line 34).
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 36-40 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].
Example 2-5: Sample GetMetadata request message
(01) <s11:Envelope
(02) xmlns:s11='
(03) xmlns:wsa='
(04) xmlns:wsp='
(05) xmlns:mex=' >
(06) <s11:Header>
(07) <wsa:To>
(08) <wsa:Action>
(09)
(10) </wsa:Action>
(11) <wsa:MessageID>
(12) urn:uuid:73d7edfc-5c3c-49b9-ba46-2480caee43e9
(13) </wsa:MessageID>
(14) <wsa:ReplyTo>
(15) <wsa:Address>
(16) </wsa:ReplyTo>
(17) </s11:Header>
(18) <s11:Body>
(19) <mex:GetMetadata>
(20) <mex:Dialect Type='wsp:Policy'
(21) Identifier='
(22) </mex:GetMetadata>
(23) </s11:Body>
(24) </s11:Envelope>
Lines 8-10 in Example 2-5 indicate this is a GetMetadata request. As lines 19-22 indicate, this request is for the policy of the Web service endpoint (line 7).
Example 2-6 lists a sample response to the request in Example 2-5.
Example 2-6: Sample GetMetadataResponse message
(01) <s11:Envelope
(02) xmlns:s11='
(03) xmlns:wsa='
(04) xmlns:wsp='
(05) xmlns:mex='
(06) <s11:Header>
(07) <wsa:To>
(08) <wsa:Action>
(09)
(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:GetMetadataResponse>
(17) <mex:Metadata>
(18) <mex:MetadataSection
(19) Dialect='wsp:Policy'
(20) Identifier='
(21) <wsp:Policy>
(22) <wsp:ExactlyOne>
(23) <!-- Policy alternatives -->
(24) </wsp:ExactlyOne>
(25) </wsp:Policy>
(26) </mex:MetadataSection>
(27) </mex:Metadata>
(28) </mex:GetMetadataResponse>
(29) </s11:Body>
(30) </s11:Envelope>
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:
[Headers]
Unordered message headers.
[Action]
The value to be used for the wsa:Action IRI.
[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>
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.
The term "generate" is used in relation to the various faults defined by this specification to imply that a fault is produced and no further processing SHOULD be performed. In these cases the fault SHOULD be transmitted. However, there might be reasons when a compliant implementation can choose not to transmit the fault - for example, security concerns - in these situations the service MAY choose not to transmit the fault.
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 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.4 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.5 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 conform to the WS-Addressing specifications and 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).
Implementations are expected to support both UTF-8 and UTF-16 as described in XML 1.0.
3.5 XML Namespaces
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 specificationPrefix / XML Namespaces / Specification(s)
s / (Either SOAP 1.1 or 1.2) / (Either SOAP 1.1 or 1.2)
s11 / / [SOAP11]
s12 / / [SOAP12]
wsa / / [WS-Addressing]
wsdl / / [WSDL11]
wsp / / [WS-Policy]
mex / / This specification
xs / / [XMLSchema - Part 1]
wssa / / [WS-SOAPAssertions]
wst / / [WS-Transfer]
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 and .
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 outline for the Metadata element is:
<mex:Metadata ...>
<mex:MetadataSection Dialect='xs:QName'
Identifier='xs:anyURI'? ...>
(
<mex:MetadataReference ...>
endpoint-reference-type
</mex:MetadataReference>
|
<mex:MetadataLocation ...> xs:anyURI </mex:MetadataLocation>
|
DialectSpecificElement
)
</mex:MetadataSection> *
xs:any*
</mex:Metadata>
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 type and version of the metadata unit contained in this MetadataSection (e.g., WSDL version 1.1). This MUST be the QName of the root element of the 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 MetadataSection, is explicitly encouraged.
/mex:Metadata/mex:MetadataSection/@Dialect='mex:Metadata'
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.