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.

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.

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 Feature Summary.) 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.

Although this specification is large because it defines many side use cases and possible error flows, the basic idea is simple:

1. An entity publishes information to a node at a publish-subscribe service.
2. The pubsub service pushes an event notification to all entities that are authorized to learn about the published information.

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>:

So that is the "pub" part of pubsub.

Now the pubsub service notifies all the subscribers about the new blog entry:

Here is an even simpler example: a transient node that sends only event notifications without a payload:

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 Create a Node) and subscribers may need to sign up for event notifications (see Subscribe to a Node). 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 Feature Summary.)

To manage permissions, the protocol defined herein uses a hierarchy of affiliations, similiar to those introduced in &xep0045;.

All affiliations MUST be based on a bare JID &BAREJID; instead of a full JID &FULLJID;.

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 Feature Summary). Particular kinds of pubsub services MAY enforce additional requirements (e.g., requiring support for a given non-required affiliation or for all affiliations).

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

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.

Subscriptions to a node may exist in several states.

The requirements for the publish-subscribe protocol imply that there are two major dimensions along which we can measure events: persistent vs. transient, and pure event notification vs. inclusion of payload. An implementation SHOULD enable an owner to configure a node along both of these dimensions.

No matter whether a node is configured for persistent or transient events, a service MAY cache the last item published to the node, in which case it SHOULD send that item to subscribers based on configuration of the "send_last_published_item" option (see the Item Caching section of this document); if the service supports the "http://jabber.org/protocol/pubsub#last-published" feature then the value of this option MUST default to "on_sub_and_presence" (though the service SHOULD allow the node owner to override the default).

Note: The "on_sub_and_presence" setting relates to the subscriber's presence, not the publisher's presence.

A pubsub service MUST validate publish requests against the configuration of the node along both of these dimensions (see the Publish An Item to a Node section of this document for the relevant error conditions).

The node configuration and desired event type determine whether an item must be provided by the publisher, whether the item includes a payload in the publish request or event notification, and whether an item ID is provided by the publisher or generated by the pubsub service. We can summarize the relevant rules as follows:

* Note: Whether the node is notification-only or includes payloads is determined by the "pubsub#deliver_payloads" configuration field.

** Note: Whether the node is persistent or transient is determined by the "pubsub#persist_items" configuration field.

There are two types of nodes:

In order to make node creation simpler for clients, we define the following node access models (in order of openness):

A generic publish-subscribe implementation SHOULD support all of the defined access models, although specialized publish-subscribe implementations MAY support only a subset of the access models. Which access models are provided in a particular deployment is a matter of service provisioning (e.g., some restricted deployments may wish to lock down permissions so that only the "authorize" and "whitelist" access models are provided, or even only the "whitelist" access model).

A node creator or owner can override the default access model by specifying an appropriate value for the 'pubsub#access_model' configuration field (see the Create a Node With Default Configuration and Configure a Node sections of this document).

If a pubsub node is addressable, it MUST be addressable either (1) as a JID or (2) as the combination of a JID and a node. These nodes are equivalent to those used in XEP-0030: Service Discovery.

A service MUST respond to service discovery information requests qualified by the 'http://jabber.org/protocol/disco#info' namespace. The "disco#info" result returned by a pubsub service MUST indicate the identity of the service and indicate which pubsub features are supported.

The possible pubsub features are noted throughout this document and have been registered as described in the XMPP Registrar Considerations section of this document. For information regarding which features are required, recommended, and optional, see the Feature Summary section of this document.

If a service implements a hierarchy of nodes (by means of Collection Nodes), it MUST also enable entities to discover the nodes in that hierarchy by means of the Service Discovery protocol, subject to the recommendations in XEP-0030 regarding large result sets (for which &xep0055; or some other protocol SHOULD be used). The following examples show the use of service discovery in discovering the nodes available at a hierarchical pubsub service.

Note: Node hierarchies and collection nodes are OPTIONAL. For details, refer to the NodeID Semantics and Collection Nodes sections of this document.

In the first example, an entity sends a service discovery items ("disco#items") request to the root node (i.e., the service itself), which is a Collection Node:

In the second example, an entity sends a disco#items request to one of the first-level nodes, which is also a collection node:

If a node is a leaf node rather than a collection node and items have been published to the node, the service MAY return one &ITEM; element for each published item as described in the Discover Items for a Node section of this document, however such items MUST NOT include a 'node' attribute (since they are published items, not nodes).

A pubsub service MUST allow entities to query individual nodes for the information associated with that node. The Service Discovery protocol MUST be used to discover this information. The "disco#info" result MUST include an identity with a category of "pubsub" and a type of either "leaf" or "collection".

Note: If a node has an identity type of "leaf", then it MUST NOT contain other nodes or collections (only items); if a node has an identity type of "collection", then it MUST NOT contain items (only other nodes or collections).

The "disco#info" result MAY include detailed metadata about the node, encapsulated in the &xep0004; format as described in &xep0128;, where the data form context is specified by including a FORM_TYPE of "http://jabber.org/protocol/pubsub#meta-data" in accordance with &xep0068;. If metadata is provided, it SHOULD include values for all configured options as well as "automatic" information such as the node creation date, a list of publishers, and the like.

Note: Node metadata can be set in many ways. Some of it is based on node configuration (e.g., the owner's JID) whereas some of it may be dynamic (e.g., the number of subscribers). Any static information to be provided in the node metadata SHOULD be provided as fields in the node configuration form.

Note: The pubsub#language field SHOULD be list-single so that the pubsub service can present an appropriate list of languages and language codes.

To discover the published items which exist on the service for a specific node, an entity MAY send a "disco#items" request to the node itself, and the service MAY return each item as a Service Discovery &ITEM; element. The 'name' attribute of each Service Discovery item MUST contain its ItemID and the item MUST NOT possess a 'node' attribute. This ItemID MAY then be used to retrieve the item using the protocol defined in the Retrieve Items from a Node section of this document.

An entity may want to query the service to retrieve its subscriptions for all nodes at the service. Support for this feature ("retrieve-subscriptions") is RECOMMENDED.

In order to make the request, the requesting entity MUST send an IQ-get whose &PUBSUB; child contains an empty <subscriptions/> element with no attributes.

If the service returns a list of subscriptions, it MUST return all subscriptions for all JIDs that match the bare JID &BAREJID; portion of the 'from' attribute on the request.

For each subscription, a <subscription/> element is returned specifying the NodeID, the JID that is affiliated (which MAY include a resource, depending on how the entity subscribed), and the current subscription state. If subscription identifiers are supported by the service, the 'subid' attribute MUST be present as well.

If the requesting entity has no subscriptions, the pubsub service MUST return an empty <subscriptions/> element.

If the service does not support subscriptions retrieval, the service MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-subscriptions".

An entity MAY also request all of its subscriptions at a specific node (e.g., if it has subscriptions with multiple SubIDs) by including a 'node' attribute on the <subscriptions/> element.

The service would then return only the entity's subscriptions to that specific node; this acts as a filter on the entity's subscriptions.

An entity may want to query the service to retrieve its affiliations for all nodes at the service, or query a specific node for its affiliation with that node. Support for this feature ("retrieve-affiliations") is RECOMMENDED.

In order to make the request of the service, the requesting entity includes an empty <affiliations/> element with no attributes.

If the service returns a list of affiliations, it MUST return all affiliations for all JIDs that match the bare JID &BAREJID; portion of the 'from' attribute on the request.

For each affiliation, an <affiliation/> element is returned containing the NodeID and the affiliation state (owner, publisher, publish-only, member, or outcast).

If the requesting entity has no affiliations, the pubsub service MUST return an empty <affiliations/> element.

If the service does not support affiliations retrieval, the service MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-affiliations".

In order to make an affiliations request of a specific node, the requesting entity includes an empty <affiliations/> element with a 'node' attribute.

An implementation MAY allow subscribers to configure subscription options. Implementations SHOULD use the Data Forms protocol to accomplish this configuration (however, an out-of-band mechanism such as a web interface could be offered as well).

An entity might want to request information about the default subscription configuration. Support for this feature is OPTIONAL.

Implementations of pubsub that choose to persist items MAY allow entities to request existing items from a node (e.g., an entity may wish to do this after successfully subscribing in order to receive all the items in the publishing history for the node).

A publisher might want to delete an item once it has been published to a node that supports persistent items. Support for this feature ("delete-items") is RECOMMENDED.

After creating a new node, the node owner may want to modify the node configuration. Support for this feature is RECOMMENDED.

An entity may want to request information about the default node configuration, e.g. in order to determine whether to perform create-and-configure as previously described. Support for this feature is OPTIONAL.

If a service supports node creation, it MUST support node deletion. If an implementation persists items, it MUST remove all items from persistent storage before the node itself is deleted.

If a service persists published items, a node owner may want to purge the node of all published items (thus removing all items from the persistent store). It is OPTIONAL for a service to implement this feature.

A service MAY send subscription approval requests to the node owner(s) at any time. An approval request consists of a message stanza containing a Data Form scoped by the "http://jabber.org/protocol/pubsub#subscribe_authorization" FORM_TYPE. The form MUST contain a boolean field that has a 'var' attribute of "pubsub#allow", which is the field that designates whether or not to allow the subscription request. The form SHOULD include fields that specify the node identifier and the JID of the pending subscriber. The message MAY include a &BODY; element that contains natural-language text explaining that the message contains a pending subscription form.

In order to approve the request, the owner shall submit the form and set the "pubsub#allow" field to a value of "1" or "true"; for tracking purposes the message MUST reflect the 'id' attribute originally provided.

The service then SHOULD notify the approved subscriber (see the Notification of Subscription State Changes section of this document).

In order to deny the request, the owner shall submit the form and set the "pubsub#allow" field to a value of "0" or "false"; as above, the message MUST reflect the 'id' attribute originally provided.

The service then SHOULD notify the denied subscriber (see the Notification of Subscription State Changes section of this document).

In order to cancel the form submission, the owner shall reply with the form's 'type' attribute set to "cancel".

The service MUST check the "pubsub#allow" field to see if the subscription should be allowed or denied. If the owner cancels the Data Form, then the subscription request MUST remain in the pending state.

A node owner may want to request all of the pending subscription requests for all of their nodes at a service. It is OPTIONAL for a service to implement this feature.

This feature MUST be implemented using the &xep0050; protocol, where the command name ('node' attribute of the command element) MUST have a value of "http://jabber.org/protocol/pubsub#get-pending".

A node owner may want to edit the list of subscriptions associated with a given node. Support for this feature ("pubsub#manage-subscriptions") is OPTIONAL.

A node owner may want to manage the affiliations of entities associated with a given node and to set affiliations for new entities. Support for this feature ("pubsub#modify-affiliations") is OPTIONAL.

When a contact is affiliated with the account owner through sharing of XMPP presence, the "auto-subscribe" feature greatly simplifies the subscription process. In particular, support for the "auto-subscribe" has the following implications:

A contact might not want to receive notifications for all the nodes hosted at a user's virtual pubsub service. A contact SHOULD signal its preferences to the account owner's server by including XEP-0115 information that specifies the NodeIDs for which the contact wishes to receive notifications (if any). This information is used by a pubsub service that supports the "filtered-notifications" feature to send notifications only from those NodeIDs that match the subscriber's preferences.

In order to make this possible, all possible NodeIDs can be appended with the string "+notify" to indicate that the contact wishes to receive notifications for the specified NodeID. Thus if Romeo wants to receive notifications for location data (&xep0080;) and tune data (&xep0118;) but not activity data (&xep0108;), his client would advertise support for the following strings in the disco#info results it sends: Including, say, the 'http://jabber.org/protocol/geoloc' NodeID indicates that the client understands the geolocation namespace described in XEP-0080, whereas including the 'http://jabber.org/protocol/geoloc+notify' namespace indicates that the client wishes to receive notifications related to geolocation, where the NodeID is the same as the geolocation namespace 'http://jabber.org/protocol/geoloc' (in this case there is a one-to-one correspondence between the namespace name and the NodeID).

• http://jabber.org/protocol/geoloc+notify
• http://jabber.org/protocol/tune+notify

This set of strings would then be advertised by including them in the identity+features hash encapsulated via the 'ver' attribute as described in XEP-0115.

It is the responsibility of the account owner's server to cache XEP-0115 information. 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 NodeIDs for the contact's client. The server MUST NOT send notifications related to any NodeIDs that the contact's client has not asked for via the relevant "NodeID+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 "NodeID+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.lit does not have any presence subscriptions to or from juliet@capulet.lit 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.lit server will quickly build up a cache of client capabilities, with the result that it will not need to send these service discovery requests):

The server shall also query the identity+features for <romeo@montague.lit>:

(As noted in XEP-0115, the server MUST check the hash provided in the 'ver' attribute against the generation method to ensure that no poisoning has occurred.)

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.lit/chamber> and <romeo@montague.lit/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.lit/chamber>.

• If Juliet publishes a geolocation item to the roster-access "http://jabber.org/protocol/geoloc" node with the "pubsub#roster_groups_allowed" variable set to a value of "Friends", her server will send notifications only to <romeo@montague.lit/orchard> because the nurse is not in that roster group.

There are many possible triggers for sending an event notification to an entity for the currently published item or the last published item, as summarized below:

1. The entity explicitly requests one or more items from the node and is authorized to retrieve items; when the service receives such a request, it sends the items to the entity.
2. The entity is an authorized subscriber to the node (explicitly via subscription or implicitly based on a role of owner or publisher); when the publisher sends a publish request, the service sends the currently published item to the entity (subject to presence checks and notification filtering if appropriate).
3. The entity is not subscribed but is eligible to do so and has sent presence containing appropriate entity capabilities data to a service that supports filtered notifications (effectively establishing a "temporary subscription" based on an expressed notification interest); when the service first receives such presence, it sends the last published item to the entity (sending it only once upon first receiving such presence, not on subsequent presence updates that contain the same notification interest).
4. The entity is not subscribed but is eligible to do so and has sent presence containing appropriate entity capabilities data to a service that supports filtered notifications (effectively establishing a "temporary subscription"); when the publisher sends a publish request that matches the entity's expressed notification interest, the service sends the currently published item to the entity.
5. The entity gains access to the node because of a change to the node access model; as a result, the service sends the last published item to the entity.
6. The entity is added to the roster group associated with a node access model of "roster"; as a result, the service sends the last published item to the entity.

When a pubsub service generates notifications, it MUST adhere to the delivery rules implicit in the subscription option configuration for each subscriber. In particular, the 'to' address SHOULD be that of the subscribed JID only. The service SHOULD NOT attempt to guess at the most available resource associated with the subscribed JID (e.g., in the context of instant messaging systems).

As noted above, a pubsub service SHOULD ensure that the &MESSAGE; stanza for each event notification it generates possesses an 'id' attribute with a value. (This notification ID is not to be confused with either the node ID or the item ID.) This ID MUST be unique within the context of the pubsub service in order to ensure proper tracking of any delivery-related errors.

Exactly how a service shall handle delivery-related errors is a matter of implementation. In general, such handling is effectively similar to the bounce processing performed by other message delivery systems, such as mail transfer agents and mailing list software. The following are some suggested guidelines regarding the handling of XMPP-specific error conditions in relation to pubsub event notifications (see RFC 3920 and XEP-0086 regarding XMPP error condition semantics):

• If the XMPP error is of type "cancel" (e.g., ¬found;), or the error condition is &gone;, the pubsub service SHOULD terminate the subscription of the entity to that node and MAY terminate the subscription of that entity to all nodes hosted at the service.
• If the XMPP error is of type "auth" (e.g., ®istration;) or "wait" (e.g., &timeout;), or the error condition is &badrequest;, &redirect;, or ¬acceptable;, the pubsub service SHOULD increment a bounce counter for that entity and MAY attempt to resend the event notification after some configurable amount of time. The service MAY terminate the subscription of the entity to that node if the bounce counter has reached some configurable limit.

An implementation MAY enable an entity to subscribe to a node temporarily, i.e., only for as long as the subscriber is online in its current presence session. To subscribe temporarily, the subscriber MUST set the "pubsub#expire" subscription configuration option to a literal value of "presence".

The service will then automatically cancel the subscription when it receives presence of type "unavailable" from the subscriber.

An implementation MAY enable the node owner to force all subscriptions to be temporary, which is useful for nodes that are also configured to use presence-based delivery. This setting uses the "pubsub#tempsub" node configuration option set to a value of true.

Implementations of pubsub MAY deliver event notifications only when the subscriber is online. In these cases, the option may be a node configuration option as shown in the examples above. To facilitate this, the pubsub service needs to subscribe to the subscriber's presence and check the subscriber's current presence information before sending any event notifications (as described in RFC 3921). Presence subscriptions MUST be based on the subscribed JID.

Sending events to users of existing XMPP servers may force event notifications to be routed to offline storage for later delivery (as described in &xep0160;). This may not always be desirable. The possible ways of preventing this behavior include:

• Use presence-based subscription options as described above.
• Use delivery semantics as defined by &xep0079;.
• Specify a message type of "headline", which in most existing server implementations will prevent offline storage.

If a service understands the semantics for a particular payload type and an entity's subscription is so configured (by the "pubsub#include_body" subscription option to true), the service SHOULD include an appropriate XMPP &BODY; child element along with the payloads it sends in event notifications for a given node, where the body's XML character data summarizes or represents the information contained in the payload (this enables clients that do not understand the payload format to present the appropriate information to an end user). For example, the Atom <summary/> element (see RFC 4287) could be mapped to the XMPP &BODY; element. A service MUST NOT provide the "pubsub#include_body" subscription option for a node if it does not have a defined way to transform part or all of the payload format into a sensible message body. A node owner MAY define an XSLT for transforming the payload format into a message body, via the "pubsub#body_xslt" node configuration option. This XSLT is applied by the pubsub service after receiving a publish request and before sending the appropriate notifications, not by the client before sending a publish request.

If the service does not understand the semantics for a particular payload type and therefore cannot transform the payload into a human-readable message body, it SHOULD NOT include a <body/> child.

If a subscriber has multiple subscriptions to the same node, where some of the SubIDs have include_body set to true and others have include_body set to false, the service SHOULD include a body with all notifications.

NodeIDs MUST be treated as unique identifiers within the context of a particular pubsub service.

If item identifiers are used, they MUST be treated as unique within the scope of the node. The combination of the NodeID + ItemID MUST be unique within a given service, and MUST specify a single published item at a single node.

If a publisher publishes an item and the ItemID matches that of an existing item, the pubsub service MUST overwrite the existing item and generate a new event notification.

Because it is possible for a node's configuration to change such that ItemIDs are required (e.g., a change from transient to persistent), a service SHOULD use ItemIDs for internal tracking purposes even if it does not include them with the notifications it generates prior to the configuration change.

A service MAY cache the last item published to a node, even if the node is configured for transient publication (i.e., configured to not persist items). The last published item SHOULD be sent to new subscribers upon successful processing of a subscription request or approval by a node owner.

Note: Particular profiles of the generic publish-subscribe protocol MAY define more stringent requirements regarding the "cache-last-item" feature.

A publisher MAY include multiple &ITEM; elements in a publish request and MAY include multiple &ITEM; elements in a retract request. This results in "batch processing" of publications or retractions.

If the service cannot process any one of the items to be published or retracted, the entire batch MUST fail and the service MUST NOT publish or retract any of the items.

If a batch publish contains so many items that publication of all the items would exceed the maximum number of items for the node, the service MUST return a ¬allowed; error, which SHOULD also include a pubsub-specific error condition of <max-items-exceeded/>.

Note: Batch publication renders the concept of "last published item" problematic; therefore, if information coherence is needed, a publisher SHOULD publish items in separate requests rather than in batch mode.

A service MUST allow owners and publishers to subscribe to a node, and to retrieve items from a node even if they are not subscribed. A service MAY auto-subscribe owners and publishers if they are not already subscribed, in which case it SHOULD generate a subscription ID if necessary for the subscription and SHOULD send a notification of successful subscription as described in the Notification of Subscription State Changes section of this document.

How subscription requests are sent to node owners is a matter of implementation. Possibilities include:

• Send requests to all owners (these may be placed in offline storage as described in XEP-0160) and first approval wins.
• The service could subscribe to owner presence, and send only to the owners that are online.
• All owners vote on the new subscriber.
• Any owner is allowed to veto the subscriber.

An implementation MAY use any of these methods, or some other method not defined herein.

Various actions and events may result in changes to a subscription state:

• Approval or denial of a subscription request as described in the Manage Subscription Requests use case

• Cancellation of an existing subscription, for which many "triggers" are possible:

  • The entity simply unsubscribes from the node
  • The node is of type "presence" and the underlying presence subscription is cancelled
  • The node is of type "roster" and the entity is moved to an unauthorized roster group

When a subscription state change occurs, a service SHOULD send a message to the (new, former, or denied) subscriber informing it of the change, where the message contains an <event/> element with a single <subscription/> child that specifies the node, JID, and subscription state. The notification MAY contain a &BODY; element specifying natural-language text regarding the subscription change. The JID to which the service sends the notification is the address that was set in the 'jid' attribute of the subscription request. Examples are shown below.

If the service has knowledge of the (former or denied) subscriber's presence, it SHOULD send the message to all of the subscriber's resources; if not, it MUST send the message to the subscriber's affiliated JID.

If a service or node supports this feature, it MUST return a feature of "subscription-notifications" in its response to service discovery information requests.

NodeIDs MAY have semantic meaning in particular profiles, implementations, or deployments of pubsub. However, it is STRONGLY RECOMMENDED that such semantic meaning not be used to encapsulate the hierarchical structure of nodes; instead, node hierarchy SHOULD be encapsulated using collections and their associated child nodes as described in XEP-0248.

When SubIDs are used, Stanza Headers and Internet Metadata (SHIM) headers are to be included in order to differentiate notifications sent regarding a particular subscription. The relevant use cases and scenarios are:

• Sending notifications regarding newly-published items as described in the Publish an Item to a Node use case.
• Sending notifications regarding deleted items as described in the Delete an Item from a Node use case.

The SHIM headers are generated by the node to which the subscriber has a subscription, which may be either a leaf node or a collection node (refer to XEP-0248).

SHIM headers are not to be included when the content does not differ based on subscription ID, e.g., when a node sends notification of a configuration change to the node itself, notification that the node has been purged, or notification that the node has been deleted.

An implementation MAY enable the node configuration to specify an association between the event notification and the entity to which the published information pertains, but such a feature is OPTIONAL. Here are some possible examples:

• In the context of a geolocation notification service using &xep0080;, the user may generate the geolocation information or the information may be generated by an automated service (e.g., a service offered by a mobile telephony provider), but in either case the information is about the user's geolocation and therefore all replies should go to the user (who is probably the node owner).
• In the context of a group weblog, different users might publish to the weblog and replies might go to the publisher of an entry rather than to the weblog owner.
• In the context of an integrated pubsub and multi-user chat system, the node owner might be the room owner but all replies need to be sent to the room rather than to the owner.

Therefore we define the "itemreply" node configuration option, with two possible values:

• "owner" (i.e., the node owner or an alias for the node owners)
• "publisher" (i.e., the item publisher)

A node owner MUST NOT define more than one of these options.

An example is shown below.

Alternatively, if a service implements the personal eventing subset of this protocol, the virtual pubsub service is the account owner's bare JID and notifications are sent from that JID; for details, refer to XEP-0163.

The word "chaining" refers to the practice of subscribing one node to another node. For instance, consider a scenario in which the node <pubsub@example.net/NewsBroadcaster> wants to distribute information received from the node "NewsFeed" at <pubsub.example.com>. While it is theoretically possible for <pubsub@example.net/NewsBroadcaster> to directly subscribe to the NewsFeed node (since the former node is directly addressable as a JID), implementations MUST NOT chain nodes in this fashion. Instead, implementations MUST subscribe from the address of the pubsub service rather than the node (in the example shown here, the subscription would be sent from <pubsub@example.net> rather than <pubsub@example.net/NewsBroadcaster>).

In some systems it may be desirable to provide a subscription "leasing" feature in order to expire old or stale subscriptions. Leases can be implemented using configurable subscription options; specifically, when an entity subscribes, the service would require configuration of subscription options and the configuration form would contain a field of "pubsub#expire". This field MUST contain a dateTime (as specified in &xep0082;).

The leasing process is shown below.

The service MAY send a message to the subscriber when the lease is almost over (e.g., 24 hours before the end of the lease term). This MUST be done by sending a &MESSAGE; containing a <subscription/> element qualified by the 'http://jabber.org/protocol/pubsub#event' namespace and including an 'expiry' attribute.

When the subscriber wants to renew the lease, it would get the current subscription options, change the value of the "pubsub#expire" field, and submit the new subscription options back to the service. If the new expire value exceeds the maximum value allowed for subscription leases, the service MUST change the value of the field to be the current date/time plus the maximum allowed lease period.

A service MAY enable entities to subscribe to nodes and apply a filter to notifications (e.g., keyword matching such as "send me all news entries from Slashdot that match the term 'XMPP'"). Such a content-based service SHOULD allow an entity to subscribe more than once to the same node and, if so, MUST use subscription identifiers (SubIDs) to distinguish between multiple subscriptions. In order to prevent collisions, a service that supports content-based subscriptions using SubIDs SHOULD generate SubIDs on behalf of subscribers rather than allowing subscribers to set their own SubIDs. Another way to implement content-based subscriptions is to host one node per keyword or other filter; however, this is likely to require an extremely large number of nodes.

Content-based services SHOULD use subscription options to specify the filter(s) to be applied. Because there many possible filtering mechanisms (many of which may be application-specific), this document does not define any such method. However, filtering mechanisms may be defined in separate specifications.

A fictional example of the subscription options configuration process for content-based pubsub is shown below.

The subscriber will then be notified about events that match the keyword.

For some nodes, it is desirable to have at most one item associated with the node at any one time (for example, a client may want to store its preferences using a node name that is a namespace controlled by that client). When this pattern is desired, it is RECOMMENDED for the publisher to specify an ItemID of "current" to ensure that the publication of a new item will overwrite the existing item.

Naturally, the node owner can enforce the singleton node pattern by setting the max_items configuration option to "1".

An XMPP URI (see &rfc5122;) can be used for the purpose of identification or interaction. Some examples are provided below.

The following URI merely identifies a pubsub node.

The following URI identifies a specific item at a node.

The following URI defines how to subscribe to a node (for details, see the URI Query Types section of this document).

The following URI defines how to retrieve a specific item from a node.

This section defines a datatype "integer-or-max" to be used with &xep0122;. An implementation may use this type to validate fields such as "pubsub#children_max", "pubsub#item_expire" or "pubsub#max_items".

The meaning of a value of this type is defined in each field named above.

When the <range/> element is used in combination with this datatype, it applies to the integer value.

The Data Forms shown in this specification include English-language labels for various fields; implementations that will display such forms to human users SHOULD provide localized label text for fields that are defined for the registered FORM_TYPEs.

The data published to a pubsub node might contain sensitive information (e.g., a user's geolocation). Therefore, node owners SHOULD exercise care in approving subscription requests. Security considerations regarding particular kinds of information are the responsibility of the "using protocol".

XMPP PubSub contains a hierarchy of affiliations for the purpose of authorization and access control. A service MUST NOT allow non-owners or other unauthorized entities to complete any actions defined under the Owner Use Cases section of this document.

A service MUST adhere to the defined access model in determining whether to send event notifications or payloads to an entity, or allow an entity to retrieve items from a node. A 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.

In the context of instant messaging systems it is possible for the act of publishing an item to reveal the node owner or item publisher's network availability. However, this risk is mitigated by the following factors:

1. A node does not necessarily reveal the existence of the publishing entity.
2. XMPP PubSub systems are not necessarily tied to instant messaging systems.
3. Even in the context of IM systems, a node provides information distinct from network availability (e.g., user tunes).
4. Even then, the actual publisher might not be an IM user (e.g., an automated calendaring or geolocation system).

The ®ISTRAR; includes the following namespaces in its registry of protocol namespaces (see &NAMESPACES;):

• http://jabber.org/protocol/pubsub
• http://jabber.org/protocol/pubsub#errors
• http://jabber.org/protocol/pubsub#event
• http://jabber.org/protocol/pubsub#owner

The XMPP Registrar includes a category of "pubsub" in its registry of Service Discovery identities (see &DISCOCATEGORIES;), as well as three specific types within that category:

The registry submission is as follows:

Future submissions to the XMPP Registrar may register additional types.

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.

XEP-0068 defines a process for standardizing the fields used within Data Forms scoped by a particular namespace, and the XMPP Registrar maintains a registry of such FORM_TYPES (see &FORMTYPES;). Within pubsub, there are four uses of such forms:

1. Authorization of subscriptions using the 'http://jabber.org/protocol/pubsub#subscribe_authorization' namespace.
2. Configuration of subscription options using the 'http://jabber.org/protocol/pubsub#subscribe_options' namespace.
3. Configuration of a node using the 'http://jabber.org/protocol/pubsub#node_config' namespace.
4. Setting of metadata information using the 'http://jabber.org/protocol/pubsub#meta-data' namespace.

The registry submissions associated with these namespaces are defined below.

Note: There is no requirement that configuration fields need to be registered with the XMPP Registrar. However, as specified in Section 3.4 of XEP-0068, names of custom (unregistered) fields MUST begin with the characters "x-" if the form itself is scoped by a registered FORM_TYPE.

The XMPP Registrar includes "Collection" and "SubID" in its registry of SHIM headers (see &SHIMHEADERS;). The registry submission is as follows:

Future submissions to the XMPP Registrar may register additional SHIM headers that can be used in relation to the pubsub protocol, and such submission may occur without updating this specification.

As authorized by &xep0147;, the XMPP Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).

The "pubsub" querytype is defined herein for interaction with pubsub services, with three keys: (1) "action" (whose defined values are "subscribe", "unsubscribe", and "retrieve"), (2) "node" (to specify a pubsub node), and optionally "item" (to specify a particular item at a node).

The following submission registers the "pubsub" querytype.

The following datatype shall be registered for use with Data Forms Validation: