This JEP defines a method for transporting XML-RPC encoded requests and responses over Jabber/XMPP.
NOTICE: The protocol defined herein is a Final Standard of the Jabber Software Foundation and may be considered a stable technology for implementation and deployment.
Status: Final
Type: Standards Track
Number: 0009
Version: 2.0
Last Updated: 2002-12-09
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, XML-RPC
Supersedes: None
Superseded By: None
Short Name: jabber-rpc
Schema: <http://jabber.org/protocol/jabber-rpc/jabber-rpc.xsd>
Wiki Page: <http://wiki.jabber.org/index.php/Jabber-RPC (JEP-0009)>
Email: dj.adams@pobox.com
JID: dj@gnu.mine.nu
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 Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
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.
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.
XML-RPC [1] is a method of encoding RPC requests and responses in XML. The original specification defines HTTP (see RFC 2068 [2]) as the only valid transport for XML-RPC payloads.
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 <message/> element as opposed to an <iq/> element), resulting in potential interoperability problems.
A working session during JabberCon 2001 resulted in a formalisation of a single method. This JEP describes that method, which is labelled as Jabber-RPC to differentiate it from XML-RPC itself.
The <iq/> element is used to transport XML-RPC payloads. XML-RPC requests are transported using an <iq/> packet of type "set", and XML-RPC responses are transported using an <iq/> packet of type "result". An <iq/> element MUST NOT contain more than one request or response.
The <iq/> element contains a single <query/> sub-element in the jabber:iq:rpc namespace. The direct child of the <query/> element will be either a single <methodCall/> element (in the case of a request) or a single <methodResponse/> 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/> element.
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.
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/> elements -- namely, by an <iq/> element of type "error" and the addition of an <error/> tag as a direct child of the <iq/> element. There are no specific XML-RPC-related, transport-level errors.
Example 1. A typical request
<iq type='set' to='responder@company-a.com/jrpc-server' id='1'>
<query xmlns='jabber:iq:rpc'>
<methodCall>
<methodName>examples.getStateName</methodName>
<params>
<param>
<value><i4>6</i4></value>
</param>
</params>
</methodCall>
</query>
</iq>
Example 2. A typical response
<iq type='result' to='requester@company-b.com/jrpc-client'
from='responder@company-a.com/jrpc-server' id='1'>
<query xmlns='jabber:iq:rpc'>
<methodResponse>
<params>
<param>
<value><string>Colorado</string></value>
</param>
</params>
</methodResponse>
</query>
</iq>
<?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
JEP-0009: http://www.jabber.org/jeps/jep-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: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>
1. XML-RPC <http://www.xmlrpc.com/spec>.
2. RFC 2068: Hypertext Transport Protocol -- HTTP/1.1 <http://www.ietf.org/rfc/rfc2068.txt>.
END