This JEP specifies best practices for including extended information in Service Discovery results.
NOTICE: This JEP is currently within Last Call or under consideration by the Jabber Council for advancement to the next stage in the JSF standards process. For further details, visit <http://www.jabber.org/council/queue.php>.
Status: Proposed
Type: Informational
Number: 0128
Version: 0.2
Last Updated: 2004-03-15
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, JEP-0004, JEP-0030, JEP-0068
Supersedes: None
Superseded By: None
Short Name: N/A
Email: stpeter@jabber.org
JID: stpeter@jabber.org
This Jabber Enhancement Proposal is copyright 1999 - 2004 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.php>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core and XMPP IM specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocols defined in this JEP have been developed outside the Internet Standards Process and are to be understood as extensions to XMPP rather than as an evolution, development, or modification of XMPP itself.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Developers periodically wonder why Service Discovery [1] does not include more bits of information. For example, why does the <identity/> element not include a 'description' attribute, and can we add one now? The answer is: well, it just doesn't, and at this point it's too late to make further changes (since JEP-0030 is Final). So the best approach is to specify a well-defined extension mechanism.
Let us consider an example. A Multi-User Chat [2] room might want to include additional information in its service discovery results, such as the full room description, the current discussion topic (room subject), the number of occupants in the room, and the JID of the room owner.
Adding one new attribute to the service discovery schema (even if that were an option) would not solve the problem, since a MUC service might want to provide certain bits of information, whereas a Publish-Subscribe [3] service might want to provide other bits.
A better solution would be to include extended information qualified by a namespace that provides a way to flexibly define structured data formats. Thankfully, we already possess such a protocol: Data Forms [4]. In addition, we possess a way to define common fields used in data forms: Field Standardization for Data Forms [5]. Using these building blocks, we can define some best practices for extending service discovery results.
If an entity desires to provide extended information about itself in an IQ results stanza within the context of the Service Discovery protocol, it SHOULD do so by including each bit of information as the XML character data of the <value/> child of a distinct <field/> element, with the entire set of fields contained within an <x/> element of type "result" qualified by the 'jabber:x:data' namespace; this <x/> element SHOULD be a child of the <query/> element qualified by the 'http://jabber.org/protocol/disco#info' namespace. Thus the IQ result SHOULD be of the following form:
<iq type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<x type='result' xmlns='jabber:x:data'>
<field var='[var-name]' label='[optional]'>
<value>[var-value]</value>
</field>
...
</x>
</query>
</iq>Note: A <field/> element MAY contain more than one <value/> child if appropriate.
If the data fields are to be used in the context of a protocol approved by the Jabber Software Foundation, they SHOULD be described in the relevant Jabber Enhancement Proposal and registered in accordance with the rules defined in JEP-0068, resulting in the inclusion of a <field/> element whose 'var' attribute has a value of "FORM_TYPE" and whose 'type' attribute has a value of "hidden".
An entity MUST NOT supply extended information about associated children communicated via the 'http://jabber.org/protocol/disco#items' namespace, since a core principle of Service Discovery is that an entity must define its own identity only and must not define the identity of any children associated with the entity.
The following is an example of including a disco extension in the IQ result sent by a standard instant messaging server.
Example 1. Entity Queries Server for Information
<iq type='get'
from='capulet.com'
to='shakespeare.lit'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
<iq type='result'
from='shakespeare.lit'
to='capulet.com'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity
category='server'
type='im'
name='shakespeare.lit jabber server'/>
<feature var='jabber:iq:register'/>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/network/serverinfo</value>
</field>
<field var='c2s_port'>
<value>5222</value>
</field>
<field var='c2s_port_ssl'>
<value>5223</value>
</field>
<field var='http_access'>
<value>http://shakespeare.lit/jabber</value>
</field>
<field var='ip_version'>
<value>ipv4</value>
<value>ipv6</value>
</field>
<field var='info_url'>
<value>http://shakespeare.lit/support.php</value>
</field>
</x>
</query>
</iq>
The following is an example of including a disco extension in the IQ result sent by a Multi-User Chat room.
Example 2. User Queries Room for Information
<iq type='get'
from='hag66@shakespeare.lit/pda'
to='darkcave@macbeth.shakespeare.lit'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
<iq type='result'
from='darkcave@macbeth.shakespeare.lit'
to='hag66@shakespeare.lit/pda'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity
category='conference'
type='text'
name='A Dark Cave'/>
<feature var='http://jabber.org/protocol/muc'/>
<feature var='jabber:iq:register'/>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/muc#roominfo</value>
</field>
<field var='muc#roominfo_description' label='Description'>
<value>The place for all good witches!</value>
</field>
<field var='muc#roominfo_subject' label='Subject'>
<value>Spells</value>
</field>
<field var='muc#roominfo_occupants' label='Number of occupants'>
<value>3</value>
</field>
<field var='muc#roominfo_lang' label='Language of discussion'>
<value>en</value>
</field>
</x>
</query>
</iq>
Applications SHOULD ensure that information disclosed in a disco extension is appropriate for discovery by any entity on the network.
This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [6].
This JEP requires no interaction with the Jabber Registrar [7]; however, JEPs following the best practices defined herein may register FORM_TYPEs and field values with the Jabber Registrar.
1. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.
2. JEP-0045: Multi-User Chat <http://www.jabber.org/jeps/jep-0045.html>.
3. JEP-0060: Publish-Subscribe <http://www.jabber.org/jeps/jep-0060.html>.
4. JEP-0004: Data Forms <http://www.jabber.org/jeps/jep-0004.html>.
5. JEP-0068: Field Data Standardization for Data Forms <http://www.jabber.org/jeps/jep-0068.html>.
6. 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/>.
7. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.
END