1.11pre1

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1674 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0060.xml

@@ -48,6 +48,13 @@
   &stpeter;
   &ralphm;
 
+  <revision>
+    <version>1.11pre1</version>
+    <date>in progress, last updated 2008-02-13</date>
+    <initials>rm/psa</initials>
+    <remark><p>For collection nodes, changed name of node child element to associate and added disassociate child element to handle disassociation use case; corrected SHIM examples to conform to XEP-0131.</p></remark>
+  </revision>
+
   <revision>
     <version>1.10</version>
     <date>2007-09-26</date>
@@ -442,6 +449,7 @@ And by opposing end them?
 
   <section2 topic='Affiliations' anchor='affiliations'>
     <p>To manage permissions, the protocol defined herein uses a hierarchy of affiliations, similiar to those introduced in &xep0045;.</p>
+    <p>All affiliations MUST be based on a bare JID &BAREJID; instead of a full JID &FULLJID;.</p>
     <p>Support for the "owner" and "none" affiliations is REQUIRED. Support for all other affiliations is RECOMMENDED. For each non-required affiliation supported by an implementation, it SHOULD return a service discovery feature of "name-affiliation" where "name" is the name of the affiliation, such as "member", "outcast", or "publisher" (see the <link url='#features'>Feature Summary</link>). Particular kinds of pubsub services MAY enforce additional requirements (e.g., requiring support for a given non-required affiliation or for all affiliations).</p>
     <table caption='Affiliations and their Privileges'>
       <tr>
@@ -929,7 +937,7 @@ And by opposing end them?
   </pubsub>
 </iq>
     ]]></example>
-    <p>If the service returns a list of subscriptions, it MUST return all subscriptions for all JIDs that match the bare JID (&BAREJID;) portion of the 'from' attribute on the request.</p>
+    <p>If the service returns a list of subscriptions, it MUST return all subscriptions for all JIDs that match the bare JID &BAREJID; portion of the 'from' attribute on the request.</p>
     <p>For each subscription, a &lt;subscription/&gt; element is returned specifying the NodeID, the JID that is affiliated (which MAY include a resource, depending on how the entity subscribed), and the current subscription state. If subscription identifiers are supported by the service, the 'subid' attribute MUST be present as well.</p>
     <example caption='Service returns all current subscriptions'><![CDATA[
 <iq type='result'
@@ -987,7 +995,7 @@ And by opposing end them?
   </pubsub>
 </iq>
     ]]></example>
-    <p>If the service returns a list of affiliations, it MUST return all affiliations for all JIDs that match the bare JID (&BAREJID;) portion of the 'from' attribute on the request.</p>
+    <p>If the service returns a list of affiliations, it MUST return all affiliations for all JIDs that match the bare JID &BAREJID; portion of the 'from' attribute on the request.</p>
     <p>For each affiliation, an &lt;affiliation/&gt; element is returned containing the NodeID and the affiliation state (owner, publisher, or outcast).</p>
     <example caption='Service replies with all current affiliations'><![CDATA[
 <iq type='result'
@@ -1040,7 +1048,7 @@ And by opposing end them?
 
   <section2 topic='Subscribe to a Node' anchor='subscriber-subscribe'>
     <section3 topic='Request' anchor='subscriber-subscribe-request'>
-      <p>When a Jabber entity wishes to subscribe to a node, it sends a subscription request to the pubsub service. The subscription request is an IQ-set where the &lt;pubsub/&gt; element contains one and only one &lt;subscribe/&gt; element. The &lt;subscribe/&gt; element SHOULD possess a 'node' attribute specifying the node to which the entity wishes to subscribe. The &lt;subscribe/&gt; element MUST also possess a 'jid' attribute specifying the exact XMPP address to be used as the subscribed JID -- often a bare JID (&BAREJID;) or full JID (&FULLJID;), although JIDs of the form &DOMAIN; or &DOMAINRES; may subscribe as well.</p>
+      <p>When a Jabber entity wishes to subscribe to a node, it sends a subscription request to the pubsub service. The subscription request is an IQ-set where the &lt;pubsub/&gt; element contains one and only one &lt;subscribe/&gt; element. The &lt;subscribe/&gt; element SHOULD possess a 'node' attribute specifying the node to which the entity wishes to subscribe. The &lt;subscribe/&gt; element MUST also possess a 'jid' attribute specifying the exact XMPP address to be used as the subscribed JID -- often a bare JID &BAREJID; or full JID &FULLJID;.</p>
       <p>Here is an example of a subscription request.</p>
       <example caption='Entity subscribes to a node'><![CDATA[
 <iq type='set'
@@ -4654,26 +4662,26 @@ And by opposing end them?
  </pubsub>
 </iq>
     ]]></example>
-    <p>In order to send notification of new nodes, the service shall send an event that contains a &lt;collection/&gt; element that in turns contains a &lt;node/&gt; element whose 'id' attribute specifies the NodeID of the new node.</p>
+    <p>In order to send notification of node associations and disassociations, the service shall send an event that contains a &lt;collection/&gt; element that in turns contains an &lt;associate/&gt; element whose 'id' attribute specifies the NodeID of the new node.</p>
-    <example caption='Notification of new node'><![CDATA[
+    <example caption='Notification of node association'><![CDATA[
 <message from='pubsub.shakespeare.lit'
          to='francisco@denmark.lit'
          id='newnode1'>
   <event xmlns='http://jabber.org/protocol/pubsub#event'>
     <collection>
-      <node id='new-node-id'>
+      <associate id='new-node-id'>
     </collection>
   </event>
 </message>
     ]]></example>
     <p>The notification event MAY also include the node meta-data, formatted using the <strong>Data Forms</strong> protocol.</p>
-    <example caption='Notification of new node'><![CDATA[
+    <example caption='Notification of node association'><![CDATA[
 <message from='pubsub.shakespeare.lit'
          to='francisco@denmark.lit'
          id='newnode2'>
   <event xmlns='http://jabber.org/protocol/pubsub#event'>
     <collection>
-      <node id='new-node-id'>
+      <associate id='new-node-id'>
         <x xmlns='jabber:x:data' type='result'>
           <field var='FORM_TYPE' type='hidden'>
             <value>http://jabber.org/protocol/pubsub#meta-data</value>
@@ -4981,6 +4989,18 @@ And by opposing end them?
   </pubsub>
 </iq>
     ]]></example>
+    <p>If the collection node is configured to send notification of node associations and disassociations, the service shall send an event that contains a &lt;collection/&gt; element that in turns contains an &lt;associate/&gt; element whose 'id' attribute specifies the NodeID of the new node.</p>
+    <example caption='Notification of node association'><![CDATA[
+<message from='pubsub.shakespeare.lit'
+         to='francisco@denmark.lit'
+         id='newnode1'>
+  <event xmlns='http://jabber.org/protocol/pubsub#event'>
+    <collection>
+      <associate id='new-node-id'>
+    </collection>
+  </event>
+</message>
+    ]]></example>
   </section2>
 
   <section2 topic='Disassociate a Node from a Collection' anchor='collections-disassociate'>
@@ -5034,6 +5054,18 @@ And by opposing end them?
     </configure>
   </pubsub>
 </iq>
+    ]]></example>
+    <p>If the collection node is configured to send notification of node associations and disassociations, the service shall send an event that contains a &lt;collection/&gt; element that in turns contains an &lt;disassociate/&gt; element whose 'id' attribute specifies the NodeID of the new node.</p>
+    <example caption='Notification of node disassociation'><![CDATA[
+<message from='pubsub.shakespeare.lit'
+         to='francisco@denmark.lit'
+         id='oldnode1'>
+  <event xmlns='http://jabber.org/protocol/pubsub#event'>
+    <collection>
+      <disassociate id='new-node-id'>
+    </collection>
+  </event>
+</message>
     ]]></example>
     <p>If a node is disassociated from a collection node and a new association is not formed, the implementation MAY associate the node with the root collection node or associate it with no collection node.</p>
     <p>Note: The combination of associating and disassociating a node with a collection can be used to move a node from one collection to another.</p>
@@ -5047,12 +5079,12 @@ And by opposing end them?
     <items node='princely_musings'>
       <item id='ae890ac52d0df67ed7cfdf51b644e901'>
         ...
-        <headers xmlns='http://jabber.org/protocol/shim'>
-          <header name='pubsub#collection'>blogs</header>
-        </headers>
       </item>
     </items>
   </event>
+  <headers xmlns='http://jabber.org/protocol/shim'>
+    <header name='pubsub#collection'>blogs</header>
+  </headers>
 </message>
 
 <message to='bernardo@denmark.lit' from='pubsub.shakespeare.lit'>
@@ -5060,12 +5092,12 @@ And by opposing end them?
     <items node='princely_musings'>
       <item id='ae890ac52d0df67ed7cfdf51b644e901'>
         ...
-        <headers xmlns='http://jabber.org/protocol/shim'>
-          <header name='pubsub#collection'>blogs</header>
-        </headers>
       </item>
     </items>
   </event>
+  <headers xmlns='http://jabber.org/protocol/shim'>
+    <header name='pubsub#collection'>blogs</header>
+  </headers>
 </message>
 .
 .
@@ -5075,7 +5107,7 @@ And by opposing end them?
 </section1>
 
 <section1 topic='IM Account Integration' anchor='presence'>
-  <p>Publish-subscribe functionality can be integrated into existing instant messaging and presence services (see <cite>RFC 3921</cite>), such that each registered account functions as a virtual pubsub service (sometimes called "pubsub-on-a-JID"). In such deployments, the root pubsub node for each virtual pubsub service has the same address as the bare JID (&BAREJID;) of the account, which is typically associated with an IM user (e.g., &lt;hamlet@denmark.lit&gt;). Since an IM user typically has a roster of "buddies" and shares presence information with those buddies, the virtual pubsub service can use roster and presence information to provide some helpful shortcuts for subscribers, in particular the auto-subscribe and filtered-notifications features described in this section.</p>
+  <p>Publish-subscribe functionality can be integrated into existing instant messaging and presence services (see <cite>RFC 3921</cite>), such that each registered account functions as a virtual pubsub service (sometimes called "pubsub-on-a-JID"). In such deployments, the root pubsub node for each virtual pubsub service has the same address as the bare JID &BAREJID; of the account, which is typically associated with an IM user (e.g., &lt;hamlet@denmark.lit&gt;). Since an IM user typically has a roster of "buddies" and shares presence information with those buddies, the virtual pubsub service can use roster and presence information to provide some helpful shortcuts for subscribers, in particular the auto-subscribe and filtered-notifications features described in this section.</p>
   <p>Note: Because the account owner's bare JID functions as a virtual pubsub service, it is OPTIONAL for the owner to include a 'to' address when sending publish requests and completing other publisher and owner use cases. That is, when the IM server receives a pubsub-related IQ stanza of type "get" or "set" from one of the account owner's resources, the server MUST consider the stanza to be addressed to the account owner's bare JID even if the IQ stanza does not include a 'to' address.</p>
   <section2 topic='Auto-Subscribe' anchor='auto-subscribe'>
     <p>When a contact is affiliated with the account owner through sharing of XMPP presence, the "auto-subscribe" feature greatly simplifies the subscription process. In particular, support for the "auto-subscribe" has the following implications:</p>
@@ -5083,16 +5115,16 @@ And by opposing end them?
       <p>Because the account owner itself is implicitly subscribed to its own XMPP presence (e.g., each XMPP resource receives presence information from all of the account owner's resources), a service MUST consider the account owner to have a pubsub subscription to the account owner's root collection node with a subscription_type of "items" and a subscription_depth of "all". This is true for all access models.</p>
     </section3>
     <section3 topic='Presence Subscriber' anchor='auto-subscribe-contact'>
-      <p>If an entity (i.e., an IM contact) has an XMPP presence subscription to the account owner's bare JID (&BAREJID;), a service MUST consider the contact to have a pubsub subscription to the account owner's root collection node with a subscription_type of "items" and a subscription_depth of "all" if:</p>
+      <p>If an entity (i.e., an IM contact) has an XMPP presence subscription to the account owner's bare JID &BAREJID;, a service MUST consider the contact to have a pubsub subscription to the account owner's root collection node with a subscription_type of "items" and a subscription_depth of "all" if:</p>
       <ol>
         <li>The node has an access model of "open".</li>
         <li>The node has an access model of "presence".</li>
         <li>The node has an access model of "roster" and the contact is in the specified roster group.</li>
       </ol>
-      <p>Note: When an IM contact has a subscription to the account owner's presence, the automated pubsub subscription MUST be based on the JID contained in the 'from' address of the presence subscription request, which for an IM contact will be a bare JID (&BAREJID;).</p>
+      <p>Note: When an IM contact has a subscription to the account owner's presence, the automated pubsub subscription MUST be based on the JID contained in the 'from' address of the presence subscription request, which for an IM contact will be a bare JID &BAREJID;.</p>
     </section3>
     <section3 topic='Presence Sharer' anchor='auto-subscribe-directed'>
-      <p>If the node has an open access model, the pubsub service SHOULD also consider an entity to be (temporarily) subscribed to the node if the entity sends presence to the account owner in the absence of a presence subscription. In this case, the subscription SHOULD be based on the 'from' address of the presence stanza, which will be a full JID (&FULLJID;). When the service receives unavailable presence from the full JID, it MUST consider cancel the (temporary) subscription.</p>
+      <p>If the node has an open access model, the pubsub service SHOULD also consider an entity to be (temporarily) subscribed to the node if the entity sends presence to the account owner in the absence of a presence subscription. In this case, the subscription SHOULD be based on the 'from' address of the presence stanza, which will be a full JID &FULLJID;. When the service receives unavailable presence from the full JID, it MUST consider cancel the (temporary) subscription.</p>
     </section3>
   </section2>
   <section2 topic='Filtered Notifications' anchor='filtered-notifications'>
@@ -7009,9 +7041,10 @@ xmpp:pubsub.shakespeare.lit?pubsub;action=unsubscribe;node=princely_musings
 
   <xs:element name='collection'>
     <xs:complexType>
-      <xs:sequence minOccurs='1'>
+      <xs:choice>
-        <xs:element ref='node'/>
+        <xs:element ref='associate'/>
-      </xs:sequence>
+        <xs:element ref='disassociate'/>
+      </xs:choice>
       <xs:attribute name='node' type='xs:string' use='optional'/>
     </xs:complexType>
   </xs:element>