In accordance with XMPP Council consensus, moved the auto-create, auto-subscribe, filtered-notifications, and last-published features from XEP-0163 to this specification and defined them more precisely; added publish-options functionality; clarified optional auto-subscribe to open access nodes via presence receipt.
In accordance with XMPP Council consensus, moved the auto-create, auto-subscribe, filtered-notifications, and last-published features from XEP-0163 to this specification and defined them more precisely; added publish-options functionality; clarified optional auto-subscribe to open access nodes via presence receipt; added developer-friendly How It Works section; split several long sections into smaller sub-sections.
As Jabber/XMPP technologies have matured, the need for a generic publish-subscribe ("pubsub") mechanism has arisen in a number of problem spaces. These include (but are not limited to): news feeds and content syndication, extended presence, avatar management, shared bookmarks, auction and trading systems, online catalogs, workflow systems, network management systems, NNTP gateways, profile management, and event notification.
+As Jabber/XMPP technologies have matured, the need for a generic publish-subscribe ("pubsub") mechanism has arisen in a number of domains. These include (but are not limited to): news feeds and content syndication, extended presence, avatar management, shared bookmarks, auction and trading systems, online catalogs, workflow systems, network management systems, NNTP gateways, profile management, and event notification.
In all of these domains, it is desirable for data communication to follow the classic "publish-subscribe" or "observer" design pattern: a person or application publishes information, and an event notification or the data itself 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 and/or the data itself to subscribers, and enables privileged entities to manage lists of people or applications that are authorized to publish or subscribe. In most pubsub services, the focal point for publication and subscription is a "topic" or "node" to which publishers send data and from which subscribers receive notifications and/or data. Additionally, some nodes may also maintain a history of events and provide other services that supplement the pure pubsub model.
-This document defines a single, cohesive, generic protocol which all forms of pubsub can utilize. While compliant implementations are not required to implement all of the features defined herein, this document addresses most usages that may be requested of a pubsub service. Other specifications may define subsets of publish-subscribe for use in specialized contexts, but such profiles are out of scope for this document.
+This document defines a single, cohesive, generic protocol, which all forms of pubsub can utilize. While compliant implementations are not required to implement all of the features defined herein, this document addresses most use cases that may be requested of a pubsub service. (For information about which features are required and which are recommended or optional, consult the Feature Summary.) Other specifications may define "subsets" or "profiles" of publish-subscribe (e.g., &xep0163;) for use in specialized contexts, but such profiles are out of scope for this document.
In order to motivate the discussion, we provide a simple, introductory example of a pubsub protocol flow.
-Perhaps the most popular application of pubsub-like functionality is content syndication, which has become familiar from the RSS and Atom (&rfc4287;) feeds associated with weblogs, news sites, and other frequently-updated information available on the Internet. Consider the example of a weblog published by one of the Shakespearean characters typical of Jabber/XMPP protocol documentation. When this character authors a new weblog entry, his blogging software publishes the entry to a pubsub node hosted at a pubsub service:
+This specification is large. However, the basic idea behind pubsub is rather simple (see Publish an Item to a Node):
+Perhaps the most popular application of pubsub-like functionality is content syndication, which has become familiar from the RSS and Atom (&rfc4287;) feeds associated with weblogs, news sites, and other frequently-updated information available on the Internet. Consider the example of a weblog published by <hamlet@denmark.lit>. When Hamlet writes a new weblog entry, his blogging software publishes the entry to a pubsub node hosted at <pubsub.shakespeare.lit>:
So that is the "pub" part of publish-subscribe.
+Now the pubsub service notifies all the subscribers about the new blog entry:
Naturally, many other protocol flows may be required in order to enable publication of items to a node (e.g., the publisher first needs to create the node and subscribers need to sign up for notifications). These protocol flows are fully described in the remainder of this document.
-An even simpler example is that of a transient node that sends only notifications, which is the pure pubsub model:
+An even simpler example is that of a transient node that sends only notifications without a payload:
Naturally, the entities involved may need to complete other use cases in order to enable full pubsub functionality -- for example, the publisher may need to create the node (see Create a Node) and subscribers may need to sign up for 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.)
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 Jabber MUST provide the basic features which implement a pure publish-subscribe pattern:
+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 Jabber MUST provide the basic features that implement a pure publish-subscribe pattern:
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.)
When a Jabber 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 <pubsub/> element contains one and only one <subscribe/> element. The <subscribe/> element MUST possess a 'node' attribute specifying the node to which the entity wishes to subscribe. The <subscribe/> element MUST also possess a 'jid' attribute specifying the exact XMPP address to be used as the subscribed JID -- often a bare JID (&BAREJID;) or full JID (&FULLJID;), although JIDs of the form &DOMAIN; or &DOMAINRES; may subscribe as well.
-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. However, some implementations 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 blacklisting of entities that are not allowed to perform specific operations (such as subscribing or creating nodes).
-A service MAY allow entities to subscribe multiple times to the same node. This enables an entity to subscribe using different subscription options. 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 entity element any time it is sent to the subscriber). It is NOT RECOMMENDED for clients to generate SubIDs, since collisions might result; therefore a service SHOULD generate the SubID on behalf of the subscriber and MAY overwrite SubIDs if they are provided by subscribers. If the service does not allow multiple subscriptions for the same entity and it receives an additional subscription request, the service MUST return the current subscription state (as if the subscription was just approved).
-Here is an example of a subscription request.
-When a Jabber 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 <pubsub/> element contains one and only one <subscribe/> element. The <subscribe/> element MUST possess a 'node' attribute specifying the node to which the entity wishes to subscribe. The <subscribe/> element MUST also possess a 'jid' attribute specifying the exact XMPP address to be used as the subscribed JID -- often a bare JID (&BAREJID;) or full JID (&FULLJID;), although JIDs of the form &DOMAIN; or &DOMAINRES; may subscribe as well.
+Here is an example of a subscription request.
+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).
-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).
+The service MAY also 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 &xep0203;) to indicate it is are sent with delayed delivery. (Note that in this example the message notification is sent to the bare JID since that is the subscribed JID.)
-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.
-There are several reasons why the subscription request might fail:
-These error cases are described more fully below.
-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 &badrequest; error, which SHOULD also include a pubsub-specific error condition of <invalid-jid/>.
-There are several reasons why the subscription request might fail:
+These error cases are described more fully in the following sections.
+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 &badrequest; error, which SHOULD also include a pubsub-specific error condition of <invalid-jid/>.
+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 ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <presence-subscription-required/>.
-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 blacklisting of entities that are not allowed to perform specific operations (such as subscribing or creating nodes).
+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 ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <presence-subscription-required/>.
+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 ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <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 ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <not-in-roster-group/>.
+For nodes with a node access model of "whitelist", if the requesting entity is not on the whitelist then the service MUST return a ¬allowed; error, specifying a pubsub-specific error condition of <closed-node/>.
-For nodes with a node access model of "whitelist", if the requesting entity is not on the whitelist then the service MUST return a ¬allowed; error, specifying a pubsub-specific error condition of <closed-node/>.
+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 &payment; error to the subscriber.
-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 &payment; error to the subscriber.
+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 &forbidden; error to the subscriber.
-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 &forbidden; error to the subscriber.
+If the requesting entity has a pending subscription, the service MUST return a ¬authorized; error to the subscriber, specifying a pubsub-specific error condition of <pending-subscription/>.
-If the requesting entity has a pending subscription, the service MUST return a ¬authorized; error to the subscriber, specifying a pubsub-specific error condition of <pending-subscription/>.
+If the requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast), the service MUST return a &forbidden; error to the subscriber.
-If the requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast), the service MUST return a &forbidden; error to the subscriber.
+If the node does not allow entities to subscribe, the service SHOULD return a &feature; error to the subscriber, specifying a pubsub-specific error condition of <unsupported/> and a feature of "subscribe".
-If the node does not allow entities to subscribe, the service SHOULD return a &feature; error to the subscriber, specifying a pubsub-specific error condition of <unsupported/> and a feature of "subscribe".
+If the node does not exist, the service SHOULD return an ¬found; error to the subscriber.
-If the node does not exist, the service SHOULD return an ¬found; error to the subscriber.
+For nodes with an access model of "authorize", subscription requests MUST be approved by one of the node owners; 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.
-For nodes with an access model of "authorize", subscription requests MUST be approved by one of the node owners; 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.
+If the entity must configure its subscription options (see the Configure Subscription Options section of this document) before receiving 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.
-If the entity must configure its subscription options (see the Configure Subscription Options section of this document) before receiving 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.
+Note: The node shall include the <required/> child element only if the subscriber must configure the subscription before receiving any notifications. A service MAY time out subscription requests if configuration is required and a configuration request is not submitted within a reasonable amount of time (which shall be determined by the service or node configuration).
-Alternatively, if the service is unable to create the subscription without simultaneous configuration, the service MAY return a ¬acceptable; error, specifying a pubsub-specific error condition of <configuration-required/>.
-Note: The node shall include the <required/> child element only if the subscriber must configure the subscription before receiving any notifications. A service MAY time out subscription requests if configuration is required and a configuration request is not submitted within a reasonable amount of time (which shall be determined by the service or node configuration).
+Alternatively, if the service is unable to create the subscription without simultaneous configuration, the service MAY return a ¬acceptable; error, specifying a pubsub-specific error condition of <configuration-required/>.
+If the <required/> element is not included and no error is returned, the subscription takes effect immediately and the entity may configure the subscription at any time (the service MAY indicate that subscription options are supported by including an empty <subscribe-options/> element in the IQ-result, as shown in the following example).
-If the <required/> element is not included and no error is returned, the subscription takes effect immediately and the entity may configure the subscription at any time (the service MAY indicate that subscription options are supported by including an empty <subscribe-options/> element in the IQ-result, as shown in the following example).
+A service MAY allow an entity to subscribe multiple times to the same node. This enables an entity to subscribe using different subscription options. 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 entity element any time it is sent to the subscriber). It is NOT RECOMMENDED for clients to generate SubIDs, since collisions might result; therefore a service SHOULD generate the SubID on behalf of the subscriber and MAY overwrite SubIDs if they are provided by subscribers. If the service does not allow multiple subscriptions for the same entity and it receives an additional subscription request, the service MUST return the current subscription state (as if the subscription was just approved).
+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 &xep0203;) to indicate it is are sent with delayed delivery. (Note that in this example the message notification is sent to the bare JID since that is the subscribed JID.)
+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.
+To unsubscribe from a node, the subscriber sends an IQ-set whose &PUBSUB; child contains an <unsubscribe/> element that specifies the node and the subscribed JID.
-To unsubscribe from a node, the subscriber sends an IQ-set whose &PUBSUB; child contains an <unsubscribe/> element that specifies the node and the subscribed JID.
+If the request can be successfully processed, the service MUST return an IQ result.
-If the request can be successfully processed, the service MUST return an IQ result.
+There are several reasons why the unsubscribe request might fail:
-These error cases are described more fully below.
-If the requesting entity has multiple subscriptions to the node but does not specify a subscription ID, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <subid-required/>.
-There are several reasons why the unsubscribe request might fail:
+These error cases are described more fully in the following sections.
+If the requesting entity has multiple subscriptions to the node but does not specify a subscription ID, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <subid-required/>.
+If the value of the 'jid' attribute does not specify an existing subscriber, the pubsub service MUST return an error stanza, which SHOULD be &unexpected; and which SHOULD also include a pubsub-specific error condition of <not-subscribed/>.
-If the value of the 'jid' attribute does not specify an existing subscriber, the pubsub service MUST return an error stanza, which SHOULD be &unexpected; and which SHOULD also include a pubsub-specific error condition of <not-subscribed/>.
+If the requesting entity is prohibited from unsubscribing the specified JID, the service MUST return a &forbidden; error. The service MUST validate that the entity making the request is authorized to unsubscribe the entity. If the subscriber's JID is of the form &FULLJID;, a service MUST perform this check by comparing the &BAREJID; part of the two JIDs to ensure that they match. If the bare JID portions of the JIDs do not match and the requesting entity is not authorized to unsubscribe the JID (e.g., because it is not a service-wide admin or authorized proxy), the service MUST return a &forbidden; error.
-If the requesting entity is prohibited from unsubscribing the specified JID, the service MUST return a &forbidden; error. The service MUST validate that the entity making the request is authorized to unsubscribe the entity. If the subscriber's JID is of the form &FULLJID;, a service MUST perform this check by comparing the &BAREJID; part of the two JIDs to ensure that they match. If the bare JID portions of the JIDs do not match and the requesting entity is not authorized to unsubscribe the JID (e.g., because it is not a service-wide admin or authorized proxy), the service MUST return a &forbidden; error.
+If the node does not exist, the pubsub service MUST return an ¬found; error.
-If the node does not exist, the pubsub service MUST return an ¬found; error.
+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 ¬acceptable; error, which SHOULD also include a pubsub-specific error condition of <invalid-subid/>.
-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 ¬acceptable; error, which SHOULD also include a pubsub-specific error condition of <invalid-subid/>.
+Implementations 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).
-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".
-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".
+A subscriber requests the subscription options by including an <options/> element inside an IQ-get stanza.
-A subscriber requests the subscription options by including an <options/> element inside an IQ-get stanza.
+If the request can be successfully processed, the service MUST respond with the options.
-If the request can be successfully processed, the service MUST respond with the options.
+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. &BOOLEANNOTE;
-There are several reasons why the options request might fail:
-These error cases are described more fully below.
-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, the service MUST assume that the requesting entity wishes to request subscription options for its subscription to the root collection node; see the Root Collection Node section of this document 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 &FULLJID;, a service MUST perform this check by comparing the &BAREJID; part of the two JIDs to ensure that they match. If the bare JID portions of the JIDs do not match and the requesting entity is not authorized to modify subscription options for the JID (e.g., because it is not a service-wide admin or authorized proxy), the service MUST return a &forbidden; error.
-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. &BOOLEANNOTE;
+There are several reasons why the options request might fail:
+These error cases are described more fully in the following sections.
+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, the service MUST assume that the requesting entity wishes to request subscription options for its subscription to the root collection node; see the Root Collection Node section of this document 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 &FULLJID;, a service MUST perform this check by comparing the &BAREJID; part of the two JIDs to ensure that they match. If the bare JID portions of the JIDs do not match and the requesting entity is not authorized to modify subscription options for the JID (e.g., because it is not a service-wide admin or authorized proxy), the service MUST return a &forbidden; error.
+If the requesting entity (or specified subscriber, if different) is not subscribed, the service MUST return an &unexpected; error, which SHOULD also include a pubsub-specific error condition of <not-subscribed/>.
-If the requesting entity (or specified subscriber, if different) is not subscribed, the service MUST return an &unexpected; error, which SHOULD also include a pubsub-specific error condition of <not-subscribed/>.
+If the subscriber does not specify a JID, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <jid-required/>.
-If the subscriber does not specify a JID, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <jid-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 &badrequest; error, which SHOULD also include a pubsub-specific error condition of <subid-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 &badrequest; error, which SHOULD also include a pubsub-specific error condition of <subid-required/>.
+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 ¬acceptable; error, which SHOULD also include a pubsub-specific error condition of <invalid-subid/>.
-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 ¬acceptable; error, which SHOULD also include a pubsub-specific error condition of <invalid-subid/>.
+If the node or service does not support subscription options, the service MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "subscription-options".
-If the node or service does not support subscription options, the service MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "subscription-options".
+If the node does not exist, the pubsub service MUST return an ¬found; error.
-If the node does not exist, the pubsub service MUST return an ¬found; error.
+After receiving the configuration form, the requesting entity SHOULD submit the form in order to update the entity's subscription options for that node.
-After receiving the configuration form, the requesting entity SHOULD submit the form in order to update the entity's subscription options for that node.
+If the service can successfully process the submission, it MUST respond with success.
-If the service can successfully process the submission, it MUST respond with success.
+If the subscriber attempts to set an invalid group of options, the service MUST respond with a &badrequest; error.
-If the subscriber attempts to set an invalid group of options, the service MUST respond with a &badrequest; error.
+The other errors already mentioned for getting subscription options also apply to setting subscription options.
-As noted, if a service supports subscription options, an entity MAY subscribe and provide the subscription options in the same stanza.
-Note: The <options/> element MUST follow the <subscribe/> element and MUST NOT possess a 'node' attribute or 'jid' attribute, since the value of the <subscribe/> element's 'node' attribute specifies the desired NodeID and the value of the <subscribe/> element's 'jid' attribute specifies the subscriber's JID; if any of these rules are violated, the service MUST return a &badrequest; error.
-The other errors already mentioned for getting subscription options also apply to setting subscription options.
+As noted, if a service supports subscription options, an entity MAY subscribe and provide the subscription options in the same stanza.
+Note: The <options/> element MUST follow the <subscribe/> element and MUST NOT possess a 'node' attribute or 'jid' attribute, since the value of the <subscribe/> element's 'node' attribute specifies the desired NodeID and the value of the <subscribe/> element's 'jid' attribute specifies the subscriber's JID; if any of these rules are violated, the service MUST return a &badrequest; error.
+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). 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.)
-The subscriber may request all items by specifying only the Node ID without restrictions.
-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.)
+The subscriber may request all items by specifying only the Node ID without restrictions.
+The service then SHOULD return all items published to the node, although it MAY truncate the result set if a large number of items has been published.
-The service then SHOULD return all items published to the node, although it MAY truncate the result set if a large number of items has been published.
+Even if the service or node does not support persistent items, it MAY return the last published item.
-Even if the service or node does not support persistent items, it MAY return the last published item.
+There are several reasons why the items retrieval request might fail:
-These error cases are described more fully below.
-If the requesting entity has multiple subscriptions to the node but does not specify a subscription ID, the service MUST return a &badrequest; error to the subscriber, which SHOULD also include a pubsub-specific error condition of <subid-required/>.
-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.
+If the requesting entity is subscribed but specifies an invalid subscription ID, the service MUST return a ¬acceptable; error to the subscriber, which SHOULD also include a pubsub-specific error condition of <invalid-subid/>.
-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 ¬authorized; error to the subscriber, which SHOULD also include a pubsub-specific error condition of <not-subscribed/>.
-If the service or node does not support persistent items and does not return the last published item, the service MUST return a &feature; error to the subscriber, specifying a pubsub-specific error condition of <unsupported/> and a feature of "persistent-items".
-If the service or node does not support item retrieval (e.g., because the node is a collection node), the service MUST return a &feature; error to the subscriber, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-items".
-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 ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <presence-subscription-required/>.
-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 ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <not-in-roster-group/>.
-For nodes with a node access model of "whitelist", if the requesting entity is not on the whitelist then the service MUST return a ¬allowed; error, specifying a pubsub-specific error condition of <closed-node/>.
-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 &payment; error to the subscriber.
-If the requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast), the service MUST return a &forbidden; error to the subscriber.
-If the node does not exist, the service SHOULD return an ¬found; error to the subscriber.
-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 &xep0059; instead of the 'max_items' attribute.)
-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 &xep0059; instead of the 'max_items' attribute.)
+The 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.
-There are several reasons why the items retrieval request might fail:
+These error cases are described more fully in the following sections.
+If the requesting entity has multiple subscriptions to the node but does not specify a subscription ID, the service MUST return a &badrequest; error to the subscriber, which SHOULD also include a pubsub-specific error condition of <subid-required/>.
+If a subscription identifier is associated with a specific subscription, the service MUST require it so that it can generate different sets of items based on the subscription options associated with a specific subscription. Therefore the entity MUST include the 'subid' attribute with the items element when making the request; if it does not, the service MUST return a ¬acceptable; error, specifying a pubsub-specific error condition of <subid-required/>.
-If the requesting entity is subscribed but specifies an invalid subscription ID, the service MUST return a ¬acceptable; error to the subscriber, which SHOULD also include a pubsub-specific error condition of <invalid-subid/>.
+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 ¬authorized; error to the subscriber, which SHOULD also include a pubsub-specific error condition of <not-subscribed/>.
+If the service or node does not support persistent items and does not return the last published item, the service MUST return a &feature; error to the subscriber, specifying a pubsub-specific error condition of <unsupported/> and a feature of "persistent-items".
+If the service or node does not support item retrieval (e.g., because the node is a collection node), the service MUST return a &feature; error to the subscriber, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-items".
+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 ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <presence-subscription-required/>.
+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 ¬authorized; error, which SHOULD also include a pubsub-specific error condition of <not-in-roster-group/>.
+For nodes with a node access model of "whitelist", if the requesting entity is not on the whitelist then the service MUST return a ¬allowed; error, specifying a pubsub-specific error condition of <closed-node/>.
+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 &payment; error to the subscriber.
+If the requesting entity is blocked from subscribing (e.g., because having an affiliation of outcast), the service MUST return a &forbidden; error to the subscriber.
+If the node does not exist, the service SHOULD return an ¬found; error to the subscriber.
+Any entity which 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 <publish/> child; the <publish/> element MUST possess a 'node' attribute and depending on the node configuration MAY contain no &ITEM; elements, one &ITEM; element, or (for Batch Processing) more than one &ITEM; element.
-Note: It is not necessary for a publication request to include a payload or even an &ITEM; element in order to trigger a notification. For example, the result of publishing to a transient, notification-only node will be a notification that does not include even an &ITEM; element (as shown in the Motivating Example section of this document). However, for the sake of convenience we refer to the act of publication as "publishing an item" (rather than, say, "triggering a notification") even though a publication request will not always contain an &ITEM; element.
-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 <publish/> child; the <publish/> element MUST possess a 'node' attribute and depending on the node configuration MAY contain no &ITEM; elements, one &ITEM; element, or (for Batch Processing) more than one &ITEM; element.
+Note: It is not necessary for a publication request to include a payload or even an &ITEM; element in order to trigger a notification. For example, the result of publishing to a transient, notification-only node will be a notification that does not include even an &ITEM; element (as shown in the Motivating Example section of this document). However, for the sake of convenience we refer to the act of publication as "publishing an item" (rather than, say, "triggering a notification") even though a publication request will not always contain an &ITEM; element.
+If the pubsub service can successfully process the request, it MUST inform the publisher of success.
-If the pubsub service can successfully process the request, it MUST inform the publisher of success.
+If the pubsub service can successfully process the request, it MUST send then one &MESSAGE; stanza containing a pubsub event notification to each approved subscriber. Each &MESSAGE; stanza generated by a pubsub service SHOULD possess an 'id' attribute with a unique value so that the service can properly track any notification-related errors that may occur (see the 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 in the following examples.
-If the node is configured to include payloads, the subscribers will receive payloads with the event notifications.
-The pubsub service MUST send then one &MESSAGE; stanza containing a pubsub event notification to each approved subscriber. Each &MESSAGE; stanza generated by a pubsub service SHOULD possess an 'id' attribute with a unique value so that the service can properly track any notification-related errors that may occur (see the 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.
+If the node is configured to include payloads, the subscribers will receive payloads with the event notifications.
+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.)
-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.)
+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 &xep0131; format and SHOULD be included after the event notification information (i.e., as the last child of the &MESSAGE; stanza).
-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 &xep0131; format and SHOULD be included after the event notification information (i.e., as the last child of the &MESSAGE; stanza).
+There are several reasons why the publish request might fail:
-These error cases are described more fully below.
-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).
-If the requesting entity does not have sufficient privileges to publish, the service MUST return a &forbidden; error.
-There are several reasons why the publish request might fail:
+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).
+If the requesting entity does not have sufficient privileges to publish, the service MUST return a &forbidden; error.
+If the node does not support item publication (because it is a Collection Node), the service MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "publish".
-If the node does not support item publication (because it is a Collection Node), the service MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "publish".
+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 ¬found; error.
-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 ¬found; error.
+If the payload size exceeds a service-defined limit, the service MUST return a ¬acceptable; error, which SHOULD also include a pubsub-specific error condition of <payload-too-big/>.
-If the payload size exceeds a service-defined limit, the service MUST return a ¬acceptable; error, which SHOULD also include a pubsub-specific error condition of <payload-too-big/>.
+If the &ITEM; element contains more than one payload element or the namespace of the root payload element does not match the configured namespace for the node, the service MUST bounce the request with a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <invalid-payload/>.
-If the &ITEM; element contains more than one payload element or the namespace of the root payload element does not match the configured namespace for the node, the service MUST bounce the request with a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <invalid-payload/>.
+If the request does not conform to the configured event type for the node, the service MAY bounce the request with a &badrequest; error, which SHOULD also include a pubsub-specific error condition. The following rules apply:
-Examples of these errors are shown below.
-If the request does not conform to the configured event type for the node, the service MAY bounce the request with a &badrequest; error, which SHOULD also include a pubsub-specific error condition. The following rules apply:
+Examples of these errors are shown below.
+Finally, 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.
+ ]]>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 ¬found; error). When doing so, the service SHOULD apply the default node configuration. If a service supports this functionality, it MUST advertise that fact by including a feature of "http://jabber.org/protocol/pubsub#auto-create" in its disco#info responses.
A service SHOULD allow a publisher to delete an item once it has been published to a node that supports persistent items. To delete an item, the publisher sends a retract request as shown in the following examples. The <retract/> element MUST possess a 'node' attribute, MAY possess a 'notify' attribute, and SHOULD contain one &ITEM; element (but MAY contain more than one &ITEM; element for Batch Processing of item retractions); the &ITEM; element MUST be empty and MUST possess an 'id' attribute.
-To delete an item, the publisher sends a retract request as shown in the following examples. The <retract/> element MUST possess a 'node' attribute, MAY possess a 'notify' attribute, and SHOULD contain one &ITEM; element (but MAY contain more than one &ITEM; element for Batch Processing of item retractions); the &ITEM; element MUST be empty and MUST possess an 'id' attribute.
+If none of the error cases occurs, the service MUST delete the item.
+There are several reasons why the item retraction request might fail:
-These error cases are described more fully below.
-If the requesting entity does not have sufficient privileges to delete the item, the service MUST return a &forbidden; error.
-If the node or item does not exist, the service MUST return an ¬found; error.
-If the request does not specify a node, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <node-required/>.
-If the request does not include an &ITEM; element or the &ITEM; element does not specify an ItemID, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <item-required/>.
-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 &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "persistent-items".
-If the service does not support item deletion, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "delete-nodes".
-If none of the foregoing errors occurred, then the service MUST delete the item.
-If none of the foregoing errors occurred and the <retract/> element included a 'notify' attribute with a value of "true" or "1" &BOOLEANNOTE;, then the service MUST delete the item and MUST send message notifications to all subscribers as shown below. The syntax is identical to publish notifications except that instead of an &ITEM; element, the notification includes a <retract/> element.
-If none of the error cases occurs and the <retract/> element included a 'notify' attribute with a value of "true" or "1" &BOOLEANNOTE;, then the service MUST delete the item and MUST send message notifications to all subscribers as shown below. The syntax is identical to publish notifications except that instead of an &ITEM; element, the notification includes a <retract/> element.
+If a single entity is subscribed to the node multiple times, the service SHOULD notate the notification of 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 event notification information (i.e., as the last child of the &MESSAGE; stanza).
-If a single entity is subscribed to the node multiple times, the service SHOULD notate the notification of 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 event notification information (i.e., as the last child of the &MESSAGE; stanza).
+There are several reasons why the item retraction request might fail:
+These error cases are described more fully in the following sections.
+If the requesting entity does not have sufficient privileges to delete the item, the service MUST return a &forbidden; error.
+If the node or item does not exist, the service MUST return an ¬found; error.
+If the request does not specify a node, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <node-required/>.
+If the request does not include an &ITEM; element or the &ITEM; element does not specify an ItemID, the service MUST return a &badrequest; error, which SHOULD also include a pubsub-specific error condition of <item-required/>.
+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 &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "persistent-items".
+If the service does not support item deletion, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "delete-nodes".
+These error cases are described more fully below.
+These error cases are described more fully in the following sections.
If the service does not support node configuration, the service MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "config-node".
These error cases are described more fully below.
+These error cases are described more fully in the following sections.
If the service does not support node configuration, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "config-node".
These error cases are described more fully below.
+These error cases are described more fully in the following sections.
If the requesting entity does not have sufficient privileges to delete the node (e.g., is not an owner), the service MUST return a &forbidden; error.
These error cases are described more fully below.
+These error cases are described more fully in the following sections.
If the node or service does not support node purging, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "purge-nodes".
These error cases are described more fully below.
+These error cases are described more fully in the following sections.
If the service does not support the ad-hoc commands protocol, it MUST respond with a &unavailable; error.
These error cases are described more fully below.
+These error cases are described more fully in the following sections.
If an implementation does not support subscription management, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "manage-subscriptions".
These error cases are described more fully below.
+These error cases are described more fully in the following sections.
If an implementation does not support modification of affiliations, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "modify-affiliations".
These error cases are described more fully below.
+These error cases are described more fully in the following sections.
If the service does not support collection nodes, it MUST respond with a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "collections".
These error cases are described more fully below.
+These error cases are described more fully in the following sections.
An implementation MAY allow a node to be associated with more than one collection node and therefore MAY specify a type of "text-multi" for the "pubsub#collection" field. However, in order to reduce the complexity of implementation, it is RECOMMENDED to allow only one parent collection node for each node and therefore it is RECOMMENDED to specify a type of "text-single" for the "pubsub#collection" field. If a service supports associating a node with multiple collections, it MUST advertise support for the "multi-collection" feature (if that feature is not advertised, entities SHOULD assume that the service allows a node to be associated with only one collection). If the request specifies more than one collection node but the service allows a node to be associated with only one collection node, the service MUST return a &badrequest; error.