JEP-0072: SOAP Over XMPP

This JEP defines methods for transporting SOAP messages over XMPP.


WARNING: This Standards-Track JEP is Experimental. Publication as a Jabber Enhancement Proposal does not imply approval of this proposal by the Jabber Software Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.


JEP Information

Status: Experimental
Type: Standards Track
Number: 0072
Version: 0.7
Last Updated: 2005-06-30
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, SOAP 1.2
Supersedes: None
Superseded By: None
Short Name: soap

Author Information

Fabio Forno

Email: fabio.forno@polito.it
JID: sciasbat@jabber.linux.it

Peter Saint-Andre

Email: stpeter@jabber.org
JID: stpeter@jabber.org

Legal Notice

This Jabber Enhancement Proposal is copyright 1999 - 2005 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this JEP has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.


Table of Contents

1. Introduction
2. Architectural Assumptions
3. Transport of SOAP Envelopes
3.1. Synchronous Transport within IQ Stanzas
3.2. Asynchronous Transport within Message Stanzas
3.3. Error Reporting
4. Encoding
5. Attachments
6. WSDL Definition with XMPP Binding
7. SOAP XMPP Binding
7.1. Binding Name
7.2. Supported Features
7.3. Supported Message Exchange Patterns
7.4. Operation of Request-Response Message Exchange Pattern
7.4.1. Behavior of Requesting SOAP Node
7.4.1.1. Init
7.4.1.2. Requesting
7.4.1.3. Sending+Receiving
7.4.1.4. Success and Fail
7.4.2. Behavior of Responding SOAP Node
7.4.2.1. Init
7.4.2.2. Receiving
7.4.2.3. Receiving+Sending
7.4.2.4. Success and Fail
8. W3C Considerations
8.1. W3C Review
8.2. SOAP Versioning
8.3. XML Versioning
9. Security Considerations
10. IANA Considerations
11. Jabber Registrar Considerations
11.1. Protocol Namespaces
12. XML Schema
13. Implementation Notes
14. Acknowledgements
Notes
Revision History


1. Introduction

Simple Object Access Protocol (SOAP) [1] is a lightweight protocol that defines a method for the exchange of messages independently from the programming language and platform. For interoperability, the SOAP specification is also agnostic about possible transport protocols, though almost all existing implementations use mainly HTTP.

The primary limitation of HTTP consists in the fact that HTTP-based message exchanges allow only synchronous RPC-like calls. To overcome this limitation, SMTP is often used to carry asynchronous messages, but it is a complex protocol and inefficient for passing short and frequent messages that should be delivered in close to real time.

Thus XMPP (see XMPP Core [2]) can be the ideal transport protocol for many of the application fields of web services, since it can carry efficiently and reliably both types of messages, synchronous and asynchronous. Moreover, XMPP-based web services will not need complex support protocols, such as WS-Routing [3] and WS-Referral [4], in order to deliver messages to entities that cannot be identified by static public IP addresses. Therefore, this JEP defines a binding of SOAP to XMPP as an alternative to the existing HTTP and SMTP bindings.

(Note: The main body of this JEP provides descriptive text suitable for use by XMPP developers. A formal description of the SOAP XMPP Binding itself is provided in the section of this document entitled SOAP XMPP Binding.)

2. Architectural Assumptions

The usual architecture of XMPP is described in Section 2 of RFC 3920. In essence, XMPP is most commonly deployed using a client-server (or logical peer-to-peer) architecture quite similar to that of the email system, except that XMPP does not have multiple hops between servers, enforces domain names to prevent address spoofing, and enables channel encryption (via TLS) and authentication (via SASL) between client and server as well as among servers.

The binding of SOAP to XMPP assumes that most SOAP-enabled XMPP entities will be implemented as XMPP clients that communicate with other entities as logical peers. However, in order to deploy more scalable services, such entities could also be implemented as server-side components (see Jabber Component Protocol [5]) or even as special-purpose XMPP servers.

The SOAP world has defined the concept of "intermediaries". In general, these intermediaries are artifacts of the existing SOAP bindings (HTTP and SMTP) rather than applicable to all possible bindings. SOAP intermediaries are usually deployed in order to (1) cross trust boundaries in protocols that do not enforce domain names or authenticate end-points, (2) ensure scalability, (3) secure messages sent over unencrypted channels, and (4) provide message tracing. However, these problems are addressed natively in XMPP (e.g., channel encryption is defined in RFC 3920), in XMPP extensions (e.g., message tracing is defined in Advanced Message Processing [6]), or in deployment decisions such as business level agreements between XMPP domains. Therefore, SOAP intermediaries are not directly part of the architectural assumptions on which this specification is based. However, see the discussion in the Implementation Notes section of this document.

3. Transport of SOAP Envelopes

Since SOAP envelopes can transport both RPC-like calls and asynchronous one-way messages, both <iq/> and <message/> with <soap/> child elements are used in order to assure maximum flexibility. It is up to implementors to choose the appropriate stanza type for their applications:

  1. <iq/> stanzas MUST be used for RPC calls and when an immediate answer is required.
  2. <message/> stanzas MUST be used for asynchronous one-way communications and is useful when either store and forward or message tracing is desired.

Examples of these approaches are provided below; for a formal definition, refer to the SOAP XMPP Binding section of this document.

3.1 Synchronous Transport within IQ Stanzas

The transport with <iq/> stanzas is performed in a way similar to that described for XML-RPC in Jabber-RPC [7]. Request envelopes are carried by <iq/> stanzas of type "set", and answer envelopes by <iq/> stanzas of type "result". SOAP errors are encoded with standard SOAP envelopes, and returned in stanzas of type "error" with appropriate codes in order to distinguish them from errors specific to the XMPP transport layer.

Each <iq/> stanza MUST contain a unique SOAP envelope as the first-level child element, since it already represents a properly namespaced XML subtree qualified by the 'http://schemas.xmlsoap.org/soap/envelope' namespace.

Example 1. A SOAP request inserted into an IQ stanza

<iq from='requester@example.com/soap-client'
    id='soap1'
    to='responder@example.com/soap-server' 
    type='set'> 
  <env:Envelope xmlns:env='http://www.w3.org/2003/05/soap-envelope'>
    <env:Body>
      <m:GetLastTradePrice 
          xmlns:m='Some-URI'
          env:encodingStyle='http://www.w3.org/2003/05/soap-encoding'>
        <m:symbol>DIS</m:symbol>
      </m:GetLastTradePrice>
    </env:Body>
  </env:Envelope>
</iq>
    

Example 2. A SOAP response, inserted into an IQ stanza

<iq from='responder@example.com/soap-server' 
    id='soap1'
    to='requester@example.com/soap-client' 
    type='result'>
  <env:Envelope xmlns:env='http://www.w3.org/2003/05/soap-envelope'>
    <env:Body>
      <m:GetLastTradePriceResponse 
          xmlns:m='Some-URI'
          env:encodingStyle='http://www.w3.org/2003/05/soap-encoding'>
        <m:Price>34.5</m:Price>
      </m:GetLastTradePriceResponse>
    </env:Body>
  </env:Envelope>
</iq>
    

3.2 Asynchronous Transport within Message Stanzas

Message stanzas MUST carry one SOAP envelope as a first-level child element, as is done with <iq/> stanzas; the only difference is given by the different semantics and benefits of <message/> stanzas, such as store and forward. The 'id' attribute MUST be used to track SOAP messages and eventually associate errors or answers with the relative requests.

Example 3. A SOAP envelope carrying an RDF description of a RSS feed inserted into a message stanza

<message to='endpoint@example.com/soap-client' id='soap2'>
  <env:Envelope xmlns:env='http://www.w3.org/2003/05/soap-envelope'>
    <env:Body>
      <rdf:RDF 
          xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
          xmlns='http://my.netscape.com/rdf/simple/0.9/'>
        <channel>
          <title>Slashdot</title>
          <link>http://slashdot.org/</link>
          <description>News for nerds, stuff that matters</description>
        </channel>
        <item>
          <title>Jabber/XMPP now supports SOAP</title>
          <link>http://slashdot.org/somepath</link>
        </item>
      </rdf:RDF>
    </env:Body>
  </env:Envelope>
</message>
    

3.3 Error Reporting

SOAP provides its own encoding scheme for errors due to message processing or application execution, and it uses SOAP envelopes for reporting. The SOAP HTTP Binding maps these errors to corresponding HTTP status codes. Since <iq/> stanzas have the same behavior as typical HTTP request/response interactions, SOAP faults are mapped in a similar way in <iq/> stanzas of type "error". This approach should facilitate the design of HTTP<->XMPP gateways for web services. The following table provides a mapping between SOAP, HTTP, and <iq/> error codes (for Jabber/XMPP error syntax, see Section 9.3.3 of RFC 3920, and also Error Condition Mappings [8]).

Table 1: Mapping of SOAP Error codes

SOAP Error HTTP Code IQ Error Description
env:VersionMismatch 500 <internal-server-error/>
env:MustUnderstand 500 <internal-server-error/>
env:Sender 400 <bad-request/>
env:Receiver 500 <internal-server-error/>
env:DataEncodingUnknown 500 <internal-server-error/>

Example 4. A SOAP response with error, inserted into an IQ stanza

<iq type='error' to='requester@example.com/soap-client' id='soap1'>
  <env:Envelope
      xmlns:env='http://www.w3.org/2003/05/soap-envelope'
      xmlns:rpc='http://www.w3.org/2003/05/soap-rpc'>
    <env:Body>
      <env:Fault>
        <env:Code>
          <env:Value>env:Sender</env:Value>
          <env:Subcode>
            <env:Value>rpc:BadArguments</env:Value>
          </env:Subcode>
        </env:Code>
        <env:Reason>
          <env:Text xml:lang='en-US'>Processing error</env:Text>
        </env:Reason>
        <env:Detail>
          <e:myFaultDetails xmlns:e='http://travel.example.com/faults'>
            <e:message>Name does not match card number</e:message>
            <e:errorcode>999</e:errorcode>
          </e:myFaultDetails>
        </env:Detail>
      </env:Fault>
    </env:Body>
  </env:Envelope>
  <error code='500' type='cancel'>
    <internal-server-error xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

Since errors could occur also for asynchronous interaction using <message/> stanzas, the same error mapping scheme of <iq/> stanzas SHOULD be used. A typical situation where this can happen is a service receiving regular messages reporting remote sensor readings with asynchronous messages. If the controlling device detects some malfunctions in the sensors, it can send a <message/> stanza of type "error" to the monitoring application.

When errors are due to the XMPP transport protocol, and not to the application layer defined by SOAP, errors MUST be reported with standard XMPP error codes only (i.e., not including the SOAP envelope).

Example 5. An XMPP entity reports that it cannot handle SOAP messages

<iq type='result' to='requester@example.com/soap-client' id='soap1'>
  <error code='503' type='cancel'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

4. Encoding

Because XMPP does not require the parsing of arbitrary and complete XML documents, and does not require implementations to support the full XML specification, transported SOAP envelopes MUST comply with the XML restrictions specified in Section 11 ("XML Usage Within XMPP") of RFC 3920. In particular, all envelope elements MUST be properly namespaced (SOAP allows elements within the default namespace, but they are deprecated since SOAP 1.2).

SOAP envelopes may contain arbitrary data encoded in valid XML, and also byte arrays encoded with SOAP-specific elements. The SOAP specification recommends to encode byte arrays in Base 64 (see RFC 3548 [9]), with the result that envelopes with binary data can be transported within regular XMPP stanzas. All the remaining PCDATA MUST be encoded with UTF-8 in order to match the XML stream encoding.

5. Attachments

Binary data could grow significantly in size, and messages carrying it could be penalized by servers with bandwidth restriction settings (commonly called "karma" in XMPP) tuned for normal text chats. The problem could be bypassed by servers having special karma settings for larger messages, or by SOAP-enabled entities being implemented as components; however, server-to-server communications risk becoming a serious bottleneck, especially in terms of latency and responsiveness when too many large messages are sent.

SOAP provides several methods to transport binary data as attachments; the most common are:

First, inserting a link to the file directly either into the XMPP message or IQ stanza (e.g, via Out-of-Band Data [10]) or into the SOAP envelope (e.g., via Resource Representation SOAP Header Block [11]). This is a general method that can be used by XMPP clients if they are able to retrieve the file via HTTP (see JEP-0066).

Second, encoding SOAP envelopes and attachments as MIME multipart messages using SOAP 1.2 Attachment Feature [12] (or, more recently, SOAP Message Transmission Optimization Mechanism [13] and XML-binary Optimized Packaging [14]). This can work well for the HTTP and email bindings of SOAP but cannot be used directly with XMPP since XML streams transport pure XML only and not MIME messages; consider the following example:

Example 6. SOAP attachment using MIME

MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml;
        start="<claim061400a.xml@claiming-it.com>"
Content-Description: This is the optional message description.

--MIME_boundary
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <claim061400a.xml@claiming-it.com>

<?xml version='1.0' ?>
<env:Envelope
xmlns:env='http://www.w3.org/2003/05/soap-envelope'>
<env:Body>
..
<theSignedForm href='cid:claim061400a.tiff@claiming-it.com'/>
..
</env:Body>
</env:Envelope>

--MIME_boundary
Content-Type: image/tiff
Content-Transfer-Encoding: binary
Content-ID: <claim061400a.tiff@claiming-it.com>
...
  

Third, using other protocols designed to transport SOAP and binary data together, such as WS-Attachments [15] and SOAP-over-BEEP as defined in RFC 3288 [16]. These methods are just other transport protocols and most likely would needlessly complicate implementations of SOAP over XMPP.

Therefore, to transport binary data when a URL cannot be provided using JEP-0066 or some similar mechanism, the file transfer method described in File Transfer [17] SHOULD be used.

  1. When some attachment must be sent, references are included in the relative SOAP envelope; fields using attachments for data have the 'href' attribute set to a unique ID designating the file, as shown above for multipart messages.
  2. After having sent the envelope, the sender begins a file transfer negotiation as described in JEP-0096. The 'name' attribute of the <file> element MUST be set to the value of the previous 'href' attribute in order to match attachments with the associated envelopes.
  3. The receiver picks a transfer mode, retrieves all the attachments, and then replies to the SOAP messages if required.

Example 7. SOAP attachment using file transfer


<iq type='set' id='offer1' to='receiver@example.org/resource'>
  <si xmlns='http://jabber.org/protocol/si' 
      id='a0'
      mime-type='img/tiff'
      profile='http://jabber.org/protocol/si/profile/file-transfer'>
    <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
          name='claim061400a.tiff@claiming-it.com'
          size='100228'
          hash='552da749930852c69ae5d2141d3766b1'
          date='1972-02-02T02:56:15Z'/>
    <feature xmlns='http://jabber.org/protocol/feature-neg'>
      <x xmlns='jabber:x:data' type='form'>
        <field var='stream-method' type='list-single'>
          <option><value>http://jabber.org/protocol/bytestreams</value></option>
          <option><value>http://jabber.org/protocol/ibb</value></option>
        </field>
      </x>
    </feature>
  </si>
</iq>
  

6. WSDL Definition with XMPP Binding

WSDL [18] provides a machine-readable, formal description of web services operations, protocol bindings, and end points (i.e., network addresses). This description is aimed at specifying a loose coupling of SOAP envelopes and their transports, in order to maintain their independence and flexibility. Thus the definition of an XMPP SOAP transport through WSDL is straightforward. The following elements are relevant for the XMPP transport:

  1. The 'transport' attribute of the <soap:binding> element MUST be set to "http://jabber.org/protocol/soap".
  2. The 'style' attribute of the <soap:binding> element SHOULD be set to 'rpc' for SOAP messages carried in <iq/> stanzas, and to 'document' for <message/> stanzas.
  3. The 'soapAction' attribute of the <soap:operation> element MAY be used; if so, it SHOULD be transported in an appropriate env:Header element for compatibility with the HTTP transport.
  4. A valid XMPP URI [19] MUST be used for the 'location' attribute in the <soap:address> element.

Example 8. Example of WSDL definition for a SOAP-based translator over XMPP

<definitions 
    name='BabelFishService' 
    targetNamespace='http://www.example.org/services/BabelFishService.wsdl'>
    xmlns='http://schemas.xmlsoap.org/wsdl/'
    xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'>
  ...
  <binding name='BabelFishBinding' type='tns:BabelFishPortType'>
    <soap:binding style='rpc' transport='http://jabber.org/protocol/soap'>
    <operation name='Translate'>
      <soap:operation soapAction='urn:googleBabelFish#BabelFish'/>
      <input>...</input>
      <output>...</output>
    </operation>
  </binding>
  <service name='BabelFishService'>
    <documentation>
      Translates text using Google's Babelfish.
    </documentation>
    <port name='BabelFishPort' binding='tns:BabelFishBinding'>
      <soap:address location='xmpp:babel@jabber.example.org'/>
    </port>
  </service>
</definitions>

Although there is no standard procedure to publish WSDL documents, usually they are made available through HTTP at some URL discoverable with public registries such as UDDI servers. WSDL descriptions for XMPP bindings MAY follow the same publishing process, or MAY be discoverable through Jabber/XMPP specific mechanisms such as Service Discovery [20] or Publish-Subscribe [21].

7. SOAP XMPP Binding

Section 4 of SOAP Version 1.2 Part 1 [22] defines a SOAP Protocol Binding Framework; two instantiations of that framework are the SOAP HTTP Binding (specified in Section 7 of SOAP Version 1.2 Part 2 [23]) and the SOAP Email Binding [24]. [25] As an alternative to the HTTP and Email bindings, this section formally defines the SOAP XMPP Binding in accordance with the SOAP Protocol Binding Framework.

Note: The SOAP XMPP Binding is optional, and SOAP nodes are not required to implement it. A SOAP node that correctly and completely implements the SOAP XMPP Binding as described herein may be said to "conform to the SOAP 1.2 XMPP Binding".

7.1 Binding Name

The SOAP XMPP Binding is identified by the following URI:

7.2 Supported Features

XMPP is a pure XML streaming protocol used to exchange snippets of structured data called "XML stanzas" (see Section 4.1 of RFC 3920) between any two network endpoints.

Because XMPP is a direct messaging protocol, it does not possess the equivalent of web methods such as the HTTP GET, PUT, POST, and DELETE methods. Therefore, it is NOT RECOMMENDED for a SOAP node that supports only the SOAP XMPP Binding to provide the "SOAP Web Method Feature" described in Section 6.4 of SOAP Version 1.2 Part 2. (A SOAP gateway between XMPP and HTTP should support the SOAP Web Method Feature in order to ensure interoperability; however, description of such gateways is outside the scope of this document.)

Because XMPP is a pure XML protocol, it does not use MIME types (RFC 2045 [26]) or XML media types (RFC 3023 [27]), but rather sends XML directly over the wire. Therefore, it is NOT RECOMMENDED for a SOAP node that supports only the SOAP XMPP Binding to provide the "SOAP Action Feature" described in Section 6.5 of SOAP Version 1.2 Part 2. (A SOAP gateway between XMPP and HTTP should support the SOAP Action Feature in order to ensure interoperability; however, description of such gateways is outside the scope of this document.)

7.3 Supported Message Exchange Patterns

XMPP inherently provides request-response semantics via the <iq/> stanza type and <message/> stanza type, where the <iq/> stanza type requires more formality regarding preservation of request-response semantics in the context of synchronous communications, whereas the <message/> stanza provides a looser mapping to request-response semantics as well as the ability to ensure store-and-forward capabilities similar to those provided by email. Because both stanza types support request-response semantics, an implementation of the SOAP XMPP Binding MUST support only the following message exchange pattern (MEP) defined in the core SOAP 1.2 specification:

7.4 Operation of Request-Response Message Exchange Pattern

The request-response message exchange pattern is described in Section 6.2 of SOAP Version 1.1 Part 2. For binding instances conforming to the specification of the SOAP XMPP Binding:

The remainder of this section describes the message exchange pattern (MEP) state machine and its relation to XMPP as described in RFC 3920. For the sake of brevity, relative URIs are used (the base URI being http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/Role), the string "fail:" is used as a conventional prefix for the namespace http://www.example.org/2001/12/soap/mep/FailureReasons/, and the string "reqresp:" is used as a conventional prefix for the namespace http://www.example.org/2001/12/soap/mep/request-response/. In the state tables below, the states are defined as values of the http://www.w3.org/2003/05/soap/bindingFramework/ExchangeContext/State property (see Section 6.2 of SOAP Version 1.2 Part 2) and are of type xs:anyURI.

7.4.1 Behavior of Requesting SOAP Node

The overall flow of the behavior of a Requesting SOAP Node follows the outline state machine description contained in Section 6.2 of SOAP Version 1.2 Part 2. The following subsections describe each state in more detail, where "Requesting SOAP Node" is to be understood as a logical entity made up of the binding and the local SOAP node associated with the XMPP entity that generates a SOAP request.

7.4.1.1 Init

The following table formally describes the "Init" state of the Requesting SOAP Node in the SOAP XMPP Binding:

Table 2: Init: State Description (Requesting)

Feature Value / Description
State Name Init
Description Formulate and send request message
Pre-Conditions Control of the outbound transport message exchange context is transferred from the local SOAP node to the binding
Actions Formulate and send XMPP <iq/> or <message/> request stanza (see table "Init: XMPP Fields (Requesting)") that encpasulates SOAP envelope transferred from local SOAP node to binding
Post-Conditions None
Transitions See table "Init: Transitions (Requesting)"

In the "Init" state, an XMPP stanza (either <iq/> or <message/>) is formulated by the Requesting SOAP Node according to the following table:

Table 3: Init: XMPP Fields (Requesting)

Field Value / Description
XMPP Method For XMPP <iq/> stanzas, the value of the XMPP 'type' attribute MUST be "set"; does not apply to XMPP <message/> stanzas
Originator The XMPP address (JID) carried in the reqresp:ImmediateSender property of the message exchange context is encapsulated as the value of the XMPP 'from' attribute; normally this is set by the XMPP server to which the originator connects
Destination The XMPP address (JID) carried in the reqresp:ImmediateDestination property of the message exchange context is encapsulated as the value of the XMPP 'to' attribute
Correlation Request Message ID As required for XMPP <iq/> stanzas in general and required for XMPP <message/> stanzas sent in the context of the SOAP XMPP Binding, a correlation request message ID is generated by the sender and encapsulated as the value of the XMPP 'id' attribute
XMPP Stanza Contents The XML of the SOAP envelope carried in the reqresp:OutboundMessage property of the transport message exchange context is encapsulated as a direct child element of the XMPP <iq/> or <message/> stanza

The following table summarizes the transitions from the "Init" state of the Requesting SOAP Node:

Table 4: Init: Transitions (Requesting)

Event / Condition Next State Failure Reason
Request Successfully Sent Requesting N/A
Failure to Send Request Fail fail:TransmissionFailure

7.4.1.2 Requesting

The following table formally describes the "Requesting" state of the Requesting SOAP Node in the SOAP XMPP Binding:

Table 5: Requesting: State Description

Feature Value / Description
State Name Requesting
Description Waiting for correlated XMPP response (Request Message completely sent on exit from Init state)
Pre-Conditions Completion of Init state
Actions Wait for a receive XMPP response stanza
Post-Conditions Instantiate or replace the reqresp:ImmediateSender property with an XMPP address (JID) that denotes the sender of the XMPP response stanza
Transitions See table "Requesting: Transitions"

The following table summarizes the transitions from the "Requesting" state of the Requesting SOAP Node:

Table 6: Requesting: Transitions

Event / Condition Next State Failure Reason
Received Correlated XMPP Response Sending+Receiving N/A
Reception Failure (various XMPP errors) Fail fail:ReceptionFailure

For a listing of relevant XMPP error conditions, refer to Sections 9.3.3 and 4.7.3 of RFC 3920.

7.4.1.3 Sending+Receiving

The following table formally describes the "Sending+Receiving" state of the Requesting SOAP Node in the SOAP XMPP Binding:

Table 7: Sending+Receiving: State Description

Feature Value / Description
State Name Sending+Receiving
Description Receive correlated XMPP response including SOAP envelope
Pre-Conditions Completion of Receiving state
Actions Process XMPP <iq/> or <message/> response stanza and included SOAP envelope, instantiating or replacing the reqresp:InboundMessage property with an infoset representation of the SOAP envelope contained in the XMPP response stanza
Post-Conditions Control of the inbound transport message exchange context is transferred from the binding to the local SOAP node
Transitions See table "Sending+Receiving: Transitions"

The following table summarizes the transitions from the "Sending+Receiving" state of the Requesting SOAP Node:

Table 8: Sending+Receiving: Transitions

Event / Condition Next State Failure Reason
Received Well-Formed Response Message Success N/A
Reception Failure (various XMPP errors) Fail fail:ReceptionFailure
Malformed Response Message (invalid SOAP envelope) Fail fail:BadRequestMessage

For a listing of relevant XMPP error conditions, refer to Sections 9.3.3 and 4.7.3 of RFC 3920.

7.4.1.4 Success and Fail

A given instance of a request-response transport message exchange terminates when the state "Success" or "Fail" is reached; control over the transport message exchange context returns to the Requesting SOAP Node.

7.4.2 Behavior of Responding SOAP Node

The overall flow of the behavior of a Responding SOAP Node follows the outline state machine description contained in Section 6.2 of SOAP Version 1.2 Part 2. The following subsections describe each state in more detail, where "Responding SOAP Node" is to be understood as a logical entity made up of the binding and the local SOAP node associated with the XMPP entity that responds to a SOAP request.

7.4.2.1 Init

The following table formally describes the "Init" state of the Responding SOAP Node in the SOAP XMPP Binding:

Table 9: Init: State Description (Responding)

Feature Value / Description
State Name Init
Description Receive request message
Pre-Conditions None
Actions Receive and validate inbound XMPP <iq/> or <message/> request stanza; instantiate or replace the reqresp:ImmediateSender property with an XMPP address (JID) that denotes the sender of the XMPP request; instantiate or replace the reqresp:InboundMessage property with an infoset representation of the included SOAP envelope
Post-Conditions Control of the inbound transport message exchange context is transferred from the binding to the local SOAP node
Transitions See table "Init: Transitions (Responding)"

The following table summarizes the transitions from the "Init" state of the Responding SOAP Node:

Table 10: Init: Transitions (Responding)

Event / Condition Next State Failure Reason
Received Well-Formed Request Message Receiving N/A
Reception Failure (various XMPP errors) Fail fail:ReceptionFailure
Malformed Response Message (invalid SOAP envelope) Fail fail:BadRequestMessage

For a listing of relevant XMPP error conditions, refer to Section 9.3.3 of RFC 3920.

7.4.2.2 Receiving

The following table formally describes the "Receiving" state of the Responding SOAP Node in the SOAP XMPP Binding:

Table 11: Receiving: State Description

Feature Value / Description
State Name Receiving
Description Waiting for local SOAP node to return response message
Pre-Conditions Completion of Init state
Actions None
Post-Conditions Control of the outbound transport message exchange context is transferred from the local SOAP node to the binding
Transitions See table "Receiving: Transitions"

The following table summarizes the transitions from the "Receiving" state of the Responding SOAP Node:

Table 12: Receiving: Transitions

Event / Condition Next State Failure Reason
Response Message B.example.orges Available Receiving+Sending N/A

7.4.2.3 Receiving+Sending

The following table formally describes the "Receiving+Sending" state of the Responding SOAP Node in the SOAP XMPP Binding:

Table 13: Receiving+Sending: State Description

Feature Value / Description
State Name Receiving+Sending
Description Waiting for local SOAP node to return response message
Pre-Conditions Completion of Receiving state
Actions Formulate and send XMPP <iq/> or <message/> response stanza (see table "Receiving+Sending: XMPP Fields")
Post-Conditions None
Transitions See table "Receiving+Sending: Transitions"

In the "Receiving+Sending" state, an XMPP stanza (either <iq/> or <message/>) is formulated by the Responding SOAP Node according to the following table:

Table 14: Receiving+Sending: XMPP Fields

Field Value / Description
XMPP Method For XMPP <iq/> stanzas, the value of the XMPP 'type' attribute MUST be "result"; does not apply to XMPP <message/> stanzas
Originator The XMPP address (JID) carried in the reqresp:ImmediateSender property of the message exchange context is encapsulated as the value of the XMPP 'from' attribute; normally set by the XMPP server to which the originator connects
Destination The XMPP address (JID) carried in the reqresp:ImmediateDestination property of the message exchange context is encapsulated as the value of the XMPP 'to' attribute
Correlation Request Message ID As required for XMPP <iq/> stanzas in general and required for XMPP <message/> stanzas sent in the context of the SOAP XMPP Binding, the correlation request message ID is copied from the ID of the request and encapsulated as the value of the XMPP 'id' attribute
XMPP Stanza Contents The XML of the SOAP envelope carried in the reqresp:OutboundMessage property of the transport message exchange context is encapsulated as a direct child element of the XMPP <iq/> or <message/> stanza

The following table summarizes the transitions from the "Receiving+Sending" state of the Responding SOAP Node:

Table 15: Receiving: Transitions

Event / Condition Next State Failure Reason
Response Message Successfully Sent Success N/A
Failure to Send Response Message Fail fail:TransmissionFailure

7.4.2.4 Success and Fail

A given instance of a request-response transport message exchange terminates when the state "Success" or "Fail" is reached; from the perspective of the Responding SOAP Node, the transport message exchange has completed.

8. W3C Considerations

The main body of text that addresses the requirements of the W3C with regard to SOAP bindings is provided in the preceding section of this document (SOAP XMPP Binding). This section addresses only the topic of organizational interaction between the W3C and the Jabber Software Foundation (JSF) [28] regarding the SOAP XMPP Binding.

8.1 W3C Review

As was done with XHTML-IM [29], the SOAP XMPP Binding defined herein should be reviewed informally by an appropriate expert from the W3C before the Jabber Council [30] advances it to a status of Draft within the JSF's standards process. Before this specification proceeds to a status of Final within the JSF's standards process, it should undergo a formal review through communication with the W3C's XML Protocol Working Group.

8.2 SOAP Versioning

This specification addresses SOAP 1.2 only. This specification may be superseded or supplemented in the future by a Jabber Enhancement Proposal that defines methods for encapsulating content defined by future versions of SOAP as published by the W3C.

8.3 XML Versioning

Per RFC 3920, XMPP supports XML 1.0 only. If future versions of XMPP support XML 1.1, this specification may be modified to address handling of SOAP messages that are encoded in XML 1.1.

9. Security Considerations

SOAP has been supplemented by several support protocols that help ensure message integrity and confidentiality (WS-Security [31]) as well as transaction management for failing message exchanges (WS-Transaction [32]). These protocols are all based on SOAP messages and take into account that the underlying protocols can be unreliable and not trusted, thus there are no arguments against their application with XMPP. Alternatively, implementations MAY use native XMPP security such as XMPP E2E [33].

10. IANA Considerations

No interaction with the Internet Assigned Numbers Authority (IANA) [34] is required as a result of this JEP.

11. Jabber Registrar Considerations

11.1 Protocol Namespaces

The Jabber Registrar [35] shall include 'http://jabber.org/protocol/soap' in its registry of protocol namespaces.

12. XML Schema

Because the SOAP envelope is included as a first-level child element of an <iq/> or <message/> stanza via standard XMPP extension mechanisms, an XML schema is not required for this JEP. An XML schema for the SOAP envelope element is provided in the SOAP 1.2 Specification.

13. Implementation Notes

This section is non-normative and is not part of the SOAP over XMPP specification itself.

Any XMPP entity that supports the SOAP XMPP binding could be a SOAP "intermediary" that hands a SOAP message off to some other deployment for subsequent processing (HTTP, email, a specialized enterprise messaging platform, etc.) rather than functioning as the final destination address for the message. Implementations should be aware that subsequent processing may alter the representation of SOAP messages.

As an example, consider a component that functions as a gateway between XMPP-based and HTTP-based web services. Its purpose is only to demonstrate how HTTP and XMPP can be used together in web services, and how to invoke any web services already accessible through HTTP from XMPP clients.

WS-Routing, whose aim is to dynamically compose SOAP message paths and processing sequences, can be used in order to reference web services outside of an XMPP network from within it. WS-Routing extends SOAP Envelope Headers with the <path/> element, which specifies the following for the message: the sender's URL (<from/>), the final destination's URL (<to/>), a forward (<forward/>) path with an arbitrary number of intermediaries (<via/>), and an optional return path (<reverse/>). Each intermediary MUST process the <path/> header and update it accordingly to the already performed path; moreover it MAY process the Body of the message.

A SOAP message originated by an XMPP entity ('xmpp:orig@A.example.com/soap'), and directed to an end point accessible through HTTP ('http://C.example.net/some/endpoint'), could be built using a <path/> header having:

  1. the <to/> element set to 'http://C.example.net/some/endpoint'
  2. one <via/> element set to an HTTP<->XMPP gateway, such as 'xmpp:soapgw@B.example.org/soap', in the forward path
  3. an appropriate SOAP action in the <action> element of the <path/> header (this may be required by the HTTP end point)
  4. a blank return path

Then the SOAP message can be sent within an <iq/> stanza to the gateway's JID. The gateway processes the SOAP headers, and looking through the headers it discovers that it must act only as intermediary. From the <to/> element it reads the URL of the final end point, extracts the SOAP action, changes the path removing the step already performed, and issues an HTTP request with the modified envelope and appropriate HTTP headers. Once it has received a response, it prepares a new <iq/> stanza of type "result" or "error" and sends its reply to the original requester. The following example shows the possible SOAP headers of the described process.

Example 9. Gateway-generated SOAP headers

<S:Envelope xmlns:S='http://www.w3.org/2003/05/soap-envelope'>
   <S:Header>
      <m:path xmlns:m='http://www.soap.org/path'>
         <m:action>http://im.example.org/chat</m:action>
         <m:to>http://C.example.net/some/endpoint</m:to>
         <m:forward>
            <m:via>xmpp:soapgw@B.example.org/soap</m:via>
         </m:forwawd>
         <m:reverse>
            <m:via/>
         </m:reverse>
         <m:from>xmpp:orig@A.example.com/soap</m:from>
         <m:id>uuid:84b9f5d0-33fb-4a81-b02b-5b760641c1d6</m:id>
      </m:path>
   </S:Header>
   <S:Body>
      ...
   </S:Body>
</S:Envelope>
  

14. Acknowledgements

Some text in the SOAP XMPP Binding section of this document is closely modelled on Section 7 of SOAP Version 1.2 Part 2 and on SOAP Version 1.2 Email Binding.


Notes

1. Simple Object Access Protocol (SOAP) <http://www.w3.org/TR/SOAP/>.

2. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.

3. WS-Routing Specification <http://msdn.microsoft.com/library/en-us/dnglobspec/html/ws-routing.asp>.

4. WS-Referral Specification <http://msdn.microsoft.com/library/en-us/dnglobspec/html/ws-referral.asp>.

5. JEP-0114: Jabber Component Protocol <http://www.jabber.org/jeps/jep-0114.html>.

6. JEP-0079: Advanced Message Processing <http://www.jabber.org/jeps/jep-0079.html>.

7. JEP-0009: Jabber-RPC <http://www.jabber.org/jeps/jep-0009.html>.

8. JEP-0086: Error Condition Mappings <http://www.jabber.org/jeps/jep-0086.html>.

9. RFC 3548: The Base16, Base32, and Base64 Data Encodings <http://www.ietf.org/rfc/rfc3548.txt>.

10. JEP-0066: Out of Band Data <http://www.jabber.org/jeps/jep-0066.html>.

11. Resource Representation SOAP Header Block <http://www.w3.org/TR/soap12-rep>.

12. SOAP 1.2 Attachment Feature <http://www.w3.org/TR/soap12-af/>.

13. SOAP Message Transmission Optimization Mechanism <http://www.w3.org/TR/soap12-mtom>.

14. XML-binary Optimized Packaging <http://www.w3.org/TR/xop10/>.

15. WS-Attachments <http://www.watersprings.org/pub/id/draft-nielsen-dime-soap-01.txt> (work in progress).

16. RFC 3288: Using the Simple Object Access Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP) <http://www.ietf.org/rfc/rfc3288.txt>.

17. JEP-0096: File Transfer <http://www.jabber.org/jeps/jep-0096.html>.

18. WSDL 1.1 Specification <http://www.w3.org/TR/wsdl>.

19. A Uniform Resource Identifier (URI) Scheme for the Extensible Messaging and Presence Protocol (XMPP) <http://www.ietf.org/internet-drafts/draft-saintandre-xmpp-uri-08.txt> (work in progress).

20. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.

21. JEP-0060: Publish-Subscribe <http://www.jabber.org/jeps/jep-0060.html>.

22. SOAP Version 1.2 Part 1: Messaging <http://www.w3.org/TR/soap12-part1>.

23. SOAP Version 1.2 Part 2: Adjuncts <http://www.w3.org/TR/soap12-part2>.

24. SOAP Version 1.2 Email Binding <http://www.w3.org/TR/soap12-email>.

25. Another binding is described in RFC 3288, but it does not formally conform to the SOAP Protocol Binding Framework.

26. RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies <http://www.ietf.org/rfc/rfc2045.txt>.

27. RFC 3023: XML Media Types <http://www.ietf.org/rfc/rfc3023.txt>.

28. The Jabber Software Foundation (JSF) is an independent, non-profit organization that develops open application protocols on top of the IETF's Extensible Messaging and Presence Protocol (XMPP). For further information, see <http://www.jabber.org/jsf/>.

29. JEP-0071: XHTML-IM <http://www.jabber.org/jeps/jep-0071.html>.

30. The Jabber Council is a technical steering committee, authorized by the JSF Board of Directors and elected by JSF members, that approves of new Jabber protocols and oversees the JSF's standards process. For further information, see <http://www.jabber.org/council/>.

31. WS-Security <http://msdn.microsoft.com/ws/2002/04/Security/>.

32. WS-Transaction <http://msdn.microsoft.com/library/en-us/dnglobspec/html/ws-transaction.asp>.

33. RFC 3923: End-to-End Signing and Object Encryption for the Extensible Messaging and Presence Protocol (XMPP) <http://www.ietf.org/rfc/rfc3923.txt>.

34. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

35. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.


Revision History

Version 0.7 (2005-06-30)

Clarified implementation notes and text on attachments. (psa)

Version 0.6 (2005-06-29)

Addressed W3C feedback by (1) adding section on architectural assumptions, (2) adding references to recent W3C attachments work, and (3) discussing XML 1.1 support. (psa)

Version 0.5 (2005-04-01)

Corrected several small errors throughout. (psa)

Version 0.4 (2005-01-06)

Added W3C Considerations and formal description of SOAP XMPP Binding. (psa)

Version 0.3 (2004-05-10)

Changed namespaces to keep in sync with latest SOAP specs. Removed the encodingStyle attribute, since in SOAP 1.2 it is allowed only in child elements of the Body. Removed the <soap> element from the error message example. Fixed the Fault encoding. Explicitly prohibited SOAP elements within the default namespace. (ff)

Version 0.2 (2003-11-11)

Deleted the superfluous <soap> element for envelope encapsulation; Changed error reporting semantics; Added a WSDL Binding example; Added a routing example for HTTP<->XMPP gateways; Added XML Schema; References to Jabber changed in references to XMPP; Other minor changes. (ff)

Version 0.1 (2003-02-17)

Initial version. (ff)


END