diff --git a/xep-0060.xml b/xep-0060.xml index 6202220d..50d953a8 100644 --- a/xep-0060.xml +++ b/xep-0060.xml @@ -276,8 +276,8 @@

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 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 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 (without 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 (e.g., &xep0163;), 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):

@@ -293,7 +293,7 @@ id='pub1'> - + Soliloquy @@ -347,7 +347,7 @@ And by opposing end them? - + @@ -357,7 +357,7 @@ And by opposing end them? ]]> -

An even simpler example is that of a transient node that sends only notifications without a payload:

+

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

@@ -413,7 +413,7 @@ And by opposing end them?

Some of the possible uses of a Jabber-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 not set to true); if it does so 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 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.
    • @@ -478,10 +478,10 @@ And by opposing end them?

    * Note: A service MAY allow any publisher to delete any item once it has been published to that node instead of allowing only the original publisher to remove it (this is discoverable via the "pubsub#delete-any" feature).

    -

    The ways in which an entity changes its affiliation with a node are well-defined. Typically, an owner action is required to make an affiliation state transition. Affiliation changes and their triggering actions are specified in the following table.

    +

    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.

    - + @@ -539,7 +539,7 @@ And by opposing end them? - +
    -->  Outcast None Publisher
    SubscribedAn 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.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).
    @@ -550,7 +550,7 @@ And by opposing end them?

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

    Whether an item must be provided by the publisher, and whether an item ID is provided by the publisher or generated by the pubsub service, depends on the type of event being published. We can summarize the relevant rules as follows:

    - + @@ -617,7 +617,7 @@ And by opposing end them?

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

    -

    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). JID addressing SHOULD 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 pubsub service MUST ensure that the NodeID conforms to the Resourceprep profile of Stringprep as described in RFC 3920.

    +

    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 This rule does not apply to the root collection node, if any.). JID addressing SHOULD 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 pubsub service MUST ensure that the NodeID conforms to the Resourceprep profile of Stringprep as described in RFC 3920.

    Consider the following example, in which the pubsub service is located at the hostname pubsub.shakespeare.lit.

    @@ -874,7 +874,8 @@ And by opposing end them?     -

    A service SHOULD allow an entity to query the service to retrieve its subscriptions for all nodes at the service. In order to make the request, the requesting entity MUST send an IQ-get whose &PUBSUB; child contains an empty <subscriptions/> element with no attributes.

    +

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

    +

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

     -

    A service SHOULD allow an entity to query the service to retrieve its affiliations for all nodes at the service. 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. 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.

    -

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

    +

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

    @@ -1716,15 +1719,20 @@ And by opposing end them? ]]> -

    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.

    + ]]>     +

    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.

    - + @@ -2399,7 +2410,7 @@ And by opposing end them? - + @@ -2653,7 +2664,7 @@ And by opposing end them?     -

    A service SHOULD allow a publisher to delete an item once it has been published to a node that supports persistent items.

    +

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

    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.

    +

    If no error occurs, the service MUST delete the item.

    ]]> -

    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 no error 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.

    @@ -2842,7 +2853,7 @@ And by opposing end them? -

    A service SHOULD allow entities to create new nodes. 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).

    +

    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:

    1. Create a node with default configuration for the specified node type.
      2. @@ -3074,8 +3085,9 @@ And by opposing end them? -

      After creating a new node, the node owner may want to modify the node configuration. The process for doing so is shown below.

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

      + + - ]]> -

      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.

      + ]]>       + + +

      If no error occurs, the server MUST return an empty configuration form to the node owner.

      +

      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.

      - ]]> -

      There are several reasons why the node configuration request might fail:

      -
        -
      1. The service does not support node configuration.
        2. -
      2. The requesting entity does not have sufficient privileges to configure the node.
        3. -
      3. The request did not specify a node.
        4. -
      4. The node has no configuration options.
        5. -
      5. The specified node does not exist.
        6. -
      + ]]> +       + +

      There are several reasons why the node configuration request might fail:

      +
        +
      1. The service does not support node configuration.
        2. +
      2. The requesting entity does not have sufficient privileges to configure the node.
        3. +
      3. The request did not specify a node.
        4. +
      4. The node has no configuration options.
        5. +
      5. The specified node does not exist.
        6. +

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

      - +

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

      + - ]]> -

      If the requesting entity does not have sufficient privileges to configure the node, the service MUST respond with a &forbidden; error.

      - + + +

      If the requesting entity does not have sufficient privileges to configure the node, the service MUST respond with a &forbidden; error.

      + - ]]> -

      If the request did not specify a node, the service SHOULD return a &badrequest; error. It is possible that by not including a NodeID, the requesting entity is asking to configure the root node; however, if the requesting entity is not a service-level admin, it makes sense to return &badrequest; instead of &forbidden;.

      - +       + +

      If the request did not specify a node, the service SHOULD return a &badrequest; error. It is possible that by not including a NodeID, the requesting entity is asking to configure the root node; however, if the requesting entity is not a service-level admin, it makes sense to return &badrequest; instead of &forbidden;.

      + - ]]> -

      If no configuration options are available (e.g., because node configuration is "locked down"), the service MUST return a ¬allowed; error to the owner.

      - +       + +

      If no configuration options are available (e.g., because node configuration is "locked down"), the service MUST return a ¬allowed; error to the owner.

      + - ]]> -

      If the node does not exist, the service MUST return an ¬found; error.

      - + + +

      If the node does not exist, the service MUST return an ¬found; error.

      + - ]]> -

      After receiving the configuration form, the owner SHOULD submit a completed configuration form.

      - +       +       + +

      After receiving the configuration form, the owner SHOULD submit a completed configuration form.

      + - ]]> - - ]]> -

      Alternatively, the owner MAY cancel the configuration process, in which case the existing configuration MUST be applied.

      - +

      Alternatively, the owner MAY cancel the configuration process, in which case the existing configuration MUST be applied.

      + - ]]> -

      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 ¬acceptable; error to the owner.

      - +       + + +

      If the form can be successfully processed, the service MUST return an IQ-result.

      + + ]]> +       + +

      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 ¬acceptable; error to the owner.

      + - ]]> -

      If the "pubsub#notify_config" option is set to true, the service MUST send a notification of configuration change to all subscribers. (A service SHOULD support this option for leaf nodes and MUST support it for Collection Nodes.) If the node configuration is set to event notifications only, the notification MUST consist of an empty <configuration/> element whose 'node' attribute is set to the NodeID of the node; if the node configuration is set to full payloads, the <configuration/> element MUST in addition contain the node configuration as represented via the Data Forms protocol.

      - +       + +

      If the "pubsub#notify_config" option is set to true, the service MUST send a notification of configuration change to all subscribers. (A service SHOULD support this option for leaf nodes and MUST support it for Collection Nodes.) If the node configuration is set to event notifications only, the notification MUST consist of an empty <configuration/> element whose 'node' attribute is set to the NodeID of the node; if the node configuration is set to full payloads, the <configuration/> element MUST in addition contain the node configuration as represented via the Data Forms protocol.

      + - ]]> - + @@ -3369,11 +3406,15 @@ And by opposing end them? - ]]> + ]]> +       +       -

      A service MAY allow entities to determine the default node configuration for new nodes created on the service, in order to help entities determine whether they want to perform create-and-configure as previously described. 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.

      - An entity way 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.

      + @@ -3471,15 +3515,18 @@ And by opposing end them? - ]]> -

      There are several reasons why the default node configuration options request might fail:

      -
        -
      1. The service does not support node configuration.
        2. -
      2. The service does not support retrieval of default node configuration.
        3. -
      + ]]>       + + +

      There are several reasons why the default node configuration options request might fail:

      +
        +
      1. The service does not support node configuration.
        2. +
      2. The service does not support retrieval of default node configuration.
        3. +

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

      - +

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

      + - ]]> -

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

      - + + +

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

      + - ]]> -

      The default configuration options may be different for a collection node vs. a leaf node. In order to specifically request the default configuration options for collection nodes, an entity MUST include a Data Form with a 'pubsub#node_type' field whose value is "collection" in the request (since the default value for the 'pubsub#node_type' field is "leaf").

      - +       +       + +

      The default configuration options may be different for a collection node vs. a leaf node. In order to specifically request the default configuration options for collection nodes, an entity MUST include a Data Form with a 'pubsub#node_type' field whose value is "collection" in the request (since the default value for the 'pubsub#node_type' field is "leaf").

      + @@ -3526,8 +3578,8 @@ And by opposing end them? - ]]> -

      If the service does not support collection nodes, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "collections".

      + ]]> +

      If the service does not support collection nodes, it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "collections".

      - ]]> + ]]> +

      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.

      -

      In order to delete a node, a node owner MUST send a node deletion request, consisting of a <delete/> element whose 'node' attribute specifies the NodeID of the node to be deleted.

      - +

      In order to delete a node, a node owner MUST send a node deletion request, consisting of a <delete/> element whose 'node' attribute specifies the NodeID of the node to be deleted.

      + - ]]> -

      If no error occurs, the service MUST inform the owner of success.

      - + + +

      If no error occurs, the service MUST inform the owner of success.

      + - ]]> -

      In addition, the service MUST also send notification of node deletion to all subscribers (which SHOULD include pending and unconfigured subscriptions).

      - +

      In addition, the service MUST also send notification of node deletion to all subscribers (which SHOULD include pending and unconfigured subscriptions).

      + @@ -3583,20 +3639,20 @@ And by opposing end them? - -. -. -. - ]]> -

      There are several reasons why the node deletion request might fail:

      -
        -
      1. The requesting entity does not have sufficient privileges to delete the node.
        2. -
      2. The node is the root collection node, which cannot be deleted.
        3. -
      3. The specified node does not exist.
        4. -
      + ]]>       +

      If the deleted node is a Collection Node, the implementation MAY associate the "orphaned" leaf nodes with the root collection node or associate them with no collection node.

      + + +

      There are several reasons why the node deletion request might fail:

      +
        +
      1. The requesting entity does not have sufficient privileges to delete the node.
        2. +
      2. The node is the root collection node, which cannot be deleted.
        3. +
      3. The specified node does not exist.
        4. +

      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.

      - +

      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.

      + - ]]> -

      If the requesting entity attempts to delete the root collection node, the service MUST return a ¬allowed; error.

      - + + +

      If the requesting entity attempts to delete the root collection node, the service MUST return a ¬allowed; error.

      + - ]]> -

      If the requesting entity attempts to delete a node that does not exist, the service MUST return an ¬found; error.

      - +       + +

      If the requesting entity attempts to delete a node that does not exist, the service MUST return an ¬found; error.

      + - ]]> -

      If the deleted node is a Collection Node, the implementation MAY associate the "orphaned" leaf nodes with the root collection node or associate them with no collection node.

      + ]]>       + +       -

      If a service persists published items, it MAY enable node owners to purge the node of all published items (thus removing all items from the persistent store, with the exception of the last published item, which MAY be cached). In order to purge a node of all items, a node owner MUST send a node purge request, consisting of a <purge/> element whose 'node' attribute specifies the NodeID of the node to be purged.

      - 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, with the exception of the last published item, which MAY be cached). It is OPTIONAL for a service to implement this feature.

      + +

      In order to purge a node of all items, a node owner sends a node purge request consisting of a <purge/> element whose 'node' attribute specifies the NodeID of the node to be purged.

      + - ]]> -

      If no error occurs, the service MUST purge the node and inform the owner of success.

      - +       + +

      If no error occurs, the service MUST purge the node and inform the owner of success.

      + - ]]> -

      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 <purge/> child element.

      - +

      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 <purge/> child element.

      + @@ -3670,21 +3735,20 @@ And by opposing end them? - -. -. -. - ]]> -

      There are several reasons why the node purge request might fail:

      -
        -
      1. The node or service does not support node purging.
        2. -
      2. The requesting entity does not have sufficient privileges to purge the node.
        3. -
      3. The node is not configured to persist items.
        4. -
      4. The specified node does not exist.
        5. -
      + ]]>       + + +

      There are several reasons why the node purge request might fail:

      +
        +
      1. The node or service does not support node purging.
        2. +
      2. The requesting entity does not have sufficient privileges to purge the node.
        3. +
      3. The node is not configured to persist items.
        4. +
      4. The specified node does not exist.
        5. +

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

      - +

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

      + - ]]> -

      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 &forbidden; error.

      - + + +

      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 &forbidden; error.

      + @@ -3711,9 +3777,11 @@ And by opposing end them? - ]]> -

      If the service or node does not persist items (e.g., because the node is a collection node), it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "persistent-items".

      - +       + +

      If the service or node does not persist items (e.g., because the node is a collection node), it MUST return a &feature; error, specifying a pubsub-specific error condition of <unsupported/> and a feature of "persistent-items".

      + @@ -3726,9 +3794,11 @@ And by opposing end them? feature='persistent-items'/> - ]]> -

      If the node does not exist, the service MUST return an ¬found; error.

      - +       + +

      If the node does not exist, the service MUST return an ¬found; error.

      + @@ -3739,7 +3809,9 @@ And by opposing end them? - ]]> + ]]>       + +       @@ -3847,8 +3919,11 @@ And by opposing end them? ]]>

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

      - -

      A service MAY allow owners to request all the current pending subscription requests for all of their nodes at the service. Implementations MUST use the &xep0050; protocol to provide this functionality. The command name ('node' attribute of the command element) MUST have a value of "http://jabber.org/protocol/pubsub#get-pending".

      +       + +

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

      +

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

      + ]]> + +

      If no error occurs, the service SHOULD return a data form for managing subscription requests, which MUST contain a single field with a 'var' attribute value of "node" whose <option/> elements specify the nodes for which the requesting entity has subscription approval privileges (as an optimization, the service MAY specify only the nodes that have subscription requests pending).

      ]]> +       +

      There are several reasons why the pending subscription approval request might fail:

      1. The service does not support the ad-hoc commands protocol.
        2. @@ -3887,8 +3966,9 @@ And by opposing end them?
      2. The specified node does not exist.

      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.

      - +

      If the service does not support the ad-hoc commands protocol, it MUST respond with a &unavailable; error.

      + - ]]> -

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

      - + + +

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

      + - ]]> -

      If the requesting entity does not have sufficient privileges to approve subscription requests, the service MUST respond with a &forbidden; error.

      - +       + +

      If the requesting entity does not have sufficient privileges to approve subscription requests, the service MUST respond with a &forbidden; error.

      + - ]]> -

      If the requested node does not exist, the service MUST respond with an ¬found; error.

      - +       + +

      If the requested node does not exist, the service MUST respond with an ¬found; error.

      + ]]> +       +       +

      Upon receiving the data form for managing subscription requests, the owner then MAY request pending subscription approval requests for a given node.

      @@ -3968,15 +4057,16 @@ And by opposing end them? id='pending2'/> ]]>

      The service shall then send one subscription approval message for each pending subscription request, as shown above for a single pending subscription request.

      -

      Note: A service SHOULD conform to its affiliation policies in maintaining the list of pending subscriptions. In particular, if the affiliation of an entity with a pending subscription is modified to owner or publisher, the service SHOULD automatically approve the subscription request and remove the entity's previous request from the pending list. Similarly, if the affiliation of an entity with a pending subscription is modified to outcast, the service SHOULD automatically reject the subscription request and remove the entity's previous request from the pending list.

      -

      If an entity's subscription request is denied, the service SHOULD send a &MESSAGE; to the entity, where the message conforms to the format described in the Notification of Subscription Denial or Cancellation section of this document.

      +

      Note: A service SHOULD conform to its affiliation policies in maintaining the list of pending subscriptions. In particular, if the affiliation of an entity with a pending subscription is modified to owner or publisher, the service SHOULD automatically approve the subscription request and remove the entity's previous request from the pending list. Similarly, if the affiliation of an entity with a pending subscription is modified to outcast, the service SHOULD automatically reject the subscription request and remove the entity's previous request from the pending list. (If an entity's subscription request is denied, the service SHOULD send a &MESSAGE; to the entity, where the message conforms to the format described in the Notification of Subscription Denial or Cancellation section of this document.)

             -

      A service MAY allow a node owner to edit the list of subscriptions associated with a given node and to set subscriptions for new entities (for nodes of type "whitelist", this enables the node owner to add subscribers); if so, it MUST advertise support for the "pubsub#manage-subscriptions" feature.

      -

      In order to request a list of all subscriptions, a node owner MUST send a subscriptions request, consisting of a <subscriptions/> element whose 'node' attribute specifies the NodeID of the relevant node.

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

      +

      Note: This feature enables a node owner to set subscriptions for new entities; for nodes of type "whitelist", this enables the node owner to add subscribers.

      + +

      In order to request a list of all subscriptions, a node owner MUST send a subscriptions request, consisting of a <subscriptions/> element whose 'node' attribute specifies the NodeID of the relevant node.

      + ]]> -

      If no error occurs, the service MUST return the list of subscriptions for entities whose subscription state is "subscribed" or "unconfigured" (it MUST NOT return entities whose subscription state is "none" and SHOULD NOT return entities whose subscription state is "pending"). The result MAY specify multiple <subscription/> elements for the same entity (JID), but each element MUST possess a distinct value of the 'subid' attribute (as shown below).

      - + +

      If no error occurs, the service MUST return the list of subscriptions for entities whose subscription state is "subscribed" or "unconfigured" (it MUST NOT return entities whose subscription state is "none" and SHOULD NOT return entities whose subscription state is "pending"). The result MAY specify multiple <subscription/> elements for the same entity (JID), but each element MUST possess a distinct value of the 'subid' attribute (as shown below).

      + - ]]> -

      There are several reasons why the manage subscriptions request might fail:

      -
        -
      1. The service does not support subscription management.
        2. -
      2. The requesting entity does not have sufficient privileges to manage subscriptions.
        3. -
      3. The specified node does not exist.
        4. -
      + ]]>       +       + +

      There are several reasons why the manage subscriptions request might fail:

      +
        +
      1. The service does not support subscription management.
        2. +
      2. The requesting entity does not have sufficient privileges to manage subscriptions.
        3. +
      3. The specified node does not exist.
        4. +

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

      - +

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

      + @@ -4023,9 +4118,11 @@ And by opposing end them? feature='manage-subscriptions'/> - ]]> -

      If the requesting entity is not a node owner, the service MUST return a &forbidden; error.

      - + + +

      If the requesting entity is not a node owner, the service MUST return a &forbidden; error.

      + @@ -4036,9 +4133,11 @@ And by opposing end them? - ]]> -

      If the node does not exist, the service MUST return an ¬found; error.

      - +       + +

      If the node does not exist, the service MUST return an ¬found; error.

      + @@ -4049,9 +4148,12 @@ And by opposing end them? - ]]> -

      Upon receiving the subscriptions list, the node owner MAY modify subscription states. The owner MUST send only modified subscription states (i.e., a "delta"), not the complete list. (Note: If the 'subscription' attribute is not specified in a modification request, then the value MUST NOT be changed.)

      - +       +       + +

      Upon receiving the subscriptions list, the node owner MAY modify subscription states. The owner MUST send only modified subscription states (i.e., a "delta"), not the complete list. (Note: If the 'subscription' attribute is not specified in a modification request, then the value MUST NOT be changed.)

      + - ]]> - + - ]]> -

      In order to remove an entity from the subscriptions list, the owner MUST set the value of the 'subscription' attribute to "none" and the service MUST remove that entity from the subscriptions list and not return it in response to future list requests.

      -

      The owner MAY change multiple subscriptions in a single request. If one of the entity elements specified is invalid, the service MUST return an IQ error (which SHOULD be ¬acceptable;) with the invalid entries, where the subscription returned is the original, un-altered subscription.

      - +       + +

      In order to remove an entity from the subscriptions list, the owner MUST set the value of the 'subscription' attribute to "none" and the service MUST remove that entity from the subscriptions list and not return it in response to future list requests.

      +       + +

      The owner MAY change multiple subscriptions in a single request. If one of the entity elements specified is invalid, the service MUST return an IQ error (which SHOULD be ¬acceptable;) with the invalid entries, where the subscription returned is the original, un-altered subscription.

      + - ]]> - + - ]]> -

      If errors occur during a modification request for multiple entities, the pubsub service MUST return any <subscription/> element(s) which caused the error. Returned entities which failed to be modified MUST include the existing 'subscription' attribute. Any entity elements which are not returned in an IQ error case MUST be treated as successful modifications. The owner MAY specify multiple <subscription/> elements for the same entity, but each element MUST possess a distinct value of the 'subid' attribute.

      -

      An implementation SHOULD send notification to an entity whose subscription has changed (see the Notification of Subscription State Changes section of this document).

      - +

      If errors occur during a modification request for multiple entities, the pubsub service MUST return any <subscription/> element(s) which caused the error. Returned entities which failed to be modified MUST include the existing 'subscription' attribute. Any entity elements which are not returned in an IQ error case MUST be treated as successful modifications. The owner MAY specify multiple <subscription/> elements for the same entity, but each element MUST possess a distinct value of the 'subid' attribute.

      +       + +

      An implementation SHOULD send notification to an entity whose subscription has changed (see the Notification of Subscription State Changes section of this document).

      + - ]]> + ]]>       +       -

      A service MAY allow a node owner to edit the affiliations of entities associated with a given node and to set affiliations for new entities; if so, it MUST advertise support for the "pubsub#modify-affiliations" feature.

      -

      In order to request a list of all affiliated entities, a node owner MUST send an affiliations request, consisting of an <affiliations/> element whose 'node' attribute specifies the NodeID of the relevant node.

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

      + +

      In order to request a list of all affiliated entities, a node owner MUST send an affiliations request, consisting of an <affiliations/> element whose 'node' attribute specifies the NodeID of the relevant node.

      + - ]]> -

      If no error occurs, the service MUST return the list of entities whose affiliation is "owner", "publisher", or "outcast" (it MUST NOT return entities whose affiliation is "none").

      - +       + +

      If no error occurs, the service MUST return the list of entities whose affiliation is "owner", "publisher", or "outcast" (it MUST NOT return entities whose affiliation is "none").

      + - ]]> -

      There are several reasons why the affiliated entities request might fail:

      -
        -
      1. The service does not support modification of affiliations.
        2. -
      2. The requesting entity does not have sufficient privileges to modify affiliations.
        3. -
      3. The specified node does not exist.
        4. -
      + ]]>       + + +

      There are several reasons why the affiliated entities request might fail:

      +
        +
      1. The service does not support modification of affiliations.
        2. +
      2. The requesting entity does not have sufficient privileges to modify affiliations.
        3. +
      3. The specified node does not exist.
        4. +

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

      - +

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

      + @@ -4157,9 +4272,11 @@ And by opposing end them? feature='modify-affiliations'/> - ]]> -

      If the requesting entity is not a node owner, the service MUST return a &forbidden; error.

      - + + +

      If the requesting entity is not a node owner, the service MUST return a &forbidden; error.

      + @@ -4170,9 +4287,11 @@ And by opposing end them? - ]]> -

      If the node does not exist, the service MUST return an ¬found; error.

      - +       + +

      If the node does not exist, the service MUST return an ¬found; error.

      + @@ -4183,9 +4302,12 @@ And by opposing end them? - ]]> -

      Upon receiving the affiliations list, the node owner MAY modify affiliations. The owner MUST send only modified affiliations (i.e., a "delta"), not the complete list. (Note: If the 'affiliation' attribute is not specified in a modification request, then the value MUST NOT be changed.)

      - +       +       + +

      Upon receiving the affiliations list, the node owner MAY modify affiliations. The owner MUST send only modified affiliations (i.e., a "delta"), not the complete list. (Note: If the 'affiliation' attribute is not specified in a modification request, then the value MUST NOT be changed.)

      + - ]]> - + - ]]> -

      In order to remove an entity from the affiliations list, the owner MUST set the value of the 'affiliation' attribute to "none" and the service MUST remove that entity from the affiliations list and not return it in response to future list requests.

      -

      The owner MAY change multiple affiliations in a single request. If one of the entity elements specified is invalid, the service MUST return an IQ error (which SHOULD be ¬acceptable;) with the invalid entries, where the affiliation returned is the original, un-altered affiliation.

      -

      The following example shows an entity attempting to make the owner something other than an affiliation of "owner", an action which MUST NOT be allowed if there is only one owner.

      - +       + +

      In order to remove an entity from the affiliations list, the owner MUST set the value of the 'affiliation' attribute to "none" and the service MUST remove that entity from the affiliations list and not return it in response to future list requests.

      +       + +

      The owner MAY change multiple affiliations in a single request. If one of the entity elements specified is invalid, the service MUST return an IQ error (which SHOULD be ¬acceptable;) with the invalid entries, where the affiliation returned is the original, un-altered affiliation.

      +

      The following example shows an entity attempting to make the owner something other than an affiliation of "owner", an action which MUST NOT be allowed if there is only one owner.

      + - ]]> - + - ]]> -

      The state chart at the beginning of this document is a MUST-IMPLEMENT set of rules for checking possible state transitions. Implementations MAY enforce other (more strict) rules. If errors occur during a modification request for multiple entities, the pubsub service MUST return any <affiliation/> element(s) which caused the error. Returned entities which failed to be modified MUST include the existing 'affiliation' attribute. Any entity elements which are not returned in an IQ error case MUST be treated as successful modifications. The owner MUST NOT specify multiple <affiliation/> elements for the same entity; otherwise the service MUST return a &badrequest; error.

      -

      An implementation MAY send a message to an entity whose affiliation has changed, which MAY contain a &BODY; element specifying natural-language text regarding the affiliation change and which SHOULD contain the modified affiliation data.

      - +

      The state chart at the beginning of this document is a MUST-IMPLEMENT set of rules for checking possible state transitions. Implementations MAY enforce other (more strict) rules. If errors occur during a modification request for multiple entities, the pubsub service MUST return any <affiliation/> element(s) which caused the error. Returned entities which failed to be modified MUST include the existing 'affiliation' attribute. Any entity elements which are not returned in an IQ error case MUST be treated as successful modifications. The owner MUST NOT specify multiple <affiliation/> elements for the same entity; otherwise the service MUST return a &badrequest; error.

      +       + +

      An implementation MAY send a message to an entity whose affiliation has changed, which MAY contain a &BODY; element specifying natural-language text regarding the affiliation change and which SHOULD contain the modified affiliation data.

      + @@ -4246,7 +4374,8 @@ And by opposing end them? - ]]> + ]]> +       @@ -4454,10 +4583,11 @@ And by opposing end them? -

      To create a new node and associate it with an existing collection, the node configuration protocol MUST be used in the node creation request (see the Create and Configure a Node section of this document). In order to specify the associated collection(s), the form MUST include a 'pubsub#collection' field.

      -

      Note: Inclusion of the node configuration form is not necessary if the node is being created as a first-level child of the root collection node, since every such child is automatically affiliated with the root collection node (if any).

      -

      Note: For the protocol used to associate an existing node with a collection, refer to the Associate an Existing Node with a Collection section of this document.

      - +

      To create a new node and associate it with an existing collection, the node configuration protocol MUST be used in the node creation request (see the Create and Configure a Node section of this document). In order to specify the associated collection(s), the form MUST include a 'pubsub#collection' field.

      +

      Note: Inclusion of the node configuration form is not necessary if the node is being created as a first-level child of the root collection node, since every such child is automatically affiliated with the root collection node (if any).

      +

      Note: For the protocol used to associate an existing node with a collection, refer to the Associate an Existing Node with a Collection section of this document.

      + - ]]> -

      The service then creates the node and associates it with the collection.

      -

      Note: If the node is a collection node and the requesting entity wishes to request the default configuration, the requesting entity MUST include only the "pubsub#collection" and "pubsub#node_type" fields in the configuration form.

      -

      There are several reasons why the request might fail:

      -
        -
      1. The request specified more than one collection node, but the service allows a node to be associated with only one collection node.
        2. -
      2. The requesting entity does not have sufficient privileges to associate a node with the specified collection node.
        3. -
      3. No additional nodes can be associated with the collection node.
        4. -
      4. The specified collection node is actually a leaf node.
        5. -
      5. The specified collection node does not exist.
        6. -
      + ]]>       +

      Note: If the node is a collection node and the requesting entity wishes to request the default configuration, the requesting entity MUST include only the "pubsub#collection" and "pubsub#node_type" fields in the configuration form.

      + + +

      If no error occurs, the service MUST create the node and associate it with the collection.

      +       + +

      There are several reasons why the request might fail:

      +
        +
      1. The request specified more than one collection node, but the service allows a node to be associated with only one collection node.
        2. +
      2. The requesting entity does not have sufficient privileges to associate a node with the specified collection node.
        3. +
      3. No additional nodes can be associated with the collection node.
        4. +
      4. The specified collection node is actually a leaf node.
        5. +
      5. The specified collection node does not exist.
        6. +

      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.

      - +

      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.

      + - ]]> -

      If the requesting entity does not have sufficient privileges to associate a node with the specified collection node, the service MUST return a &forbidden; error.

      - + + +

      If the requesting entity does not have sufficient privileges to associate a node with the specified collection node, the service MUST return a &forbidden; error.

      + - ]]> -

      If no additional nodes can be associated with the collection node because a configurable limit of associated nodes has been reached, the service MUST return a &conflict; error, which SHOULD also include a pubsub-specific error condition of <max-nodes-exceeded/>.

      - +       + +

      If no additional nodes can be associated with the collection node because a configurable limit of associated nodes has been reached, the service MUST return a &conflict; error, which SHOULD also include a pubsub-specific error condition of <max-nodes-exceeded/>.

      + - ]]> -

      If the specified collection node is actually a leaf node, the service MUST return an ¬allowed; error.

      - +       + +

      If the specified collection node is actually a leaf node, the service MUST return an ¬allowed; error.

      + - ]]> -

      If the specified collection node does not exist, the service MUST return an ¬found; error.

      - +       + +

      If the specified collection node does not exist, the service MUST return an ¬found; error.

      + - ]]> + ]]>       + +       @@ -5046,7 +5191,7 @@ And by opposing end them?
    - + @@ -5528,7 +5673,7 @@ And by opposing end them?

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

    @@ -5540,12 +5685,12 @@ And by opposing end them? @@ -5556,23 +5701,23 @@ And by opposing end them? @@ -5589,12 +5734,12 @@ And by opposing end them? @@ -5610,12 +5755,12 @@ And by opposing end them? ]]>

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

    +
    -->NotificationPayload
     NotificationPayload
    Persistent Publisher MUST include an &ITEM; element, which MAY be empty or contain a payload; if item ID is not provided by publisher, it MUST be generated by pubsub service multi-subscribe A single entity may subscribe to a node multiple times. OPTIONAL Multiple Subscriptions
    outcast-affiliation