xeps/xep-0060.xml

7418 lines
377 KiB
XML
Raw Normal View History

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
<!ENTITY ITEM "&lt;item/&gt;">
<!ENTITY ITEMS "&lt;items/&gt;">
<!ENTITY PUBSUB "&lt;pubsub/&gt;">
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Publish-Subscribe</title>
<abstract>This specification defines an XMPP protocol extension for generic publish-subscribe functionality. The protocol enables XMPP entities to create nodes (topics) at a pubsub service and publish information at those nodes; an event notification (with or without payload) is then broadcasted to all entities that have subscribed to the node. Pubsub therefore adheres to the classic Observer design pattern and can serve as the foundation for a wide variety of applications, including news feeds, content syndication, rich presence, geolocation, workflow systems, network management systems, and any other application that requires event notifications.</abstract>
&LEGALNOTICE;
<number>0060</number>
<status>Draft</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0004</spec>
<spec>XEP-0030</spec>
<spec>XEP-0059</spec>
<spec>XEP-0068</spec>
<spec>XEP-0082</spec>
<spec>XEP-0131</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>pubsub</shortname>
<schemaloc>
<ns>pubsub</ns>
<url>http://xmpp.org/schemas/pubsub.xsd</url>
</schemaloc>
<schemaloc>
<ns>pubsub#errors</ns>
<url>http://xmpp.org/schemas/pubsub-errors.xsd</url>
</schemaloc>
<schemaloc>
<ns>pubsub#event</ns>
<url>http://xmpp.org/schemas/pubsub-event.xsd</url>
</schemaloc>
<schemaloc>
<ns>pubsub#owner</ns>
<url>http://xmpp.org/schemas/pubsub-owner.xsd</url>
</schemaloc>
<discuss>pubsub</discuss>
&pgmillard;
&stpeter;
&ralphm;
<revision>
<version>1.23.0</version>
<date>2022-01-14</date>
<initials>edhelas, pep</initials>
<remark><p>Clarify (redefine) pubsub#type field.</p></remark>
</revision>
<revision>
<version>1.22.1</version>
<date>2021-12-26</date>
<initials>egp</initials>
<remark><p>Fix indentation to be consistent.</p></remark>
</revision>
<revision>
<version>1.22.0</version>
<date>2021-09-07</date>
<initials>jp</initials>
<remark><p>Remove exception for last item when purging a node: all items must be removed.</p></remark>
</revision>
<revision>
<version>1.21.0</version>
<date>2021-08-03</date>
<initials>pep</initials>
<remark><p>Revert change from version 1.15.5 which changed meta-data to metadata in wire protocol. That was an unintended breaking change which has now been reverted.</p></remark>
</revision>
<revision>
<version>1.20.0</version>
<date>2021-06-08</date>
<initials>pep</initials>
<remark><p>Add integer-or-max datatype to use with Data Forms Validation.</p></remark>
</revision>
<revision>
<version>1.19.1</version>
<date>2021-03-04</date>
<initials>mw</initials>
<remark><p>Cross-document editorial adjustments for inclusive language.</p></remark>
</revision>
<revision>
<version>1.19.0</version>
<date>2020-08-16</date>
<initials>ps</initials>
<remark><p>Add missing 'item' key and 'retrieve' action to query type registry.</p></remark>
</revision>
2020-08-25 11:32:39 -04:00
<revision>
<version>1.18.1</version>
<date>2020-08-25</date>
<initials>lnjx</initials>
<remark><p>Fix trivial typo</p></remark>
</revision>
<revision>
<version>1.18.0</version>
<date>2020-02-27</date>
<initials>jsc</initials>
<remark><p>Properly specifiy that an empty &lt;item/&gt; is invalid on publish.</p></remark>
</revision>
<revision>
<version>1.17.0</version>
<date>2019-10-06</date>
<initials>dg</initials>
<remark><p>Clarify node config behaviour with regards to unlimited behaviour for fields that specify a maximum.</p></remark>
</revision>
2019-09-11 11:43:00 -04:00
<revision>
<version>1.16.0</version>
<date>2019-09-11</date>
<initials>edhelas</initials>
<remark><p>Add a pubsub#rsm disco#info feature to clear confusion</p></remark>
</revision>
2019-06-19 09:11:20 -04:00
<revision>
2019-06-19 09:12:23 -04:00
<version>1.15.8</version>
2019-06-19 09:11:20 -04:00
<date>2019-06-19</date>
<initials>edhelas</initials>
<remark><p>Add pubsub#access_model and pubsub#publish_model to examples</p></remark>
</revision>
<revision>
<version>1.15.7</version>
<date>2019-01-27</date>
<initials>egp</initials>
<remark>
<p>Add 'publisher' attribute to &lt;item/&gt; in the http://jabber.org/protocol/pubsub schema, forgotten in revision 1.13.</p>
</remark>
</revision>
<revision>
<version>1.15.6</version>
<date>2018-11-22</date>
<initials>jsc (Editor)</initials>
<remark>
<ul><li>Correct several "entity element(s)" to "&lt;subscription/&gt; element(s)" (mw)</li>
<li>Remove unused and never defined 'node' attribute in pubsub#event item schema. This had been added in version 1.8 of the JEP, but never used. (egp)</li></ul>
</remark>
</revision>
<revision>
2018-11-22 12:06:34 -05:00
<version>1.15.5</version>
<date>2018-11-03</date>
<initials>pep</initials>
<remark>Fix a bunch of typos, batch-style.</remark>
</revision>
2018-11-08 14:26:32 -05:00
<revision>
<version>1.15.4</version>
<date>2018-08-11</date>
<initials>egp</initials>
<remark>Add example where fewer than the number of requested items are returned.</remark>
</revision>
<revision>
<version>1.15.3</version>
<date>2018-08-18</date>
<initials>egp</initials>
<remark>
<p>Add a new sentence and example about what to do if there are fewer items than requested present in a node.</p>
</remark>
</revision>
2018-02-08 13:39:51 -05:00
<revision>
2018-05-14 16:23:29 -04:00
<version>1.15.2</version>
<date>2018-05-14</date>
<initials>egp</initials>
<remark>
<p>Fix a few things in the schema:</p>
<ul>
<li>Remove duplicated &lt;publish/&gt; element.</li>
<li>Make &lt;affiliations/&gt;s node attribute optional.</li>
<li>Add a missing optional dataform in &lt;default/&gt;.</li>
</ul>
</remark>
</revision>
<revision>
2018-02-08 13:39:51 -05:00
<version>1.15.1</version>
<date>2018-02-02</date>
<initials>sc</initials>
<remark>
<p>Add missing "retrieve-default-sub" feature to the XML Schema</p>
</remark>
</revision>
<revision>
<version>1.15.0</version>
<date>2017-12-12</date>
<initials>dg</initials>
<remark>
<ul>
<li>Specify that unregistered publish-options are mapped 1:1 to node configurations</li>
<li>Get rid of per-item OVERRIDE</li>
<li>Get rid of METADATA publish-options</li>
<li>Remove registration for the obsolete pubsub#access_model publish-options</li>
</ul>
</remark>
</revision>
<revision>
<version>1.14</version>
<date>2017-11-29</date>
<initials>jt</initials>
<remark><p>Add pubsub#multi-items to features.</p></remark>
</revision>
2017-10-10 02:32:29 -04:00
<revision>
<version>1.13.8</version>
<date>2017-10-10</date>
<initials>fs (XEP Editor: jwi)</initials>
<remark><p>Add missing dependency on XEP-0059.</p></remark>
</revision>
<revision>
<version>1.13.7</version>
<date>2017-08-24</date>
<initials>egp</initials>
<remark><p>Fix examples using invalid XEP-0082 dates.</p></remark>
</revision>
<revision>
<version>1.13.6</version>
<date>2017-06-22</date>
<initials>dg</initials>
<remark><p>Clarify behaviour of publish-options. Fields must be registered</p></remark>
</revision>
2016-12-17 14:04:33 -05:00
<revision>
<version>1.13.5</version>
<date>2016-12-21</date>
<initials>psa (XEP Editor: ssw)</initials>
<remark><p>Add missing options to schema.</p></remark>
</revision>
2016-12-02 20:28:29 -05:00
<revision>
<version>1.13.4</version>
<date>2016-12-02</date>
<initials>psa</initials>
<remark><p>Make Multiple Simultaneous Modifications examples consistent with text.</p></remark>
</revision>
<revision>
<version>1.13.3</version>
<date>2016-12-08</date>
<initials>ss (XEP Editor: ssw)</initials>
<remark><p>Include publisher with any item retrieval.</p></remark>
</revision>
2016-10-11 11:30:30 -04:00
<revision>
<version>1.13.2</version>
<date>2016-10-11</date>
<initials>ss (XEP Editor: ssw)</initials>
<remark><p>Be more consistent with reply.</p></remark>
</revision>
2016-07-21 02:57:41 -04:00
<revision>
<version>1.13.1</version>
<date>2016-07-21</date>
<initials>ss</initials>
<remark>
<ul>
<li>Fix wording, replace Jabber with XMPP where applicable.</li>
</ul>
</remark>
</revision>
<revision>
<version>1.13</version>
<date>2010-07-12</date>
<initials>psa</initials>
<remark>
<ul>
<li>Pending further discussion: added but then removed change to allow notifications via IQ stanzas; removed but then retained batch publishing; removed but then retained SubIDs in subscription approvals.</li>
<li>Corrected a large number of reported errata.</li>
<li>Removed delete-any feature.</li>
<li>Added missing delete-items feature.</li>
<li>Added special value of "presence" for the pubsub#expire option to support temporary subscriptions.</li>
<li>Removed replyto and replyroom config options.</li>
<li>Removed multiple node discovery since it depended on the deprecated Service Discovery Publishing feature.</li>
<li>Defined "room" value for itemreply config option.</li>
<li>Added optional 'publisher' attribute to &lt;item/&gt; element.</li>
<li>Added optional &lt;redirect/&gt; child to &lt;delete/&gt; element.</li>
2011-04-11 18:33:53 -04:00
<li>Based redirects on URIs for consistency with RFC 6120 gone and redirect errors.</li>
<li>Clarified meaning of filtered notifications (they are based on NodeIDs, not payload namespaces).</li>
<li>Added pubsub-on-a-jid service discovery feature for explicit discovery that an IM and presence account also functions as a virtual pubsub service.</li>
<li>Added purge_offline node configuration option for purging the node when the relevant publisher goes offline, for use in certain extended presence applications.</li>
<li>Added item_expire node configuration option for automatically removing items after a certain number of seconds.</li>
<li>Added notification_type node configuration option for defining which value of the &lt;message/&gt; type attribute shall be used for notifications.</li>
<li>Added retrieve-default-sub feature for retrieving default subscription configuration from a node (as you can retrieve default node configuration from the service).</li>
<li>Clarified suggested rules for payload definitions.</li>
<li>Mentioned that singleton pattern can be enforced by setting max_items to 1.</li>
<li>Removed the notion of batch publishing because it makes information coherence and atom handling excessively difficult.</li>
<li>Added error handling for too-many-subscriptions to help prevent a certain denial of service attack.</li>
<li>Added process for retrieving default subscription configuration options for leaf nodes, by omitting the 'node' attribute on the &lt;default/&gt; element (also added the &lt;default/&gt; element to the schema for the http://jabber.org/protocol/pubsub namespace, since it was missing).</li>
<li>Removed informational mapping of node metadata to Dublin Core.</li>
</ul>
</remark>
</revision>
<revision>
<version>1.12</version>
<date>2008-09-03</date>
<initials>psa</initials>
<remark>
<ul>
<li>Specified that service should return ItemID on successful publish if no ItemID was provided in request.</li>
<li>Described the use of Result Set Management to return some but not all published items.</li>
<li>Defined pubsub#notify_sub config option so that owners can receive notifications of new subscriptions, unsubscribes, and other subscription changes.</li>
<li>Harmonized definition of +notify feature with implementation reality.</li>
<li>Moved text about collections to XEP-0248.</li>
</ul>
</remark>
</revision>
<revision>
<version>1.11</version>
<date>2008-03-05</date>
<initials>rm/psa</initials>
<remark><p>For collection nodes, changed name of node child element to associate and added disassociate child element to handle disassociation use case; corrected SHIM examples to conform to XEP-0131; modified lease expiry notification for consistency with other subscription-related notifications (i.e., not using SHIM header); renamed SHIM headers to Collection and SubID for consistency with HTTP and Email headers.</p></remark>
</revision>
<revision>
<version>1.10</version>
<date>2007-09-26</date>
<initials>psa</initials>
<remark>
<ul>
<li>In accordance with XMPP Council consensus, moved the auto-create, auto-subscribe, filtered-notifications, and last-published features from XEP-0163 to this specification</li>
<li>Clarified implications of auto-subscribe feature for handling of account owners, stable presence subscribers, and transient presence sharers</li>
<li>Updated filtered-notifications text and examples to track changes to XEP-0115</li>
<li>Added publish-options functionality</li>
<li>Added developer-friendly How It Works section</li>
<li>Defined member affiliation to properly implement whitelist feature</li>
<li>Split several long sections into smaller sub-sections.</li>
<li>Clarified that a pubsub service must generate an ItemID if the publisher does not provide one.</li>
<li>Specified recommended ItemID for singleton nodes.</li>
<li>Summarized triggers for sending notifications.</li>
</ul>
</remark>
</revision>
<revision>
<version>1.9</version>
<date>2006-09-13</date>
<initials>psa</initials>
<remark>
<ul>
<li>Replaced boolean send_item_subscribe node configuration option with more comprehensive send_last_published_item option per list discussion</li>
<li>Added deliver_notifications node configuration option to enable quiet nodes without notifications, if desired enabling pull-model item retrieval only.</li>
<li>Modified subscription and affiliation retrieval to return empty element if no results.</li>
</ul>
</remark>
</revision>
<revision>
<version>1.8</version>
<date>2006-06-27</date>
<initials>psa</initials>
<remark>
<ul>
<li>Defined five access models: open, presence, roster, authorize, and whitelist</li>
<li>Renamed pubsub#subscription_model feature to pubsub#access_model</li>
<li>Separated affiliations retrieval from subscriptions retrieval</li>
<li>Removed subscription information from affiliations management</li>
<li>Changed &lt;entity/&gt; element to &lt;subscription/&gt; element in response to subscription request</li>
<li>Clarified batch processing of item publication and item deletion</li>
<li>Added basic example to introduction</li>
<li>More fully specified node creation flows</li>
<li>More fully specified recommended behavior for caching last published item, including use of jabber:x:delay protocol</li>
<li>Specified that semantic meaning of NodeIDs must not be used to encapsulate hierarchy</li>
<li>More fully specified error conditions</li>
<li>Changed some feature-related conditions to &lt;unsupported/&gt; plus feature attribute</li>
<li>Changed some error conditions from &lt;not-authorized/&gt; to &lt;forbidden/&gt;</li>
<li>Harmonized error conditions for unsubscribe if entity is not subscribed (unexpected-request rather than not-found)</li>
<li>Further defined error conditions related to item publication</li>
<li>Specified structure of &lt;affiliations/&gt;, &lt;delete/&gt;, &lt;purge/&gt;, and &lt;subscriptions/&gt; elements qualified by pubsub#owner namespace</li>
<li>Changed retrieval of default node configuration options to use &lt;default/&gt; element, not &lt;configure/&gt; element</li>
<li>Allowed caching of last published item</li>
<li>Added pubsub#deliver subscription option</li>
<li>Added metadata fields for pubsub#owners and pubsub#contact</li>
<li>Changed element for retrieval of default node configuration options from &lt;configure/&gt; to &lt;default/&gt; to prevent ambiguity related to configuration of root collection node</li>
<li>Specified pubsub#node_type configuration field</li>
<li>Specified pubsub#collection SHIM header</li>
<li>Specified conformance with Resourceprep for nodes addressable as JIDs</li>
<li>Added pubsub#modify-affiliations feature</li>
<li>Added pubsub#digest_frequency field to subscribe_options FORM_TYPE</li>
<li>Added pubsub#roster_groups_allowed field to node_config FORM_TYPE</li>
<li>More clearly specified the requirements level (MUST, SHOULD, MAY) for each service discovery feature</li>
<li>Defined pubsub#include_body subscription option and the pubsub#body_xslt node configuration option to transform payload format into an XMPP message body, and clarified rules for inclusion of message bodies</li>
<li>Clarified nature of collections and association of a node to a collection</li>
<li>Specified that simultaneous subscriptions of type nodes and items are allowed to collection nodes</li>
<li>Added examples and further explanation of time-based and content-based subscriptions</li>
<li>Added Internationalization Considerations</li>
<li>Clarified terminology</li>
<li>Corrected and updated the schemas</li>
</ul>
</remark>
</revision>
<revision>
<version>1.7</version>
<date>2005-03-03</date>
<initials>psa/rm</initials>
<remark>
<ul>
<li>Reinstated pubsub#subscribe feature (deleted in error)</li>
<li>Added type attribute for the &lt;create/&gt; and &lt;configure/&gt; elements to differentiate between leaf nodes and collection nodes</li>
<li>In Section 8.1.7, changed affiliations retrieval support to SHOULD and added pubsub#retrieve-affiliations feature</li>
<li>In Section 8.1.10, removed two duplicate examples</li>
<li>In Section 8.1.12, clarified relationship between normal disco#info data and node metadata (which uses a service discovery extension)</li>
<li>In Section 8.2.4, specified that node purgation MUST result in one event notification, not a notification per item</li>
<li>In Section 8.1.8, further specified handling of SubIDs</li>
<li>Clarified nature of the pubsub#type field</li>
<li>Mentioned that the forbidden error should be returned in response to certain operations requested by an outcast</li>
<li>Corrected datatype of max_items attribute from xs:string to xs:positiveInteger</li>
<li>Corrected &lt;requesting-entity-not-subscribed/&gt; error to &lt;not-subscribed/&gt; since the subscribed JID need not be that of the requesting entity</li>
<li>Added service discovery features for more optional use cases: retracting items, purging nodes, deleting nodes</li>
<li>Updated relevant registries</li>
</ul>
</remark>
</revision>
<revision>
<version>1.6</version>
<date>2004-07-13</date>
<initials>pgm/psa</initials>
<remark><p>Added service discovery features for pubsub#meta-data, and pubsub#retrieve-items. Added pubsub#subscription_depth configuration option. Specified pubsub-specific error condition elements qualified by pubsub#errors namespace.</p></remark>
</revision>
<revision>
<version>1.5</version>
<date>2004-07-07</date>
<initials>pgm/psa</initials>
<remark><p>Fixed typos. Added more details to the section on collections. Added paragraph to create node use case to allow the service to change the requested node-id to something which it creates. Added text about bouncing publish requests when the request does not match the event-type for that node. Added disco features for the jabber registrar. Changed affiliation verbiage to allow publishers to remove any item. Tweaked verbiage for create node, eliminated extra example. Fully defined XMPP Registrar submissions. Corrected schemas.</p></remark>
</revision>
<revision>
<version>1.4</version>
<date>2004-06-22</date>
<initials>pgm</initials>
<remark><p>Added subid syntax in a variety of places. Added more information about disco#info and disco#items support. Added more info about subscription options. Added collection information. Added implementation notes about subscription leases, and content-based pubsub services.</p></remark>
</revision>
<revision>
<version>1.3</version>
<date>2004-04-25</date>
<initials>psa</initials>
<remark><p>Editorial review; added one implementation note.</p></remark>
</revision>
<revision>
<version>1.2</version>
<date>2004-03-09</date>
<initials>psa</initials>
<remark><p>Added XMPP error handling.</p></remark>
</revision>
<revision>
<version>1.1</version>
<date>2004-01-14</date>
<initials>psa</initials>
<remark><p>Added XMPP Registrar Considerations subsection for Service Discovery category/type registration.</p></remark>
</revision>
<revision>
<version>1.0</version>
<date>2003-10-28</date>
<initials>psa</initials>
2016-07-18 11:51:42 -04:00
<remark><p>Per a vote of the Jabber Council, advanced status to Draft.</p></remark>
</revision>
<revision>
<version>0.16</version>
<date>2003-10-23</date>
<initials>pgm</initials>
<remark><p>Clarified JID addressing usage for nodes. Added specific MAY requirement for disco usage. Added sentence about implementations verifying that an entity has a subscription before getting the current items.</p></remark>
</revision>
<revision>
<version>0.15</version>
<date>2003-10-21</date>
<initials>pgm</initials>
<remark><p>Fixed invalid XML in examples for subscription deny/allow.</p></remark>
</revision>
<revision>
<version>0.14</version>
<date>2003-10-21</date>
<initials>pgm</initials>
<remark><p>Clarified restrictions on addressing nodes by JID. Added section on Approving and Denying Subscription Requests. Changed get-pending to use Ad-Hoc Commands. Changed semantics when sending in a form type='cancel' for pending subscriptions.</p></remark>
</revision>
<revision>
<version>0.13</version>
<date>2003-09-30</date>
<initials>pgm</initials>
<remark><p>Removed item as a possible child of subscribe and unsubscribe and pubsub in the schemas. Removed retract as a possible child of item in the pubsub#event schema. Added verbiage to requirements for addressing nodes either via JIDs or disco nodes.</p></remark>
</revision>
<revision>
<version>0.12</version>
<date>2003-08-13</date>
<initials>pgm/psa</initials>
<remark><p>Defined public vs. private nodes; described how changes to existing nodes might trigger meta-node events (e.g., configuration changes); changed &lt;x/&gt; to &lt;event/&gt; for #events namespace; added metadata about meta-nodes; fully defined XMPP Registrar considerations.</p></remark>
</revision>
<revision>
<version>0.11</version>
<date>2003-06-25</date>
<initials>pgm</initials>
<remark><p>Removed subscription notifications since they have inherent issues. Removed empty implementation note sub-section.</p></remark>
</revision>
<revision>
<version>0.10</version>
<date>2003-06-11</date>
<initials>pgm</initials>
<remark><p>Fixed error example when returning 501 from an items-get request. Added note about receiving subscription requests when an entity is already subscribed. Fixed some entity elements in various subscription examples. Many were missing the node attribute. Added subscription change notification verbiage and example. Added verbiage and example of subscription state notification being sent to the requesting entity. Added disco#items information for getting a list of item identifiers for a single node. Added verbiage for returning the current entity element when a curent subscriber attempts to subscribe again.</p></remark>
</revision>
<revision>
<version>0.9</version>
<date>2003-04-30</date>
<initials>pgm</initials>
<remark><p>Include JID attributes in the entity elements when receiving your affiliations. Changed error code 406 (which was wrong) to 404, which is correct. Changed many 405 errors to 401, and modified the error table to make it more implementable (rules are more concrete). Added subscribe-options element for indicating subscriptions may be configured.</p></remark>
</revision>
<revision>
<version>0.8</version>
<date>2003-04-03</date>
<initials>pgm</initials>
<remark><p>Clarified the affiliations table and the semantics around subscribing and unsubscribing. Added protocol to get all of your affiliations in the service. Added protocol for services informing subscribers that configurable subscription options are available. Added protocol for obtaining existing node configuration settings and for concatenating configuration and node creation requests into a single stanza. Added meta-node implementation notes and specified the interaction with the XMPP Registrar and the meta NodeIDs. Added authorization notes to subscription options.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2003-02-14</date>
<initials>pgm</initials>
<remark><p>Clarified requirements around what affiliations must be supported. Moved requirements about specifying entities which can subscribe and publish out of the MUSTs to MAYs. Changed SHOULD to MAY when talking about allowing entities to create nodes. Added ability to send configuration requests in the same stanza as a creation request.</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2003-02-06</date>
<initials>pgm</initials>
<remark><p>Added more details and an example about publishing without NodeID. Added more implementation notes about NodeIDs and persistent storage.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2003-01-22</date>
<initials>pgm</initials>
<remark><p>Fixed header for delete item example. Added examples showing subscribers being notified of deleted items. Added examples for notification of node deletion, and configuration for node deletion. Added Subscriber option semantics and examples. Added examples for 402 and 407 errors on subscribe and create respectively. Added clarification about ItemID handling to impl notes.</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2003-01-21</date>
<initials>pgm</initials>
<remark><p>Clarified in-band and out-of-band configuration requirement. Added Delete Item privilege for all affiliations to the table. Added Delete item protocol for publishers and owners. Added 401 error case for subscribing to an illegal jid. Changed subscription request form. Added defaults to configuration form, and clarified role of the XMPP Registrar for the features show. Added text explaining the max_items attribute. Changed &quot;last items&quot; to &quot;most recent items&quot;. Removed default configuration acceptance -- owners should just cancel. Added the notify_retract configuration option. Clarified error handling for affiliation modifications. </p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2003-01-20</date>
<initials>pgm</initials>
<remark><p>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. </p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2003-01-02</date>
<initials>pgm</initials>
<remark><p>Added numerous implementation notes; added get-pending action with regard to subscriptions; added error table; changed purge and delete to use IQ type='set'.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2002-11-19</date>
<initials>pgm</initials>
<remark><p>Initial version.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<section2 topic='Overview' anchor='intro-overview'>
<p>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.</p>
<p>This technology uses the classic "publish-subscribe" or "observer" design pattern: a person or application publishes information, and an event notification (with or without payload) is broadcasted to all authorized subscribers. In general, the relationship between the publisher and subscriber is mediated by a service that receives publication requests, broadcasts event notifications to subscribers, and enables privileged entities to manage lists of people or applications that are authorized to publish or subscribe. The focal point for publication and subscription is a "node" to which publishers send data and from which subscribers receive event notifications. Nodes can also maintain a history of events and provide other services that supplement the pure pubsub model.</p>
<p>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 <link url='#features'>Feature Summary</link>.) 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.</p>
</section2>
<section2 topic='How It Works' anchor='intro-howitworks'>
<p>Although this specification is large because it defines many side use cases and possible error flows, the basic idea is simple:</p>
<ol>
<li>An entity publishes information to a node at a publish-subscribe service.</li>
<li>The pubsub service pushes an event notification to all entities that are authorized to learn about the published information.</li>
</ol>
<p>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 &lt;hamlet@denmark.lit&gt;. When Hamlet writes a new weblog entry, his blogging software publishes the entry to a pubsub node hosted at &lt;pubsub.shakespeare.lit&gt;:</p>
<example caption='Publisher Publishes a New Weblog Entry'><![CDATA[
<iq type='set'
from='hamlet@denmark.lit/blogbot'
to='pubsub.shakespeare.lit'
id='pub1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='princely_musings'>
<item>
<entry xmlns='http://www.w3.org/2005/Atom'>
<title>Soliloquy</title>
<summary>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
</summary>
<link rel='alternate' type='text/html'
href='http://denmark.lit/2003/12/13/atom03'/>
<id>tag:denmark.lit,2003:entry-32397</id>
<published>2003-12-13T18:30:02Z</published>
<updated>2003-12-13T18:30:02Z</updated>
</entry>
</item>
</publish>
</pubsub>
</iq>
]]></example>
<p>So that is the "pub" part of pubsub.</p>
<p>Now the pubsub service notifies all the subscribers about the new blog entry:</p>
<example caption='Service Notifies Subscribers'><![CDATA[
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit' id='foo'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='princely_musings'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
[ ... ENTRY ... ]
</item>
</items>
</event>
</message>
<message from='pubsub.shakespeare.lit' to='bernardo@denmark.lit' id='bar'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='princely_musings'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
[ ... ENTRY ... ]
</item>
</items>
</event>
</message>
<message from='pubsub.shakespeare.lit' to='horatio@denmark.lit' id='baz'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='princely_musings'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
[ ... ENTRY ... ]
</item>
</items>
</event>
</message>
<message from='pubsub.shakespeare.lit' to='bard@shakespeare.lit' id='fez'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='princely_musings'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
[ ... ENTRY ... ]
</item>
</items>
</event>
</message>
]]></example>
<p>Here is an even simpler example: a transient node that sends only event notifications without a payload:</p>
<example caption='A Transient Notification'><![CDATA[
<message from='pubsub.shakespeare.lit' to='francisco@denmark.lit'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='elsinore/doorbell'/>
</event>
</message>
]]></example>
<p>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 <link url='#owner-create'>Create a Node</link>) and subscribers may need to sign up for event notifications (see <link url='#subscriber-subscribe'>Subscribe to a Node</link>). 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 <link url='#features'>Feature Summary</link>.)</p>
</section2>
</section1>
<section1 topic='Glossary' anchor='glossary'>
<p>The following terms are used throughout this document to refer to elements, objects, or actions that occur in the context of a pubsub service. (Note: Some of these terms are specified in greater detail within the body of this document.)</p>
<dl>
<di><dt>Authorize Access Model</dt><dd>A node access model under which an entity can subscribe only through having a subscription request approved by a node owner (subscription requests are accepted but only provisionally) and only subscribers may retrieve items.</dd></di>
<di><dt>Address</dt><dd>(1) A JID as defined in &xmppcore;, or (2) the combination of a JID and a &xep0030; node.</dd></di>
<di><dt>Collection Node</dt><dd>A type of node that contains nodes and/or other collections but no published items. Collections make it possible to represent more sophisticated relationships among nodes. Collection nodes are defined in &xep0248;.</dd></di>
2016-07-18 04:55:29 -04:00
<di><dt>Entity</dt><dd>A JID-addressable XMPP entity (client, service, application, etc.).</dd></di>
<di><dt>Event</dt><dd>A change in the state of a node.</dd></di>
<di><dt>Instant Node</dt><dd>A node whose NodeID is automatically generated by a pubsub service.</dd></di>
<di><dt>Item</dt><dd>An XML fragment which is published to a node, thereby generating an event.</dd></di>
<di><dt>ItemID</dt><dd>A unique identifier for an item in the context of a specific node.</dd></di>
<di><dt>Leaf Node</dt><dd>A type of node that contains published items only. It is NOT a container for other nodes.</dd></di>
<di><dt>Node</dt><dd>A virtual location to which information can be published and from which event notifications and/or payloads can be received (in other pubsub systems, this may be labelled a "topic").</dd></di>
<di><dt>NodeID</dt><dd>The unique identifier for a node within the context of a pubsub service. The NodeID is either supplied by the node creator or generated by the pubsub service (if the node creator requests an Instant Node). The NodeID MAY have semantic meaning (e.g., in some systems or in pubsub profiles such as PEP the NodeID might be an XML namespace for the associated payload), but such meaning is OPTIONAL. If a document defines a given NodeID as unique within the realm of XMPP pubsub systems, it MUST specify the XML namespace of the associated payload.</dd></di>
<di><dt>Notification</dt><dd>A message sent to a subscriber informing them of an event.</dd></di>
<di><dt>Outcast</dt><dd>An entity that is disallowed from subscribing or publishing to a node.</dd></di>
<di><dt>Owner</dt><dd>The manager of a node, of which there may be more than one; often but not necessarily the node creator.</dd></di>
<di><dt>Open Access Model</dt><dd>A node access model under which any entity may subscribe and retrieve items without approval.</dd></di>
<di><dt>Payload</dt><dd>The XML data that is contained within the &lt;item/&gt; element of a publication request or an event notification. A given payload is defined by an XML namespace and associated schema. A document that defines a payload format SHOULD specify whether the payload can be used only for a NodeID whose value is the same as the XML namespace, or whether the payload can be used for any NodeID. Such a document also SHOULD specify whether it is suggested that node at which such payloads are published are best configured as <link url='#impl-singleton'>Singleton Nodes</link>.</dd></di>
<di><dt>Personal Eventing</dt><dd>A simplified subset of Publish-Subscribe for use in the context of instant messaging and presence applications, whereby each IM user's JID is a virtual pubsub service; for details, see &xep0163;.</dd></di>
<di><dt>Presence Access Model</dt><dd>A node access model under which any entity that is subscribed to the owner's presence with a subscription of type "from" or "both" (see &rfc3921;) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems.</dd></di>
<di><dt>Publisher</dt><dd>An entity that is allowed to publish items to a node and that is automatically subscribed to the node.</dd></di>
<di><dt>Publish-Only</dt><dd>An entity that is allowed to publish items to a node but that is not allowed to receive notifications. (This affiliation is useful in the context of nodes that do not have an open access model when automated entities need to generate notifications on behalf of the owner.)</dd></di>
<di><dt>Pubsub Service</dt><dd>An XMPP server or component that adheres to the protocol defined herein.</dd></di>
<di><dt>Roster Access Model</dt><dd>A node access model under which any entity that is subscribed to the owner's presence and in the specified roster group(s) may subscribe to the node and retrieve items from the node; this access model applies mainly to instant messaging systems.</dd></di>
<di><dt>Subscriber</dt><dd>An entity that is subscribed to a node.</dd></di>
<di><dt>Whitelist Access Model</dt><dd>A node access model under which an entity may subscribe and retrieve items only if explicitly allowed to do so by the node owner (subscription requests from unauthorized entities are rejected).</dd></di>
</dl>
</section1>
<!-- =================== REQS ======================== -->
<section1 topic='Requirements' anchor='reqs'>
2016-07-18 04:55:29 -04:00
<p>Requirements for a pubsub service can be driven by end-user needs as well as the needs of other components and services which can use the service. First, a pubsub service implemented using XMPP MUST provide the basic features that implement a pure publish-subscribe pattern:</p>
<!-- ================== MUSTS =================== -->
<ul>
<li>An entity MUST be able to publish events to a service such that all subscribers to a node receive notification of the event. See <link url='#publisher-publish'>Publish an Item to a Node</link>.</li>
<li>An entity MUST be able to subscribe to a node (or be informed that subscription is not allowed). See <link url='#subscriber-subscribe'>Subscribe to a Node</link>.</li>
<li>An entity MUST be allowed to be affiliated with a node. Allowable affiliations are member, none, outcast, owner, publish-only, and publisher. Implementations MUST support affiliations of none and owner, and MAY support affiliations of member, outcast, publisher, and publish-only. See <link url='#affiliations'>Affiliations</link>.</li>
<li>An entity MUST be allowed to query the pubsub service (or a specific node) to determine what optional features of this specification the service (or node) implements. This query MUST use the Service Discovery (disco#info) protocol. See <link url='#entity-info'>Discover Node Information</link>.</li>
</ul>
<!-- =================== MAYS and SHOULDS =================== -->
2016-07-18 11:51:31 -04:00
<p>Some of the possible uses of an XMPP-based pubsub service will require other features, but these features are OPTIONAL and therefore not mandatory for compliance with this specification. However, if these features are implemented, they MUST adhere to the protocol described herein in to be compliant. These features include:</p>
<ul>
<li>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.</li>
<li>A node owner SHOULD be able to specify who may subscribe to a node.</li>
<li>A node owner SHOULD be able to specify who may publish to a node.</li>
<li>A node MAY be configured to deliver the published payload inside the event notification.</li>
<li>A node MAY be configured to persist published items to some persistent storage mechanism.</li>
<li>A node MAY be configured to persist only a limited number of items.</li>
<li>A service MAY support collections as described in <cite>XEP-0248</cite>.</li>
<li>A service or node MAY support extended service discovery information (metadata).</li>
</ul>
</section1>
<section1 topic='Preliminaries' anchor='preliminaries'>
<section2 topic='Affiliations' anchor='affiliations'>
<p>To manage permissions, the protocol defined herein uses a hierarchy of affiliations, similiar to those introduced in &xep0045;.</p>
<p>All affiliations MUST be based on a bare JID &BAREJID; instead of a full JID &FULLJID;.</p>
<p>Support for the "owner" and "none" affiliations is REQUIRED. Support for all other affiliations is RECOMMENDED. For each non-required affiliation supported by an implementation, it SHOULD return a service discovery feature of "name-affiliation" where "name" is the name of the affiliation, such as "member", "outcast", or "publisher" (see the <link url='#features'>Feature Summary</link>). Particular kinds of pubsub services MAY enforce additional requirements (e.g., requiring support for a given non-required affiliation or for all affiliations).</p>
<table caption='Affiliations and their Privileges'>
<tr>
<th>Affiliation</th>
<th>Subscribe</th>
<th>Retrieve Items</th>
<th>Publish Items</th>
<th>Delete Single Item</th>
<th>Purge Node</th>
<th>Configure Node</th>
<th>Delete Node</th>
</tr>
<tr>
<td>Owner</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
</tr>
<tr>
<td>Publisher</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes *</td>
<td>Yes *</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td>Publish-Only</td>
<td>No</td>
<td>No</td>
<td>Yes</td>
<td>Yes *</td>
<td>No *</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td>Member</td>
<td>Yes</td>
<td>Yes</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td>None</td>
<td>Yes</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td>Outcast</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
</table>
<p>* Note: A service MAY allow any publisher to delete / purge any item once it has been published to that node instead of allowing only the original publisher to remove it. This behavior is NOT RECOMMENDED for the publish-only affiliation, which SHOULD be allowed to delete only items that the publish-only entity has published.</p>
<p>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.</p>
<table caption='Affiliation State Chart'>
<tr>
<th>&#160;</th>
<th>Outcast</th>
<th>None</th>
<th>Member</th>
<th>Publisher</th>
<th>Owner</th>
</tr>
<tr>
<td>Outcast</td>
<td>--</td>
<td>Owner removes ban</td>