<abstract>This JEP defines a protocol profile for centrally defined and administered roster groups; the protocol described herein has been retracted in favor of JEP-0144: Roster Item Exchange.</abstract>
<abstract>This document defines a protocol profile for centrally defined and administered roster groups; the protocol described herein has been retracted in favor of XEP-0144: Roster Item Exchange.</abstract>
&LEGALNOTICE;
<number>0140</number>
<status>Retracted</status>
@ -16,12 +16,12 @@
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>JEP-0060</spec>
<spec>JEP-0093</spec>
<spec>XEP-0060</spec>
<spec>XEP-0093</spec>
</dependencies>
<supersedes/>
<supersededby>
<spec>JEP-0144</spec>
<spec>XEP-0144</spec>
</supersededby>
<shortname>groups</shortname>
&stpeter;
@ -29,7 +29,7 @@
<version>0.2</version>
<date>2004-10-27</date>
<initials>psa</initials>
<remark>Retracted in favor of JEP-0144.</remark>
<remark>Retracted in favor of XEP-0144.</remark>
</revision>
<revision>
<version>0.1</version>
@ -42,16 +42,16 @@
<p>&xmppim; defines a protocol for personal rosters (also known as contact lists). So far all Jabber rosters are personal rosters that are defined by a single user and accessed only by that user. However, in some contexts it would be helpful to centrally define and administer roster groups so that they can be shared among a user population in an organized fashion. This functionality is often called "shared groups".</p>
<p>One context in which shared groups might be useful is the enterprise environment. 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.</p>
<p>This functionality is not limited to the enterprise environment. It could prove quite useful in academic settings, social networking applications, consumer IM services, and anywhere else that it is important to build and manage small communities of users.</p>
<p>Although &jep0093; defines a format for sharing roster items between two users and therefore enables one user to send roster items to another user, it does not currently provide a way to share or coordinate a group of roster items in an organized fashion. To make that possible, this document extends JEP-0093 by defining &jep0060; as the distribution mechanism, resulting in a basic solution for shared groups over Jabber.</p>
<p>Although &xep0093; defines a format for sharing roster items between two users and therefore enables one user to send roster items to another user, it does not currently provide a way to share or coordinate a group of roster items in an organized fashion. To make that possible, this document extends XEP-0093 by defining &xep0060; as the distribution mechanism, resulting in a basic solution for shared groups over Jabber.</p>
</section1>
<section1topic='Requirements'anchor='reqs'>
<p>This JEP addresses the following use cases:</p>
<p>This document addresses the following use cases:</p>
<ol>
<li>Creating a shared group.</li>
<li>Adding a member to the group.</li>
<li>Removing a member from the group.</li>
</ol>
<p>This JEP does not address the following use cases, which instead are discussed in the <linkurl="#impl">Implementation Guidelines</link> section of this document:</p>
<p>This document does not address the following use cases, which instead are discussed in the <linkurl="#impl">Implementation Guidelines</link> section of this document:</p>
<ul>
<li>Exchanging presence with members of a shared group.</li>
<li>Sending a message to all members of a shared group.</li>
<p>An administrator may wish to define a hierarchy of shared groups (e.g., "Marketing/Europe" and "Marketing/North America"). This can be done using collection nodes as defined in Section 9 of JEP-0060. The receiving application MAY use &jep0083; to define the roster group names.</p>
<p>An administrator may wish to define a hierarchy of shared groups (e.g., "Marketing/Europe" and "Marketing/North America"). This can be done using collection nodes as defined in Section 9 of XEP-0060. The receiving application MAY use &xep0083; to define the roster group names.</p>
<p>In order to send a message to all members of a shared group, a group member's sending application (usually an end-user client) SHOULD either send multiple messages or use &jep0033;.</p>
<p>In order to send a message to all members of a shared group, a group member's sending application (usually an end-user client) SHOULD either send multiple messages or use &xep0033;.</p>
<p>In order to invite all members of a shared group to a groupchat room, a group member's sending application SHOULD use the mechanisms defined in &jep0045;.</p>
<p>In order to invite all members of a shared group to a groupchat room, a group member's sending application SHOULD use the mechanisms defined in &xep0045;.</p>
<p>This protocol introduces no security considerations above and beyond those defined in <strong>JEP-0060: Publish-Subscribe</strong> and <strong>JEP-0093: Roster Item Exchange</strong>.</p>
<p>This protocol introduces no security considerations above and beyond those defined in <strong>XEP-0060: Publish-Subscribe</strong> and <strong>XEP-0093: Roster Item Exchange</strong>.</p>
<remark>Renamed <desc/> element to <text/> to avoid confusion with JEP-0004 element names; clarified formal definition of <text/> element; added <text/> elements to examples.</remark>
<remark>Renamed <desc/> element to <text/> to avoid confusion with XEP-0004 element names; clarified formal definition of <text/> element; added <text/> elements to examples.</remark>
</revision>
<revision>
<version>0.2</version>
@ -50,10 +50,10 @@
</revision>
</header>
<section1topic='Introduction'anchor='intro'>
<p>&jep0004; ("x:data") provides a simple and interoperable way to request and present information for both applications and humans. However, the simple nature of "x:data" requires the form renderer to use a generic "key/value" format. This JEP builds upon "x:data" to enable applications to specify additional layout information.</p>
<p>&xep0004; ("x:data") provides a simple and interoperable way to request and present information for both applications and humans. However, the simple nature of "x:data" requires the form renderer to use a generic "key/value" format. This document builds upon "x:data" to enable applications to specify additional layout information.</p>
</section1>
<section1topic='Requirements'anchor='reqs'>
<p>The requirements for this JEP are:</p>
<p>The requirements for this document are:</p>
<ul>
<li>Provide hints for laying out form fields in pages.</li>
<li>Provide hints for laying out pages in sections.</li>
@ -62,7 +62,7 @@
</ul>
</section1>
<section1topic='Use Cases'anchor='usecases'>
<p>This JEP defines a new namespace, "http://jabber.org/protocol/xdata-layout". All layout is defined by "pages" and "sections".</p>
<p>This document defines a new namespace, "http://jabber.org/protocol/xdata-layout". All layout is defined by "pages" and "sections".</p>
<p>All of the use cases refer to the following form:</p>
<examplecaption='Sample form'><![CDATA[
<xxmlns='jabber:x:data'type='form'>
@ -91,7 +91,7 @@
<fieldvar='activity.mailing-lists'type='text-multi'label='Recent Mailing List Activity'>
</field>
<fieldvar='activity.jeps' type='text-multi'label='JEPs Authored or Co-Authored'>
<fieldvar='activity.xeps' type='text-multi'label='XEPs Authored or Co-Authored'>
<p>Form providers MAY attempt to discover if the recipient of a form supports the data forms layout protocol extension, although implementations are not required to do so. If implemented, Discovery MUST be implemened as defined in &jep0030;, using the namespace "http://jabber.org/protocol/xdata-layout" as a feature.</p>
<p>Form providers MAY attempt to discover if the recipient of a form supports the data forms layout protocol extension, although implementations are not required to do so. If implemented, Discovery MUST be implemened as defined in &xep0030;, using the namespace "http://jabber.org/protocol/xdata-layout" as a feature.</p>
<p>In order to prevent the processing from becoming too complex, there are some restrictions in how fields are distributed within the layout.</p>
@ -296,16 +296,16 @@
<p>The <text/> child element of the <section/> element is OPTIONAL. If it is missing, the renderer MAY use whatever it deems appropriate (including nothing).</p>
<p>This JEP relies on the internationalization/localization mechanisms provided by &xmppcore;. Specifically, labels and descriptions MUST be appropriate for the locale indicated by the containing stanza or <form/> element.</p>
<p>This document relies on the internationalization/localization mechanisms provided by &xmppcore;. Specifically, labels and descriptions MUST be appropriate for the locale indicated by the containing stanza or <form/> element.</p>
<abstract>This document defines an XMPP protocol extension that enables a user to communicate with a representative of an organization, department, or workgroup.</abstract>
@ -15,8 +15,8 @@
<jig>Standards JIG</jig>
<dependencies>
<spec>XMPP Core</spec>
<spec>JEP-0030</spec>
<spec>JEP-0045</spec>
<spec>XEP-0030</spec>
<spec>XEP-0045</spec>
</dependencies>
<supersedes>None</supersedes>
<supersededby>None</supersededby>
@ -56,11 +56,11 @@
</section2>
<section2topic='Concepts'anchor='intro-concepts'>
<p>The namespace governing this protocol is "http://jabber.org/protocol/workgroup". This namespace relies on the &IQ; element for execution, and uses the &PRESENCE; element for announcing status updates.</p>
<p>This protocol depends on &jep0030; for reporting and announcing available workgroup services. However, support for service discovery is entirely optional and workgroup services may be made known through other means (e.g. web pages or word of mouth .</p>
<p>This protocol depends on &xep0030; for reporting and announcing available workgroup services. However, support for service discovery is entirely optional and workgroup services may be made known through other means (e.g. web pages or word of mouth .</p>
<p>The end result of a workgroup interaction is to negotiate and route a user and workgroup member (a.k.a. agent) to an appropriate chat room for a chat conversation using the multi-user chat (MUC) protocol. However, multi-user chat essentially 'takes over' when the workgroup protocol successfully completes so there is no overlap between the two protocols. It is RECOMMENDED that groupchat implementations support basic groupchat (a.k.a. Groupchat 1.0) for maximum client compatibility.</p>
<p>There are no requirements for supporting the workgroup protocol beyond &xmppcore; and &jep0045;. Support for &jep0004; is optional if users need to submit additional data before joining (see User Join section of this document).</p>
<p>There are no requirements for supporting the workgroup protocol beyond &xmppcore; and &xep0045;. Support for &xep0004; is optional if users need to submit additional data before joining (see User Join section of this document).</p>
</section2>
</section1>
<section1topic='Roles and Responsibilities'anchor='roleresp'>
<p>Finally an example of a required form submission before a user is allowed to the workgroup queue for support@workgroup.example.com. The data form in this example is trivial; please see <cite>JEP-0004</cite> for a complete data form example. The example begins as normal, but the workgroup returns a &e406; error.</p>
<p>Finally an example of a required form submission before a user is allowed to the workgroup queue for support@workgroup.example.com. The data form in this example is trivial; please see <cite>XEP-0004</cite> for a complete data form example. The example begins as normal, but the workgroup returns a &e406; error.</p>
<examplecaption='Join With Form'><![CDATA[
U: <iqtype='set'
U: from='user@example.net/home'
@ -471,7 +471,7 @@ User Service
|<-----------------------------|
| |
]]></example>
<p>The server sends an invitation to the user to begin their conversation with an agent, structured according to the format defined in <cite>JEP-0045</cite>. The 'from' attribute of the <invite/> element MUST be set to the JID of the workgroup. The invitation indicates that the user is no longer in the workgroup queue. The user MUST NOT receive any more user queue status updates once they receive an invitation.</p>
<p>The server sends an invitation to the user to begin their conversation with an agent, structured according to the format defined in <cite>XEP-0045</cite>. The 'from' attribute of the <invite/> element MUST be set to the JID of the workgroup. The invitation indicates that the user is no longer in the workgroup queue. The user MUST NOT receive any more user queue status updates once they receive an invitation.</p>
<p>There are no defined error conditions for user invitations.</p>
</section4>
@ -630,7 +630,7 @@ S: </presence>
<p>The defined sub-elements of <notify-queue> are:</p>
<ul>
<li><count> - The total number of users in the workgroup queue.</li>
<li><oldest> - The date and time when the oldest member of the queue joined (MUST conform to the DateTime profile defined in &jep0082;).</li>
<li><oldest> - The date and time when the oldest member of the queue joined (MUST conform to the DateTime profile defined in &xep0082;).</li>
<li><time> - The average time in seconds that a user is in the queue before they are routed to an agent for handling.</li>
<li><status> - The status of the queue. Queues may be active (requests are being routed and handled by agents) but not accepting new requests for handling. Typical reasons for this state include the queue is shutting down but finishing processing users in the queue, or because the queue has too many requests and should not accept more request until the existing requests are handled. The status field MUST contain one of the following values:
<ul>
@ -657,7 +657,7 @@ S: </presence>
<ul>
<li><position> - The user's zero-based position in the queue.</li>
<li><time> - Estimated time in seconds remaining before the user is routed to an agent.</li>
<li><join-time> - The datetime when the user joined the queue (MUST conform to the DateTime profile defined in <cite>JEP-0082</cite>).</li>
<li><join-time> - The datetime when the user joined the queue (MUST conform to the DateTime profile defined in <cite>XEP-0082</cite>).</li>
<p>There are no defined error conditions for workgroup queue status updates.</p>
@ -892,7 +892,7 @@ Agent Service
|<-----------------------------|
| |
]]></example>
<p>The server sends an invitation to the agent to begin their conversation with the user, structured according to the format defined in <cite>JEP-0045</cite>. The 'from' attribute of the <invite/> element MUST be set to the JID of the workgroup.</p>
<p>The server sends an invitation to the agent to begin their conversation with the user, structured according to the format defined in <cite>XEP-0045</cite>. The 'from' attribute of the <invite/> element MUST be set to the JID of the workgroup.</p>
<p>In order to match invitations to offers, all invitations SHOULD include meta-data in the <offer/> element, with the JID of the user specified via the 'jid' attribute. The typical meta-data fragment would appear as:</p>
<p>The Jabber Registrar shall add a Service Discovvery type of "workgroup" to the existing "collaboration" category. The registry submission is as follows:</p>
<p>The XMPP Registrar shall add a Service Discovvery type of "workgroup" to the existing "collaboration" category. The registry submission is as follows:</p>
<p>The author would like to thank Iain Shigeoka for his work on the first version of this document, and Derek DeMoro and Gaston Dombiak for their comments.</p>
<title>Guidelines for Authors of XMPP Extension Protocols</title>
<abstract>This document provides information intended to assist authors of XMPP Extension Protocols.</abstract>
@ -89,7 +89,7 @@
<p>To create your proposal, do a CVS checkout of the 'xmpp' module, change directories to the 'extensions/' directory, copy the template file (e.g., 'cp xep-template.xml xep-foo.xml'), and start editing the file using either a basic text editor or a specialized XML editing application such as XML Spy or XMLmind.</p>
<p>Even if you use a basic text editor, you should be able to view your document in most modern web browsers as an XML file as long as you have xep.xsl and xep.dtd in the 'extensions/' directory. Because of inconsistencies in browser XSLT implementations, certain formatting (e.g., table layouts and the numbering of tables, examples, and footnotes) may not be perfect. Don't panic; it will look fine in the HTML output produced by the XMPP Extensions Editor. If your XML file doesn't render at all (i.e., it's just one big text blob), you are using a bad browser. If you see only the bare outline generated by xep.xsl but none of your text, you have an error in your XML. You can check your XML syntax at xml.com <note><<linkurl="http://www.xml.com/pub/a/tools/ruwf/check.html">http://www.xml.com/pub/a/tools/ruwf/check.html</link>></note>.</p>
<p>To programatically convert your XML file into HTML, we recommend using Daniel Veillard's <linkurl='http://xmlsoft.org/XSLT/'>xsltproc</link> program, which will give you helpful error messages regarding XML syntax problems. However, the XMPP Extensions Editor will do the final rendering of XML into HTML as well as posting of your HTML file to www.xmpp.org, so you do not need to generate HTML files for submission to the XMPP Extensions Editor (in fact, the XMPP Extensions Editor requires that you submit your proposal in the XEP XML format, not HTML).</p>
<p>Finally, the jep.ent file contains convenient "external entities" that provide shortcuts for including references to XMPP Extension Protocols, RFCs, and other common strings. Unfortunately, most browsers do not correctly process external entities, so you cannot include entities from jep.ent if you need to view your XML source file in a browser. However, the XMPP Extensions Editor reserves the right to convert your markup to external entities, since it makes his life easier. Also, please do not add items to the jep.ent file; instead, ask the XMPP Extensions Editor to add them for you.</p>
<p>Finally, the xep.ent file contains convenient "external entities" that provide shortcuts for including references to XMPP Extension Protocols, RFCs, and other common strings. Unfortunately, most browsers do not correctly process external entities, so you cannot include entities from xep.ent if you need to view your XML source file in a browser. However, the XMPP Extensions Editor reserves the right to convert your markup to external entities, since it makes his life easier. Also, please do not add items to the xep.ent file; instead, ask the XMPP Extensions Editor to add them for you.</p>
<p>This section describes the metadata elements contained in the <header/> element of a XEP file (see below for the file contents).</p>
@ -111,7 +111,7 @@
<p>The <example/> and <code/> elements are used to show protocol snippets; the <example/> element SHOULD possess a 'caption' attribute that describes the example, whereas the <code/> element does not. Define an XML CDATA section within both of these elements so that you do not need to escape the '<' and '>' characters in your sample XML stanzas, since this makes life much easier for author and editor alike (see the markup in existing XEP specifications).</p>
<p>The <p/> and <li/> elements can also contain more markup that is familiar from XHTML, such as the <img/> element. Note that hyperlinks are of the form <link url='foo'>bar</link> rather than <a href='foo'>bar</a>; the reasons for this are lost in the mists of time and it is too late to change it now, so you'll just have to adjust. If needed, you can also use inline structural and presentational markup such as <em/>, <strong/>, <tt/>, <cite/>, and <span/> within the <p/> and <li/> elements. </p>
<p>You may also include tables (these are helpful for listing error codes and such). The <table/> element SHOULD possess a 'caption' attribute that describes the table's contents. Standard XHTML table structure applies (<tr/> defines a row, which contains <th/> elements for header rows and <td/> elements for data rows), and the 'colspan' and 'rowspan' attributes are also available if you need them. Table presentation (such as cellpadding and cellspacing) is handled by the XSLT and CSS stylesheets.</p>
<p>In fact, the jep.xsl file performs all sorts of magic in converting your XML file into HTML, including creation of the front matter, table of contents, section numbering, notes, and revision history. Feel free to submit patches for this file, but do not commit your modified version to CVS.</p>
<p>In fact, the xep.xsl file performs all sorts of magic in converting your XML file into HTML, including creation of the front matter, table of contents, section numbering, notes, and revision history. Feel free to submit patches for this file, but do not commit your modified version to CVS.</p>
</section2>
</section1>
<section1topic='The Sections of a XEP Document'anchor='sections'>
@ -227,11 +227,11 @@
<p>Elements <em>possess</em> attributes and <em>contain</em> character data and/or child elements; do not confuse these terms.</p>
<p>Do not use the term "tag" when you mean "element".</p>
<p>Do not add a possessive to the element itself. Negative example: the <body/>'s character data. Positive example: the <body/> element's character data.</p>
<p>Note: There are shortcuts for stanza names and some common element names in the jep.ent file.</p>
<p>Note: There are shortcuts for stanza names and some common element names in the xep.ent file.</p>
</section2>
<section2topic='Errors'anchor='style-err'>
<p>When talking about an error condition, use the XML element names defined in <cite>RFC 3920</cite> rather than the old HTTP-style code numbers. Example: the <feature-not-implemented/> error.</p>
<p>Note: There are shortcuts for the stanza errors in the jep.ent file.</p>
<p>Note: There are shortcuts for the stanza errors in the xep.ent file.</p>
</section2>
<section2topic='Namespaces'anchor='style-ns'>
<p>When talking about a namespace by name, refer to it in single quotes. Example: the 'jabber:iq:roster' namespace.</p>
<abstract>This JEP defines a protocol for exchanging roster items, including the ability to suggest whether the item is to be added, deleted, or modified.</abstract>
<remark>Forked JEP-0093 by adding the action attribute, defining requirements and use cases, specifying processing rules, and detailing security considerations.</remark>
<remark>Forked XEP-0093 by adding the action attribute, defining requirements and use cases, specifying processing rules, and detailing security considerations.</remark>
</revision>
</header>
<section1topic='Introduction'anchor='intro'>
<p>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 &rfc2779;, it was removed from &xmppim; and documented for historical purposes in &jep0093;. However, since that time discussions in the &SJIG; 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.</p>
<p>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 &rfc2779;, it was removed from &xmppim; and documented for historical purposes in &xep0093;. However, since that time discussions in the &SJIG; 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 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.</p>
</section1>
<section1topic='Requirements'anchor='reqs'>
<p>JEP-0093 did not define the requirements for roster item exchange. This section remedies that oversight.</p>
<p>XEP-0093 did not define the requirements for roster item exchange. This section remedies that oversight.</p>
<p>Roster item exchange meets the following requirements:</p>
<ol>
<li>Enable an entity to send one or more roster items to another entity, with the suggestion that the roster item(s) be added to the recipient's roster.</li>
@ -178,7 +178,7 @@
</section2>
</section1>
<section1topic='Service Discovery'anchor='disco'>
<p>In order to determine whether a receiving entity supports the protocol defined herein, the sending entity SHOULD use &jep0030; but MAY depend on the "profile" of Service Discovery defined in &jep0115;. If an entity supports roster item exchange, it MUST (subject to appropriate security considerations as described under <linkurl='#security-support'>Advertising Support</link>) 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:</p>
<p>In order to determine whether a receiving entity supports the protocol defined herein, the sending entity SHOULD use &xep0030; but MAY depend on the "profile" of Service Discovery defined in &xep0115;. If an entity supports roster item exchange, it MUST (subject to appropriate security considerations as described under <linkurl='#security-support'>Advertising Support</link>) 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:</p>
<examplecaption='Sending Entity Queries for Support'><![CDATA[
<p>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 <cite>Service Discovery</cite> category of "client" (e.g., a bot) <note>See <<linkurl='http://www.jabber.org/registrar/disco-categories.html#client'>http://www.jabber.org/registrar/disco-categories.html#client</link>>.</note>, 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.</p>
<p>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 <cite>Service Discovery</cite> category of "client" (e.g., a bot) <note>See <<linkurl='http://www.jabber.org/registrar/disco-categories.html#client'>http://www.jabber.org/registrar/disco-categories.html#client</link>>.</note>, 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.</p>
<p>The nature of client proxy gateways (i.e., entities with a service discovery category of "gateway") is specified more fully in &jep0100;. Herein we describe how such gateways should use roster item exchange, and how receiving applications should treat roster items received from such gateways.</p>
<p>The nature of client proxy gateways (i.e., entities with a service discovery category of "gateway") is specified more fully in &xep0100;. Herein we describe how such gateways should use roster item exchange, and how receiving applications should treat roster items received from such gateways.</p>
<p>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).</p>
<p>There is a third category of entities that might initiate roster item exchanges, which we label a "group service" and identify by a <cite>Service Discovery</cite> 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
<note>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.</note>
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).</p>
<p>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 &jep0077; 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.</p>
<p>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 &xep0077; 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.</p>
<p>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).</p>
<p>The Jabber Registrar includes a <cite>Service Discovery</cite> type of "group" under the "directory" category in its registry of service discovery identities.</p>
<p>The XMPP Registrar includes a <cite>Service Discovery</cite> type of "group" under the "directory" category in its registry of service discovery identities.</p>
</section2>
</section1>
<section1topic='XML Schema'anchor='schema'>
@ -286,7 +286,7 @@
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
<remark><p>JEP Editor revisions: changed type to Historical; changed namespace to storage:rosternotes; corrected schema; specified use of DateTime profile from JEP-0082; corrected some small textual errors.</p></remark>
<remark><p>JEP Editor revisions: changed type to Historical; changed namespace to storage:rosternotes; corrected schema; specified use of DateTime profile from XEP-0082; corrected some small textual errors.</p></remark>
</revision>
<revision>
<version>0.1</version>
@ -53,7 +53,7 @@
<p>Many modern IM clients offer functionality that enables users to make notes about items in their roster. This comes in handy if users don't have meaningful information in their vCard or if you need to remember additional things related to a roster item.</p>
<p>This specification defines a protocol for storing annotations about a given set of entities. Its primary goal is to enable users to store some personal piece of information with their roster items. &jep0049; provides with a convenient method for storing user data on the server using the 'jabber:iq:private' namespace; all we need to do is define a namespace and schema for storing this sort of information. For this the 'storage' element introduced in &jep0048; is reused, and a new namespace of 'storage:rosternotes' is added.</p>
<p>This specification defines a protocol for storing annotations about a given set of entities. Its primary goal is to enable users to store some personal piece of information with their roster items. &xep0049; provides with a convenient method for storing user data on the server using the 'jabber:iq:private' namespace; all we need to do is define a namespace and schema for storing this sort of information. For this the 'storage' element introduced in &xep0048; is reused, and a new namespace of 'storage:rosternotes' is added.</p>
</section1>
@ -61,7 +61,7 @@
<p>Annotations are stored using server-side private XML storage (the 'jabber:iq:private' namespace). A storage element marked by the storage:rosternotes namespace contains a collection of one or more <note/> elements, each representing a note about a given entity. For any given JID there MUST NOT be more than one note.</p>
<p>The 'jid' attribute of the <note/> element SHOULD be used without a resource. Along with the annotation a client MAY choose to store creation time ('cdate') and modification time ('mdate') as attributes to the <note/> element containing the note; these attributes MUST conform to the DateTime profile specified in &jep0082; and the timezone SHOULD be UTC.</p>
<p>The 'jid' attribute of the <note/> element SHOULD be used without a resource. Along with the annotation a client MAY choose to store creation time ('cdate') and modification time ('mdate') as attributes to the <note/> element containing the note; these attributes MUST conform to the DateTime profile specified in &xep0082; and the timezone SHOULD be UTC.</p>
<examplecaption='Storing Annotations'>
<![CDATA[
@ -81,7 +81,7 @@
<p>Note: All notes are stored as a "bundle" within the same <storage/> element.</p>
<p>Retrieving notes uses the protocol described in <cite>JEP-0049</cite>.</p>
<p>Retrieving notes uses the protocol described in <cite>XEP-0049</cite>.</p>
<examplecaption='Retrieving Annotations'>
<![CDATA[
@ -108,19 +108,19 @@
</iq>
]]></example>
<p>For error conditions please refer to <cite>JEP-0049</cite>.</p>
<p>For error conditions please refer to <cite>XEP-0049</cite>.</p>
<abstract>This document defines a registry of query components to be used in the context of XMPP IRIs/URIs and also specifies an initial submission of values to that registry.</abstract>
@ -17,7 +17,7 @@
<dependencies>
<spec>XMPP Core</spec>
<spec>RFC 4622</spec>
<spec>JEP-0053</spec>
<spec>XEP-0053</spec>
</dependencies>
<supersedes/>
<supersededby/>
@ -34,7 +34,7 @@
<version>1.1</version>
<date>2006-06-19</date>
<initials>psa</initials>
<remark><p>Added actions for roster removal, presence unsubscription, and cancellation of registration; moved querytypes related to XMPP extensions from this document to the relevant JEPs.</p></remark>
<remark><p>Added actions for roster removal, presence unsubscription, and cancellation of registration; moved querytypes related to XMPP extensions from this document to the relevant XMPP Extension Protocol specifications.</p></remark>
</revision>
<revision>
<version>1.0</version>
@ -107,18 +107,18 @@
<li>Adding or removing a roster item.</li>
<li>Subscribing to or unsubscribing from an entity's presence information.</li>
<li>Probing for current presence information.</li>
<li>Determining &jep0030; information about an entity.</li>
<li>Joining a groupchat room (see &jep0045;).</li>
<li>Requesting initiation of &jep0050; associated with an entity.</li>
<li>Retrieving the &jep0054; data associated with an entity.</li>
<li>Subscribing to or unsubscribing from a &jep0060; node.</li>
<li>Registering with another entity via &jep0077;.</li>
<li>Initiating a file transfer with another entity (see &jep0096;).</li>
<li>Determining &xep0030; information about an entity.</li>
<li>Joining a groupchat room (see &xep0045;).</li>
<li>Requesting initiation of &xep0050; associated with an entity.</li>
<li>Retrieving the &xep0054; data associated with an entity.</li>
<li>Subscribing to or unsubscribing from a &xep0060; node.</li>
<li>Registering with another entity via &xep0077;.</li>
<li>Initiating a file transfer with another entity (see &xep0096;).</li>
</ol>
<p>For each such action, the Jabber Registrar maintains a RECOMMENDED "querytype" (this can be thought of as an action name or "verb"; see <cite>RFC 4622</cite> for syntax and semantics) as well as an OPTIONAL list of keys to be used in key-value pairs if appropriate.</p>
<p>The querytypes and key-value pairs related to <cite>RFC 3920</cite> and <cite>RFC 3921</cite> are defined herein; the querytypes and key-value pairs related to protocols defined in the JSF's JEP series are defined in the relevant JEPs.</p>
<p>For each such action, the XMPP Registrar maintains a RECOMMENDED "querytype" (this can be thought of as an action name or "verb"; see <cite>RFC 4622</cite> for syntax and semantics) as well as an OPTIONAL list of keys to be used in key-value pairs if appropriate.</p>
<p>The querytypes and key-value pairs related to <cite>RFC 3920</cite> and <cite>RFC 3921</cite> are defined herein; the querytypes and key-value pairs related to protocols defined in the JSF's XEP series are defined in the relevant XMPP Extension Protocol specifications.</p>
<p>It may desirable for an XMPP IRI/URI to trigger a specialized interface for sending an XMPP message stanza. The RECOMMENDED querytype for this action is "message". If no key-value pair is provided, interacting with an XMPP IRI/URI that contains a querytype of "message" SHOULD trigger an interface that enables the user to input the text of an XMPP message and other relevant parameters (e.g., a message subject or &jep0071; markup).</p>
<p>It may desirable for an XMPP IRI/URI to trigger a specialized interface for sending an XMPP message stanza. The RECOMMENDED querytype for this action is "message". If no key-value pair is provided, interacting with an XMPP IRI/URI that contains a querytype of "message" SHOULD trigger an interface that enables the user to input the text of an XMPP message and other relevant parameters (e.g., a message subject or &xep0071; markup).</p>
<p>Completion of some of the actions defined herein will cause changes to an entity's account, subscriptions to information, registration with services, communication with other entities, completion of ad-hoc commands, and the like. Naturally, such changes, information, services, and communications are potentially undesirable (e.g., joining a chatroom whose discussion topic is not of interest to, or even patently offensive to, the joining user). The invoked application SHOULD appropriately warn a human user regarding the potential consequences of the action about to be completed.</p>
<p>This document requires no interaction with &IANA;. If in the future the IANA should wish to maintain a registry of XMPP URI/IRI query components, the Jabber Registrar will cooperate with efforts to migrate the registry from the Jabber Registrar to the IANA.</p>
<p>This document requires no interaction with &IANA;. If in the future the IANA should wish to maintain a registry of XMPP URI/IRI query components, the XMPP Registrar will cooperate with efforts to migrate the registry from the XMPP Registrar to the IANA.</p>
<p>The following submission registers parameters related to the XMPP RFCs. For submissions related to XMPP extensions, refer to the relevant JEPs.</p>
<p>The following submission registers parameters related to the XMPP RFCs. For submissions related to XMPP extensions, refer to the relevant XMPP Extension Protocol specifications.</p>
<code><![CDATA[
<querytype>
<name>message</name>
<proto>jabber:client</proto>
<desc>enables sending of an XMPP message stanza</desc>
<abstract>Canonical documentation of the jabber:iq:iq namespace.</abstract>
<abstract>This specification provides canonical documentation of the jabber:iq:iq namespace.</abstract>
&LEGALNOTICE;
<number>0148</number>
<status>Active</status>
@ -29,7 +29,7 @@
</revision>
</header>
<section1topic='Introduction'anchor='intro'>
<p>The early Jabber community was a hotbed of innovation and experimentation. Although the community produced a large number of interesting protocols and technologies, not all of them were widely adopted. For example, server-side message filtering (implemented in the mod_filter module of the &jabberd; server) was one promising technology that simply did not scale up beyond a few hundred concurrent users. Another potentially helpful technology (though even less well-known) was that of the "Instant Messaging Intelligence Quotient" (IM IQ) as defined by the 'jabber:iq:iq' protocol. For the sake of historical completeness, this JEP provides canonical documentation of that protocol.</p>
<p>The early Jabber community was a hotbed of innovation and experimentation. Although the community produced a large number of interesting protocols and technologies, not all of them were widely adopted. For example, server-side message filtering (implemented in the mod_filter module of the &jabberd; server) was one promising technology that simply did not scale up beyond a few hundred concurrent users. Another potentially helpful technology (though even less well-known) was that of the "Instant Messaging Intelligence Quotient" (IM IQ) as defined by the 'jabber:iq:iq' protocol. For the sake of historical completeness, this specification provides canonical documentation of that protocol.</p>
</section1>
<section1topic='Concepts and Approach'anchor='concepts'>
<p>It is a harsh reality of the modern Internet that plenty of stupid people have found their way onto today's communication networks (email, Usenet, IM, and the like). Because the early Jabber developers were your typically elitist geeks (whose mantra seems to have been "not everyone can be as smart as we are"), they sought to shield themselves from the inevitable emergence of dumb Jabber users.</p>
@ -38,7 +38,7 @@
</section1>
<section1topic='Use Cases'anchor='usecases'>
<section2topic='Discover Another User's IM IQ'anchor='disco-other'>
<p>Before chatting with another user over the network or adding that user to one's Jabber roster, it can be helpful to get a sense of how intelligent or unintelligent that person is. This is done by requesting the person's IM IQ from that person's server by sending an IQ get qualified by the 'jabber:iq:iq' namespace to the person's bare JID (user@host) rather than full JID (similar in this regard to the functionality of &jep0054;).</p>
<p>Before chatting with another user over the network or adding that user to one's Jabber roster, it can be helpful to get a sense of how intelligent or unintelligent that person is. This is done by requesting the person's IM IQ from that person's server by sending an IQ get qualified by the 'jabber:iq:iq' namespace to the person's bare JID (user@host) rather than full JID (similar in this regard to the functionality of &xep0054;).</p>
<examplecaption='Requesting Someone's IM IQ'><![CDATA[
<iqtype='get'
from='kindanormal@example.com/IM'
@ -98,7 +98,7 @@
]]></example>
</section2>
<section2topic='Messaging Hints'anchor='hints'>
<p>Even smart people say stupid things, and we are all familiar with the experience of having said something stupid (or just average) and realizing later that one could have said something exceedingly clever. To prevent people from saying stupid things and to help users appear as smart as possible, the mod_iq jabberd module provides hints to users regarding what to say at a given point in a conversation, based on the advanced linguistic analysis technologies described under <linkurl='#impl'>Implementation Guidelines</link> below. A user can ask for a hint by sending the complete message to the server itself, wrapped in a &QUERY; element qualified by the 'jabber:iq:iq' namespace. (While it may be argued that this functionality could be provided client-side, thus saving a roundtrip, it is consistent with the Jabber philosophy of "smart servers, dumb clients" as explained in &jep0134;.)</p>
<p>Even smart people say stupid things, and we are all familiar with the experience of having said something stupid (or just average) and realizing later that one could have said something exceedingly clever. To prevent people from saying stupid things and to help users appear as smart as possible, the mod_iq jabberd module provides hints to users regarding what to say at a given point in a conversation, based on the advanced linguistic analysis technologies described under <linkurl='#impl'>Implementation Guidelines</link> below. A user can ask for a hint by sending the complete message to the server itself, wrapped in a &QUERY; element qualified by the 'jabber:iq:iq' namespace. (While it may be argued that this functionality could be provided client-side, thus saving a roundtrip, it is consistent with the Jabber philosophy of "smart servers, dumb clients" as explained in &xep0134;.)</p>
<examplecaption='Requesting IM IQ Information'><![CDATA[
<iqtype='get'
from='kindanormal@example.com/IM'
@ -175,7 +175,7 @@
<td>idiot</td>
</tr>
</table>
<p>While once common, these terms are now considered politically incorrect. However, please note that this JEP merely provides informational documentation of a protocol historically used within the Jabber community, and is not intended to stereotype individuals in any manner whatsoever. A given server implementation of the 'jabber:iq:iq' protocol MAY substitute more modern ranges and terminology if desired or leave out the descriptive phrases entirely, and a given client implementation MAY rename or disguise the descriptive phrases.</p>
<p>While once common, these terms are now considered politically incorrect. However, please note that this specification merely provides informational documentation of a protocol historically used within the Jabber community, and is not intended to stereotype individuals in any manner whatsoever. A given server implementation of the 'jabber:iq:iq' protocol MAY substitute more modern ranges and terminology if desired or leave out the descriptive phrases entirely, and a given client implementation MAY rename or disguise the descriptive phrases.</p>
<p>That said, it is true that many people on the Jabber network do act like morons, imbeciles, and even idiots.</p>
</section2>
<section2topic='Determination of IM IQ'anchor='impl-determination'>
@ -201,9 +201,9 @@
<p>Most people become somewhat insecure when they realize that in fact they are not as smart as they thought they were; for this reason, querying the server for one's own IM IQ is NOT RECOMMENDED on a regular basis.</p>
</section1>
<section1topic='IANA Considerations'>
<p>This JEP requires no interaction with &IANA;.</p>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1topic='Jabber Registrar Considerations'>
<section1topic='XMPP Registrar Considerations'>
<p>The ®ISTRAR; shall include the 'jabber:iq:iq' namespace in its registry of protocol namespaces.</p>
</section1>
<section1topic='XML Schema'anchor='schema'>
@ -221,7 +221,7 @@
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
<abstract>This document defines a method to specify the valid time periods for states, events, and activities communicated via Jabber/XMPP protocols.</abstract>
@ -16,7 +16,7 @@
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>JEP-0082</spec>
<spec>XEP-0082</spec>
</dependencies>
<supersedes/>
<supersededby/>
@ -38,7 +38,7 @@
<version>0.1</version>
<date>2005-04-21</date>
<initials>psa</initials>
<remark>Initial JEP version.</remark>
<remark>Initial version.</remark>
</revision>
<revision>
<version>0.0.2</version>
@ -54,25 +54,25 @@
</revision>
</header>
<section1topic='Introduction'anchor='intro'>
<p>Certain events and states may last for only a limited period of time. For example, when a person changes his availability to "dnd" and his status to "In a Meeting", the person (or his calendaring application) may know that the meeting is expected to last for 90 minutes; because those who subscribe to the person's presence may find it helpful to know how long the person will be in the meeting, it might be desirable to include that time period information in the presence stanza sent when the person's availability changes. Similar considerations apply to other states, events, and activities, such as various forms of "extended presence" (see &jep0119;).</p>
<p>This JEP defines a straightforward XMPP extension for encapsulating information about time periods, using new headers that adhere to the format specified in &jep0131;.</p>
<p>Certain events and states may last for only a limited period of time. For example, when a person changes his availability to "dnd" and his status to "In a Meeting", the person (or his calendaring application) may know that the meeting is expected to last for 90 minutes; because those who subscribe to the person's presence may find it helpful to know how long the person will be in the meeting, it might be desirable to include that time period information in the presence stanza sent when the person's availability changes. Similar considerations apply to other states, events, and activities, such as various forms of "extended presence" (see &xep0119;).</p>
<p>This document defines a straightforward XMPP extension for encapsulating information about time periods, using new headers that adhere to the format specified in &xep0131;.</p>
</section1>
<section1topic='Requirements'anchor='reqs'>
<p>This JEP addresses the following requirements:</p>
<p>This document addresses the following requirements:</p>
<ol>
<li>Provide the ability to specify time periods for states, events, and activities communicated via Jabber/XMPP protocols.</li>
<li>Conform to &jep0082;.</li>
<li>Conform to &xep0082;.</li>
</ol>
</section1>
<section1topic='Protocol'anchor='protocol'>
<p>In order to specify the time period for a state, event, or activity, the generating entity SHOULD include both "Start" and "Stop" SHIM headers that specify the dateTimes at which the time period starts and stops. The following rules apply:</p>
<ol>
<li>All start and stop dates MUST conform to the dateTime profile specified in <cite>JEP-0082</cite>.</li>
<li>All start and stop dates MUST conform to the dateTime profile specified in <cite>XEP-0082</cite>.</li>
<li>All dateTime information MUST be expressed in UTC (i.e., with no timezone offsets).</li>
<li>Start and stop times SHOULD be understood by the recipient as estimates or approximations.</li>
<li>If both a start time and a stop time are specified, the stop time MUST be later than the start time.</li>
</ol>
<p>These SHIM headers MAY be included wherever appropriate; however, it is expected that they will be included mainly to further specify basic presence states (see &rfc3921;) and various "extended presence" states, events, and activities (see, for example, &jep0107; and &jep0108;).</p>
<p>These SHIM headers MAY be included wherever appropriate; however, it is expected that they will be included mainly to further specify basic presence states (see &rfc3921;) and various "extended presence" states, events, and activities (see, for example, &xep0107; and &xep0108;).</p>
<p>There is no requirement that the start time needs to be the time when the stanza is generated; for example, the start time may be retroactive to a dateTime in the past or may be an estimated dateTime in the future.</p>
</section1>
<section1topic='Examples'anchor='examples'>
@ -89,7 +89,7 @@
]]></example>
</section2>
<section2topic='User Activity'anchor='activity'>
<p>An XMPP extension for user activity is specified in <cite>JEP-0108</cite>. It may be desirable to include time period information when publishing one's activity.</p>
<p>An XMPP extension for user activity is specified in <cite>XEP-0108</cite>. It may be desirable to include time period information when publishing one's activity.</p>
<examplecaption='User Activity With Time Period'><![CDATA[
<iqtype='set'
from='juliet@capulet.com/balcony'
@ -115,7 +115,7 @@
]]></example>
</section2>
<section2topic='User Mood'anchor='mood'>
<p>An XMPP extension for user mood is specified in <cite>JEP-0107</cite>. It may be desirable to include time period information when publishing one's mood.</p>
<p>An XMPP extension for user mood is specified in <cite>XEP-0107</cite>. It may be desirable to include time period information when publishing one's mood.</p>
<examplecaption='User Mood With Time Period'><
Peter Saint-Andre
17 years ago