Understanding WS Metadata Exchange - Part I

Part I of this article by Sanka Samaranayake introduces the different types of Web services metadata and their importance, explains the necessity for a standard way to encapsulate, publish and retrieve metadata and provides a detailed description of what is specified in Web Services Metadata Exchange.

Part II will describe how to enable metadata exchange for any service deployed in the WSO2 Web Services Application Server.

Introduction

The metadata of a Web service describes what a client needs to know in order to interact with it. For example, the format and the content of the messages that are exchanged are usually described in XML Schema. A WSDL description describes the abstract operations, concrete network protocols, and endpoint addresses of the service. WS-Policy describes the requirements and capabilities of the service such as reliable and transacted messaging.

To interact successfully with a service endpoint, it is necessary to acquire all description data (or metadata) of the service. It is important to have a standard way of publishing/retrieving metadata because it gives a client a vendor-independent mechanism of locating and retrieving metadata for a service. Having a standard encapsulating format makes metadata machine-processable which enables Web service middleware to configure their clients automatically. It ensures that everyone interprets the retrieved metadata exactly the same way which helps interoperability. The Web Services Metadata Exchange specification attempts to address this problem by providing a standard format to encapsulate metadata, specifying mechanisms for retrieval of metadata (pull metadata) and a standard to include service metadata in addressing headers (push metadata). It allows metadata retrieval as a whole, or particular types requested by the client.

Applies To

Metadata Encapsulation

In order to ensure interoperability, WS Metadata Exchange describes a standard format for encapsulating metadata.

<mex:Metadata xmlns:mex="https://schemas.xmlsoap.org/ws/2004/09/mex">
  <mex:MetadataSection Dialect="xs:any" (Identifier="xs:any")?  >
    (
      <mex:MetadataReference>
        endpoint-reference
      </mex:MetadataReference>
    |
      <mex:Location>xs:anyURI</mex:Locatoin>
    |
      Dialect Specific Element
    )
  </mex:MetadataSection>*
</mex:Metadata>

Web service metadata is a collection of metadata units such as XML schemas, WSDL descriptions, and WS-Policy expressions. Each metadata unit corresponds to a particular scope, domain or a namespace. For example, a service may have a WS-Policy expression which applies to some particular operation (operation scope) and an XML schema which belongs to the target namespace of the service The collection of units of metadata is encapsulated by the mex:Metadata element, and each distinct unit of metadata is encapsulated by the mex:MetadataSection element.

Each mex:MetadataSection element must carry a Dialect attribute, and optionally an Identifier attribute. The Dialect attribute specifies the metadata format and the version of the metadata included within the mex:MetadataSection element (e.g. WSDL version 1.1). Authors are advised to place each metadata unit in a separate mex:MetadataSection element even if more than one unit has the same Dialect value (e.g. the metadata includes more than one schema document).

The Web Services Metadata Exchange specification defines the following URL values to indicate the various data formats.

The value of the Dialect attribute is an absolute URI which should be compared directly as a case sensitive string with no attempt to escape or canonicalize.

The Identifier attribute can be used to identify or differentiate mex:MetadataSections with the same Dialect value. A recommended practice is to use an identifier that the metadata format itself considers its identifier, such as a namespace. The following Identifier values from various metadata formats are recommended for well-known metadata types.

Note that the Identifier value doesn't necessarily have to be unique for each mex:MetadataSection element. For example an XML Schema defining a targetNamespace could be split up into multiple XML Schemas. In this case a corresponding number of mex:MetadataSection elements with the same Identifier (the targetNamespace value) might result.

The value of the Identifier is an absolute URI value which should be compared directly without any attempt to unescape or otherwise canonicalize it. In case the Identifier value is not specified, no default value is implied.

The content of the mex:MetadataSection contains or references the actual metadata as described by the Dialect and Identifier. In addition to directly embedding the metadata within the mex:MetadataSection, WS Metadata Exchange provides two elements representing different types of references - by Endpoint Reference, or by URI. Only one child element, the metadata itself, or one of the forms of reference, may appear within a given mex:MetadataSection.

• The mex:MetadataReference element contains an endpoint reference to a metadata resource which is an EndpointReference type defined by WS-Addressing2004 or WS-Addressing Core 1.0. The referenced metadata resource should be retrievable via WS-Transfer Get request. The mex:MetadataReference should contain only a single endpoint reference
• The mex:Location element contains a URL to the metadata resource which is specified by the Dialect and the Identifier (if any). The metadata resource should be accessible via the primary access scheme of the URL. For example, for an HTTP URL, specified metadata should be retrievable by sending a HTTP GET request to the URL
• When an element other than the mex:MetadataReference or mex:Location is included inside the mex:MetadataSection element, that element should be interpreted as the actual metadata which is specified by the Dialect and the Identifier (if any).

Retrieval of Metadata (pull metadata from service)

The Web Services Metadata Exchange specification specifies the following mechanisms to retrieve metadata.

1. Retrieval of metadata via mex:GetMetadata request

This can also be considered as the bootstrap mechanism for retrieving metadata. If a client only knows the endpoint address of a service and there is no service metadata available or no information on how to retrieve metadata (for example if the client doesn't know any endpoint addresses of metadata resources which are accessible via WS-Transfer Get requests or HTTP Get requests), the client can send a mex:GetMetadata request to the service's endpoint address in order to retrieve its metadata. Services can support bootstrapping by handling mex:GetMetadata requests.

Format of the mex:GetMetadata Request

[action] https://schemas.xmlsoap.org/ws/2004/09/mex/GetMetadata/Request

[body]
<mex:GetMetadata>
  (
    <mex:Dialect>xs:anyURI</mex:Dialect>
    ( <mex:Identifier>xs:anyURI</mex:Identifier> ) ?
  ) ?
</mex:GetMetadata>

When the Dialect element is present in the mex:GetMetadata request, the response should contain mex:MetadataSections with the indicated Dialect value. If there is no metadata available with a specified Dialect value, then the response should not contain any mex:MetadataSections. If a Dialect element is not specified in the request, the response can contain multiple mex:MetadataSections with different Dialect values. In this case, it is generally a good practice to return all metadata the service has even if it is not mandatory

The mex:Identifier element should be present only if a mex:Dialect element is specified in the request. When the Identifier element is present in the request, the response should contain only mex:MetadataSections with the same Identifier value. If there are no mex:MetadataSections available with the same Identifier value, the response should not contain any mex:MetadataSections. If there are multiple mex:MetadataSections available with the same Identifier value, then all those mex:MetadataSections should be present in the response.

2. Retrieval of metadata specified by the mex:MetadataReference element

If the mex:MetadataSection contains a mex:MetadataReference element, the WS-Transfer Get request should be sent to the endpoint reference specified in that mex:MetadataReference element to retrieve the metadata described by the Dialect and the Identifier of the mex:MetadataSection element. The response will contain a current representation of metadata. When there are several metadata types associated with the same endpoint, a WS-Transfer Get request to a metadata reference's endpoint might return only the metadata in a particular Dialect or with a particular Identifier. The response can either contain a mex:Metadata element (described above) or an actual metadata document in one of the defined metadata dialects. (e.g. XML Schema, WSDL or WS-Policy).

3. Retrieval of metadata specified by the mex:Location element

If the mex:MetadataSection contains a mex:Location element, the actual metadata can be retrieved via the primary mechanism defined by the scheme of the URL. For instance, if the mex:Location contains a HTTP URL, then metadata can be fetched via the HTTP GET request. The response should contain the actual metadata document in one of the defined metadata dialects.

All the mechanisms above describe how to pull metadata from a service endpoint. For example, the client may issue a mex:GetMetadata request to a service endpoint, issue a WS-Transfer Get request to an endpoint reference it encountered in a mex:MetadataReference element or it may issue an HTTP Get request to a URL specified by the mex:Location element.

However, each of these mechanisms require multiple calls to the service endpoint or mex:MetadataReference endpoints to retrieve metadata. The WS-Metadata Exchange specification also describes how to embed or push metadata of a service into a WS-Addressing endpoint reference of the service. It eliminates the need of multiple calls to retrieve service metadata and simplifies the bootstrapping of service interaction on the client-side.

Publishing of Metadata (push metadata of a service)

By embedding a mex:Metadata element inside an endpoint reference, the issuer can specify metadata of a service either by value or reference using the options described above. The outline of how to include a mex:Metadata element inside a WS-Addressing 2004 endpoint reference element is as follows.

<wsa04:EndpointReference>
  <wsa04:Address>xs:anyURI</wsa04:Address>
  <wsa04:ReferenceProperties>...</wsa04:ReferenceProperties> ?
  <wsa04:ReferenceParameters>...</wsa04:ReferenceParameters> ?
  <wsa04:PortType>xs:QName</wsa04:PortType> ?
  <wsa04:ServiceName PortName="xs:NCName"?>xs:QName</wsa04:ServiceName> ?
  <wsp:Policy>...</wsp:Policy>*
  
  <mex:Metadata>...</mex:Metadata>?
  
  ...
<wsa04:EndpointReference>

The outline of a WS-Addressing 1.0 endpoint reference that includes a Metadata element is as follows.

<wsa10:EndpointReference>
  <wsa10:Address>xs:anyURI</wsa10:Address>
  <wsa10:ReferenceParameters>...</wsa10:ReferenceParameters> ?
  <wsa10:Metadata>
      
    <mex:Metadata>...</mex:Metadata>?
  ...
  </wsa10:Metadata> ?
  ...
</wsa10:EndpointReference>

Consider the example below. A wsa10:Metadata element which contains a mex:Metadata element is embedded in a wsa10:EndpointReference element which describes the location of a service. The mex:Metadata element contains a single mex:MetadataSection element which encapsulates a metadata reference to a WS-Transfer resource which represents the metadata of that service. The dialect attribute of the mex:Metadata section indicates that the resource is also of the mex:Metadata type.

Interestingly there is another wsa10:Metadata embedded inside the mex:MetadataReference element. It contains metadata which is necessary to interact with the WS-Transfer resource specified in the mex:MetadataReference element. In other words, mex:MetadataReference is also an endpoint reference to a WS-Transfer resource, and the embedded wsa10:Metadata element contains the WSDL Port type and the necessary binding information to interact with the endpoint to the resource.

<wsa10:EndpointReference
    xmlns:wsa10="https://www.w3.org/2005/08/addressing">
  <wsa10:Address>https://services.example.org/stockquote</wsa10:Address>
  <wsa10:Metadata>
    <mex:Metadata xmlns:mex="https://schemas.xmlsoap.org/ws/2004/09/mex">
      <mex:MetadataSection
          Dialect="https://schemas.xmlsoap.org/ws/2004/09/mex">
        <mex:MetadataReference>
          <wsa10:Address>
            https://services.example.org/stockquote/metadata
          </wsa10:Address>
          <wsa10:Metadata>
            <mex:Metadata>
              <mex:MetadataSection
                  Dialect="https://schemas.xmlsoap.org/wsdl/">
                <!-- A reference to WS-Transfer WSDL wxf:Resource portType plus binding -->
                  <wsdl:definitions
                      targetNamespace="https://schemas.xmlsoap.org/ws/2004/09/transfer"
                      xmlns:tns="https://schemas.xmlsoap.org/ws/2004/09/transfer"
                      xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing"
                      xmlns:wsdl="https://schemas.xmlsoap.org/wsdl/"
                      xmlns:soap="https://schemas.xmlsoap.org/wsdl/soap/"
                      xmlns:xs="https://www.w3.org/2001/XMLSchema">
                  <wsdl:types>
                    <xs:schema>
                      <xs:import
                          namespace="https://schemas.xmlsoap.org/ws/2004/09/transfer"
                          schemaLocation="https://schemas.xmlsoap.org/ws/2004/09/transfer/transfer.xsd" />
                    </xs:schema>
                  </wsdl:types>
                  <wsdl:message name="EmptyMessage"/>
                  <wsdl:message name="AnyXmlMessage">
                    <wsdl:part name="Body" type="tns:AnyXmlType"/>
                  </wsdl:message>
                  <wsdl:portType name="Metadata_Resource_Port">
                    <wsdl:operation name="Get">
                      <wsdl:input
                          message="tns:EmptyMessage"
                          wsa:Action="https://schemas.xmlsoap.org/ws/2004/09/transfer/Get" />
                      <wsdl:output
                          message="tns:AnyXmlMessage"
                          wsa:Action="https://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse" />
                    </wsdl:operation>
                  </wsdl:portType>
                  <wsdl:binding name="Metadata_Resource_Port_Binding" type="tns:Metadata_Resource_Port">
                    <soap:binding transport="https://schemas.xmlsoap.org/soap/http"/>
                    <wsdl:operation name="Get">
                      <soap:operation soapAction="https://schemas.xmlsoap.org/ws/2004/09/transfer/Get" style="rpc"/>
                      <wsdl:input>
                        <soap:body use="literal"/>
                      </wsdl:input>
                      <wsdl:output>
                        <soap:body use="literal"/>
                      </wsdl:output>
                    </wsdl:operation>
                  </wsdl:binding>
                  <wsdl:service name="Metadata_Resource_Service">
                    <wsdl:port name="Metadata_Service_Port" binding="tns:Metadata_Resource_Port_Binding">
                      <soap:address location="https://example.org/soap12/example1/metadata"/>
                    </wsdl:port>
                  </wsdl:service>
                </wsdl:definitions>           
              </mex:MetadataSection>
            </mex:Metadata>
          </wsa10:Metadata>
        </mex:MetadataReference>
      </mex:MetadataSection>
    </mex:Metadata>
  </wsa10:Metadata>
</wsa10:EndpointReference>

Summary

Web Services Metadata Exchange defines how metadata of a service can be represented as a WS-Transfer resource or how it can be embedded in a WS-Addressing endpoint reference. It also describes a standard format for encapsulating metadata and standard mechanisms to retrieve them. However, it should be noted that this specification relies on other Web services specifications such as WS-Security, WS-Reliable Messaging, and WS-Transaction to provide secure, reliable and transacted message delivery to express Web services metadata.

Part II of this article will describe how to configure metadata of a deployed service and how to use the wso2mex module to enable bootstrapping of metadata retrieval for a deployed service.

References

• Web Services Metadata Exchange Specification
  https://specs.xmlsoap.org/ws/2004/09/mex/WS-MetadataExchange.pdf
• Web Services Addressing 2004
  https://www.w3.org/Submission/2004/SUBM-ws-addressing-20040810/
• Web Services Addressing Core
  https://www.w3.org/TR/2006/PR-ws-addr-core-20060321
• Web Service Transfer
  https://specs.xmlsoap.org/ws/2004/09/transfer/WS-Transfer.pdf

Author

Sanka Samaranayake, Software Engineer, WSO2 Inc. sanka AT wso2 DOT com