xep-0011.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Jabber Browsing</title>
  <abstract>This document defines a way to describe information about Jabber entities and the relationships between entities. Note: This document is superseded by XEP-0030: Service Discovery.</abstract>
  &LEGALNOTICE;
  <number>0011</number>
  <status>Obsolete</status>
  <type>Historical</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>XMPP Core</spec>
  </dependencies>
  <supersedes/>
  <supersededby>
    <spec>XEP-0030</spec>
  </supersededby>
  <shortname>iq-browse</shortname>
  &jer;
  &xvirge;
  &temas;
  <revision>
    <version>1.3.1</version>
    <date>2021-03-04</date>
    <initials>mw</initials>
    <remark><p>Cross-document editorial adjustments for inclusive language.</p></remark>
  </revision>
  <revision>
    <version>1.3</version>
    <date>2009-06-03</date>
    <initials>psa</initials>
    <remark><p>Per a vote of the XMPP Council, changed status to Obsolete.</p></remark>
  </revision>
  <revision>
    <version>1.2</version>
    <date>2004-11-12</date>
    <initials>psa</initials>
    <remark><p>Per a vote of the Jabber Council, changed status to Deprecated.</p></remark>
  </revision>
  <revision>
    <version>1.1</version>
    <date>2004-01-06</date>
    <initials>psa</initials>
    <remark><p>Added schema.</p></remark>
  </revision>
  <revision>
    <version>1.0</version>
    <date>2002-05-08</date>
    <initials>psa</initials>
    <remark><p>Changed status to Active.</p></remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2002-04-15</date>
    <initials>jer</initials>
    <remark><p>Changed the suggested use of category to an attribute of item instead of the element names.</p></remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2002-01-16</date>
    <initials>psa</initials>
    <remark><p>Added additional category/type combinations from the protocol draft (also created new category 'validate' as a bucket for the grammar and spelling checkers, which formerly were under the 'render' category).</p></remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2002-01-04</date>
    <initials>jkm</initials>
    <remark><p>Updated to XML format and revised description.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2001-01-25</date>
    <initials>jm</initials>
    <remark><p>Initial draft version.</p></remark>
  </revision>
</header>
<section1 topic='Introduction'>
  <p>The Jabber world is a diverse place, with lots of services, transports, software agents, users, groupchat rooms, translators, headline tickers, and just about anything that might interact on a real-time basis using conversational messages or presence. Every JabberID (JID) is a node that can be interacted with via messages, presence, and special purpose IQ namespaces. Some JIDs are parents (such as transports), and often many JIDs have relationships with other JIDs (such as a user to their resources, a server to its services, etc.). We need a better way to structure and manage this culture of multi-namespace JID stew. The answer: Jabber Browsing.</p>
  <p><em>Note well that implementors are encouraged to implement &xep0030; instead of Jabber Browsing.</em></p>
</section1>
<section1 topic='JID-Types'>
  <p>One of the concepts in browsing which helps to extend the interaction between JIDs is a "JID-Type", a simple heirarchy for identifying the role of any JabberID that is similar to the mime-type format. Many programmers are comfortable with the concept of identifying file types by mime-types, which use the format "category/type". A JID-Type, once discovered, is to be used in the same way that a mime-type would be for a file, to alter the user interface representing that JID or provide alternative functionality for interacting with it (either automatically or driven by user interaction). The following categories and types are proposed as the canonical list for the purpose of JID-Types:</p>
  <table caption='Official List of JID-Type Categories and Types'>
    <tr>
      <th>Category</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
    <tr>
      <td rowspan="7">application/</td>
      <td> </td>
      <td>Specific applications running as a resource on a user@host</td>
    </tr>
    <tr>
      <td>bot</td>
      <td>Automated conversations</td>
    </tr>
    <tr>
      <td>calendar</td>
      <td>Calendaring and scheduling service</td>
    </tr>
    <tr>
      <td>editor</td>
      <td>Collaborative editor</td>
    </tr>
    <tr>
      <td>fileserver</td>
      <td>Available files</td>
    </tr>
    <tr>
      <td>game</td>
      <td>Multi-player game</td>
    </tr>
    <tr>
      <td>whiteboard</td>
      <td>Whiteboard tool</td>
    </tr>
    <tr>
      <td rowspan="7">conference/</td>
      <td> </td>
      <td>Nodes of this category provide multi-user chat facilities (a.k.a. conference rooms).</td>
    </tr>
    <tr>
      <td>irc</td>
      <td>IRC rooms (note: this enables Jabber users to connect to Internet Relay Chat rooms)</td>
    </tr>
    <tr>
      <td>list</td>
      <td>Mailing-list-style conferences</td>
    </tr>
    <tr>
      <td>private</td>
      <td>Private, dynamically-generated conference rooms</td>
    </tr>
    <tr>
      <td>public</td>
      <td>Public, permanent conference rooms</td>
    </tr>
    <tr>
      <td>topic</td>
      <td>Topic-based conferences</td>
    </tr>
    <tr>
      <td>url</td>
      <td>Website-hosted conferences</td>
    </tr>
    <tr>
      <td rowspan="5">headline/</td>
      <td> </td>
      <td>Recognize different sources of headlines, GUI hints</td>
    </tr>
    <tr>
      <td>logger</td>
      <td>Log messages (usually presented in a scrolling GUI)</td>
    </tr>
    <tr>
      <td>notice</td>
      <td>Alerts and warnings (usually presented as popup messages)</td>
    </tr>
    <tr>
      <td>rss</td>
      <td>Rich Site Summary syndication</td>
    </tr>
    <tr>
      <td>stock</td>
      <td>Stock market information by symbol (ticker)</td>
    </tr>
    <tr>
      <td rowspan="7">keyword/</td>
      <td> </td>
      <td>Keyword-based lookup services (search engines, etc.)</td>
    </tr>
    <tr>
      <td>dictionary</td>
      <td>Dictionary lookup service</td>
    </tr>
    <tr>
      <td>dns</td>
      <td>DNS resolver</td>
    </tr>
    <tr>
      <td>software</td>
      <td>Software search</td>
    </tr>
    <tr>
      <td>thesaurus</td>
      <td>Thesaurus lookup service</td>
    </tr>
    <tr>
      <td>web</td>
      <td>Web search</td>
    </tr>
    <tr>
      <td>whois</td>
      <td>Whois query service</td>
    </tr>
    <tr>
      <td rowspan="4">render/</td>
      <td> </td>
      <td>Automated translation services</td>
    </tr>
    <tr>
      <td>en2fr</td>
      <td>English to French</td>
    </tr>
    <tr>
      <td>*2*</td>
      <td>Other language to language (using standard language codes)</td>
    </tr>
    <tr>
      <td>tts</td>
      <td>Text to Speech</td>
    </tr>
    <tr>
      <td rowspan="12">service/</td>
      <td> </td>
      <td>Nodes of this category provide a link to another Instant Messaging network or messaging gateway. The 'jabber:iq:register' namespace can be used to gain access to such networks, and the 'jabber:iq:search' namespace may also be available.</td>
    </tr>
    <tr>
      <td>aim</td>
      <td>AIM transport</td>
    </tr>
    <tr>
      <td>icq</td>
      <td>ICQ transport</td>
    </tr>
    <tr>
      <td>irc</td>
      <td>IRC gateway (note: this enables IRC users to connect to Jabber)</td>
    </tr>
    <tr>
      <td>jabber</td>
      <td>A Jabber server which conforms to the specification for the 'jabber:client' namespace</td>
    </tr>
    <tr>
      <td>jud</td>
      <td>Jabber User Directory</td>
    </tr>
    <tr>
      <td>msn</td>
      <td>MSN transport</td>
    </tr>
    <tr>
      <td>pager</td>
      <td>Pager gateway</td>
    </tr>
    <tr>
      <td>serverlist</td>
      <td>A list of servers. It is assumed that this node has service/* children</td>
    </tr>
    <tr>
      <td>sms</td>
      <td>SMS gateway</td>
    </tr>
    <tr>
      <td>smtp</td>
      <td>SMTP gateway</td>
    </tr>
    <tr>
      <td>yahoo</td>
      <td>Yahoo! transport</td>
    </tr>
    <tr>
      <td rowspan="6">user/</td>
      <td> </td>
      <td>Nodes of this category are Jabber users, typically implementing enough of the 'jabber:client' namespace to be compliant.</td>
    </tr>
    <tr>
      <td>client</td>
      <td>A standard or fully-featured Jabber client compliant with the 'jabber:client' namespace</td>
    </tr>
    <tr>
      <td>forward</td>
      <td>A forward alias</td>
    </tr>
    <tr>
      <td>inbox</td>
      <td>An alternate inbox</td>
    </tr>
    <tr>
      <td>portable</td>
      <td>A portable device implementing some of the 'jabber:client' namespace</td>
    </tr>
    <tr>
      <td>voice</td>
      <td>A node providing phone or voice access</td>
    </tr>
    <tr>
      <td rowspan="4">validate/</td>
      <td> </td>
      <td>Validation services</td>
    </tr>
    <tr>
      <td>grammar</td>
      <td>Grammar-checking tool</td>
    </tr>
    <tr>
      <td>spell</td>
      <td>Spell-checking tool</td>
    </tr>
    <tr>
      <td>xml</td>
      <td>XML validator</td>
    </tr>
  </table>
  <p>Historically each category was used as the name of an element, and the type was an attribute, such as <![CDATA[<service type="aim"/>]]>. The proper expression for all new implementations supporting this specification is to express the type information as attributes on a generic item element: <![CDATA[<item category="service" type="aim"/>]]>. When processing returned browse information this new syntax should always be handled first, and the old syntax only used if it is important to be able to access older implementations.</p>
  <p>Additional unofficial categories or types may be specified by prefixing their name with an "x-", such as "service/x-virgeim" or "x-location/gps". Changes to the official categories and subtypes may be defined either by revising this document or by activating another specification. Removal of a category or subtype must be noted in this document.</p>
</section1>
<section1 topic='The jabber:iq:browse Namespace'>
  <p>The namespace containing the Jabber Browsing data is jabber:iq:browse. The primary element within this namespace is 'item' (again, historically every category listed above would also be an element).</p>
  <section2 topic='Browsing to a JabberID'>
    <p>The common way to browse to a JabberID using IQ is:</p>
    <example caption='Browsing to a JabberID'>
&lt;iq type="get" to="jer@jabber.org" id="browse1"&gt;
  &lt;query xmlns="jabber:iq:browse"/&gt;
&lt;/iq&gt;
    </example>
  </section2>
  <section2 topic='Generic Attributes for Browse Results'>
    <p>The item element has these attributes in a browse result:</p>
    <ul>
      <li>jid [required] -- The full JabberID of the entity described.</li>
      <li>category [optional] -- One of the categories from the list above, or a non-standard category prefixed with the string "x-".</li>
      <li>type [optional] -- One of the official types from the specified category, or a non-standard type prefixed with the string "x-".</li>
      <li>name [optional] -- A friendly name that may be used in a user interface.</li>
      <li>version [optional] -- A string containing the version of the node, equivalent to the response provided to a query in the 'jabber:iq:version' namespace. This is useful for servers, especially for lists of services (see the 'service/serverlist' category/type above).</li>
    </ul>
  </section2>
  <section2 topic='Expressing Relationships'>
    <p>Any item may contain any number of additional items as a child, which describes the hierarchical relationship between the parent and the child items. This relationship could be represented as a "link" in a wizard or page-based user interface, or as a branch in a tree as it is expanded. Browse results usually only contain the direct children of a node, not the grandchildren. Browsing to a user, but not a resource, will return results from the server (still with the user's JID) containing the list of resources.</p>
    <p>For example, this could be the result of browsing to jer@jabber.org:</p>
    <example caption='Result of Browsing to a User'>
&lt;iq type="result" from="jer@jabber.org" id="browse1"&gt;
  &lt;query
      xmlns="jabber:iq:browse"
      category="user"
      jid="jer@jabber.org"
      name="jer"&gt;
    &lt;item
        category="user"
        jid="jer@jabber.org/foxy"
        type="client"/&gt;
    &lt;item
        category="application"
        jid="jer@jabber.org/chess"
        name="XChess"
        type="game"/&gt;
    &lt;item
        category="user"
        jid="jer@jabber.org/palm"
        type="client"/&gt;
  &lt;/query&gt;
&lt;/iq&gt;
    </example>
    <p>More definitively, throughout all of browsing, a parent describes the children, and the children when browsed to fully describe themselves. The browse data received from the child takes precedence.</p>
    <p>Parents should list children only if they are available. This means that if for a user a child client goes offline, the parent should remove it from its browse result.</p>
  </section2>
  <section2 topic='Namespace Advertising'>
    <p>On top of the browsing framework, a simple form of "feature advertisement" can be built. This enables any entity to advertise which features it supports, based on the namespaces associated with those features. The &#60;ns/&#62; element is allowed as a subelement of the item. This element contains a single namespace that the entity supports, and multiple &#60;ns/&#62; elements can be included in any item. For a connected client this might be &#60;ns&#62;jabber:iq:oob&#60;/ns&#62;, or for a service &#60;ns&#62;jabber:iq:search&#60;/ns&#62;. This list of namespaces should be used to present available options for a user or to automatically locate functionality for an application.</p>
    <p>The children of a browse result may proactively contain a few &#60;ns/&#62; elements (such as the result of the service request to the home server), which advertises the features that the particular service supports. This list may not be complete (it is only for first-pass filtering by simpler clients), and the JID should be browsed if a complete list is required.</p>
    <p>Clients should answer incoming browsing requests to advertise the namespaces they support.</p>
    <example caption='Result of Browsing to a Resource'>
&lt;iq type="result" from="jer@jabber.org/foxy" id="browse2"&gt;
  &lt;query
      xmlns="jabber:iq:browse"
      category="user"
      jid="jer@jabber.org/foxy"
      name="laptop"
      type="client"&gt;
    &lt;ns&gt;jabber:client&lt;/ns&gt;
    &lt;ns&gt;jabber:iq:browse&lt;/ns&gt;
    &lt;ns&gt;jabber:iq:conference&lt;/ns&gt;
    &lt;ns&gt;jabber:iq:time&lt;/ns&gt;
    &lt;ns&gt;jabber:iq:version&lt;/ns&gt;
    &lt;ns&gt;jabber:x:roster&lt;/ns&gt;
    &lt;ns&gt;jabber:x:signed&lt;/ns&gt;
    &lt;ns&gt;jabber:x:encrypted&lt;/ns&gt;
  &lt;/query&gt;
&lt;/iq&gt;
    </example>
  </section2>
  <section2 topic='Empty Results'>
    <p>When a JabberID is browsed, the result may contain children or it may be empty. An empty result means there are no further relationships or links under that JID, which could be represented as a page containing a list of functions available for the JID, such as vCard, message, register, etc. When the result contains children, they may also be empty (as in the first result from jer@jabber.org above). An empty child does not mean anything, and to determine the namespaces supported or if there are more children, it must be browsed to directly.</p>
  </section2>
</section1>
<section1 topic='Supplanting jabber:iq:agents'>
  <p>The first important use of jabber:iq:browse is to replace the jabber:iq:agents namespace. When a client connects, it may optionally browse to the server to which it connected in order to retrieve a list of available services. The resulting iq might look like the following example:</p>
    <example caption='Result of Browsing to a Server'>
&lt;iq type="result" from="jabber.org" id="browse3"&gt;
  &lt;query
      xmlns="jabber:iq:browse"
      category="service"
      type="jabber"
      jid="jabber.org"
      name="Jabber.org Public Server"&gt;
    &lt;ns&gt;jabber:client&lt;/ns&gt;
    &lt;ns&gt;jabber:iq:browse&lt;/ns&gt;
    &lt;ns&gt;jabber:iq:conference&lt;/ns&gt;
    &lt;ns&gt;jabber:iq:time&lt;/ns&gt;
    &lt;ns&gt;jabber:iq:version&lt;/ns&gt;
    &lt;item
        category="service"
        jid="icq.jabber.org"
        name="ICQ Transport"
        type="icq"&gt;
      &lt;ns&gt;jabber:iq:register&lt;/ns&gt;
      &lt;ns&gt;jabber:iq:search&lt;/ns&gt;
      &lt;ns&gt;jabber:iq:gateway&lt;/ns&gt;
    &lt;/item&gt;
    &lt;item
      category="conference"
      type="private"
      jid="conference.jabber.org"
      name="Private Chatrooms"/&gt;
    &lt;item
        category="application"
        jid="jabber.org/help"
        name="Assistance Agent"
        type="bot"/&gt;
  &lt;/query&gt;
&lt;/iq&gt;
  </example>
  <p>To determine any further details from this list, each child would have to be browsed. The elements within the icq service are only hints to a client for building user interface elements. The icq.jabber.org service would still need to be browsed in order to determine any relationships or additional namespaces. This top-level list is the primary "services" list available from the server, and should be used for any default functionality when available. This list could also serve as the "home page" for a page-based browsing user interface.</p>
</section1>
<section1 topic='Implementation Notes'>
  <p>A client should not just blindly request browse information every time the user requests it, rather, a client should cache the browse results based on JabberID. Any display or use of the browse data should then be returned from the cache. This model is similiar to that of presence.</p>
</section1>
<section1 topic='Security Considerations'>
  <p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations'>
  <p>No action on the part of the &REGISTRAR; is necessary as a result of this document, since 'jabber:iq:browse' is already a registered protocol namespace.</p>
</section1>
<section1 topic='XML Schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='jabber:iq:browse'
    xmlns='jabber:iq:browse'
    elementFormDefault='qualified'>

  <xs:element name='query'>
    <xs:complexType>
      <xs:choice minOccurs='0' maxOccurs='unbounded'>
        <xs:element ref='item'/>
        <xs:element ref='ns'/>
      </xs:choice>
      <xs:attribute name='category' type='xs:string' use='optional'/>
      <xs:attribute name='jid' type='xs:string' use='optional'/>
      <xs:attribute name='name' type='xs:string' use='optional'/>
      <xs:attribute name='type' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='item'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='ns' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='category' type='xs:string' use='optional'/>
      <xs:attribute name='jid' type='xs:string' use='optional'/>
      <xs:attribute name='name' type='xs:string' use='optional'/>
      <xs:attribute name='type' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='ns' type='xs:string'/>

</xs:schema>
]]></code>
</section1>
<section1 topic='Future Considerations'>
  <p>The 'jabber:iq:browse' namespace has been in use for quite some time. However, live browsing still needs to be better defined by a generic publication/subscription system. It is assumed that when such a system is defined, updates to this document will be made. It is, however, possible that no futher changes to jabber:iq:browse itself may be needed.</p>
</section1>
</xep>