<abstract>This specification defines methods for transporting SOAP messages over XMPP. Although the protocol supports only the request-response message exchange pattern, the protocol is formally defined as a SOAP Protocol Binding in accordance with version 1.2 of the W3C SOAP specification. In addition, a WSDL definition is defined for the purpose of advertising the availability of this protocol binding.</abstract>
<remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
</revision>
<revision>
<version>0.14</version>
<date>2005-11-29</date>
<initials>psa</initials>
<remark>In accordance with further Council feedback, cleaned up the section on file transfer by clarifying which methods are recommended, removing section on MIME, and correcting use of SI-Pub.</remark>
<remark>In accordance with Council feedback: divided Sending Attachments text into multiple subsections and added XMPP examples to each subsection; specified use of XEP-0137 to publish SI requests related to file transfer; specified use of application-specific stanza errors; fixed typographical error in WSDL example.</remark>
<remark>In accordance with Council feedback, re-organized descriptive text around use cases.</remark>
</revision>
<revision>
<version>0.11</version>
<date>2005-09-07</date>
<initials>psa</initials>
<remark>Modified service discovery category and type; made several other small text changes based on W3C feedback.</remark>
</revision>
<revision>
<version>0.10</version>
<date>2005-09-01</date>
<initials>psa</initials>
<remark>Added information about service discovery.</remark>
</revision>
<revision>
<version>0.9</version>
<date>2005-08-17</date>
<initials>psa</initials>
<remark>Added implementation note about XMPP routers based on W3C feedback.</remark>
</revision>
<revision>
<version>0.8</version>
<date>2005-07-21</date>
<initials>psa</initials>
<remark>Cleaned up WSDL definition.</remark>
</revision>
<revision>
<version>0.7</version>
<date>2005-06-30</date>
<initials>psa/ff</initials>
<remark>Clarified implementation notes and text on attachments.</remark>
</revision>
<revision>
<version>0.6</version>
<date>2005-06-29</date>
<initials>psa</initials>
<remark>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.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2005-04-01</date>
<initials>psa</initials>
<remark>Corrected several small errors throughout.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2005-01-06</date>
<initials>psa</initials>
<remark>Added W3C Considerations and formal description of SOAP XMPP Binding.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2004-05-10</date>
<initials>ff</initials>
<remark>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.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-11-11</date>
<initials>ff</initials>
<remark>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.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2003-02-17</date>
<initials>ff</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1topic='Introduction'anchor='intro'>
<p>&w3soap; 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.</p>
<p>The primary limitation of HTTP consists in the fact that HTTP-based message exchanges allow only synchronous request-response semantics. 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.</p>
<p>Thus XMPP (see &rfc3920;) 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 <cite>WS-Routing</cite> and <cite>WS-Referral</cite>, in order to deliver messages to entities that cannot be identified by static public IP addresses. Therefore, this document defines a binding of SOAP to XMPP as an alternative to the existing HTTP and SMTP bindings.</p>
<p>(Note: The main body of this document 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 <linkurl='#binding'>SOAP XMPP Binding</link>.)</p>
<p>The usual architecture of XMPP is described in Section 2 of <cite>RFC 3920</cite>. 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.</p>
<p>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 &xep0114;) or even as special-purpose XMPP servers.</p>
<p>The SOAP specification defines the concepts of "SOAP intermediary" and "ultimate SOAP receiver" (see Section 1.5.3 of <cite>SOAP Version 1.2 Part 1</cite>). In general, this specification assumes that XMPP entities that support the SOAP XMPP Binding will be ultimate SOAP receivers, since SOAP intermediaries tend to be 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 issues are addressed natively in XMPP (e.g., channel encryption is defined in <cite>RFC 3920</cite>), in XMPP extensions (e.g., message tracing is defined in &xep0079;), or in deployment decisions such as business level agreements between XMPP domains. One final justification for SOAP intermediaries is to act as gateways between different transport mechanisms (e.g., between HTTP and SMTP), and XMPP entities may well be SOAP intermediaries for that reason. For further details about gateways between XMPP and other SOAP bindings, refer to the <linkurl='#impl'>Implementation Notes</link> section of this document.</p>
<p>In order to determine whether a potential responding entity supports the SOAP XMPP Binding, a requesting entity SHOULD send a &xep0030; information request to the potential responding entity:</p>
<p>If the responding entity supports the SOAP XMPP Binding and the requesting entity is not blocked from communicating with the responding entity, the responding entity MUST include a feature of "http://jabber.org/protocol/soap" in its reply and SHOULD specify a service discovery identity of "automation/soap".</p>
<p>When a requesting entity wants to interact with a responding entity via the SOAP XMPP Binding, it faces a fundamental choice: to use &IQ; stanzas or to use &MESSAGE; stanzas. The following guidelines may prove useful:</p>
<ol>
<li>&IQ; stanzas SHOULD be used when more formal request-response semantics are needed or when an immediate answer is required.</li>
<li>&MESSAGE; stanzas SHOULD be used when less formal request-response semantics are acceptable or when store-and-forward ("offline message") delivery is needed (e.g., because the intended recipient may be temporarily unavailable).</li>
</ol>
<p>Examples of both approaches are provided below, encapsulating the SOAP message examples (a travel reservation flow) to be found in &w3soap0;.</p>
<section3topic="Exchanging SOAP Messages Using XMPP IQ Stanzas"anchor='exchange-iq'>
<p>The transport with &IQ; stanzas is performed in a way similar to that described for XML-RPC in &xep0009;. 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 (see <linkurl='#errors'>Error Handling</link> for details).</p>
<p>Each &IQ; stanza of type "set" MUST contain a SOAP envelope as the first-level child element, since it already represents a properly namespaced XML subtree qualified by the 'http://www.w3.org/2003/05/soap-envelope' namespace.</p>
<section3topic="Exchanging SOAP Messages Using XMPP Message Stanzas"anchor='exchange-message'>
<p>The process for exchanging SOAP messages using the XMPP &MESSAGE; stanza type is effectively no different from the use with &IQ; stanzas, except that message stanzas may be sent to bare JIDs (user@host) rather than full JIDs (user@host/resource), message stanzas may be stored for later delivery, etc. The following business rules apply:</p>
<ol>
<li>The message stanza containing a request MUST carry one SOAP envelope as a first-level child element.</li>
<li>The 'id' attribute MUST be used to track the XMPP messages and eventually associate errors or answers with the related requests (this is for tracking at the XMPP level, not the SOAP level).</li>
<p>SOAP messages may contain associated (usually binary) data, and XMPP stanzas that encapsulate such SOAP messages could invoke 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 rather than XMPP nodes; however, server-to-server communications risk becoming a serious bottleneck, especially in terms of latency and responsiveness when too many large messages are sent. Therefore, it is desirable to support the sending of attachments or files in order to exchange large amounts of binary data associated with SOAP requests and responses. As summarized in the following table, here are four possible methods:</p>
<tablecaption='Possible Methods for Sending Associated Data'>
<td>Represent the binary data as a file, publish it to an accessible file server (e.g., HTTP or FTP URL), and insert a link to the file directly into the XMPP message stanza (via &xep0066;) or into the SOAP envelope (via &w3soaprep;).</td>
<td>Send SOAP XML plus binary data over alternate transports such as <cite>WS-Attachments</cite><note>WS-Attachments <<linkurl="http://www.watersprings.org/pub/id/draft-nielsen-dime-soap-01.txt">http://www.watersprings.org/pub/id/draft-nielsen-dime-soap-01.txt</link>> (work in progress).</note> or SOAP-over-BEEP as defined in &rfc4227;.</td>
<p>The recommended method for sending associated data is to use the file transfer protocol described in <cite>XEP-0096</cite>. Because this is the common and standardized method for XMPP entities to transfer large or binary files outside the XMPP band, it SHOULD be used.</p>
<p>In particular, the entity that has the file SHOULD advertise the availability of the associated stream using <cite>XEP-0137</cite> by including the SI-pub data extension along with the XMPP &MESSAGE; stanza with which the data is associated: <note>In accordance with <cite>RFC 3920</cite>, an &IQ; stanza MUST NOT include multiple payload child elements; therefore, a &MESSAGE; stanza must be used when sending associated data.</note></p>
<p>The entity that is to receive the file SHOULD initiate the file transfer process sending an IQ-get to the sender, using the <start xmlns='http://jabber.org/protocol/sipub'/> element. This element contains the 'id' attribute to specify which published stream to retrieve:</p>
<examplecaption='Receiver requests start of stream'><![CDATA[
<iqtype='get'
id='sipub-request-0'
from='responder@example.com/soap-server'
to='requester@example.com/soap-client'>
<startxmlns='http://jabber.org/protocol/sipub'
id='publish-2345'/>
</iq>
]]></example>
<p>If the sender accepts the request, it responds with an IQ-result containing a <starting/> element. This element indicates the stream initiation identifier to be used:</p>
<examplecaption='Sender accepts request to start stream'><![CDATA[
<iqtype='result'
id='sipub-request-0'
from='requester@example.com/soap-client'
to='responder@example.com/soap-server'>
<startingxmlns='http://jabber.org/protocol/sipub'
sid='session-87651234'/>
</iq>
]]></example>
<p>Then the sender begins the stream initiation negotiation:</p>
<p>For details regarding file transfer and advertising of file transfer stream initiation requests, refer to <cite>XEP-0096</cite> and <cite>XEP-0137</cite>.</p>
<p>If the file transfer method is not possible (e.g., because file transfer is not implemented or transfer attempts fails), the entity that is sending the associated data MAY as a fallback publish the associated data as a file (e.g., at an HTTP or FTP URL) and include a link to the file as out-of-band content by including the out-of-band data extension along with the XMPP &MESSAGE; stanza with which the data is associated: <note>As above, in accordance with <cite>RFC 3920</cite>, an &IQ; stanza MUST NOT include multiple payload child elements; therefore, a &MESSAGE; stanza must be used when sending associated data.</note></p>
<examplecaption="Sender sends message with out-of-band data"><