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 (XEP-0093) [3]. However, since that time discussions in the Standards SIG [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 XEP-0093, specifically the ability to indicate whether a roster item is to be added, deleted, or modified. Therefore this document 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 specifications will define how to solve the problems of shared groups and roster synchronization using the protocol defined herein.
XEP-0093 did not define the requirements for roster item exchange. This section remedies that oversight.
Roster item exchange meets the following requirements:
This document 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 is sent, it MAY contain a <body/> element but SHOULD NOT contain any other child elements. Here is an example:
<message from='horatio@denmark.lit' to='hamlet@denmark.lit'>
<body>Some visitors, m'lord!</body>
<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 deleted, 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 is sent, it MAY contain a <body/> element but SHOULD NOT contain any other child elements. Here is an example:
<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 modified, 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 is sent, it MAY contain a <body/> element but SHOULD NOT contain any other child elements. Here is an example:
<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 (XEP-0030) [6] but MAY depend on the "profile" of Service Discovery defined in Entity Capabilities (XEP-0115) [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:
<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:
<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>
Roster item exchanges can be sent in any of the four following ways:
In an <iq/> stanza to a full JID <localpart@domain.tld/resource>. This is appropriate if the sender has knowledge (e.g., via presence and Entity Capabilities (XEP-0115) [7]) that a particular resource associated with the recipient is online and supports this protocol.
In an <iq/> stanza to a bare JID <localpart@domain.tld>. This can be appropriate if the sender wants the roster item to be processed by the server on behalf of the recipient (e.g., if the sender is a trusted component of the server).
In a <message/> stanza to a bare JID <localpart@domain.tld>. This can be appropriate if the sender wants the roster item to be delivered to all of the recipient's online resources (e.g., because the sender does to have presence or capabilities information about particular resources).
In a <message/> stanza to a full JID <localpart@domain.tld/resource>. This is generally undesirable, since it is better to se an <iq/> stanza when sending to a full JID (e.g., IQ stanzas are automatically acknowledged).
The sending entity or sending application MUST 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.
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 XEP-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" (e.g., a bot) [8], 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 (XEP-0100) [9]. 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 [10] 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 (XEP-0077) [11] 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 document requires no interaction with the Internet Assigned Numbers Authority (IANA) [12].
The XMPP Registrar [13] includes 'http://jabber.org/protocol/rosterx' in its registry of protocol namespaces.
The XMPP Registrar includes 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:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
XEP-0144: http://www.xmpp.org/extensions/xep-0144.html
</xs:documentation>
</xs:annotation>
<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' default='add'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<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>
Thanks to Joe Hildebrand and Sicong Yao for their feedback.
This document in other formats: XML PDF
This XMPP Extension Protocol is copyright © 1999 – 2020 by the XMPP Standards Foundation (XSF).
Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.
## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.
This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).
The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards 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 document 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 primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.
Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.
Errata can be sent to <editor@xmpp.org>.
The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
1. RFC 2779: A Model for Presence and Instant Messaging <http://tools.ietf.org/html/rfc2779>.
2. RFC 6121: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/rfc6121>.
3. XEP-0093: Roster Item Exchange <https://xmpp.org/extensions/xep-0093.html>.
4. The Standards SIG is a standing Special Interest Group devoted to development of XMPP Extension Protocols. The discussion list of the Standards SIG is the primary venue for discussion of XMPP protocol extensions, as well as for announcements by the XMPP Extensions Editor and XMPP Registrar. To subscribe to the list or view the list archives, visit <https://mail.jabber.org/mailman/listinfo/standards/>.
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. XEP-0030: Service Discovery <https://xmpp.org/extensions/xep-0030.html>.
7. XEP-0115: Entity Capabilities <https://xmpp.org/extensions/xep-0115.html>.
8. See <http://www.xmpp.org/registrar/disco-categories.html#client>.
9. XEP-0100: Gateway Interaction <https://xmpp.org/extensions/xep-0100.html>.
10. 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.
11. XEP-0077: In-Band Registration <https://xmpp.org/extensions/xep-0077.html>.
12. 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/>.
13. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <https://xmpp.org/registrar/>.
Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/
END