To facilitate the bootstrapping of this XEP, it is also designed to work in a basic way with generic pubsub service. However, some implementation work is necessary to offer the full potential of the XEP (and notably to be able to scale).
@@ -70,7 +85,7 @@Romeo wants to indicate to Juliet that he has noticed her post about the balcony restoration. This &xep0277; item has been published on the PEP service of Juliet at service juliet@capulet.lit on the node 'urn:xmpp:microblog:0' and the item has the ID 'balcony-restoration-afd1'.
-To do so he publishes the following item to the suitable attachment node:
+To do so he publishes the following item to the suitable attachment node:
To attach metadata to a pubsub item, an "attachment node" MAY be created, either by the publisher of the target item, or by the pubsub service if it is fully-compliant with this XEP (see below). This node name is generated by merging the following strings:
Thus, in the example above, the node name to use for the item "balcony-restoration-afd1" of the node "urn:xmpp:microblog:0" located at PEP service "juliet@capulet.lit" is: "urn:xmpp:pubsub-attachments:0/xmpp:juliet@capulet.lit?;node=urn%3Axmpp%3Amicroblog%3A0;item=balcony-restoration-afd1"
+Thus, in the example above, the node name to use for the item "balcony-restoration-afd1" of the node "urn:xmpp:microblog:0" located at PEP service "juliet@capulet.lit" is: "urn:xmpp:pubsub-attachments:1/xmpp:juliet@capulet.lit?;node=urn%3Axmpp%3Amicroblog%3A0;item=balcony-restoration-afd1"
This node SHOULD have the same access model than the target node.
To publish to this node, an entity MUST use its own bare JID for the ID of the item. It is both to keep the uniqueness of the item per JID and to make the retrieval of attachment for a particular entity easy.
The entity willing to publish attachment tries directly to publish to the above mentioned node. If the node doesn't exist (and is not created on the fly by the pubsub service, see below), the pubsub service SHOULD answer with <item-not-found> error as explained in XEP-0060 ยง7.1.3.3 Node Does Not Exist. If the node doesn't not exist, that means that it's not possible to attach metadata to the target item, the entity willing to publish the attachment MUST NOT try to create the node itself (that would result in wrong ownership of the node).
-An attachment payload is build with a top level <attachments> element which has zero, one or more child elements. This specification defines 2 child elements, <noticed> and <reaction>, but future XEPs may add their own elements qualified by their own namespaces to extend the functionalities. Each child element MAY have an optional 'timestamp' attribute indicating when the element has been attached. The value of this attribute is a DateTime as specified in &xep0082;.
+An attachment payload is build with a top level <attachments> element which has zero, one or more child elements. This specification defines 2 child elements, <noticed> and <reactions>, but future XEPs may add their own elements qualified by their own namespaces to extend the functionalities. Each child element MAY have an optional 'timestamp' attribute indicating when the element has been attached. The value of this attribute is a DateTime as specified in &xep0082;.
Because there is one item per JID; to update, add or remove attachments an entity simply re-publish an item on the same node with its bare JID as ID. It is the responsibility of the publishing entity to republish all previously existing attachments (except those who need to be removed). If an XMPP client doesn't know a specific attachment, it MUST keep it and republish it when updating attachments.
-All attachments of a specific JID can be deleted at once by retracting the item as specified at XEP-0060 ยง7.2 Delete an Item from a Node. A client SHOULD not retract an attachment item if there are attachments it doesn't know, instead it SHOULD publish a new attachment item without the attachments which must be removed, and with the unknown attachments left in place.
+All attachments of a specific JID can be deleted at once by retracting the item as specified at XEP-0060 ยง7.2 Delete an Item from a Node. A client SHOULD NOT retract an attachment item if there are attachments it doesn't know, instead it SHOULD publish a new attachment item without the attachments which must be removed, and with the unknown attachments left in place.
If any user, including owner of target node or publisher of target item, tries to create manually an attachment node or a summary node, a fully-compliant service MUST reject it by returning a ¬allowed; error.
-A client can see if a node creation is necessary by using &xep0030;: the presence of 'urn:xmpp:pubsub-attachments:0' feature in disco#info means that the service is fully-compliant, and that manual node creation MUST NOT be done.
+A client can see if a node creation is necessary by using &xep0030;: the presence of 'urn:xmpp:pubsub-attachments:1' feature in disco#info means that the service is fully-compliant, and that manual node creation MUST NOT be done.
When an entity publish an items with attachments to an attachment node, a fully-compliant service MUST check that the item is valid by
If any of these points are not met, the service MUST reject the item by returning a &badrequest; error.
In addition to those 2 mandatory checks, a pubsub service MAY add implementation specific checks.
@@ -174,12 +192,12 @@As soon as a first attachment is received, a fully-compliant pubsub service MUST create a "summary node". A summary node is a node maintained by the service which group all attachments of a kind, allowing client to have a good overview of the data without needing to retrieve individually all items of the attachment nodes of all target items.
A summary node has the same access_model as the attachment node, but nobody is allowed to publish directly to it. The summary node is linked to the target node, and its name is made by joining the following element:
Thus in the initial example, for the blog of Juliet, the summary node name would be 'urn:xmpp:pubsub-attachments:summary:0/urn:xmpp:microblog:0' and it would be located at the PEP service juliet@capulet.lit.
-For each item of the target node which has attachments, the summary node MUST contain an item which MUST have the same ID. This item contain a <summary> element qualified with the namespace 'urn:xmpp:pubsub-attachments:summary:0'. This item has elements with names matching attachments elements names, and a summary data which depend of the attachment. This specifications explain below how to summarize <noticed> and <reaction> attachments, it is the up to other XEPs specifying other features to explain how to summarize their own attachments. If a service doesn't know how to summarize an attachment, it SHOULD ignore it.
+Thus in the initial example, for the blog of Juliet, the summary node name would be 'urn:xmpp:pubsub-attachments:summary:1/urn:xmpp:microblog:0' and it would be located at the PEP service juliet@capulet.lit.
+For each item of the target node which has attachments, the summary node MUST contain an item which MUST have the same ID. This item contain a <summary> element qualified with the namespace 'urn:xmpp:pubsub-attachments:summary:1'. This item has elements with names matching attachments elements names, and a summary data which depend of the attachment. This specifications explain below how to summarize <noticed> and <reactions> attachments, it is the up to other XEPs specifying other features to explain how to summarize their own attachments. If a service doesn't know how to summarize an attachment, it SHOULD ignore it.
If a target item has no attachment at all, or if all attachments have been removed, the node MAY either return an <item-not-found> error, or an empty <summary> element, whatever is simpler for the service implementation.
Summary node subscriptions are working as for normal pubsub nodes: when a new attachment is published, resulting in the corresponding summary item updated, an event is sent with the new item to every subscribers.
<reaction> element lets an entity attach various emojis to an item. Emojis are simply put in the content of a <reaction> element, and a client MUST ensure that any given emoji only appears once at most. A for any attachment, a "timestamp" attribute may be set with the DateTime of latest publication.
+<reactions> element lets an entity attach various emojis to an item. Each emoji is put as the content of a single <reaction> element, and a client SHOULD ensure that any <reaction> element only appears once at most. As for any attachment, a "timestamp" attribute may be set with the DateTime of latest publication to the root <reactions> element. The protocol is similar to &xep0444; which is used for &MESSAGE; stanza.
To summarize <reaction> attachments, a fully-compliant pubsub service counts how many times each emoji is attached, ignoring duplicate from the same JID if any. If an emoji only appears once, it is simply put in the content of the <reaction>, however if it appears several times, it must be put in a <multiple> child element which MUST have a "count" attribute with the number of times that the emoji appears as value.
+To summarize <reactions> attachments, a fully-compliant pubsub service counts how many times each emoji is attached, ignoring duplicate from the same JID if any. If an emoji appears multiple times (from distinct bare JIDs), a 'count' attribute MUST be added to the <reaction> element with the number of time this reaction appear in all reactions as a value (if the same reaction appears several times for a single bare JID, it MUST be counted only once).
In following example, all emojis are attached only once to the item, except the woman dancing one which appears 22 times and the ballet shoes one which appears twice.
-
+
+ A <reaction> element SHOULD only contain Unicode codepoints that
+ can be displayed as a single emoji, as specified in the latest revision
+ of the Unicode Technical Standard #51
If and only if a PEP or pubsub service is fully-compliant with the "Pubsub Attachments" protocol (as explained in Full-Compliance section), it MUST advertise that fact by including the "urn:xmpp:pubsub-attachments:0" discovery feature in response to a &xep0030; information request:
+If and only if a PEP or pubsub service is fully-compliant with the "Pubsub Attachments" protocol (as explained in Full-Compliance section), it MUST advertise that fact by including the "urn:xmpp:pubsub-attachments:1" discovery feature in response to a &xep0030; information request: