XEP-0248: PubSub Collection Nodes

WARNING: Consideration of this document has been Deferred by the XMPP Standards Foundation. Implementation of the protocol described herein is not recommended.

Table of Contents

1. Introduction

Publish-Subscribe [1] defines an XMPP protocol extension for generic publish-subscribe features. This specification defines the nature and handling of collection nodes in XMPP-based publish-subscribe technologies.

A pubsub service MAY support collection nodes as well as leaf nodes. Collections enable nodes to be grouped together in many ways. A collection node MUST contain only leaf nodes and/or other collection nodes (similar to the way in which a file system directory can contain both files and subdirectories) and MUST NOT contain published items (therefore a collection MUST NOT support the "publish" feature or related features such as "persistent-items"). If collections are supported, a service MUST advertise that fact in its "disco#info" responses by including a feature of "pubsub#collections" and MUST support service discovery of child nodes as described in the Discover Nodes section of this document.

2. Node Relationship Models

This section provides background information about collection nodes, with insights from graph theory. [2] The intended result is a clearer vocabulary about particular deployment scenarios. The terminology introduced in this section is used mainly in the discussion of collection node deletion.

In terms of graph theory, the set of nodes hosted at a pubsub service is a directed acyclic graph. [3] The particular graph types can be further described as follows:

1. If there are no collection nodes, we say that the graph is simply a flat set of nodes without connections because there are no arcs between nodes, i.e., no node is the direct predecessor of another node (here we use the less formal phrase that no node is the parent of any other child node).
2. If there may be multiple paths between any two given nodes (where the path may include intermediate collection nodes), the graph is a Directed Acyclic Graph or "DAG" [4] because a given node may be the child of multiple parents.
3. If there is only one path between any two given nodes (where the path may include intermediate collection nodes), the graph is a Tree [5] because a given node may be the child of only one collection node.
4. If there is a root collection node but there are no internal collection nodes, we say informally that the graph has a depth of 1 because all of the connections from leaf nodes to the root collection node are direct (i.e., each connection is an arc); this case is equivalent to a flat set with a root collection node and is typically uninteresting.
5. If there is a root collection node and there are internal collection nodes, we say that the graph has infinite depth because there is an unbounded number of arcs between each leaf node and the root collection node; this case is more interesting than a graph of depth=1 since it enables a wide range of trees and hierarchies.
6. In a tree with collection nodes, deletion of a collection node automatically results in destruction of the arcs to that collection node from leaf nodes or other collection nodes because a child can have only one parent; in this case we say that a child node has a dependency on its parent and that the tree is a Strict Hierarchy. (This is similar to a strictly hierarchical file system, in which deletion of a directory results in deletion of all its file and subdirectories.)
7. In a DAG with collection nodes, deletion of a collection node does not automatically result in destruction of the arcs to that collection node from leaf nodes or other collection nodes because a child can have multiple parents (but if the last parent is deleted, the last remaining arc is destroyed); in this case we say that the tree is a Loose Hierarchy. (This is similar to a loosely hierarchical file system that is mostly hierarchical but that allows multiple soft links.)
8. If a graph is made up of directed acyclic graphs but there is no single root collection node for all the DAGs, we say that the graph is a Dag Set (i.e., a set of directed acyclic graphs).
9. If a graph is made up of trees but there is no single root collection node for all the trees, the graph is a Forest (i.e., a set of trees).
10. If each tree in a forest is a Strict Hierarchy, we say that the graph is a Strict Hierarchy Set.
11. If each DAG in a set is a Loose Hierarchy, we say that the graph is a Loose Hierarchy Set.

Finally, in XMPP pubsub, all graphs are oriented because any two collection nodes cannot have a bidirectional relationship (i.e., if collection node #1 is a direct predecessor of collection node #2 then #2 cannot also be a direct predecessor of #1).

This terminology is summarized in the following table.

3. Subscribe to a Collection Node

A service that implements collection nodes SHOULD allow entities to subscribe to collection nodes (subject to access models and local security policies).

In addition to the subscription configuration options already defined, there are two subscription configuration options specific to collection nodes:

• pubsub#subscription_type

  This subscription option enables the subscriber to subscribe either to items or to nodes.

  If the subscription type is "items", the subscriber shall be notified whenever any node contained in the collection generates a notification (e.g., when an item is published or deleted), as modified by the value of the "pubsub#subscription_depth" option.

  If the subscription type is "nodes", the subscriber shall be notified whenever a new node is added to the collection, as modified by the value of the "pubsub#subscription_depth" option.

  The default value of this subscription option MUST be "nodes".

• pubsub#subscription_depth

  This subscription option enables the subscriber to specify whether it wants to receive notifications only from first-level children of the collection (a value of "1") or from all descendents (a value of "all").

  For subscriptions of type "items", this enables the subscriber to be informed only when an item is published to a leaf node that is a direct child of the collection node to which it has subscribed, or to be informed whenever an item is published to any leaf node in the "tree" that begins at the level of the collection to which it has subscribed.

  For subscriptions of type "nodes", this enables the subscriber to be informed only when a new node is added in the specific collection to which it has subscribed, or to be informed whenever a node is added anywhere in the "tree" that begins at the level of the collection to which it has subscribed.

  The default value of this subscription option MUST be "1".

In order to subscribe to a collection node, an entity MUST send a subscription request to the node; the subscription request MAY include subscription options, but this is not strictly necessary (especially if the entity does not wish to override the default settings for the "pubsub#subscription_type" and "pubsub#subscription_depth" options).

Example 1. Entity subscribes to a collection node (no configuration)

<iq type='set'
    from='francisco@denmark.lit/barracks'
    to='pubsub.shakespeare.lit'
    id='collsub1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe jid='francisco@denmark.lit'
               node='blogs'/>
   </pubsub>
</iq>
    

The subscriber will now receive notification of new first-level nodes created within the "blogs" collection.

Example 2. Entity subscribes to a collection node (with configuration)

<iq type='set'
    from='francisco@denmark.lit/barracks'
    to='pubsub.shakespeare.lit'
    id='collsub2'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe jid='francisco@denmark.lit'
               node='blogs'/>
    <options>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#subscribe_options</value>
        </field>
        <field var='pubsub#subscription_type'>
          <value>items</value>
        </field>
        <field var='pubsub#subscription_depth'>
          <value>all</value>
        </field>
      </x>
   </options>
 </pubsub>
</iq>
    

The subscriber will now receive item notifications from nodes at any depth within the "blogs" collection.

Depending on the nature of the node "tree", a subscription type of "items" and depth of "all" may result in an extremely large number of notifications. Therefore, a service MAY disallow such a combination of subscription options, in which case it MUST return a <not-allowed/> error to the requesting entity.

A service MAY allow an entity to subscribe to a collection node in two ways, once with a subscription of type "nodes" (to receive notification of any new nodes added to the collection or the entire tree) and once with a subscription of type "items" (to receive all items published within the tree). However, a service SHOULD NOT allow an entity to subscribe twice to a collection node (once with a subscription depth of "1" and once with a subscription depth of "all") for the same subscription type, since two such subscriptions are unnecessary (a depth of "all" includes by definition a depth of "1"); in this case the service SHOULD return a <conflict/> error to the requesting entity.

4. Root Collection Node

A service that implements collections SHOULD support a root collection. The root collection shall be identified by the lack of a node identifier (i.e., the address of the pubsub service itself, such as "pubsub.shakespeare.lit").

Subscribing to this node with a subscription of type "nodes" and a depth of "1" enables an entity to be notified whenever a new first-level node is created at the pubsub service. Subscribing to this node with a subscription of type "nodes" and a depth of "all" enables an entity to be notified whenever a new node is created anywhere at the pubsub service.

Example 3. Entity subscribes to the root collection node

<iq type='set'
    from='francisco@denmark.lit/barracks'
    to='pubsub.shakespeare.lit'
    id='root1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe jid='francisco@denmark.lit'/>
 </pubsub>
</iq>
    

If the root collection node is configured to send notification of node associations and disassociations, the service shall send an event that contains a <collection/> element whose 'node' attribute specifies the NodeID of the collection (in this case the NodeID is empty to signify that the collection is the root collection); this element in turn contains an <associate/> element whose 'node' attribute specifies the NodeID of node that has been associated with the collection.

Example 4. Notification of node association

<message from='pubsub.shakespeare.lit'
         to='francisco@denmark.lit'
         id='newnode1'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <collection node='some-collection'>
      <associate node='new-node-id'/>
    </collection>
  </event>
</message>
    

The notification event MAY also include the node meta-data, formatted using the Data Forms protocol.

Example 5. Notification of node association

<message from='pubsub.shakespeare.lit'
         to='francisco@denmark.lit'
         id='newnode2'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <collection node=''>
      <associate node='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>
          </field>
          <field var='pubsub#creation_date'><var>2003-07-29T22:56Z</var></field>
          <field var='pubsub#creator'><var>hamlet@denmark.lit</var></field>
          <field var='pubsub#description'><var>Atom feed for my blog.</var></field>
          <field var='pubsub#language'><var>en</var></field>
          <field var='pubsub#contact'><value>bard@shakespeare.lit</value></field>
          <field var='pubsub#owner'><value>hamlet@denmark.lit</value></field>
          <field var='pubsub#title'><var>Princely Musings (Atom).</var></field>
          <field var='pubsub#type'><value>http://www.w3.org/2005/Atom</value></field>
        </x>
      </node>
    </collection>
  </event>
</message>
    

5. Create a New Collection Node

To create a new collection node, the requesting entity MUST include a Data Form containing a 'pubsub#node_type' field whose <value/> is "collection".

Example 6. Entity requests a new collection node

<iq type='set'
    from='bard@shakespeare.lit/globe'
    to='pubsub.shakespeare.lit'
    id='create3'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='announcements'/>
    <configure>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#node_config</value>
        </field>
        <field var='pubsub#node_type'><value>collection</value></field>
      </x>
    </configure>
  </pubsub>
</iq>
    

Example 7. Service responds with success

<iq type='result'
    from='pubsub.shakespeare.lit'
    to='bard@shakespeare.lit/globe'
    id='create3'/>
    

In addition to the errors already defined for leaf node creation, there are several reasons why the collection node creation request might fail:

1. The service does not support collection nodes.
2. The service does not support creation of collection nodes.
3. The requesting entity does not have sufficient privileges to create collection nodes.

These error cases are described more fully in the following sections.

If the service does not support collection nodes, it MUST respond with a <feature-not-implemented/> error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "collections".

Example 8. Service does not support collection nodes

<iq type='error'
    from='hamlet@denmark.lit/elsinore'
    to='pubsub.shakespeare.lit'
    id='config1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
    <configure node='princely_musings'/>
  </pubsub>
  <error type='cancel'>
    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
                 feature='collections'/>
  </error>
</iq>
    

If the service supports collection nodes but does not allow new collection nodes to be created, it MUST respond with a <not-allowed/> error.

Example 9. Service does not allow creation of collection nodes

<iq type='error'
    from='hamlet@denmark.lit/elsinore'
    to='pubsub.shakespeare.lit'
    id='config1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
    <configure node='princely_musings'/>
  </pubsub>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

If the requesting entity has insufficient privileges to create new collections, the service MUST respond with a <forbidden/> error.

Example 10. Requesting entity has insufficient privileges to create collection nodes

<iq type='error'
    from='pubsub.shakespeare.lit'
    to='hamlet@denmark.lit/elsinore'
    id='config1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
    <configure node='princely_musings'/>
  </pubsub>
  <error type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

A service MAY offer some node configuration options that are specific to collection nodes and not provided in configuration forms related to leaf nodes. The following are RECOMMENDED:

• pubsub#children_association_policy -- the policy regarding who may associate child nodes with the collection (values: all, owner, whitelist).
• pubsub#children_association_whitelist -- the whitelist of entities that may associate child nodes with the collection.
• pubsub#children_max -- the maximum number of child nodes that may be associated with a collection.

6. Create a Node Associated with a Collection

<iq type='set'
    from='bard@shakespeare.lit/globe'
    to='pubsub.shakespeare.lit'
    id='create4'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='plays'/>
    <configure>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='pubsub#collection'><value>announcements</value></field>
      </x>
    </configure>
  </pubsub>
</iq>
      

<iq type='error'
    from='pubsub.shakespeare.lit'
    to='bard@shakespeare.lit/globe'
    id='create4'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='plays'/>
    <configure>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='pubsub#collection'>
          <value>announcements</value>
          <value>news</value>
        </field>
        <field var='pubsub#node_type'>
          <value>collection</value>
        </field>
      </x>
    </configure>
  </pubsub>
  <error type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
        

<iq type='error'
    from='pubsub.shakespeare.lit'
    to='bard@shakespeare.lit/globe'
    id='create4'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='plays'/>
    <configure>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='pubsub#collection'><value>announcements</value></field>
      </x>
    </configure>
  </pubsub>
  <error type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
        

<iq type='error'
    from='pubsub.shakespeare.lit'
    to='bard@shakespeare.lit/globe'
    id='create4'>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <max-nodes-exceeded xmlns='http://jabber.org/protocol/pubsub#errors'/>
  </error>
</iq>
        

<iq type='error'
    from='pubsub.shakespeare.lit'
    to='bard@shakespeare.lit/globe'
    id='create4'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='plays'/>
    <configure>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='pubsub#collection'><value>announcements</value></field>
      </x>
    </configure>
  </pubsub>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
        

<iq type='error'
    from='pubsub.shakespeare.lit'
    to='bard@shakespeare.lit/globe'
    id='create4'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='plays'/>
    <configure>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='pubsub#collection'><value>announcements</value></field>
      </x>
    </configure>
  </pubsub>
  <error type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
        

7. Collection Node Deletion

Deletion of a collection node can introduce a large number of changes to the system, depending on the node relationship model of the deployed system. This section describes recommended handling of deletion requests in the context of collection nodes.

<iq type='error'
    from='pubsub.shakespeare.lit'
    to='hamlet@denmark.lit/elsinore'
    id='delete1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
    <delete/>
  </pubsub>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    

8. Associate an Existing Node with a Collection

Although a node can be associated with a collection when it is created (as described above), it can also be associated with a collection after it has been created. This can be done in two ways:

• By modifying the node's "pubsub#collection" configuration field.
• By modifying the collection node's "pubsub#children" configuration field.

These methods are described below.

In order to modify the (child) node's "pubsub#collection" configuration field, the owner of the node shall submit a request to edit the node's configuration, receive a configuration form from the service, and then submit a modified configuration form:

Example 18. Node owner modifies node configuration

<iq type='set'
    from='hamlet@denmark.lit/elsinore'
    to='pubsub.shakespeare.lit'
    id='associate1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
    <configure node='princely_musings'>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#node_config</value>
        </field>
        ...
        <field var='pubsub#collection'><value>blogs</value></field>
        ...
      </x>
    </configure>
  </pubsub>
</iq>
    

Note: To associate a node with the root collection node, the node owner MUST submit an empty <value/> element within the 'pubsub#collection' field.

In order to modify the (parent) node's "pubsub#children" configuration field, the owner of the node shall submit a request to edit the node's configuration, receive a configuration form from the service, and then submit a modified configuration form:

Example 19. Node owner modifies node configuration

<iq type='set'
    from='bard@shakespeare.lit/globe'
    to='pubsub.shakespeare.lit'
    id='associate2'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
    <configure node='blogs'>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#node_config</value>
        </field>
        ...
        <field var='pubsub#children'>
          <value>princely_musings</value>
          <value>kingly_ravings</value>
          <value>starcrossed_stories</value>
          <value>moorish_meanderings</value>
        </field>
        ...
      </x>
    </configure>
  </pubsub>
</iq>
    

If the collection node is configured to send notification of node associations and disassociations, the service shall send an event that contains a <collection/> element whose 'node' attribute specifies the NodeID of the collection; this element in turn contains an <associate/> element whose 'node' attribute specifies the NodeID of node that has been associated with the collection.

Example 20. Notification of node association

<message from='pubsub.shakespeare.lit'
         to='francisco@denmark.lit'
         id='newnode3'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <collection node='some-collection'>
      <associate node='new-node-id'/>
    </collection>
  </event>
</message>
    

If an entity attempts to associate a node with a collection in a way that would violate the node relationship model (e.g., adding a second parent to a node in a Tree or Strict Hierarchy or making a child a new parent of its existing parent or other predecessor and thus violating the orientation of the graph), the service MUST return a <conflict/> error.

9. Disassociate a Node from a Collection

A node can be disassociated from a collection after it has been associated (whether at creation time or afterward). This can be done in two ways:

• By modifying the node's "pubsub#collection" configuration field.
• By modifying the collection node's "pubsub#children" configuration field.

These methods are described below.

In order to modify the (child) node's "pubsub#collection" configuration field, the owner of the node shall submit a request to edit the node's configuration, receive a configuration form from the service, and then submit a modified configuration form:

Example 21. Node owner modifies node configuration

<iq type='set'
    from='hamlet@denmark.lit/elsinore'
    to='pubsub.shakespeare.lit'
    id='associate1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
    <configure node='princely_musings'>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#node_config</value>
        </field>
        ...
        <field var='pubsub#collection'></field>
        ...
      </x>
    </configure>
  </pubsub>
</iq>
    

Note: To disassociate the node from all collection nodes, the node owner MUST submit an empty <field/> element for the 'pubsub#collection' field as shown in the foregoing example.

Note: To disassociate the node from the root collection node, the node owner MUST submit an empty <value/> element within the 'pubsub#collection' field as shown in the foregoing example.

In order to modify the (parent) node's "pubsub#children" configuration field, the owner of the node shall submit a request to edit the node's configuration, receive a configuration form from the service, and then submit a modified configuration form:

Example 22. Node owner modifies node configuration

<iq type='set'
    from='bard@shakespeare.lit/globe'
    to='pubsub.shakespeare.lit'
    id='associate2'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
    <configure node='blogs'>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#node_config</value>
        </field>
        ...
        <field var='pubsub#children'>
          <value>kingly_ravings</value>
          <value>starcrossed_stories</value>
          <value>moorish_meanderings</value>
        </field>
        ...
      </x>
    </configure>
  </pubsub>
</iq>
    

If the collection node is configured to send notification of node associations and disassociations, the service shall send an event that contains a <collection/> element whose 'node' attribute specifies the NodeID of the collection; this element in turn contains a <disassociate/> element whose 'node' attribute specifies the NodeID of node that has been disassociated from the collection.

Example 23. Notification of node disassociation

<message from='pubsub.shakespeare.lit'
         to='francisco@denmark.lit'
         id='oldnode1'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <collection node='some-collection'>
      <disassociate node='new-node-id'/>
    </collection>
  </event>
</message>
    

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.

Note: The combination of associating a node with one collection and disassociating the same node from another collection can be used to move a node from one collection to another.

10. Requesting Collection Node Configuration

The default configuration options can be different for a collection node vs. a leaf node. In order to specifically request the default configuration options for collection nodes, an entity MUST include a Data Form with a 'pubsub#node_type' field whose value is "collection" in the request (since the default value for the 'pubsub#node_type' field is "leaf").

Example 24. Entity requests default configuration options for collection nodes

<iq type='get'
    from='hamlet@denmark.lit/elsinore'
    id='def2'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
    <default>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#node_config</value>
        </field>
        <field var='pubsub#node_type'><value>collection</value></field>
      </x>
    </default>
  </pubsub>
</iq>
      

If the service does not support collection nodes, it MUST return a <feature-not-implemented/> error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "collections".

Example 25. Service does not support collection nodes

<iq type='error'
    from='pubsub.shakespeare.lit'
    to='hamlet@denmark.lit/elsinore'
    id='def2'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
    <default>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#node_config</value>
        </field>
        <field var='pubsub#node_type'><value>collection</value></field>
      </x>
    </default>
  </pubsub>
  <error type='cancel'>
    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <unsupported xmlns='http://jabber.org/protocol/pubsub#errors'
                 feature='collections'/>
  </error>
</iq>
      

11. Generating Publish Notifications for Collections

If an item is published to a node which is also included by a collection, and an entity is subscribed to that collection with a subscription type of "items", then the notifications generated by the service MUST contain additional information. The <items/> element contained in the notification message MUST specify the node identifier of the node that generated the notification (not the collection) and the <item/> element MUST contain a SHIM header that specifies the node identifier of the collection.

Example 26. Subscribers receive notifications from a collection

<message to='francisco@denmark.lit' from='pubsub.shakespeare.lit'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='princely_musings'>
      <item id='ae890ac52d0df67ed7cfdf51b644e901'>
        ...
      </item>
    </items>
  </event>
  <headers xmlns='http://jabber.org/protocol/shim'>
    <header name='Collection'>blogs</header>
  </headers>
</message>

<message to='bernardo@denmark.lit' from='pubsub.shakespeare.lit'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='princely_musings'>
      <item id='ae890ac52d0df67ed7cfdf51b644e901'>
        ...
      </item>
    </items>
  </event>
  <headers xmlns='http://jabber.org/protocol/shim'>
    <header name='Collection'>blogs</header>
  </headers>
</message>
.
.
.
    

Note: The delivery options (such as "pubsub#deliver_payloads") are determined by the publishing leaf node, not by the aggregating collection node. If the owner of a collection node sets delivery options for a collection node, the service SHOULD ignore those options and apply the options set for the leaf node that publishes an item.

12. Security Considerations

REQUIRED.

13. IANA Considerations

REQUIRED.

14. XMPP Registrar Considerations

REQUIRED.

15. XML Schema

REQUIRED for protocol specifications.

Appendices

Appendix A: Document Information

Series: XEP
Number: 0248
Publisher: XMPP Standards Foundation
Status: Deferred
Type: Standards Track
Version: 0.1
Last Updated: 2008-08-11
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0060
Supersedes: None
Superseded By: None
Short Name: NOT_YET_ASSIGNED
Source Control: HTML  RSS
This document in other formats: XML  PDF

Appendix B: Author Information

Appendix C: Legal Notices

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes

Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

END