JEP-0072: SOAP Over XMPP

This JEP defines methods for transporting SOAP messages over XMPP.

NOTICE: This JEP is currently within Last Call or under consideration by the Jabber Council for advancement to the next stage in the JSF standards process. For further details, visit <>.

JEP Information

Status: Proposed
Type: Standards Track
Number: 0072
Version: 0.3
Last Updated: 2004-05-10
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, SOAP 1.2
Supersedes: None
Superseded By: None
Short Name: None

Author Information

Fabio Forno


Legal Notice

This Jabber Enhancement Proposal is copyright 1999 - 2004 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <>. 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 <>).

Discussion Venue

The preferred venue for discussion of this document is the Standards-JIG discussion list: <>.

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 protocols defined in this JEP have been developed outside the Internet Standards Process and are to be understood as extensions 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. Transport of SOAP Envelopes
2.1. Synchronous Transport within IQ Stanzas
2.2. Asynchronous Transport within Message Stanzas
2.3. Error Reporting
3. Encoding
4. Attachments
5. WSDL Definition with XMPP Binding
6. HTTP <-> XMPP Gateways
7. Security Considerations
8. IANA Considerations
9. Jabber Registrar Considerations
9.1. Protocol Namespaces
10. XML Schema
Revision History

1. Introduction

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.

2. 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 when store and forward may be necessary; examples of applications can be RSS feeds, news and headlines, and event notifications.

These approaches are defined in the following sections.

2.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 [5]. 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 '' namespace.

Example 1. A SOAP request inserted into an IQ stanza

<iq from=''
  <env:Envelope xmlns:env=''>

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

<iq from='' 
  <env:Envelope xmlns:env=''>

2.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 to the relative requests.

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

<message to='' id='soap2'>
  <env:Envelope xmlns:env=''>
          <description>News for nerds, stuff that matters</description>
          <title>Jabber/XMPP now supports SOAP</title>

2.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 specifications [6] map 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 XMPP Core and Error Condition Mappings [7]).

Table 1: Mapping of SOAP Error codes

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

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

<iq type='error' to='' id='soap1'>
          <env:Text xml:lang='en-US'>Processing error</env:Text>
          <e:myFaultDetails xmlns:e=''>
            <e:message>Name does not match card number</e:message>
  <error code='500' type='cancel'>
    <internal-server-error xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>

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='' id='soap1'>
  <error code='503' type='cancel'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>

3. 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 XMPP Core. 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 [8]), 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.

4. Attachments

Binary data could grow significantly in size, and messages carrying it could be penalized by servers with karma settings tuned for normal textual 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.

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

The first method, using the file link in the envelope, is a general one, and can be used by XMPP clients if they are able to retrieve the file (e.g, using Out-of-Band Data [12]). However, the other methods cannot be used directly with XMPP, since MIME messages do not fit in XML streams and WS-Attachments and BEEP are just other transport protocols.

Example 6. SOAP attachment using MIME

MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml;
Content-Description: This is the optional message description.

Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <>

<?xml version='1.0' ?>
<theSignedForm href=''/>

Content-Type: image/tiff
Content-Transfer-Encoding: binary
Content-ID: <>

For the transport of binary data, the file transfer method described in File Transfer [13] 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=''>
  <si xmlns='' 
    <file xmlns=''
    <feature xmlns=''>
      <x xmlns='jabber:x:data' type='form'>
        <field var='stream-method' type='list-single'>

5. WSDL Definition with XMPP Binding

WSDL [14] 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 "".
  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 [15] 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

  <binding name='BabelFishBinding' type='tns:BabelFishPortType'>
    <soap:binding style='rpc' transport=''>
    <operation name='Translate'>
      <soap:operation soapAction='urn:googleBabelFish#BabelFish'/>
  <service name='BabelFishService'>
      Translates text using Google's Babelfish.
    <port name='BabelFishPort' binding='tns:BabelFishBinding'>
      <soap:address location=''/>

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 [16] or Publish-Subscribe [17].

6. HTTP <-> XMPP Gateways

This section is non-normative.

This section provides an example of a gateway between XMPP-based and HTTP-based web services and it is not meant to be part of the SOAP over XMPP specifications. 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 (''), and directed to an end point accessible through HTTP (''), could be built using a <path/> header having:

  1. the <to/> element set to ''
  2. one <via/> element set to an HTTP<->XMPP gateway, such as '', 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 the result 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=''>
      <m:path xmlns:m=''>

7. Security Considerations

SOAP has several support protocols that help ensure message integrity and confidentiality (WS-Security [18]) as well as transaction management for failing message exchanges (WS-Transaction [19]). 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 [20].

8. IANA Considerations

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

9. Jabber Registrar Considerations

9.1 Protocol Namespaces

The Jabber Registrar [22] shall include '' in its registry of protocol namespaces.

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


1. SOAP 1.2 Specification <>.

2. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <>.

3. WS-Routing Specification <>.

4. WS-Referral Specification <>.

5. JEP-0009: Transporting XML-RPC over Jabber <>.

6. SOAP Version 1.2 Part 2: Adjuncts <>.

7. JEP-0086: Error Condition Mappings <>.

8. RFC 3548: The Base16, Base32, and Base64 Data Encodings <>.

9. SOAP Messages with Attachments <>.

10. WS-Attachments <> (work in progress).

11. RFC 3080: The Blocks Extensible Exchange Protocol Core (BEEP) <>.

12. JEP-0066: Out of Band Data <>.

13. JEP-0096: File Transfer <>.

14. WSDL 1.1 Specification <>.

15. A Uniform Resource Identifier (URI) Scheme for the Extensible Messaging and Presence Protocol (XMPP) <> (work in progress).

16. JEP-0030: Service Discovery <>.

17. JEP-0060: Publish-Subscribe <>.

18. WS-Security <>.

19. WS-Transaction <>.

20. RFC 3923: End-to-End Signing and Object Encryption for the Extensible Messaging and Presence Protocol (XMPP) <>.

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

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

Revision History

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)