<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>
</ol>
<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 (the 'to' address is REQUIRED and MUST contain a valid JID; 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>
<examplecaption='Querying for information'><![CDATA[
<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.) Each <identity/> element MUST possess '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. Each <feature/> element MUST possess a 'var' attribute whose value is a protocol namespace or other feature offered by the entity. 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'><![CDATA[
<p>A query sent to an associated entity may result in different or more detailed information. One example is sending a query to a particular conference room rather than the parent conference service:</p>
<examplecaption='Querying a specific conference room'><![CDATA[
<p>A disco#info query MAY also be directed to a specific node identifier associated with a JID, although the primary use of nodes is as <linkurl='#items-nodes'>Items Nodes</link> rather than as info nodes:</p>
<examplecaption='Querying a specific JID and node combination'><![CDATA[
<p>If the request included a 'node' attribute, the response SHOULD mirror the specified 'node' attribute to ensure coherence between the request and the response.</p>
<p>In order for the requesting entity to discover the items associated with a Jabber Entity, it MUST send an IQ stanza of type "get" to the target entity, containing an empty <query/> element qualified by the 'http://jabber.org/protocol/disco#items' namespace:</p>
<p>The target entity then MUST either return its list of publicly-available items, or return an error. The list of items MUST be provided in an IQ stanza of type "result", with each item specified by means of an <item/> child of a <query/> element qualified by the 'http://jabber.org/protocol/disco#items' namespace (the <item/> child MUST possess a 'jid' attribute specifying the JID of the item and MAY possess a 'name' attribute specifying a natural-language name for the item):</p>
<examplecaption='Result-set for all items'><![CDATA[
<p>The <item/> element MUST NOT contain XML character data and SHOULD be empty; while it MAY contain XML data in another namespace, such data MUST be ignored if an implementation does not understand it.</p>
<p>If there are no items associated with an entity (or if those items are not publicly available), the target entity MUST return an empty query element to the requesting entity:</p>
<p>As with disco#info requests, when an entity sends a disco#items request to a bare JID (<account@domain.tld>) hosted by a server, the server itself MUST reply on behalf of the hosted account. 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#items request sent to a bare JID with no node, if access is not denied the server SHOULD return the associated items including connected or available resources as appropriate:</p>
<examplecaption='Requesting items from a bare JID'><![CDATA[
<p>It is possible that an item associated with an entity will not be addressable as a JID; examples might include offline messages stored in an inbox (see &xep0013;), entries in a Jabber-enabled weblog, XML-RPC services associated with a client or component, items available in an online trading system (e.g., a catalog or auction), news postings located at an NNTP gateway, and topics hosted by a &xep0060; component. In order to handle such items, the <item/> element MAY possess an OPTIONAL 'node' attribute that supplements the REQUIRED 'jid' attribute.</p>
<p>The value of the node attribute may or may not have semantic meaning; from the perspective of Service Discovery, a node is merely something that is associated with an entity. In order to discover more about the node, the requesting entity MUST query the entity's JID while specifying the node. If the value of the 'node' attribute has semantic meaning, that meaning is provided by the "using protocol" or application, not by the Service Discovery protocol. A node attribute SHOULD NOT be included unless it is necessary to provide or discover information about an entity that cannot be directly addressed as a JID (i.e., if the associated item can be addressed as a JID, do not include a node). The value of the 'node' attribute MUST NOT be null.</p>
<p>If there are items associated with the target entity but they are not addressable as JIDs, the service SHOULD then return a list of nodes (where each <item/> element MUST possess a 'jid' attribute, SHOULD possess a 'node' attribute, and MAY possess a 'name' attribute):</p>
<p>There may be futher nodes associated with the "first-level" nodes returned in the above query (e.g., the nodes may be categories that have associated items). The requesting entity can query a node further by sending a request to the JID and specifying the node of interest in the query.</p>
<examplecaption='Requesting further nodes'><![CDATA[
<p>The service then returns the further nodes associated with the "parent" node. In the following example, the service itself enforces an alphabetically-ordered hierarchical structure on the nodes that are returned, but such a structure is a matter of implementation rather than protocol.</p>
<examplecaption='Service returns further nodes'><![CDATA[
<p>The foregoing examples show a hierarchy of nodes, in which some nodes are branches (i.e., contain further nodes) and some nodes are leaves (i.e., do not contain further nodes). The "hierarchy" category SHOULD be used to identify such nodes, where the "branch" and "leaf" types are exhaustive of the types within this category.</p>
<p>If the hierarchy category is used, every node in the hierarchy MUST be identified as either a branch or a leaf; however, since a node MAY have multiple identities, any given node MAY also possess an identity other than "hierarchy/branch" or "hierarchy/leaf".</p>
<p>Therefore, a disco#info request to the "music/D" node shown above would yield <identity category='hierarchy' type='branch'/> while a disco#info request to the "music/D/dowland-firstbooke" node would yield <identity category='hierarchy' type='leaf'/> (and each node could yield additional identities as appropriate).</p>
</section2>
<section2topic='Relationship Between an Entity and its Items'anchor='items-relationship'>
<p>This section explains in greater detail the relationship between an entity and its associated items.</p>
<p>In general, the items returned by an entity in a disco#items result MUST be items over which the entity has some relationship of ownership -- either direct control over the item itself (e.g., <cite>Publish-Subscribe</cite> nodes owned by the entity) or at least the ability to provide or vouch for the item in a canonical way on the Jabber network (e.g., groupchat rooms directly hosted by a multi-user chat service or IRC channels to which a gateway provides access).</p>
<p>Such a relationship does not constrain the relationship between the owning entity's address and the address of the associated entity. In particular, any of the following scenarios is perfectly acceptable:</p>
<ol>
<li><p>Upon querying an entity (JID1) for items, one receives a list of items that can be addressed as JIDs; each associated item has its own JID, but no such JID equals JID1.</p></li>
<li><p>Upon querying an entity (JID1) for items, one receives a list of items that cannot be addressed as JIDs; each associated item has its own JID+node, where each JID equals JID1 and each NodeID is unique.</p></li>
<li><p>Upon querying an entity (JID1+NodeID1) for items, one receives a list of items that can be addressed as JIDs; each associated item has its own JID, but no such JID equals JID1.</p></li>
<li><p>Upon querying an entity (JID1+NodeID1) for items, one receives a list of items that cannot be addressed as JIDs; each associated item has its own JID+node, but no such JID+node equals JID1+NodeID1 and each NodeID is unique in the context of the associated JID.</p></li>
</ol>
<p>In addition, the results MAY also be mixed, so that a query to a JID or a JID+node could yield both (1) items that are addressed as JIDs and (2) items that are addressed as JID+node combinations.</p>
<p>Consider the case of an entity that owns multiple publish-subscribe nodes -- for example, a person who owns one such node for each of his music players. The following examples show what the disco#items query and result might look like (using the protocol defined in &xep0118;):</p>
<p>The queried entity now returns a list of publish-subscribe nodes over which it has control, each of which is hosted on a different pubsub service:</p>
<p>The server handling rules defined in <cite>XMPP IM</cite> require that the server itself reply on behalf of the user if the 'to' attribute of an IQ get or set is of the form <user@host>. This functionality is currently employed so that the user can "publish" information (e.g., vCard information as specified in &xep0054;) in a way that makes it possible for other entities to retrieve that information even if the user is unavailable. The service discovery specification defined herein builds on that notion by enabling a user to publish some of its service discovery information to the server, which shall store that information in persistent storage and return that information when other entities request it from the user's "bare JID" (user@host), either alone or in combination with a particular node.</p>
<p>Implementations of service discovery that are built into instant messaging servers SHOULD allow users to publish items in this fashion, although they are not required to do so in order to conform to the service discovery specification. In order to discover whether his or her server supports this publish functionality, the user SHOULD send a disco#info request to his or her server:</p>
<examplecaption="User sends disco#info request to server"><![CDATA[
<p>If the server supports service discovery publishing and the server wishes to disclose that fact to the user, it MUST include a feature of 'http://jabber.org/protocol/disco#publish' in its response.</p>
<examplecaption="Server responds with identity and feature information"><![CDATA[
<p>In order to publish items, an entity uses an IQ-set transaction to its server, which is responsible for responding to requests on behalf of that entity. Each <item/> child element of the parent query MUST possess the following attributes:</p>
<ul>
<li><strong>action</strong> -- specifies the action to be taken for the item</li>
<li><strong>jid</strong> -- specifies the Jabber ID of the item "owner" or location</li>
</ul>
<p>The <item/> element MAY also possess the following attributes:</p>
<ul>
<li><strong>name</strong> -- specifies a natural-language name for the item.</li>
<li><strong>node</strong> -- specifies the particular node associated with the JID of the item "owner" or location</li>
</ul>
<p>The allowable values for the 'action' attribute are "update" and "remove"). If the action is "update", the server MUST either create a new entry (if the node and jid combination does not already exist) or overwrite an existing entry. If the action is "remove", the item MUST be removed from persistent storage.</p>
<p>The following example shows a user publishing a list of his biological children to a well-known (but fictitious) service discovery node.</p>
<examplecaption="Server responds with success"><![CDATA[
<iqid='publish1'
to='kinglear@shakespeare.lit'
type='result'/>
]]></example>
<p>Subsequent queries to "jid='kinglear@shakespeare.lit'" and "node='jabber:iq:kids'" will yield the list shown above (absent the 'action' attributes).</p>
<p>If the server or service does not support persistent storage, it MUST respond to IQ-set requests with a &feature; error.</p>
<examplecaption='Persistent storage is not available'><