xeps/xep-0330.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
  <!ENTITY subscription "&lt;subscription/&gt;">
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
  <header>
    <title>Pubsub Subscription</title>
    <abstract>This specification describe a method that allow a user to share a list of nodes on which it is Pubsub registered</abstract>
    &LEGALNOTICE;
    <number>0330</number>
    <status>Experimental</status>
    <type>Standards Track</type>
    <sig>Standards</sig>
    <approver>Council</approver>
    <dependencies>
      <spec>XMPP Core</spec>
      <spec>XEP-0001</spec>
      <spec>XEP-0163</spec>
      <spec>XEP-0060</spec>
    </dependencies>
    <supersedes/>
    <supersededby/>
    <shortname>NOT_YET_ASSIGNED</shortname>
    <author>
      <firstname>Christine</firstname>
      <surname>Ho</surname>
      <email>nodpounod@gmail.com</email>
      <jid>christine.ho.dev@gmail.com</jid>
    </author>
    <author>
      <firstname>Timothée</firstname>
      <surname>Jaussoin</surname>
      <email>edhelas@gmail.com</email>
      <jid>edhelas@movim.eu</jid>
    </author>
    <revision>
      <version>0.1</version>
      <date>2013-06-11</date>
      <initials>psa</initials>
      <remark><p>Initial published version approved by the XMPP Council.</p></remark>
    </revision>
    <revision>
      <version>0.0.1</version>
      <date>2013-03-04</date>
      <initials>psa</initials>
      <remark><p>First draft.</p></remark>
    </revision>
  </header>
<section1 topic='Introduction' anchor='intro'>
    <p>
    &xep0060; nodes are commonly used by XMPP users to subscribe to news feeds. This document describe a way, for them, to share some of the nodes to which they have subscribed with other users.
    </p>
    <p>
    The list of &xep0060; subcribed nodes is stored on a classic &xep0163; node qualified by the 'urn:xmpp:subscription' namespace. If an entity wishes to make pubsub subscriptions publicly available then the entity MAY publish them on this node. The entity SHOULD ensure that this information is kept up to date.
    </p>
</section1>
<section1 topic='Protocol' anchor='protocol'>
    <p>Information about the subscribed node is provided by the user client. The subscription container is defined as a classic &subscription; element with theses specific constraints :</p>
    <table caption='attributes'>
        <tr>
            <td><strong>Name</strong></td>
            <td><strong>Type</strong></td>
            <td><strong>Description</strong></td>
            <td><strong>Support</strong></td>
        </tr>
        <tr>
            <td>server</td>
            <td>attribute</td>
            <td>Any server's address</td>
            <td>REQUIRED</td>
        </tr>
        <tr>
            <td>node</td>
            <td>attribute</td>
            <td></td>
            <td>REQUIRED</td>
        </tr>
        <tr>
            <td>id</td>
            <td>node</td>
            <td></td>
            <td>RECOMMENDED</td>
        </tr>
        <tr>
            <td>title</td>
            <td>node</td>
            <td></td>
            <td>OPTIONAL</td>
        </tr>
    </table>
    <section2 topic="Item ID generation method">
        <p>The aim of this XEP is to handle a list of subscriptions. To simplify the managment of this list the ID of the &xep0060; items MUST be generated according to the following method :</p>
        <ol>
            <li>Initialize an empty string S</li>
            <li>Append the name of the server, followed by the '&lt;' character</li>
            <li>Append the name of the node, followed by the '&lt;' character</li>
            <li>Append the jid of the current account</li>
            <li>Compute the ID by hashing the S string using the SHA1 algorythm</li>
        </ol>
        <section3 topic="Generation Example">
            <ol>
                <li>S = ''</li>
                <li>S = 'pubsub.montague.lit&lt;'</li>
                <li>S = 'pubsub.montague.lit&lt;party'</li>
                <li>id = de6c6772ff43d9a604ea78e51ce28b63ab8692eb</li>
            </ol>
        </section3>
    </section2>
</section1>
<section1 topic='Requirements' anchor='reqs'>
    <p>The motivations for this document are to :</p>
    <ul>
        <li>Allow Jabber user's to share their &xep0060; subscriptions</li>
        <li>Add a new way to discover &xep0060; nodes</li>
    </ul>
</section1>
<section1 topic='Glossary' anchor='glossary'>
    <dl>
        <di>
            <dt>Personnal Eventing</dt>
            <dd>A simplified subset of Publish-Subscribe for use in the context of instant messaging and presence applications, whereby each IM user's JID is a virtual pubsub service; for details, see
                <link url='http://xmpp.org/extensions/xep-0163.html'>Personal Eventing Protocol</link>.
            </dd>
        </di>
    </dl>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
  <section2 topic='Requesting the list of subscription' anchor='usecases'>
    <example caption='Requests the list of subscriptions'><![CDATA[
<iq type='get'
    from='romeo@montague.lit'
    to='pubsub.shakespeare.lit'
    id='items1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <items node='urn:xmpp:pubsub:subscription'/>
  </pubsub>
</iq>]]></example>
    </section2>
    <section2 topic='Adding a subscription to the list' anchor='usecases'>
      <example caption='Add a subscription to the list '><![CDATA[
<iq type="set" from="romeo@montague.lit" id="sub123">
<pubsub xmlns="http://jabber.org/protocol/pubsub">
    <publish node="urn:xmpp:pubsub:subscription">
      <item id="0bc0e76cb803b3b107aa369169d8c0d45086f844">
        <subscription xmlns="urn:xmpp:pubsub:subscription:0"
server="pubsub.shakespeare.lit" node="party">
          <title>Party at the Capulets</title>
        </subscription>
      </item>
    </publish>
  </pubsub>
</iq>]]></example>
    </section2>
    <section2 topic='Removing a subscription from the list' anchor='usecases'>
          <example caption='Remove a subscription from the list '><![CDATA[
<iq type='set'
    from='romeo@montague.lit'
    to='pubsub.shakespeare.lit'
    id='unsub1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <retract node='urn:xmpp:pubsub:subscription'>
      <item id='0bc0e76cb803b3b107aa369169d8c0d45086f844'/>
    </retract>
</pubsub>
</iq>]]></example>
    </section2>
    <section2 topic='Modifiying a subscription of the list' anchor='usecases'>
      <example caption='Change the information of a subscription of the list '><![CDATA[
<iq type='set'
    from='romeo@montague.lit'
    to='pubsub.shakespeare.lit'
    id='unsub1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
 <publish node='urn:xmpp:pubsub:subscription'>
      <item id='0bc0e76cb803b3b107aa369169d8c0d45086f844'>
        <subscription xmlns='urn:xmpp:pubsub:subscription:0'
server='pubsub.shakespeare.lit' node='party'>
          <title>Party at the Capulets [canceled !]</title>
        </subscription>
      </item>
</publish>
</pubsub>
</iq>]]></example>
    </section2>
</section1>
<section1 topic='Internationalization Considerations' anchor='i18n'>
  <p>The title element of a &subscription; item SHOULD be in the same language as the contents of the node in question.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>The publication of user tune information is not known to introduce  any new security considerations above and beyond those defined in XEP-0060: Publish-Subscribe.</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'>
  <p>The &REGISTRAR; is requested to issue an initial namespace of "urn:xmpp:pubsub:subscription".</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <p>REQUIRED for protocol specifications.</p>
</section1>
</xep>