1EdTech Logo

1EdTech General Web Services Addressing Profile

Version 1.0 Final Specification

Copyright © 2005 1EdTech Consortium, Inc. All Rights Reserved.
The 1EdTech Logo is a registered trademark of 1EdTech/GLC
Document Name: 1EdTech General Web Services Addressing Profile
Revision: 19 December 2005

IPR and Distribution Notices

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

1EdTech takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright ) 2005 1EdTech Consortium. All Rights Reserved.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech website: http://www.imsglobal.org/license.html.

The limited permissions granted above are perpetual and will not be revoked by 1EdTech or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.


Executive Summary

The 1EdTech General Web Service (GWS) Base Profile provides a basic structure for the definition of Web Services used to realize 1EdTech service-oriented specifications. It consists of a set of non-proprietary Web Services specifications, along with clarifications and amendments to those specifications that promote interoperability. The 1EdTech GWS Base Profile addresses the most common problems experienced when implementing web service specifications. The 1EdTech GWS Base Profile defines the selection of mechanisms within referenced specifications that are well understood, widely implemented and useful.

The 1EdTech GWS Base Profile promotes interoperability across web specifications implementations on different software and vendor platforms. The 1EdTech GWS Base Profile focuses on a core set of web service specifications and the most common problems experienced implementing the identified web service specifications. It is not a goal of the 1EdTech GWS Base Profile to create a plug-and-play architecture for web services or to guarantee complete interoperability. The 1EdTech GWS Base Profile addresses interoperability in the application layer, in particular, the description of behaviors exposed via Web Services.

The 1EdTech GWS Addressing Profile extends the 1EdTech GWS Base Profile to enable transport-independent end system addressing. 1EdTech GWS Addressing is based upon the WS-Addressing recommendations from the World Wide Web Consortium. WS-Addressing describes two techniques for transport-independent addressing, namely, Endpoint References (EPR) and Message Addressing Properties (MAP). Both techniques are compatible with Web Services Description Language (WSDL). The MAP approach has been selected for the 1EdTech GWS Addressing Profile as this is based upon extending the WSDL v1.1 files as opposed to EPR that defines another external object structure.

Table of Contents


Executive Summary

1. Introduction
1.1 Scope and Context
1.2 Structure of the Primer
1.3 Nomenclature
1.4 References

2. Addressing Framework
2.1 WS-Addressing
2.1.1 Endpoint References (EPRs)
2.1.2 Message Addressing Properties (MAPs)
2.2 Addressing Processing Workflow

3. Addressing Profile Rules

4. WSDL Binding Implications

5. Relationship to the Other GWS Profiles

6. Extending the Addressing Profile
6.1 Proprietary Extensions
6.2 Further Work in V2.0

7. Conformance to the Addressing Profile

Appendix A - Glossary of Terms

About This Document
List of Contributors

Revision History

Index


1. Introduction

1.1 Scope and Context

The 1EdTech General Web Services (GWS) Base Profile [GWS, 05a] provides a basic structure for the definition of Web Services. It consists of a set of non-proprietary Web Services specifications, along with clarifications and amendments to those specifications that promote interoperability. The 1EdTech GWS Base Profile addresses the most common problems experienced implementing web service specifications. The 1EdTech GWS Base Profile defines the selection of mechanisms within referenced specifications that are well understood, widely implemented and useful.

The 1EdTech GWS Addressing Profile extends the 1EdTech GWS Base Profile to enable transport-independent end system addressing. 1EdTech GWS Addressing is based upon the WS-Addressing recommendations from the World Wide Web Consortium (W3C) [WSA, 05a], [WSA, 05b], [WSA, 05c]. WS-Addressing describes two techniques for transport-independent addressing, namely, Endpoint References (EPR) and Message Addressing Properties (MAP). Both techniques are compatible with the Web Services Description Language (WSDL) v1.1 [WSDL, 01]. The MAP approach has been selected for the 1EdTech GWS Addressing Profile as this is based upon extending the WSDL v1.1 files as opposed to EPR that defines another external object structure.

1.2 Structure of the Primer

The structure of the rest of this document is:

2. Addressing Framework

Establishes the framework for the operation of 1EdTech web services that use WS-Addressing to support transport-independent end-user addressing;

3. Addressing Profile Rules

The statement of the profile rules that must be followed to enable the 1EdTech Base Profile to be extended to enable transport-independent end-user addressing;

4. WSDL Binding Implications

An explanation of the implications of the Addressing Profile rules on the 1EdTech specification development methodology (using the 1EdTech Binding Auto-generation Toolkit) and the WSDL binding that are created;

5. Relationship to the Other 1EdTech GWS Profiles

Describes the relationships and dependencies between this profile and the other 1EdTech GWS profiles;

6. Extending the Addressing Profile

A brief discussion of the ways in which the Addressing Profile can be extended to support proprietary requirements and an indication of future development for this profile;

7. Conformance to the Addressing Profile

An explanation of how conformance for systems that use the Addressing Profile can be demonstrated;

Appendix A Glossary of Terms

Definition of the concepts, terms and technologies used within this document. This material complements the Abstract Framework Glossary.

1.3 Nomenclature

EPR Endpoint Reference
HTTP Hypertext Transport Protocol
IAF 1EdTech Abstract Framework
I-BAT 1EdTech Binding Auto-generation Toolkit
MAP Message Addressing Properties
MEP Message Exchange Pattern
SOAP Simple Object Access Protocol
UML Unified Modelling Language
URI Universal Resource Identifier
URL Universal Resource Locator
W3C World Wide Web Consortium
WSDL Web Services Description Language
WS-I Web Services Interoperability Organization
XML Extensible Mark-up Language
XSD XML Schema Definition
XSLT Extensible Stylesheet Language Transformations

1.4 References

[AbsGloss, 03] 1EdTech Abstract Framework: Glossary v1.0, Ed. C.Smythe, 1EdTech/GLC, July 2003.
[GWS, 05a] 1EdTech General Web Services Base Profile Final Release, C.Schroeder, J.Simon and C.Smythe, V1.0 1EdTech/GLC, December 2005.
[GWS, 05b] 1EdTech General Web Services WSDL Binding Guidelines Final Release, C.Schroeder, J.Simon and C.Smythe, V1.0 1EdTech/GLC, December 2005.
[GWS, 05c] 1EdTech Binding Auto-generation Toolkit Manual, C.Smythe, V1.0 1EdTech/GLC, December 2005.
[RFC2119, 97] RFC 2119: Key words for use in RFC to Indicate Requirement Levels, S.Bradner, IETF, March 1997.
[WSA, 05a] Web Services Addressing 1.0 - Core, M.Gudgin and M.Hadley, W3C Candidate Recommendation, http://www.w3.org/TR/2005/CR-ws-addr-core-20050817, August 2005.
[WSA, 05b] Web Services Addressing 1.0 - SOAP Binding, M.Gudgin and M.Hadley, W3C Candidate Recommendation, http://www.w3.org/TR/2005/CR-ws-addr-soap-20050817, August 2005.
[WSA, 05c] Web Services Addressing 1.0 - WSDL Binding, M.Gudgin and M.Hadley, W3C Working Draft, http://www.w3.org/TR/2005/WD-ws-addr-wsdl-20050413, April 2005.
[WSDL, 01] Web Services Description Language, http://www.w3.org/TR/2001/NOTE-wsdl-20010315, Version 1.1, W3C, W3C Note, March 2001.

2. Addressing Framework

2.1 WS-Addressing

The W3C WS-Addressing recommendation defines a standard for incorporating message addressing information into Web Services messages. WS-Addressing provides a uniform addressing method for SOAP messages traveling over synchronous and/or asynchronous transports. Additionally, it provides addressing features to help web service developers build applications around a variety of messaging patterns beyond the typical exchange of requests and responses. WS-Addressing is independent of the other WS-* specifications but can be used in conjunction with them. WS-Addressing extends and incorporates some concepts from WSDL [WSDL, 01], but there is no explicit dependency between the two. Web services developers can use either or both, depending on their needs. WS-Addressing is currently published as three separate specifications:

  • WS-Addressing Core [WSA, 05a] - defines the abstract properties;
  • WS-Addressing SOAP binding [WSA, 05b] - defines the SOAP binding for WS-Addressing;
  • WS-Addressing WSDL binding [WSA, 05c] - defines the WSDL binding for WS-Addressing;

SOAP does not provide a standard way to specify where a message is going, how to return a response, or where to report an error. Those details have, historically, been left to the transport layer. Addressing at the transport level is sufficient for many existing services, but it is a limiting factor in the development of others. WS-Addressing defines standard ways to route a message over multiple transports or direct a response to a third party. WS-Addressing is achieved by extending the SOAP header i.e.

<soap11:Envelope xmlns:soap11="http://www.w3.org/2003/05/soap-envelope" 
   xmlns:wsa="http://www.w3.org/2005/03/addressing">
   <soap11:Header>
      <wsa:MessageID>AVSGEHUWEJIOLIUOMNGG1245</wsa:MessageID>
      <wsa:ReplyTo>
         <wsa:Address>http://www.imsglobal.org/myaddress</wsa:Address>
      </wsa:ReplyTo>
      <wsa:FaultTo>
         <wsa:Address>http://www.imsglobal.org/faultaddress</wsa:Address>
      </wsa:FaultTo>
      <wsa:To>http://www.imsglobal.org/serveraddress</wsa:To>
      <wsa:Action>http://www.imsglobal.org/serviceoperationrequest</wsa:Action>
   </soap11:Header>
   <soap11:Body>
      ...
         <!-- The message body of the SOAP request appears here -->
      ...
   </soap11:Body>
</soap11:Envelope>

WS-Addressing introduces two new Web Services constructs: Endpoint References (EPRs) and Message Addressing Properties (MAPs). "Endpoint" is an established term for a destination at which a Web Service can be accessed. EPRs are a new model for describing these destinations. MAPs, which may include one or more endpoint references, provide a context for that destination information.

2.1.1 Endpoint References (EPRs)

The WS-Addressing specification introduces a new description element type, the EPR, with the intent of supporting a set of dynamic usage patterns not currently appropriately covered by WSDL 1.1. EPRs are defined as a complex type in the WS-Addressing schema that contains an address (a URI), reference properties, reference parameters, a port type, a service name, and policy elements (defined by the WS-Policy specification). The only required element of an endpoint reference is the address, so the simplest EPR is:

   <wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/03/addressing">
      <wsa:Address>http://www.imsglobal.org/services/myservice</wsa:Address>
   </wsa:EndpointReference>

The other elements of an EPR are optional. The port type and service name elements are very similar to their WSDL counterparts [GWS, 05a]. WSDL defines a port type as an identifying name attached to an abstract set of operations. The port type and service name in a WS-Addressing EPR provide compatibility with WSDL.

A significant aspect of an EPR is the ability to attach data from other XML namespaces using reference properties or reference parameters. Both of these elements are collections of properties and values that can be used to incorporate elements from any XML namespace into the EPR. A reference property is used to identify the endpoint at which a service is deployed. Two EPRs that share a URI but specify different reference property values represent two different services. Reference properties are used to dispatch a request to the appropriate service. For example, one might deploy two different versions of a service and have requests specify a target version in their reference parameters. When a service receives a request and fulfills it, its behavior should not vary in response to the reference properties. Reference parameters are meant to identify resources managed by a particular service. Reference parameters tell a service which resources to handle. They do not identify the service. Two EPRs with different reference parameters do refer to the same service.

EPRs complement and do not replace the WSDL 1.1 <wsdl:service> element. The EPR is linked to the associated WSDL 1.1 description using one of two methods:

  • External meta-data reference
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/03/addressing">
      <wsa:Address>http://www.imsglobal.org/services/myservice</wsa:Address>
      <wsa:Metadata xmlns:wsdli="http://www.w3/org/2005/08/wsdl-instance"
         wsdli:wsdlLocation="http://www.imsglobal.org/services/myservice.wsdl">
      </wsa:Metadata>
</wsa:EndpointReference>

  • Embedded meta-data
<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/03/addressing">
      <wsa:Address>http://www.imsglobal.org/services/myservice</wsa:Address>
      <wsa:Metadata>
         <wsdl11:definitions targetNamespace=""
            ...
            xmlns:wsdl11="http://schemas.xmlsopa.org/wsdl/">
            ...
            ...
            <wsdl11:service name="myservicename">
               ...
               ...
            </wsdl11:service>
         </wsdl11:definitions>
      </wsa:Metadata>
</wsa:EndpointReference>

Each EPR must be individually defined and linked to the associated service and port/interface. At the current time 1EdTech/GLC will not supply the EPRs as part of the service specification development.

2.1.2 Message Addressing Properties (MAPs)

MAPs define the full set of addressing information that can be attached to a SOAP message. The MAP objects are:

  • [destination] : URI (mandatory) - the address of the intended receiver of this message;
  • [recipient] : EPR (optional) - the intended receiver of this message;
  • [source endpoint] : EPR (optional) - from where the message originated;
  • [reply endpoint] : EPR (optional) - this identifies the intended receiver for replies to this message. When formulating a reply message, the sender SHOULD use the contents of the [reply endpoint] of the message being replied to formulate the reply message. If the [reply endpoint] is absent, the sender MAY use the contents of the [source endpoint] to formulate the reply message. This property may be absent if the message has no meaningful reply, e.g., is a one-way application message, or when the reply endpoint has already been communicated to the target by other means. If the [reply endpoint] contains embedded policy, that policy must be the complete policy for that endpoint;
  • [fault endpoint] : EPR (optional) - identifies the intended receiver for faults related to this message. When formulating a fault message, the sender SHOULD use the contents of the [fault endpoint] of the message being replied to formulate the fault message. If the [fault endpoint] is absent, the sender MAY use the contents of the [reply endpoint] to formulate the fault message. If both the [fault endpoint] and [reply endpoint] is absent, the sender MAY use the contents of the [source endpoint] to formulate the fault message. This property may be absent if the sender cannot receive fault messages (e.g., is a one-way application message). If the [fault endpoint] contains embedded policy, that policy must be the complete policy for that endpoint.
  • [action] : URI (mandatory) - an identifier that uniquely (and opaquely) identifies the semantics implied by this message. It is RECOMMENDED that the value of the [action] property is a URI corresponding to an abstract WSDL construct, e.g., message, operation, port type available at the destination endpoint. In this case, the "relates to" property determines if the action is a request or response (the "direction" of the message). It is expected that at least one interoperable URI encoding scheme for computing an action element from WSDL will be defined. An action may be associated with the WSDL definition of an operation using a Policy element. The algorithm used for computing the action element URI from the WSDL definition of the endpoint may also be identified using an attached Policy element. Finally, it is possible to explicitly associate an arbitrary URI with an operation, superceding all declared encoding algorithms. This provides support to bottom-up development models;
  • [message id] : URI (optional) - a URI that uniquely identifies this message in time and space. No two messages may share a [message id] property. The value of this property is an opaque URI whose interpretation beyond equivalence is not defined in this specification;
  • [relationship] : (Qname, URI) (0..unbounded) - a pair of values that indicate how this message relates to another message. The type of the relationship is identified by a Qname. The related message is identified by a URI that corresponds to the related message's [message id] property.
  • [reference parameters] : xs:any (0..unbounded) - corresponds to the value of the reference parameters property of the EPR to which the message is addressed.

These properties are inserted into the SOAP header. Different combinations of properties are used depending on the message exchange pattern. The 1EdTech GWS Message Exchange patterns (MEPs) are Synchronous, Asynchronous and Polled. The Synchronous MEP is equivalent to the Request/Response MEP in the WS-Addressing WSDL Binding [WSA, 05c].

The MAP approach has been selected for the 1EdTech GWS Addressing Profile as this is based upon extending the WSDL v1.1 files.

2.2 Addressing Processing Workflow

The key terms used in the description of the work-flow are defined in Table 2.1.

Table 2.1 Key terms for the workflow description.

Term Definition
INITIATOR An application that consumes a Web Service by sending SOAP messages and attachments to a RESPONDENT.
RESPONDENT An application that exposes a Web Service and performs processing upon receiving SOAP messages and attachments from an INITIATOR.
MESSAGE An 1EdTech message encapsulated within a SOAP envelope as referenced in the [GWS, 05b]
SOURCE The ENDPOINT that transmits the MESSAGE to the RESPONDENT
DESTINATION The ENDPOINT that receives messages from the INITIATOR.

Note that INITIATOR and RESPONDENT as used in the rest of the document, are at a different level of abstraction compared to SOURCE and DESTINATION, the former belong to the application layer, while the latter belong to the messaging infrastructure layer and provide services to INITIATORS and RESPONDENTS (see Figure 2.1).

Schematic representation of the web service support for an application
Figure 2.1 Schematic representation of the web service support for an application.

The following is a step-by-step breakdown of a typical workflow for exchanging 1EdTech MESSAGES that use the GWS Addressing Profile. This workflow represents a common sequence of tasks. As a result, this workflow is intended to outline the pertinent tasks and is not prescriptive as to the sequence of fine-grained steps:

  1. INITIATOR constructs an 1EdTech MESSAGE according to the relevant 1EdTech specification and the WSDL binding guidelines [GWS, 05b];
  2. The Web Services Messaging Adapter within the INITIATOR:-
    • Constructs the SOAP message request header according to the service WSDL. The action value specified in the WSDL is used to construct the <wsa:Action> header. The <wsa:To> and <wsa:ReplyTo> endpoint addresses are taken from the 'soap:address/@location' attribute values for the service. The <wsa:MessageID> value is allocated as per the local algorithm
    • Encapsulates the 1EdTech MESSAGE in the body of the SOAP message
    • Passes the 1EdTech MESSAGE and any ATTACHMENT to SOURCE;
  3. SOURCE transmits the 1EdTech MESSAGE through the transport;
  4. 1EdTech MESSAGE is transferred to the DESTINATION;
  5. DESTINATION gets the 1EdTech MESSAGE from the transport;
  6. The Web Services Messaging Adapter within the RESPONDENT:-
    • Decodes and detaches all ATTACHMENTs attached to the message
    • Constructs the SOAP message response header according to the service WSDL. The action value specified in the WSDL is used to construct the <wsa:Action> header. The <wsa:To> and <wsa:ReplyTo> endpoint addresses are taken from the 'soap:address/@location' attribute values for the service. The <wsa:MessageID> value is allocated as per the local algorithm
    • Passes the receipt/response message to the INITIATOR
    • RESPONDENT extracts, validates and processes the 1EdTech MESSAGE and any ATTACHMENT.

3. Addressing Profile Rules

Table 3.1 summarizes the set of rules used for the Addressing Profile. Within Table 3.1 the following conventions are used:

  • 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 RFC2119 [RFC2119, 97];
  • Normative statements in the Profile are presented in the following manner: RADPnnnnStatement text here, where "nnnn" is replaced by the statement number. Each statement contains exactly one requirement level keyword, e.g., "MUST", and one conformance target keyword, e.g., "MESSAGE".

Note that in the rules the namespace prefix "wsa" is used. Any consistent prefix may be used.

Table 3.1 Summary of the 1EdTech GWS Addressing Profile rules.

Identifier Description
Basic Addressing
RADP0001

All messages based upon the 1EdTech GWS Addressing Profile MUST use the WS-Addressing framework for SOAP-based messages.

The requirement to use this Profile.

RADP0002

All messages based upon the 1EdTech GWS Addressing Profile MUST have a corresponding WSDL file based upon WSDL v1.1 that contains the relevant information for the Message Addressing Properties.

This states that it is the MAP approach within WS-Addressing that must be supported.

RADP0003

An 1EdTech service using the 1EdTech GWS Addressing Profile MAY have Endpoint Reference definitions which MAY have the associated WSDL file embedded within the <wsa:Metadata> element.

EPR may also be used with the MAP approach in WS-Addressing. Embedded WSDL file approaches are permitted.

RADP0004

An 1EdTech service using the 1EdTech GWS Addressing Profile MAY have Endpoint Reference definitions which MAY have the associated WSDL file externally referenced by the <wsa:Metadata> element.

EPR may also be used with the MAP approach in WS-Addressing. Externally referenced WSDL file approaches are permitted.

Synchronous Message Exchange Pattern - SOAP v1.1 Request Message
RADP2001

All Request SOAP messages MUST contain the <wsa:To> header element.

This is the EPR for the Destination. The value for this element is the same as the value of the 'soap:address/@location' attribute in the WSDL file for the service.

RADP2002

All Request SOAP messages MUST contain the <wsa:Action> header element.

This element is used by the Destination to identify the semantics of the input message.

RADP2003

The value of the <wsa:Action> header element must be set to the value of the 'soapAction' attribute as defined in the XPath '/definitions/binding/operation/soap:operation' element.

This value is used to identify the input message within the WSDL portType for the service.

RADP2004

All Request SOAP messages MUST contain the <wsa:ReplyTo> header element.

This is the EPR for the Source. The value for this element is the same as the value of the 'soap:address/@location' attribute in the WSDL file for the service. This is the address to which the Response message will be sent.

RADP2005

All Request SOAP messages MUST contain the <wsa:MessageID> header element.

This is unique identifier for the message. The value of this element is the same as that assigned to the <imsx_messageIdentifier> element within the 1EdTech GWS SOAP header. This identifier must be unique for the duration of the communications session. The generation of this value is left to the implementation but should take the form of <xs:anyURI>.

RADP2006

Request SOAP messages MAY contain other valid WS-Addressing MAP elements.

The other MAP elements may be used to provide service-specific information. These service-specific elements will be defined in the associated 1EdTech service specification.

RADP2007

Request SOAP messages MUST NOT use other valid WS-Addressing MAP elements to redefine the information mandated by this Addressing Profile.

A service must not redefine the SOAP Request message rules defined in this Profile by using other MAP elements.

RADP2008

Duplicate Response messages MUST NOT result in duplicate information processing by the Initiator application.

It is the responsibility of the Source to ensure that duplicate Response messages do not result in duplication information processing by the local application(s).

Synchronous Message Exchange Pattern - SOAP v1.1 Response Message
RADP4001

All Response SOAP messages MUST contain the <wsa:To> header element.

This is the EPR for the Source. The value for this element is the same as the value of the 'soap:address/@location' attribute in the WSDL file for the service.

RADP4002

All Response SOAP messages MUST contain the <wsa:Action> header element.

This element is used by the Source to identify the semantics of the output message.

RADP4003

The value of the <wsa:Action> header element must be set to the value of the 'soapAction' attribute as defined in the XPath 'definitions/binding/operation/soap:operation' element.

This value is used to identify the output message within the WSDL portType for the service.

RADP4004

All Response SOAP messages MUST contain the <wsa:MessageID> header element.

This is unique identifier for the message. The value of this element is the same as that assigned to the <imsx_messageIdentifier> element within the 1EdTech GWS SOAP header. This identifier must be unique for the duration of the communications session. The generation of this value is left to the implementation but should take the form of <xs:anyURI>.

RADP4005

All Response SOAP messages MUST contain the <wsa:RelatesTo> header element.

This element is used by the Destination to denote that this message is a response to a previous request message from the Source.

RADP4006

The value of the <wsa:RelatesTo> element must be set to the value of the <wsa:MessageID> element of the Source's Request message which causes the generation of this Response message.

This information is used by the Source to correlate the Response message with the originating Request message.

RADP4007

The value of the attribute 'RelationshipType' for the <wsa:RelatesTo> element MUST be set to "http://www.w3c.org/2005/08/addressing/reply".

This identifies the message as a response to a previous request message. Note that the Source may not be blocked and so it MUST keep a record of all requests that have not yet had a response.

RADP4008

Response SOAP messages MAY contain other valid WS-Addressing MAP elements.

The other MAP elements may be used to provide service-specific information. These service-specific elements will be defined in the associated 1EdTech service specification.

RADP4009

Response SOAP messages MUST NOT use other valid WS-Addressing MAP elements to redefine the information mandated by this Addressing Profile.

A service must not redefine the SOAP Response message rules defined in this Profile by using other MAP elements.

RADP4010

Duplicate Request messages MUST NOT result in duplicate information processing by the Respondent application.

It is the responsibility of the Destination to ensure that duplicate Request messages do not result in duplication information processing by the local application(s).

WSDL v1.1 Encodings
RADP6001

The 1EdTech GWS Address Profile MAP values MUST be defined using WSDL v1.1.

All of the WSDL files that conform to WSDL v1.1 must be produced for the service.

RADP6002

The WS-Addressing namespace of "http://www.w3.org/2005/03/addressing' MUST be used.

The WS-Addressing namespace used within the WSDL files and the SOAP messages is defined as http://www.w3c.w3.org/2005/03/addressing.

RADP6003

The empty <wsa:UsingAddressing> element with the attribute 'wsdl:required=true' MUST be used in the <wsdl:binding> element.

This is used to indicate that WS-Addressing is to be used for this service binding.

RADP6004

The attribute 'wsa:Action' on the XPath '/definitions/portType/operation/input' element MUST be defined.

This element is used to supply the value of MAP <wsa:Action> element for the Request message in the WS-Addressing SOAP header extension.

RADP6005

The value of the attribute 'wsa:Action' for the input structure SHOULD be defined as: [AddressLocationRoot][delimiter][portType_name][delimiter][input_message_name].

The values of this default structure are:

[delimiter] = '/'

[AddressLocationRoot] = XPath value of 'definition/service/port/soap:address/soap:address/@location' minus the last leaf string value (this root value is supplied as part of the 1EdTech UML Profile and supported by the I-BAT).

[portType_name] = XPath value of '/definition/portType/@name'

[input_message_name] = concatenation of XPath value of '/definition/binding/operation/@name' with the string "Request".

RADP6006

The attribute 'wsa:Action' on the XPath '/definitions/portType/operation/output' element MUST be defined.

This element is used to supply the value of MAP <wsa:Action> element for the Response message in the WS-Addressing SOAP header extension.

RADP6007

The value of the attribute 'wsa:Action' for the output structure SHOULD be defined as: [AddressLocationRoot][delimiter][portType_name][delimiter][output_message_name].

The values of this default structure are:

[delimiter] = '/'

[AddressLocationRoot] = XPath value of 'definition/service/port/soap:address/soap:address/@location' minus the last leaf string value (this root value is supplied as part of the 1EdTech UML Profile and supported by the I-BAT).

[portType_name] = XPath value of '/definition/portType/@name'

[output_message_name] = concatenation of XPath value of '/definition/binding/operation/@name' with the string "Response".

4. WSDL Binding Implications

The usage of 1EdTech GWS Addressing Profile requires the following information to supplied as part of the specification process:

  • Identification that the Addressing Profile is to be used.

From the perspective of the WSDL 1.1 the attachment information is presented in the WSDL definition part of the file. The transformation files in the 1EdTech Binding Auto-generation Toolkit (I-BAT) [I-BAT, 05] use the information supplied in the UML description as described in Table 4.1. In Table 4.1 each attribute has an example value and for each set of values there follows the corresponding WSDL file.

Table 4.1 Synchronous single file auto-generation including the Addressing Profile.

Attribute Original Value
ServiceGroupModel Attributes
Service Group Package Name ExampleGroup
WSDLv1.1:NameSpaceRoot http://www.example/services/
WSDLv1.1:TargetNameSpaceLeaf wsdlfilev1p0
WSDLv1.1:TargetNameSpacePrefix tns
WSDLv1.1:AbstractFileNameSpaceLeaf Unused
WSDLv1.1:AbstractFileNameSpacePrefix Unused
WSDLv1.1:XSDLinkNameSpaceLeaf Unused
WSDLv1.1:XSDLinkNameSpacePrefix Unused
WSDLv1.1:MessageHdrNameSpaceLeaf Unused
WSDLv1.1:MessageHdrNameSpacePrefix Unused
WSDLv1.1:WS-Addressing Yes
<wsdl11:definitions name = "ExampleGroupSyncServices" 
   targetNamespace = "http://www.example/services/wsdl/sync/wsdlfilev1p0" 
   xmlns:tns = "http://ww.example/services/wsdl/sync/wsdlfilev1p0"
   xmlns:soap11 = "http://schemas.xmlsoap.org/wsdl/soap/"
   xmlns:wsdl11 = "http://schemas.xmlsoap.org/wsdl/"
   xmlns:wsa = "http://www.w3.org/2005/03/addressing" 
   xmlns:xs = "http://www.w3.org/2001/XMLSchema" 
   xmlns:xsi = "http://www.w3.org/2000/10/XMLSchema-instance">
ServiceModel Attributes
Service Package Name EgServiceName
SOAPv1.1:AddressLocationRoot http://www.example.soap/serviceuri/
SOAPv1.1:OperationActionRoot http://www.example/soap/service/
<wsdl11:service name = "EgServiceNameSyncService">
   <wsdl11:port name = "CoreOperationsNameSyncSoapPort" binding = "...">
      <soap11:address 
         location="http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap/"/>
   </wsdl11:port>
</wsdl11:service>
Interface Attributes
Interface Name CoreOpsName
<wsdl11:portType name = "coreOpsNamePortType">
   <wsdl11:operation name = "createObject">
      <wsdl11:input message = "tns:createObjectRequest" wsa:Action =
         "http://www.example.soap/serviceuri/coreOpsNamePortType/createObjectRequest"/>
      <wsdl11:input message = "tns:createObjectResponse" wsa:Action =
         "http://www.example.soap/serviceuri/coreOpsNamePortType/createObjectResponse"/>
   </wsdl11:operation>
</wsdl11:portType
<wsdl11:binding name = "CoreOpsNameSyncSoapBinding" type="tns:CoreOpsNameSyncPortType">
   <soap11:binding transport="http://schema.xmlsoap.org/soap/http" style="document"/>
   <wsa:UsingAddressing wsdl:required = "true"/>
   <wsdl11:operation name="createObject">
      <soap11:operation soapAction="http://www.example/soap/service/createObject" 
         style="document"/>
      ...
   </wsdl11:operation>
</wsdl11:binding>
<wsdl11:service name = "EgServiceNameSyncService">
   <wsdl11:port name = "CoreOpsNameSyncSoapPort" binding = "tns:CoreOpsNameSyncSoapBinding">
      <soap11:address 
         location="http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap/"/>
   </wsdl11:port>
</wsdl11:service>
DataModel Attributes
NameSpaceRoot Unused
NameSpaceLeaf Unused
NameSpacePrefix Unused
SchemaVersion 1EdTech 1.0
QualifiedElements Yes
QualifiedAttributes No
<wsdl11:types>
   <xs:schema xmlns="http://www.w3.org/2001/XMLSchema"
          targetNamespace="http://www.example/services/wsdl/sync/wsdlfilev1p0"
      xmlns:xsd=http://www.w3.org/2001/XMLSchema                                        
      xmlns:xsi=http://www.w3.org/2000/10/XMLSchema-instance
      xmlns:xmlmime="http://www.w3.org/2004/06/xmlmime"
      version="1EdTech 1.0"
      elementFormDefault="qualified"
      attributeFormDefault="unqualified">

      ...

   </xs:schema>
</wsdl11:types>

The corresponding 1EdTech GWS SOAP request message produced is (the text shown in bold is specific to the usage of WS-Addressing):

SOAP request message
<SOAP-ENV:Envelope
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:wsa="http://www.w3.org/2005/03/addressing">
   <SOAP-ENV:Header>
      <wsa:To>http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap</wsa:To>
      <wsa:Action>http://www.example.soap/serviceuri/coreOpsNamePortType/createObjectRequest
      </wsa:Action>
      <wsa:ReplyTo>
         <wsa:Address>http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap
         </wsa:Address>
      </wsa:ReplyTo>
      <wsa:MessageID>MessageIDSTRINGinitiator</wsa:MessageID>
      <imsx_syncRequestHeaderInfo 
         xmlns="http://www.imsglobal.org/services/ti/wsdl/sync/sync/wsdlfilev1p0">
         <imsx_version>1.0</imsx_version>
         <imsx_messageIdentifier>MessageIDSTRINGinitiator</imsx_messageIdentifier>
      </imsx_syncRequestHeaderInfo>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
      <createObjectRequest xmlns="http://www.example/services/wsdl/sync/wsdlfilev1p0">

         ...

      </ceateObjectRequest>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The corresponding 1EdTech GWS SOAP response message produced is (the text shown in bold is specific to the usage of WS-Addressing):

SOAP response message
<SOAP-ENV:Envelope
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:wsa="http://www.w3.org/2005/03/addressing">
   <SOAP-ENV:Header>
      <wsa:To>http://www.example.soap/serviceuri/EgServiceNameSyncServiceSoap</wsa:To>
      
<wsa:Action>http://www.example.soap/serviceuri/coreOpsNamePortType/createObjectResponse 
      </wsa:Action>
      <wsa:MessageID>MessageIDSTRINGrespondent</wsa:MessageID>
      <wsa:RelatesTo wsa:RelationshipType = 
"http://www.w3.org/2005/08/adddressing/reply">

         MessageIDSTRINGinitiator
      </wsa:RelatesTo>
      <imsx_syncResponseHeaderInfo 
         xmlns="http://www.imsglobal.org/services/ti/wsdl/sync/sync/wsdlfilev1p0">
         <imsx_version>1.0</imsx_version>
         <imsx_messageIdentifier>MessageIDSTRINGrespondent</imsx_messageIdentifier>
         <imsx_statusInfo>
            ...
         <imsx_statusInfo>
      </imsx_syncResponseHeaderInfo>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
      <createObjectResponse xmlns="http://www.example/services/wsdl/sync/wsdlfilev1p0">

         ...

      </ceateObjectResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

5. Relationship to the Other GWS Profiles

The relationship of the Addressing Profile to the other 1EdTech GWS profiles is shown in Figure 5.1.

Relationship between the Addressing Profile and the other 1EdTech GWS Profiles
Figure 5.1 Relationship between the Addressing Profile and the other 1EdTech GWS Profiles.

The Addressing Profile assumes that the Base Profile is already being used [GWS, 05a]. WS-Security assumes the usage of WS-Addressing and so the 1EdTech GWS Addressing Profile must be used with the 1EdTech GWS Base Profile is WS-Security is to be adopted as part of the 1EdTech GWS Security Profile.

6. Extending the Addressing Profile

6.1 Proprietary Extensions

Extensions to the Addressing Profile are restricted to using the reference parameters element within the MAP. The <wsa:ReferenceParameters> element should be used to pass service-specific extension data between the communications web service entities. The <wsa:ReferenceParameters> element is a SOAP header extension which can occur any number of times and which can contain any name-spaced element or attribute.

Any extensions must be agreed using external mechanisms and services that do not recognize the extension features should ignore them.

6.2 Further Work in V2.0

In 1EdTech GWS v2.0 further work will focus on three areas:

  1. The usage of the Addressing Profile with SOAP v1.2 and WSDL v2.0;
  2. Definition of what to do when SOAP faults occur. The current Addressing Profile does not provide specific instructions for handling SOAP fault messages;
  3. Investigation of the provision of separate EPR files. This would be an alternative method to using the current WSDL files to contain all of the WS-Addressing information. In this approach the WSDL files are either embedded or referenced using the EPR meta-data element.

7. Conformance to the Addressing Profile

Any claim of conformance for an implementation against the Addressing Profile must show that the implementation complies with the set of profile rules listed in Section 3.

Apart from the WS-I Conformance Claims mechanism, the W3C is investigating the usage of WS-Policy. Therefore, no definitive recommendation is made on the usage of the WS-I approach. More information on the WS-I Conformance Claim mechanism is given in the 1EdTech GWS WSDL Binding Guidelines document [GWS, 05b]. However, if some form of conformance statement is required then the WS-I approach may be used but no firm commitment is made to supporting this technique in later releases of the 1EdTech GWS specification.

Appendix A - Glossary of Terms

Throughout the General Web Services documents a variety of key terms, concepts and descriptions have been introduced. These terms, concepts and descriptions and defined below but where appropriate the normative definition from the IAF Glossary is referenced [AbsGloss, 03].

Destination The Endpoint that receives messages from the Initiator.
Endpoint An entity, processor, or resource that can be referenced and where Web Service messages are originated or targeted.
Endpoint Reference (EPR) An Endpoint Reference is a construct defined in WS-Addressing that enables the dynamic generation and customization of service endpoint descriptions, referencing and description of specific service instances that are created as the result of state-full interactions, and flexible and dynamic exchange of endpoint information in tightly coupled environments where communicating parties share a set of common assumptions about specific polices or protocols that are used during the interaction.
Initiator An application that consumes a Web Service by sending SOAP messages and attachments to a Respondent.
Message Addressing Properties (MAP) Message Addressing Properties provide references for the endpoints involved in an interaction. The use of these properties to support specific interactions is in general defined by both the semantics of the properties themselves and the implicit or explicit contract that governs the message exchange. If explicitly available, this contract can take different forms including but not being limited to WSDL MEPs and interfaces; business processes and e-commerce specifications, among others, can also be used to define explicit contracts between the parties.
Message Exchange Pattern (MEP) Message Exchange Patterns describe the sequence of messages that are exchanged between a Source and Destination. 1EdTech GWS has three MEPS: Synchronous, Asynchronous and Polled. The Synchronous MEP is in effective the request-response message choreography.
Respondent An application that exposes a Web Service and performs processing upon receiving SOAP messages and attachments from an Initiator.
Source The Endpoint that transmits the messages to the Respondent.
WS-Addressing WS-Addressing provides a transport-neutral mechanisms to address Web services and messages. Specifically, this specification defines XML elements to identify Web service endpoints and to secure end-to-end endpoint identification in messages. This specification enables messaging systems to support message transmission through networks that include processing nodes such as endpoint managers, firewalls, and gateways in a transport-neutral manner.

About This Document

Title 1EdTech General Web Services Addressing Profile
Editor Colin Smythe (1EdTech)
Team Co-Leads Cathy Schroeder (Microsoft Corp.), James Simon (SUN Microsystems Corp.)
Version 1.0
Version Date 19 December 2005
Status Final Specification
Summary This document contains the description of the profiling of the WS-Addressing specification from the World Wide Web Consortium to enhance the 1EdTech General Web Services Base Profile. WS-Addressing defines an end-point addressing mechanism that is transport independent.
Revision Information 19 December 2005
Purpose This document is circulated for public adoption. This document is to be adopted by 1EdTech and all other organizations that wish to enhance the 1EdTech General Web Services Base Profile to support WS-Addressing.
Document Location http://www.imsglobal.org/gws/gwsv1p0/imsgws_addressProfv1p0.html

To register any comments or questions about this specification please visit: http://www.imsglobal.org/developers/ims/imsforum/categories.cfm?catid=20

List of Contributors

The following individuals contributed to the development of this document:

Name Organization
Fred Beshears UC Berkeley
John Evdemon Microsoft Corp.
Ron Kleinman SUN Micrsosystems Corp.
Sherman Mohler Cisco Learning Institute, Inc.
Cathy Schroeder Microsoft Corp.
James Simon SUN Microsystems Corp.
Colin Smythe Dunelm Services Ltd.
Scott Thorne MIT

Revision History

Version No. Release Date Comments
Final v1.0 19 December 2005 This is the first formal version of the Final Release.

Index

A
Abstract Framework 1, 2, 3
Asynchronous 1, 2

B
Base Profile 1, 2, 3

C
Conformance 1, 2
Context 1

E
Endpoint Reference 1, 2, 3, 4, 5, 6, 7, 8, 9

I
1EdTech Auto-generation Binding Tool 1, 2, 3, 4
1EdTech General Web Services 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
Addressing Profile 1, 2, 3, 4, 5, 6, 7, 8
Base Profile 1, 2, 3, 4, 5, 6
Security Profile 1
 

M
Message Addressing Properties 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
Messaging
Asynchronous 1, 2
Polled 1, 2
Synchronous 1, 2, 3, 4, 5
 

P
Protocols
HTTP 1
SOAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
 

S
SOAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
Synchronous 1, 2, 3, 4, 5

U
Unified Modelling Language 1, 2, 3, 4
UML 1, 2, 3, 4
 

W
W3C 1, 2, 3, 4
Web Services 1, 2, 3, 4, 5, 6
SOAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
WS-Addressing 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
WSDL 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
WS-Security 1
Web Services Interoperability Organization 1, 2
WSA 1, 2, 3, 4
WS-Addressing 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
Endpoint Reference 1, 2, 3, 4, 5
EPR 1, 2, 3, 4, 5, 6, 7, 8, 9
MAP 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Message Addressing Properties 1, 2, 3, 4, 5, 6
WSDL 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
WSDL Versions
1.1 1, 2, 3
WS-Security 1
 

X
XML 1, 2, 3
XML Schema 1
XML Schema Definition 1
XSD 1
XSLT 1

1EdTech Consortium, Inc. ("1EdTech/GLC") is publishing the information contained in this 1EdTech General Web Services Addressing Profile ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.

1EdTech/GLC makes no warranty or representation regarding the accuracy or completeness of the Specification.
This material is provided on an "As Is" and "As Available" basis.

The Specification is at all times subject to change and revision without notice.

It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.

1EdTech/GLC would appreciate receiving your comments and suggestions.

Please contact 1EdTech/GLC through our website at http://www.imsglobal.org

Please refer to Document Name:
1EdTech General Web Services Addressing Profile Revision: 19 December 2005