Specify how to attach images (avatar and banner) to a space.
0.2.02025-09-13nc
Rewrite using pubsub semantics.
0.1.02025-03-11XEP Editor: dg
Promoted to Experimental
0.0.12025-02-23nc
Initial version.
A single group chat room is not always enough.
In various situations, one wishes to have several rooms (or even other entities) clustered together around a common
theme. For instance, large open source software projects use different rooms for user support,
development, announcements (examples: Slack's
workspaces, Discord's servers, Mattermost's teams, WhatsApp's
communities, Matrix's spaces). For the purpose of this document, let us call such group of entities under the umbrella term "spaces".
This clustering is already possible by setting up a dedicated MUC Service (Multi-User Chat (XEP-0045)XEP-0045: Multi-User Chat <https://xmpp.org/extensions/xep-0045.html>.)
to group several rooms, but existing implementations of MUC service leave that option the administrators only.
This specification proposes to use the semantics of Publish-Subscribe (XEP-0060)XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>. for spaces that:
are groupchat protocol-independent;
allow other types of entities than rooms (such as pubsub nodes);
allow several spaces on a single pubsub service;
allow entities to subscribe to updates of the space content;
can be managed by users and not only administrators of a service.
Since there are many subtle variations over the concept of spaces, this
specification voluntarily does not cover access control, permissions,
membership inside a space and its children entities. Similarly, it does not describe
how a space holding entities hosted on several services in the federated XMPP
network would work (but it does not forbid it). It aims at being a lowest common denominator
for all sort of spaces to be built on.
A space is a pubsub node (Publish-Subscribe (XEP-0060)XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>.) acting as the "parent" of several related rooms and other entities.
A spaces service is a pubsub service that contains spaces, i.e.,
it is the parent of multiple spaces.
To be effectively usable as a space, a pubsub node must be configured in the way described by the following table below. We here introduce the notion of space exposure. A space can be public, meant to be joinable by anyone; or private, meant to be joined at the discretion of the node owner.
field
requirement
value
exposure
pubsub#type
MUST
urn:xmpp:spaces:0
any
pubsub#notify_retract
MUST
true
any
pubsub#persist_items
MUST
true
any
pubsub#purge_offline
MUST
false
any
pubsub#notify_sub
SHOULD
true
any
pubsub#notify_config
SHOULD
true
any
pubsub#notify_delete
SHOULD
true
any
pubsub#publish_model
SHOULD NOT
open
any
pubsub#access_model
MUST
open
public
pubsub#access_model
MUST
authorize or whitelist
private
NB: this specification is made to be fully compatible with Publish-Subscribe (XEP-0060)XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>. without special server support. Ideally, additional functionality, yet to be described in subsequent specifications, would allow:
To notify the subscribers of a space node of new subscriptions (and not just the owner). This is especially useful for private spaces.
To ensure that a private space node is hidden from the list of nodes of a pubsub service, similar to the muc#roomconfig_publicroom configuration option for Multi-User Chat (XEP-0045)XEP-0045: Multi-User Chat <https://xmpp.org/extensions/xep-0045.html>..
In order to act as a space service, a pubsub service MUST implement and advertise in its disco#info (Service Discovery (XEP-0030)XEP-0030: Service Discovery <https://xmpp.org/extensions/xep-0030.html>.) the following features described in Publish-Subscribe (XEP-0060)XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>. (prepended by http://jabber.org/protocol/pubsub#):
subscribe
create-nodes
delete-nodes
config-node
meta-data
delete-items
retract-items
multi-items
item-ids
manage-subscriptions
retrieve-items
For better usability, it SHOULD also implement:
member-affiliation
modify-affiliations
retrieve-affiliations
get-pending
Fetching the list of spaces hosted on a spaces service is done via a
disco#items (Service Discovery (XEP-0030)XEP-0030: Service Discovery <https://xmpp.org/extensions/xep-0030.html>.) request directed at the pubsub service JID.
If supported by the server and/or if the pubsub component holds pubsub nodes that are not spaces,
PubSub Type Filtering (XEP-0462)XEP-0462: PubSub Type Filtering <https://xmpp.org/extensions/xep-0462.html>. support might come in handy.
urn:xmpp:pubsub-filter:0urn:xmpp:spaces:0
]]>
]]>
Getting more information about a specific space relies on the standard pubsub mechanism to do so, i.e., a disco#info request directed at the space node.
If the spaces service supports Pubsub Extended Discovery (XEP-0499)XEP-0499: Pubsub Extended Discovery <https://xmpp.org/extensions/xep-0499.html>. it could be used to reduce the number of roundtrips, by fetching metadata along with with the disco#items request of the previous section.
The standard pubsub#meta-data form does not specify a way to attach images to a pubsub node.
To avoid requiring special support from a pubsub server, avatar and banner image(s)
for a space can be declared as items (content) of the space pubsub node using standard Publish-Subscribe (XEP-0060)XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>. semantics.
These items MUST use the dedicated "urn:xmpp:spaces:avatar:metadata:0" and "urn:xmpp:spaces:banner:metadata:0" identifiers.
Their content is a User Avatar (XEP-0084)XEP-0084: User Avatar <https://xmpp.org/extensions/xep-0084.html>.<metadata> element specifying where to download the images and their SHA1 hash.
Implementations using HTTP File Upload (XEP-0363)XEP-0363: HTTP File Upload <https://xmpp.org/extensions/xep-0363.html>. to upload these images SHOULD use the appropriate
permanent purpose
when uploading such images.
The items MAY contain several metadata elements in case the images are available in different formats and/or resolutions.
]]>
Joining a space is equivalent to subscribing to a pubsub node, as described in Publish-Subscribe (XEP-0060)XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>..
If the pubsub service supports Pubsub Extended Subscriptions (XEP-0497)XEP-0497: Pubsub Extended Subscriptions <https://xmpp.org/extensions/xep-0497.html>., clients SHOULD also subscribe to the metadata updates of this node.
After a successful join, a client may decide to use Pubsub Subscription (XEP-0330)XEP-0330: Pubsub Subscription <https://xmpp.org/extensions/xep-0330.html>. or Pubsub Public Subscriptions (XEP-0465)XEP-0465: Pubsub Public Subscriptions <https://xmpp.org/extensions/xep-0465.html>. to advertise its subscriptions.
Discovering the children of a space uses the pubsub/items (Publish-Subscribe (XEP-0060)XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>.) query directed a the node. The items can represent different entities, wrapped in appropriate elements. Chat rooms SHOULD be wrapped in PEP Native Bookmarks (XEP-0402)XEP-0402: PEP Native Bookmarks <https://xmpp.org/extensions/xep-0402.html>., which extensibility allows adding additional information that are useful for client to adapt their user interface, e.g. specifying that a given MUC is a Multiparty Jingle (XEP-0272)XEP-0272: Multiparty Jingle <https://xmpp.org/extensions/xep-0272.html>., or that its access is restricted to a specific subset of members of the space. Pubsub nodes SHOULD be wrapped in Pubsub Subscription (XEP-0330)XEP-0330: Pubsub Subscription <https://xmpp.org/extensions/xep-0330.html>.<subscription> elements. Other types of entities can be present and MUST be ignored by unsupporting clients.
According to Publish-Subscribe (XEP-0060)XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>., all items of the space are returned, but Pubsub Node Relationships (XEP-0496)XEP-0496: Pubsub Node Relationships <https://xmpp.org/extensions/xep-0496.html>. could be used to define a more complex hierarchy of items, e.g., chat rooms restricted to the owners and not discoverable by other users.
All entities that are part of a space SHOULD advertise their parent in their disco#info and the 'urn:xmpp:spaces:0' feature. This is useful if an entity wants to advertise the "official" space it is part of, and to help discoverability of related entities. To verify that an entity is effectively part of a space it advertises, the disco#items of the advertised node can be queried.
To advertise their parent, entities SHOULD include a Data Forms (XEP-0004)XEP-0004: Data Forms <https://xmpp.org/extensions/xep-0004.html>. of type urn:xmpp:spaces:0 with a parent field of type text-single.
In the case of Multi-User Chat (XEP-0045)XEP-0045: Multi-User Chat <https://xmpp.org/extensions/xep-0045.html>., the muc#roomconfig_pubsub field SHOULD point to the space node IRI for backwards compatibility of this specification with existing MUC services implementations.