Added subscription attribute for entities. Removed subscriber from the affiliations table. Clarified configuration details. Clarified JabberID usages. Added XMPP Registrar Considerations. Added link to XEP-0068 about the FORM_TYPE element in subscription request notifications. Fixed some typos in examples. Added unsupported configuration namespace to example. Added a default configuration example.
Added subscription attribute for entities. Removed subscriber from the affiliations table. Clarified configuration details. Clarified JabberID usages. Added XMPP Registrar Considerations. Added link to XEP-0068 about the FORM_TYPE element in subscription request notifications. Fixed some typos in examples. Added unsupported configuration namespace to example. Added a default node configuration example.
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, 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.
-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 (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. 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. 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 that all forms of pubsub can use. 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 for use in specialized contexts, but such profiles are out of scope for this document.
+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 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.
This specification is large. However, the basic idea behind pubsub is rather simple (see Publish an Item to a Node):
+Although this specification is large because it defines many side use cases and possible error flows, the basic idea is simple:
An entity may want to query the service to retrieve its affiliations for all nodes at the service. Support for this feature ("retrieve-affiliations") is RECOMMENDED.
-In order to make the request, the requesting entity includes an empty <affiliations/> element with no attributes.
+An entity may want to query the service to retrieve its affiliations for all nodes at the service, or query a specific node for its affiliation with that node. Support for this feature ("retrieve-affiliations") is RECOMMENDED.
+In order to make the request of the service, the requesting entity includes an empty <affiliations/> element with no attributes.
In order to make an affiliations request of a specific node, the requesting entity includes an empty <affiliations/> element with a 'node' attribute.
+An entity may want to request information about the default subscription configuration. Support for this feature is OPTIONAL.
+To get the default subscription options, the entity MUST send an empty <default/> element to the node (not the service); in response, the node SHOULD return the default subscription options.
+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).
+If no error occurs, the node MUST return the default subscription configuration options.
+There are several reasons why the default subscription configuration options request might fail:
+These error cases are described more fully in the following sections.
+If the node does not support subscription configuration, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "subscription-options".
+If the node does not support retrieval of default subscription configuration options, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-default-sub".
+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 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 (see next section).
+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.
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 Configurations section of this document).
+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 <create/> child element.
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).
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.
To get the options, the entity MUST send an empty <default/> element to the service with no NodeID; in response, the service SHOULD return the default node options.
-If no error occurs, the service MUST return the default configuration options.
-If the service does not support retrieval of default node configuration options, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "retrieve-default".
-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, the subscription id (if applicable), and the JID of the pending subscriber. The message MAY include a &BODY; element that contains natural-language text explaining that the message contains a pending subscription form.
+A service MAY send subscription approval requests to the node owner(s) at any time. An approval request consists of a message stanza containing a Data Form scoped by the "http://jabber.org/protocol/pubsub#subscribe_authorization" FORM_TYPE. The form MUST contain a boolean field that has a 'var' attribute of "pubsub#allow", which is the field that designates whether or not to allow the subscription request. The form SHOULD include fields that specify the node identifier and the JID of the pending subscriber. The message MAY include a &BODY; element that contains natural-language text explaining that the message contains a pending subscription form.
When a subscription state change occurs, a service SHOULD send a message to the (new, former, or denied) subscriber informing it of the change, where the message contains an <event/> element with a single <subscription/> child that specifies the node, JID, and subscription state. The notification MAY contain a &BODY; element specifying natural-language text regarding the subscription change. Examples are shown below.
+When a subscription state change occurs, a service SHOULD send a message to the (new, former, or denied) subscriber informing it of the change, where the message contains an <event/> element with a single <subscription/> child that specifies the node, JID, and subscription state. The notification MAY contain a &BODY; element specifying natural-language text regarding the subscription change. The JID to which the service sends the notification is the address that was set in the 'jid' attribute of the subscription request. Examples are shown below.
Naturally, the node owner can enforce the singleton node pattern by setting the max_items configuration option to "1".
An XMPP URI (see &rfc5122;) can be used for the purpose of identification or interaction. Some examples are provided below.
@@ -5316,9 +5471,24 @@ xmpp:pubsub.shakespeare.lit?pubsub;action=retrieve;node=princely_musings;item=aeBecause the data published to a pubsub node may contain sensitive information (e.g., a user's geolocation), node owners SHOULD exercise care in approving subscription requests. Security considerations regarding particular kinds of information are the responsibility of the "using protocol".
-A service MUST NOT allow non-owners or other unauthorized entities to complete any actions defined under the Owner Use Cases section of this document.
-A service MUST adhere to the defined access model in determining whether to send event notifications or payloads to an entity, or allow an entity to retrieve items from a node. A service MAY enforce additional privacy and security policies when determining whether an entity is allowed to subscribe to a node or retrieve items from a node; however, any such policies shall be considered specific to an implementation or deployment and are out of scope for this document.
+The data published to a pubsub node might contain sensitive information (e.g., a user's geolocation). Therefore, node owners SHOULD exercise care in approving subscription requests. Security considerations regarding particular kinds of information are the responsibility of the "using protocol".
+XMPP PubSub contains a hierarchy of affiliations for the purpose of authorization and access control. A service MUST NOT allow non-owners or other unauthorized entities to complete any actions defined under the Owner Use Cases section of this document.
+A service MUST adhere to the defined access model in determining whether to send event notifications or payloads to an entity, or allow an entity to retrieve items from a node. A service MAY enforce additional privacy and security policies when determining whether an entity is allowed to subscribe to a node or retrieve items from a node; however, any such policies shall be considered specific to an implementation or deployment and are out of scope for this document.
+In the context of instant messaging systems it is possible for the act of publishing an item to reveal the node owner or item publisher's network availability. However, this risk is mitigated by the following factors:
+