This JEP defines a registry of XMPP URI query components and also specifies an initial submission of values to that registry.
WARNING: This Standards-Track JEP is Experimental. Publication as a Jabber Enhancement Proposal does not imply approval of this proposal by the Jabber Software Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.
Status: Experimental
Type: Standards Track
Number: 0147
Version: 0.1
Last Updated: 2004-11-12
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, XMPP URI, JEP-0053
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 (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 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.
XMPP URI [1] defines the xmpp: URI scheme for interaction with XMPP entities (see XMPP Core [2]) by non-native applications, but intentionally leaves the potential values of the query component somewhat open-ended. In particular, that document does not provide a list of common "actions" for queries (e.g., send message or join chatroom), nor does it specify recommended "key-value" pairs to be used in the context of such actions. This JEP calls for a registry of such actions and key-value pairs, to be maintained by Jabber Registrar [3].
Note: The format for XMPP URIs, including the format of the query component, is fully specified and formally defined in XMPP URI; this document does not modify the xmpp: URI scheme in any way and assumes that the reader is familiar with all aspects of that specification.
This document inherits terminology from XMPP URI and from URI Syntax [4].
The range of actions that might be triggered by interaction with an XMPP entity by means of an XMPP URI is potentially as wide as the range of extensions to XMPP. This JEP does not seek to exhaustively defined all such potential actions. However, the following actions might be of general interest, and therefore are described below:
For each such action, this JEP specifies a recommended "querytype" (this can be thought of as an action name; see XMPP URI for syntax and semantics) as well as a list of keys to be used in key-value pairs if appropriate.
It may desirable for an XMPP URI to trigger a specialized interface for sending an XMPP message stanza (as opposed to completing some other action). The RECOMMENDED querytype for this action is "message". If no key-value pair is provided, interacting with an XMPP 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 [8] markup).
Example 1. Basic Message Action
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:
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 URI):
Other keys MAY be registered with the Jabber Registrar but are not specified herein.
Example 2. Message Action with Keys
xmpp:romeo@montague.net?message&subject=Test%20Message&body=Here%27s%20a%20test%20message
Example 3. Message Action with Keys: Resulting Stanza
<message to='romeo@montage.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 XMPP IM [9]. 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 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/>.
Example 4. Roster Action
xmpp:romeo@montague.net?roster
Example 5. Roster Action: Resulting Stanza
<iq type='set'>
<query xmlns='jabber:iq:roster'>
<item jid='romeo@montage.net'/>
</query>
</iq>
Example 6. Roster Action With Name
xmpp:romeo@montague.net?roster&name=Romeo%20Montague
Example 7. Roster Action With Name: Resulting Stanza
<iq type='set'>
<query xmlns='jabber:iq:roster'>
<item jid='romeo@montage.net' name='Romeo Montague'/>
</query>
</iq>
Example 8. Roster Edit Action With Name and Group
xmpp:romeo@montague.net?roster&action=edit&name=Romeo%20Montague&group=Friends
Example 9. Roster Edit Action With Name and Group: Resulting Stanza
<iq type='set'>
<query xmlns='jabber:iq:roster'>
<item jid='romeo@montage.net' name='Romeo Montague'>
<group>Friends</group>
</item>
</query>
</iq>
Note: Methods for including more than one group are yet to be determined.
In order to remove an item from the roster, the registered querytype to use is "remove".
Example 10. Roster Remove Action
xmpp:romeo@montague.net?remove
Example 11. Roster Remove Action: Resulting Stanza
<iq type='set'>
<query xmlns='jabber:iq:roster'>
<item jid='romeo@montage.net' subscription='remove'/>
</query>
</iq>
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 XMPP IM. Support for the subscribe and unsubscribe actions is RECOMMENDED, whereas support for the subscribed and unsubscribed actions is OPTIONAL.
Example 12. Subscribe Action
xmpp:romeo@montague.net?subscribe
Example 13. Subscribe Action: Resulting Stanza
<presence to='romeo@montague.net' type='subscribe'/>
Example 14. Unsubscribe Action
xmpp:romeo@montague.net?unsubscribe
Example 15. Unsubscribe Action: Resulting Stanza
<presence to='romeo@montague.net' type='unsubscribe'/>
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 action and resulting protocol are shown below.
Example 16. Probe Action
xmpp:romeo@montague.net?probe
Example 17. Probe Action: Resulting Stanza
<presence to='romeo@montague.net' type='probe'/>
The Jabber 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 "leave".
Example 18. Join Action
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.
Example 19. Join Action: Resulting Stanza
<presence to='darkcave@macbeth.shakespeare.lit/thirdwitch'>
<x xmlns='http://jabber.org/protocol/muc'/>
</presence>
Example 20. Leave Action
xmpp:darkcave@macbeth.shakespeare.lit?leave
The application SHOULD populate the room nickname based on the value provided when joining.
Example 21. Leave Action: Resulting Stanza
<presence to='darkcave@macbeth.shakespeare.lit/thirdwitch'
type='unavailable'/>
Sometimes it is necessary to register with an entity (e.g., a groupchat room or 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. Two querytype values are included in the querytype registry to enable registration management: "register" and "unregister".
Example 22. Register Action
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:
Example 23. Retrieving Registration Fields
<iq to='marlowe.shakespeare.lit' type='get'>
<query xmlns='jabber:iq:register'/>
</iq>
Example 24. Receiving Registration Fields
<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.
Example 25. Sending Registration Information
<iq to='marlowe.shakespeare.lit' type='set'>
<query xmlns='jabber:iq:register'>
<username>juliet</username>
<password>R0m30</password>
</query>
</iq>
Once registered, a user may also want to unregister.
Example 26. Unregister Action
xmpp:marlowe.shakespeare.lit?unregister
Example 27. Unregister Action: Resulting Stanza
<iq to='marlowe.shakespeare.lit' type='set'>
<query xmlns='jabber:iq:register'>
<remove/>
</query>
</iq>
JEP-0060: Publish-Subscribe defines a generic protocol for subscribing and publishing to "feeds" or "channels" of information. The "pubsub" quertype is defined herein for interaction with pubsub services, with an "action" key for pubsub-related actions, whose defined values are "subscribe", "unsubscribe", and "publish".
Example 28. Pubsub Subscribe Action
xmpp:pubsub.shakespeare.lit?pubsub&action=subscribe#globe/performances
Note the inclusion of a fragment identifier component; this is to be mapped to the pubsub NodeID.
Example 29. Pubsub Subscribe Action: Resulting Stanza
<iq to='pubsub.shakespeare.lit' type='set'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe node='globe/performances'/>
</pubsub>
</iq>
Example 30. Pubsub Unsubscribe Action
xmpp:pubsub.shakespeare.lit?pubsub&action=unsubscribe#globe/performances
Example 31. Pubsub Unsubscribe Action: Resulting Stanza
<iq to='pubsub.shakespeare.lit' type='set'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<unsubscribe node='globe/performances'/>
</pubsub>
</iq>
Internationalization considerations for XMPP URIs are specified in XMPP URI; the reader is referred to that document for a complete discussion of the relevant issues.
Security considerations for XMPP URIs are specified in XMPP URI.
This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [10].
The Jabber Registrar shall create a registry of querytype values.
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>join</name>
<proto>http://jabber.org/protocol/muc</proto>
<desc>enables joining a groupchat room</desc>
<doc>JEP-xxxx</doc>
</querytype>
<querytype>
<name>leave</name>
<proto>http://jabber.org/protocol/muc</proto>
<desc>enables leaving a groupchat room</desc>
<doc>JEP-xxxx</doc>
</querytype>
<querytype>
<name>message</name>
<proto>jabber:client</proto>
<desc>enables sending of an XMPP message stanza</desc>
<doc>JEP-xxxx</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-xxxx</doc>
</querytype>
<querytype>
<name>pubsub</name>
<proto>http://jabber.org/protocol/pubsub</proto>
<desc>enables interaction with a publish-subscribe service</desc>
<doc>JEP-xxxx</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>
</keys>
</querytype>
<querytype>
<name>register</name>
<proto>jabber:iq:register</proto>
<desc>enables registering with a server or service</desc>
<doc>JEP-xxxx</doc>
</querytype>
<querytype>
<name>remove</name>
<proto>jabber:iq:roster</proto>
<desc>enables removing a roster item</desc>
<doc>JEP-xxxx</doc>
</querytype>
<querytype>
<name>roster</name>
<proto>jabber:iq:roster</proto>
<desc>enables adding or editing a roster item</desc>
<doc>JEP-xxxx</doc>
</querytype>
<querytype>
<name>subscribe</name>
<proto>jabber:client</proto>
<desc>enables sending a presence subscription request</desc>
<doc>JEP-xxxx</doc>
</querytype>
<querytype>
<name>unregister</name>
<proto>jabber:iq:register</proto>
<desc>enables unregistering with a server or service</desc>
<doc>JEP-xxxx</doc>
</querytype>
<querytype>
<name>unsubscribe</name>
<proto>jabber:client</proto>
<desc>enables unsubscribing from a contact's presence</desc>
<doc>JEP-xxxx</doc>
</querytype>
1. A Uniform Resource Identifier (URI) Scheme for the Extensible Messaging and Presence Protocol (XMPP) <http://www.ietf.org/internet-drafts/draft-saintandre-xmpp-uri-06.txt> (work in progress).
2. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.
3. 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/>.
4. Uniform Resource Identifiers (URI): Generic Syntax <http://www.ietf.org/internet-drafts/draft-fielding-uri-rfc2396bis-07.txt>.
5. JEP-0045: Multi-User Chat <http://www.jabber.org/jeps/jep-0045.html>.
6. JEP-0077: In-Band Registration <http://www.jabber.org/jeps/jep-0077.html>.
7. JEP-0060: Publish-Subscribe <http://www.jabber.org/jeps/jep-0060.html>.
8. JEP-0071: XHTML-IM <http://www.jabber.org/jeps/jep-0071.html>.
9. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.
10. 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/>.
END