Defined atomic publish+configure action for use on first publish; added friendly but non-normative How It Works section to introduction; tightened up definition of normative sections; explicitly defined auto-create and publish-and-configure features.
The XMPP &xep0060; extension ("pubsub") can be used to broadcast state change events associated with a Jabber/XMPP account or user, such as those described in &xep0080;, &xep0107;, &xep0108;, and &xep0118;.
Note: This document does not show error flows related to the various publish-subscribe use cases referenced herein, since they are exhaustively defined in XEP-0060. The reader is referred to XEP-0060 for all relevant protocol details related to the XMPP publish-subscribe extension.
+Personal eventing provides a way for a Jabber/XMPP user to send updates or "events" to other users, who are typically contacts in the user's roster. An event can be anything that a user wants to make known to other people, such as those described in &xep0080;, &xep0107;, &xep0108;, and &xep0118;. While the XMPP &xep0060; extension ("pubsub") can be used to broadcast such events associated, the full pubsub protocol is often thought of as complicated and therefore has not been widely implemented.
+
This section provides a friendly, non-normative introduction to the workings of personal eventing via pubsub (PEP).
+There are two sides to personal eventing: what the user does to generate events and what the contact does to receive events. As shown in the following examples, both are simplified in PEP as compared to generic pubsub.
+Imagine that you are a Shakespearean character named Juliet and that you want to generate the following kinds of events that may be of interest to other people:
+We assume that there are three other users who have the following relationship to you:
+We also assume that your server (montague.net) supports PEP and that your client discovered that support when you logged in.
+Now you start playing a song on your music playing software. Your client captures that "event" and publishes it to your server:
+Note the following about your publish request:
+If all goes well (see Publishing Events), everyone who is interested in what you are listening to will receive notification of the event:
+But how do Romeo and the Nurse tell your server that they are interested in knowing what you're listening to? In generic pubsub they need to explicitly subscribe to your "http://jabber.org/protocol/tune" node.
Your server knows to send tune information to Romeo not directly because his client advertises an 'ext' value of "sendmetunes" (the 'ext' values have no semantic meaning in XEP-0115) but because the disco#info response from the "http://www.chatopus.com/ec#sendmetunes" node advertises a feature of "http://jabber.org/protocol/tune+notify", where the "+notify" suffix indicates interest in the protocol that precedes the suffix:
+Naturally your server doesn't need to send out a disco#info request every time, since it will quickly create a large cache of such extensions!
+So that's the general idea. We'll demonstrate it again with an example of geolocation...
+First your client generates a geolocation event:
+Then your server sends event notifications, this time addressing the event only to Romeo, since the Nurse is not in your Friends roster group:
+And your server knows to send the geolocation notification to Romeo because (1) he is in your Friends group and (2) his client advertised interest in "http://jabber.org/protocol/geolocation" events.
+Personal eventing via pubsub ("PEP") is based on six principles:
+Personal eventing via pubsub ("PEP") is based on the following principles:
These principles are described more fully below.
Most pubsub configuration options and metadata are not needed for personal eventing. Instead, PEP services offer smart defaults to simplify node creation and management.
A client should be able to publish an item without having to worry about whether the node exists; if the node does not exist, the server simply creates the node automatically and applies the specified configuration.
+This document illustrates PEP through a series of examples that use the following scenario:
-An owner-publisher juliet@capulet.com who publishes the following information:
-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.
-Three users who have the following relationship to Juliet:
-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 &xep0030; 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 XEP-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.
For example, Juliet would send the following stanzas in order to create the nodes mentioned above:
-An account owner publishes an item to a node by following the protocol specified in XEP-0060:
+If the node does not already exist, the PEP service MUST create the node (see fire and forget). This "auto-create" feature MUST be supported by a PEP service, but support for the feature is OPTIONAL on the part of a generic pubsub service. (Naturally, the account owner's client MAY follow the node creation use case specified in XEP-0060 before attempting to publish an item.)
+Because PEP nodes may be automatically created, a client MAY specify the desired node configuration along with the publish request:
+The PEP service MUST process such a request in accordance with the rules shown in the table below. This "publish-and-configure" feature MUST be supported by a PEP service, but support for the feature is OPTIONAL on the part of a generic pubsub service.
+| Case | +Result | +
|---|---|
| The node does not exist and the publish request does not include a <configure/> element. | +The node is automatically created with default configuration (which for PEP nodes MUST be the presence access model) and the item is published. | +
| The node does not exist and the publish request includes a <configure/> element. | +The node is automatically created with the specified configuration and the item is published. | +
| The node exists and the publish request does not include a <configure/> element. | +The item is published and the node configuration is not modified. | +
| The node exists and the publish request includes a <configure/> element. | +If the specified configuration matches the existing node configuration, the item is published and the node configuration is not modified. If the specified configuration does not match the existing node configuration, the server returns a &conflict; error to the account owner (with an application-specific error of <config-does-not-match/>), the item is not published, and the node configuration is not modified. | +
If the publication logic dictates that event notifications shall be sent, the account owner's server generates notifications and sends them to all appropriate entities as described in the Receiving Event Notifications section of this document, as well as to any of the account owner's available resources.
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 XEP-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:
-An entity shall receive event notifications if:
+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:
-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 XEP-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, as well as to any of the account owner's available resources.
-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 &xep0033; "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:
-Note the 'to' addresses: the notification to Benvolio is addressed to "benvolio@montague.net" (bare JID) since the PEP service does not have presence information about the subscriber, whereas the notifications to the Nurse and to Romeo are addressed to the full JIDs of those subscribers.
-A contact may not want to receive notifications for all payload types. A contact SHOULD signal its preferences to the account owner's server by including XEP-0115 information that specifies the namespaces for which the contact wishes to receive notifications (if any).
-In order to make this possible, all possible payload namespaces can be appended with the string "+notify" to indicate that the contact wishes to receive notifications for the payload format. Thus if Romeo wants to receive notifications for activity data and geolocation data but not tune data, his client would advertise support for the following namespaces in the disco#info results it sends:
This set of namespaces would then be advertised as a XEP-0115 "ext" value, such as the following:
-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;).
+ +A contact may not want to receive notifications for all payload types. A contact SHOULD signal its preferences to the account owner's server by including XEP-0115 information that specifies the namespaces for which the contact wishes to receive notifications (if any).
+In order to make this possible, all possible payload namespaces can be appended with the string "+notify" to indicate that the contact wishes to receive notifications for the payload format. Thus if Romeo wants to receive notifications for activity data and geolocation data but not tune data, his client would advertise support for the following namespaces in the disco#info results it sends:
This set of namespaces would then be advertised as a XEP-0115 "ext" value, such as the following:
+Note: In XEP-0115, the "ext" values are opaque strings with no semantic meaning.
-It is the responsibility of the account owner's server to cache XEP-0115 information (including "ext" values and their associated namespaces). When the server receives presence from a contact, it MUST check that presence information for entity capabilities data and correlate that data with the desired namespaces for the contact's client. The server MUST NOT send notifications related to any data formats that the contact's client has not asked for via the relevant "namespace+notify" disco#info feature. This enables a client to turn off all notifications (e.g., because of bandwidth restrictions) and to easily receive all desired data formats simply by adding support for the appropriate "namespace+notify" combination in its disco#info results and client capabililies. However, it also implies that a client can request notifications only on a global basis and cannot request, say, mood information only from certain contacts in the user's roster. Community consensus is that this is an acceptable tradeoff. Also, note that this works only if the account owner has a presence subscription to the contact and the contact has a presence subscription to the account owner.
-Some examples may help to illustrate the concept of notification filtering. Here we show presence generated by two of the contacts listed above (benvolio@montague.net does have any presence subscriptions to or from juliet@capulet.com and therefore is not involved in these protocol flows).
-Note: In XEP-0115, the "ext" values are opaque strings with no semantic meaning.
+It is the responsibility of the account owner's server to cache XEP-0115 information (including "ext" values and their associated namespaces). When the server receives presence from a contact, it MUST check that presence information for entity capabilities data and correlate that data with the desired namespaces for the contact's client. The server MUST NOT send notifications related to any data formats that the contact's client has not asked for via the relevant "namespace+notify" disco#info feature. This enables a client to turn off all notifications (e.g., because of bandwidth restrictions) and to easily receive all desired data formats simply by adding support for the appropriate "namespace+notify" combination in its disco#info results and client capabililies. However, it also implies that a client can request notifications only on a global basis and cannot request, say, mood information only from certain contacts in the user's roster. Community consensus is that this is an acceptable tradeoff. Also, note that this works only if the account owner has a presence subscription to the contact and the contact has a presence subscription to the account owner.
+Some examples may help to illustrate the concept of notification filtering. Here we show presence generated by two of the contacts listed above (benvolio@montague.net does have any presence subscriptions to or from juliet@capulet.com and therefore is not involved in these protocol flows).
+We assume that Juliet's server doesn't know anything about these capabilities, so it sends service discovery information requests to each of the clients on Juliet's behalf (realistically, the capulet.com server will quickly build up a cache of client capabilities, with the result that it will not need to send these service discovery requests):
-We assume that Juliet's server doesn't know anything about these capabilities, so it sends service discovery information requests to each of the clients on Juliet's behalf (realistically, the capulet.com server will quickly build up a cache of client capabilities, with the result that it will not need to send these service discovery requests):
+Note: The disco#info result from the node#ver includes only base protocol support, since user-configured notification preferences are to be specified in entity capability extensions. Therefore the server also needs to query the relevant extensions:
+Now we revisit account owner publication and server generation of notifications, with filtering enabled because the server has caps information:
-If Juliet publishes a tune item to the open-access "http://jabber.org/protocol/tune" node, her server will send notifications to <benvolio@montague.net> (bare JID) and to <nurse@capulet.com/chamber> (full JID) but not to <romeo@montague.net/orchard>.
If Juliet publishes an activity item to the presence-access "http://jabber.org/protocol/activity" node, her server will send notifications only to <nurse@capulet.com/chamber>.
If Juliet publishes a geolocation item to the roster-access "http://jabber.org/protocol/geoloc" node, her server will send notifications only to <romeo@montague.net/orchard>.
If a subscriber subscribed using a full JID (&FULLJID;), domain identifier (&DOMAIN;), or domain plus resource (&DOMAINRES;), a PEP service MUST send one notification only, addressed to the subscribed JID.
If a subscriber subscribed using a bare JID (&BAREJID;) and a PEP service does not have appropriate presence information about the subscriber, a PEP service MUST send at most one notification, addressed to the bare JID (&BAREJID;) of the subscriber, and MAY choose not to send any notification. (By "appropriate presence information" is meant an available presence stanza with non-negative priority and XEP-0115 data that indicates interest in the relevant data format.)
If a subscriber subscribed using a bare JID (&BAREJID;) and a PEP service has appropriate presence information about the subscriber, the PEP service MUST send one notification to the full JID (&FULLJID;) of each of the subscriber's available resources that have specified non-negative presence priority and included XEP-0115 information that indicates an interest in the data format.
Note: As explained in XEP-0115, these requests would not all be sent to the same client and resource, but rather would be sent to random entities that advertise the same entity capabilities information.
+The server shall also query the node#ver and node#ext combinations for other contacts (not shown here), which for <romeo@montague.net> indicate an interest in "http://jabber.org/protocol/geoloc+notify" and "http://jabber.org/protocol/tune+notify" but not "http://jabber.org/protocol/activity+notify".
+Now we revisit account owner publication and server generation of notifications, with filtering enabled because the server has caps information:
+If Juliet publishes a tune item to the presence-access "http://jabber.org/protocol/tune" node, her server will send notifications to <nurse@capulet.com/chamber> and <romeo@montague.net/orchard> (full JIDs).
If Juliet publishes an activity item to the presence-access "http://jabber.org/protocol/activity" node, her server will send notifications only to <nurse@capulet.com/chamber>.
If Juliet publishes a geolocation item to the roster-access "http://jabber.org/protocol/geoloc" node, her server will send notifications only to <romeo@montague.net/orchard>.
When an account owner publishes an item to a node, a PEP service MUST generate a notification and send it to all appropriate subscribers (where the number of notifications is determined by the foregoing rules).
When a PEP service receives initial presence information from a subscriber's resource with a non-negative priority and including XEP-0115 information that indicates an interest in the data format, it MUST generate a notification containing the last published item for that node and send it to the newly-available resource.
As an exception to the foregoing MUST rules, a PEP service MUST NOT send notifications to a subscriber if the user has blocked the subscriber from receiving all or any kinds of stanza (presence, message, IQ, or any combination thereof) using communiations blocking as specified in XMPP IM.
As described in the Generating Notifications section of this document, a PEP service MUST send the last published item to all new subscribers and to all newly-available resources for each subscriber.
The server MUST set the 'from' address on the notification to the bare JID (&BAREJID;) of the account owner (in these examples, "juliet@capulet.com").
Any errors generated by the recipient or the recipient's server in relation 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.
When sending notifications to an entity that has a presence subscription to the account owner, the server SHOULD include an &xep0033; "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.
If the PEP service has presence information about the intended recipient, it SHOULD direct the notification(s) to the full JID(s) of the recipients (&FULLJID;); if the PEP service does not have presence information about a subscriber, it MUST address the notification to the subscriber's bare JID (&BAREJID;).
If a subscriber subscribed using a full JID (&FULLJID;), domain identifier (&DOMAIN;), or domain plus resource (&DOMAINRES;), a PEP service MUST send one notification only, addressed to the subscribed JID.
If a subscriber subscribed using a bare JID (&BAREJID;) and a PEP service does not have appropriate presence information about the subscriber, a PEP service MUST send at most one notification, addressed to the bare JID (&BAREJID;) of the subscriber, and MAY choose not to send any notification. (By "appropriate presence information" is meant an available presence stanza with non-negative priority and XEP-0115 data that indicates interest in the relevant data format.)
If a subscriber subscribed using a bare JID (&BAREJID;) and a PEP service has appropriate presence information about the subscriber, the PEP service MUST send one notification to the full JID (&FULLJID;) of each of the subscriber's available resources that have specified non-negative presence priority and included XEP-0115 information that indicates an interest in the data format.
When an account owner publishes an item to a node, a PEP service MUST generate a notification and send it to all appropriate subscribers (where the number of notifications is determined by the foregoing rules).
When a PEP service receives initial presence information from a subscriber's resource with a non-negative priority and including XEP-0115 information that indicates an interest in the data format, it MUST generate a notification containing the last published item for that node and send it to the newly-available resource.
As an exception to the foregoing MUST rules, a PEP service MUST NOT send notifications to a subscriber if the user has blocked the subscriber from receiving all or any kinds of stanza (presence, message, IQ, or any combination thereof) using communiations blocking as specified in XMPP IM.
As mentioned, a PEP service MUST send the last published item to all new subscribers and to all newly-available resources for each subscriber.
As noted, PEP services may be used to implement private data storage, such as defined in &xep0049;. A future version of this document will specify this usage in more detail.
+ ]]> + +A PEP service MAY support other use cases, affiliations, access models, and features, but such support is OPTIONAL.
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 &xep0030; 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 XEP-0060 features):
+A contact MAY send service discovery requests to the account owner's bare JID (&BAREJID;). If the contact already has a subscription to the account owner's presence, this is not necessary in order to receive notifications from the account owner via personal eventing. However, a user without a presence subscription needs to do so in order to discover if the account owner is a virtual pubsub service and to discover the account owner's eventing nodes. The relevant protocol flows are demonstrated in XEP-0060.
+Note: When returning disco#info results, 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.
+This subset of Publish-Subscribe defines and registers two additional pubsub features, as shown in the following table.
+Note: The feature names are of the form "http://jabber.org/protocol/pubsub#name", where "name" is the text specified in the first column below.
+| Name | +Description | +Support | +
|---|---|---|
| auto-create | +The service supports auto-creation of nodes on publish to a non-existent node. | +REQUIRED for PEP services, OPTIONAL for generic pubsub services | +
| publish-and-configure | +The service supports specification of desired node configuration on publish. | +REQUIRED for PEP services, OPTIONAL for generic pubsub services | +
In order to ensure appropriate access to information published at nodes of type "presence" and "roster", a PEP service MUST re-calculate access controls when:
If the modification results in a loss of access, the service MUST cancel the entity's subscription. In addition, the service MAY send a message to the (former) subscriber informing it of the cancellation (for information about the format of messages sent to notify subscribers of subscription cancellation, see the "Notification of Subscription Denial or Cancellation" section of XEP-0060).
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, e.g. as defined in &xep0049;. A separate document will specify private data storage via PEP in more detail.
+The XMPP Registrar maintains a registry of service discovery features (see &DISCOFEATURES;), which includes a number of features that may be returned by pubsub services. The following registry submission has been provided to the XMPP Registrar for that purpose.
+
+ http://jabber.org/protocol/pubsub#auto-create
+ The service supports automatic creation of nodes on publish.
+ XEP-0163
+
+
+ http://jabber.org/protocol/pubsub#publish-and-configure
+ The service accepts node configuration forms on publish.
+ XEP-0163
+
+ ]]>
+ The authors wish to thank the participants in the XMPP Interoperability Testing Event held July 24 and 25, 2006, who provided valuable feedback that resulted in radical simplification of the protocol.
+Thanks also to the many members of the standards@xmpp.org discussion list who patiently suffered through seemingly endless discussion of the auto-create and publish-and-configure features.