JEP-0163: Personal Eventing Protocol

This document specifies a simple subset of the publish-subscribe protocol for use in broadcasting state change events associated with an instant messaging and presence user (e.g., extended presence).


WARNING: This Standards-Track JEP is Experimental. Publication as a Jabber Enhancement Proposal does not imply approval of this proposal by the Jabber Software Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.


JEP Information

Status: Experimental
Type: Standards Track
Number: 0163
Version: 0.7
Last Updated: 2006-04-10
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, XMPP IM, JEP-0060
Supersedes: None
Superseded By: None
Short Name: pep
Wiki Page: <http://wiki.jabber.org/index.php/Personal Eventing Protocol (JEP-0163)>

Author Information

Peter Saint-Andre

Email: stpeter@jabber.org
JID: stpeter@jabber.org

Kevin Smith

Email: kevin@kismith.co.uk
JID: kevdadrum@jabber.ex.ac.uk

Legal Notice

This Jabber Enhancement Proposal is copyright 1999 - 2006 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.

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 Jabber Software 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 JEP 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.

Conformance Terms

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


Table of Contents

1. Introduction
2. Concepts and Approach
2.1. Every Account a Pubsub Service
2.2. One Node Per Namespace
2.3. One Publisher Per Node
2.4. Smart Defaults
2.5. Use Presence
3. Service Discovery
4. Publisher Use Cases
4.1. Creating a Node
4.2. Publishing an Item
4.3. Sending the Last Published Item
5. Subscriber Use Cases
5.1. Discovering Nodes
5.2. Subscribing to a Node
6. Recommended Defaults
7. Business Rules
7.1. Generating Notifications
7.1.1. Number of Notifications
7.1.2. When to Generate Notifications
7.2. Cancelling Subscriptions
8. Security Considerations
9. IANA Considerations
10. Jabber Registrar Considerations
10.1. Protocol Namespaces
10.2. Service Discovery Category/Type
11. XML Schema
Notes
Revision History


1. Introduction

The XMPP Publish-Subscribe [1] extension is commonly thought of as complicated. This is unfortunate, since it would be good to use it to broadcast personal state change events such as those described in Extended Presence Protocol Suite [2]. [3] To make publish-subscribe functionality more accessible in the context of instant messaging and presence applications that conform to XMPP IM [4], this document defines best practices that can be followed by instant messaging and presence client and server developers, hopefully resulting in the deployment of personal eventing protocol ("PEP") services across the Jabber IM network.

Note Well: This document describes all and only a subset of the full publish-subscribe protocol; any new features needed by PEP shall be defined in JEP-0060, not in this document. Until the provisional changes to JEP-0060 required for PEP are approved by the Jabber Council, readers of this document are referred to the version-in-progress located at <http://www.jabber.org/jeps/tmp/jep-0060-1.8.html>.

2. Concepts and Approach

The personal eventing protocol (PEP) is based on five principles:

  1. Every account a pubsub service.
  2. One node per namespace.
  3. One publisher per node.
  4. Smart defaults.
  5. Use presence.

These principles are described more fully below.

2.1 Every Account a Pubsub Service

When a user creates an instant messaging and presence account (or has an account provisioned) at a Jabber server, that account should have associated with it a virtual pubsub service. 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 (<node@domain.tld>). This assumption also simplifies publishing and subscribing.

2.2 One Node Per Namespace

To further simplify matters, we assume that there is only one publish-subscribe node associated with any given payload type (XML namespace) for the owner-publisher. For example, there is one pubsub node for User Geolocation [5], one node for User Tune [6], one node for User Mood [7], and so on. This simplifies discovery, publishing, and subscribing.

2.3 One Publisher Per Node

There is no need for multiple publishers to a personal eventing 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.

2.4 Smart Defaults

Most pubsub configuration options and metadata are not needed for personal eventing. Instead, servers should offer smart defaults to simplify node creation and management.

2.5 Use Presence

Although generic publish-subscribe service do not necessarily have access to presence information about subscribers, personal eventing services are closely integrated with presence, since each account simply is a virtual publish-subscribe service and the recommended access models are "presence" and "roster" (both of which involve presence subscriptions in XMPP instant messaging and presence systems). This presence information can be used to make notifications more intelligent, thus simplifying the task of developing compliant clients (see Protocol Design Guidelines [8]).

3. Service Discovery

In order to discover whether a server or other entity supports the personal eventing protocol, an entity MUST use Service Discovery [9].

Example 1. Entity queries a server regarding protocol support

<iq from='juliet@capulet.com/balcony'
    to='capulet.com'
    id='disco1'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  

If a server supports PEP, it MUST return an identity of "pubsub/pep", MUST return a feature of "http://jabber.org/protocol/pubsub#pep", and MUST specify its default access model as described in JEP-0060.

Example 2. Server communicates protocol support

<iq from='capulet.com'
    to='juliet@capulet.com/balcony'
    id='disco1'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <identity category='pubsub' type='pep'/>
    <feature var='http://jabber.org/protocol/pubsub'/>
    <feature var='http://jabber.org/protocol/pubsub#pep'/>
    <feature var='http://jabber.org/protocol/pubsub#default_access_model_presence'/>
    ...
  </query>
</iq>
  

It is RECOMMENDED for a PEP-aware client to advertise its support for PEP only if the server to which it is connected also supports PEP. This is true both for Service Discovery and for the dynamic "profile" of Service Discovery specified in Entity Capabilities [10].

4. Publisher Use Cases

4.1 Creating a Node

First, the account owner creates the node (we use as our example a node to publish information about the user's current tune as specified in JEP-0118).

Example 3. Account owner creates node

<iq from='juliet@capulet.com/balcony' type='set' id='create1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='http://jabber.org/protocol/tune'/>
    <configure/>
  </pubsub>
</iq>
    

There are several things to note about this node creation request:

  1. Because the account owner's server supports PEP, no 'to' address is needed.
  2. Following the principle of "one node per namespace", the node name is "http://jabber.org/protocol/tune".
  3. Following the principle of "smart defaults", the PEP service has a default access model of "presence" so that the <create/> element does not need to include an 'access' attribute.
  4. Following the principle of "smart defaults", the creation request contains an empty <configure/> child to denote that default node configuration is requested.

If no error occurs (see JEP-0060 for error scenarios), the server acknowledges success.

Example 4. Server returns result

<iq to='juliet@capulet.com/balcony' type='result' id='create1'/>
    

The value of the 'access' attribute SHOULD be "presence" or "roster" for PEP nodes but MAY be "open" (i.e., the value SHOULD NOT be "authorize" or "whitelist" since maintenance of such nodes requires interaction on the part of the node owner). The default access model for PEP nodes MUST be "presence" for IM servers but MAY be something other than "presence" for other PEP service types (e.g., non-IM servers).

If the account owner desires a roster access model for a node, it MUST specify that in the creation request:

Example 5. Account owner creates roster access node

<iq from='juliet@capulet.com/balcony' type='set' id='create-roster-1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='http://jabber.org/protocol/geoloc'/>
    <configure access='roster'>
      <x xmlns='jabber:x:data' type='form'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#node_config</value>
        </field>
        <field var='pubsub#roster_groups_allowed'>
          <option><value>friends</value></option>
        </field>
      </x>
    </configure>
  </pubsub>
</iq>
    

If the account owner desires an open access model for a node, it MUST specify that in the creation request:

Example 6. Account owner creates open access node

<iq from='juliet@capulet.com/balcony' type='set' id='create-open-1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='http://jabber.org/protocol/tune'/>
    <configure access='open'/>
  </pubsub>
</iq>
    

4.2 Publishing an Item

Next, the account owner publishes an item to the node.

Example 7. Account owner publishes item

<iq from='juliet@capulet.com/balcony' type='set' id='pub1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='http://jabber.org/protocol/tune'>
      <item>
        <tune xmlns='http://jabber.org/protocol/tune'>
          <artist>Gerald Finzi</artist>
          <title>Introduction (Allegro vigoroso)</title>
          <source>Music for "Love's Labors Lost" (Suite for small orchestra)</source>
          <track>1</track>
          <length>255</length>
        </tune>
      </item>
    </publish>
  </pubsub>
</iq>
  

If no error occurs (see JEP-0060 for error scenarios), the server acknowledges success.

Example 8. Server returns result

<iq to='juliet@capulet.com/balcony' type='result' id='pub1'/>
    

The notification (with payload) is then delivered to all subscribers (see the Generating Notifications section of this document regarding proper generation of the 'to' address):

Example 9. Server generates notifications

<message from='juliet@capulet.com'
         to='romeo@montague.net/home'
         type='headline'
         id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/tune'>
      <item>
        <tune xmlns='http://jabber.org/protocol/tune'>
          <artist>Gerald Finzi</artist>
          <title>Introduction (Allegro vigoroso)</title>
          <source>Music for "Love's Labors Lost" (Suite for small orchestra)</source>
          <track>1</track>
          <length>255</length>
        </tune>
      </item>
    </items>
  </event>
  <addresses xmlns='http://jabber.org/protocol/address'>
    <address type='replyto' jid='juliet@capulet.com/balcony'/>
  </addresses>
</message>

.
.
.
    

The server MUST set the 'from' address on the notification to the bare JID (<node@domain.tld>) of the publishing entity (in this example, "juliet@capulet.com"). The server SHOULD include an Extended Stanza Addressing [11] "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 an account owner's resources (for example, different resources may be in different places and therefore may need to specify distinct geolocation data). However, 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.

4.3 Sending the Last Published Item

As described in the Generating Notifications section of this document, a PEP service MUST send the last published item to all new subscribers. In addition, a PEP service MUST send the last published item to all newly-available resources for each subscriber. (Both of these behaviors essentially mimic the functionality of presence as defined in XMPP IM.)

Example 10. Subscriber sends presence from newly-available resource

<presence from='romeo@montague.net/orchard'/>
    

Example 11. Subscriber's server sends presence from newly-available resource to publisher's bare JID (i.e., PEP service)

<presence from='romeo@montague.net/orchard' to='juliet@capulet.com'/>
    

Example 12. PEP service sends last published item to newly-available resource

<message from='juliet@capulet.com'
         to='romeo@montague.net/orchard'
         type='headline'
         id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/tune'>
      <item>
        <tune xmlns='http://jabber.org/protocol/tune'>
          <artist>Gerald Finzi</artist>
          <title>Introduction (Allegro vigoroso)</title>
          <source>Music for "Love's Labors Lost" (Suite for small orchestra)</source>
          <track>1</track>
          <length>255</length>
        </tune>
      </item>
    </items>
  </event>
  <x xmlns='jabber:x:delay' stamp='20031213T23:58:37'/>
</message>
    

5. Subscriber Use Cases

5.1 Discovering Nodes

Node discovery is straightforward since there is only one node per namespace. The potential subscriber may send a service discovery items request to the bare JID to discover all active pubsub nodes.

Example 13. Subscriber queries bare JID

<iq type='set' id='disco1' from='romeo@montague.net/home' to='juliet@capulet.com'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
    

Subject to access restrictions as described in JEP-0030, the account owner's server would then return a list of all pubsub nodes (as well as any other associated items as described in JEP-0030):

Example 14. Servers returns list of pubsub nodes

<iq type='result' id='disco1' to='romeo@montague.net/home' from='juliet@capulet.com'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='juliet@capulet.com' node='http://jabber.org/protocol/tune'/>
    <item jid='juliet@capulet.com' node='http://jabber.org/protocol/activity'/>
    <item jid='juliet@capulet.com' node='http://jabber.org/protocol/geolocation'/>
  </query>
</iq>
    

5.2 Subscribing to a Node

In order to subscribe, a contact sends a subscription request to the account owner's bare JID (<node@domain.tld>) and specifies the desired node:

Example 15. Contact subscribes to a node

<iq type='set'
    from='romeo@montague.net/home'
    to='juliet@capulet.com'
    id='sub1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe node='http://jabber.org/protocol/tune' jid='romeo@montague.net'/>
  </pubsub>
</iq>
    

The following scenarios are possible:

  1. If the access model is "presence", the server MUST verify that the full JID of the 'from' address (or the bare JID portion of the full JID) has a presence subscription of type "both" or "from" in the account owner's roster. If so, the server SHOULD allow the entity to subscribe; if not, the server MUST disallow the subscription request.
  2. If the access model is "roster", the server MUST verify that the full JID of the 'from' address (or the bare JID portion of the full JID) has a presence subscription of type "both" or "from" in the account owner's roster and is in the specified roster group. If so, the server SHOULD allow the entity to subscribe; if not, the server MUST disallow the subscription request.
  3. If the access model is "open", the server SHOULD allow the entity to subscribe.

The only exception foreseen to the SHOULD requirements in the foregoing scenarios is the enforcement of local privacy and security policies as specified more fully in the Security Considerations section of this document. (In addition, a service MUST always allow the account owner to subscribe and to retrieve items.)

If no error occurs (see JEP-0060 for error conditions related to subscription requests), the server shall allow the subscription and return an IQ-result:

Example 16. Server allows subscription

<iq type='result'
    from='juliet@capulet.com'
    to='romeo@montague.net/home'
    id='sub1'/>
    

The service then MUST send the last published item to the new subscriber:

Example 17. Server sends last published item

<message from='juliet@capulet.com' to='romeo@montague.net' type='headline' id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/tune'>
      <item>
        <tune xmlns='http://jabber.org/protocol/tune'>
          <artist>Gerald Finzi</artist>
          <title>Introduction (Allegro vigoroso)</title>
          <source>Music for "Love's Labors Lost" (Suite for small orchestra)</source>
          <track>1</track>
          <length>255</length>
        </tune>
      </item>
    </items>
  </event>
  <x xmlns='jabber:x:delay' stamp='20031213T23:58:37'/>
</message>
    

6. Recommended Defaults

The default access model for a PEP service MUST be "presence" (a PEP service SHOULD support the "roster" access model and MAY support the "open" access model).

A PEP service SHOULD NOT support affiliations other than Owner and Subscriber.

A PEP service SHOULD use the following "smart defaults" for every node:

  1. No item persistence (all nodes are transient).
  2. Deliver payloads (no notification-only nodes).
  3. No delete-items.
  4. No get-affiliations.
  5. No get-items.
  6. No purge-items.
  7. No node configuration.
  8. No node metadata.
  9. No configuration of subscription options.
  10. No subscription IDs.

A PEP service MAY allow the owner-publisher's bare JID (<node@domain.tld>) to be a collection node, but MUST NOT support any other collection nodes.

A PEP service SHOULD NOT support instant nodes, since the "one node per namespace" rule makes instant nodes unnecessary.

7. Business Rules

7.1 Generating Notifications

7.1.1 Number of Notifications

  1. If a subscriber subscribed using a full JID (<node@domain.tld/resource>), domain identifier (<domain.tld>), or domain plus resource (<domain.tld/resource>), a PEP service MUST send one notification only, addressed to the subscribed JID.

  2. If a subscriber subscribed using a bare JID (<node@domain.tld>) and a PEP service has presence information about the subscriber, the service MUST send one notification to the full JID (<node@domain.tld/resource>) of each of the subscriber's available resources that have specified non-negative presence priority.

  3. If a subscriber subscribed using a bare JID (<node@domain.tld>) and a PEP service does not have presence information about the subscriber, it MUST send one notification only, addressed to the bare JID (<node@domain.tld>) of the subscriber.

7.1.2 When to Generate Notifications

  1. When an account owner publishes an item to a node, a PEP service MUST generate a notification and send it to all subscribers (where the number of notifications is determined by the foregoing rules).

  2. When a PEP service successfully processes a new subscription, it MUST generate a notification containing the last published item for that node and send it to the subscribing JID (where the number of notifications is determined by the foregoing rules).

  3. When a PEP service receives non-negative presence information from a subscriber's resource, it MUST generate a notification containing the last published item for that node and send it to the newly-available resource.

  4. As an exception to the foregoing MUST rules, a PEP service MAY choose not to send notifications to a particular resource for a subscriber if it knows via Entity Capabilities that the resource does not support PEP or does not support the payload namespace associated with a particular node.

  5. 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 privacy lists as specified in XMPP IM.

  6. Specify impact of privacy rule changes on logic for generating notifications and cancelling subscriptions.

7.2 Cancelling Subscriptions

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:

  1. A presence subscription state changes (e.g., when a subscription request is approved).
  2. A roster item is modified (e.g., when the item is moved to a new roster group).

If the modification results in a loss of access, the service MUST cancel the entity's subscription and SHOULD 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 JEP-0060.

8. Security Considerations

A PEP service MAY enforce additional privacy and security policies when determining whether an entity is allowed to subscribe to a node or retrieve items from a node; however, any such policies shall be considered specific to an implementation or deployment and are out of scope for this document.

9. IANA Considerations

This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [12].

10. Jabber Registrar Considerations

10.1 Protocol Namespaces

The Jabber Registrar [13] shall include 'http://jabber.org/protocol/pubsub#pep' in its registry of protocol namespaces.

10.2 Service Discovery Category/Type

The Jabber Registrar includes a category of "pubsub" in its registry of Service Discovery identities (see <http://www.jabber.org/registrar/disco-features.html>); as a result of this JEP, the Registrar shall add a type of "pep" to that category.

The registry submission is as follows:

<category>
  <name>pubsub</name>
  <type>
    <name>pep</name>
    <desc>
      A personal eventing service that supports the 
      publish-subscribe subset defined in JEP-0163.
    </desc>
    <doc>JEP-0163</doc>
  </type>
</category>
    

11. XML Schema

Because the Personal Eventing Protocol is all and only a subset of Publish-Subscribe, the schemas defined in JEP-0060 apply to PEP as well.


Notes

1. JEP-0060: Publish-Subscribe <http://www.jabber.org/jeps/jep-0060.html>.

2. JEP-0119: Extended Presence Protocol Suite <http://www.jabber.org/jeps/jep-0119.html>.

3. 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.

4. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.

5. JEP-0080: User Geolocation <http://www.jabber.org/jeps/jep-0080.html>.

6. JEP-0118: User Tune <http://www.jabber.org/jeps/jep-0118.html>.

7. JEP-0107: User Mood <http://www.jabber.org/jeps/jep-0107.html>.

8. JEP-0134: Protocol Design Guidelines <http://www.jabber.org/jeps/jep-0134.html>.

9. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.

10. JEP-0115: Entity Capabilities <http://www.jabber.org/jeps/jep-0115.html>.

11. JEP-0033: Extended Stanza Addressing <http://www.jabber.org/jeps/jep-0033.html>.

12. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

13. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.


Revision History

Version 0.7 (2006-04-10)

Specified that notifications are to be sent from bare JID, not full JID.

(psa)

Version 0.6 (2006-04-10)

Updated to reflect pubsub changes; clarified business rules for generation of notifications and cancellation of subscriptions.

(psa)

Version 0.5 (2006-03-09)

Modified roster groups example to use jabber:x:data; added note about advertising client support for PEP.

(psa)

Version 0.4 (2006-02-02)

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.

(psa/ks)

Version 0.3 (2006-01-30)

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.

(psa)

Version 0.2 (2006-01-11)

Updated to reflect proposed JEP-0060 modifications.

(psa)

Version 0.1 (2005-11-02)

Initial JEP version.

(psa)

Version 0.0.2 (2005-10-25)

Added more details and examples.

(psa)

Version 0.0.1 (2005-10-24)

First draft.

(psa)


END