XEP-0060: Publish-Subscribe
XEP-0060: Publish-Subscribe
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.
Authors
Peter Millard
Peter Saint-Andre
Ralph Meijer
SEE LEGAL NOTICES
Status
Stable
NOTICE: The protocol defined herein is a
Stable Standard
of the XMPP Standards Foundation. Implementations are encouraged and the protocol is appropriate for deployment in production systems, but some changes to the protocol are possible before it becomes a Final Standard.
Type
Standards Track
Version
1.30.0 (2025-11-11)
Document Lifecycle
Experimental
Proposed
Stable
Final
1.
Introduction
1.1 Overview
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.
1.2 How It Works
Although this specification is large because it defines many side use cases and possible error flows, the basic idea is simple:
An entity publishes information to a node at a publish-subscribe service.
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 (
RFC 4287
]) feeds associated with weblogs, news sites, and other frequently-updated information available on the Internet. Consider the example of a weblog published by
Example 1.
Publisher Publishes a New Weblog Entry
to='pubsub.shakespeare.lit'
id='pub1'>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
href='http://denmark.lit/2003/12/13/atom03'/>
So that is the "pub" part of pubsub.
Now the pubsub service notifies all the subscribers about the new blog entry:
Example 2.
Service Notifies Subscribers
[ ... ENTRY ... ]
[ ... ENTRY ... ]
[ ... ENTRY ... ]
[ ... ENTRY ... ]
Here is an even simpler example: a transient node that sends only event notifications without a payload:
Example 3.
A Transient Notification
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
.)
2.
Glossary
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.)
Authorize Access Model
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.
Address
(1) A JID as defined in
XMPP Core
], or (2) the combination of a JID and a
Service Discovery (XEP-0030)
] node.
Collection Node
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
PubSub Collection Nodes (XEP-0248)
].
Entity
A JID-addressable XMPP entity (client, service, application, etc.).
Event
A change in the state of a node.
Instant Node
A node whose NodeID is automatically generated by a pubsub service.
Item
An XML fragment which is published to a node, thereby generating an event.
ItemID
A unique identifier for an item in the context of a specific node.
Leaf Node
A type of node that contains published items only. It is NOT a container for other nodes.
Node
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").
NodeID
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.
Notification
A message sent to a subscriber informing them of an event.
Outcast
An entity that is disallowed from subscribing or publishing to a node.
Owner
The manager of a node, of which there may be more than one; often but not necessarily the node creator.
Open Access Model
A node access model under which any entity may subscribe and retrieve items without approval.
Payload
The XML data that is contained within the
Singleton Nodes
Personal Eventing
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
Personal Eventing Protocol (XEP-0163)
].
Presence Access Model
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
RFC 3921
]) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems.
Publisher
An entity that is allowed to publish items to a node and that is automatically subscribed to the node.
Publish-Only
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.)
Pubsub Service
An XMPP server or component that adheres to the protocol defined herein.
Roster Access Model
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.
Subscriber
An entity that is subscribed to a node.
Whitelist Access Model
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).
3.
Requirements
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:
An entity MUST be able to publish events to a service such that all subscribers to a node receive notification of the event. See
Publish an Item to a Node
An entity MUST be able to subscribe to a node (or be informed that subscription is not allowed). See
Subscribe to a Node
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
Affiliations
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
Discover Node Information
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:
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.
A node owner SHOULD be able to specify who may subscribe to a node.
A node owner SHOULD be able to specify who may publish to a node.
A node MAY be configured to deliver the published payload inside the event notification.
A node MAY be configured to persist published items to some persistent storage mechanism.
A node MAY be configured to persist only a limited number of items.
A service MAY support collections as described in
PubSub Collection Nodes (XEP-0248)
].
A service or node MAY support extended service discovery information (metadata).
4.
Preliminaries
4.1 Affiliations
To manage permissions, the protocol defined herein uses a hierarchy of affiliations, similiar to those introduced in
Multi-User Chat (XEP-0045)
].
All affiliations MUST be based on a bare JID (
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).
Table 1:
Affiliations and their Privileges
Affiliation
Retrieve Items
Publish Items
Delete Single Item
Purge Node
Configure Node
Delete Node
Owner
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Publisher
Yes
Yes
Yes
Yes *
Yes *
No
No
Publish-Only
No
No
Yes
Yes *
No *
No
No
Member
Yes
Yes
No
No
No
No
No
None
Yes
No
No
No
No
No
No
Outcast
No
No
No
No
No
No
No
* 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.
Table 2:
Affiliation State Chart
Outcast
None
Member
Publisher
Owner
Outcast
--
Owner removes ban
Owner adds entity to member list
Owner adds entity to publisher list
Owner adds entity to owner list
None
Owner bans entity
--
Owner adds entity to member list
Owner adds entity to publisher list
Owner adds entity to owner list
Member
Owner bans entity
Owner removes entity from member list
--
Owner adds entity to publisher list
Owner adds entity to owner list
Publisher
Owner bans entity
Owner removes entity from publisher list
n/a
--
Owner adds entity to owner list
Owner
n/a
Owner resigns
n/a
n/a
--
4.2 Subscription States
Subscriptions to a node may exist in several states.
Table 3:
Subscription States
Subscription State
Description
None
The node MUST NOT send event notifications or payloads to the Entity.
Pending
An entity has requested to subscribe to a node and the request has not yet been approved by a node owner. The node MUST NOT send event notifications or payloads to the entity while it is in this state.
Unconfigured
An entity has subscribed but its subscription options have not yet been configured. The node MAY send event notifications or payloads to the entity while it is in this state. The service MAY timeout unconfigured subscriptions.
Subscribed
An entity is subscribed to a node. The node MUST send all event notifications (and, if configured, payloads) to the entity while it is in this state (subject to subscriber configuration and content filtering).
4.3 Event Types
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:
Table 4:
Items, Payloads, and Item IDs
Notification-Only Node *
Payload-Included Node *
Persistent Node **
Publish request MUST include an
Publish request MUST include an
Transient Node **
Publish request MUST NOT include an
Publish request MUST include an
* 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.
4.4 Node Types
There are two types of nodes:
Table 5:
Node Types
Node Type
Description
Leaf
A node that contains published items only. It is NOT a container for other nodes. This is the most common node type.
Collection
A node that contains nodes and/or other collections but no published items. Collections make it possible to represent more sophisticated relationships among nodes. For details, refer to
PubSub Collection Nodes (XEP-0248)
].
4.5 Node Access Models
In order to make node creation simpler for clients, we define the following node access models (in order of openness):
Table 6:
Node Access Models
Access Model
Description
Open
Any entity may subscribe to the node (i.e., without the necessity for subscription approval) and any entity may retrieve items from the node (i.e., without being subscribed); this SHOULD be the default access model for generic pubsub services.
Presence
Any entity with a subscription of type "from" or "both" may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems (see
RFC 3921
]).
Roster
Any entity 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 (see
RFC 3921
]).
Authorize
The node owner must approve all subscription requests, and only subscribers may retrieve items from the node.
Whitelist
An entity may subscribe or retrieve items only if on a whitelist managed by the node owner. The node owner MUST automatically be on the whitelist. In order to add entities to the whitelist, the node owner SHOULD use the protocol specified in the
Manage Affiliated Entities
section of this document, specifically by setting the affiliation to "member".
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).
4.6 Addressing
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. [
4.6.1 JID
JID addressing SHOULD only be used when interacting with a pubsub node using a protocol that does not support the node attribute. For example, when a service makes it possible for entities to subscribe to nodes via presence, it would address nodes as JIDs.
If a pubsub node is addressable as a JID, the NodeID MUST be the resource identifier, and MUST NOT be specified by the "user" portion (node identifier) of the JID (e.g. "domain.tld/NodeID" and "user@domain.tld/NodeID" are allowed; "NodeID@domain.tld" is not allowed [
]). The pubsub service MUST ensure that the NodeID conforms to the Resourceprep profile of Stringprep as described in
RFC 3920
10
].
Consider the following example, in which the pubsub service is located at the hostname pubsub.shakespeare.lit.
Example 4.
Node addressed as domain.tld/NodeID
...
Now consider the following example, in which the pubsub service is located at pubsub@shakespeare.lit.
Example 5.
Node addressed as user@domain.tld/NodeID
...
4.6.2 JID+NodeID
JID plus Node addressing SHOULD be used when interacting with a pubsub node using a protocol that support the node attribute (e.g. Service Discovery).
If a pubsub node is addressable as a JID plus node, the NodeID MUST be the value of both the protocol's 'node' attribute and the pubsub 'node' attribute; i.e., for discovery purposes, a pubsub node is equivalent to a Service Discovery node. If a pubsub node is addressable as a JID plus node, the pubsub service SHOULD ensure that the NodeID conforms to the Resourceprep profile of Stringprep as described in
RFC 3920
10
].
Consider the following example, in which the (virtual) pubsub service is located at hamlet@denmark.lit.
Example 6.
Node addressed as JID+NodeID
5.
Entity Use Cases
This section defines the use cases for and protocols to be used by any entity that wishes to interact with a publish-subscribe service, mainly focused on Service Discovery use cases.
5.1 Discover Features
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.
Example 7.
Entity Queries Pubsub Service Regarding Supported Features
to='pubsub.shakespeare.lit'
id='feature1'>
Example 8.
Pubsub Service Returns Set of Supported Features
to='francisco@denmark.lit/barracks'
id='feature1'>
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.
Note: The value 'http://jabber.org/protocol/pubsub' is historically commonly advertised as a feature for a pubsub service. Although it has been used in examples of previous versions of this specification, it is not a feature that was previously normatively defined. It is RECOMMENDED that services include that value as feature for compatibility, but entities should not depend on it being advertised. To identify a pubsub service, entities can depend on the advertised service discovery identity.
5.2 Discover Nodes
The service discovery items ("disco#items") protocol enables an entity to query a service for a list of associated items, which, in the case of a pubsub service would consist of its nodes that, subject to local policies and configuration, are accessible to the requesting entity. A service SHOULD enable entities to discover the nodes by means of the
Service Discovery
protocol, subject to the recommendations in
Service Discovery (XEP-0030)
] regarding large result sets (for which
Jabber Search (XEP-0055)
11
] or some other protocol SHOULD be used). The following examples show the use of service discovery in discovering the nodes available at a pubsub service.
Example 9.
Entity requests node discovery
to='pubsub.shakespeare.lit'
id='disco1'>
Example 10.
Service responds with nodes
to='francisco@denmark.lit/barracks'
id='disco1'>
jid='pubsub.shakespeare.lit'/>
jid='pubsub.shakespeare.lit'/>
If a node is a leaf node and items have been published to the node, the service MAY return one
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).
5.3 Discover Node Information
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
an appropriate type
as registered by the XMPP registrar (e.g. "leaf").
Example 11.
Entity queries leaf node for information
to='pubsub.shakespeare.lit'
id='info1'>
Example 12.
Service responds with identity of pubsub/leaf
to='francisco@denmark.lit/barracks'
id='info1'>
...
...
5.4 Discover Node Metadata
The "disco#info" result MAY include detailed metadata about the node, encapsulated in the
Data Forms (XEP-0004)
12
] format as described in
Service Discovery Extensions (XEP-0128)
13
], where the data form context is specified by including a FORM_TYPE of "http://jabber.org/protocol/pubsub#meta-data" in accordance with
Field Standardization for Data Forms (XEP-0068)
14
]. 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.
Example 13.
Entity queries a node for information
to='pubsub.shakespeare.lit'
id='meta1'>
Example 14.
Service responds with information and metadata
to='francisco@denmark.lit/barracks'
id='meta1'>
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.
5.5 Discover Items for a Node
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
Retrieve Items from a Node
section of this document.
Example 15.
Entity requests all of the items for a node
to='pubsub.shakespeare.lit'
id='items1'>
to='francisco@denmark.lit/barracks'
id='items1'>
Note: when the service uses
JID addressing
(as opposed to (
JID+NodeID addressing
), the response to a request to Discover Items for a node (as described here) may be indistinguishable from the response to a request to
Discover Nodes
. Therefore
JID+NodeID addressing
SHOULD be used.
5.6 Retrieve Subscriptions
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
Example 16.
Entity requests all current subscriptions
to='pubsub.shakespeare.lit'
id='subscriptions1'>
If the service returns a list of subscriptions, it MUST return all subscriptions for all JIDs that match the bare JID (
For each subscription, a
Example 17.
Service returns all current subscriptions
to='francisco@denmark.lit'
id='subscriptions1'>
If the requesting entity has no subscriptions, the pubsub service MUST return an empty
Example 18.
No subscriptions
to='francisco@denmark.lit/barracks'
id='subscriptions1'>
If the service does not support subscriptions retrieval, the service MUST respond with a
Example 19.
Subscriptions retrieval not supported
to='francisco@denmark.lit/barracks'
id='subscriptions1'>
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
Example 20.
Entity requests current subscriptions from a specific node
to='pubsub.shakespeare.lit'
id='subscriptions2'>
The service would then return only the entity's subscriptions to that specific node; this acts as a filter on the entity's subscriptions.
Example 21.
Service returns all current subscriptions to a specific node
to='francisco@denmark.lit'
id='subscriptions2'>
5.7 Retrieve Affiliations
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
Example 22.
Entity requests all current affiliations
to='pubsub.shakespeare.lit'
id='affil1'>
If the service returns a list of affiliations, it MUST return all affiliations for all JIDs that match the bare JID (
For each affiliation, an
Example 23.
Service replies with all current affiliations
to='francisco@denmark.lit'
id='affil1'>
If the requesting entity has no affiliations, the pubsub service MUST return an empty
Example 24.
No affiliations
to='francisco@denmark.lit/barracks'
id='affil1'>
If the service does not support affiliations retrieval, the service MUST respond with a
Example 25.
Affiliations retrieval not supported
to='francisco@denmark.lit/barracks'
id='affil1'>
In order to make an affiliations request of a specific node, the requesting entity includes an empty
Example 26.
Entity requests affiliation at a specific node
to='pubsub.shakespeare.lit'
id='affil2'>
Example 27.
Service replies with current affiliation
to='francisco@denmark.lit'
id='affil2'>
6.
Subscriber Use Cases
This section defines the use cases for and protocols to be used by potential and actual subscribers. (Note: The
Implementation Notes
section of this document describes many important factors and business rules which a pubsub service MUST observe. In addition, the examples throughout assume the existence of a separate pubsub component and include any relevant 'from' addresses as stamped by a server or network edge.)
6.1 Subscribe to a Node
6.1.1 Request
When an XMPP entity wishes to subscribe to a node, it sends a subscription request to the pubsub service. The subscription request is an IQ-set where the
Here is an example of a subscription request.
Example 28.
Entity subscribes to a node
to='pubsub.shakespeare.lit'
id='sub1'>
jid='francisco@denmark.lit'/>
6.1.2 Success Case
If the subscription request is successfully processed, the server MUST inform the requesting entity that it is now subscribed (which MAY include a service-generated SubID).
Example 29.
Service replies with success
to='francisco@denmark.lit/barracks'
id='sub1'>
jid='francisco@denmark.lit'
subid='ba49252aaa4f5d320c24d3766f0bdcade78c78d3'
subscription='subscribed'/>
6.1.3 Error Cases
There are several reasons why the subscription request might fail:
The bare JID portions of the JIDs do not match.
The node has an access model of "presence" and the requesting entity is not subscribed to the owner's presence.
The node has an access model of "roster" and the requesting entity is not in one of the authorized roster groups.
The node has an access model of "whitelist" and the requesting entity is not on the whitelist.
The service requires payment for subscriptions to the node.
The requesting entity is anonymous and the service does not allow anonymous entities to subscribe.
The requesting entity has a pending subscription.
The requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast).
The requesting entity has attempted to establish too many subscriptions.
The node does not support subscriptions.
The node has moved.
The node does not exist.
These error cases are described more fully in the following sections.
6.1.3.1 JIDs Do Not Match
If the specified JID is a bare JID or full JID, the service MUST at a minimum check the bare JID portion against the bare JID portion of the 'from' attribute on the received IQ request to make sure that the requesting entity has the same identity as the JID which is being requested to be added to the subscriber list.
If the bare JID portions of the JIDs do not match as described above and the requesting entity does not have some kind of admin or proxy privilege as defined by the implementation, the service MUST return a
Example 30.
JIDs do not match
to='francisco@denmark.lit/barracks'
id='sub1'>
Note: An implementation MAY enable the service administrator to configure a list of entities that are excluded from this check; those entities may be considered "trusted proxies" that are allowed to subscribe on behalf of other entities. In the same way, implementations MAY enable listing of entities that are not allowed to perform specific operations (such as subscribing or creating nodes).
6.1.3.2 Presence Subscription Required
For nodes with an access model of "presence", if the requesting entity is not subscribed to the owner's presence then the pubsub service MUST respond with a
Example 31.
Entity is not authorized to create a subscription (presence subscription required)
to='francisco@denmark.lit/barracks'
id='sub1'>
6.1.3.3 Not in Roster Group
For nodes with an access model of "roster", if the requesting entity is not in one of the authorized roster groups then the pubsub service MUST respond with a
Example 32.
Entity is not authorized to create a subscription (not in roster group)
to='francisco@denmark.lit/barracks'
id='sub1'>
6.1.3.4 Not on Whitelist
For nodes with a node access model of "whitelist", if the requesting entity is not on the whitelist then the service MUST return a
Example 33.
Node has whitelist access model
to='francisco@denmark.lit/barracks'
id='sub1'>
6.1.3.5 Payment Required
Commercial deployments may wish to link subscribers to a database of paying customers. If the subscriber needs to provide payment in order to subscribe to the node (e.g., if the subscriber is not in the customer database or the customer's account is not paid up), the service SHOULD return a
Example 34.
Payment is required for a subscription
to='francisco@denmark.lit/barracks'
id='sub1'>
6.1.3.6 Anonymous Subscriptions Not Allowed
Some XMPP servers may allow authentication using SASL ANONYMOUS; however, because the resulting entity is unstable (the assigned JID may not be owned by the same principal in a persistent manner), a service MAY prevent anonymous entities from subscribing to nodes and SHOULD use service discovery to determine if an entity has an identity of "account/anonymous". If a requesting entity is anonymous but the service does not allow anonymous entities to subscribe, the service SHOULD return a
Example 35.
Requesting entity is anonymous
to='anonymous@denmark.lit/foo'
id='sub1'>
6.1.3.7 Subscription Pending
If the requesting entity has a pending subscription, the service MUST return a
Example 36.
Requesting entity has pending subscription
to='francisco@denmark.lit/barracks'
id='sub1'>
6.1.3.8 Blocked
If the requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast), the service MUST return a
Example 37.
Requesting entity is blocked
to='francisco@denmark.lit/barracks'
id='sub1'>
6.1.3.9 Too Many Subscriptions
If the requesting entity has attempted to establish too many subscriptions (where the definition of "too many" is a matter of local service policy), the service MUST return a
Example 38.
Requesting entity has exceeded limit on number of subscriptions
to='francisco@denmark.lit/barracks'
id='sub1'>
The service can match on bare JID or full JID in determining which subscribing entities match for the purpose of determining if an entity has requested too many subscriptions.
6.1.3.10 Subscriptions Not Supported
If the node does not allow entities to subscribe, the service SHOULD return a
Example 39.
Subscribing not supported
to='francisco@denmark.lit/barracks'
id='sub1'>
6.1.3.11 Node Has Moved
If the node has, the service SHOULD return a
Example 40.
Node has moved
to='francisco@denmark.lit/barracks'
id='sub1'>
xmpp:pubsub.shakespeare.lit?;node=some-other-node
6.1.3.12 Node Does Not Exist
If the node does not exist, the service SHOULD return an
Example 41.
Node does not exist
to='francisco@denmark.lit/barracks'
id='sub1'>
6.1.4 Approval Required
For nodes with an access model of "authorize", subscription requests MUST be approved by one of the node owners unless service policy allows entities with affiliations other than "none" to auto-subscribe (e.g., members and publishers might be allowed to auto-subscribe); therefore the pubsub service sends a message to the node owner(s) requesting authorization (see the
Manage Subscription Requests
section of this document). Because the subscription request may or may not be approved, the service MUST return a pending notification to the subscriber.
Example 42.
Service replies with pending
to='francisco@denmark.lit/barracks'
id='sub1'>
jid='francisco@denmark.lit'
subscription='pending'/>
6.1.5 Configuration Required
If the entity must configure its subscription options (see the
Configure Subscription Options
section of this document) before receiving event notifications, the service MUST so inform the entity. It SHOULD do so by returning an IQ-result to the requesting entity with a notation that configuration of subscription options is required.
Example 43.
Service replies with success and indicates that subscription configuration is required
to='francisco@denmark.lit/barracks'
id='sub1'>
jid='francisco@denmark.lit'
subscription='unconfigured'>
Note: The node shall include the
Alternatively, if the service is unable to create the subscription without simultaneous configuration, the service MAY return a
Example 44.
Service returns error specifying that subscription configuration is required
to='francisco@denmark.lit/barracks'
id='sub1'>
jid='francisco@denmark.lit'/>
If the
Example 45.
Service replies with success and indicates that subscription options are supported but not required
to='francisco@denmark.lit/barracks'
id='sub1'>
jid='francisco@denmark.lit'
subscription='unconfigured'>
6.1.6 Multiple Subscriptions
An entity may wish to subscribe using different subscription options, which it can do by subscribing multiple times to the same node. Support for this feature ("multi-subscribe") is OPTIONAL.
If multiple subscriptions for the same JID are allowed, the service MUST use the 'subid' attribute to differentiate between subscriptions for the same entity (therefore the SubID MUST be unique for each node+JID combination and the SubID MUST be present on the
When the pubsub service generates event notifications, it SHOULD send only one event notification to an entity that has multiple subscriptions, rather than one event notification for each subscription. By "entity" here is meant the JID specified for the subscription, whether bare JID or full JID; however, if the same bare JID has multiple subscriptions but those subscriptions are for different full JIDs (e.g., one subscription for user@domain.tld./foo and another subscription for user@domain.tld/bar), the service MUST treat those as separate JIDs for the purpose of generating event notifications.
6.1.7 Receiving the Last Published Item
When a subscription request is successfully processed, the service MAY send the last published item to the new subscriber. The message containing this item SHOULD be stamped with extended information qualified by the 'urn:xmpp:delay' namespace (see
Delayed Delivery (XEP-0203)
15
]) to indicate it is sent with delayed delivery. (Note that in this example the event notification is sent to the bare JID since that is the subscribed JID.)
Example 46.
Service sends last published item
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
href='http://denmark.lit/2003/12/13/atom03'/>
If the service sends the last published item by default for all nodes (subject to overriding by node configuration), it MUST return a feature of "http://jabber.org/protocol/pubsub#last-published" in its responsess to disco#info requests.
6.2 Unsubscribe from a Node
6.2.1 Request
To unsubscribe from a node, the subscriber sends an IQ-set whose
Example 47.
Entity unsubscribes from a node
to='pubsub.shakespeare.lit'
id='unsub1'>
jid='francisco@denmark.lit'/>
6.2.2 Success Case
If the request can be successfully processed, the service MUST return an IQ result and MAY include a
Example 48.
Service replies with success
to='francisco@denmark.lit/barracks'
id='unsub1'>
jid='francisco@denmark.lit'
subscription='none'
subid='ba49252aaa4f5d320c24d3766f0bdcade78c78d3'/>
6.2.3 Error Cases
There are several reasons why the unsubscribe request might fail:
The requesting entity has multiple subscriptions to the node but does not specify a subscription ID.
The request does not specify an existing subscriber.
The requesting entity does not have sufficient privileges to unsubscribe the specified JID.
The node does not exist.
The request specifies a subscription ID that is not valid or current.
These error cases are described more fully in the following sections.
6.2.3.1 No Subscription ID
If the requesting entity has multiple subscriptions to the node but does not specify a subscription ID, the service MUST return a
Example 49.
Entity did not specify SubID
to='francisco@denmark.lit/barracks'
id='unsub1'>
6.2.3.2 No Such Subscriber
If the value of the 'jid' attribute does not specify an existing subscriber, the pubsub service MUST return an error stanza, which SHOULD be
Example 50.
Requesting entity is not a subscriber
to='francisco@denmark.lit/barracks'
id='unsub1'>
6.2.3.3 Insufficient Privileges
If the requesting entity is prohibited from unsubscribing the specified JID, the service MUST return a
Example 51.
Requesting entity is prohibited from unsubscribing entity
to='francisco@denmark.lit/barracks'
id='unsub1'>
6.2.3.4 Node Does Not Exist
If the node does not exist, the pubsub service MUST return an
Example 52.
Node does not exist
to='francisco@denmark.lit/barracks'
id='unsub1'>
6.2.3.5 Bad Subscription ID
If a subscription identifier is associated with the subscription, the unsubscribe request MUST include an appropriate 'subid' attribute. If the unsubscribe request includes a SubID but SubIDs are not supported for the node (or the subscriber did not subscribe using a SubID in the first place), the service SHOULD ignore the SubID and simply unsubscribe the entity. If the subscriber originally subscribed with a SubID but the unsubscribe request includes a SubID that is not valid or current for the subscriber, the service MUST return a
Example 53.
Invalid subscription identifier
to='francisco@denmark.lit/barracks'
id='unsub1'>
6.3 Configure Subscription Options
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).
6.3.1 Advertising Support
If a service supports subscription options it MUST advertise that fact in its response to a "disco#info" query by including a feature whose 'var' attribute is "pubsub#subscription-options".
Example 54.
Pubsub service indicates support for subscription options
to='francisco@denmark.lit/barracks'
id='feature1'>
...
...
6.3.2 Request
A subscriber requests the subscription options by including an
Example 55.
Subscriber requests subscription options form
to='pubsub.shakespeare.lit'
id='options1'>
6.3.3 Success Case
If the request can be successfully processed, the service MUST respond with the options.
Example 56.
Service responds with the options form
to='francisco@denmark.lit/barracks'
id='options1'>
type='list-multi'
label='Select the presence types which are
allowed to receive event notifications'>
Note: The foregoing example shows some (but by no means all) of the possible configuration options that MAY be provided. If an implementation provides these options using the
Data Forms
protocol, it MUST use the field variables that are registered with the XMPP Registrar in association with the 'http://jabber.org/protocol/pubsub' namespace (a preliminary representation of those field variables is shown above and in the
pubsub#subscribe_options FORM_TYPE
section of this document, but MUST NOT be construed as canonical since the XMPP Registrar may standardize additional fields at a later date without changes to this document).
Note: Many of the relevant data form fields are of type "boolean" and MUST be handled accordingly. [
16
6.3.4 Error Cases
There are several reasons why the options request might fail:
The requesting entity does not have sufficient privileges to modify subscription options for the specified JID.
The requesting entity (or specified subscriber) is not subscribed.
The request does not specify both the NodeID and the subscriber's JID.
The request does not specify a subscription ID but one is required.
The request specifies a subscription ID that is not valid or current.
Subscription options are not supported.
The node does not exist.
These error cases are described more fully in the following sections.
6.3.4.1 Insufficient Privileges
When requesting subscription options, the subscriber MUST specify the JID that is subscribed to the node and SHOULD specify a node (if no node is specified, i.e. via node="", the service MUST assume that the requesting entity wishes to request subscription options for its subscription to the root collection node; refer to
PubSub Collection Nodes (XEP-0248)
] for details).
The service MUST validate that the entity making the request is authorized to set the subscription options for the subscribed entity. If the subscriber's JID is of the form (
Example 57.
Requesting entity does not have sufficient privileges to modify subscription options
to='francisco@denmark.lit/barracks'
id='sub1'>
6.3.4.2 No Such Subscriber
If the requesting entity (or specified subscriber, if different) is not subscribed, the service MUST return an
Example 58.
No such subscriber
to='francisco@denmark.lit/barracks'
id='options1'>
6.3.4.3 Subscriber JID Required
If the subscriber does not specify a subscriber JID, the service MUST return a
Example 59.
Subscriber JID not specified
to='francisco@denmark.lit/barracks'
id='options1'>
6.3.4.4 Subscription ID Required
If a subscription identifier is associated with the subscription, the 'subid' attribute MUST be present on the request in order for the service to differentiate subscriptions for the same entity. If the 'subid' is required but not provided, the service MUST return a
Example 60.
SubID required
to='francisco@denmark.lit/barracks'
id='sub1'>
6.3.4.5 Invalid Subscription ID
If a subscription identifier is associated with the subscription but the request includes a SubID that is not valid or current for the subscriber, the service MUST return a
Example 61.
Invalid subscription identifier
to='francisco@denmark.lit/barracks'
id='unsub1'>
6.3.4.6 Subscription Options Not Supported
If the node or service does not support subscription options, the service MUST respond with a
Example 62.
Subscription options not supported
to='francisco@denmark.lit/barracks'
id='options1'>
6.3.4.7 Node Does Not Exist
If the node does not exist, the pubsub service MUST return an
Example 63.
Node does not exist
to='francisco@denmark.lit/barracks'
id='options1'>
6.3.5 Form Submission
After receiving the configuration form, the requesting entity SHOULD submit the form in order to update the entity's subscription options for that node.
Example 64.
Subscriber submits completed options form
to='pubsub.shakespeare.lit'
id='options2'>
6.3.6 Form Processing
6.3.6.1 Success
If the service can successfully process the submission, it MUST respond with success.
Example 65.
Service responds with success
to='francisco@denmark.lit/barracks'
id='options2'/>
6.3.6.2 Failure
If the subscriber attempts to set an invalid group of options, the service MUST respond with a
Example 66.
Service responds with Bad Request for invalid options
to='francisco@denmark.lit/barracks'
id='options2'>
The other errors already mentioned for getting subscription options also apply to setting subscription options.
6.3.7 Subscribe and Configure
As noted, if a service supports subscription options, an entity MAY subscribe and provide the subscription options in the same stanza.
Note: The
Example 67.
Entity subscribes to node and sets configuration options
to='pubsub.shakespeare.lit'
id='sub1'>
When the service informs the client of success, it SHOULD include a data form of type "result" informing the client of the resulting configuration options.
Example 68.
Service replies with success (including configuration options)
to='francisco@denmark.lit/barracks'
id='sub1'>
jid='francisco@denmark.lit'
subid='ba49252aaa4f5d320c24d3766f0bdcade78c78d3'
subscription='subscribed'/>
6.4 Request Default Subscription Configuration Options
An entity might want to request information about the default subscription configuration. Support for this feature is OPTIONAL.
6.4.1 Request
To get the default subscription options for a node, the entity MUST send an empty
Example 69.
Entity requests default subscription configuration options
to='pubsub.shakespeare.lit'
id='def1'>
Note: Here the namespace is 'http://jabber.org/protocol/pubsub' (not 'http://jabber.org/protocol/pubsub#owner' as for retrieval of the default node configuration options).
The service itself MAY also have default subscription configuration options. To get the default subscription configuration options all (leaf) nodes at a service, the entity MUST send an empty
Example 70.
Entity requests default subscription configuration options
to='pubsub.shakespeare.lit'
id='def2'>
6.4.2 Success Case
If no error occurs, the node MUST return the default subscription configuration options.
Example 71.
Service responds with default subscription configuration options
to='francisco@denmark.lit/barracks'
id='def1'>
6.4.3 Error Cases
There are several reasons why the default subscription configuration options request might fail:
The service does not support subscription configuration.
The service does not support retrieval of default subscription configuration.
These error cases are described more fully in the following sections.
6.4.3.1 Node Configuration Not Supported
If the node does not support subscription configuration, it MUST return a
Example 72.
Service does not support subscription configuration
to='francisco@denmark.lit/barracks'
id='def1'>
6.4.3.2 Default Subscription Configuration Retrieval Not Supported
If the node does not support retrieval of default subscription configuration options, it MUST return a
Example 73.
Service does not support retrieval of default subscription configuration options
to='francisco@denmark.lit/barracks'
id='def1'>
6.5 Retrieve Items from a Node
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).
6.5.1 Permissions
The service MUST conform to the node's access model in determining whether to return items to the entity that requests them. Specifically:
If the access model is "open", the service SHOULD allow any entity (whether or not it is subscribed) to retrieve items.
If the access model is "presence", the service SHOULD allow any entity that is subscribed to the owner's presence to retrieve items.
If the access model is "roster", the service SHOULD allow any entity that is subscribed to the owner's presence and contained in the relevant roster group(s) to retrieve items.
If the access model is "authorize" or "whitelist", the service MUST allow only subscribed entities to retrieve items.
The only exception foreseen to the SHOULD requirements for the foregoing access models 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 node owner to retrieve items from a node and SHOULD always allow a publisher to do so.)
6.5.2 Requesting All Items
The subscriber may request all items by specifying only the Node ID without restrictions.
Example 74.
Subscriber requests all items
to='pubsub.shakespeare.lit'
id='items1'>
6.5.3 Returning All Items
The service then SHOULD return all available items at the node, although it MAY truncate the result set if a large number of items has been published (see next section) and naturally it cannot return items that have been deleted, expired, etc.
Example 75.
Service returns all items
to='francisco@denmark.lit/barracks'
id='items1'>
O, that this too too solid flesh would melt
Thaw and resolve itself into a dew!
href='http://denmark.lit/2003/12/13/atom03'/>
O all you host of heaven! O earth! what else?
And shall I couple hell? O, fie! Hold, hold, my heart;
And you, my sinews, grow not instant old,
But bear me stiffly up. Remember thee!
href='http://denmark.lit/2003/12/13/atom03'/>
Now I am alone.
O, what a rogue and peasant slave am I!
href='http://denmark.lit/2003/12/13/atom03'/>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
href='http://denmark.lit/2003/12/13/atom03'/>
6.5.4 Returning Some Items
A node may have a large number of items associated with it, in which case it may be problematic to return all of the items in response to an items request. In this case, the service SHOULD return some of the items and note that the list of items has been truncated by including a
Result Set Management (XEP-0059)
17
] notation.
A Pubsub entity supporting
Result Set Management (XEP-0059)
17
] SHOULD include a feature of "http://jabber.org/protocol/pubsub#rsm" in its disco#info response, to make it clear that the RSM feature is for PubSub, and not for e.g.,
Message Archive Management (XEP-0313)
18
].
Example 76.
Service returns some items via result set management
to='francisco@denmark.lit/barracks'
id='items1'>
O, that this too too solid flesh would melt
Thaw and resolve itself into a dew!
href='http://denmark.lit/2003/12/13/atom03'/>
O all you host of heaven! O earth! what else?
And shall I couple hell? O, fie! Hold, hold, my heart;
And you, my sinews, grow not instant old,
But bear me stiffly up. Remember thee!
href='http://denmark.lit/2003/12/13/atom03'/>
Now I am alone.
O, what a rogue and peasant slave am I!
href='http://denmark.lit/2003/12/13/atom03'/>
6.5.5 Returning the Last Published Item
Even if the service or node does not support persistent items, it MAY return the last published item.
Example 77.
Service returns last published item
to='francisco@denmark.lit/barracks'
id='items1'>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
href='http://denmark.lit/2003/12/13/atom03'/>
6.5.6 Returning Notifications Only
A service MAY return event notifications without payloads (e.g., to conserve bandwidth). If so, the client MAY request a specific item (using the ItemID) in order to retrieve the payload. When an entity requests items by ItemID, implementations MUST allow multiple items to be specified in the request.
Example 78.
Subscriber requests specific items by ItemID
to='pubsub.shakespeare.lit'
id='items3'>
Example 79.
Service sends requested item(s)
id='items3'>
O, that this too too solid flesh would melt
Thaw and resolve itself into a dew!
href='http://denmark.lit/2003/12/13/atom03'/>
Now I am alone.
O, what a rogue and peasant slave am I!
href='http://denmark.lit/2003/12/13/atom03'/>
6.5.7 Requesting the Most Recent Items
A service MAY allow entities to request the most recent N items by using the 'max_items' attribute. When max_items is used, implementations SHOULD return the N most recent (as opposed to the N oldest) items. (Note: A future version of this specification may recommend the use of
Result Set Management (XEP-0059)
17
] instead of the 'max_items' attribute.)
Example 80.
Subscriber requests two most recent items
to='pubsub.shakespeare.lit'
id='items2'>
Example 81.
Service returns two most recent items
to='francisco@denmark.lit/barracks'
id='items2'>
Now I am alone.
O, what a rogue and peasant slave am I!
href='http://denmark.lit/2003/12/13/atom03'/>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
href='http://denmark.lit/2003/12/13/atom03'/>
If there are fewer items in the node than requested, the service should return all of them.
Example 82.
Service returns no items if it has none
to='francisco@denmark.lit/barracks'
id='items2'>
6.5.8 Requesting a Particular Item
The subscriber can request a particular item by specifying the Node ID and the appropriate ItemID.
Example 83.
Subscriber requests a particular item
to='pubsub.shakespeare.lit'
id='items3'>
The service would then return that specific item, if available.
6.5.9 Error Cases
There are several reasons why the items retrieval request might fail:
The requesting entity has multiple subscriptions to the node but does not specify a subscription ID.
The requesting entity is subscribed but specifies an invalid subscription ID.
The node does not return items to unsubscribed entities and the requesting entity is not subscribed.
The service or node does not support persistent items and does not return the last published item.
The service or node does not support item retrieval.
The node has an access model of "presence" and the requesting entity is not subscribed to the owner's presence.
The node has an access model of "roster" and the requesting entity is not in one of the authorized roster groups.
The node has an access model of "whitelist" and the requesting entity is not on the whitelist.
The service or node requires payment for item retrieval.
The requesting entity is blocked from retrieving items from the node (e.g., because having an affiliation of outcast).
The node does not exist.
These error cases are described more fully in the following sections.
6.5.9.1 Subscription ID Required
If the requesting entity has multiple subscriptions to the node but does not specify a subscription ID, the service MUST return a
Example 84.
Entity did not specify SubID
to='francisco@denmark.lit/barracks'
id='items1'>
6.5.9.2 Invalid Subscription ID
If the requesting entity is subscribed but specifies an invalid subscription ID, the service MUST return a
Example 85.
Entity specified invalid SubID
to='francisco@denmark.lit/barracks'
id='items1'>
6.5.9.3 Entity Not Subscribed
If the node does not return items to unsubscribed entities and the requesting entity is not subscribed (which includes having a pending subscription), the service MUST return a
Example 86.
Entity is not subscribed
to='francisco@denmark.lit/barracks'
id='items1'>
6.5.9.4 Persistent Items Not Supported
If the service or node does not support persistent items and does not return the last published item, the service MUST return a
Example 87.
Persistent items not supported
to='francisco@denmark.lit/barracks'
id='items1'>
6.5.9.5 Item Retrieval Not Supported
If the service or node does not support item retrieval (e.g., because the node is a collection node as described in
PubSub Collection Nodes (XEP-0248)
]), the service MUST return a
Example 88.
Item retrieval not supported
to='francisco@denmark.lit/barracks'
id='items1'>
6.5.9.6 Presence Subscription Required
For nodes with an access model of "presence", if the requesting entity is not subscribed to the owner's presence then the pubsub service MUST respond with a
Example 89.
Entity is not authorized to retrieve items (presence subscription required)
to='francisco@denmark.lit/barracks'
id='items1'>
6.5.9.7 Not in Roster Group
For nodes with an access model of "roster", if the requesting entity is not in one of the authorized roster groups then the pubsub service MUST respond with a
Example 90.
Entity is not authorized to retrieve items (not in roster group)
to='francisco@denmark.lit/barracks'
id='items1'>
6.5.9.8 Not on Whitelist
For nodes with a node access model of "whitelist", if the requesting entity is not on the whitelist then the service MUST return a
Example 91.
Node has whitelist access model
to='francisco@denmark.lit/barracks'
id='items1'>
6.5.9.9 Payment Required
Commercial deployments may wish to link subscribers to a database of paying customers. If the subscriber needs to provide payment in order to retrieve items from the node (e.g., if the subscriber is not in the customer database or the customer's account is not paid up), the service SHOULD return a
Example 92.
Payment is required to retrieve items
to='francisco@denmark.lit/barracks'
id='items1'>
6.5.9.10 Blocked
If the requesting entity is blocked from retrieving items (e.g., because having an affiliation of outcast), the service MUST return a
Example 93.
Requesting entity is blocked
to='francisco@denmark.lit/barracks'
id='items1'>
6.5.9.11 Node Does Not Exist
If the node does not exist, the service SHOULD return an
Example 94.
Node does not exist
to='francisco@denmark.lit/barracks'
id='items1'>
6.5.9.12 No Such Item(s)
If there are no items at the node or the requested items do not exist, the service SHOULD return an IQ stanza of type "result" with an empty
Example 95.
No such item(s)
to='francisco@denmark.lit/barracks'
type='result'>
7.
Publisher Use Cases
7.1 Publish an Item to a Node
7.1.1 Request
A pubsub service MAY support the ability to publish items (if so, it MUST advertise support for the "http://jabber.org/protocol/pubsub#publish" feature). Any entity that is allowed to publish items to a node (i.e., a publisher or an owner) may do so at any time by sending an IQ-set to the service containing a pubsub element with a
The syntax is as follows:
The
Depending on the node configuration, the
19
] [
20
The
Example 96.
Publisher publishes an item with an ItemID
to='pubsub.shakespeare.lit'
id='publish1'>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
href='http://denmark.lit/2003/12/13/atom03'/>
Example 97.
Publisher publishes an item without an ItemID
to='pubsub.shakespeare.lit'
id='publish2'>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
href='http://denmark.lit/2003/12/13/atom03'/>
7.1.2 Success Case
If the pubsub service can successfully process the request, it MUST inform the publisher of success. If the publish request did not include an ItemID, the IQ-result SHOULD include an empty
Example 98.
Service replies with success
to='hamlet@denmark.lit/blogbot'
id='publish1'>
Example 99.
Service replies with success and the ID of the new item
to='hamlet@denmark.lit/blogbot'
id='publish2'>
Note: If the publisher previously published an item with the same ItemID, successfully processing the request means that the service MUST overwrite the old item with the new item and then proceed as follows.
The pubsub service MUST then send one event notification to each entity that meets the criteria for receiving an event notification (typically to each approved subscriber, although there are other contexts in which an entity may receive an event notification as summarized under
Notification Triggers
). Each
Handling Notification-Related Errors
section of this document). Depending on the node configuration, the event notification either will or will not contain the payload, as shown below.
Note: In order to facilitate authorization for item removal as described in the
Delete an Item from a Node
section of this document, implementations that support persistent items SHOULD store the item (if the node is so configured) and maintain a record of the publisher.
7.1.2.1 Notification With Payload
If the node is configured to include payloads, the subscribers will receive payloads with the event notifications.
Example 100.
Subscribers receive event notifications with payloads
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
href='http://denmark.lit/2003/12/13/atom03'/>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
href='http://denmark.lit/2003/12/13/atom03'/>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
href='http://denmark.lit/2003/12/13/atom03'/>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
href='http://denmark.lit/2003/12/13/atom03'/>
7.1.2.2 Notification Without Payload
If the node is configured to not include payloads, the subscribers will receive event notifications only. (If payloads are not included, subscribers may request the published item via the protocol defined in the
Retrieve Items from a Node
section of this document.)
Example 101.
Subscribers receive event notifications only
7.1.2.3 Item Publisher
If configured to do so (see
Associating Events and Payloads with the Generating Entity
), the service can include the publisher of the item when it generates event notifications.
Example 102.
Service Notifies Subscribers
[ ... ENTRY ... ]
If so, the service MUST also include the publisher with every other form of item retrieval.
Example 103.
Service returns items
to='francisco@denmark.lit/barracks'
id='items1'>
[ ... ENTRY ... ]
[ ... MORE ITEMS ... ]
The value of the 'publisher' attribute MUST be generated by the service, not accepted by the service in the published item, since allowing the publisher to assert its JID would open the possibility of spoofing.
The JID stamped by the service can be either (1) the full JID
7.1.2.4 Inclusion of Subscription ID
If a single entity is subscribed to a node multiple times, the service SHOULD notate the event notification so that the entity can determine which subscription identifier(s) generated this event. If these notations are included, they MUST use the
Stanza Headers and Internet Metadata (XEP-0131)
21
] format and SHOULD be included after the event notification information (i.e., as the last child of the
Example 104.
Subscriber receives notated event notification
7.1.2.5 Node is full
If the service or node is configured so that there is a maximum number of items cached at the node and the maximum is reached when an item is published, the service MUST delete one of the existing items or reject the new item.
The behaviour of the service is determined by the "pubsub#publish_node_full" option which may take one of the following values: "retract-oldest", "discard-oldest", or "reject".
The "retract-oldest" option is the default one and SHOULD be implemented even if this configuration isn't supported.
It is RECOMMENDED for the service to follow the "first in, first out" rule and retract the oldest item. Depending on node configuration, deletion of an existing item MAY result in sending of a retract notification to the subscribers.
When configured as "discard-oldest", a service MUST discard the oldest item.
The "reject" option for this configuration is described in
Node is full
publishing errors.
7.1.3 Error Cases
There are several reasons why the publish request might fail:
The requesting entity does not have sufficient privileges to publish.
The node does not support item publication.
The node does not exist.
The node is full (max_items exceeded).
The payload size exceeds a service-defined limit.
The item contains more than one payload element or the namespace of the root payload element does not match the configured namespace for the node.
The request does not match the node configuration.
These error cases are described more fully in the following sections.
Note: If a publisher publishes an item with an Item ID and the ItemID matches that of an existing item, the pubsub service MUST NOT fail the publication but instead MUST overwrite the existing item and generate a new event notification (i.e., re-publication is equivalent to modification).
7.1.3.1 Insufficient Privileges
If the requesting entity does not have sufficient privileges to publish, the service MUST return a
Example 105.
Entity does not have sufficient privileges to publish to node
id='publish1'>
7.1.3.2 Item Publication Not Supported
If the node does not support item publication (e.g., because it is a collection node as described in
PubSub Collection Nodes (XEP-0248)
]), the service MUST return a
Example 106.
Node does not support item publication
to='hamlet@denmark.lit/elsinore'
id='publish1'>
7.1.3.3 Node Does Not Exist
If the requesting entity attempts to publish an item to a node that does not exist and the service does not support the "auto-create" feature (see
Automatic Node Creation
), the service MUST return an
Example 107.
Entity attempts to publish to a non-existent node
to='hamlet@denmark.lit/elsinore'
id='publish1'>
7.1.3.4 Node is full
If the requesting entity attempts to publish an item to a node that has reached its maximum number of items, visible via pubsub#max_items, and the pubsub#publish_full_node configuration value is set to "reject", then the service MUST return a
Example 108.
Entity attempts to publish to a node with max_items reached
to='hamlet@denmark.lit/elsinore'
id='publish1'>
7.1.3.5 Payload Too Big
If the payload size exceeds a service-defined limit, the service MUST return a
Example 109.
Entity attempts to publish very large payload
to='hamlet@denmark.lit/elsinore'
id='publish1'>
7.1.3.6 Bad Payload
If the
Example 110.
Entity attempts to publish item with multiple payload elements or namespace does not match
to='hamlet@denmark.lit/elsinore'
id='publish1'>
7.1.3.7 Request Does Not Match Configuration
If the request does not conform to the configured
event type
for the node, the service MAY bounce the request with a
If the event type is persistent (either event notification or payload) and the publisher does not specify an ItemID, the service MUST generate the ItemID and MUST NOT bounce the publication request.
If the event type is persistent (either event notification or payload) and the publisher does not include an item, the service MUST bounce the publication request with a
If the event type is payload (either persistent or transient) and the publisher does not include a payload, the service SHOULD bounce the publication request with a
If the event type is notification + transient and the publisher provides an item, the service MUST bounce the publication request with a
Examples of these errors are shown below.
Example 111.
Publisher attempts to publish to persistent node with no item
to='hamlet@denmark.lit/elsinore'
id='publish1'>
Example 112.
Publisher attempts to publish to payload node with no payload
to='hamlet@denmark.lit/elsinore'
id='publish1'>
Example 113.
Publisher attempts to publish to transient notification node with item
to='hamlet@denmark.lit/elsinore'
id='publish1'>
7.1.4 Automatic Node Creation
A pubsub service MAY automatically create a node when it receives a publish request sent to a node that does not exist (instead of returning an
7.1.5 Publishing Options
A pubsub service MAY support the ability to specify options along with a publish request (if so, it MUST advertise support for the "http://jabber.org/protocol/pubsub#publish-options" feature). Here is an example:
Example 114.
Publishing with options
to='pubsub.shakespeare.lit'
id='pub1'>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
href='http://denmark.lit/2003/12/13/atom03'/>
The
Data Forms (XEP-0004)
12
]), whose FORM_TYPE MUST be "http://jabber.org/protocol/pubsub#publish-options" (see
XEP-0068
).
Each form field denotes a precondition to publishing the request. A pub-sub service advertising support for publishing options MUST check each precondition field against the node configuration of the same name, and it MUST reject the publication upon encountering unknown fields.
Preconditions MUST be processed as follows:
If the node exists and the precondition is not met, then the publish MUST fail with a
If the node exists and the precondition is met, then the publish succeeds.
If the node does not exist and the service supports the "auto-create" feature, then the service shall auto-create the node with default configuration in all respects except those specified in the preconditions, and the publish succeeds.
If the node does not exist and the service does not support the "auto-create" feature, then the publish shall fail.
7.2 Delete an Item from a 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.
7.2.1 Request
To delete an item, the publisher sends a retract request as shown in the following examples. The
Example 115.
Entity deletes an item from a node
to='pubsub.shakespeare.lit'
id='retract1'>
7.2.2 Success Case
If no error occurs, the service MUST delete the item.
Example 116.
Service replies with success
to='hamlet@denmark.lit/elsinore'
id='retract1'/>
7.2.2.1 Delete And Notify
If no error occurs and the
16
], then the service MUST delete the item and MUST notify all subscribers as shown below. The syntax is identical to event notifications except that instead of an
Example 117.
Subscribers are notified of deletion
7.2.2.2 Inclusion of Subscription ID
If a single entity is subscribed to the node multiple times, the service SHOULD notate the item deletion so that the entity can determine which subscription identifier(s) generated this event. As above, if these notations are included, they MUST use the
Stanza Headers and Internet Metadata (SHIM)
protocol and SHOULD be included after the notification data (i.e., as the last child of the
Example 118.
Subscriber receives notated event notification
7.2.3 Error Cases
There are several reasons why the item retraction request might fail:
The publisher does not have sufficient privileges to delete the requested item.
The node or item does not exist.
The request does not specify a node.
The request does not include an
The node does not support persistent items.
The service does not support the deletion of items.
These error cases are described more fully in the following sections.
7.2.3.1 Insufficient Privileges
If the requesting entity does not have sufficient privileges to delete the item, the service MUST return a
Example 119.
Requesting entity does not have sufficient privileges
to='hamlet@denmark.lit/elsinore'
id='retract1'>
7.2.3.2 Node Does Not Exist
If the node or item does not exist, the service MUST return an
Example 120.
Non-existent node or item
to='hamlet@denmark.lit/elsinore'
id='retract1'>
7.2.3.3 NodeID Required
If the request does not specify a node, the service MUST return a
Example 121.
Request does not specify a node
to='hamlet@denmark.lit/elsinore'
id='retract1'>
7.2.3.4 Item or ItemID Required
If the request does not include an
Example 122.
Request does not specify an item
to='hamlet@denmark.lit/elsinore'
id='retract1'>
7.2.3.5 Persistent Items Not Supported
If the node does not support persistent items (e.g., because it is a collection node or a transient node that does not deliver payloads), the service MUST return a
Example 123.
Node does not support persistent items
to='hamlet@denmark.lit/elsinore'
id='retract1'>
7.2.3.6 Item Deletion Not Supported
If the service does not support item deletion, it MUST return a
Example 124.
Service does not support item deletion
to='hamlet@denmark.lit/elsinore'
id='retract1'>
8.
Owner Use Cases
8.1 Create a Node
8.1.1 General Considerations
An entity may want to create a new node. Support for this feature ("create-nodes") is RECOMMENDED. However, a service MAY disallow creation of nodes based on the identity of the requesting entity, or MAY disallow node creation altogether (e.g., reserving that privilege to a service-wide administrator).
There are two ways to create a node:
Create a node with default configuration for the specified node type.
Create and configure a node simultaneously.
Example 125.
Request to create a node
to='pubsub.shakespeare.lit'
id='create1'>
These methods, along with method-specific error conditions, are explained more fully in the following sections.
In addition to method-specific error conditions, there are several general reasons why the node creation request might fail:
The service does not support node creation.
Only entities that are registered with the service are allowed to create nodes but the requesting entity is not registered.
The requesting entity does not have sufficient privileges to create nodes.
The requested NodeID already exists.
The request did not include a NodeID and "instant nodes" are not supported.
These general error cases are described more fully below.
If the service does not support node creation, it MUST respond with a
Example 126.
Service does not support node creation
to='hamlet@denmark.lit/elsinore'
id='create1'>
If only entities that are registered with the service may create nodes but the requesting entity has not yet registered, the service MUST respond with a
Example 127.
Service requires registration
to='hamlet@denmark.lit/elsinore'
id='create1'>
If the requesting entity does not have sufficient privileges to create nodes, the service MUST respond with a
Example 128.
Requesting entity is prohibited from creating nodes
to='hamlet@denmark.lit/elsinore'
id='create1'>
If the requested NodeID already exists, the service MUST respond with a
Example 129.
NodeID already exists
to='hamlet@denmark.lit/elsinore'
id='create1'>
If the node creator does not specify a NodeID but the service does not support instant nodes, the service MUST return a
Example 130.
Service does not support instant nodes
to='hamlet@denmark.lit/elsinore'
id='create2'>
If the node creator does not specify a NodeID but the service supports instant nodes, the service SHOULD generate a NodeID that is unique within the context of the service on behalf of the node creator.
Example 131.
Entity requests an instant node
to='pubsub.shakespeare.lit'
id='create2'>
If no error occurs, the pubsub service SHOULD create the node, generate a NodeID that is unique within the context of that service, and inform the user of success (including the NodeID in the response).
Example 132.
Service replies with success and generated NodeID
to='hamlet@denmark.lit/elsinore'
id='create2'>
Note: When a service successfully creates a node on behalf of the requesting entity, it MUST return an IQ result (in accordance with XMPP Core). If the node creation request did not specify a NodeID and the service supports creation of instant nodes, the service MUST specify the created NodeID in the IQ result. Similarly, if the node creation request specified a NodeID but the service modified the NodeID before creating the node, the service MUST also specify the modified node in the IQ result. In all other cases, the service MAY specify the NodeID in the IQ result but the node creator MUST NOT depend on receiving it from the service (since the node creator can determine which node was created by tracking the 'id' attribute that it specified for the IQ-set).
8.1.2 Create a Node With Default Configuration
As explained above, each node type has its own default configuration. By asking the service to create a node with default configuration, the node creator accepts the default configuration. If the service allows node configuration, the owner may reconfigure the node after creating the node (as described in the
Configure a Node
section of this document). In addition, a service MAY allow entities to determine the default configuration options for a given node type before creating a node (as described in the
Request Default Node Configurations
section of this document).
In order to create a node with default configuration, the node creator can simply include an empty
In the following example, the node creator requests a leaf node (the default type) with an open access model (assumed to be the default type for this service).
Example 133.
Entity requests leaf node with (default) open access model
to='pubsub.shakespeare.lit'
id='create1'>
Note: The default setting for the 'pubsub#node_type' configuration field is "leaf".
In order to request an access model other than the default for the service, the node creator MUST include a Data Form in the node creation request that specifies a non-default value for the 'pubsub#access_model' field.
Example 134.
Entity requests leaf node with non-default access model
to='pubsub.shakespeare.lit'
id='create2'>
If the access model is supported and none of the general or method-specific errors has occurred, the service SHOULD create the node and inform the requesting entity of success.
Example 135.
Service informs requesting entity of success
to='hamlet@denmark.lit/elsinore'
id='create1'/>
If service does not support the specified access model, it MUST return a
Example 136.
Service does not support specified access model
to='hamlet@denmark.lit/elsinore'
id='create2'>
(For error handling if the service does not support the specified node type, refer to
PubSub Collection Nodes (XEP-0248)
].)
8.1.3 Create and Configure a Node
If an implementation allows node configuration (see the
Configure a Node
section of this document), it SHOULD allow node creation requests to contain the desired node configuration in the node creation request.
Note: The
Example 137.
Entity requests a new node with non-default configuration.
to='pubsub.shakespeare.lit'
id='create1'>
Example 138.
Service replies with success
to='hamlet@denmark.lit/elsinore'
id='create1'/>
If a service supports this "create-and-configure" feature, it MUST advertise that fact by returning a feature of "http://jabber.org/protocol/pubsub#create-and-configure" in response to service discovery information requests. If the create-and-configure option is not supported but the requesting entity sends such a request anyway, the service SHOULD ignore the configuration part of the request and proceed as if it had not been included.
8.2 Configure a Node
After creating a new node, the node owner may want to modify the node configuration. Support for this feature is RECOMMENDED.
8.2.1 Request
Example 139.
Owner requests configuration form
to='pubsub.shakespeare.lit'
id='config1'>
8.2.2 Success Case
If no error occurs, the server MUST return a configuration form to the node owner, which SHOULD contain the current node configuration as the default values.
Note: The following example shows some of the possible configuration options that MAY be provided. If an implementation implements these features using the
Data Forms
protocol, that implementation MUST use the fields that are registered with the XMPP Registrar in association with the 'http://jabber.org/protocol/pubsub' namespace (a preliminary representation of those field variables is shown below and in the
pubsub#node_config FORM_TYPE
section of this document, but MUST NOT be construed as canonical, since the XMPP Registrar may standardize additional fields at a later date without changes to this document). An implementation MAY choose to specify different labels, values, and even field types, but MUST conform to the defined variable naming scheme.
Example 140.
Service responds with configuration form
to='hamlet@denmark.lit/elsinore'
id='config1'>
8.2.3 Error Cases
There are several reasons why the node configuration request might fail:
The service does not support node configuration.
The requesting entity does not have sufficient privileges to configure the node.
The request did not specify a node.
The node has no configuration options.
The specified node does not exist.
These error cases are described more fully in the following sections.
8.2.3.1 Node Configuration Not Supported
If the service does not support node configuration, the service MUST return a
Example 141.
Service does not support node configuration
to='pubsub.shakespeare.lit'
id='config1'>
8.2.3.2 Insufficient Privileges
If the requesting entity does not have sufficient privileges to configure the node, the service MUST respond with a
Example 142.
Requesting entity is prohibited from configuring this node
to='hamlet@denmark.lit/elsinore'
id='config1'>
8.2.3.3 NodeID Required
If the request did not specify a node, the service SHOULD return a
Example 143.
Request did not specify a node
to='pubsub.shakespeare.lit'
id='config1'>
8.2.3.4 No Configuration Options
If no configuration options are available (e.g., because node configuration is "locked down"), the service MUST return a
Example 144.
Node has no configuration options
to='pubsub.shakespeare.lit'
id='config1'>
8.2.3.5 Node Does Not Exist
If the node does not exist, the service MUST return an
Example 145.
Node does not exist
to='hamlet@denmark.lit/elsinore'
id='config1'>
8.2.4 Form Submission
After receiving the configuration form, the owner SHOULD submit a completed configuration form. Note that the
rules of XEP-0004 for incomplete submission form handling
apply.
Example 146.
Owner submits node configuration form
to='pubsub.shakespeare.lit'
id='config2'>
Alternatively, the owner MAY cancel the configuration process, in which case the existing configuration MUST be applied.
Example 147.
Owner cancels configuration process
to='pubsub.shakespeare.lit'
id='config2'>
8.2.5 Form Processing
8.2.5.1 Success
If the form can be successfully processed, the service MUST return an IQ-result.
Example 148.
Service replies with success
to='hamlet@denmark.lit/elsinore'
id='config2'/>
8.2.5.2 Failure
If the requested node configuration change cannot be processed (e.g., because the node owner has attempted to change the configuration so that there are no node owners), the service MUST return a
Example 149.
Configuration change cannot be processed
to='hamlet@denmark.lit/elsinore'
id='config2'>
8.2.5.3 Success With Notifications
If the "pubsub#notify_config" option is set to true, the service MUST notify subscribers of the configuration change. (A service SHOULD support this option for leaf nodes.) If the node configuration is set to notification-only, the notification MUST consist of an empty
Data Forms
protocol.
Example 150.
Service sends configuration change notification (event notification only)
Example 151.
Service sends configuration change notification (full payload)
8.3 Request Default Node Configuration Options
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.
8.3.1 Request
To get the node options, the entity MUST send an empty
Example 152.
Entity requests default node configuration options
to='pubsub.shakespeare.lit'
id='def1'>
8.3.2 Request
A service may support several node types. The default configuration for each node type may be different. To request the node options that are specific to a particular node type, the entity MAY include an attribute named 'type' in the
Example 153.
Entity requests default node configuration options
to='pubsub.shakespeare.lit'
id='def1collection'>
8.3.3 Success Case
If no error occurs, the service MUST return the default node configuration options.
Example 154.
Service responds with default node configuration options
to='hamlet@denmark.lit/elsinore'
id='def1'>
8.3.4 Error Cases
There are several reasons why the default node configuration options request might fail:
The service does not support node configuration.
The service does not support retrieval of default node configuration.
These error cases are described more fully in the following sections.
8.3.4.1 Node Configuration Not Supported
If the service does not support node configuration, it MUST return a
Example 155.
Service does not support node configuration
to='hamlet@denmark.lit/elsinore'
id='def1'>
8.3.4.2 Default Node Configuration Retrieval Not Supported
If the service does not support retrieval of default node configuration options, it MUST return a
Example 156.
Service does not support retrieval of default node configuration options
to='hamlet@denmark.lit/elsinore'
id='def1'>
8.4 Delete a Node
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.
8.4.1 Request
In order to delete a node, a node owner MUST send a node deletion request, consisting of a
Example 157.
Owner deletes a node
to='pubsub.shakespeare.lit'
id='delete1'>
The deletion request MAY include the URI of a replacement node to which requests might be redirected. Typically this is an XMPP URI or IRI as described under
PubSub URIs
, but it can be an HTTP URI or any other scheme.
Example 158.
Owner deletes a node with redirection
to='pubsub.shakespeare.lit'
id='delete1'>
Support for redirection is OPTIONAL on the part of pubsub services.
8.4.2 Success Case
If no error occurs, the service MUST inform the owner of success.
Example 159.
Service replies with success
id='delete1'/>
In addition, the service MUST also send notification of node deletion to all subscribers (which SHOULD include pending and unconfigured subscriptions).
Example 160.
Subscribers are notified of node deletion
8.4.3 Error Cases
There are several reasons why the node deletion request might fail:
The requesting entity does not have sufficient privileges to delete the node.
The node is the root collection node, which cannot be deleted (see
PubSub Collection Nodes (XEP-0248)
]).
The specified node does not exist.
These error cases are described more fully in the following sections.
8.4.3.1 Insufficient Privileges
If the requesting entity does not have sufficient privileges to delete the node (e.g., is not an owner), the service MUST return a
Example 161.
Entity is not an owner
to='hamlet@denmark.lit/elsinore'
id='delete1'>
8.4.3.2 Node Does Not Exist
If the requesting entity attempts to delete a node that does not exist, the service MUST return an
Example 162.
Owner attempts to delete a non-existent node
to='hamlet@denmark.lit/elsinore'
id='delete1'>
8.5 Purge All Node Items
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.
8.5.1 Request
In order to purge a node of all items, a node owner sends a node purge request consisting of a
Example 163.
Owner purges all items from a node
to='pubsub.shakespeare.lit'
id='purge1'>
8.5.2 Success Case
If no error occurs, the service MUST purge the node and inform the owner of success.
Example 164.
Service replies with success
id='purge1'/>
If the node or service has been configured to notify subscribers on deletion of items, a purge request MUST NOT result in sending the same notifications as are sent when deleting items (since purging a node with many persisted items could result in a large number of notifications); instead, the node MUST send a single notification to each subscriber, containing an empty
Example 165.
Subscribers are notified of node purge
8.5.3 Error Cases
There are several reasons why the node purge request might fail:
The node or service does not support node purging.
The requesting entity does not have sufficient privileges to purge the node.
The node is not configured to persist items.
The specified node does not exist.
These error cases are described more fully in the following sections.
8.5.3.1 Node Purging Not Supported
If the node or service does not support node purging, it MUST return a
Example 166.
Service does not support node purging
to='hamlet@denmark.lit/elsinore'
id='purge1'>
8.5.3.2 Insufficient Privileges
If the requesting entity does not have sufficient privileges to purge the node (e.g., because it is not a node owner), the service MUST return a
Example 167.
Entity is not an owner
id='purge1'>
8.5.3.3 Node Does Not Persist Items
If the service or node does not persist items (e.g., because the node is a collection node as described in
PubSub Collection Nodes (XEP-0248)
]), it MUST return a
Example 168.
Node is not configured for persistent items
id='purge1'>
8.5.3.4 Node Does Not Exist
If the node does not exist, the service MUST return an
Example 169.
Node does not exist
id='purge1'>
8.6 Manage Subscription Requests
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