This document defines a registry of query components to be used in the context of XMPP IRIs/URIs and also specifies an initial submission of values to that registry.
NOTICE: This Informational JEP defines a best practice or protocol profile that has been approved by the Jabber Council and/or the JSF Board of Directors. Implementations are encouraged and the best practice or protocol profile is appropriate for deployment in production systems.
Status: Active
Type: Informational
Number: 0147
Version: 1.0
Last Updated: 2006-03-23
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, draft-saintandre-xmpp-iri, JEP-0053
Supersedes: None
Superseded By: None
Short Name: querytypes
Registry:
<http://www.jabber.org/registrar/querytypes.html>
Wiki Page: <http://wiki.jabber.org/index.php/XMPP URI Scheme Query Components (JEP-0147)>
Email:
stpeter@jabber.org
JID:
stpeter@jabber.org
This Jabber Enhancement Proposal 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.jabber.org/jsf/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 JEP 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 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.
XMPP URI Scheme [1] defines a Uniform Resource Identifier (URI) scheme for use in forming URIs and Internationalized Resource Identifiers (IRIs) [2] from the addresses of entities that can communicate using the Extensible Messaging and Presence Protocol (see XMPP Core [3]). Such identifiers enable identification of and interaction with XMPP entities by non-native applications such as databases and web browsers.
However, draft-saintandre-xmpp-iri intentionally leaves the potential values of the query component open-ended, does not provide a list of common "actions" for queries (e.g., send message or join chatroom), and does not specify recommended "key-value" pairs to be used in the context of such actions. Therefore, this document defines a registry of such actions and key-value pairs (to be maintained by the Jabber Registrar [4]) and specifies a set of initial values for that registry.
This document is organized as follows:
Note: The format of the XMPP URI scheme, including the format of the query component, is fully specified and formally defined in draft-saintandre-xmpp-iri; this document does not modify the xmpp URI scheme in any way and assumes that the reader is familiar with all aspects of draft-saintandre-xmpp-iri.
This document inherits terminology from RFC 3986 [5], RFC 3987 [6], and draft-saintandre-xmpp-iri.
The range of actions that might be triggered by interaction with an XMPP entity by means of an XMPP IRI/URI is potentially as wide as the range of extensions to XMPP. This document does not seek to exhaustively defined all such potential actions. However, the following actions might be of general interest, and therefore are described below and included in the initial submission of values to the registry:
For each such action, this document specifies a RECOMMENDED "querytype" (this can be thought of as an action name or "verb"; see draft-saintandre-xmpp-iri for syntax and semantics) as well as an OPTIONAL list of keys to be used in key-value pairs if appropriate.
It may desirable for an XMPP IRI/URI to trigger a specialized interface for sending an XMPP message stanza. The RECOMMENDED querytype for this action is "message". If no key-value pair is provided, interacting with an XMPP IRI/URI that contains a querytype of "message" SHOULD trigger an interface that enables the user to input the text of an XMPP message and other relevant parameters (e.g., a message subject or XHTML-IM [14] markup).
xmpp:romeo@montague.net?message
A query component whose querytype is "message" MAY specify various key-value pairs. The following three keys are associated with the child elements of the <message/> stanza specified in the XML schema for the 'jabber:client' namespace as defined in XMPP IM [15]:
In addition, the following three keys are associated with the attributes of the <message/> stanza specified in the XML schema for the 'jabber:client' namespace (the 'to' attribute is unnecessary, since it is provided by the XMPP address included in the IRI/URI):
Other keys MAY be registered with the Jabber Registrar but are not specified herein.
xmpp:romeo@montague.net?message;subject=Test%20Message;body=Here%27s%20a%20test%20message
<message to='romeo@montague.net'> <subject>Test Message</subject> <body>Here's a test message.</body> </message>
The 'jabber:iq:roster' namespace provides a mechanism for managing an XMPP roster (also called a "contact list"). This namespace is defined in RFC 3921. The registered querytype for adding items to the roster or editing items in the roster is "roster" (effectively there is no difference between adding and editing). An XMPP IRI/URI containing a "roster" querytype MAY also include at most one "name" key whose value maps to the 'name' attribute of the <item/> element within the 'jabber:iq:roster' namespace, and MAY contain one "group" key whose value maps to the character data of the <group/> child element of <item/>.
xmpp:romeo@montague.net?roster
<iq type='set'> <query xmlns='jabber:iq:roster'> <item jid='romeo@montague.net'/> </query> </iq>
xmpp:romeo@montague.net?roster;name=Romeo%20Montague
<iq type='set'> <query xmlns='jabber:iq:roster'> <item jid='romeo@montague.net' name='Romeo Montague'/> </query> </iq>
xmpp:romeo@montague.net?roster;name=Romeo%20Montague;group=Friends
<iq type='set'> <query xmlns='jabber:iq:roster'> <item jid='romeo@montague.net' name='Romeo Montague'> <group>Friends</group> </item> </query> </iq>
Note: Methods (if any) for including more than one group are yet to be determined. Furthermore, roster item removal is not supported.
Closely coupled with roster management is presence subscription management. In XMPP, subscription management is handled via special values of the <presence/> stanza, as described in RFC 3921. When an entity subscribes to another entity's presence by means of an XMPP IRI/URI, the invoked XMPP application SHOULD first send a roster add stanza as shown below (this is consistent with the recommendations in RFC 3921).
xmpp:romeo@montague.net?subscribe
<iq type='set'> <query xmlns='jabber:iq:roster'> <item jid='romeo@montague.net'/> </query> </iq> <presence to='romeo@montague.net' type='subscribe'/>
Note: Unsubscribing is not supported.
Once an entity is subscribed to the presence of a contact, it is allowed to probe for the contact's current presence if necessary. Although normally this is done by the server on the user's behalf, the client may initiate a probe as well. The registered querytype for initiating a presence probe is "probe".
An example of the action and resulting protocol is shown below.
xmpp:romeo@montague.net?probe
<presence to='romeo@montague.net' type='probe'/>
The Jabber/XMPP network has long included groupchat rooms (similar to IRC channels); this functionality is defined fully in JEP-0045: Multi-User Chat. Two querytype values are registered to enable interaction with groupchat rooms: "join" and "invite".
xmpp:darkcave@macbeth.shakespeare.lit?join
The application MUST either present an interface enabling the user to provide a room nickname or populate the room nickname based on configured preferences.
<presence to='darkcave@macbeth.shakespeare.lit/thirdwitch'> <x xmlns='http://jabber.org/protocol/muc'/> </presence>
The application SHOULD populate the room nickname based on the value provided when joining.
It may be desirable to simultaneously join a room and invite one or more specified other individuals to join the room. The "invite" querytype is used to complete such an action.
xmpp:darkcave@macbeth.shakespeare.lit?invite;jid=hecate@shakespeare.lit
If the joining user is not yet in the room, the application MUST send two stanzas: the first to join the room and the second to invite the other individual. If the joining user is in the room already, the application shall send only the invitation stanza.
<presence to='darkcave@macbeth.shakespeare.lit/thirdwitch'> <x xmlns='http://jabber.org/protocol/muc'/> </presence> <message to='darkcave@macbeth.shakespeare.lit'> <x xmlns='http://jabber.org/protocol/muc#user'> <invite to='hecate@shakespeare.lit'/> </x> </message>
The Jabber/XMPP protocols include an extension that enables two entities to transfer a file between them, as defined in JEP-0096: File Transfer. The entity that controls an XMPP IRI/URI may enable other entities to send files or receive files, the registered querytypes for which are "sendfile" and "recvfile". Note well that "sendfile" means a second entity will send a file to the XMPP entity that controls the IRI/URI and that "recvfile" means a second entity will receive a file from the XMPP entity that controls the IRI/URI.
To enable a second entity to send a file, the IRI/URI is of the following form:
xmpp:romeo@montague.net/orchard?sendfile
The application SHOULD then present an interface enabling the user to provide information about the file to be sent (e.g., by "browsing" the file system of the user's computer in order to choose a file). As a result, the application SHOULD then send a Publishing SI Requests [16] message to the XMPP address encapsulated in the IRI/URI:
<message from='juliet@capulet.com/balcony' to='romeo@montague.net'> <sipub xmlns='http://jabber.org/protocol/si-pub' id='publish-0123' mime-type='text/plain' profile='http://jabber.org/protocol/si/profile/file-transfer'> <file xmlns='http://jabber.org/protocol/si/profile/file-transfer' name='missive.txt' size='1024' date='2005-11-29T11:21Z'/> </sipub> </message>
To enable a second entity to receive a file, the IRI/URI is of the following form:
xmpp:romeo@montague.net/orchard?recvfile;sid=pub234;mime-type=text%2Fplain&name=reply.txt&size=2048
That IRI/URI is equivalent to the following XML stanza:
<message from='romeo@montague.net' to='juliet@capulet.com/balcony'> <sipub xmlns='http://jabber.org/protocol/si-pub' id='pub234' mime-type='text/plain' profile='http://jabber.org/protocol/si/profile/file-transfer'> <file xmlns='http://jabber.org/protocol/si/profile/file-transfer' name='reply.txt' size='2048'/> </sipub> </message>
In accordance with JEP-0137, the application SHOULD then initiate a file transfer exchange with by sending a stanza of the following form:
<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard'> <start xmlns='http://jabber.org/protocol/si-pub' id='pub234'/> </iq>
Note well that the request to begin the stream is send to the full JID (user@host/resource) of the XMPP entity identified by the XMPP IRI/URI. Therefore, the IRI/URI SHOULD include a full JID. If it does not, the receiver MUST discover a full JID via presence or service discovery. If the receiver cannot discover a full JID for the sender (e.g., in the last resort through sending a presence subscription request to the sender and receiving presence from the sender's resources), then it SHOULD abort the file transfer exchange.
Sometimes it is desirable or necessary to register with an entity (e.g., a groupchat room or a gateway to a non-Jabber IM system) before interacting with it further; the protocol for doing so is defined in JEP-0077: In-Band Registration. The registered querytype value for registration management is "register".
xmpp:marlowe.shakespeare.lit?register
Because registration is a two-step process (see JEP-0077), the application MUST then send an IQ-get to the entity in order to retrieve the required registration fields:
<iq to='marlowe.shakespeare.lit' type='get'> <query xmlns='jabber:iq:register'/> </iq>
<iq from='marlowe.shakespeare.lit' type='result'> <query xmlns='jabber:iq:register'> <username/> <password/> </query> </iq>
The application MUST then present an appropriate interface that enables the user to complete the registration form. Once the user provides the information, the application MUST send an IQ-set to the entity.
<iq to='marlowe.shakespeare.lit' type='set'> <query xmlns='jabber:iq:register'> <username>juliet</username> <password>R0m30</password> </query> </iq>
Note: Cancelling an existing registration is not supported.
JEP-0060: Publish-Subscribe defines a generic protocol for subscribing and publishing to "feeds" or "channels" of information. The "pubsub" querytype is defined herein for interaction with pubsub services, with two keys: (1) "node" (to specify pubsub nodes) and (2) "action", whose defined values are "subscribe", "unsubscribe", and "publish".
xmpp:pubsub.shakespeare.lit?pubsub;action=subscribe;node=globe/performances
<iq to='pubsub.shakespeare.lit' type='set'> <pubsub xmlns='http://jabber.org/protocol/pubsub'> <subscribe node='globe/performances'/> </pubsub> </iq>
xmpp:pubsub.shakespeare.lit?pubsub;action=unsubscribe;node=globe/performances
<iq to='pubsub.shakespeare.lit' type='set'> <pubsub xmlns='http://jabber.org/protocol/pubsub'> <unsubscribe node='globe/performances'/> </pubsub> </iq>
JEP-0030: Service Discovery defines a protocol for discovering information about Jabber entities as well as the items associated with such entities. The "disco" querytype is defined herein for interaction for the purpose of service discovery, with three keys: (1) an OPTIONAL "node" (to specify service discovery nodes), (2) "request", whose defined values are "info" and "items" (corresponding to the disco#info and disco#items namespaces specified in JEP-0030), and (3) "type", whose defined values are "get" and "set" (corresponding to the IQ "get" and "set" methods specified in RFC 3920).
xmpp:romeo@montague.net?disco;type=get;request=info
<iq to='romeo@montague.net' type='get'> <query xmlns='http://jabber.org/protocol/disco#info'/> </iq>
xmpp:romeo@montague.net?disco;type=get;request=items;node=http://jabber.org/protocol/extended-presence
<iq to='romeo@montague.net' type='get'> <query xmlns='http://jabber.org/protocol/disco#info' node='http://jabber.org/protocol/extended-presence'/> </iq>
Many Jabber/XMPP systems have long included support for user (and even server) vCards, as specified in JEP-0054. Although this functionality may be superseded by a more flexible and extensible protocol in the future, it remains valuable to be able to retrieve vCard data associated with an XMPP entity. The "vcard" querytype is defined for this purpose.
xmpp:romeo@montague.net?vcard
<iq to='romeo@montague.net' type='get'> <vCard xmlns='vcard-temp'/> </iq>
The ad-hoc commands protocol specified in JEP-0050 enables one entity to interact with another entity to complete application-specific functions such as configuration or statistics retrieval. The "command" querytype is defined for this purpose.
xmpp:montague.net?command;node=stats
<iq to='montague.net' type='get'> <command xmlns='http://jabber.org/protocol/commands' node='stats'/> </iq>
Internationalization considerations for XMPP IRIs/URIs are specified in draft-saintandre-xmpp-iri; the reader is referred to that document for a complete discussion of the relevant issues.
Security considerations for XMPP IRIs/URIs are specified in draft-saintandre-xmpp-iri.
Completion of some of the actions defined herein will cause changes to an entity's account, subscriptions to information, registration with services, communication with other entities, completion of ad-hoc commands, and the like. Naturally, such changes, information, services, and communications are potentially undesirable (e.g., joining a chatroom whose discussion topic is not of interest to, or even patently offensive to, the joining user). The invoked application SHOULD appropriately warn a human user regarding the potential consequences of the action about to be completed.
This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [17]. If in the future the IANA should wish to maintain a registry of XMPP URI/IRI query components, the Jabber Registrar will cooperate with efforts to migrate the registry from the Jabber Registrar to the IANA.
The Jabber Registrar maintains a registry of querytype values (see <http://www.jabber.org/registrar/querytypes.html>).
In order to submit new values to this registry, the registrant must define an XML fragment of the following form and either include it in the relevant Jabber Enhancement Proposal or send it to the email address <registrar@jabber.org>:
<querytype> <name>the name of the querytype (e.g., "pubsub")</name> <proto> the namespace of associated protocol output (e.g., "http://jabber.org/protocol/pubsub") </proto> <desc>a natural-language description of the querytype</desc> <doc>the document in which the querytype is specified</doc> <keys> <key> <name>the name of the key (e.g., "action")</name> <desc>a natural-language description of the key</desc> <values> <value> <name>the name of a value (e.g., "subscribe")</name> <desc>a natural-language description of the value</desc> </value> </values> </key> </keys> </querytype>
Note: Within the <querytype/> element, the <keys/> child element is OPTIONAL; within any given <key/> element, the <values/> child element is also OPTIONAL.
The registrant may register more than one querytype at a time, each contained in a separate <querytype/> element.
<querytype> <name>command</name> <proto>http://jabber.org/protocol/commands</proto> <desc>enables completion of ad-hoc commands</desc> <doc>JEP-0147</doc> <keys> <key> <name>node</name> <desc>the command node</desc> </key> <key> <name>action</name> <desc>the ad-hoc commands action type</desc> <values> <value> <name>cancel</name> <desc>a request to cancel processing of the command</desc> </value> <value> <name>complete</name> <desc>a request to complete processing of the command</desc> </value> <value> <name>execute</name> <desc>a request to execute the command (the default implied action)</desc> </value> <value> <name>next</name> <desc>a request to move to the next command in a series</desc> </value> <value> <name>complete</name> <desc>a request to move to the previous command in a series</desc> </value> </values> </key> <key> <name>type</name> <desc>the IQ type</desc> <values> <value> <name>get</name> <desc>an IQ get</desc> </value> <value> <name>set</name> <desc>an IQ set (disco publish)</desc> </value> </values> </key> </keys> </querytype> <querytype> <name>disco</name> <proto>http://jabber.org/protocol/disco</proto> <desc>enables interaction for the purpose of service discovery</desc> <doc>JEP-0147</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> <value> <name>set</name> <desc>an IQ set (disco publish)</desc> </value> </values> </key> </keys> </querytype> <querytype> <name>invite</name> <proto>http://jabber.org/protocol/muc</proto> <desc>enables simultaneously joining a groupchat room and inviting others</desc> <doc>JEP-0147</doc> </querytype> <querytype> <name>join</name> <proto>http://jabber.org/protocol/muc</proto> <desc>enables joining a groupchat room</desc> <doc>JEP-0147</doc> </querytype> <querytype> <name>message</name> <proto>jabber:client</proto> <desc>enables sending of an XMPP message stanza</desc> <doc>JEP-0147</doc> <keys> <key> <name>subject</name> <desc>a subject for the message per the "jabber:client" schema</desc> </key> <key> <name>body</name> <desc>a body for the message per the "jabber:client" schema</desc> </key> <key> <name>thread</name> <desc>a Thread ID for the message per the "jabber:client" schema</desc> </key> <key> <name>from</name> <desc>a from address for the message per the "jabber:client" schema</desc> </key> <key> <name>id</name> <desc>an ID for the message per the "jabber:client" schema</desc> </key> <key> <name>type</name> <desc>the message type per the "jabber:client" schema</desc> <values> <value> <name>chat</name> <desc>a message of type "chat"</desc> </value> <value> <name>groupchat</name> <desc>a message of type "groupchat"</desc> </value> <value> <name>headline</name> <desc>a message of type "headline"</desc> </value> <value> <name>normal</name> <desc>a message of type "normal"</desc> </value> </values> </key> </keys> </querytype> <querytype> <name>probe</name> <proto>jabber:client</proto> <desc>enables probing for a contact's current presence information</desc> <doc>JEP-0147</doc> </querytype> <querytype> <name>pubsub</name> <proto>http://jabber.org/protocol/pubsub</proto> <desc>enables interaction with a publish-subscribe service</desc> <doc>JEP-0147</doc> <keys> <key> <name>action</name> <desc>the pubsub action</desc> <values> <value> <name>subscribe</name> <desc>enables subscribing to a pubsub node</desc> </value> <value> <name>unsubscribe</name> <desc>enables unsubscribing from a pubsub node</desc> </value> </values> </key> <key> <name>node</name> <desc>the pubsub node</desc> </key> </keys> </querytype> <querytype> <name>recvfile</name> <proto>http://jabber.org/protocol/si/profile/file-transfer</proto> <desc>enables initiation of an outbound file transfer from XMPP entity</desc> <doc>JEP-0147</doc> </querytype> <querytype> <name>register</name> <proto>jabber:iq:register</proto> <desc>enables registering with a server or service</desc> <doc>JEP-0147</doc> </querytype> <querytype> <name>roster</name> <proto>jabber:iq:roster</proto> <desc>enables adding or editing a roster item</desc> <doc>JEP-0147</doc> </querytype> <querytype> <name>sendfile</name> <proto>http://jabber.org/protocol/si/profile/file-transfer</proto> <desc>enables initiation of an inbound file transfer to XMPP entity</desc> <doc>JEP-0147</doc> </querytype> <querytype> <name>subscribe</name> <proto>jabber:client</proto> <desc>enables sending a presence subscription request</desc> <doc>JEP-0147</doc> </querytype> <querytype> <name>vcard</name> <proto>vcard-temp</proto> <desc>enables retrieval of an entity's vCard data</desc> <doc>JEP-0147</doc> </querytype>
1. Internationalized Resource Identifiers (IRIs) and Uniform Resource Identifiers (URIs) for the Extensible Messaging and Presence Protocol (XMPP) <http://www.ietf.org/internet-drafts/draft-saintandre-xmpp-iri-04.txt> (approved by the IESG on 2006-05-08, publication as an RFC is pending).
2. On the difference between IRIs and URIs, see RFC 3987.
3. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.
4. 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/>.
5. RFC 3986: Uniform Resource Identifiers (URI): Generic Syntax <http://www.ietf.org/rfc/rfc3986.txt>.
6. RFC 3987: Internationalized Resource Identifiers (IRIs) <http://www.ietf.org/rfc/rfc3987.txt>.
7. JEP-0045: Multi-User Chat <http://www.jabber.org/jeps/jep-0045.html>.
8. JEP-0096: File Transfer <http://www.jabber.org/jeps/jep-0096.html>.
9. JEP-0077: In-Band Registration <http://www.jabber.org/jeps/jep-0077.html>.
10. JEP-0060: Publish-Subscribe <http://www.jabber.org/jeps/jep-0060.html>.
11. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.
12. JEP-0054: vcard-temp <http://www.jabber.org/jeps/jep-0054.html>.
13. JEP-0050: Ad-Hoc Commands <http://www.jabber.org/jeps/jep-0050.html>.
14. JEP-0071: XHTML-IM <http://www.jabber.org/jeps/jep-0071.html>.
15. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.
16. JEP-0137: Publishing SI Requests <http://www.jabber.org/jeps/jep-0137.html>.
17. 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/>.
Per a vote of the Jabber Council, advanced to Active.
(psa)Added actions for ad-hoc commands and vCard retrieval; clarified some explanatory text.
(psa)Updated to reflect draft-saintandre-xmpp-iri-03; modified file transfer query operations to handle both send and receive use cases.
(psa)Updated to reflect draft-saintandre-xmpp-iri-01; added file querytype for file transfer.
(psa)Updated to reflect draft-saintandre-xmpp-iri-00.
(psa)Updated to reflect draft-saintandre-xmpp-uri-08 and subsequent XMPP WG discussion; removed use cases for editing roster items, removing roster items, leaving chatrooms, unsubscribing, and unregistering (these make more sense from within a dedicated client); added use case for simultaneously joining a room and inviting other participants; further specified security considerations.
(psa)Updated to reflect draft-saintandre-xmpp-uri-07; specified Service Discovery usage.
(psa)Initial version.
(psa)END