This JEP defines a protocol for exchanging roster items, including the ability to suggest whether the item is to be added, deleted, or modified.
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 <http://www.jabber.org/council/queue.shtml>.
Status: Proposed
Type: Standards Track
Number: 0144
Version: 0.5
Last Updated: 2005-07-26
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, XMPP IM
Supersedes: JEP-0093
Superseded By: None
Short Name: rosterx
Email: stpeter@jabber.org
JID: stpeter@jabber.org
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/>).
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.
The Jabber protocols have long included a method for sending roster items from one entity to another, making use of the 'jabber:x:roster' namespace. Because this protocol extension was not required by RFC 2779 [1], it was removed from XMPP IM [2] and documented for historical purposes in Roster Item Exchange [3]. However, since that time discussions in the Standards JIG [4] have revealed that it would be helpful to use roster item exchange in the problem spaces of "shared groups" (e.g., predefined roster groups used within an organization) and roster synchronization (e.g., keeping a Jabber roster in sync with a contact list on a legacy IM service). These problem spaces require a slightly more sophisticated kind of roster item exchange than was documented in JEP-0093, specifically the ability to indicate whether a roster item is to be added, deleted, or modified. Therefore this JEP redefines roster item exchange to provide this functionality in a way that is backwards-compatible with existing implementations, albeit using a modern namespace URI of 'http://jabber.org/protocol/rosterx' rather than the old 'jabber:x:roster' namespace name. Further JEPs will specify how to solve the problems of shared groups and roster synchronization using the protocol defined herein.
JEP-0093 did not define the requirements for roster item exchange. This section remedies that oversight.
Roster item exchange meets the following requirements:
This JEP deliberately speaks of rosters and roster items, not presence subscriptions. Although rosters and subscriptions are closely connected (as explained in RFC 3921), they are not identical. The protocol defined herein enables an entity to suggest that another entity might want to add, delete, or modify roster items only, and does not dictate the suggested presence subscription state associated with those roster items. This is intentional.
In order to programatically suggest that the receiving entity should add one or more items to its roster, the sending entity MUST send a <message/> or <iq/> stanza containing an <x/> element qualified by the 'http://jabber.org/protocol/rosterx' namespace (see Recommended Stanza Type regarding when to use <message/> and when to use <iq/>); the <x/> element in turn MUST contain one or more <item/> child elements, each of which SHOULD possess an 'action' attribute whose value is "add" [5], MUST possess a 'jid' attribute that specifies the JabberID of the item to be added, MAY possess a 'name' attribute that specifies a natural-language name or nickname for the item, and MAY contain one or more <group/> elements specifying roster groups into which to place the item. If a <message/> stanza was sent, it SHOULD NOT contain any other child elements. Here is an example:
Example 1. Suggesting Addition
<message from='horatio@denmark.lit' to='hamlet@denmark.lit'>
<x xmlns='http://jabber.org/protocol/rosterx'>
<item action='add'
jid='rosencrantz@denmark.lit'
name='Rosencrantz'>
<group>Visitors</group>
</item>
<item action='add'
jid='guildenstern@denmark.lit'
name='Guildenstern'>
<group>Visitors</group>
</item>
</x>
</message>
In determining how to handle any given roster item whose 'action' attribute has a value of "add" (either explicitly or as the default value), the receiving application SHOULD proceed as follows:
If the roster item addition stanza will result in adding the item to the roster, the receiving application MUST (either with approval by a human user or automatically subject to configuration) send a roster set to the user's server containing the new item as described in RFC 3921. After completing the roster set, the receiving application SHOULD also send a <presence/> stanza of type "subscribe" to the JID of the new item.
For a description of the recommended application behavior when a roster item addition stanza actually results in editing of an existing roster item, refer to the Suggesting Roster Item Modification section of this document.
In order to programatically suggest that the receiving entity should delete one or more items from its roster, the sending entity MUST send a <message/> or <iq/> stanza containing an <x/> element qualified by the 'http://jabber.org/protocol/rosterx' namespace; the <x/> element in turn MUST contain one or more <item/> child elements, each of which MUST possess an 'action' attribute whose value is "delete", MUST possess a 'jid' attribute that specifies the JabberID of the item to be added, MAY possess a 'name' attribute that specifies a natural-language name or nickname for the item, and MAY contain one or more <group/> elements specifying roster groups for the item. If a <message/> stanza was sent, it SHOULD NOT contain any other child elements. Here is an example:
Example 2. Suggesting Deletion
<message from='horatio@denmark.lit' to='hamlet@denmark.lit'>
<x xmlns='http://jabber.org/protocol/rosterx'>
<item action='delete'
jid='rosencrantz@denmark'
name='Rosencrantz'>
<group>Visitors</group>
</item>
<item action='delete'
jid='guildenstern@denmark'
name='Guildenstern'>
<group>Visitors</group>
</item>
</x>
</message>
In determining how to handle any given roster item whose 'action' attribute has a value of "delete", the receiving application SHOULD proceed as follows:
If the item is to be deleted, the receiving application SHOULD remove the item from the roster by sending a roster set to the user's server with the 'subscription' attribute set to a value of "remove" as described in RFC 3921, since this results in generation of the appropriate <presence/> stanzas by the user's server.
In order to programatically suggest that the receiving entity should modify one or more items from its roster, the sending entity MUST send a <message/> or <iq/> stanza containing an <x/> element qualified by the 'http://jabber.org/protocol/rosterx' namespace; the <x/> element in turn MUST contain one or more <item/> child elements, each of which MUST possess an 'action' attribute whose value is "modify", MUST possess a 'jid' attribute that specifies the JabberID of the item to be added, MAY possess a 'name' attribute that specifies a natural-language name or nickname for the item, and MAY contain one or more <group/> elements specifying roster groups into which to place the item. If a <message/> stanza was sent, it SHOULD NOT contain any other child elements. Here is an example:
Example 3. Suggesting Modification
<message from='horatio@denmark.lit' to='hamlet@denmark.lit'>
<x xmlns='http://jabber.org/protocol/rosterx'>
<item action='modify'
jid='rosencrantz@denmark.lit'
name='Rosencrantz'>
<group>Retinue</group>
</item>
<item action='modify'
jid='guildenstern@denmark.lit'
name='Guildenstern'>
<group>Retinue</group>
</item>
</x>
</message>
In determining how to handle any given roster item whose 'action' attribute has a value of "modify", the receiving application SHOULD proceed as follows:
If a roster item addition, deletion, or modification stanza will result in editing of an existing item in the roster, the receiving application MUST (either with approval by a human user or automatically subject to configuration) send a roster set to the user's server with no changes to the 'subscription' attribute but rather with appropriate changes to the value of 'name' attribute or the <group/> child element or elements, as described in RFC 3921.
In order to determine whether a receiving entity supports the protocol defined herein, the sending entity SHOULD use Service Discovery [6] but MAY depend on the "profile" of Service Discovery defined in Entity Capabilities [7]. If an entity supports roster item exchange, it MUST (subject to appropriate security considerations as described under Advertising Support) include <feature var='http://jabber.org/protocol/rosterx'/> in its responses to disco#info queries. Thus a sending entity can discover if a receiving entity supports the protocol defined herein by sending an IQ request of the following form:
Example 4. Sending Entity Queries for Support
<iq from='horatio@denmark.lit/castle'
to='hamlet@denmark.lit/throne'
type='get'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
The receiving entity then indicates its support:
Example 5. Receiving Entity Advertises Support
<iq from='hamlet@denmark.lit/throne'
to='horatio@denmark.lit/castle'
type='get'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/rosterx'/>
...
</query>
</iq>
If the sending entity has knowledge (e.g., via presence or an active chat conversation) that the receiving entity is online and available, it SHOULD: [8]
If the sending entity does not know that the receiving entity is online and available, it MUST send a <message/> stanza to the receiving entity's "bare JID" (user@host) rather than an <iq/> stanza to a particular resource.
If the sending entity uses <iq/> stanzas to communicate its roster item exchange suggestions, the receiving entity MUST adhere to the IQ semantics defined in XMPP Core [9]. Specifically:
Naturally, other IQ errors may be more appropriate; however, if the receiving entity will not or cannot process the suggested action(s), it MUST return an error to the sending entity.
The sending entity or sending application SHOULD NOT send additions, deletions, and modifications in the same <x/> element and <message/> or <iq/> stanza; instead, it SHOULD send separate stanzas for the additions, deletions, and modifications.
If approval is required or recommended regarding more than one item suggested by the sending entity, the receiving entity SHOULD present all of the items for approval at the same time or in the same interface; however, the receiving application may want to split additions, deletions, and modifications into separate prompts so as not to confuse the user.
If the sending entity is in some sense "trusted" (see Trusted Entities), then the receiving application MAY skip the approval steps described above.
The receiving application SHOULD NOT accept an unreasonable number of roster items from any one sending entity at one time. Unfortunately, it can be difficult to determine how many roster items count as "unreasonable". For example, when a user registers with a gateway, it is possible that the initial set of roster items may be quite large (however, note that most existing consumer IM services enforce a limit of 100 to 150 items in their contact lists). Users who have newly registered with or been newly created on a server (e.g., within an organization) may also receive a large set of initial roster items in order to sync up with shared groups established on the server. However, after such initialization, the subsequent roster item sets should be much smaller. In any case, sets of more than 150 or 200 roster items SHOULD be treated with suspicion, and entities that repeatedly send such sets SHOULD NOT be trusted.
The foregoing protocol description speaks only of "sending entities" and does not differentiate between different types of sending entities. However, it is envisioned that roster items will be sent to receiving entities by three different kinds of senders:
These are described more completely below.
Roster item exchange as developed within the early Jabber community and documented in JEP-0093 was used to send a roster item from one user to another in a manner more structured than simply typing a third party's JID in a chat window. This usage is still encouraged. However, if the sender is a human user and/or the sending application has a primary Service Discovery category of "client", the sending application SHOULD NOT specify an 'action' attribute other than "add", the receiving application MAY ignore values of the 'action' attribute other than "add", and the receiving application MUST prompt a human user regarding whether to add the suggested item or items to the user's roster.
The nature of client proxy gateways (i.e., entities with a service discovery category of "gateway") is specified more fully in Gateway Interaction [10]. Herein we describe how such gateways should use roster item exchange, and how receiving applications should treat roster items received from such gateways.
In order to make use of a gateway's protocol translation service, a user MUST first register with the gateway. If the gateway advertises support for a service discovery feature of 'http://jabber.org/protocol/rosterx', then the user's client SHOULD expect that it may receive roster item suggestions from the gateway. In order to maintain synchronization between the user's contact list on a legacy IM service and the user's Jabber roster, the gateway SHOULD send roster items with an 'action' attribute of "add", "delete", or "modify" as appropriate, and the receiving application SHOULD process such roster item suggestions. Such processing MAY occur automatically (i.e., without the user's approval of each roster item or batch of roster items) if and only if the receiving application has explicitly informed the user that it will automatically process roster items from the gateway. Furthermore, the receiving application SHOULD periodically verify automatic processing with the user (e.g., once per session in which the gateway sends roster item suggestions to the user).
There is a third category of entities that might initiate roster item exchanges, which we label a "group service" and identify by a Service Discovery category of "directory" and type of "group". A group service enables an administrator to centrally define and administer roster groups so that they can be shared among a user population in an organized fashion. Such a service could prove useful in enterprise environments [11] and other settings where it is beneficial to synchronize rosters across individuals (e.g., schools, social networking applications, consumer IM services, and anywhere else that it is important to build and manage small communities of users).
In some contexts, an IM server could function as a group service (e.g., if there is a single server deployed on a small company intranet); in other contexts, it may make more sense to deploy a standalone group service (e.g., in a larger or more heterogeneous environment with users on multiple servers). In both cases, the group service MUST advertise a service discovery identity of "directory/group" and SHOULD use the protocol specified herein to communicate changes ("add", "delete", and "modify") to the relevant shared groups; in addition, a user MUST first register with the service (either over Jabber via In-Band Registration [12] or out of band, e.g., via the web) or be otherwise provisioned to use the service (e.g., by a system administrator) before accepting roster item suggestions from the service.
If the user has registered with a group service or been otherwise provisioned to use a group service, the receiving application SHOULD process roster item suggestions received from the service. Such processing MAY occur automatically (i.e., without the user's approval of each roster item or batch of roster items) if and only if the receiving application has explicitly informed the user that it will automatically process roster items from the service. Furthermore, the receiving application SHOULD periodically verify automatic processing with the user (e.g., once per session in which the service sends roster item suggestions to the user).
A principal (user) or receiving application MAY establish a list of trusted entities from which roster item exchanges are processed automatically, i.e., without explicit approval by a human user. In order to avoid corruption of the roster, it is STRONGLY RECOMMENDED that such trusted entities be limited to gateways and group services as defined above. In addition, the receiving application SHOULD periodically verify such automatic processing with the principal, e.g., once per session in which the trusted entity sends roster item suggestions to the user.
A sending entity could effectively deny service to the receiving entity by rapidly and repeatedly sending (1) alternating add and delete suggestions or (2) modify suggestions, thus invoking throttling mechanisms enforced by the receiving entity's server. The receiving application SHOULD guard against this by monitoring roster item exchanges received from each sending entity and refusing or ignoring roster item exchanges from offending entities (e.g., by adding such entities to a list of distrusted entities).
A receiving application MAY refuse to advertise its support for the roster item exchange protocol (see the Service Discovery section of this document) to entities that that are (1) not explicitly trusted or (2) explicitly distrusted.
This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [13].
The Jabber Registrar [14] shall include 'http://jabber.org/protocol/rosterx' in its registry of protocol namespaces.
The Jabber Registrar shall include a Service Discovery type of "group" under the "directory" category in its registry of service discovery identities.
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/rosterx'
xmlns='http://jabber.org/protocol/rosterx'
elementFormDefault='qualified'>
<xs:element name='x'>
<xs:complexType>
<xs:sequence>
<xs:element ref='item' minOccurs='1' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='item'>
<xs:complexType>
<xs:sequence>
<xs:element name='group' type='xs:string' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='action' use='optional'/>
<xs:simpleType>
<xs:restriction base='xs:NCName' default='add'>
<xs:enumeration value='add'/>
<xs:enumeration value='delete'/>
<xs:enumeration value='modify'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='jid' type='xs:string' use='required'/>
<xs:attribute name='name' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
</xs:schema>
1. RFC 2779: A Model for Presence and Instant Messaging <http://www.ietf.org/rfc/rfc2779.txt>.
2. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.
3. JEP-0093: Roster Item Exchange <http://www.jabber.org/jeps/jep-0093.html>.
4. The Standards JIG is a standing Jabber Interest Group devoted to discussion of Jabber Enhancement Proposals. The discussion list of the Standards JIG is the primary venue for discussion of Jabber protocol development, as well as for announcements by the JEP Editor and Jabber Registrar. To subscribe to the list or view the list archives, visit <http://mail.jabber.org/mailman/listinfo/standards-jig/>.
5. The default value of the 'action' attribute is "add"; therefore, if the 'action' attribute is not included or the receiving application does not understand the 'action' attribute, the receiving application MUST treat the item as if the value were "add".
6. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.
7. JEP-0115: Entity Capabilities <http://www.jabber.org/jeps/jep-0115.html>.
8. If the receiving entity has more than one available resource, the sending application SHOULD communicate with the "most available" resource according its best estimation (e.g., the resource with the highest priority).
9. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.
10. JEP-0100: Gateway Interaction <http://www.jabber.org/jeps/jep-0100.html>.
11. For example, when Alice is hired by the marketing department of Big Company Enterprises, it makes sense for her to automatically have the other members of the marketing department in her roster the first time she logs in, and for the rest of the marketing department to have Alice in their rosters as soon as her account has been set up. Similarly, when Bob in logistics gets fired, it makes sense for him to disappear from the rosters of everyone else in the logistics department.
12. JEP-0077: In-Band Registration <http://www.jabber.org/jeps/jep-0077.html>.
13. 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 <http://www.iana.org/>.
14. 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 <http://www.jabber.org/registrar/>.
END