JEP-0147: XMPP URI Scheme Query Components

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.

JEP Information

Status: Active
Type: Informational
Number: 0147
Version: 1.1
Last Updated: 2006-06-19
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, RFC 4622, 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)>

Author Information

Legal Notice

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

Discussion Venue

The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.

Given that this JEP normatively references IETF technologies, discussion on the JSF-IETF list may also be appropriate (see <http://mail.jabber.org/mailman/listinfo/jsf-ietf> for details).

Relation to XMPP

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.

Conformance Terms

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

Table of Contents

1. Introduction

RFC 4622 [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, RFC 4622 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:

• The registry is defined in the XMPP IRI/URI Querytype Registry section.
• An initial set of actions and key-value pairs is described in the Query Actions section.
• A corresponding initial submission to the registry is specified in the Initial Registration section.
• The process for submitting additional values to the registry is specified in the Registration Process section.

Note: The format of the XMPP URI scheme, including the format of the query component, is fully specified and formally defined in RFC 4622; this document does not modify the xmpp URI scheme in any way and assumes that the reader is familiar with all aspects of RFC 4622.

2. Terminology

This document inherits terminology from RFC 3986 [5], RFC 3987 [6], and RFC 4622.

3. Query Actions

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 define all such potential actions. However, the following actions might be of general interest:

1. Sending a message.
2. Adding or removing a roster item.
3. Subscribing to or unsubscribing from an entity's presence information.
4. Probing for current presence information.
5. Determining Service Discovery [7] information about an entity.
6. Joining a groupchat room (see Multi-User Chat [8]).
7. Requesting initiation of Ad-Hoc Commands [9] associated with an entity.
8. Retrieving the vcard-temp [10] data associated with an entity.
9. Subscribing to or unsubscribing from a Publish-Subscribe [11] node.
10. Registering with another entity via In-Band Registration [12].
11. Initiating a file transfer with another entity (see File Transfer [13]).

For each such action, the Jabber Registrar maintains a RECOMMENDED "querytype" (this can be thought of as an action name or "verb"; see RFC 4622 for syntax and semantics) as well as an OPTIONAL list of keys to be used in key-value pairs if appropriate.

The querytypes and key-value pairs related to RFC 3920 and RFC 3921 are defined herein; the querytypes and key-value pairs related to protocols defined in the JSF's JEP series are defined in the relevant JEPs.

xmpp:romeo@montague.net?message
    

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&apos;s a test message.</body>
</message>
    

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>
    

xmpp:romeo@montague.net?remove
    

<iq type='set'>
  <query xmlns='jabber:iq:roster'>
    <item jid='romeo@montague.net' subscription='remove'/>
  </query>
</iq>
    

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'/>
    

xmpp:romeo@montague.net?unsubscribe
    

<presence to='romeo@montague.net' type='unsubscribe'/>
    

xmpp:romeo@montague.net?probe
    

<presence to='romeo@montague.net' type='probe'/>
    

4. Internationalization Considerations

Internationalization considerations for XMPP IRIs/URIs are specified in RFC 4622; the reader is referred to that document for a complete discussion of the relevant issues.

Localization of application-specific data presented to a human user (e.g., as encapsulated in key-value pairs) is the responsibility of the using protocol.

5. Security Considerations

Security considerations for XMPP IRIs/URIs are specified in RFC 4622.

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.

6. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [16]. 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.

7. Jabber Registrar Considerations

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

<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>remove</name>
  <proto>jabber:iq:roster</proto>
  <desc>enables removing a roster item</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>
  <keys>
    <key>
      <name>group</name>
      <desc>the user-assigned group for the roster item</desc>
    </key>
    <key>
      <name>name</name>
      <desc>the user-assigned name for the roster item</desc>
    </key>
  </keys>
</querytype>

<querytype>
  <name>subscribe</name>
  <proto>jabber:client</proto>
  <desc>enables sending a presence subscription request</desc>
  <doc>JEP-0147</doc>
</querytype>

<querytype>
  <name>unsubscribe</name>
  <proto>jabber:client</proto>
  <desc>enables unsubscribing from an entity's presence</desc>
  <doc>JEP-0147</doc>
</querytype>

      

Notes

Revision History

END