This document defines an XMPP protocol extension that enables two entities to mutually negotiate feature options.
NOTICE: The protocol defined herein is a Draft Standard of the Jabber Software Foundation. Implementations are encouraged and the protocol is appropriate for deployment in production systems, but some changes to the protocol are possible before it becomes a Final Standard.
Status:
Draft
Type:
Standards Track
Number: 0020
Version: 1.4
Last Updated: 2004-05-21
Publishing Organization: Jabber Software Foundation
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0004
Supersedes: None
Superseded By: None
Short Name: feature-neg
Schema: <http://www.xmpp.org/schemas/feature-neg.xsd>
Wiki Page: <http://wiki.jabber.org/index.php/Feature Negotiation (XEP-0020)>
This XMPP Extension Protocol is copyright 1999 - 2006 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.xmpp.org/extensions/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).
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 (RFC 3920) and XMPP IM (RFC 3921) 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 protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
A discovery protocol such as Service Discovery [1] enables Jabber entities to query other entities regarding the features they support, but does not provide a means for the two entities to negotiate specific options related to the advertised features (e.g., specific methods of file transfer such as In-Band Bytestreams [2] or SOCKS5 Bytestreams [3]).
The protocol defined herein enables Jabber entities to negotiate options for specific features. These features could be negotiated between any two endpoints on the Jabber network, such as two clients, a client and a component, two components, a client and a server, or two servers. The protocol is generic enough that it can be used whenever options need to be negotiated between two Jabber entities.
Features are negotiated though the exchange of <iq/> stanzas containing <query/> child elements qualified by the 'http://jabber.org/protocol/feature-neg' namespace. However, this <query/> element is simply a wrapper for structured data encapsulated in the Data Forms [4] protocol. [5]
In order to begin a negotation, the initiator sends an <iq/> stanza of type "get" to the recipient with a single <feature/> element containing a data form of type "form" which defines the available options for one or more features. Each feature is represented as an x-data "field", which MUST be of type "list-single" as specified in XEP-0004.
The recipient SHOULD examine each feature and the options provided. In order to indicate preferred options, the recipient then SHOULD specify one option for each feature and return a data form of type "submit" to the initiator in an <iq/> stanza of type "result".
The following examples show some likely scenarios for feature negotiation between entities. Further examples can be found in using protocols, such as File Transfer [6].
A typical negotiation flow is shown in the following example of two entities negotiating the time and place for a meeting.
Example 1. Initiating entity sends offer
<iq type='get'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='neg1'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='form'>
<field type='list-single' var='places-to-meet'>
<option><value>Lover's Lane</value></option>
<option><value>Secret Grotto</value></option>
<option><value>Verona Park</value></option>
</field>
<field type='list-single' var='times-to-meet'>
<option><value>22:00</value></option>
<option><value>22:30</value></option>
<option><value>23:00</value></option>
<option><value>23:30</value></option>
</field>
</x>
</feature>
</iq>
Example 2. Responding entity sends preferred option values
<iq type='result'
id='neg1'
from='juliet@jabber.org/balcony'
to='romeo@montague.net/orchard'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='places-to-meet'>
<value>Secret Grotto</value>
</field>
<field var='times-to-meet'>
<value>22:30</value>
</field>
</x>
</feature>
</iq>
If the responding entity does not support one or more of the features, it MUST return a <feature-not-implemented/> error, and SHOULD specify the feature(s) not implemented in the XMPP <text/> element.
Example 3. Responding entity does not support a feature
<iq type='error'
id='neg1'
from='juliet@jabber.org/balcony'
to='romeo@montague.net/orchard'>
<error code='501' type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>times-to-meet</text>
</error>
</iq>
If the responding entity supports none of the options offered for a certain feature, it MUST return a <not-acceptable/> error, and SHOULD specify the relevant feature in the XMPP <text/> element.
Example 4. Responding entity supports no options
<iq type='error'
from='juliet@jabber.org/balcony'
to='romeo@montague.net/orchard'
id='neg1'>
<error code='406' type='modify'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>places-to-meet</text>
</error>
</iq>
If at least one feature offered by an entity is subject to Feature Negotiation [7], the entity's response to a service discovery information request MUST include <feature var='http://jabber.org/protocol/feature-neg'/> as one of the features.
Example 5. Client queries a chatroom for supported features
<iq type='get'
from='juliet@capulet.com/balcony'
to='balconyscene@plays.shakespeare.lit'
id='neg1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>Example 6. Chatroom returns supported features
<iq type='result'
from='balconyscene@plays.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='neg1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/feature-neg'/>
<feature var='muc-password'/>
...
</query>
</iq>The using protocol (in these examples, Multi-User Chat [8]) SHOULD specify which features might be negotiable, either in the relevant documentation or in the entry for that feature in the service discovery features registry maintained by the XMPP Registrar. However, the requesting entity MAY also query the responding entity in order to determine which features are negotiable, as shown below.
Example 7. Client queries a chatroom for supported features
<iq type='get'
from='juliet@capulet.com/balcony'
to='balconyscene@plays.shakespeare.lit'
id='neg1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>Example 8. Chatroom returns supported features
<iq type='result'
from='balconyscene@plays.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='neg1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://jabber.org/protocol/feature-neg'/>
<feature var='muc-password'/>
...
</query>
</iq>The using protocol (in these examples, XEP-0045) SHOULD specify which features might be negotiable, either in the relevant documentation or in the entry for that feature in the service discovery features registry maintained by the XMPP Registrar (see <http://www.jabber.org/registrar/disco-vars.html>). However, the requesting entity MAY also query the responding entity in order to determine which features are negotiable, as shown below.
Example 9. Client queries chatroom regarding options for a negotiable feature
<iq type='get'
from='juliet@capulet.com/balcony'
to='balconyscene@plays.shakespeare.lit'
id='neg2'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='submit'>
<field var='muc-password'/>
</x>
</feature>
</iq>If that feature is not negotiable, the responding entity MUST return a "Feature Not Implemented" error:
Example 10. Chatroom returns error
<iq type='result'
from='balconyscene@plays.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='neg2'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='result'>
<field var='muc-password' type='list-single'>
<option><value>cleartext</value></option>
<option><value>SHA1</value></option>
<option><value>SASL</value></option>
</field>
</x>
</feature>
<error code='501' type='cancel'>
<feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>If that feature is negotiable, the responding entity MUST return an appropriate negotiation form:
Example 11. Chatroom returns negotiation form
<iq type='result'
from='balconyscene@plays.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='neg2'>
<feature xmlns='http://jabber.org/protocol/feature-neg'>
<x xmlns='jabber:x:data' type='result'>
<field var='muc-password' type='list-single'>
<option><value>cleartext</value></option>
<option><value>SHA1</value></option>
<option><value>SASL</value></option>
</field>
</x>
</feature>
</iq>The requesting entity MAY then submit a data form containing the required information.
Security considerations are the responsibility of the using protocol.
This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [9].
In order for Jabber entities to adequately leverage Data Forms (e.g., by using machine-readable fields), it is RECOMMENDED to register standard x-data fields with the XMPP Registrar [10] via the mechanisms defined in Field Standardization for Data Forms [11]. Whether to do so for any given features and options shall be determined by the using protocol.
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/protocol/feature-neg'
xmlns='http://jabber.org/protocol/feature-neg'
elementFormDefault='qualified'>
<xs:import
namespace='jabber:x:data'
schemaLocation='http://www.xmpp.org/schemas/x-data.xsd'/>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
XEP-0020: http://www.xmpp.org/extensions/xep-0020.html
</xs:documentation>
</xs:annotation>
<xs:element name='feature'>
<xs:complexType>
<xs:sequence xmlns:data='jabber:x:data'>
<xs:element ref='data:x'/>
</xs:sequence>
</xs:complexType>
</xs:schema>
Peter Millard, the primary author of this specification from version 0.1 through version 1.4, died on April 26, 2006. The remaining author is thankful for Peter's work on this specification.
1. XEP-0030: Service Discovery <http://www.xmpp.org/extensions/xep-0030.html>.
2. XEP-0047: In-Band Bytestreams <http://www.xmpp.org/extensions/xep-0047.html>.
3. XEP-0065: SOCKS5 Bytestreams <http://www.xmpp.org/extensions/xep-0065.html>.
4. XEP-0004: Data Forms <http://www.xmpp.org/extensions/xep-0004.html>.
5. Earlier versions of this document defined an structured data format to handle the feature negotiation workflow; versions later than 0.4 use Data Forms, i.e., the 'jabber:x:data' namespace.
6. XEP-0096: File Transfer <http://www.xmpp.org/extensions/xep-0096.html>.
7. XEP-0020: Feature Negotiation <http://www.xmpp.org/extensions/xep-0020.html>.
8. XEP-0045: Multi-User Chat <http://www.xmpp.org/extensions/xep-0045.html>.
9. 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/>.
10. 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 Jabber Software Foundation. For further information, see <http://www.xmpp.org/registrar/>.
11. XEP-0068: Field Data Standardization for Data Forms <http://www.xmpp.org/extensions/xep-0068.html>.
END