%ents; ]>
Service Discovery 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. &LEGALNOTICE; 0030 Final Standards Track Standards XMPP Core XEP-0011 XEP-0094 disco disco#info http://www.xmpp.org/schemas/disco-info.xsd disco#items http://www.xmpp.org/schemas/disco-items.xsd &hildjj; &pgmillard; &reatmon; &stpeter; 2.5rc1 2015-09-22 editor(mam)

Errata submitted to standards@ regarding subscriptions and returned items.

Clarify that feature elements must be childless to make the text match the schema.

2.4 2008-06-06 psa

Per Council consensus, removed disco-publish feature (implementations should use publish-subscribe instead).

2.3 2007-02-15 psa

Added implementation note regarding Entity Capabilities.

2.2 2006-01-24 psa

Further specified and clarified security considerations relating to server handling of requests sent to bare JIDs.

2.1 2005-03-03 psa

Added paragraph to implementation notes about server handling of requests sent to bare JIDs.

2.0 2004-07-20 psa

Per a vote of the Jabber Council, advanced status to Final.

1.10 2004-06-29 psa/jjh

Defined security considerations; changed extended presence example to use a fictitious protocol; further specified publish feature; defined registry submissions.

1.9 2004-05-27 psa

Clarified error conditions.

1.8 2004-05-21 psa

Moved remaining feature negotiation text to XEP-0020.

1.7 2004-05-13 psa

Added implementation note regarding flexibility of feature and item results; final editorial cleanup.

1.6 2004-05-11 psa

Corrected examples of publishing available items; further clarified nature of node hierarchies.

1.5 2004-05-10 psa

Added clarifying note about node hierarchies.

1.4 2004-05-07 psa

Clarified usage of "directory"; added section defining the relationship between an entity and its associated items.

1.3 2004-04-23 psa

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.

1.2 2004-04-20 psa

Editorial cleanup; incorporated some Call for Experience suggestions.

1.1 2004-03-15 psa

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.

1.0 2003-04-21 psa

Per a vote of the Jabber Council, advanced status to Draft; also added XML schemas.

0.13 2003-02-25 pgm

Added remarks about empty node attributes; described semantics regarding multiple identity elements.

0.12 2003-02-06 pgm

Added support for IQ-set; added example for disco#info to a specific node.

0.11 2002-12-17 psa

Added support for the 'node' attribute per discussion on the Standards list in order to support items that are not JID-addressable.

0.10 2002-11-21 psa

Changed <feature type='foo'/> to <feature var='foo'/> to track changes in feature negotiation (XEP-0020); added initial registry parameters.

0.9 2002-11-07 psa

Added support for empty result sets in disco#item.

0.8 2002-11-01 psa

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.

0.7 2002-10-28 psa

Cleaned up the feature text and examples.

0.6 2002-10-27 psa

Added the 'category' attribute to the <feature/> element; added security, IANA, and XMPP Registrar considerations; added a number of examples.

0.5 2002-10-15 psa

Total overhaul and simplification.

0.4 2002-07-16 psa

Major additions and fixes, many more examples.

0.3 2002-05-30 psa

Re-organized around use cases, made some minor fixes.

0.2 2002-05-05 psa

Incorporated comments from co-authors and added notes.

0.1 2002-05-03 psa

Initial draft.

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:

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

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

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

  4. In both Jabber Browsing and Agent Information, items must be addressable as JIDs; however, this may not be possible in some applications.

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

The authors have designed the service discovery protocol with the following requirements in mind:

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, and MUST NOT have any children.

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:

]]>

This feature has been removed in favor of the XMPP publish-subscribe technology defined in XEP-0060.

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.

If a specific entity (JID or JID+node) does not support the disco namespace, refuses to return disco results to the specific requesting entity, or refuses to return disco results to any requesting entity, it SHOULD return an appropriate error message (such as &unavailable;, &forbidden;, or ¬allowed;, respectively). One example is shown below.

]]>

Other error conditions may be appropriate depending on the application.

The following table summarizes the common error conditions that can have special meaning in the context of Service Discovery (for information regarding error condition syntax and semantics, see &xep0086;).

Condition Cause
¬found; The JID or JID+NodeID of the specified target entity does not exist and that fact can be divulged in accordance with privacy and security considerations and policies.
&unavailable; The target entity does not support this protocol, or the specified target entity does not exist but that fact cannot be divulged because of privacy and security considerations.

The other error conditions specified in XMPP Core MAY be returned as well (&forbidden;, ¬allowed;, ¬authorized;, etc.), including application-specific conditions.

As noted above, if an entity has no associated items, it MUST return an empty &QUERY; element (rather than an error) in response to a disco#items request.

Certain attacks may be made easier when an entity discloses (via disco#info responses) that it supports particular protocols or features; however, in general, service discovery introduces no new vulnerabilities, since a malicious entity could discover that the responding entity supports such protocols and features by sending requests specific to those protocols rather than by sending service discovery requests.

A responding entity is under no obligation to return the identical service discovery response when replying to service discovery requests received from different requesting entities, and MAY perform authorization checks before responding in order to determine how (or whether) to respond.

A server MUST carefully control access to any functionality that would enable directory harvesting attacks or that would leak information about connected or available resources; this functionality consists of the server's replies to disco#info and disco#items requests sent to bare JIDs (addresses of the form account@domain.tld) hosted on the server, since the server responds to such requests on behalf of the account. The following rules apply to the handling of service discovery requests sent to bare JIDs:

  1. In response to a disco#info request, the server MUST return a &unavailable; error if one of the following is true:

    1. The target entity does not exist (no matter if the request specifies a node or not).
    2. The requesting entity is not authorized to receive presence from the target entity (i.e., via the target having a presence subscription to the requesting entity of type "both" or "from") or is not otherwise trusted (e.g., another server in a trusted network).
  2. In response to a disco#items request, the server MUST return an empty result set if:

    1. The target entity does not exist (no matter if the request specifies a node or not).
    2. The request did not specify a node, the only items are available resources (as defined in RFC 3921), and the requesting entity is not authorized to receive presence from the target entity (i.e., via the target having a presence subscription to the requesting entity of type "both" or "from") or is not otherwise trusted (e.g., another server in a trusted network). However, the server MAY return items other than available resources (if any).

This document requires no interaction with &IANA;.

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

The XMPP Registrar maintains a registry of values for the 'category' and 'type' attributes of the <identity/> element in the 'http://jabber.org/protocol/disco#info' namespace; see &DISCOCATEGORIES;.

®PROCESS; the name of the category (all lower-case) a natural-language description of the category the name of the specific type (all lower-case) a natural-language description of the type the document (e.g., XEP) in which this type is specified ]]>

The registrant may register more than one category at a time, each contained in a separate <category/> element. The registrant may also register more than one type at a time, each contained in a separate <type/> child element. Registrations of new types within an existing category must include the full XML snippet but should not include the category description (only the name).

This document defines a "hierarchy" category that contains two and only two types: "branch" and "leaf"; the associated registry submission is as follows:

hierarchy An entity that exists in the context of a service discovery node hierarchy. branch A "container node" for other entities in a service discovery node hierarchy. XEP-0030 leaf A "terminal node" in a service discovery node hierarchy. XEP-0030 ]]>

The XMPP Registrar maintains a registry of features for use as values of the 'var' attribute of the <feature/> element in the 'http://jabber.org/protocol/disco#info' namespace; see &DISCOFEATURES;.

®PROCESS; name of feature or namespace a natural-language description of the feature the document (e.g., XEP) in which this feature is specified ]]>

The registrant may register more than one feature at a time, each contained in a separate <feature/> element.

A "using protocol" may specify one or more service discovery nodes that have a special and well-defined meaning in the context of that protocol. For the purpose of reserving these node names globally across all Jabber protocols, the XMPP Registrar maintains a registry of well-known service discovery nodes at &NODES;.

®PROCESS; the name of the node a natural-language description of the node the document (e.g., XEP) in which this node is specified ]]>

The registrant may register more than one node at a time, each contained in a separate <node/> element.

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.

disco http://jabber.org/protocol/disco enables interaction for the purpose of service discovery XEP-0030 node the (optional) service discovery node request the service discovery request type info a service discovery information (disco#info) request items a service discovery items (disco#items) request type the IQ type get an IQ get ]]>
The protocol documented by this schema is defined in XEP-0030: http://www.xmpp.org/extensions/xep-0030.html ]]> The protocol documented by this schema is defined in XEP-0030: http://www.xmpp.org/extensions/xep-0030.html ]]>

Peter Millard, a co-author of this specification from version 0.1 through version 2.2, died on April 26, 2006.