<abstract>This specification defines an XMPP protocol extension for discovering information about other XMPP entities. Two kinds of information can be discovered: (1) the identity and capabilities of an entity, including the protocols and features it supports; and (2) the items associated with an entity, such as the list of rooms hosted at a multi-user chat service.</abstract>
<remark><p>Defined security considerations; changed extended presence example to use a fictitious protocol; further specified publish feature; defined registry submissions.</p></remark>
<remark><p>Further clarified item-publication protocol; moved some feature negotiation text to XEP-0020; added information about registry of well-known service discovery nodes; added implementation notes regarding tree-walking and large result sets; incorporated additional Call for Experience suggestions.</p></remark>
<remark><p>Described requirements, syntax, and use cases in a more formal manner; corrected several errors in the examples and schemas; defined XMPP Registrar procedures; added a number of references; specified XMPP error handling.</p></remark>
<remark><p>Added support for the 'node' attribute per discussion on the Standards list in order to support items that are not JID-addressable.</p></remark>
<remark><p>Removed the max, start, and total attributes for item queries (this will be handled by a generic paging protocol); added "http://jabber.org/protocol/feature-neg" namespace as a feature to signal negotiability regarding one or more features.</p></remark>
<remark><p>Added the 'category' attribute to the <feature/> element; added security, IANA, and XMPP Registrar considerations; added a number of examples.</p></remark>
<p>The ability to discover information about entities on the Jabber network is extremely valuable. Such information might include features offered or protocols supported by the entity, the entity's type or identity, and additional entities that are associated with the original entity in some way (often thought of as "children" of the "parent" entity). While mechanisms for doing so are not defined in &xmppcore;, several protocols have been used in the past within the Jabber community for service discovery, specifically &xep0011; and &xep0094;. However, those protocols are perceived to be inadequate for several reasons:</p>
<li><p>Neither Jabber Browsing nor Agent Information is easily extensible. For example, the categories and subcategories listed for JID-Types in XEP-0011 are explicitly defined as the only official categories, and any additions to the list of JID-Types would require a modification to XEP-0011. While the Jabber Browsing specification does allow for the use of unofficial categories and types prefixed with the string 'x-', this introduces migration issues. This lack of flexibility violates one of the Jabber community's core &xep0134;.</p></li>
<li><p>In Agent Information, there is no way to advertise supported features. While Jabber Browsing includes such a mechanism, the only way to express the availability of a feature is to advertise a supported protocol namespace. Yet some features may not be uniquely associated with a protocol namespace, which are one implementation of features but not the only one.</p></li>
<li><p>A Jabber Browsing result returns a combination of (1) namespaces supported by a Jabber Entity, (2) items associated with a Jabber Entity, and (3) namespaces supported by the associated items. This approach mixes information levels and requires parents to know everything about child nodes, thereby introducing significant confusion.</p></li>
<li><p>In both Jabber Browsing and Agent Information, items must be addressable as JIDs; however, this may not be possible in some applications.</p></li>
<p>This document addresses the perceived weaknesses of both the Jabber Browsing and Agent Information protocols. The result is a standards-track protocol for service discovery (often abbreviated to "disco", as is familiar in protocols such as &w3soap;).</p>
<li>the features it offers and protocols it supports</li>
<li>any additional items associated with the entity, whether or not they are addressable as JIDs</li>
</ol>
<p>All three MUST be supported, but the first two kinds of information relate to the entity itself whereas the third kind of information relates to items associated with the entity itself; therefore two different query types are needed.</p>
</li>
<li><p>Discovering information about a child item MUST be accomplished by sending a separate discovery request to that item, not to the parent entity. (One result of this is that discovering complete information about an entire tree will require multiple request/response pairs in order to "walk the tree".)</p></li>
<li><p>The lists of identities and features MUST be flexible.</p></li>
<li><p>The protocol itself MUST be extensible.</p></li>
</ul>
</section1>
<section1topic='Discovering Information About a Jabber Entity'anchor='info'>
<p>A requesting entity may want to discover information about another entity on the network. The information desired generally is of two kinds:</p>
<ol>
<li><p><strong>The target entity's identity.</strong> In disco, an entity's identity is broken down into its category (server, client, gateway, directory, etc.) and its particular type within that category (IM server, phone vs. handheld client, MSN gateway vs. AIM gateway, user directory vs. chatroom directory, etc.). This information helps requesting entities to determine the group or "bucket" of services into which the entity is most appropriately placed (e.g., perhaps the entity is shown in a GUI with an appropriate icon). An entity MAY have multiple identities. When multiple identity elements are provided, the name attributes for each identity element SHOULD have the same value.</p>
</li>
<li><p><strong>The features offered and protocols supported by the target entity.</strong> This information helps requesting entities determine what actions are possible with regard to this entity (registration, search, join, etc.), what protocols the entity supports, and specific feature types of interest, if any (e.g., for the purpose of feature negotiation).</p></li>
<p>In order to discover such information, the requesting entity MUST send an IQ stanza of type "get", containing an empty <query/> element qualified by the 'http://jabber.org/protocol/disco#info' namespace, to the JID of the target entity (a 'node' attribute on the &QUERY; element is OPTIONAL as described in the <linkurl="#info-nodes">Info Nodes</link> and <linkurl="#items-nodes">Items Nodes</link> section of this document):</p>
<p>The target entity then MUST either return an IQ result, or return an error (see the <linkurl="#errors">Error Conditions</link> section of this document). The result MUST contain a <query/> element qualified by the 'http://jabber.org/protocol/disco#info' namespace, which in turn contains one or more <identity/> elements and one or more <feature/> elements. (Note: Every entity MUST have at least one identity, and every entity MUST support at least the 'http://jabber.org/protocol/disco#info' feature; however, an entity is not required to return a result and MAY return an error, most likely &feature; or &unavailable;, although other error conditions may be appropriate.)</p>
<p>Each <identity/> element MUST possess the 'category' and 'type' attributes specifying the category and type for the entity, and MAY possess a 'name' attribute specifying a natural-language name for the entity; the <identity/> element MAY also possess a standard 'xml:lang' attribute, which enables the entity to return localized results if desired (i.e., the <query/> element MAY include multiple <identity/> elements with the same category+type but with different 'xml:lang' values, however the <query/> element MUST NOT include multiple <identity/> elements with the same category+type+xml:lang but with different 'name' values).</p>
<p>Each <feature/> element MUST possess a 'var' attribute whose value is a protocol namespace or other feature offered by the entity.</p>
<p>Preferably, both the category/type values and the feature values will be registered in a public registry, as described in the <linkurl="#registrar">XMPP Registrar Considerations</link> section of this document.</p>
<p>If the JID of the specified target entity does not exist, the server or other authoritative entity SHOULD return an ¬found; error, unless doing so would violate the privacy and security considerations specified in <cite>XMPP Core</cite> and &xmppim; or local privacy and security policies (see also the <linkurl='#security'>Security Considerations</link> of this document):</p>
<p>If privacy and security considerations or policies prevent the server or other authoritative entity from returning an ¬found; error, it SHOULD return a &unavailable; error instead:</p>
<p>When an entity sends a disco#info request to a bare JID (<account@domain.tld>) hosted by a server, the server itself MUST reply on behalf of the hosted account, either with an IQ-error or an IQ-result. For important rules regarding access to this functionality, see the <linkurl='#security'>Security Considerations</link> section of this document. In particular, in response to a disco#info request sent to a bare JID with no node, if access is not denied the server SHOULD return an IQ-result for the bare JID, in which the primary identity SHOULD have a category of "account" with an appropriate type as specified in the Service Discovery Identities registry (most likely, a type of "registered"). Note: This enables authorized or trusted entities to discover whether the account exists and its account type (e.g., in IM systems to determine the existence of an account before adding it to a contact's roster).</p>
<examplecaption='Requesting info from a bare JID'><