xep-0100.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>Gateway Interaction</title>
  <abstract>This document specifies best practices for interactions between Jabber clients and client proxy gateways to legacy IM services.</abstract>
  &LEGALNOTICE;
  <number>0100</number>
  <status>Active</status>
  <type>Informational</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
    <spec>XEP-0030</spec>
    <spec>XEP-0077</spec>
    <spec>XEP-0144</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>gateway</shortname>
  <schemaloc>
    <url>http://www.xmpp.org/schemas/iq-gateway.xsd</url>
  </schemaloc>
  &stpeter;
  &dizzyd;
  <revision>
    <version>1.0</version>
    <date>2005-10-05</date>
    <initials>psa</initials>
    <remark>Per a vote of the Jabber Council, advanced status to Active.</remark>
  </revision>
  <revision>
    <version>0.10</version>
    <date>2005-05-12</date>
    <initials>psa</initials>
    <remark>Modified text regarding address transformations and added reference to XEP-0106; corrected several small errors in the text and examples.</remark>
  </revision>
  <revision>
    <version>0.9</version>
    <date>2004-10-27</date>
    <initials>psa</initials>
    <remark>Added specification of jabber:iq:gateway namespace; added reference to XEP-0144.</remark>
  </revision>
  <revision>
    <version>0.8</version>
    <date>2004-05-07</date>
    <initials>psa</initials>
    <remark>Editorial review: made a number of minor textual changes and clarifications throughout; added introductory paragraph to each use case; specified that groupchat is out of scope.</remark>
  </revision>
  <revision>
    <version>0.7</version>
    <date>2004-03-31</date>
    <initials>psa</initials>
    <remark>Cleaned up several notes, examples, and business rules based on feedback received on list.</remark>
  </revision>
  <revision>
    <version>0.6</version>
    <date>2004-03-08</date>
    <initials>psa</initials>
    <remark>Added note about 'from' address on presence notifications and messages received through gateways from legacy users.</remark>
  </revision>
  <revision>
    <version>0.5</version>
    <date>2004-01-21</date>
    <initials>psa</initials>
    <remark>Further specified the rationale for deprecating the "jabber:iq:gateway" protocol.</remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2004-01-05</date>
    <initials>psa</initials>
    <remark>Added Edit Registration use case; modified handling of legacy contact lists to conform to RFC 3921; modified addressing rules; defined gateway startup and shutdown behavior; included XMPP error handling.</remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2003-12-10</date>
    <initials>psa</initials>
    <remark>Added security considerations; defined handling of legacy contact lists.</remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2003-12-03</date>
    <initials>psa</initials>
    <remark>Corrected some errors; clarified some ambiguities; added protocol flows.</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2003-06-25</date>
    <initials>psa/dss</initials>
    <remark>Initial version.</remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>One distinguishing characteristic of Jabber technologies from their earliest days has been the existence of gateways (also called "transports") between the Jabber network and legacy instant messaging services such as AOL Instant Messenger (AIM), ICQ, Windows Live Messenger, and Yahoo! Messenger. Surprisingly, the recommended behavior of such gateways, including the protocol elements used by a client to interact with a gateway, has never been fully documented. This document attempts to fill that void by codifying best practices for gateway interaction.</p>
  <p>Note well that this document defines protocol usage with regard to client proxy gateways, i.e., gateways that "masquerade" as a client on a non-Jabber IM service. Gateways that perform direct protocol translation without proxying for an account on a non-Jabber service are not addressed in this document. Furthermore, this document does not define any interaction between a gateway and the non-Jabber service, only interactions between a Jabber client and the gateway. Although what happens on the other side of the gateway is highly dependent on the nature of the legacy service, gateways should at least provide a common interface on the Jabber side of the gateway so that Jabber clients can be written in a consistent fashion.</p>
</section1>
<section1 topic='Glossary' anchor='glossary'>
  <dl>
    <di>
      <dt>Gateway</dt>
      <dd>A service on the Jabber network that translates between the Jabber/XMPP protocols and the protocol used by a Legacy Service; in the context of this document, by "gateway" we mean a "client proxy service" that acts as a client with regard to a Legacy Service and thereby "masquerades" as a user on such a service.</dd>
    </di>
    <di>
      <dt>Jabber User</dt>
      <dd>A human user who has registered an account with a Jabber server; a Jabber User who wants to use a Gateway must first have also registered an account with a Legacy Service.</dd>
    </di>
    <di>
      <dt>Legacy Service</dt>
      <dd>A non-XMPP instant messaging service.</dd>
    </di>
    <di>
      <dt>Legacy User</dt>
      <dd>A human user who has registered an account with a Legacy Service.</dd>
    </di>
    <di>
      <dt>Server</dt>
      <dd>An instant messaging server as defined in &rfc6121;.</dd>
    </di>
  </dl>
</section1>
<section1 topic='Requirements' anchor='reqs'>
  <p>The requirements defined by this document are captured in two sets of use cases: one set from the perspective of the Jabber User, and a smaller set from the perspective of the Legacy User who wants to interact with the Jabber User.</p>
  <p>The Jabber User use cases are:</p>
  <ol>
    <li>Register</li>
    <li>Edit Registration</li>
    <li>Unregister</li>
    <li>Log In</li>
    <li>Log Out</li>
    <li>Add Contact</li>
    <li>Delete Contact</li>
    <li>Send Message</li>
  </ol>
  <p>The Legacy User use cases are:</p>
  <ol>
    <li>Add Contact</li>
    <li>Delete Contact</li>
    <li>Send Message</li>
  </ol>
  <p>While more advanced use cases (e.g., sending files and joining chat rooms) are of inherent interest, they are not covered in this document because registration, contact list management, and message exchange define the baseline functionality included in all gateway implementations; future specifications may address the more advanced use cases.</p>
</section1>
<section1 topic='Jabber User Use Cases' anchor='usecases-jabber'>
  <section2 topic='Register' anchor='usecases-jabber-register'>
    <p>All existing client proxy gateways require a Jabber User to register with the Gateway before sending messages or presence through the gateway. Although strictly speaking registration is not required (e.g., a Gateway could prompt the Jabber User for credentials every time the user attempted to communicate through the gateway, or once per "session"), in practice this step is required.</p>
    <section3 topic='Primary Flow' anchor='usecases-jabber-register-pri'>
      <ol>
        <li>
          <p>Jabber User sends IQ-get qualified by the &xep0030; information namespace to the Gateway, and/or IQ-get qualified by the &xep0094; namespace to the Gateway's parent (the latter method is deprecated but still in use).</p>
          <example caption="User Queries Gateway Regarding Service Discovery Identity"><![CDATA[
<iq type='get'
    from='romeo@montague.lit/orchard'
    to='aim.shakespeare.lit'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
          <example caption="User Queries Gateway's Parent Regarding Agent Information"><![CDATA[
<iq type='get'
    from='romeo@montague.lit/orchard'
    to='shakespeare.lit'
    id='agent1'>
  <query xmlns='jabber:iq:agents'/>
</iq>
]]></example>
          <p>Note: Although many existing gateway implementations support only the older Agent Information protocol, it is RECOMMENDED that gateways support the Service Discovery protocol, since the former protocol is deprecated in favor of the latter. Until existing gateways are upgraded, clients SHOULD support both.</p>
        </li>
        <li>
          <p>Gateway and/or parent returns identity information to Jabber User's Client.</p>
          <example caption="Gateway Returns Service Discovery Identity"><![CDATA[
<iq type='result'
    from='aim.shakespeare.lit'
    to='romeo@montague.lit/orchard'
    id='disco1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity category='gateway'
              type='aim'
              name='AIM Gateway'/>
    <feature var='http://jabber.org/protocol/disco#info'/>
    <feature var='jabber:iq:register'/>
    <feature var='jabber:iq:time'/>
    <feature var='jabber:iq:version'/>
  </query>
</iq>
]]></example>
          <example caption="Gateway's Parent Returns Agent Information"><![CDATA[
<iq type='result'
    from='romeo@montague.lit/orchard'
    to='shakespeare.lit'
    id='agent1'>
  <query xmlns='jabber:iq:agents'>
    <agent jid='aim.shakespeare.lit'>
      <name>AIM Gateway</name>
      <service>aim</service>
      <transport/>
      <register/>
    </agent>
  </query>
</iq>
]]></example>
          <p>Note: Given the foregoing, a client can determine the identity of the gateway, specifically (1) that it is a gateway and (2) to which legacy service it provides a gateway.</p>
        </li>
        <li>
          <p>Jabber User sends IQ-get qualified by the &xep0077; (jabber:iq:register) namespace to Gateway.</p>
          <example caption="User Queries Gateway Regarding Registration Requirements"><![CDATA[
<iq type='get'
    from='romeo@montague.lit/orchard'
    to='aim.shakespeare.lit'
    id='reg1'>
  <query xmlns='jabber:iq:register'/>
</iq>
]]></example>
        </li>
        <li>
          <p>Gateway returns IQ-result to Jabber User, specifying information that is required in order to register.</p>
          <example caption="Gateway Returns Registration Requirements"><![CDATA[
<iq type='result'
    from='aim.shakespeare.lit'
    to='romeo@montague.lit/orchard'
    id='reg1'>
  <query xmlns='jabber:iq:register'>
    <instructions>
      Please provide your AIM screen name and password.
    </instructions>
    <username/>
    <password/>
  </query>
</iq>
]]></example>
        </li>
        <li>
          <p>Jabber User sends IQ-set qualified by the 'jabber:iq:register' namespace to Gateway, containing information required to register.</p>
          <example caption="User Provides Registration Information"><![CDATA[
<iq type='set'
    from='romeo@montague.lit/orchard'
    to='aim.shakespeare.lit'
    id='reg2'>
  <query xmlns='jabber:iq:register'>
    <username>RomeoMyRomeo</username>
    <password>ILoveJuliet</password>
  </query>
</iq>
]]></example>
          <p>Note: The XML character data of the &lt;username/&gt; element SHOULD be the Jabber User's LegacyUserAddress as described under <link url='#addressing'>Addressing</link>, such as an AOL screen name, ICQ number, Windows Live Messenger (formerly MSN Messenger) address, or Yahoo! ID.</p>
        </li>
        <li>
          <p>Gateway verifies that registration information provided by Jabber User is valid (using whatever means appropriate for the Legacy Service) and informs Jabber User of success [A1].</p>
          <example caption="Gateway Informs Jabber User of Success"><![CDATA[
<iq type='result'
    from='aim.shakespeare.lit'
    to='romeo@montague.lit/orchard'
    id='reg2'/>
]]></example>
        </li>
        <li><p>If Gateway logged into Legacy Service in preceding step, Gateway buffers any translatable events (e.g., messages and presence) queued up for Jabber User on Legacy Service.</p></li>
        <li>
          <p>Optionally, Jabber User sends IQ-set qualified by the 'jabber:iq:roster' namespace to its server (see &xmppcore;), containing a roster item for Gateway.</p>
          <example caption="User Creates Roster Entry"><![CDATA[
<iq type='set'
    from='romeo@montague.lit/orchard'
    id='roster1'>
  <query xmlns='jabber:iq:roster'>
    <item jid='aim.shakespeare.lit' name='AIM Gateway'/>
  </query>
</iq>
]]></example>
          <example caption="Server Response"><![CDATA[
<iq type='result'
    to='romeo@montague.lit/orchard'
    id='roster1'/>
]]></example>
        </li>
        <li>
          <p>Gateway sends subscription request to Jabber User (i.e., by sending a presence stanza of type "subscribe" to Jabber User's bare JID).</p>
          <example caption="Gateway Subscribes to User's Presence"><![CDATA[
<presence type='subscribe'
          from='aim.shakespeare.lit'
          to='romeo@montague.lit'/>
]]></example>
        </li>
        <li>
          <p>Jabber User's client SHOULD approve the subscription request (i.e., by sending a presence stanza of type "subscribed" to Gateway).</p>
          <example caption="Jabber User Approves Subscription Request"><![CDATA[
<presence type='subscribed'
          from='romeo@montague.lit'
          to='aim.shakespeare.lit'/>
]]></example>
          <p>Note: As specified in &rfc6121;, Jabber User's server will generate a "roster push" at this point if client did not previously perform a roster set to add Gateway to user's roster (as mentioned above).</p>
        </li>
        <li>
          <p>Jabber User sends subscription request to Gateway (i.e., by sending a presence stanza of type "subscribe" to Gateway).</p>
          <example caption="Jabber User Subscribes to Gateway&apos;s Presence"><![CDATA[
<presence type='subscribe'
          from='romeo@montague.lit'
          to='aim.shakespeare.lit'/>
]]></example>
        </li>
        <li>
          <p>Gateway sends approves subscription request (i.e., by sending a presence stanza of type "subscribed" to Jabber User's bare JID).</p>
          <example caption="Gateway Approves Subscription Request"><![CDATA[
<presence type='subscribed'
          from='aim.shakespeare.lit'
          to='romeo@montague.lit'/>
]]></example>
        </li>
        <li><p>Execute "Log In" use case.</p></li>
        <li><p>Gateway sends any buffered messages to Jabber User.</p></li>
        <li><p>Use Case Ends.</p></li>
      </ol>
    </section3>
    <section3 topic='Alternate Flows' anchor='usecases-jabber-register-alt'>
      <ol>
        <li><p>User information not verified:</p>
          <ol>
            <li>
              <p>Gateway returns &notacceptable; error to Jabber User. (For detailed information regarding error conditions, refer to &xep0086;.)</p>
              <example caption="Gateway Informs Jabber User of Registration Error"><![CDATA[
<iq type='error'
    from='aim.shakespeare.lit'
    to='romeo@montague.lit/orchard'
    id='reg2'>
  <query xmlns='jabber:iq:register'>
    <username>RomeoMyRomeo</username>
    <password>ILoveJuliet</password>
  </query>
  <error code='406' type='modify'>
    <not-acceptable
        xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
            </li>
            <li><p>Use Case Ends unsuccessfully.</p></li>
          </ol>
        </li>
      </ol>
    </section3>
  </section2>
  <section2 topic='Edit Registration' anchor='usecases-jabber-edit'>
    <p>After a Jabber User has registered with a Gateway, the user may wish to modify his or her existing registration information (e.g., because the user has changed his or her password on the legacy IM service).</p>
    <section3 topic='Primary Flow' anchor='usecases-jabber-edit-pri'>
      <ol>
        <li>
          <p>Jabber User sends IQ-get qualified by the 'jabber:iq:register' namespace to Gateway.</p>
          <example caption="User Queries Gateway Regarding Registration Requirements"><![CDATA[
<iq type='get'
    from='romeo@montague.lit/orchard'
    to='aim.shakespeare.lit'
    id='edit1'>
  <query xmlns='jabber:iq:register'/>
</iq>
]]></example>
        </li>
        <li>
          <p>Gateway returns IQ-result to Jabber User, specifying registration information on record and including empty &lt;registered/&gt; element to signify that user is already registered. <note>The fact that the Gateway can determine the Jabber User's legacy username based on the JID of the 'from' address indicates that the client proxy model assumes one registration per Jabber User.</note></p>
          <example caption="Gateway Returns Registration Information of Record"><![CDATA[
<iq type='result'
    from='aim.shakespeare.lit'
    to='romeo@montague.lit/orchard'
    id='edit1'>
  <query xmlns='jabber:iq:register'>
    <registered/>
    <username>RomeoMyRomeo</username>
    <password>ILoveJuliet</password>
  </query>
</iq>
]]></example>
        </li>
        <li>
          <p>Jabber User sends IQ-set qualified by the 'jabber:iq:register' namespace to Gateway, containing all information (i.e., not just the "delta").</p>
          <example caption="User Provides Registration Information"><![CDATA[
<iq type='set'
    from='romeo@montague.lit/orchard'
    to='aim.shakespeare.lit'
    id='edit2'>
  <query xmlns='jabber:iq:register'>
    <username>RomeoMyRomeo</username>
    <password>B4lc0ny</password>
  </query>
</iq>
]]></example>
        </li>
        <li>
          <p>Gateway verifies that, if changed, information provided by Jabber User is still valid (using whatever means appropriate for the Legacy Service) and informs Jabber User of success [A1].</p>
          <example caption="Gateway Informs Jabber User of Success"><![CDATA[
<iq type='result'
    from='aim.shakespeare.lit'
    to='romeo@montague.lit/orchard'
    id='edit2'/>
]]></example>
        </li>
      </ol>
    </section3>
    <section3 topic='Alternate Flows' anchor='usecases-jabber-edit-alt'>
      <ol>
        <li><p>Edit unsuccessful:</p>
          <ol>
            <li>
              <p>Gateway returns &notacceptable; error to Jabber User.</p>
              <example caption="Gateway Informs Jabber User of Registration Error"><![CDATA[
<iq type='error'
    from='aim.shakespeare.lit'
    to='romeo@montague.lit/orchard'
    id='edit2'>
  <query xmlns='jabber:iq:register'>
    <username>RomeoMyRomeo</username>
    <password>B4lc0ny</password>
  </query>
  <error code='406' type='modify'>
    <not-acceptable
        xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
            </li>
            <li><p>Use Case Ends unsuccessfully.</p></li>
          </ol>
        </li>
      </ol>
    </section3>
  </section2>
  <section2 topic='Unregister' anchor='usecases-jabber-unregister'>
    <p>After a Jabber User has registered with a Gateway, the user may choose to unregister with the Gateway, effectively ending his or her relationship with the Gateway (e.g., the user will no longer be allowed to communicate through the gateway with legacy users).</p>
    <section3 topic='Primary Flow' anchor='usecases-jabber-unregister-pri'>
      <ol>
        <li>
          <p>Jabber User sends IQ-set in 'jabber:iq:register' namespace to Gateway, containing empty &lt;remove/&gt; element.</p>
          <example caption="User Unregisters"><![CDATA[
<iq type='set'
    from='romeo@montague.lit/orchard'
    to='aim.shakespeare.lit'
    id='unreg1'>
  <query xmlns='jabber:iq:register'>
    <remove/>
  </query>
</iq>
]]></example>
        </li>
        <li><p>Gateway sends unavailable presence from Jabber User to Legacy Users and logs Jabber User out of Legacy Service.</p></li>
        <li><p>Gateway deletes Jabber User's information.</p></li>
        <li>
          <p>Gateway sends IQ-result to Jabber User.</p>
          <example caption="Gateway Informs Jabber User of Success"><![CDATA[
<iq type='result'
    from='aim.shakespeare.lit'
    to='romeo@montague.lit/orchard'
    id='unreg1'/>
]]></example>
        </li>
        <li>
          <p>Gateway cancels subscriptions.</p>
          <example caption="Gateway Cancels Subscriptions"><![CDATA[
<presence type='unsubscribe'
          from='aim.shakespeare.lit'
          to='romeo@montague.lit'/>

<presence type='unsubscribed'
          from='aim.shakespeare.lit'
          to='romeo@montague.lit'/>
]]></example>
        </li>
        <li>
          <p>Gateway sends unavailable presence to Jabber User.</p>
          <example caption="Gateway Logs User Out"><![CDATA[
<presence type='unavailable'
          from='aim.shakespeare.lit'
          to='romeo@montague.lit'/>
]]></example>
        </li>
        <li><p>Jabber User's client SHOULD delete from the user's roster (1) the gateway itself, and (2) all legacy Contacts associated with the gateway.</p></li>
        <li><p>Use Case Ends.</p></li>
      </ol>
    </section3>
    <section3 topic='Alternate Flows' anchor='usecases-jabber-unregister-alt'>
      <p>None.</p>
    </section3>
  </section2>
  <section2 topic='Log In' anchor='usecases-jabber-login'>
    <p>After a Jabber User has registered with a Gateway, the Jabber User may subsequently log in to the Gateway, effectively creating a "session" with the Gateway and enabling the Gateway to log into the Legacy Service on behalf of the user by sending the user's legacy credentials to the Legacy Service.</p>
    <section3 topic='Primary Flow' anchor='usecases-jabber-login-pri'>
      <ol>
        <li>
          <p>Jabber User sends available presence broadcast to Server or sends directed presence to Gateway or a Legacy User.</p>
          <example caption="Jabber User Sends Available Presence"><![CDATA[
<presence/>
]]></example>
          <example caption="Jabber User's Server Broadcasts Available Presence"><![CDATA[
<presence from='romeo@montague.lit/orchard'
          to='juliet@aim.shakespeare.lit'/>
<presence from='romeo@montague.lit/orchard'
          to='aim.shakespeare.lit'/>
...
]]></example>
        </li>
        <li><p>Upon receiving the first presence notification stanza from Jabber User to Gateway or Legacy User, Gateway logs Jabber User into Legacy Service [A1].</p></li>
        <li>
          <p>Gateway sends presence stanza to Jabber User expressing availability.</p>
          <example caption="Gateway Sends Presence to Jabber User"><![CDATA[
<presence from='aim.shakespeare.lit'
          to='romeo@montague.lit'/>
]]></example>
        </li>
        <li><p>Optionally, Gateway handles Legacy Service contact list; see the <link url="#rosters">Contact Lists</link> section of this document.</p></li>
        <li>
          <p>Gateway forwards current presence information from Legacy Users to Jabber User, if possible mapping availability status (e.g., "away").</p>
          <example caption="Gateway Sends Presence from Legacy Users to Jabber User"><![CDATA[
<presence from='juliet@aim.shakespeare.lit'
          to='romeo@montague.lit'>
  <show>away</show>
</presence>
]]></example>
          <p>Note: If the Legacy Service to which the Gateway connects does not support the concept of "resources", the 'from' address of presence notification stanzas generated by a gateway SHOULD NOT include a resource identifier (i.e., they SHOULD be of the form &lt;user@host&gt; rather than &lt;user@host/resource&gt;). However, the 'from' address MAY include a resource if the Gateway determines that this is appropriate in the context of its communications with the Legacy Service.</p>
        </li>
        <li>
          <p>Gateway forwards all subsequent presence stanzas to Legacy Users (except those of type "probe" and those addressed to the Gateway itself).</p>
          <example caption="Jabber User Modifies Presence"><![CDATA[
<presence from='romeo@montague.lit/orchard'
          to='juliet@aim.shakespeare.lit'>
  <show>dnd</show>
  <status>Wooing Juliet</status>
</presence>
]]></example>
        </li>
        <li><p>Use Case Ends.</p></li>
      </ol>
    </section3>
    <section3 topic='Alternate Flows' anchor='usecases-jabber-login-alt'>
      <ol>
        <li><p>Login fails:</p>
          <ol>
            <li>
              <p>Gateway sends appropriate presence error to Jabber User (&notauthorized; if password is bad, &timeout; if Legacy Service is down, etc.).</p>
              <example caption="Gateway Informs Jabber User of Failed Login"><![CDATA[
<presence to='aim.shakespeare.lit'
          from='romeo@shakespeare.lit'
          type='error'>
  <error code='504' type='wait'>
    <remote-server-timeout
        xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</presence>
]]></example>
            </li>
            <li><p>Use Case Ends unsuccessfully.</p></li>
          </ol>
        </li>
      </ol>
    </section3>
  </section2>
  <section2 topic='Log Out' anchor='usecases-jabber-logout'>
    <p>At any time after logging in to the Gateway, the Jabber User may log out of the Gateway and thereby end his or her session on the Legacy Service. This may happen automatically when the Jabber User terminates his or her session with a Jabber server, or independently of any session on the Jabber network by manually logging out of the Gateway.</p>
    <section3 topic='Primary Flow' anchor='usecases-jabber-logout-pri'>
      <ol>
        <li>
          <p>Jabber User sends unavailable presence broadcast to Server or sends directed presence stanza of type "unavailable" to Gateway or (if Gateway does not support directed presence) Legacy User.</p>
          <example caption="Jabber User Sends Unavailable Presence"><![CDATA[
<presence type='unavailable'/>
]]></example>
          <example caption="Jabber User's Server Broadcasts Unavailable Presence"><![CDATA[
<presence type='unavailable'
          from='romeo@montague.lit/orchard'
          to='aim.shakespeare.lit'/>
]]></example>
        </li>
        <li><p>Gateway transforms unavailable presence stanzas received from the Jabber User's server and routes them to all of the Jabber User's contacts on Legacy Service.</p></li>
        <li><p>Gateway logs Jabber User out of Legacy Service [A1].</p></li>
        <li>
          <p>Gateway sends presence stanza of type "unavailable" to Jabber User.</p>
          <example caption="Gateway Logs User Out"><![CDATA[
<presence type='unavailable'
          from='aim.shakespeare.lit'
          to='romeo@montague.lit/orchard'/>
]]></example>
        </li>
        <li><p>Use Case Ends.</p></li>
      </ol>
    </section3>
    <section3 topic='Alternate Flows' anchor='usecases-jabber-logout-alt'>
      <ol>
        <li><p>Legacy Service supports directed presence and Gateway receives presence stanza of type "unavailable" directed to a Legacy User:</p>
          <ol>
            <li>
              <p>Gateway passes through directed unavailable presence to Legacy User.</p>
              <example caption="Jabber User Becomes Unavailable"><![CDATA[
<presence type='unavailable'
          from='romeo@montague.lit/orchard'
          to='juliet@aim.shakespeare.lit'/>
]]></example>
              </li>
            <li><p>Use Case Ends.</p></li>
          </ol>
        </li>
      </ol>
    </section3>
  </section2>
  <section2 topic='Add Contact' anchor='usecases-jabber-addcontact'>
    <p>After registering with the Gateway, the Jabber User may want to add Legacy Users to his or her Jabber roster.</p>
    <section3 topic='Primary Flow' anchor='usecases-jabber-addcontact-pri'>
      <ol>
        <li>
          <p>Jabber User sends presence stanza of type "subscribe" to Legacy User.</p>
          <example caption="Jabber User Sends Subscription Request to Legacy User"><![CDATA[
<presence type='subscribe'
          from='romeo@montague.lit'
          to='CapuletNurse@aim.shakespeare.lit'/>
]]></example>
          <p>Note: As specified in &rfc6121;, sending this packet will result in a "roster push" from the Server to all of the Jabber User's available resources.</p>
        </li>
        <li><p>Gateway transforms subscription request and routes it to Legacy User.</p></li>
        <li>
          <p>If Legacy User approves subscription request, Gateway sends presence stanza of type "subscribed" to Jabber User on behalf of Legacy User. [A1]</p>
          <example caption="Gateway Approves Subscription Request on Behalf of Legacy User"><![CDATA[
<presence type='subscribed'
          from='CapuletNurse@aim.shakespeare.lit'
          to='romeo@montague.lit'/>
]]></example>
        </li>
        <li>
          <p>Gateway sends available presence stanza to Jabber User on behalf of Legacy User.</p>
          <example caption="Gateway Sends Legacy User's Current Presence Information to Jabber User"><![CDATA[
<presence from='CapuletNurse@aim.shakespeare.lit'
          to='romeo@montague.lit/orchard'/>
]]></example>
        </li>
        <li>
          <p>Gateway sends presence stanza of type "subscribe" to Jabber User on behalf of Legacy User.</p>
          <example caption="Gateway Sends Subscription Request to Jabber User on Behalf of Legacy User"><![CDATA[
<presence type='subscribe'
          from='CapuletNurse@aim.shakespeare.lit'
          to='romeo@montague.lit'/>
]]></example>
        </li>
        <li>
          <p>Jabber User sends presence stanza of type "subscribed" to Legacy User.</p>
          <example caption="Jabber User Approves Subscription Request"><![CDATA[
<presence type='subscribed'
          from='romeo@montague.lit'
          to='CapuletNurse@aim.shakespeare.lit'/>
]]></example>
        </li>
        <li><p>Use Case Ends.</p></li>
      </ol>
    </section3>
    <section3 topic='Alternate Flows' anchor='usecases-jabber-addcontact-alt'>
      <ol>
        <li>
          <p>Legacy User denies subscription request:</p>
          <ol>
            <li>
              <p>Gateway transforms subscription denial and routes it to Jabber User.</p>
              <example caption="Legacy User Denies Subscription Request"><![CDATA[
<presence type='unsubscribed'
          from='juliet@aim.shakespeare.lit'
          to='romeo@montague.lit'/>
]]></example>
              </li>
            <li><p>Use Case Ends unsuccessfully.</p></li>
          </ol>
        </li>
      </ol>
    </section3>
  </section2>
  <section2 topic='Delete Contact' anchor='usecases-jabber-deletecontact'>
    <p>After adding a Legacy User to his or her Jabber roster, the Jabber User may want to delete that contact.</p>
    <section3 topic='Primary Flow' anchor='usecases-jabber-deletecontact-pri'>
      <ol>
        <li>
          <p>Jabber User sends IQ-set qualified by the 'jabber:iq:roster' namespace, containing subscription attribute with value of "remove".</p>
          <example caption="User Removes Roster Entry for Legacy User"><![CDATA[
<iq type='set'
    from='romeo@montague.lit/orchard'
    id='remove1'>
  <query xmlns='jabber:iq:roster'>
    <item jid='CapuletNurse@aim.shakespeare.lit'
          subscription='remove'/>
  </query>
</iq>
]]></example>
        </li>
        <li>
          <p>Server sends normal "roster push" to Jabber User (see &rfc6121;) and sends presence stanzas of type "unsubscribe", "unsubscribed", and "unavailable" to Legacy User.</p>
          <example caption="Server Sends Presence Changes to Legacy User"><![CDATA[
<presence type='unsubscribe'
          from='romeo@montague.lit'
          to='CapuletNurse@aim.shakespeare.lit'/>

<presence type='unsubscribed'
          from='romeo@montague.lit'
          to='CapuletNurse@aim.shakespeare.lit'/>

<presence type='unavailable'
          from='romeo@montague.lit/orchard'
          to='CapuletNurse@aim.shakespeare.lit'/>
]]></example>
        </li>
        <li><p>Gateway cleans up subscription state, informs Legacy User that Jabber User is unavailable, and MUST NOT send future changes in Jabber User's presence to Legacy User.</p></li>
        <li><p>Use Case Ends.</p></li>
      </ol>
    </section3>
    <section3 topic='Alternate Flows' anchor='usecases-jabber-deletecontact-alt'>
      <p>None.</p>
    </section3>
  </section2>
  <section2 topic='Send Message' anchor='usecases-jabber-send'>
    <p>Naturally, the Jabber User may want to exchange messages with a Legacy User. For the purposes of this document, we discuss one-to-one messaging only (i.e., groupchat messages, such as those defined in &xep0045;, are out of scope).</p>
    <section3 topic='Primary Flow' anchor='usecases-jabber-send-pri'>
      <ol>
        <li>
          <p>Jabber User sends message stanza to Legacy User.</p>
          <example caption="Jabber User Sends Message to Legacy User"><![CDATA[
<message from='romeo@montague.lit/orchard'
         to='juliet@aim.shakespeare.lit'
         type='chat'>
  <body>Neither, fair saint, if either thee dislike.</body>
</message>
]]></example>
        </li>
        <li><p>Gateway transforms message to legacy protocol and sends to Legacy User [A1].</p></li>
        <li><p>Use Case Ends.</p></li>
      </ol>
    </section3>
    <section3 topic='Alternate Flows' anchor='usecases-jabber-send-alt'>
      <ol>
        <li><p>Legacy Service reports error.</p></li>
        <li>
          <p>Gateway sends appropriate error to Jabber User:</p>
          <ul>
            <li><p>&notfound; -- Legacy User address is not valid.</p></li>
            <li><p>&registration; -- Jabber User is not registered with Gateway.</p></li>
            <li><p>&unavailable; -- Legacy User is offline and Legacy Service (or Gateway) does not provide offline message storage.</p></li>
            <li><p>&timeout; -- Legacy Service cannot be reached.</p></li>
          </ul>
        </li>
        <li><p>Use Case Ends unsuccessfully.</p></li>
      </ol>
    </section3>
  </section2>
</section1>
<section1 topic='Legacy User Use Cases' anchor='usecases-legacy'>
  <section2 topic='Add Contact' anchor='usecases-legacy-add'>
    <p>The Legacy User may want to add the Jabber User to his or her contact list on the Legacy Service. Because the Jabber User has an account on the Legacy Service by definition, the Legacy User will actually add the Jabber User's legacy address to his or her contact list, not the Jabber User's address on the Jabber/XMPP network.</p>
    <section3 topic='Primary Flow' anchor='usecases-legacy-add-pri'>
      <ol>
        <li><p>Legacy User requests subscription to Jabber User's legacy address (using legacy protocol).</p></li>
        <li>
          <p>Gateway sends presence stanza of type "subscribe" to Jabber User on behalf of Legacy User. (Note: Gateway MUST NOT send presence stanza of type "subscribed".)</p>
          <example caption="Gateway Sends Subscription Request on Behalf of Legacy User"><![CDATA[
<presence type='subscribe'
          from='CapuletNurse@aim.shakespeare.lit'
          to='romeo@montague.lit'/>
]]></example>
        </li>
        <li>
          <p>Jabber User approves subscription request by sending presence stanza of type "subscribed" to Legacy User [A1].</p>
          <example caption="Jabber User Approves Subscription Request"><![CDATA[
<presence type='subscribed'
          from='romeo@montague.lit'
          to='CapuletNurse@aim.shakespeare.lit'/>
]]></example>
        </li>
        <li><p>Gateway sends Jabber User's presence information to Legacy User.</p></li>
        <li>
          <p>Jabber User's Client sends presence stanza of type "subscribe" to Legacy User.</p>
          <example caption="Jabber User Sends Subscription Request to Legacy User"><![CDATA[
<presence type='subscribe'
          from='romeo@montague.lit'
          to='CapuletNurse@aim.shakespeare.lit'/>
]]></example>
        </li>
        <li>
          <p>Gateway sends presence stanza of type "subscribed" to Jabber User on behalf of Legacy User.</p>
          <example caption="Gateway Approves Subscription Request on Behalf of Legacy User"><![CDATA[
<presence type='subscribed'
          from='CapuletNurse@aim.shakespeare.lit'
          to='romeo@montague.lit'/>
]]></example>
        </li>
        <li>
          <p>Gateway sends Legacy User's presence information to Jabber User.</p>
          <example caption="Gateway Sends Legacy User's Current Presence Information to Jabber User"><![CDATA[
<presence from='CapuletNurse@aim.shakespeare.lit'
          to='romeo@montague.lit/orchard'/>
]]></example>
        </li>
        <li><p>Use Case Ends.</p></li>
      </ol>
    </section3>
    <section3 topic='Alternate Flows' anchor='usecases-legacy-add-alt'>
      <ol>
        <li><p>Jabber User denies subscription request:</p>
          <ol>
            <li>
              <p>Jabber User sends presence stanza of type "unsubscribed" to Legacy User.</p>
              <example caption="Jabber User Denies Subscription Request"><![CDATA[
<presence type='unsubscribed'
          from='romeo@montague.lit'
          to='CapuletNurse@aim.shakespeare.lit'/>
]]></example>
            </li>
            <li><p>Gateway cleans up subscription state and MUST NOT send Jabber User's presence to Legacy User.</p></li>
            <li><p>Use Case Ends unsuccessfully.</p></li>
          </ol>
        </li>
      </ol>
    </section3>
  </section2>
  <section2 topic='Delete Contact' anchor='usecases-legacy-delete'>
    <p>After adding the Jabber User to his or her legacy contact list, the Legacy User may want to delete the Jabber User.</p>
    <section3 topic='Primary Flow' anchor='usecases-legacy-delete-pri'>
      <ol>
        <li><p>Legacy User deletes Jabber User's legacy address (using legacy protocol).</p></li>
        <li>
          <p>Gateway sends presence stanzas of type "unsubscribe", "unsubscribed", and "unavailable" to Jabber User on behalf of Legacy User.</p>
          <example caption="Gateway Cleans Up Subscription on Behalf of Legacy User"><![CDATA[
<presence type='unsubscribe'
          from='CapuletNurse@aim.shakespeare.lit'
          to='romeo@montague.lit'/>

<presence type='unsubscribed'
          from='CapuletNurse@aim.shakespeare.lit'
          to='romeo@montague.lit'/>

<presence type='unavailable'
          from='CapuletNurse@aim.shakespeare.lit'
          to='romeo@montague.lit/orchard'/>
]]></example>
        </li>
        <li><p>Jabber User's server performs defined functionality for handling presence stanzas of type "unsubscribe" and "unsubscribed" (see &rfc6121;).</p></li>
        <li><p>Use Case Ends.</p></li>
      </ol>
    </section3>
    <section3 topic='Alternate Flows' anchor='usecases-legacy-delete-alt'>
      <p>None.</p>
    </section3>
  </section2>
  <section2 topic='Send Message' anchor='usecases-legacy-send'>
    <p>Naturally, the Legacy User may want to exchange messages with the Jabber User. (Here again, groupchat messages are out of scope.)</p>
    <section3 topic='Primary Flow' anchor='usecases-legacy-send-pri'>
      <ol>
        <li><p>Legacy User sends message to Jabber User using legacy protocol.</p></li>
        <li>
          <p>Gateway transforms message and routes to Jabber User.</p>
          <example caption="Legacy User Sends Message to Jabber User"><![CDATA[
<message from='juliet@aim.shakespeare.lit'
         to='romeo@montague.lit'>
  <body>Art thou not Romeo, and a Montague?</body>
</message>
]]></example>
          <p>Note: If the Legacy Service to which the Gateway connects does not support a concept equivalent to that of Jabber "resources" as described in &rfc6120;, the 'from' address of message stanzas generated by a gateway SHOULD NOT include a resource identifier (i.e., they SHOULD be of the form &lt;user@host&gt; rather than &lt;user@host/resource&gt;). However, the 'from' address MAY include a resource if the Gateway determines that this is appropriate in the context of its communications with the Legacy Service.</p>
        </li>
        <li><p>Jabber User's Server delivers message or (optionally) stores it for later retrieval.</p></li>
        <li><p>Use Case Ends.</p></li>
      </ol>
    </section3>
    <section3 topic='Alternate Flows' anchor='usecases-legacy-send-alt'>
      <p>None.</p>
    </section3>
  </section2>
</section1>
<section1 topic='Addressing' anchor='addressing'>
  <section2 topic='Gateways' anchor='addressing-gateway'>
    <p>The address of a gateway itself SHOULD be a hostname only, and that hostname SHOULD NOT be supplemented with a resource identifier when referring to the gateway's address (e.g., when storing the gateway in a roster).</p>
  </section2>
  <section2 topic='Users' anchor='addressing-user'>
    <p>The Jabber Identifier corresponding to a Legacy User's address is typically of the form &lt;LegacyUserAddress@gateway.example.com&gt;, where LegacyUserAddress is the Legacy User's address on the Legacy Service and where gateway.example.com is the Jabber address of the gateway.</p>
    <p>Unfortunately, usernames on some Legacy Services may allow characters that are disallowed in Jabber usernames as specified by the Nodeprep profile of stringprep defined in &rfc3920;. For example, the usernames for a Legacy Service may be of the form &lt;user@domain&gt;, which would result in an illegal JID such as &lt;user@domain@gateway.example.com&gt;.</p>
    <p>There are two possible ways to solve this problem:</p>
    <ol>
      <li>Use &xep0106;.</li>
      <li>Use the older 'jabber:iq:gateway' protocol (as documented in the following section).</li>
    </ol>
    <p>Gateways and clients SHOULD implement at least one of these protocols; at a minimum, it is RECOMMENDED for gateways and clients to implement the 'jabber:iq:gateway' protocol.</p>
  </section2>
  <section2 topic='The jabber:iq:gateway Protocol' anchor='addressing-iqgateway'>
    <p>The 'jabber:iq:gateway' protocol performs two functions:</p>
    <ol>
      <li><p>It enables a client to determine the text for the "prompt" to show to a Jabber User when the user wants to add a legacy contact to the user's roster (e.g., "Please enter the AOL Screen Name of the person you would like to contact"), as well as the preferred name for the prompted item (e.g., "Screen Name"). To do so, the client sends an empty &lt;query/&gt; element and the gateway returns a &lt;prompt/&gt; element (the name for the prompted item) and optionally a &lt;desc/&gt; element (the text of the prompt itself).</p></li>
      <li><p>It enables a client to send a legacy username to the gateway and receive a properly-formatted JID in return. To do so, the client sends the legacy address to the gateway as the character data of the &lt;prompt/&gt; element and the gateway returns a valid JID as the character data of the &lt;jid/&gt; element.</p></li>
    </ol>
    <p>Both uses are illustrated below.</p>
    <example caption='Client Requests Prompt'><![CDATA[
<iq type='get' to='aim.jabber.org' from='stpeter@jabber.org/roundabout' id='gate1'>
  <query xmlns='jabber:iq:gateway'/>
</iq>
]]></example>
    <example caption='Gateway Returns Prompt'><![CDATA[
  <iq type='result' from='aim.jabber.org' to='stpeter@jabber.org/roundabout' id='gate1'>
    <query xmlns='jabber:iq:gateway'>
      <desc>
        Please enter the AOL Screen Name of the
        person you would like to contact.
      </desc>
      <prompt>Contact ID</prompt>
    </query>
  </iq>
]]></example>
    <p>The following table is intended to assist implementors with mapping of gateway identities to English-language prompt names and text.</p>
    <table caption='Prompt Item Mapping (English)'>
      <tr>
        <th>Legacy Service</th>
        <th>Service Discovery Identity</th>
        <th>Prompt Name</th>
        <th>Prompt Text</th>
      </tr>
      <tr>
        <td>AOL Instant Messenger</td>
        <td>gateway/aim</td>
        <td>Contact ID</td>
        <td>Please enter the AOL Screen Name of the person you would like to contact.</td>
      </tr>
      <tr>
        <td>ICQ</td>
        <td>gateway/icq</td>
        <td>Contact ID</td>
        <td>Please enter the ICQ Number of the person you would like to contact.</td>
      </tr>
      <tr>
        <td>Windows Live Messenger</td>
        <td>gateway/msn <note>The service discovery type was originally defined as "msn" to reflect the name of the service as "MSN Messenger"; this type is retained even though the service has been renamed to "Windows Live Messenger".</note></td>
        <td>Contact ID</td>
        <td>Please enter the Windows Live Messenger address of the person you would like to contact.</td>
      </tr>
      <tr>
        <td>Yahoo! Messenger</td>
        <td>gateway/yahoo</td>
        <td>Contact ID</td>
        <td>Please enter the Yahoo ID of the person you would like to contact.</td>
      </tr>
    </table>
    <p>If the client provides an 'xml:lang' attribute with the IQ-get, the gateway SHOULD return localized prompt names and text if available, or default to English if not available.</p>
    <p>Once the user enters a legacy username or address, the client MUST send it to the gateway as the character data of the &lt;prompt/&gt; element in an IQ-set; the gateway MUST then return a properly-formed JID based on the provided by the client.</p>
    <example caption='Client Provides Legacy Username'><![CDATA[
<iq type='set' to='aim.jabber.org' from='stpeter@jabber.org/roundabout' id='gate1'>
  <query xmlns='jabber:iq:gateway'>
      <prompt>Foo Bar</prompt>
  </query>
</iq>
]]></example>
    <example caption='Gateway Returns JID'><![CDATA[
<iq type='result' from='aim.jabber.org' to='stpeter@jabber.org/roundabout' id='gate1'>
  <query xmlns='jabber:iq:gateway'>
    <jid>FooBar@aim.jabber.org</jid>
  </query>
</iq>
]]></example>
  </section2>
</section1>
<section1 topic='Contact Lists' anchor='rosters'>
  <p>Some legacy services maintain server-side contact lists, which are sent to the gateway when it logs in to the legacy service on behalf of the user. The gateway MAY initiate adding of the legacy contact list items to the user's Jabber roster. Some existing gateways do this by sending a presence stanza of type "subscribed" from the legacy contact's JID (e.g., &lt;LegacyUser@gateway.jabberserver.com&gt;) to the Jabber user; unfortunately, this behavior violates the presence stanza handling rules specified in &rfc6121;. Therefore, a gateway SHOULD instead send the legacy contact list items to the Jabber User via the &xep0144; protocol.</p>
</section1>
<section1 topic='Business Rules' anchor='bizrules'>
  <p>The following business rules apply:</p>
  <ol>
    <li><p>A client SHOULD send a <cite>Service Discovery</cite> request to the gateway (and/or an <cite>Agent Information</cite> request to the gateway's parent) before requesting registration information.</p></li>
    <li><p>A gateway SHOULD support the <cite>Service Discovery</cite> protocol.</p></li>
    <li><p>A gateway SHOULD support the <cite>Agent Information</cite> protocol, although it is deprecated.</p></li>
    <li><p>A gateway SHOULD map, as best it can, the legacy registration fields onto the fields defined for the 'jabber:iq:register' namespace.</p></li>
    <li><p>A gateway SHOULD NOT attempt to emulate offline message storage functionality for legacy services that lack such functionality.</p></li>
    <li>
      <p>Existing gateway implementations do not strictly adhere to the bi-directional nature of Jabber presence notifications, since they do not broadcast presence from the gateway itself to registered users of the gateway, but rather wait for a registered user to send presence to the gateway before sending presence to the user. This sidesteps scalability challenges but may be sub-optimal; while this document does not require existing gateways to change their current behavior, it does RECOMMEND that they broadcast presence notifications to registered users in accordance with the standard Jabber presence model. Specifically:</p>
      <ul>
        <li><p>On startup, a gateway (1) SHOULD send presence to all registered users of that gateway but (2) MAY wait to receive presence changes from each registered user.</p></li>
        <li><p>On shutdown, a gateway SHOULD send unavailable presence to all registered users of the gateway.</p></li>
      </ul>
    </li>
  </ol>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>As defined herein, a gateway is a <em>client proxy</em>, since it "masquerades" as a user on a legacy instant messaging service. In order to act as a client proxy, the gateway logs into the user's account on the legacy service. This implies two things:</p>
  <ul>
    <li>The gateway must gather the legacy credentials from the user, and perhaps store them on the user's behalf.</li>
    <li>The gateway must provide the user's credentials to the legacy service.</li>
  </ul>
  <p>There are obvious security concerns with this approach. The concerns include:</p>
  <ol>
    <li>The user's credentials on the legacy service may be sent in the clear from the gateway to the legacy service if the legacy service does not support channel encryption or strong authentication.</li>
    <li>When the user informs the gateway of the user's legacy credentials, the credentials may be sent in the clear between the user's Jabber client and the user's Jabber server (if client-to-server channel encryption is not enabled) or between the user's Jabber server and the gateway (if the gateway is not in the user's "home" domain and server-to-server channel encryption is not enabled).</li>
    <li>If the gateway stores the user's legacy credentials after registration (this is the default behavior of most or all existing gateway implementations), the user's credentials could be acquired by a malicious user if the server hosting the gateway is compromised.</li>
  </ol>
  <p>There is no foreseeable solution to these concerns, since they are instrinsic to the client proxy model. Some assurance regarding the second and third concerns can be achieved if the user runs his or her own Jabber server and gateways. However, the only true solution is to move beyond the client proxy model, either by using Jabber for all IM communications or to convince legacy IM services to allow federated server-to-server communications using open protocols such as Jabber/XMPP, thus obviating the need for client proxy gateways entirely.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>The &REGISTRAR; includes 'jabber:iq:gateway' in its registry of protocol namespaces.</p>
  </section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='jabber:iq:gateway'
    xmlns='jabber:iq:gateway'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0100: http://www.xmpp.org/extensions/xep-0100.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='query'>
    <xs:complexType>
      <xs:choice>
        <xs:sequence>
          <xs:element name='desc' minOccurs='0' type='xs:string'/>
          <xs:element name='prompt' type='xs:string'/>
        </xs:sequence>
        <xs:element name='jid' type='xs:string'/>
      </xs:choice>
    </xs:complexType>
  </xs:element>

</xs:schema>
]]></code>
</section1>
</xep>