The XMPP &jep0060; extension ("pubsub") can be used to broadcast state change events associated with a Jabber/XMPP account or user, such as those described in &jep0080;, &jep0107;, &jep0108;, and &jep0118;. Currently, many "extended presence" formats are sent using the &PRESENCE; stanza type; however, this overloads presence, results in unnecessary presence traffic, and does not provide fine-grained control over access. The use of publish-subscribe rather than presence is therefore preferable. However, the full, generic pubsub protocol is often thought of as complicated and therefore has not been widely implemented. To make publish-subscribe functionality more accessible (especially to instant messaging and presence applications that conform to &xmppim;), this document defines simplified protocol semantics that can be followed by instant messaging client and server developers, hopefully resulting in the deployment of personal eventing services across the Jabber/XMPP network.

Note: This document does not show error flows related to the various publish-subscribe use cases referenced herein, since they are exhaustively defined in JEP-0060. The reader is referred to JEP-0060 for all relevant protocol details related to the XMPP publish-subscribe extension.

Personal eventing via pubsub ("PEP") is based on six principles:

1. Every account a pubsub service.
2. One publisher per node.
3. One node per namespace.
4. Use presence.
5. Notifications are filtered based on expressed interests.
6. Smart defaults.

These principles are described more fully below.

This document illustrates PEP through a series of examples that use the following scenario:

1. An owner-publisher juliet@capulet.com who publishes the following information:

   1. Tune information that anyone may see (i.e., an access model of "open")
   2. Activity information that only subscribers to her presence may see (i.e., an access model of "presence")
   3. Geolocation information that only contacts in her "Friends" group may see (i.e., an access model of "roster" with a group of "Friends")
   4. Bookmark information that only the account owner may see (i.e., an access model of "whitelist")

   Note: A PEP node with an access model of "whitelist" and no entities on the whitelist effectively results in a node that enables private data storage; for details, see the Private Data Storage section of this document.

2. Three users who have the following relationship to Juliet:

   1. benvolio@montague.net, who has no subscription to Juliet's presence
   2. nurse@capulet.com, who has a bidirectional subscription to Juliet's presence and who is in the "Servants" group in Juliet's roster
   3. romeo@montague.net, who has a bidirectional subscription to Juliet's presence and who is in the "Friends" group in Juliet's roster

The examples shown in the following sections walk through the protocol flows for node creation, discovery, publishing, and subscribing.

Naturally, before an account owner attempts to complete any PEP use cases, its client SHOULD determine whether the account owner's server supports PEP; to do so, it MUST send a &jep0030; information request to the server:

If a server supports PEP, it MUST return an identity of "pubsub/pep" (as well as a list of the namespaces and other features it supports, including all supported JEP-0060 features):

When an account owner attempts to publish an item to a PEP node and that node does not already exist, the PEP service MUST automatically create the node with default configuration. This similar to the room creation process in JEP-0045: Multi-User Chat. However, if the account owner wishes to create a node with a configuration other than the default (e.g., a node with an access model of "open", "roster", or "whitelist"), the account owner MUST follow the node creation protocol specified in JEP-0060.

For example, Juliet would send the following stanzas in order to create the nodes mentioned above:

A contact MAY send service discovery requests to the account owner's bare JID (&BAREJID;). Although this is not necessary in order to subscribe to the account owner's personal eventing data (as explained in the following section), it is shown here to further illustrate the role of access models.

First, benvolio@montague.net sends a disco#info request to juliet@capulet.com:

If Juliet's server supports PEP (thereby making juliet@capulet.com a virtual pubsub service), it MUST return an identity of "pubsub/pep":

Second, benvolio@montague.net sends a disco#items request to juliet@capulet.com:

The account owner's server MUST check the access model for each of the account owner's PEP nodes and MUST return as service discovery items only those nodes to which the contact is allowed to subscribe or from which the contact is allowed to retrieve items without first subscribing.

Therefore, in this case, the server would return only the "http://jabber.org/protocol/tune" node (since it has an open access model and the contact does not have a presence subscription to the account owner's presence):

Next, nurse@capulet.com sends a disco#items request to juliet@capulet.com:

However, in this case, the server would return the "http://jabber.org/protocol/tune" node (open access model) and the "http://jabber.org/protocol/activity" node (presence access model):

Finally, romeo@montague.net sends a disco#items request to juliet@capulet.com:

In this case, the server would return the "http://jabber.org/protocol/tune" node (open access model) and the "http://jabber.org/protocol/activity" node (presence access model) and the "http://jabber.org/protocol/geoloc" node (roster access model):

If an entity is not subscribed to the account owner's presence, it MUST subscribe to a node using the protocol defined in JEP-0060. For instance, here is how benvolio@montague.net would subscribe Juliet's tune information:

However, when a contact is affiliated with the account owner through a presence subscription, PEP greatly simplifies the subscription process. This is done by associating the presence subscription with a pubsub subscription to the account owner's root collection node (i.e., bare JID), with a subscription_type of "items" and a subscription_depth of "all".

Consider the following presence subscription exchange:

For PEP purposes, this is equivalent to the following pubsub subscription exchange:

Note: Automated pubsub subscriptions MUST be based on the JID contained in the 'from' address of the presence subscription request, which for IM contacts will be a bare JID (&BAREJID;).

An account owner publishes an item to a node by following the protocol specified in JEP-0060:

As a result, the account owner's server generates notifications and sends them to all subscribers who have requested or are interested in the data as described in the Contact Notification Filtering and Generating Notifications sections of this document.

The server MUST set the 'from' address on the notification to the bare JID (&BAREJID;) of the account owner (in this example, "juliet@capulet.com"). When sending notifications to an entity that has a presence subscription to the account owner, the server SHOULD include an &jep0033; "replyto" extension specifying the publishing resource (in this example, "juliet@capulet.com/balcony"); this enables the subscriber's client to differentiate between information received from each of the account owner's resources (for example, different resources may be in different places and therefore may need to specify distinct geolocation data). However, a server MUST NOT include the "replyto" address when sending a notification to an entity that does not have a presence subscription to the account owner. In addition, any errors related to the notification MUST be directed to the JID of the 'from' address on the notification (i.e., the bare JID) so that bounce processing can be handled by the PEP service rather than by the publishing client.

Assuming that all three entities previously mentioned would receive the notifications, the PEP service would generate the following stanzas: