A requesting entity may want to discover information about another entity on the network. The information desired generally is of two kinds:

1. The target entity's identity. 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.

2. The features offered and protocols supported by the target entity. 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).

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 Info Nodes and Items Nodes section of this document):

The target entity then MUST either return an IQ result, or return an error (see the Error Conditions 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 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).

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 XMPP Registrar Considerations section of this document.

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 XMPP Core and &xmppim; or local privacy and security policies (see also the Security Considerations of this document):

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:

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 Security Considerations 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).

Here we assume that shakespeare.lit is trusted by capulet.com and that the account <juliet@capulet.com> is a registered account:

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:

Another example of this is sending a query to a specific connected resource for an IM user:

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 Items Nodes rather than as info nodes:

If the request included a 'node' attribute, the response MUST mirror the specified 'node' attribute to ensure coherence between the request and the response.

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:

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):

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.

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:

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 Security Considerations 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:

Here we assume that shakespeare.lit is trusted by capulet.com and that the account <juliet@capulet.com> has two available resources:

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.

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.

In the following example, a user requests all available items from an online catalog service:

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):

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.

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.

The requesting entity can then query further if desired:

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.

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

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

This section explains in greater detail the relationship between an entity and its associated items.

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., Publish-Subscribe 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).

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:

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

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

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

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

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.

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;):

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:

When the requesting application is a client, it may want to retrieve service discovery information about all of a user's contacts after retrieving the user's roster and receiving presence from contacts in the user's roster (e.g., to show capabilities). Unfortunately, a user's roster can be quite large, resulting in sending a large number of outbound disco#info requests and receiving a large number of inbound disco#info responses upon login. Because this "disco flood" is undesirable for reasons of scalability and bandwidth usage, client applications SHOULD use &xep0115; to determine the capabilities of entities from which they receive presence information and SHOULD NOT send disco#info requests to such entities.

In order to retrieve full information about an entity and its associated items, the requesting application needs to "walk the tree" of items. Naturally, this can result in a large number of requests and responses. The requesting application SHOULD NOT send follow-up requests to all items associated with an entity if the list of such items is long (e.g., more than twenty items). Entities that will routinely host a large number of items (e.g., IRC gateways or NNTP services) SHOULD structure nodes into hierarchies and/or provide more robust searching capabilities, for example via &xep0055;; they SHOULD NOT return extremely large result sets via Service Discovery.

This document recommends but does not require that a responding entity must return the same results in response to the same request from different requesting entities (e.g., an entity could return a different list of items or features based on the degree to which it trusts the requesting entity, or based on the known capabilities of the requesting entity). However, the responding entity SHOULD return the same <identity/> element (category+type) to all disco#info requests sent to the same JID+node combination.

The ®ISTRAR; includes the 'http://jabber.org/protocol/disco#info' and 'http://jabber.org/protocol/disco#items' namespaces in its registry of protocol namespaces.

As authorized by &xep0147;, the XMPP Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).

The "disco" querytype is defined herein for service discovery interactions, with three keys: (1) "node" (the optional node to query), (2) "request" (with values of "info" to retrieve service discovery information and "items" to retrieve service discovery items), and (3) "type" (with values of "get" for IQ-gets and "set" for IQ-sets).

The following submission registers the "disco" querytype.