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

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

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.

<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>
    

<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>
    

<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>
    

<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>
    

<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".

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.

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

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

Revision History

END