<p>Commenting is a popular activity on the Internet. Users leave comments on just about anything: blog posts, news articles, product reviews, photos, status updates, etc. Existing commenting solutions often involve proprietary access methods and authentication, and are silo'd off from other services. This specification proposes an open and federated way of commenting. A conversation exists as a set of &xep0060; nodes, containing comment items or other activity, and any user with a JID may leave a comment there (per conversation access rules). The protocol is designed to be modern, social, and extensible. Additionally, while the protocol is described in XMPP terms, the core concept is meant to translate easily to the HTTP-based Social Web.</p>
</section1>
<section1topic='Requirements'anchor='reqs'>
<p>The following features are required:</p>
<ul>
<li>A client MUST be able to efficiently request the most recent portion of a conversation (as well as "page" to further portions) without having to fetch every comment.</li>
<li>A client MUST be able to efficiently receive updates to a conversation as they happen.</li>
<li>It MUST be possible to nest comments (comments as replies to other comments) for rendering the conversation as a tree.</li>
<li>A user MUST be able to mention another user in a comment, and have that user be notified about it.</li>
<li>A user MUST be able to efficiently track its own history in a conversation using a third-party service. For example, such a service might maintain a web page of the user's activity, or send an SMS message to the user if a reply is discovered.</li>
<li>To enable future expansion, consideration must be made for allowing non-comment activity in the conversation, even if this specification does not define those activity types.</li>
</ul>
</section1>
<section1topic='Result Set Management'anchor='pubsub-rsm'>
<p>&xep0060; contains an example of how to retrieve items with &xep0059;, but the specification is light on details. This section gives a more complete description of how RSM is used in conjunction with PubSub.</p>
<p>Clients MAY provide an RSM section in the iq request:</p>
<examplecaption="Requesting items with a maximum of 20 in the result set"><![CDATA[
<p>The server MAY provide an RSM section in the response. This is already documented in XEP-0060. The server can do this regardless of whether or not the client has made the request with RSM.</p>
<p>Use of RSM implies that there is a natural ordering of the items at a node. The criteria used for ordering is to be determined by the node.</p>
<p>RSM and max_items do not mix. If the client provides both, then the server MUST prefer RSM. If the server does not support RSM, then it may honor max_items and return items ordered by newest first (which may not necessarily be the same as the ordering used by RSM).</p>
<p>A conversation exists across a set of PubSub nodes, some of which are dynamic:</p>
<tablecaption='Conversation Nodes and their Descriptions'>
<tr>
<th>Node</th>
<th>Natural Sort Order</th>
<th>Description</th>
</tr>
<td>"info"</td>
<td>N/A</td>
<td>Singleton node containing information about the conversation.</td>
<tr>
<td>"comments" (dynamic)</td>
<td>modified-ascending</td>
<td>Contains comment items only. This node is primarily used for presenting conversations to the user. It is essentially a subset of the activity node.</td>
</tr>
<tr>
<td>"activity" (dynamic)</td>
<td>modified-ascending</td>
<td>Contains all activity items in the conversation, including comments. This node is primarily used for submitting comments and receiving mention events. Item persistence is OPTIONAL. Advanced implementations may choose to maintain full activity history of a conversation and expose it in this node.</td>
</tr>
</table>
<p>The comments and activity nodes share item data. Comments are added to the conversation by publishing to the activity node, yet the comment will also appear in the comments node as a result. In fact, since the activity node is not required to offer item persistence, it is possible that the comment might <em>only</em> be retrievable through the comments node. Implementations of this protocol will therefore require tight association between the comments and activity nodes. It is not possible to implement this protocol using a "generic" PubSub service.</p>
<p>A dynamic node accepts additional parameters by appending the parameters to the node name using a "query"-like notation. Parameters and values in the query string MUST be percent-encoded.</p>
<tablecaption='Dynamic Node Parameters'>
<tr>
<th>Name</th>
<th>Allowed Values</th>
<th>Applies To</th>
<th>Example</th>
</tr>
<tr>
<td>"order"</td>
<td>"-created" (sort items by created time, descending)</td>
<td>comments</td>
<td>Node name "comments?order=-created" would present comments in created-descending order.</td>
</tr>
<tr>
<td>"parent_ids"</td>
<td>Comma-separated list of parent comment IDs to filter by. An empty value means to include top-level comments.</td>
<td>comments</td>
<td>Node name "comments?order=-created&parent_ids=1%2C5a%2Co19g%2C" (note last value is empty) would present items in created-descending order, filtered to only include comments that have parent ID "1", "5a", "o19g", or are top-level.</td>
</tr>
</table>
<p>The "activity" node is defined as dynamic to allow for future expansion, even though no dynamic node parameters are defined in this document that apply to it.</p>
<p>Before utilizing additional nodes or parameters not defined in this document, the client SHOULD first determine support via &xep0030; or other discovery mechanism. If the server does not support or understand a parameter or value, it SHOULD reject the request. Attempting to service a request by ignoring unsupported parameters will most likely result in incorrect or undesired behavior.</p>
<p>A conversation is accessible through a JID and optionally a node prefix. The prefix is prepended to the desired node name, separated by a '/' character. For example, if the "Coffee Talk" conversation is said to be accessible at the JID "coffeetalk@comments.example.com" without a node prefix, then PubSub interactions are made using the node names defined above (i.e. "info", "comments", etc). If that conversation is instead said to be accessible at the JID "comments.example.com" with node prefix "coffeetalk", then PubSub interactions are made using node names like "coffeetalk/info", "coffeetalk/comments", etc. This allows conversations to be provisioned as either one per JID or many per JID.</p>
</section2>
<section2topic='Retrieving Information About the Conversation'anchor='retrieve-info'>
<p>Information about a conversation can be obtained by requesting the item from the info node.</p>
<summary>A great place to talk about your day.</summary>
<id>tag:comments.example.com,2011:coffeetalk</id>
<published>2011-07-01T10:15:00Z</published>
<updated>2011-07-01T10:15:00Z</updated>
</entry>
</item>
</items>
</pubsub>
</iq>]]></example>
<p>It is also possible to subscribe to the info node to track changes to the conversation information.</p>
</section2>
<section2topic='Retrieving Comments in a Conversation'anchor='retrieve-comments'>
<p>The process for retrieving the first "page" of a conversation and listening for further updates can be summarized as follows:</p>
<ol>
<li>Subscribe to the "comments" node.</li>
<li>Retrieve items from the "comments?order=-created" node. Multiple retrieval requests may be required depending on the client display needs (parent_ids can be used to reduce trips, see the <linkurl='#impl'>Implementation Notes</link>)</li>
<li>Updates are pushed via the subscription.</li>
</ol>
<p>First, the client subscribes to the comments node. A temporary subscription is recommended, so that it is removed if the client goes offline.</p>
<examplecaption="Subscribe to comments node"><