xeps/xep-0330.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>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'>
        <p>
            <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>
        </p>
    </section2>
    
    <section2 topic='Modifiying a subscription of the list' anchor='usecases'>
        <p>
            <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>
        </p>
    </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>