<abstract>This document specifies XMPP semantics for using the publish-subscribe protocol to broadcast state change events associated with an instant messaging and presence account.</abstract>
<remark><p>In accordance with XMPP Council consensus (1) explicitly defined auto-create, auto-subscribe, filtered-notifications, and last-published features, (2) moved them to XEP-0060, and (3) added appropriate references to XEP-0060 throughout; also added friendly but non-normative How It Works section and removed references to private data storage; updated to reflect changes to entity capabilities and pubsub.</p></remark>
<remark><p>Per a vote of the Jabber Council, advanced status to Draft.</p></remark>
</revision>
<revision>
<version>0.15</version>
<date>2006-08-30</date>
<initials>psa</initials>
<remark><p>Added the deliver_notifications and send_last_published_item configuration options to the recommended defaults.</p></remark>
</revision>
<revision>
<version>0.14</version>
<date>2006-08-02</date>
<initials>psa</initials>
<remark><p>Changed various recommended defaults from SHOULD to MUST; corrected several errors in the text and examples.</p></remark>
</revision>
<revision>
<version>0.13</version>
<date>2006-08-01</date>
<initials>psa</initials>
<remark><p>Recommended node creation with default configuration on initial publish; corrected several errors and clarified several points in the text.</p></remark>
</revision>
<revision>
<version>0.12</version>
<date>2006-08-01</date>
<initials>psa</initials>
<remark><p>Simplified the subscription process using XMPP presence and entity capabilities.</p></remark>
</revision>
<revision>
<version>0.11</version>
<date>2006-07-20</date>
<initials>psa</initials>
<remark><p>Clarified rules regarding number of notifications and when to generate notifications; corrected several errors in the text and examples.</p></remark>
<remark><p>Clarified terminology and defaults.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2006-04-10</date>
<initials>psa</initials>
<remark><p>Specified that notifications are to be sent from bare JID, not full JID.</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2006-04-10</date>
<initials>psa</initials>
<remark><p>Updated to reflect pubsub changes; clarified business rules for generation of notifications and cancellation of subscriptions.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2006-03-09</date>
<initials>psa</initials>
<remark><p>Modified roster groups example to use jabber:x:data; added note about advertising client support for PEP.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2006-02-02</date>
<initials>psa/ks</initials>
<remark><p>Specified rules for generation of notifications, including use of presence in determining address of intended recipient for notifications and sending of last published item on receipt of presence information; changed name to Personal Eventing Protocol; specified service discovery identity of pubsub/pep; removed section on service types; added Kevin Smith as co-author.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2006-01-30</date>
<initials>psa</initials>
<remark><p>Specified that a service may enforce additional privacy and security policies; specified that an account owner must always be allowed to subscribe and to retrieve items; specified that an implementation should enforce access modifications resulting from roster state changes.</p></remark>
<p>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.
<note>Instead, many "extended presence" formats are currently sent using the &PRESENCE; stanza type; unfortunately, 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.</note> To make publish-subscribe functionality more accessible (especially to instant messaging and presence applications that conform to &xmppim;), this document defines a simplified subset of pubsub that can be followed by instant messaging client and server developers to more easily deploy personal eventing services across the Jabber/XMPP network. We label this subset "Personal Eventing via Pubsub" or PEP.</p>
<pclass='em'>Note: Any use cases not described herein are described in <cite>XEP-0060</cite>. Also, this document does not show error flows related to the generic publish-subscribe use cases referenced herein, since they are exhaustively defined in <cite>XEP-0060</cite>. The reader is referred to <cite>XEP-0060</cite> for all relevant protocol details related to the XMPP publish-subscribe extension. This document merely defines a "subset" or "profile" of XMPP publish-subscribe.</p>
<p>Imagine that you are a Shakespearean character named Juliet and that you want to generate events about what music you're listening to, which anyone may see as long as they are authorized to see your online/offline presence (i.e., a pubsub access model of "presence").</p>
<p>We assume that you have three contacts with the following relationship to you:</p>
<p>Note the following about your publish request:</p>
<olstart='1'>
<li>It is sent with no 'to' address (see <linkurl='#approach-everyjid'>Every Account a Pubsub Service</link>).</li>
<li>It specifies a node of "http://jabber.org/protocol/tune" (see <linkurl='#approach-onenode'>One Node per Namespace</link>).</li>
</ol>
<p>If all goes well (see <linkurl='#publish'>Publishing Events</link>), everyone who is interested in what you are listening to will receive notification of the event:</p>
<p>Because PEP services must send notifications to the account owner, you too receive the notification at each of your resources (here "balcony" and "chamber").</p>
<p>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 typically need to explicitly subscribe to your "http://jabber.org/protocol/tune" node. <note>That may still be necessary for open access model nodes in PEP if another user does not send you presence, such as benvolio@montague.lit in our scenario.</note> But PEP services support two special features:</p>
<li>"auto-subscribe" -- because they are subscribed to your presence, they automatically receive your events (see <linkurl='#approach-presence'>Use Presence</link>).</li>
<li>"filtered-notification" -- they can include some special flags in their &xep0115; information to specify which event types (payloads) they want to receive (see <linkurl='#approach-filter'>Filtered Notifications</link>).</li>
<p>Your server knows to send tune information to Romeo because when the server unpacks the value of the 'ver' attribute ("054H4A7280JuT6+IroVYxgCAjZo=") in accordance with <cite>XEP-0115</cite>, it discovers that Romeo's client advertises a service discovery feature of "http://jabber.org/protocol/tune+notify", where the "+notify" suffix indicates interest in receiving notifications related to the protocol that precedes the suffix. The server can verify this support if needed by sending a service discovery request to Romeo's full JID, where the response would be as follows:</p>
<p>These principles are described more fully below.</p>
<section2topic='Every Account a Pubsub Service'anchor='approach-everyjid'>
<p>When a user creates an account (or has an account provisioned) at a Jabber/XMPP server that supports PEP, the server associates a virtual pubsub service with the account. This greatly simplifies the task of discovering the account owner's personal pubsub nodes, since the root pubsub node simply is the account owner's bare JID (&BAREJID;). This assumption also simplifies publishing and subscribing.</p>
</section2>
<section2topic='One Publisher Per Node'anchor='approach-publisher'>
<p>There is no need for multiple publishers to a PEP service, since by definition the service generates information associated with only one entity. The owner-publisher for every node is the bare JID of the account owner.</p>
<section2topic='One Node Per Namespace'anchor='approach-onenode'>
<p>There is only one publish-subscribe node associated with any given payload type (XML namespace) for the account owner (e.g., there is one pubsub node for geolocation events, one node for tune events, and one node for mood events). This simplifies node creation, discovery, publishing, and subscribing.</p>
<p>Although generic publish-subscribe services do not necessarily have access to presence information about subscribers, PEP services are integrated with presence in the following ways:</p>
<ul>
<li>Each messaging and presence account simply <em>is</em> a virtual publish-subscribe service.</li>
<li>A contact's subscription to an account owner's personal eventing data is automatically created because the contact has an XMPP presence subscription (the "auto-subscribe" feature).</li>
<li>Services take account of subscriber presence in the generation of notifications. <note>This works only if the subscription state is "both" (see <cite>RFC 3921</cite>).</note></li>
<p>By default, the existence of an XMPP presence subscription is used to establish a PEP subscription to the account owner's personal eventing data. In order to filter which notifications are sent by the PEP service, the contact's client includes extended &xep0115; information in the presence notifications it sends to the account owner. Because the PEP service supports the "filtered-notifications" feature, it sends only those notifications that match the contact's expressed notification preferences.</p>
<p>Most pubsub configuration options and metadata are not needed for personal eventing. Instead, PEP services offer smart defaults to simplify node creation and management.</p>
<p>If the node does not already exist, the PEP service MUST create the node. This "auto-create" feature (defined in <cite>XEP-0060</cite>) MUST be supported by a PEP service. (Naturally, the account owner's client MAY follow the node creation use case specified in <cite>XEP-0060</cite> before attempting to publish an item.)</p>
<p>A PEP service SHOULD also support the "publish-options" feature defined in <cite>XEP-0060</cite>.</p>
<p>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 <linkurl='#notify'>Receiving Event Notifications</link> section of this document, as well as to any of the account owner's available resources.</p>
<li>The entity shares presence with the account owner (see <linkurl='#notify-presence'>Presence Sharing</link>), is authorized to receive events from the node in accordance with the node access model (see <cite>XEP-0060</cite>), and advertises an interest in the payload type (see <linkurl='#notify-filter'>Notification Filtering</link>).</li>
<li>The entity is the account owner itself, in which case the PEP service shall send notifications to all of the account owner's available resources (subject to <linkurl='#notify-filter'>notification filtering</link>).</li>
<p>A PEP service MUST support the "auto-subscribe" feature defined in Section 10.1 of <cite>XEP-0060</cite>. This implies that when a user has an XMPP presence subscription to the account owner's presence, the user automatically also has a pubsub subscription account owner's root collection node (i.e., bare JID), with a subscription_type of "items" and a subscription_depth of "all".</p>
<p>A PEP service MUST support the "filtered-notifications" feature defined in Section 10.2 of <cite>XEP-0060</cite>. This implies that when an automatic subscriber can specify which event payloads it wants to receive by including appropriate feature bundles in the <cite>XEP-0115</cite> information it broadcasts.</p>
<li><p>The server MUST set the 'from' address on the notification to the bare JID (&BAREJID;) of the account owner (in these examples, "juliet@capulet.lit").</p></li>
<li><p>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.</p></li>
<li><p>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.lit/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.</p></li>
<li><p>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;).</p></li>
</ol>
</section3>
<section3topic='Number of Notifications'anchor='notify-num'>
<olstart='1'>
<li><p>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.</p></li>
<li><p>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 <cite>XEP-0115</cite> data that indicates interest in the relevant data format.)</p></li>
<li><p>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 <cite>XEP-0115</cite> information that indicates an interest in the data format.</p></li>
</ol>
</section3>
<section3topic='When to Generate Notifications'anchor='notify-when'>
<olstart='1'>
<li><p>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).</p></li>
<li><p>When a PEP service receives initial presence information from a subscriber's resource with a non-negative priority and including <cite>XEP-0115</cite> 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.</p></li>
<li><p>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 <cite>XMPP IM</cite>.</p></li>
</ol>
</section3>
<section3topic='Sending the Last Published Item'anchor='notify-last'>
<p>As mentioned, a PEP service MUST send the last published item to all new subscribers and to all newly-available resources for each subscriber, including the account owner itself. (That is, the default value of the "pubsub#send_last_published_item" node configuration field must be "on_sub_and_presence"; this behavior essentially mimics the functionality of presence as defined in <cite>XMPP IM</cite>.)</p>
<li>Support the node discovery, node creation, node deletion, publish item, subscribe, unsubscribe, and item retrieval use cases specified in <cite>XEP-0060</cite>.</li>
<li>Support the "presence" access model and set it to the default.</li>
<li>Support the "open", "roster", and "whitelist" access models.</li>
<li>Treat the account owner's bare JID (&BAREJID;) as a collection node (i.e., as the root collection node for the account's virtual pubsub service).</li>
<section2topic='Account Owner Service Discovery'anchor='disco-owner'>
<p>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:</p>
<examplecaption='Account owner queries server regarding protocol support'><