mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-24 02:02:16 -05:00
XEP-0470: version 0.2.0
- update reactions to be similar to XEP-0444 - namespace bump
This commit is contained in:
Jérôme Poisson
parent
0981631d37
commit
64bb4e53ea
115
xep-0470.xml
115
xep-0470.xml
@ -28,6 +28,21 @@
|
||||
<email>goffi@goffi.org</email>
|
||||
<jid>goffi@jabber.fr</jid>
|
||||
</author>
|
||||
<revision>
|
||||
<version>0.2.0</version>
|
||||
<date>2022-08-25</date>
|
||||
<initials>jp</initials>
|
||||
<remark>
|
||||
<ul>
|
||||
<li>
|
||||
Update reactions to be similar to &xep0444;
|
||||
</li>
|
||||
<li>
|
||||
Namespace bump
|
||||
</li>
|
||||
</ul>
|
||||
</remark>
|
||||
</revision>
|
||||
<revision>
|
||||
<version>0.1.0</version>
|
||||
<date>2022-08-23</date>
|
||||
@ -62,7 +77,7 @@
|
||||
<li>handle uniqueness of attachment per JID</li>
|
||||
<li>have an extensible mechanism for future use</li>
|
||||
<li>re-use pubsub subscription and access control mechanism</li>
|
||||
<li>suitable to implement feature similar to commonly seen "like/favourite" and "reaction".</li>
|
||||
<li>suitable to implement feature similar to commonly seen "like/favourite" and "reactions".</li>
|
||||
<li>optionally have a way to "group" or "summarize" informations: get a summary of all attachment without needing to retrieve each of them individually.</li>
|
||||
</ul>
|
||||
<p>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).</p>
|
||||
@ -70,7 +85,7 @@
|
||||
<section1 topic='Glossary' anchor='glossary'>
|
||||
<ul>
|
||||
<li><strong>like/favourite</strong>: a common way to indicate interest in item</li>
|
||||
<li><strong>reaction</strong>: attaching one or more emoji(s) to an item</li>
|
||||
<li><strong>reactions</strong>: attaching one or more emoji(s) to an item</li>
|
||||
<li><strong>attachment node</strong>: node where attached data of an item are published</li>
|
||||
<li><strong>summary node</strong>: node managed by pubsub service which keep a summary of all attachment of target items</li>
|
||||
<li><strong>target item</strong>: item to which metadata is attached</li>
|
||||
@ -83,14 +98,14 @@
|
||||
<section1 topic='Use Cases' anchor='usecases'>
|
||||
<section2 topic="Basic Usage" anchor="basic">
|
||||
<p>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'.</p>
|
||||
<p>To do so he publishes the following item to the suitable attachment node:</p>
|
||||
<p>To do so he publishes the following item to the suitable attachment node:</p>
|
||||
<example caption="Romeo Indicates To Juliet That He Has Noticed Her Publication"><![CDATA[
|
||||
<iq from='romeo@montague.lit/123'
|
||||
id='attachment_1'
|
||||
to='juliet@capulet.lit'
|
||||
type='set'>
|
||||
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
||||
<publish node='urn:xmpp:pubsub-attachments:0/xmpp:juliet@capulet.lit?;node=urn%3Axmpp%3Amicroblog%3A0;item=balcony-restoration-afd1'>
|
||||
<publish node='urn:xmpp:pubsub-attachments:1/xmpp:juliet@capulet.lit?;node=urn%3Axmpp%3Amicroblog%3A0;item=balcony-restoration-afd1'>
|
||||
<item id='romeo@montague.lit'>
|
||||
<attachments>
|
||||
<noticed timestamp="2022-07-11T12:07:24Z" />
|
||||
@ -107,11 +122,14 @@
|
||||
to='juliet@capulet.lit'
|
||||
type='set'>
|
||||
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
||||
<publish node='urn:xmpp:pubsub-attachments:0/xmpp:juliet@capulet.lit?;node=urn%3Axmpp%3Amicroblog%3A0;item=balcony-restoration-afd1'>
|
||||
<publish node='urn:xmpp:pubsub-attachments:1/xmpp:juliet@capulet.lit?;node=urn%3Axmpp%3Amicroblog%3A0;item=balcony-restoration-afd1'>
|
||||
<item id='romeo@montague.lit'>
|
||||
<attachments>
|
||||
<noticed timestamp="2022-07-11T12:07:24Z" />
|
||||
<reaction timestamp="2022-07-11T12:07:48Z">👷🔨</reaction>
|
||||
<reactions timestamp="2022-07-11T12:07:48Z">
|
||||
<reaction>👷</reaction>
|
||||
<reaction>🔨</reaction>
|
||||
</reactions>
|
||||
</attachments>
|
||||
</item>
|
||||
</publish>
|
||||
@ -122,17 +140,17 @@
|
||||
<p>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:</p>
|
||||
<ul>
|
||||
<li>the namespace '<strong>urn:xmpp:pubsub-attachments:0</strong>'</li>
|
||||
<li>the namespace '<strong>urn:xmpp:pubsub-attachments:1</strong>'</li>
|
||||
<li>a slash "<strong>/</strong>"</li>
|
||||
<li>the <strong>XMPP URI</strong> of the target item as explained at <link url="https://xmpp.org/extensions/xep-0060.html#impl-ur">XEP-0060 § Pubsub URIs</link></li>
|
||||
</ul>
|
||||
<p>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"</p>
|
||||
<p>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"</p>
|
||||
<p>This node SHOULD have the same access model than the target node.</p>
|
||||
<p>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.</p>
|
||||
<p>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 <link url="https://xmpp.org/extensions/xep-0060.html#publisher-publish-error-node">XEP-0060 §7.1.3.3 Node Does Not Exist</link>. 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).</p>
|
||||
<p>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;.</p>
|
||||
<p>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;.</p>
|
||||
<p>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.</p>
|
||||
<p>All attachments of a specific JID can be deleted at once by retracting the item as specified at <link url="https://xmpp.org/extensions/xep-0060.html#publisher-delete">XEP-0060 §7.2 Delete an Item from a Node</link>. 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.</p>
|
||||
<p>All attachments of a specific JID can be deleted at once by retracting the item as specified at <link url="https://xmpp.org/extensions/xep-0060.html#publisher-delete">XEP-0060 §7.2 Delete an Item from a Node</link>. 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.</p>
|
||||
</section3>
|
||||
</section2>
|
||||
|
||||
@ -145,7 +163,7 @@
|
||||
<li>forbid manual creation of attachment or summary node</li>
|
||||
<li>check validity of items published to attachment node, and notably the item ID</li>
|
||||
<li>create and maintain a summary node</li>
|
||||
<li>handle <noticed> and <reaction> attachments</li>
|
||||
<li>handle <noticed> and <reactions> attachments</li>
|
||||
</ul>
|
||||
</section2>
|
||||
|
||||
@ -157,14 +175,14 @@
|
||||
|
||||
<section2 topic="Manual Node Creation Rejection" anchor="node-creation-rejection">
|
||||
<p>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.</p>
|
||||
<p>A client can see if a node creation is necessary by using &xep0030;: the presence of 'urn:xmpp:pubsub-attachments:0' feature in <em>disco#info</em> means that the service is fully-compliant, and that manual node creation MUST NOT be done.</p>
|
||||
<p>A client can see if a node creation is necessary by using &xep0030;: the presence of 'urn:xmpp:pubsub-attachments:1' feature in <em>disco#info</em> means that the service is fully-compliant, and that manual node creation MUST NOT be done.</p>
|
||||
</section2>
|
||||
|
||||
<section2 topic="Checking Validity of Attachments Items" anchor="validity-check">
|
||||
<p>When an entity publish an items with attachments to an attachment node, a fully-compliant service MUST check that the item is valid by</p>
|
||||
<ol>
|
||||
<li>Verifying that the item ID is equal to the bare jid of the item publisher</li>
|
||||
<li>Verifying that the root element of the payload is an <attachments> element qualified by the 'urn:xmpp:pubsub-attachments:0' namespace</li>
|
||||
<li>Verifying that the root element of the payload is an <attachments> element qualified by the 'urn:xmpp:pubsub-attachments:1' namespace</li>
|
||||
</ol>
|
||||
<p>If any of these points are not met, the service MUST reject the item by returning a &badrequest; error.</p>
|
||||
<p>In addition to those 2 mandatory checks, a pubsub service MAY add implementation specific checks.</p>
|
||||
@ -174,12 +192,12 @@
|
||||
<p>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.</p>
|
||||
<p>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:</p>
|
||||
<ol>
|
||||
<li>the '<strong>urn:xmpp:pubsub-attachments:summary:0</strong>' prefix</li>
|
||||
<li>the '<strong>urn:xmpp:pubsub-attachments:summary:1</strong>' prefix</li>
|
||||
<li>a slash "<strong>/</strong>"</li>
|
||||
<li>the <strong>name of the target node</strong></li>
|
||||
</ol>
|
||||
<p>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.</p>
|
||||
<p>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.</p>
|
||||
<p>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.</p>
|
||||
<p>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.</p>
|
||||
<p>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.</p>
|
||||
<p>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.</p>
|
||||
<example caption="Romeo Check Summary of Attachments of Juliet Blog"><![CDATA[
|
||||
@ -188,7 +206,7 @@
|
||||
to='juliet@capulet.lit'
|
||||
type='get'>
|
||||
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
||||
<items node='urn:xmpp:pubsub-attachments:summary:0/urn:xmpp:microblog:0' />
|
||||
<items node='urn:xmpp:pubsub-attachments:summary:1/urn:xmpp:microblog:0' />
|
||||
</pubsub>
|
||||
</iq>
|
||||
]]></example>
|
||||
@ -198,14 +216,16 @@
|
||||
to='romeo@montague.lit/123'
|
||||
type='result'>
|
||||
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
||||
<items node='urn:xmpp:pubsub-attachments:summary:0/urn:xmpp:microblog:0'>
|
||||
<items node='urn:xmpp:pubsub-attachments:summary:1/urn:xmpp:microblog:0'>
|
||||
<item id='balcony-restoration-afd1'>
|
||||
<summary xmlns='urn:xmpp:pubsub-attachments:summary:0'>
|
||||
<summary xmlns='urn:xmpp:pubsub-attachments:summary:1'>
|
||||
<noticed count="5" />
|
||||
<reaction >
|
||||
<multiple count="2">👷</multiple>
|
||||
🔨🔧🚧
|
||||
</reaction>
|
||||
<reactions>
|
||||
<reaction count="2">👷</reaction>
|
||||
<reaction>🔨</reaction>
|
||||
<reaction>🔧</reaction>
|
||||
<reaction>🚧</reaction>
|
||||
</reactions>
|
||||
</summary>
|
||||
</item>
|
||||
<!-- ... -->
|
||||
@ -244,9 +264,9 @@
|
||||
to='juliet@capulet.lit/123'
|
||||
type='result'>
|
||||
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
||||
<items node='urn:xmpp:pubsub-attachments:summary:0/urn:xmpp:example:0'>
|
||||
<items node='urn:xmpp:pubsub-attachments:summary:1/urn:xmpp:example:0'>
|
||||
<item id='ball-event-ab1e'>
|
||||
<summary xmlns='urn:xmpp:pubsub-attachments:summary:0'>
|
||||
<summary xmlns='urn:xmpp:pubsub-attachments:summary:1'>
|
||||
<noticed count="25" />
|
||||
</summary>
|
||||
</item>
|
||||
@ -258,30 +278,32 @@
|
||||
|
||||
</section2>
|
||||
|
||||
<section2 topic="Reaction Attachment" anchor="reaction">
|
||||
<section3 topic="Attachment Overview" anchor="reaction_overview">
|
||||
<p><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.</p>
|
||||
<section2 topic="Reactions Attachment" anchor="reactions">
|
||||
<section3 topic="Attachment Overview" anchor="reactions_overview">
|
||||
<p><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.</p>
|
||||
|
||||
|
||||
</section3>
|
||||
<section3 topic="Summarizing" anchor="reaction_summarizing">
|
||||
<p>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.</p>
|
||||
<section3 topic="Summarizing" anchor="reactions_summarizing">
|
||||
<p>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).</p>
|
||||
<p>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.</p>
|
||||
|
||||
<example caption="Example of reaction Attachment Summary"><![CDATA[
|
||||
<example caption="Example of reactions Attachment Summary"><![CDATA[
|
||||
<iq from='pubsub.example.net'
|
||||
id='attachment_5'
|
||||
to='juliet@capulet.lit/123'
|
||||
type='result'>
|
||||
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
|
||||
<items node='urn:xmpp:pubsub-attachments:summary:0/urn:xmpp:example:0'>
|
||||
<items node='urn:xmpp:pubsub-attachments:summary:1/urn:xmpp:example:0'>
|
||||
<item id='ball-event-ab1e'>
|
||||
<summary xmlns='urn:xmpp:pubsub-attachments:summary:0'>
|
||||
<reaction >
|
||||
<multiple count="22">💃</multiple>
|
||||
<multiple count="2">🩰</multiple>
|
||||
🎉🥳🎈
|
||||
</reaction>
|
||||
<summary xmlns='urn:xmpp:pubsub-attachments:summary:1'>
|
||||
<reactions>
|
||||
<reaction count="22">💃</reaction>
|
||||
<reaction count="2">🩰</reaction>
|
||||
<reaction>🎉</reaction>
|
||||
<reaction>🥳</reaction>
|
||||
<reaction>🎈</reaction>
|
||||
</reactions>
|
||||
</summary>
|
||||
</item>
|
||||
</items>
|
||||
@ -296,12 +318,23 @@
|
||||
<section1 topic='Business Rules' anchor='rules'>
|
||||
<ul>
|
||||
<li>Similarly to "like" in commercial software, the "noticed" attachment can be used to analyse user's tastes, political view, religious beliefs, sexual orientation, etc. It is recommended that implementers post a prominent notice warning users of potential abuses.</li>
|
||||
<li>Emoji pictures may differ widely on various platforms where they are displayed. This has already led to misunderstanding of reactions, as a slightly different picture can be interpreted in a completely different way from what the reaction author meant. Here again, a prominent notice in implementations warning user is recommended.</li>
|
||||
<li>Emoji pictures may differ widely on various platforms where they are displayed. This has already led to misunderstanding of reactions, as a slightly different picture can be interpreted in a completely different way from what the reactions author meant. Here again, a prominent notice in implementations warning user is recommended.</li>
|
||||
<li>As "reactions" attachment is similar to &xep0444; which is used for &MESSAGE; stanza, non &MESSAGE; related <link url="https://xmpp.org/extensions/xep-0444.html#rules">business rules from there</link> apply for this attachment too. Notably:
|
||||
<p>
|
||||
<em>
|
||||
A <reaction> element SHOULD only contain Unicode codepoints that
|
||||
can be displayed as a single emoji, as specified in the latest revision
|
||||
of the <link url="http://www.unicode.org/reports/tr51/">Unicode Technical Standard #51</link> <note>Unicode Technical Standard #51 <<link url="http://www.unicode.org/reports/tr51/">http://www.unicode.org/reports/tr51/</link>>.</note>.
|
||||
Receiving entities MAY ignore <reaction> elements that do not comply
|
||||
with this specification.
|
||||
</em>
|
||||
</p>
|
||||
</li>
|
||||
</ul>
|
||||
</section1>
|
||||
|
||||
<section1 topic='discovering support' anchor='disco'>
|
||||
<p>If and only if a PEP or pubsub service is fully-compliant with the "Pubsub Attachments" protocol (as explained in <link url="full-compliance">Full-Compliance section</link>), it MUST advertise that fact by including the "urn:xmpp:pubsub-attachments:0" discovery feature in response to a &xep0030; information request:</p>
|
||||
<p>If and only if a PEP or pubsub service is fully-compliant with the "Pubsub Attachments" protocol (as explained in <link url="full-compliance">Full-Compliance section</link>), it MUST advertise that fact by including the "urn:xmpp:pubsub-attachments:1" discovery feature in response to a &xep0030; information request:</p>
|
||||
<example caption="service discovery information request"><![CDATA[
|
||||
<iq from='example.org'
|
||||
id='disco1'
|
||||
@ -317,7 +350,7 @@
|
||||
type='result'>
|
||||
<query xmlns='http://jabber.org/protocol/disco#info'>
|
||||
…
|
||||
<feature var='urn:xmpp:pubsub-attachments:0'/>
|
||||
<feature var='urn:xmpp:pubsub-attachments:1'/>
|
||||
…
|
||||
</query>
|
||||
</iq>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user