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 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.4
Last Updated: 2006-02-02
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: 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. Implementation Notes
7.1. Generating Notifications
7.2. Roster States
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]. To make publish-subscribe functionality more accessible in the context of instant messaging and presence applications that conform to XMPP IM [3], this document defines best practices that can be followed by IM 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 personal pubsub nodes associated with the account owner, 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) associated with the owner-publisher. For example, there is one pubsub node for User Geolocation [4], one node for User Tune [5], one node for User Mood [6], 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 instant messaging and presence 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 [7]).

3. Service Discovery

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

Example 1. Entity queries a server regarding protocol support

<iq from='juliet@capulet.com/balcony'
    to='capulet.com'
    id='disco1'>
  <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'>
  <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>
  

4. Publisher Use Cases

4.1 Creating a Node

First, the account owner creates the node.

Example 3. Account owner creates node

<iq type='set' id='create1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='http://jabber.org/protocol/mood'/>
    <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/mood".
  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 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 type='set' id='create-roster-1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='http://jabber.org/protocol/geoloc'/>
    <configure access='roster'>
      <group>Friends</group>
    </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 type='set' id='create-open-1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <create node='http://jabber.org/protocol/mood'/>
    <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 type='set' id='pub1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='http://jabber.org/protocol/mood'>
      <item>
        <mood xmlns='http://jabber.org/protocol/mood'>
          <happy>
        </mood>
      </item>
    </publish>
  </pubsub>
</iq>
  

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

Example 8. Server returns result

<iq 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/balcony'
         to='romeo@montague.net/home'
         type='headline'
         id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/mood'>
      <item>
        <mood xmlns='http://jabber.org/protocol/mood'>
          <happy>
        </mood>
      </item>
    </items>
  </event>
</message>

.
.
.
    

The server MUST set the 'from' address on the notification to the full JID (<node@domain.tld/resource>) of the publishing resource (in the previous 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). Naturally, if there is only one active resource for the account owner, the subscriber's client can safely ignore the resource.

4.3 Sending the Last Published Item

As described below, 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/balcony'
         to='romeo@montague.net/orchard'
         type='headline'
         id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/mood'>
      <item>
        <mood xmlns='http://jabber.org/protocol/mood'>
          <happy>
        </mood>
      </item>
    </items>
  </event>
  <x xmlns='jabber:x:delay' stamp='20031213T23:58:37'/>
</message>
    

5. Subscriber Use Cases

5.1 Discovering Nodes

Node discovery is made easy 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:

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/mood'/>
    <item jid='juliet@capulet.com' node='http://jabber.org/protocol/activity'/>
    <item jid='juliet@capulet.com' node='http://jabber.org/protocol/geolocation'/>
  </query>
</iq>
    

Alternatively, the potential subscriber may send a disco#info request to the specific node of interest:

Example 15. Subscriber queries specific node

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

The account owner's server would then return information about the node (if it exists) or an <item-not-found/> error if the node does not exist:

Example 16. Servers returns node info

<iq type='result' id='disco2' to='romeo@montague.net/home' from='juliet@capulet.com'>
  <query xmlns='http://jabber.org/protocol/disco#items'
         node='http://jabber.org/protocol/mood'>
    <identity category='pubsub' type='leaf'/>
    <feature var='http://jabber.org/protocol/pubsub'/>
  </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 17. 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/mood' 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 18. 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 19. Server sends last published item

<message from='juliet@capulet.com/balcony' to='romeo@montague.net' type='headline' id='foo'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='http://jabber.org/protocol/mood'>
      <item>
        <mood xmlns='http://jabber.org/protocol/mood'>
          <happy>
        </mood>
      </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. Implementation Notes

7.1 Generating Notifications

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

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

7.2 Roster States

In order to ensure coherency for nodes of type "presence" and "roster", a PEP service SHOULD recalculate access controls whenever a roster item is modified (e.g., when a subscription request is approved or when the item is moved to a new roster group). If the modification results in a loss of access, a service MUST cancel the entity's subscription and MAY send a message to the (former) subscriber informing the entity of the cancellation.

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) [9].

10. Jabber Registrar Considerations

10.1 Protocol Namespaces

The Jabber Registrar [10] 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; as a result of this JEP, the Registrar shall include an additional type of "pep".

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

The schemas defined in JEP-0060 apply to the Personal Eventing Protocol.


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. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.

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

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

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

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

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

9. 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/>.

10. 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.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)

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