xep-0009.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Jabber-RPC</title>
  <abstract>This specification defines an XMPP protocol extension for transporting XML-RPC encoded requests and responses between two XMPP entities. The protocol supports all syntax and semantics of XML-RPC except that it uses XMPP instead of HTTP as the underlying transport.</abstract>
  &LEGALNOTICE;
  <number>0009</number>
  <status>Final</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XML-RPC</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>jabber-rpc</shortname>
  <schemaloc>
    <url>http://xmpp.org/schemas/jabber-rpc.xsd</url>
  </schemaloc>
  <author>
    <firstname>DJ</firstname>
    <surname>Adams</surname>
    <email>dj.adams@pobox.com</email>
    <jid>dj@gnu.mine.nu</jid>
  </author>
  <revision>
    <version>2.2</version>
    <date>2011-11-10</date>
    <initials>psa</initials>
    <remark>Corrected element name in XML schema from "Base64" to "base64".</remark>
  </revision>
  <revision>
    <version>2.1</version>
    <date>2006-02-09</date>
    <initials>psa</initials>
    <remark>Defined error handling, service discovery, security considerations, and XMPP Registrar considerations.</remark>
  </revision>
  <revision>
    <version>2.0</version>
    <date>2002-12-09</date>
    <initials>psa</initials>
    <remark>Per a vote of the Jabber Council, changed status to Final.</remark>
  </revision>
  <revision>
    <version>1.0</version>
    <date>2001-09-27</date>
    <initials>psa</initials>
    <remark>Changed status to Draft</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2001-09-14</date>
    <initials>dja</initials>
    <remark>Initial version</remark>
  </revision>
</header>
<section1 topic='Introduction'>
  <p>&xmlrpc; is a method of encoding RPC requests and responses in XML. The original specification defines HTTP (see &rfc2068;) as the only valid transport for XML-RPC payloads.</p>
  <p>Various initiatives exist already to transport XML-RPC payloads over Jabber. These initiatives were independent of each other and used slightly differing methods (e.g. carrying the payload in a &lt;message/&gt; element as opposed to an &IQ; stanza), resulting in potential interoperability problems.</p>
  <p>A working session during JabberCon 2001 resulted in formalisation of a single method. This document describes that method, which is labelled as Jabber-RPC to differentiate it from XML-RPC itself.</p>
</section1>
<section1 topic='Jabber-RPC'>
  <p>The &IQ; stanza is used to transport XML-RPC payloads. XML-RPC requests are transported using an &IQ; stanza of type "set", and XML-RPC responses are transported using an &IQ; stanza of type "result". An &IQ; stanza MUST NOT contain more than one request or response.</p>
  <p>The &IQ; stanza contains a single &QUERY; sub-element in the jabber:iq:rpc namespace. The direct child of the &QUERY; element will be either a single &lt;methodCall/&gt; element (in the case of a request) or a single &lt;methodResponse/&gt; element (in the case of a response). This child element will contain the XML-RPC payload. Note that the XML declaration that normally appears at the head of an XML-RPC request or response when transported as the payload of an HTTP POST request MUST BE omitted when it is transported via a Jabber &IQ; stanza.</p>
  <p>The encoding of the Jabber XML stream is UTF-8. It is assumed that the encoding of the XML-RPC payload is also UTF-8.</p>
  <p>Application-level errors will be indicated within the XML-RPC payload (as is the case with the traditional HTTP-based XML-RPC mechanism). Transport level errors will be indicated in the normal way for &IQ; stanzas -- namely, by an &IQ; stanza of type "error" and the addition of an &lt;error/&gt; tag as a direct child of the &IQ; stanza. There are no specific XML-RPC-related, transport-level errors.</p>
  <p class='box'>In September of 2011, it was discovered that the XML schema quoted in <link url='#schema'>Section 8</link> contains an error, showing a child element of &lt;Base64/&gt; (uppercase "B") instead of &lt;base64/&gt; (lowercase "b"). A review of the XML-RPC specification and of numerous XML-RPC and Jabber-RPC implementations showed that the element name is properly "base64" and that the quoted schema was in error by having an element name of "Base64". Therefore this specification and its associated schema were modified to use the correct element name: "base64". It is possible that some existing Jabber-RPC implementations might send a child element of &lt;Base64/&gt;.</p>
</section1>
<section1 topic='Examples'>
  <example caption='A typical request'><![CDATA[
<iq type='set'
    from='requester@company-b.com/jrpc-client'
    to='responder@company-a.com/jrpc-server'
    id='rpc1'>
  <query xmlns='jabber:iq:rpc'>
    <methodCall>
      <methodName>examples.getStateName</methodName>
      <params>
        <param>
          <value><i4>6</i4></value>
        </param>
      </params>
    </methodCall>
  </query>
</iq>
]]></example>
  <example caption='A typical response'><![CDATA[
<iq type='result'
    from='responder@company-a.com/jrpc-server'
    to='requester@company-b.com/jrpc-client'
    id='rpc1'>
  <query xmlns='jabber:iq:rpc'>
    <methodResponse>
      <params>
        <param>
          <value><string>Colorado</string></value>
        </param>
      </params>
    </methodResponse>
  </query>
</iq>
]]></example>
  <p>If the requesting entity does not have sufficient permissions to perform remote procedure calls, the responding entity MUST return a &forbidden; error:</p>
  <example caption='Requesting entity is forbidden to perform remote procedure calls'><![CDATA[
<iq type='error'
    from='responder@company-a.com/jrpc-server'
    to='requester@company-b.com/jrpc-client'
    id='rpc1'>
  <query xmlns='jabber:iq:rpc'>
    <methodCall>
      <methodName>examples.getStateName</methodName>
      <params>
        <param>
          <value><i4>6</i4></value>
        </param>
      </params>
    </methodCall>
  </query>
  <error code='403' type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
</section1>
<section1 topic='Service Discovery' anchor='disco'>
  <p>If an entity supports the Jabber-RPC protocol, it SHOULD advertise that fact in response to &xep0030; information ("diso#info") requests by returning an identity of "automation/rpc" and a feature of "jabber:iq:rpc":</p>
  <example caption='A disco#info query'><![CDATA[
<iq type='get'
    from='requester@company-b.com/jrpc-client'
    to='responder@company-a.com/jrpc-server'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
  <example caption='A disco#info response'><![CDATA[
<iq type='result'
    to='requester@company-b.com/jrpc-client'
    from='responder@company-a.com/jrpc-server'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity category='automation' type='rpc'/>
    <feature var='jabber:iq:rpc'/>
  </query>
</iq>
]]></example>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>An entity that supports Jabber-RPC SHOULD establish a "whitelist" of entities that are allowed to perform remote procedure calls and MUST return a &forbidden; error if entities with insufficient permissions attempt such calls.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic="XMPP Registrar Considerations" anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>The &REGISTRAR; includes 'jabber:iq:rpc' in its registry of protocol namespaces.</p>
  </section2>
  <section2 topic='Service Discovery Identity' anchor='registrar-disco'>
    <p>The XMPP Registrar includes a Service Discovery type of "rpc" within the "automation" category in its registry of service discovery identities.</p>
  </section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='jabber:iq:rpc'
    xmlns='jabber:iq:rpc'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0009: http://www.xmpp.org/extensions/xep-0009.html

      There is no official XML schema for XML-RPC. The main body
      of this schema has been borrowed from an unofficial schema
      representation contained in the book "Processing XML With
      Java" by Elliotte Rusty Harold, as located at:

      http://www.ibiblio.org/xml/books/xmljava/chapters/ch02s05.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='query'>
    <xs:complexType>
      <xs:choice minOccurs='0' maxOccurs='1'>
        <xs:element ref='methodCall'/>
        <xs:element ref='methodResponse'/>
      </xs:choice>
    </xs:complexType>
  </xs:element>

  <xs:element name="methodCall">
    <xs:complexType>
      <xs:all>
        <xs:element name="methodName">
          <xs:simpleType>
            <xs:restriction base="ASCIIString">
              <xs:pattern value="([A-Za-z0-9]|/|\.|:|_)*" />
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element name="params" minOccurs="0" maxOccurs="1">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="param"  type="ParamType"
                           minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
          </xs:complexType>
         </xs:element>
      </xs:all>
    </xs:complexType>
  </xs:element>

  <xs:element name="methodResponse">
    <xs:complexType>
      <xs:choice>
        <xs:element name="params">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="param" type="ParamType"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="fault">
          <!-- What can appear inside a fault is very restricted -->
          <xs:complexType>
            <xs:sequence>
              <xs:element name="value">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element name="struct">
                      <xs:complexType>
                        <xs:sequence>
                          <xs:element name="member"
                                       type="MemberType">
                          </xs:element>
                          <xs:element name="member"
                                       type="MemberType">
                          </xs:element>
                        </xs:sequence>
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
         </xs:element>
      </xs:choice>
    </xs:complexType>
  </xs:element>

  <xs:complexType name="ParamType">
    <xs:sequence>
      <xs:element name="value" type="ValueType"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="ValueType" mixed="true">
    <xs:choice>
      <xs:element name="i4"            type="xs:int"/>
      <xs:element name="int"           type="xs:int"/>
      <xs:element name="string"        type="ASCIIString"/>
      <xs:element name="double"        type="xs:decimal"/>
      <xs:element name="base64"        type="xs:base64Binary">
        <xs:annotation>
          <xs:documentation>
            Corrected from "Base64" to "base64" in version 2.2 of XEP-0009.
          </xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="boolean"       type="NumericBoolean"/>
      <xs:element name="dateTime.iso8601" type="xs:dateTime"/>
      <xs:element name="array"         type="ArrayType"/>
      <xs:element name="struct"        type="StructType"/>
    </xs:choice>
  </xs:complexType>

  <xs:complexType name="StructType">
    <xs:sequence>
      <xs:element name="member" type="MemberType"
                   maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="MemberType">
    <xs:sequence>
      <xs:element name="name"  type="xs:string" />
      <xs:element name="value" type="ValueType"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="ArrayType">
    <xs:sequence>
      <xs:element name="data">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="value"  type="ValueType"
                         minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:simpleType name="ASCIIString">
    <xs:restriction base="xs:string">
      <xs:pattern value="([ -~]|\n|\r|\t)*" />
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="NumericBoolean">
    <xs:restriction base="xs:boolean">
      <xs:pattern value="0|1" />
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
]]></code>
</section1>
</xep>