Jabber Browsing

Jeremie Miller


<jeremie@jabber.org> jeremie@jabber.org

Julian Missig


<julian@jabber.org> julian@jabber.org

Thomas Muldowney


<temas@jabber.org> temas@jabber.org

This document has been placed in the public domain.

Revision History
Revision 1.0 2002-01-04 jkm
Updated to JEP format and revised description.
Revision 0.9 2001-01-25 jm
Initial draft version.


Jabber Browsing provides a better way for describing the relationship between JabberIDs.

Table of Contents

The jabber:iq:browse Namespace
Browsing to a JabberID
Generic Attributes for Browse Results
Expressing Relationships
Namespace Advertising
Empty Results
Supplanting jabber:iq:agents
Implementation Notes
Future Considerations


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 with 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 it's services, etc.). We need a better way to structure and manage this culture of JID stew. The answer: Jabber Browsing


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 based on the mime-type format. Many programmers are comfortable identifying file types by mime-types, which use the format "category/type". A JID-Type, after 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 user interface-driven). The following is the list of the categories and types which have been officially defined:

Table 1. Official List of JID-Type Categories and Types

Category Type Description
conference/   Nodes of this category provide conference rooms.
irc IRC rooms
list Mailing list style conference
private Private dynamically-generated conference rooms
public Public permanent conference rooms
topic Topic-based conferences
url Web site-based conferences
service/   Nodes of this category provide a link to another Instant Messaging network or messaging gateway. jabber:iq:register can be used to gain access to the networks they provide links to, and jabber:iq:search may also be available.
jabber A Jabber server which conforms with the specification for jabber:client.
serverlist A list of servers. It is assumed that this node has service/* children.
aim AIM transport
icq ICQ transport
jud Jabber User Directory (Argh! To fit in with the rest of the browsing world, I wish this were just part of the service/jabber node - as in, we should be able to search and register with jabber.org instead of users.jabber.org - it makes more sense to me that way)
irc IRC gateway (Please note that this is for IRC users, not IRC rooms)
msn MSN transport
pager Pager gateway
smtp SMTP gateway
yahoo Yahoo! transport
user/   Nodes of this category are Jabber users, typically implementing enough of jabber:client to be compliant.
client A standard or fully-featured Jabber client compliant with jabber:client.
forward A forward alias.
inbox Alternate inbox.
portable A portable device implementing some of jabber:client.
voice Phone or voice access.
item/   This category describes a node which does not fit any of the other official categories. No types are defined under this category because it is expected that an unofficial "x-" type will be used when necessary (described below).

Additional unofficial types may be specified by prefixing the name with an "x-", such as "service/x-virgeim". Additional categories cannot be unofficially defined under this namespace. Changes to the official categories and subtypes may be defined by either revising this document or activating another JEP. Removal of a category or subtype must be noted in this document.

The jabber:iq:browse Namespace

The namespace containing the Jabber Browsing data is jabber:iq:browse. Every category listed above is an element within this namespace.

Browsing to a JabberID

The common way to browse to a JabberID using IQ is:

Example 1. Browsing to a JabberID

<iq type="get" to="jer@jabber.org" id="example1"/>
  <item xmlns="jabber:iq:browse"/>


Generic Attributes for Browse Results

Every category element has these generic attributes in a browse result:

  • jid - required - The full JabberID of the entity described.
  • type - required - The type from the list above or prefixed with "x-".
  • name - optional - A friendly name that may be used in a user interface.
  • presence - optional - Whether this node is "available" or "unavailable". If this attribute is missing, it should be assumed the JID is "available". This is useful for servers which wish to indicate that particular components (usually transports) are unavailable. Most clients and components will simply remove unavailable nodes from the browse result instead of using this attribute.
  • version - optional - This is another attribute which is useful for servers, especially lists of services (see service/serverlist above). It is a string containing the version from the response of a jabber:iq:version query.

Expressing Relationships

Any category element may contain any other category element as a child, which describes the hierarchical relationship between the two. 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.

For example, this could be the result of browsing to jer@jabber.org:

Example 2. Result of Browsing to a User

<iq type="result" from="jer@jabber.org" id="example1"/>
  <user xmlns="jabber:iq:browse" jid="jer@jabber.org" name="jer">
    <user jid="jer@jabber.org/home" type="client"/>
    <application jid="jer@jabber.org/chess" type="game" name="XChess"/>
    <user jid="jer@jabber.org/palm" type="client"/>


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 precidence.

Namespace Advertising

On top of the browsing framework, a simple form of "feature advertisement" can be built. This allows any entity to advertise which features they support, based on namespaces of those features. The ns element is allowed as a subelement of the category elements. This element contains a single namespace that the entity supports, and multiple ns elements can be included in any category element. For a connected client this might be <ns>jabber:iq:oob</ns>, or for a service <ns>jabber:iq:search</ns>. This list of namespaces should be used to present available options for a user or to automatically locate functionality for an application.

The children of a browse result may pro-actively contain a few <ns> elements (such as the result of the service request to the home server), which advertises the features that particular service supports. This list may not be complete, and the jid should be browsed to for a complete list, it is only for first-pass filtering by simpler clients.

Clients should answer incoming browsing requests to advertise the namespaces they support.

For example:

Example 3. Result of Browsing to a Resource

<iq type="result" from="jer@jabber.org/home" id="example2"/>
  <user xmlns="jabber:iq:browse" jid="jer@jabber.org/home" type="client" name="Home Desktop">


Empty Results

When a JabberID is browsed, the result may contain children or 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 of it it must be browsed to directly.

Supplanting jabber:iq:agents

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 it connected to to retrieve a list of available services. The resulting iq might look like:

Example 4. Result of Browsing to a Server

<iq type="result" from="jabber.org" id="example3"/>
      name="Jabber.org Public Server"
    <service type="icq" jid="icq.jabber.org" name="ICQ Transport">
      name="Private Chatrooms"/>
    <application type="bot" jid="jabber.org/help" name="Assistance Agent"/>


To determine any further details from this list, each child would have to be browsed. The elements within the icq service are only hints for a client for building user interface elements.icq.jabber.org would still need to be browsed to determine any relationships or additional namespaces. This top-level list is the master "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.

Implementation Notes

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 is a similiar model to that of presence.

Future Considerations

jabber:iq:browse 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 JEP will be made. It is, however, possible that no futher changes to jabber:iq:browse itself may be needed.