XEP-0011: Jabber Browsing

1. Introduction
2. JID-Types
3. The jabber:iq:browse Namespace
    3.1. Browsing to a JabberID
    3.2. Generic Attributes for Browse Results
    3.3. Expressing Relationships
    3.4. Namespace Advertising
    3.5. Empty Results
4. Supplanting jabber:iq:agents
5. Implementation Notes
6. Security Considerations
7. IANA Considerations
8. XMPP Registrar Considerations
9. XML Schema
10. Future Considerations

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History

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

3.1 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="browse1">
  <query xmlns="jabber:iq:browse"/>
</iq>
    

3.2 Generic Attributes for Browse Results

The item element has these attributes in a browse result:

• jid [required] -- The full JabberID of the entity described.
• category [optional] -- One of the categories from the list above, or a non-standard category prefixed with the string "x-".
• type [optional] -- One of the official types from the specified category, or a non-standard type prefixed with the string "x-".
• name [optional] -- A friendly name that may be used in a user interface.
• 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).

3.3 Expressing Relationships

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.

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="browse1">
  <query
      xmlns="jabber:iq:browse"
      category="user"
      jid="jer@jabber.org"
      name="jer">
    <item
        category="user"
        jid="jer@jabber.org/foxy"
        type="client"/>
    <item
        category="application"
        jid="jer@jabber.org/chess"
        name="XChess"
        type="game"/>
    <item
        category="user"
        jid="jer@jabber.org/palm"
        type="client"/>
  </query>
</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 precedence.

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.

3.4 Namespace Advertising

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 <ns/> element is allowed as a subelement of the item. This element contains a single namespace that the entity supports, and multiple <ns/> elements can be included in any item. 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 proactively contain a few <ns/> 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.

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

Example 3. Result of Browsing to a Resource

<iq type="result" from="jer@jabber.org/foxy" id="browse2">
  <query
      xmlns="jabber:iq:browse"
      category="user"
      jid="jer@jabber.org/foxy"
      name="laptop"
      type="client">
    <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>
  </query>
</iq>
    

3.5 Empty Results

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.

<iq type="result" from="jabber.org" id="browse3">
  <query
      xmlns="jabber:iq:browse"
      category="service"
      type="jabber"
      jid="jabber.org"
      name="Jabber.org Public Server">
    <ns>jabber:client</ns>
    <ns>jabber:iq:browse</ns>
    <ns>jabber:iq:conference</ns>
    <ns>jabber:iq:time</ns>
    <ns>jabber:iq:version</ns>
    <item
        category="service"
        jid="icq.jabber.org"
        name="ICQ Transport"
        type="icq">
      <ns>jabber:iq:register</ns>
      <ns>jabber:iq:search</ns>
      <ns>jabber:iq:gateway</ns>
    </item>
    <item
      category="conference"
      type="private"
      jid="conference.jabber.org"
      name="Private Chatrooms"/>
    <item
        category="application"
        jid="jabber.org/help"
        name="Assistance Agent"
        type="bot"/>
  </query>
</iq>
  

<?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>
    

Jeremie Miller

Email: jer@jabber.org
JabberID: jer@jabber.org

Julian Missig

Email: julian@jabber.org
JabberID: julian@jabber.org

Thomas Muldowney

Email: temas@jabber.org
JabberID: temas@jabber.org

Copyright

Permissions

Disclaimer of Warranty

Limitation of Liability

IPR Conformance

1. XEP-0030: Service Discovery <http://xmpp.org/extensions/xep-0030.html>.

2. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

3. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://xmpp.org/registrar/>.

Version 1.3 (2009-06-03)

Version 1.2 (2004-11-12)

Version 1.1 (2004-01-06)

Version 1.0 (2002-05-08)

Version 0.4 (2002-04-15)

Version 0.3 (2002-01-16)

Version 0.2 (2002-01-04)

Version 0.1 (2001-01-25)