Collection nodes link nodes together to unify notifications from a set of collection or leaf nodes. An entity can subscribe to the collection and receive notifications of any associated leaf nodes.

A collection node can link with any other node in order to create a directed acyclic graph (DAG). Collection nodes MUST NOT be linked in such a way as to produce a cyclic graph (i.e., they cannot link to nodes that eventually link back to the initial node).

Collection nodes only contain other nodes and MUST NOT contain published items (therefore a collection MUST NOT support the "publish" feature or related features such as "persistent-items").

An entity might wish to discover if a service implements collection nodes; in order to do so, it sends a service discovery information ("disco#info") query to the component's JID using &xep0030;. If a service supports collection nodes it MUST return a "pubsub#collections" feature. In addition, if the service supports associating a node with more than one collection it MUST return a feature of "pubsub#multi-collections".

The service discovery items ("disco#items") protocol enables an entity to query a service for a list of associated items, which, in the case of collection nodes would consist of the children associated with a given 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 in XEP-0060, there are two subscription configuration options specific to collection nodes:

• pubsub#subscription_type

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

  If the subscription type is "items", the subscriber shall be notified whenever any node contained in the collection has an item published to it, retracted from it, or the node is purged, 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, removed from the collection, or the configuration of a node within the collection has changed, as modified by the value of the "pubsub#subscription_depth" option.

  If the subscription type is "all", the subscriber shall be notified about both "items" and "nodes" types of events, as modified by the value of the "pubsub#subscription_depth" option.

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

• pubsub#subscription_depth

  This subscription option enables the subscriber to specify how far to traverse the node graph when determining whether a notification will be sent. It may be any integer value, 0 or greater, or the value "all" which means that any node within the collection will generate a notification.

  The default value of this subscription option SHOULD 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).

When an entity requests items on a collection node the service SHOULD return the items on any leaf nodes associated with it subject to the access model of the collection node.

To create a new collection node, the requesting entity MUST include a Data Form containing a "pubsub#node_type" field whose <value/> element contains "collection". The default value for "pubsub#node_type" SHOULD be "leaf".

To provide a starting point for service discovery a service SHOULD support a root node. A root node represents the node belonging to a given service and MUST be identified by the lack of a node identifier (i.e., the address of the pubsub service itself, such as "pubsub.shakespeare.lit"). Because the root node is owned by the service itself an entity SHOULD NOT be allowed create, delete, or configure the root node.

If a node is created or configured without any parents specified, a service MAY automatically associate otherwise orphaned nodes directly to the root node. If a service automatically associates a node with the root it MUST reflect that in the node configuration data form.

Deletion of collection nodes can have a number of side effects due to implementation. Depending on the nature of the collection any of the following MAY happen when a collection node is deleted:

• When the collection node is deleted and the child nodes have no other parents the child nodes are orphaned; meaning that they will have no parent node, but continue to exist.
• When the collection node is deleted and the child nodes have no other parents the child nodes are re-assigned as children of the root node.
• When the collection node is deleted and the child nodes have no other parents the child nodes are also deleted.
• When the collection node is deleted and the child nodes have at least one other node the child nodes MUST remain associated with remaining parent nodes.

Node configuration MUST always reflect the current state of the node graph. Because node configuration contains both a pointer to its parents as well as its children an update to a primary node's "pubsub#collection" value will change the value of the secondary node's "pubsub#children" value, and vice-versa. A service MAY send a notification of the configuration change on the secondary node to subscribers if "pubsub#notify_config" is enabled on the secondary node.

Collection nodes can be used to associate almost any node within the service, but only the access model of the collection node itself is used to determine what an entity is allowed to see. Therefore care should be taken that nodes are not linked in such a way as to leak private data (e.g., from a "closed" leaf node through an "open" collection) unless that behavior is specifically desired.