<abstract>This specification defines an XMPP protocol extension for generic publish-subscribe functionality. The protocol enables XMPP entities to create nodes (topics) at a pubsub service and publish information at those nodes; an event notification (with or without payload) is then broadcasted to all entities that have subscribed to the node. Pubsub therefore adheres to the classic Observer design pattern and can serve as the foundation for a wide variety of applications, including news feeds, content syndication, rich presence, geolocation, workflow systems, network management systems, and any other application that requires event notifications.</abstract>
<remark><p>Revert change from version 1.15.5 which changed meta-data to metadata in wire protocol. That was an unintended breaking change which has now been reverted.</p></remark>
<ul><li>Correct several "entity element(s)" to "<subscription/> element(s)" (mw)</li>
<li>Remove unused and never defined 'node' attribute in pubsub#event item schema. This had been added in version 1.8 of the JEP, but never used. (egp)</li></ul>
<li>Pending further discussion: added but then removed change to allow notifications via IQ stanzas; removed but then retained batch publishing; removed but then retained SubIDs in subscription approvals.</li>
<li>Clarified meaning of filtered notifications (they are based on NodeIDs, not payload namespaces).</li>
<li>Added pubsub-on-a-jid service discovery feature for explicit discovery that an IM and presence account also functions as a virtual pubsub service.</li>
<li>Added purge_offline node configuration option for purging the node when the relevant publisher goes offline, for use in certain extended presence applications.</li>
<li>Added item_expire node configuration option for automatically removing items after a certain number of seconds.</li>
<li>Added notification_type node configuration option for defining which value of the <message/> type attribute shall be used for notifications.</li>
<li>Added retrieve-default-sub feature for retrieving default subscription configuration from a node (as you can retrieve default node configuration from the service).</li>
<li>Clarified suggested rules for payload definitions.</li>
<li>Mentioned that singleton pattern can be enforced by setting max_items to 1.</li>
<li>Added process for retrieving default subscription configuration options for leaf nodes, by omitting the 'node' attribute on the <default/> element (also added the <default/> element to the schema for the http://jabber.org/protocol/pubsub namespace, since it was missing).</li>
<li>Defined pubsub#notify_sub config option so that owners can receive notifications of new subscriptions, unsubscribes, and other subscription changes.</li>
<remark><p>For collection nodes, changed name of node child element to associate and added disassociate child element to handle disassociation use case; corrected SHIM examples to conform to XEP-0131; modified lease expiry notification for consistency with other subscription-related notifications (i.e., not using SHIM header); renamed SHIM headers to Collection and SubID for consistency with HTTP and Email headers.</p></remark>
<li>In accordance with XMPP Council consensus, moved the auto-create, auto-subscribe, filtered-notifications, and last-published features from XEP-0163 to this specification</li>
<li>Clarified implications of auto-subscribe feature for handling of account owners, stable presence subscribers, and transient presence sharers</li>
<li>Updated filtered-notifications text and examples to track changes to XEP-0115</li>
<li>Added publish-options functionality</li>
<li>Added developer-friendly How It Works section</li>
<li>Replaced boolean send_item_subscribe node configuration option with more comprehensive send_last_published_item option per list discussion</li>
<li>Added deliver_notifications node configuration option to enable quiet nodes without notifications, if desired enabling pull-model item retrieval only.</li>
<li>Modified subscription and affiliation retrieval to return empty element if no results.</li>
</ul>
</remark>
</revision>
<revision>
<version>1.8</version>
<date>2006-06-27</date>
<initials>psa</initials>
<remark>
<ul>
<li>Defined five access models: open, presence, roster, authorize, and whitelist</li>
<li>Renamed pubsub#subscription_model feature to pubsub#access_model</li>
<li>Separated affiliations retrieval from subscriptions retrieval</li>
<li>Removed subscription information from affiliations management</li>
<li>Changed <entity/> element to <subscription/> element in response to subscription request</li>
<li>Clarified batch processing of item publication and item deletion</li>
<li>Added basic example to introduction</li>
<li>More fully specified node creation flows</li>
<li>More fully specified recommended behavior for caching last published item, including use of jabber:x:delay protocol</li>
<li>Specified that semantic meaning of NodeIDs must not be used to encapsulate hierarchy</li>
<li>More fully specified error conditions</li>
<li>Changed some feature-related conditions to <unsupported/> plus feature attribute</li>
<li>Changed some error conditions from <not-authorized/> to <forbidden/></li>
<li>Harmonized error conditions for unsubscribe if entity is not subscribed (unexpected-request rather than not-found)</li>
<li>Further defined error conditions related to item publication</li>
<li>Specified structure of <affiliations/>, <delete/>, <purge/>, and <subscriptions/> elements qualified by pubsub#owner namespace</li>
<li>Changed element for retrieval of default node configuration options from <configure/> to <default/> to prevent ambiguity related to configuration of root collection node</li>
<li>Specified conformance with Resourceprep for nodes addressable as JIDs</li>
<li>Added pubsub#modify-affiliations feature</li>
<li>Added pubsub#digest_frequency field to subscribe_options FORM_TYPE</li>
<li>Added pubsub#roster_groups_allowed field to node_config FORM_TYPE</li>
<li>More clearly specified the requirements level (MUST, SHOULD, MAY) for each service discovery feature</li>
<li>Defined pubsub#include_body subscription option and the pubsub#body_xslt node configuration option to transform payload format into an XMPP message body, and clarified rules for inclusion of message bodies</li>
<li>Clarified nature of collections and association of a node to a collection</li>
<li>Specified that simultaneous subscriptions of type nodes and items are allowed to collection nodes</li>
<li>Added examples and further explanation of time-based and content-based subscriptions</li>
<li>In Section 8.2.4, specified that node purgation MUST result in one event notification, not a notification per item</li>
<li>In Section 8.1.8, further specified handling of SubIDs</li>
<li>Clarified nature of the pubsub#type field</li>
<li>Mentioned that the forbidden error should be returned in response to certain operations requested by an outcast</li>
<li>Corrected datatype of max_items attribute from xs:string to xs:positiveInteger</li>
<li>Corrected <requesting-entity-not-subscribed/> error to <not-subscribed/> since the subscribed JID need not be that of the requesting entity</li>
<li>Added service discovery features for more optional use cases: retracting items, purging nodes, deleting nodes</li>
<remark><p>Added service discovery features for pubsub#meta-data, and pubsub#retrieve-items. Added pubsub#subscription_depth configuration option. Specified pubsub-specific error condition elements qualified by pubsub#errors namespace.</p></remark>
<remark><p>Fixed typos. Added more details to the section on collections. Added paragraph to create node use case to allow the service to change the requested node-id to something which it creates. Added text about bouncing publish requests when the request does not match the event-type for that node. Added disco features for the jabber registrar. Changed affiliation verbiage to allow publishers to remove any item. Tweaked verbiage for create node, eliminated extra example. Fully defined XMPP Registrar submissions. Corrected schemas.</p></remark>
<remark><p>Added subid syntax in a variety of places. Added more information about disco#info and disco#items support. Added more info about subscription options. Added collection information. Added implementation notes about subscription leases, and content-based pubsub services.</p></remark>
</revision>
<revision>
<version>1.3</version>
<date>2004-04-25</date>
<initials>psa</initials>
<remark><p>Editorial review; added one implementation note.</p></remark>
<remark><p>Clarified JID addressing usage for nodes. Added specific MAY requirement for disco usage. Added sentence about implementations verifying that an entity has a subscription before getting the current items.</p></remark>
</revision>
<revision>
<version>0.15</version>
<date>2003-10-21</date>
<initials>pgm</initials>
<remark><p>Fixed invalid XML in examples for subscription deny/allow.</p></remark>
</revision>
<revision>
<version>0.14</version>
<date>2003-10-21</date>
<initials>pgm</initials>
<remark><p>Clarified restrictions on addressing nodes by JID. Added section on Approving and Denying Subscription Requests. Changed get-pending to use Ad-Hoc Commands. Changed semantics when sending in a form type='cancel' for pending subscriptions.</p></remark>
</revision>
<revision>
<version>0.13</version>
<date>2003-09-30</date>
<initials>pgm</initials>
<remark><p>Removed item as a possible child of subscribe and unsubscribe and pubsub in the schemas. Removed retract as a possible child of item in the pubsub#event schema. Added verbiage to requirements for addressing nodes either via JIDs or disco nodes.</p></remark>
<remark><p>Defined public vs. private nodes; described how changes to existing nodes might trigger meta-node events (e.g., configuration changes); changed <x/> to <event/> for #events namespace; added metadata about meta-nodes; fully defined XMPP Registrar considerations.</p></remark>
<remark><p>Removed subscription notifications since they have inherent issues. Removed empty implementation note sub-section.</p></remark>
</revision>
<revision>
<version>0.10</version>
<date>2003-06-11</date>
<initials>pgm</initials>
<remark><p>Fixed error example when returning 501 from an items-get request. Added note about receiving subscription requests when an entity is already subscribed. Fixed some entity elements in various subscription examples. Many were missing the node attribute. Added subscription change notification verbiage and example. Added verbiage and example of subscription state notification being sent to the requesting entity. Added disco#items information for getting a list of item identifiers for a single node. Added verbiage for returning the current entity element when a curent subscriber attempts to subscribe again.</p></remark>
</revision>
<revision>
<version>0.9</version>
<date>2003-04-30</date>
<initials>pgm</initials>
<remark><p>Include JID attributes in the entity elements when receiving your affiliations. Changed error code 406 (which was wrong) to 404, which is correct. Changed many 405 errors to 401, and modified the error table to make it more implementable (rules are more concrete). Added subscribe-options element for indicating subscriptions may be configured.</p></remark>
<remark><p>Clarified the affiliations table and the semantics around subscribing and unsubscribing. Added protocol to get all of your affiliations in the service. Added protocol for services informing subscribers that configurable subscription options are available. Added protocol for obtaining existing node configuration settings and for concatenating configuration and node creation requests into a single stanza. Added meta-node implementation notes and specified the interaction with the XMPP Registrar and the meta NodeIDs. Added authorization notes to subscription options.</p></remark>
<remark><p>Clarified requirements around what affiliations must be supported. Moved requirements about specifying entities which can subscribe and publish out of the MUSTs to MAYs. Changed SHOULD to MAY when talking about allowing entities to create nodes. Added ability to send configuration requests in the same stanza as a creation request.</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2003-02-06</date>
<initials>pgm</initials>
<remark><p>Added more details and an example about publishing without NodeID. Added more implementation notes about NodeIDs and persistent storage.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-01-22</date>
<initials>pgm</initials>
<remark><p>Fixed header for delete item example. Added examples showing subscribers being notified of deleted items. Added examples for notification of node deletion, and configuration for node deletion. Added Subscriber option semantics and examples. Added examples for 402 and 407 errors on subscribe and create respectively. Added clarification about ItemID handling to impl notes.</p></remark>
<remark><p>Clarified in-band and out-of-band configuration requirement. Added Delete Item privilege for all affiliations to the table. Added Delete item protocol for publishers and owners. Added 401 error case for subscribing to an illegal jid. Changed subscription request form. Added defaults to configuration form, and clarified role of the XMPP Registrar for the features show. Added text explaining the max_items attribute. Changed "last items" to "most recent items". Removed default configuration acceptance -- owners should just cancel. Added the notify_retract configuration option. Clarified error handling for affiliation modifications. </p></remark>
<remark><p>Added subscription attribute for entities. Removed subscriber from the affiliations table. Clarified configuration details. Clarified JabberID usages. Added XMPP Registrar Considerations. Added link to XEP-0068 about the FORM_TYPE element in subscription request notifications. Fixed some typos in examples. Added unsupported configuration namespace to example. Added a default node configuration example. </p></remark>
<remark><p>Added numerous implementation notes; added get-pending action with regard to subscriptions; added error table; changed purge and delete to use IQ type='set'.</p></remark>
<p>The XMPP publish-subscribe extension defined in this document provides a framework for a wide variety of applications, including news feeds, content syndication, extended presence, geolocation, avatar management, shared bookmarks, auction and trading systems, workflow systems, network management systems, NNTP gateways, profile management, and any other application that requires event notifications.</p>
<p>This technology uses the classic "publish-subscribe" or "observer" design pattern: a person or application publishes information, and an event notification (with or without payload) is broadcasted to all authorized subscribers. In general, the relationship between the publisher and subscriber is mediated by a service that receives publication requests, broadcasts event notifications to subscribers, and enables privileged entities to manage lists of people or applications that are authorized to publish or subscribe. The focal point for publication and subscription is a "node" to which publishers send data and from which subscribers receive event notifications. Nodes can also maintain a history of events and provide other services that supplement the pure pubsub model.</p>
<p>This document defines a generic protocol that all pubsub applications can use. Compliant implementations are not required to implement all of the features defined here (see the <linkurl='#features'>Feature Summary</link>.) Other specifications may define "subsets" or "profiles" of publish-subscribe for use in specialized contexts, but such profiles are out of scope for this document.</p>
<p>Perhaps the most popular application of pubsub-like functionality is content syndication, which has become familiar from the RSS and Atom (&rfc4287;) feeds associated with weblogs, news sites, and other frequently-updated information available on the Internet. Consider the example of a weblog published by <hamlet@denmark.lit>. When Hamlet writes a new weblog entry, his blogging software publishes the entry to a pubsub node hosted at <pubsub.shakespeare.lit>:</p>
<p>Naturally, the entities involved may need to complete other use cases in order to enable full pubsub functionality -- for example, the publisher may need to create the node (see <linkurl='#owner-create'>Create a Node</link>) and subscribers may need to sign up for event notifications (see <linkurl='#subscriber-subscribe'>Subscribe to a Node</link>). These use cases are fully described in the remainder of this document. (For information about which features are required and which are recommended or optional, consult the <linkurl='#features'>Feature Summary</link>.)</p>
<p>The following terms are used throughout this document to refer to elements, objects, or actions that occur in the context of a pubsub service. (Note: Some of these terms are specified in greater detail within the body of this document.)</p>
<di><dt>Authorize Access Model</dt><dd>A node access model under which an entity can subscribe only through having a subscription request approved by a node owner (subscription requests are accepted but only provisionally) and only subscribers may retrieve items.</dd></di>
<di><dt>Address</dt><dd>(1) A JID as defined in &xmppcore;, or (2) the combination of a JID and a &xep0030; node.</dd></di>
<di><dt>Collection Node</dt><dd>A type of node that contains nodes and/or other collections but no published items. Collections make it possible to represent more sophisticated relationships among nodes. Collection nodes are defined in &xep0248;.</dd></di>
<di><dt>Event</dt><dd>A change in the state of a node.</dd></di>
<di><dt>Instant Node</dt><dd>A node whose NodeID is automatically generated by a pubsub service.</dd></di>
<di><dt>Item</dt><dd>An XML fragment which is published to a node, thereby generating an event.</dd></di>
<di><dt>ItemID</dt><dd>A unique identifier for an item in the context of a specific node.</dd></di>
<di><dt>Leaf Node</dt><dd>A type of node that contains published items only. It is NOT a container for other nodes.</dd></di>
<di><dt>Node</dt><dd>A virtual location to which information can be published and from which event notifications and/or payloads can be received (in other pubsub systems, this may be labelled a "topic").</dd></di>
<di><dt>NodeID</dt><dd>The unique identifier for a node within the context of a pubsub service. The NodeID is either supplied by the node creator or generated by the pubsub service (if the node creator requests an Instant Node). The NodeID MAY have semantic meaning (e.g., in some systems or in pubsub profiles such as PEP the NodeID might be an XML namespace for the associated payload), but such meaning is OPTIONAL. If a document defines a given NodeID as unique within the realm of XMPP pubsub systems, it MUST specify the XML namespace of the associated payload.</dd></di>
<di><dt>Payload</dt><dd>The XML data that is contained within the <item/> element of a publication request or an event notification. A given payload is defined by an XML namespace and associated schema. A document that defines a payload format SHOULD specify whether the payload can be used only for a NodeID whose value is the same as the XML namespace, or whether the payload can be used for any NodeID. Such a document also SHOULD specify whether it is suggested that node at which such payloads are published are best configured as <linkurl='#impl-singleton'>Singleton Nodes</link>.</dd></di>
<di><dt>Personal Eventing</dt><dd>A simplified subset of Publish-Subscribe for use in the context of instant messaging and presence applications, whereby each IM user's JID is a virtual pubsub service; for details, see &xep0163;.</dd></di>
<di><dt>Presence Access Model</dt><dd>A node access model under which any entity that is subscribed to the owner's presence with a subscription of type "from" or "both" (see &rfc3921;) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems.</dd></di>
<di><dt>Publisher</dt><dd>An entity that is allowed to publish items to a node and that is automatically subscribed to the node.</dd></di>
<di><dt>Publish-Only</dt><dd>An entity that is allowed to publish items to a node but that is not allowed to receive notifications. (This affiliation is useful in the context of nodes that do not have an open access model when automated entities need to generate notifications on behalf of the owner.)</dd></di>
<di><dt>Pubsub Service</dt><dd>An XMPP server or component that adheres to the protocol defined herein.</dd></di>
<di><dt>Roster Access Model</dt><dd>A node access model under which any entity that is subscribed to the owner's presence and in the specified roster group(s) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems.</dd></di>
<di><dt>Subscriber</dt><dd>An entity that is subscribed to a node.</dd></di>
<di><dt>Whitelist Access Model</dt><dd>A node access model under which an entity may subscribe and retrieve items only if explicitly allowed to do so by the node owner (subscription requests from unauthorized entities are rejected).</dd></di>
<p>Requirements for a pubsub service can be driven by end-user needs as well as the needs of other components and services which can use the service. First, a pubsub service implemented using XMPP MUST provide the basic features that implement a pure publish-subscribe pattern:</p>
<li>An entity MUST be able to publish events to a service such that all subscribers to a node receive notification of the event. See <linkurl='#publisher-publish'>Publish an Item to a Node</link>.</li>
<li>An entity MUST be able to subscribe to a node (or be informed that subscription is not allowed). See <linkurl='#subscriber-subscribe'>Subscribe to a Node</link>.</li>
<li>An entity MUST be allowed to be affiliated with a node. Allowable affiliations are member, none, outcast, owner, publish-only, and publisher. Implementations MUST support affiliations of none and owner, and MAY support affiliations of member, outcast, publisher, and publish-only. See <linkurl='#affiliations'>Affiliations</link>.</li>
<li>An entity MUST be allowed to query the pubsub service (or a specific node) to determine what optional features of this specification the service (or node) implements. This query MUST use the Service Discovery (disco#info) protocol. See <linkurl='#entity-info'>Discover Node Information</link>.</li>
<p>Some of the possible uses of an XMPP-based pubsub service will require other features, but these features are OPTIONAL and therefore not mandatory for compliance with this specification. However, if these features are implemented, they MUST adhere to the protocol described herein in to be compliant. These features include:</p>
<li>A service MAY cache the last item published to a node (even if the "persistent-items" option is set to false); if it does default "cache-last-item" to true, it SHOULD send the last published item (or notification thereof) to subscribed entities based on configuration of the "send_last_published_item" field.</li>
<p>Support for the "owner" and "none" affiliations is REQUIRED. Support for all other affiliations is RECOMMENDED. For each non-required affiliation supported by an implementation, it SHOULD return a service discovery feature of "name-affiliation" where "name" is the name of the affiliation, such as "member", "outcast", or "publisher" (see the <linkurl='#features'>Feature Summary</link>). Particular kinds of pubsub services MAY enforce additional requirements (e.g., requiring support for a given non-required affiliation or for all affiliations).</p>
<p>* Note: A service MAY allow any publisher to delete / purge any item once it has been published to that node instead of allowing only the original publisher to remove it. This behavior is NOT RECOMMENDED for the publish-only affiliation, which SHOULD be allowed to delete only items that the publish-only entity has published.</p>
<p>The ways in which an entity changes its affiliation with a node are well-defined. Typically, action by an owner is required to make an affiliation state transition. Affiliation changes and their triggering actions are specified in the following table.</p>
