It is nowadays common to attach informations to messages or other items in various social networks: famous example are "like" (or "favourite") and "reactions" features.
While there are ways to attach informations to <message/> stanzas with extensions such as Message Fastening (XEP-0422) [1] or Message Reactions (XEP-0444) [2], this is not the case for pubsub items
Some software use comments as a work-around for Microblogging Over XMPP (XEP-0277) [3], by posting a single "♥" character to notify a "like". This has the advantage to work out of the box even if no specific implementation is done to manage this, but this has a couple of disadvantages:
This XEP proposes an alternative and generic solution, which can work with any kind of pubsub item.
The design goal of this XEP are:
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).
Romeo wants to indicate to Juliet that he has noticed her post about the balcony restoration. This Microblogging Over XMPP (XEP-0277) [3] 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:
<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'>
<item id='romeo@montague.lit'>
<attachments>
<noticed timestamp="2022-07-11T12:07:24Z" />
</attachments>
</item>
</publish>
</pubsub>
</iq>
Few seconds later, Romeo reacts with some emojis, it does that with the following item, and his client takes care of keeping the <noticed> element above:
<iq from='romeo@montague.lit/123'
id='attachment_2'
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'>
<item id='romeo@montague.lit'>
<attachments>
<noticed timestamp="2022-07-11T12:07:24Z" />
<reaction timestamp="2022-07-11T12:07:48Z">👷🔨</reaction>
</attachments>
</item>
</publish>
</pubsub>
</iq>
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"
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 XMPP Date and Time Profiles (XEP-0082) [4].
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.
Previous section describes the basic usage of pubsub attachments, which works with generic pubsub service. However, even if it works out of the box, it relies on the goodwill of entities: an attacker or simply a bugged implementation could publish an item with wrong ID or somebody else bare JID, an item publisher client could miss the creation of attachment node, or give it bad access model, access model between attachment node and target node can become out of sync, etc.
To avoid these flaws, a pubsub service SHOULD implement the features described in this and following sections. If a pubsub service does so, it is said to be fully-compliant with pubsub attachments, and then and only then it can advertises the feature with Service Discovery (XEP-0030) [5]
To be fully compliant, a PEP or pubsub service MUST implement the following features, which are explained in details below:
When an attachments item is published to a fully-compliant pubsub service, and if the attachment node doesn't exist, the service MUST create automatically the node as explained at XEP-0060 §7.1.4 Automatic Node Creation, except that instead of applying the default configuration, it MUST apply the same access_model and publish_model as for the target node. The service MAY also copy other configuration options if they differ from default, it is up to the implementation to decide which other options are relevant to copy.
If the <iq/> stanza of the publishing client includes publishing options as explained in XEP-0060 § 7.1.5 Publishing Options, they are ignored.
If later the target node configuration is updated and either access_model or pubsub_model are modified, the fully-compliant service MUST also update the attachment node pubsub_model and access_model accordingly.
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 <not-allowed/> error.
A client can see if a node creation is necessary by using Service Discovery (XEP-0030) [5]: 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.
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 <bad-request/> error.
In addition to those 2 mandatory checks, a pubsub service MAY add implementation specific checks.
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.
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.
<iq from='romeo@montague.lit/123'
id='attachment_3'
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' />
</pubsub>
</iq>
<iq from='juliet@capulet.lit'
id='attachment_3'
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'>
<item id='balcony-restoration-afd1'>
<summary xmlns='urn:xmpp:pubsub-attachments:summary:0'>
<noticed count="5" />
<reaction >
<multiple count="2">👷</multiple>
🔨🔧🚧
</reaction>
</summary>
</item>
<!-- ... -->
</items>
</pubsub>
</iq>
The <noticed> feature described here is similar to what is most often known as "like", and sometime "favourite". It has been decided to use "noticed" word to highlight a different spirit from its ancestors.
The "like" feature has been invented in mid 2000s on commercial social network. Over the years, this functionality has proven to be a borderline toxic problem. Among known issues, we can mention:
For all these reasons, it has been decided to use the word "noticed" which reflect better the way it is used by some people (notably observed on some social network built on top of the ActivityPub protocol): it is then used as way to say "I have seen" or "I've taken that into account".
However, and for compatibly reason with other protocols (especially to have the tools to make gateways), the summary feature of <noticed> attachment does count the number of elements. After reading this note, it is up to the various implementations to decide whether to show this number prominently, inconspicuously, or not at all.
<noticed> element is attached by an entity to say that they have seen or taken into account something. On the client UI side, it is often published when user push a simple button or icon, and the attachment is often visible with the same icon displayed on the noticed item. If an icon is used, it is recommended to use something as neutral as possible, thus a heart icon SHOULD NOT be used to avoid misunderstanding between various implementations (also see foreword above). As for any attachment, an optional "timestamp" attribute MAY be set with a value of latest publication DateTime as specified in XMPP Date and Time Profiles (XEP-0082) [4].
To summarize <noticed> attachments, a fully-compliant pubsub service just sum-up the total number of <noticed> elements found for the item, and put this number in "count" attribute of the summary <noticed> element. In the example below, an item has been noticed 25 times.
<iq from='pubsub.example.net'
id='attachment_4'
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'>
<item id='ball-event-ab1e'>
<summary xmlns='urn:xmpp:pubsub-attachments:summary:0'>
<noticed count="25" />
</summary>
</item>
</items>
</pubsub>
</iq>
<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.
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.
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.
<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'>
<item id='ball-event-ab1e'>
<summary xmlns='urn:xmpp:pubsub-attachments:summary:0'>
<reaction >
<multiple count="22">💃</multiple>
<multiple count="2">🩰</multiple>
🎉🥳🎈
</reaction>
</summary>
</item>
</items>
</pubsub>
</iq>
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 Service Discovery (XEP-0030) [5] information request:
<iq from='example.org'
id='disco1'
to='example.com'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
<iq from='example.com'
id='disco1'
to='example.org'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
…
<feature var='urn:xmpp:pubsub-attachments:0'/>
…
</query>
</iq>
TODO
TODO
TODO
TODO
This document in other formats: XML PDF
This XMPP Extension Protocol is copyright © 1999 – 2024 by the XMPP Standards Foundation (XSF).
Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.
## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.
This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).
The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.
Discussion on other xmpp.org discussion lists might also be appropriate; see <https://xmpp.org/community/> for a complete list.
Errata can be sent to <editor@xmpp.org>.
The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
1. XEP-0422: Message Fastening <https://xmpp.org/extensions/xep-0422.html>.
2. XEP-0444: Message Reactions <https://xmpp.org/extensions/xep-0444.html>.
3. XEP-0277: Microblogging over XMPP <https://xmpp.org/extensions/xep-0277.html>.
4. XEP-0082: XMPP Date and Time Profiles <https://xmpp.org/extensions/xep-0082.html>.
5. XEP-0030: Service Discovery <https://xmpp.org/extensions/xep-0030.html>.
Note: Older versions of this specification might be available at https://xmpp.org/extensions/attic/
First draft.
@report{poisson2022pubsub-attachments,
title = {Pubsub Attachments},
author = {Poisson, Jérôme},
type = {XEP},
number = {xxxx},
version = {0.0.1},
institution = {XMPP Standards Foundation},
url = {https://xmpp.org/extensions/xep-xxxx.html},
date = {2022-07-11/2022-07-11},
}END