This document has been placed in the public domain.
|Updated to JEP format and revised description.|
|Initial draft version.|
Jabber Browsing provides a better way for describing the relationship between JabberIDs.
Table of Contents
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
|conference/||Nodes of this category provide conference rooms.|
|list||Mailing list style conference|
|private||Private dynamically-generated conference rooms|
|public||Public permanent conference rooms|
|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.|
|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)|
|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.|
|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 namespace containing the Jabber Browsing data is jabber:iq:browse. Every category listed above is an element within this namespace.
The common way to browse to a JabberID using IQ is:
Example 1. Browsing to a JabberID
<iq type="get" to="firstname.lastname@example.org" id="example1"/> <item xmlns="jabber:iq:browse"/> </iq>
Every category element has these generic attributes in a browse result:
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 email@example.com:
Example 2. Result of Browsing to a User
<iq type="result" from="firstname.lastname@example.org" id="example1"/> <user xmlns="jabber:iq:browse" jid="email@example.com" name="jer"> <user jid="firstname.lastname@example.org/home" type="client"/> <application jid="email@example.com/chess" type="game" name="XChess"/> <user jid="firstname.lastname@example.org/palm" type="client"/> </user> </iq>
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.
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.
Example 3. Result of Browsing to a Resource
<iq type="result" from="email@example.com/home" id="example2"/> <user xmlns="jabber:iq:browse" jid="firstname.lastname@example.org/home" type="client" name="Home Desktop"> <ns>jabber:client</ns> <ns>jabber:iq:browse</ns> <ns>jabber:iq:conference</ns> <ns>jabber:iq:time</ns> <ns>jabber:iq:version</ns> <ns>jabber:x:roster</ns> <ns>jabber:x:signed</ns> <ns>jabber:x:encrypted</ns> <ns>jabber:x:conference</ns> </user> </iq>
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 email@example.com 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.
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"/> <service type="jabber" jid="jabber.org" name="Jabber.org Public Server" > <service type="icq" jid="icq.jabber.org" name="ICQ Transport"> <ns>jabber:iq:register</ns> <ns>jabber:iq:search</ns> <ns>jabber:iq:gateway</ns> </service> <conference type="private" jid="conference.jabber.org" name="Private Chatrooms"/> <application type="bot" jid="jabber.org/help" name="Assistance Agent"/> </service> </iq>
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.
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.
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.