xep-0147.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>XMPP URI Scheme Query Components</title>
  <abstract>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.</abstract>
  &LEGALNOTICE;
  <number>0147</number>
  <status>Active</status>
  <type>Informational</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>RFC 5122</spec>
    <spec>XEP-0053</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>querytypes</shortname>
  <registry/>
  &stpeter;
  <revision>
    <version>1.2</version>
    <date>2006-09-13</date>
    <initials>psa</initials>
    <remark><p>Removed probe action.</p></remark>
  </revision>
  <revision>
    <version>1.1</version>
    <date>2006-06-19</date>
    <initials>psa</initials>
    <remark><p>Added actions for roster removal, presence unsubscription, and cancellation of registration; moved querytypes related to XMPP extensions from this document to the relevant XMPP Extension Protocol specifications.</p></remark>
  </revision>
  <revision>
    <version>1.0</version>
    <date>2006-03-23</date>
    <initials>psa</initials>
    <remark><p>Per a vote of the Jabber Council, advanced to Active.</p></remark>
  </revision>
  <revision>
    <version>0.7</version>
    <date>2006-03-16</date>
    <initials>psa</initials>
    <remark><p>Added actions for ad-hoc commands and vCard retrieval; clarified some explanatory text.</p></remark>
  </revision>
  <revision>
    <version>0.6</version>
    <date>2005-12-01</date>
    <initials>psa</initials>
    <remark><p>Updated to reflect draft-saintandre-xmpp-iri-03; modified file transfer query operations to handle both send and receive use cases.</p></remark>
  </revision>
  <revision>
    <version>0.5</version>
    <date>2005-09-05</date>
    <initials>psa</initials>
    <remark><p>Updated to reflect draft-saintandre-xmpp-iri-01; added file querytype for file transfer.</p></remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2005-06-06</date>
    <initials>psa</initials>
    <remark><p>Updated to reflect draft-saintandre-xmpp-iri-00.</p></remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2005-02-28</date>
    <initials>psa</initials>
    <remark><p>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.</p></remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2004-11-17</date>
    <initials>psa</initials>
    <remark><p>Updated to reflect draft-saintandre-xmpp-uri-07; specified Service Discovery usage.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2004-11-12</date>
    <initials>psa</initials>
    <remark><p>Initial version.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>&rfc5122; defines a Uniform Resource Identifier (URI) scheme for use in forming URIs and Internationalized Resource Identifiers (IRIs) <note>On the difference between IRIs and URIs, see &rfc3987;.</note> from the addresses of entities that can communicate using the Extensible Messaging and Presence Protocol (see &xmppcore;). Such identifiers enable identification of and interaction with XMPP entities by non-native applications such as databases and web browsers.</p>
  <p>However, &rfc5122; 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 &REGISTRAR;) and specifies a set of initial values for that registry.</p>
  <p>This document is organized as follows:</p>
  <ul>
    <li>The registry is defined in the <link url='#registrar-querytype'>XMPP IRI/URI Querytype Registry</link> section.</li>
    <li>An initial set of actions and key-value pairs is described in the <link url='#actions'>Query Actions</link> section.</li>
    <li>A corresponding initial submission to the registry is specified in the <link url='#registrar-querytype-init'>Initial Registration</link> section.</li>
    <li>The process for submitting additional values to the registry is specified in the <link url='#registrar-querytype-process'>Registration Process</link> section.</li>
  </ul>
  <p>Note: The format of the XMPP URI scheme, including the format of the query component, is fully specified  and formally defined in &rfc5122;; this document does not modify the xmpp URI scheme in any way and assumes that the reader is familiar with all aspects of <cite>RFC 5122</cite>.</p>
</section1>
<section1 topic='Terminology' anchor='terms'>
  <p>This document inherits terminology from &rfc3986;, &rfc3987;, and &rfc5122;.</p>
</section1>
<section1 topic='Query Actions' anchor='actions'>
  <p>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:</p>
  <ol>
    <li>Sending a message.</li>
    <li>Adding or removing a roster item.</li>
    <li>Subscribing to or unsubscribing from an entity's presence information.</li>
    <li>Determining &xep0030; information about an entity.</li>
    <li>Joining a groupchat room (see &xep0045;).</li>
    <li>Requesting initiation of &xep0050; associated with an entity.</li>
    <li>Retrieving the &xep0054; data associated with an entity.</li>
    <li>Subscribing to or unsubscribing from a &xep0060; node.</li>
    <li>Registering with another entity via &xep0077;.</li>
    <li>Initiating a file transfer with another entity (see &xep0096;).</li>
  </ol>
  <p>For each such action, the XMPP Registrar maintains a RECOMMENDED "querytype" (this can be thought of as an action name or "verb"; see &rfc5122; for syntax and semantics) as well as an OPTIONAL list of keys to be used in key-value pairs if appropriate.</p>
  <p>The querytypes and key-value pairs related to &rfc3920; and <cite>RFC 3921</cite> are defined herein; the querytypes and key-value pairs related to protocols defined in the XMPP Standards Foundation's XEP series are defined in the relevant XMPP Extension Protocol specifications.</p>
  <section2 topic='Message Action' anchor='actions-message'>
    <p>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 &xep0071; markup).</p>
    <example caption='Basic Message Action'><![CDATA[
xmpp:romeo@montague.net?message
]]></example>
    <p>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 &xmppim;:</p>
    <ol>
      <li>subject</li>
      <li>body</li>
      <li>thread</li>
    </ol>
    <p>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):</p>
    <ol>
      <li>from</li>
      <li>id</li>
      <li>type</li>
    </ol>
    <p>Other keys MAY be registered with the XMPP Registrar but are not specified herein.</p>
    <example caption='Message Action with Keys: IRI/URI'><![CDATA[
xmpp:romeo@montague.net?message;subject=Test%20Message;body=Here%27s%20a%20test%20message
]]></example>
    <example caption='Message Action with Keys: Resulting Stanza'><![CDATA[
<message to='romeo@montague.net'>
  <subject>Test Message</subject>
  <body>Here&apos;s a test message.</body>
</message>
]]></example>
  </section2>
  <section2 topic='Roster Management Actions' anchor='actions-roster'>
    <p>The 'jabber:iq:roster' namespace provides a mechanism for managing an XMPP roster (also called a "contact list"). This namespace is defined in &rfc3921;. The following actions are defined.</p>
    <section3 topic='Add Roster Item' anchor='actions-roster-add'>
      <p>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 &lt;item/&gt; element within the 'jabber:iq:roster' namespace, and MAY contain one "group" key whose value maps to the character data of the &lt;group/&gt; child element of &lt;item/&gt;.</p>
      <example caption='Roster Action: IRI/URI'><![CDATA[
xmpp:romeo@montague.net?roster
]]></example>
      <example caption='Roster Action: Resulting Stanza'><![CDATA[
<iq type='set'>
  <query xmlns='jabber:iq:roster'>
    <item jid='romeo@montague.net'/>
  </query>
</iq>
]]></example>
      <example caption='Roster Action With Name: IRI/URI'><![CDATA[
xmpp:romeo@montague.net?roster;name=Romeo%20Montague
]]></example>
      <example caption='Roster Action With Name: Resulting Stanza'><![CDATA[
<iq type='set'>
  <query xmlns='jabber:iq:roster'>
    <item jid='romeo@montague.net' name='Romeo Montague'/>
  </query>
</iq>
]]></example>
      <example caption='Roster Action With Name and Group: IRI/URI'><![CDATA[
xmpp:romeo@montague.net?roster;name=Romeo%20Montague;group=Friends
]]></example>
      <example caption='Roster Action With Name and Group: Resulting Stanza'><![CDATA[
<iq type='set'>
  <query xmlns='jabber:iq:roster'>
    <item jid='romeo@montague.net' name='Romeo Montague'>
      <group>Friends</group>
    </item>
  </query>
</iq>
]]></example>
      <p>Note: Methods (if any) for including more than one group are yet to be determined.</p>
    </section3>
    <section3 topic='Remove Roster Item' anchor='actions-roster-remove'>
      <p>The 'jabber:iq:roster' namespace includes a mechanism for removing an XMPP roster item. The registered querytype for removing an item from the roster is "remove".</p>
      <example caption='Roster Removal Action: IRI/URI'><![CDATA[
xmpp:romeo@montague.net?remove
]]></example>
      <example caption='Roster Removal Action: Resulting Stanza'><![CDATA[
<iq type='set'>
  <query xmlns='jabber:iq:roster'>
    <item jid='romeo@montague.net' subscription='remove'/>
  </query>
</iq>
]]></example>
    </section3>
  </section2>
  <section2 topic='Subscription Management Actions' anchor='actions-sub'>
    <p>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 &rfc3921;. The following actions are defined</p>
    <section3 topic='Subscribe' anchor='actions-sub-subscribe'>
      <p>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 &rfc3921;).</p>
      <example caption='Subscribe Action: IRI/URI'><![CDATA[
xmpp:romeo@montague.net?subscribe
]]></example>
      <example caption='Subscribe Action: Resulting Stanzas'><![CDATA[
<iq type='set'>
  <query xmlns='jabber:iq:roster'>
    <item jid='romeo@montague.net'/>
  </query>
</iq>

<presence to='romeo@montague.net' type='subscribe'/>
]]></example>
    </section3>
    <section3 topic='Unsubscribe' anchor='actions-sub-unsubscribe'>
      <p>XMPP includes a mechanism for unsubscribing from an entity. The registered querytype for doing so is "unsubscribe".</p>
      <example caption='Unsubscribe Action: IRI/URI'><![CDATA[
xmpp:romeo@montague.net?unsubscribe
]]></example>
      <example caption='Unsubscribe Action: Resulting Stanza'><![CDATA[
<presence to='romeo@montague.net' type='unsubscribe'/>
]]></example>
    </section3>
  </section2>
</section1>
<section1 topic='Internationalization Considerations' anchor='i18n'>
  <p>Internationalization considerations for XMPP IRIs/URIs are specified in &rfc5122;; the reader is referred to that document for a complete discussion of the relevant issues.</p>
  <p>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".</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>Security considerations for XMPP IRIs/URIs are specified in &rfc5122;.</p>
  <p>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.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;. If in the future the IANA should wish to maintain a registry of XMPP URI/IRI query components, the XMPP Registrar will cooperate with efforts to migrate the registry from the XMPP Registrar to the IANA.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='XMPP IRI/URI Querytype Registry' anchor='registrar-querytype'>
    <p>The XMPP Registrar maintains a registry of querytype values (see &QUERYTYPES;).</p>
    <section3 topic='Registration Process' anchor='registrar-querytype-process'>
      &REGPROCESS;
      <code><![CDATA[
<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>
]]></code>
      <p>Note: Within the &lt;querytype/&gt; element, the &lt;keys/&gt; child element is OPTIONAL; within any given &lt;key/&gt; element, the &lt;values/&gt; child element is also OPTIONAL.</p>
      <p>The registrant may register more than one querytype at a time, each contained in a separate &lt;querytype/&gt; element.</p>
    </section3>
    <section3 topic='Registration' anchor='registrar-querytype-reg'>
      <p>The following submission registers parameters related to the XMPP RFCs. For submissions related to XMPP extensions, refer to the relevant XMPP Extension Protocol specifications.</p>
      <code><![CDATA[

<querytype>
  <name>message</name>
  <proto>jabber:client</proto>
  <desc>enables sending of an XMPP message stanza</desc>
  <doc>XEP-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>remove</name>
  <proto>jabber:iq:roster</proto>
  <desc>enables removing a roster item</desc>
  <doc>XEP-0147</doc>
</querytype>

<querytype>
  <name>roster</name>
  <proto>jabber:iq:roster</proto>
  <desc>enables adding or editing a roster item</desc>
  <doc>XEP-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>XEP-0147</doc>
</querytype>

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

]]></code>
    </section3>
  </section2>
</section1>
</xep>