This JEP defines a protocol for exchanging roster items, including the ability to suggest whether the item is to be added, deleted, or modified.
WARNING: This Standards-Track JEP is Experimental. Publication as a Jabber Enhancement Proposal does not imply approval of this proposal by the Jabber Software Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.
Status: Experimental
Type: Standards Track
Number: 0144
Version: 0.1
Last Updated: 2004-09-29
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 - 2004 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.php>. 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 and XMPP IM 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.
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, but uses 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 XMPP IM), 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. The <message/> stanza 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'
name='Rosencrantz'>
<group>Visitors</group>
</item>
<item action='add'
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 "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 XMPP IM. 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/> 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 into which to place the item. The <message/> stanza 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 a roster item deletion stanza will result in removal of the item from the roster (rather than editing of the item), 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 the 'subscription' attribute set to a value of "remove" as described in XMPP IM, since this results in generation of the appropriate <presence/> stanzas by the user's server.
For a description of the recommended application behavior when a roster item deletion 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 modify one or more items from its roster, the sending entity MUST send a <message/> 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. The <message/> stanza 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'
name='Rosencrantz'>
<group>Retinue</group>
</item>
<item action='modify'
jid='guildenstern@denmark'
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 XMPP IM.
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>
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/> 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 are "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.
A principal (user) or receiving application MAY establish a list of trusted entities from which roster item exchanges are handled without approval by a human user. In order to avoid corruption of the roster, it is STRONGLY RECOMMENDED that such trusted entities meet at least one of the following criteria, in order of trustworthiness:
The sending entity is a component (e.g., "groups.example.com") or authoritative representative (e.g., "admin@example.com" if that address is reserved) of the server with which the receiving entity is registered, or the sending entity is the server itself (e.g., "example.com"), such that the receiving application can trust the sending entity as much as it trusts the server.
The sending entity has a Service Discovery identity that typically involves responsibility for roster items (e.g., "gateway/msn") and the receiving entity has previously and explicitly registered with the sending entity, including acknowledgement on the user's part that the sending entity will suggest roster items that may be automatically approved by the receiving application (e.g., a human user has registered with a gateway); such trust SHOULD be periodically verified with the human user (e.g., once per session in which the sending entity suggests roster additions, modifications, or deletions).
The sending entity has otherwise been explicitly approved by a human user as the trusted source of roster items; such trust SHOULD extend to specified roster groups only (e.g., a sender of "stpeter@jabber.org" is trusted only for the "JSF Members" group), and SHOULD be periodically verified with the human user (e.g., once per session in which the sending entity suggests roster additions, modifications, or deletions).
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) [10].
Upon advancement of this JEP to a status of Draft, the Jabber Registrar [11] shall add 'http://jabber.org/protocol/rosterx' to its registry of protocol namespaces.
<?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: Instant Messaging / Presence Protocol Requirements <http://www.ietf.org/rfc/rfc2779.txt>.
2. XMPP IM <http://www.jabber.org/ietf/> (Proposed Standard, RFC number to follow).
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. XMPP Core <http://www.jabber.org/ietf/> (Proposed Standard, RFC number to follow).
10. 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/>.
11. 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