XEP-0030: Service Discovery

1. Introduction
2. Requirements
3. Discovering Information About a Jabber Entity
    3.1. Basic Protocol
    3.2. Info Nodes
4. Discovering the Items Associated with a Jabber Entity
    4.1. Basic Protocol
    4.2. Items Nodes
    4.3. Node Hierarchies
    4.4. Relationship Between an Entity and its Items
5. Publishing Available Items
6. Implementation Notes
    6.1. Number of Info Requests
    6.2. Number of Items Requests
    6.3. Response Consistency
7. Error Conditions
8. Security Considerations
9. IANA Considerations
10. XMPP Registrar Considerations
    10.1. Protocol Namespaces
    10.2. Registries
       10.2.1. Identity Categories and Types Registry
         10.2.1.1. Process
         10.2.1.2. Initial Submission
       10.2.2. Features Registry
         10.2.2.1. Process
       10.2.3. Well-Known Nodes
         10.2.3.1. Process
    10.3. URI Query Types
11. XML Schemas
    11.1. disco#info
    11.2. disco#items
12. Author Note

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

3.1 Basic Protocol

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

Example 1. Querying for information

<iq type='get'
    from='romeo@montague.net/orchard'
    to='plays.shakespeare.lit'
    id='info1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
      

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-not-implemented/> or <service-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.

Example 2. Result-set for information request

<iq type='result'
    from='plays.shakespeare.lit'
    to='romeo@montague.net/orchard'
    id='info1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        type='text'
        name='Play-Specific Chatrooms'/>
    <identity
        category='directory'
        type='chatroom'
        name='Play-Specific Chatrooms'/>
    <feature var='http://jabber.org/protocol/disco#info'/>
    <feature var='http://jabber.org/protocol/disco#items'/>
    <feature var='http://jabber.org/protocol/muc'/>
    <feature var='jabber:iq:register'/>
    <feature var='jabber:iq:search'/>
    <feature var='jabber:iq:time'/>
    <feature var='jabber:iq:version'/>
  </query>
</iq>
    

If the JID of the specified target entity does not exist, the server or other authoritative entity SHOULD return an <item-not-found/> error, unless doing so would violate the privacy and security considerations specified in XMPP Core and XMPP IM [6] or local privacy and security policies (see also the Security Considerations of this document):

Example 3. Target entity does not exist

<iq type='error'
    from='plays.shakespeare.lit'
    to='romeo@montague.net/orchard'
    id='info1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
  <error type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
      

If privacy and security considerations or policies prevent the server or other authoritative entity from returning an <item-not-found/> error, it SHOULD return a <service-unavailable/> error instead:

Example 4. Service unavailable

<iq type='error'
    from='plays.shakespeare.lit'
    to='romeo@montague.net/orchard'
    id='info1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
  <error type='cancel'>
    <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
      

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

Example 5. Requesting info from a bare JID

<iq type='get'
    from='shakespeare.lit'
    to='juliet@capulet.com'
    id='info2'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
      

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

Example 6. Server replies on behalf of bare JID

<iq type='result'
    from='juliet@capulet.com'
    to='shakespeare.lit'
    id='info2'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity category='account' type='registered'/>
  </query>
</iq>
      

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:

Example 7. Querying a specific conference room

<iq type='get'
    from='juliet@capulet.com/balcony'
    to='balconyscene@plays.shakespeare.lit'
    id='info3'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

<iq type='result'
    from='balconyscene@plays.shakespeare.lit'
    to='juliet@capulet.com/balcony'
    id='info3'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='conference'
        name='A Dark Cave'
        type='text'/>
    <feature var='http://jabber.org/protocol/muc'/>
    <feature var='muc_passwordprotected'/>
    <feature var='muc_hidden'/>
    <feature var='muc_temporary'/>
    <feature var='muc_open'/>
    <feature var='muc_unmoderated'/>
    <feature var='muc_nonanonymous'/>
  </query>
</iq>

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

Example 8. Querying a connected resource for further information

<iq type='get'
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/orchard'
    id='info4'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

<iq type='result'
    from='romeo@montague.net/orchard'
    to='juliet@capulet.com/balcony'
    id='info4'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity
        category='client'
        type='pc'
        name='Gabber'/>
    <feature var='jabber:iq:time'/>
    <feature var='jabber:iq:version'/>
  </query>
</iq>
      

3.2 Info Nodes

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:

Example 9. Querying a specific JID and node combination

<iq type='get'
    from='romeo@montague.net/orchard'
    to='mim.shakespeare.lit'
    id='info3'>
  <query xmlns='http://jabber.org/protocol/disco#info' 
         node='http://jabber.org/protocol/commands'/>
</iq>
      

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

Example 10. JID+node result

<iq type='result'
    from='mim.shakespeare.lit'
    to='romeo@montague.net/orchard'
    id='info3'>
  <query xmlns='http://jabber.org/protocol/disco#info' 
         node='http://jabber.org/protocol/commands'>
    <identity
        category='automation'
        type='command-list'/>
  </query>
</iq>
      

4.1 Basic Protocol

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:

Example 11. Requesting all items

<iq type='get'
    from='romeo@montague.net/orchard'
    to='shakespeare.lit'
    id='items1'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
      

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

Example 12. Result-set for all items

<iq type='result'
    from='shakespeare.lit'
    to='romeo@montague.net/orchard'
    id='items1'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='people.shakespeare.lit'
          name='Directory of Characters'/>
    <item jid='plays.shakespeare.lit'
          name='Play-Specific Chatrooms'/>
    <item jid='mim.shakespeare.lit'
          name='Gateway to Marlowe IM'/>
    <item jid='words.shakespeare.lit'
          name='Shakespearean Lexicon'/>
    <item jid='globe.shakespeare.lit'
          name='Calendar of Performances'/>
    <item jid='headlines.shakespeare.lit'
          name='Latest Shakespearean News'/>
    <item jid='catalog.shakespeare.lit'
          name='Buy Shakespeare Stuff!'/>
    <item jid='en2fr.shakespeare.lit'
          name='French Translation Service'/>
  </query>
</iq>
      

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:

Example 13. Empty result set

<iq type='result'
    from='shakespeare.lit'
    to='romeo@montague.net/orchard'
    id='items1'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
      

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:

Example 14. Requesting items from a bare JID

<iq type='get'
    from='shakespeare.lit'
    to='juliet@capulet.com'
    id='items2'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
      

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

Example 15. Server replies on behalf of bare JID

<iq type='result'
    from='juliet@capulet.com'
    to='shakespeare.lit'
    id='items2'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='juliet@capulet.com/balcony'/>
    <item jid='juliet@capulet.com/chamber'/>
  </query>
</iq>
      

4.2 Items Nodes

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 Flexible Offline Message Retrieval (XEP-0013) [7]), 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 Publish-Subscribe (XEP-0060) [8] 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:

Example 16. Requesting nodes

<iq type='get'
    from='romeo@montague.net/orchard'
    to='catalog.shakespeare.lit'
    id='items2'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
        

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

Example 17. Service returns nodes

<iq type='result'
    from='catalog.shakespeare.lit'
    to='romeo@montague.net/orchard'
    id='items2'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='catalog.shakespeare.lit'
          node='books'
          name='Books by and about Shakespeare'/>
    <item jid='catalog.shakespeare.lit'
          node='clothing'
          name='Wear your literary taste with pride'/>
    <item jid='catalog.shakespeare.lit'
          node='music'
          name='Music from the time of Shakespeare'/>
  </query>
</iq>
      

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.

Example 18. Requesting further nodes

<iq type='get'
    from='romeo@montague.net/orchard'
    to='catalog.shakespeare.lit'
    id='items3'>
  <query xmlns='http://jabber.org/protocol/disco#items' 
         node='music'/>
</iq>
      

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.

Example 19. Service returns further nodes

<iq type='result'
    from='catalog.shakespeare.lit'
    to='romeo@montague.net/orchard'
    id='items3'>
  <query xmlns='http://jabber.org/protocol/disco#items' 
         node='music'>
    <item jid='catalog.shakespeare.lit'
          node='music/A'/>
    <item jid='catalog.shakespeare.lit'
          node='music/B'/>
    <item jid='catalog.shakespeare.lit'
          node='music/C'/>
    <item jid='catalog.shakespeare.lit'
          node='music/D'/>
    .
    .
    .
  </query>
</iq>
      

The requesting entity can then query further if desired:

Example 20. Requesting even more nodes

<iq type='get'
    from='romeo@montague.net/orchard'
    to='catalog.shakespeare.lit'
    id='items4'>
  <query xmlns='http://jabber.org/protocol/disco#items' 
         node='music/D'/>
</iq>
      

Example 21. Service returns even more nodes

<iq type='result'
    from='catalog.shakespeare.lit'
    to='romeo@montague.net/orchard'
    id='items4'>
  <query xmlns='http://jabber.org/protocol/disco#items' 
         node='music/D'>
    <item jid='catalog.shakespeare.lit'
          node='music/D/dowland-firstbooke'
          name='John Dowland - First Booke of Songes or Ayres'/>
    <item jid='catalog.shakespeare.lit'
          node='music/D/dowland-solace'
          name='John Dowland - A Pilgrimes Solace'/>
  </query>
</iq>
      

4.3 Node Hierarchies

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

4.4 Relationship Between an Entity and its Items

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 User Tune (XEP-0118) [9]):

Example 22. User queries entity regarding tunes

<iq from='juliet@capulet.com/chamber'
    id='items4'
    to='romeo@montague.net'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#items' 
         node='http://jabber.org/protocol/tune'/>
</iq>
      

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:

Example 23. Entity returns multiple items

<iq from='romeo@montague.net'
    id='items4'
    to='juliet@capulet.com/chamber'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#items' 
         node='http://jabber.org/protocol/tune'>
    <item jid='pubsub.shakespeare.lit'
          name='Romeo&apos;s CD player'
          node='s623nms9s3bfh8js'/>
    <item jid='pubsub.montague.net'
          node='music/R/Romeo/iPod'/>
    <item jid='tunes.characters.lit'
          node='g8k4kds9sd89djf3'/>
  </query>
</iq>
      

6.1 Number of Info Requests

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 Entity Capabilities (XEP-0115) [10] to determine the capabilities of entities from which they receive presence information and SHOULD NOT send disco#info requests to such entities.

6.2 Number of Items Requests

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 Jabber Search (XEP-0055) [11]; they SHOULD NOT return extremely large result sets via Service Discovery.

6.3 Response Consistency

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.

<iq type='error'
    from='mim.shakespeare.lit'
    to='romeo@montague.net/orchard'
    id='info3'>
  <query xmlns='http://jabber.org/protocol/disco#info' 
         node='http://jabber.org/protocol/commands'/>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

Table 1: Error Conditions

10.1 Protocol Namespaces

The XMPP Registrar [15] includes the 'http://jabber.org/protocol/disco#info' and 'http://jabber.org/protocol/disco#items' namespaces in its registry of protocol namespaces.

10.2 Registries

<category>
  <name>the name of the category (all lower-case)</name>
  <desc>a natural-language description of the category</desc>
  <type>
    <name>the name of the specific type (all lower-case)</name>
    <desc>a natural-language description of the type</desc>
    <doc>the document (e.g., XEP) in which this type is specified</doc>
  </type>
</category>
          

<category>
  <name>hierarchy</name>
  <desc>
    An entity that exists in the context of a 
    service discovery node hierarchy.
  </desc>
  <type>
    <name>branch</name>
    <desc>
      A "container node" for other entities in a 
      service discovery node hierarchy.
    </desc>
    <doc>XEP-0030</doc>
  </type>
  <type>
    <name>leaf</name>
    <desc>
      A "terminal node" in a service discovery 
      node hierarchy.
    </desc>
    <doc>XEP-0030</doc>
  </type>
</category>
          

<var>
  <name>name of feature or namespace</name>
  <desc>a natural-language description of the feature</desc>
  <doc>the document (e.g., XEP) in which this feature is specified</doc>
</var>
          

<node>
  <name>the name of the node</name>
  <desc>a natural-language description of the node</desc>
  <doc>the document (e.g., XEP) in which this node is specified</doc>
</node>
          

10.3 URI Query Types

As authorized by XMPP URI Query Components (XEP-0147) [16], the XMPP Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see <http://xmpp.org/registrar/querytypes.html>).

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

Example 25. Service Discovery Information Request: IRI/URI

xmpp:romeo@montague.net?disco;type=get;request=info
      

Example 26. Service Discovery Information Request: Resulting Stanza

<iq to='romeo@montague.net' type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
      

Example 27. Service Discovery Items Request: IRI/URI

xmpp:romeo@montague.net?disco;type=get;request=items
      

Example 28. Service Discovery Items Request: Resulting Stanza

<iq to='romeo@montague.net' type='get'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
      

The following submission registers the "disco" querytype.

<querytype>
  <name>disco</name>
  <proto>http://jabber.org/protocol/disco</proto>
  <desc>enables interaction for the purpose of service discovery</desc>
  <doc>XEP-0030</doc>
  <keys>
    <key>
      <name>node</name>
      <desc>the (optional) service discovery node</desc>
    </key>
    <key>
      <name>request</name>
      <desc>the service discovery request type</desc>
      <values>
        <value>
	  <name>info</name>
          <desc>a service discovery information (disco#info) request</desc>
        </value>
        <value>
	  <name>items</name>
          <desc>a service discovery items (disco#items) request</desc>
        </value>
      </values>
    </key>
    <key>
      <name>type</name>
      <desc>the IQ type</desc>
      <values>
        <value>
	  <name>get</name>
          <desc>an IQ get</desc>
        </value>
      </values>
    </key>
  </keys>
</querytype>

      

11.1 disco#info

<?xml version='1.0' encoding='UTF-8' ?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/disco#info'
    xmlns='http://jabber.org/protocol/disco#info'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0030: http://www.xmpp.org/extensions/xep-0030.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='query'>
    <xs:complexType>
      <xs:sequence minOccurs='0'>
        <xs:element ref='identity' maxOccurs='unbounded'/>
        <xs:element ref='feature' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='node' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='identity'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='category' type='nonEmptyString' use='required'/>
          <xs:attribute name='name' type='xs:string' use='optional'/>
          <xs:attribute name='type' type='nonEmptyString' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='feature'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='var' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name='nonEmptyString'>
    <xs:restriction base='xs:string'>
      <xs:minLength value='1'/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
      

11.2 disco#items

<?xml version='1.0' encoding='UTF-8' ?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/disco#items'
    xmlns='http://jabber.org/protocol/disco#items'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0030: http://www.xmpp.org/extensions/xep-0030.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='query'>
    <xs:complexType>
      <xs:sequence minOccurs='0'>
        <xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='node' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='item'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='jid' type='fullJIDType' use='required'/>
          <xs:attribute name='name' type='xs:string' use='optional'/>
          <xs:attribute name='node' type='xs:string' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:simpleType name='fullJIDType'>
    <xs:restriction base='xs:string'>
      <xs:minLength value='8'/>
      <xs:maxLength value='3071'/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
      

Joe Hildebrand

Email: jhildebr@cisco.com
JabberID: hildjj@jabber.org

Peter Millard

See Author Note

Ryan Eatmon

Email: reatmon@jabber.org
JabberID: reatmon@jabber.org

Peter Saint-Andre

Email: peter@andyet.net
JabberID: stpeter@stpeter.im
URI: https://stpeter.im/

Copyright

Permissions

Disclaimer of Warranty

Limitation of Liability

IPR Conformance

1. RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core <http://tools.ietf.org/html/rfc6120>.

2. XEP-0011: Jabber Browsing <http://xmpp.org/extensions/xep-0011.html>.

3. XEP-0094: Agent Information <http://xmpp.org/extensions/xep-0094.html>.

4. XEP-0134: XMPP Design Guidelines <http://xmpp.org/extensions/xep-0134.html>.

5. SOAP <http://www.w3.org/TR/SOAP/>.

6. RFC 6121: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/rfc6121>.

7. XEP-0013: Flexible Offline Message Retrieval <http://xmpp.org/extensions/xep-0013.html>.

8. XEP-0060: Publish-Subscribe <http://xmpp.org/extensions/xep-0060.html>.

9. XEP-0118: User Tune <http://xmpp.org/extensions/xep-0118.html>.

10. XEP-0115: Entity Capabilities <http://xmpp.org/extensions/xep-0115.html>.

11. XEP-0055: Jabber Search <http://xmpp.org/extensions/xep-0055.html>.

12. XEP-0086: Error Condition Mappings <http://xmpp.org/extensions/xep-0086.html>.

13. However, the server MAY return items other than available resources (if any).

14. 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/>.

15. 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/>.

16. XEP-0147: XMPP URI Query Components <http://xmpp.org/extensions/xep-0147.html>.

Version 2.5rc1 (2015-09-22)

Version 2.4 (2008-06-06)

Version 2.3 (2007-02-15)

Version 2.2 (2006-01-24)

Version 2.1 (2005-03-03)

Version 2.0 (2004-07-20)

Version 1.10 (2004-06-29)

Version 1.9 (2004-05-27)

Version 1.8 (2004-05-21)

Version 1.7 (2004-05-13)

Version 1.6 (2004-05-11)

Version 1.5 (2004-05-10)

Version 1.4 (2004-05-07)

Version 1.3 (2004-04-23)

Version 1.2 (2004-04-20)

Version 1.1 (2004-03-15)

Version 1.0 (2003-04-21)

Version 0.13 (2003-02-25)

Version 0.12 (2003-02-06)

Version 0.11 (2002-12-17)

Version 0.10 (2002-11-21)

Version 0.9 (2002-11-07)

Version 0.8 (2002-11-01)

Version 0.7 (2002-10-28)

Version 0.6 (2002-10-27)

Version 0.5 (2002-10-15)

Version 0.4 (2002-07-16)

Version 0.3 (2002-05-30)

Version 0.2 (2002-05-05)

Version 0.1 (2002-05-03)