XEP-0463: MUC Affiliations Versioning

This specification provides a way to reduce the amount of queries necessary to stay up-to-date with affiliations in a MUC room.
  • Maxime Buquet
  • Marvin Wißfeld
© 1999 – 2021 XMPP Standards Foundation. SEE LEGAL NOTICES.


WARNING: This Standards-Track document is Experimental. Publication as an XMPP Extension Protocol does not imply approval of this proposal by the XMPP Standards Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems are advised to carefully consider whether it is appropriate to deploy implementations of this protocol before it advances to a status of Draft.
Standards Track
0.1.0 (2022-03-08)
Document Lifecycle
  1. Experimental
  2. Proposed
  3. Stable
  4. Final

1. Introduction

Affiliations are a way in Multi-User Chat (XEP-0045) [1] to handle permissions (ownership, membership, etc.). Currently, an observer gets the data in presence of online participants at the time of join, of new participants when they join, or when affiliation is changed. This observer has to send in one query per category (owner, admin, member, outcast) if they want to get a full view.

Caching this data can be tricky, as any member removed when the observer is offline is not likely to be caught until the 4 queries are run again. Having multiple queries can also produce race conditions where an occupant is moved out of a group (e.g., owners) to another group (e.g., members) while an observer queries, and they end up not seeing this occupant at all, or twice, or not in the correct group.

Affiliations have become more and more used lately, for example in so-called private groupchats, that is, a non-public, non-anonymous (visible JIDs), members-only room. Having to run all queries is particularly annoying in these private rooms where some implementations prefer to display all participants instead of online participants only, and where the affiliations list is used to know whom to encrypt to in an e2ee context.

This specification sets a versioning mechanism in place, allowing an observer in a room to get the latest changes from a known version, and to reduce the amount of round-trips to handle affiliations.

2. Requirements

3. Glossary

Full response
A response including the complete affiliation list.
Boostrap request
A request asking for a full reponse.

4. Discovering Support

A server implementing this specification MUST advertise the urn:xmpp:muc:affiliations:0 as a Service Discovery (XEP-0030) [2] feature on the Multi-User Chat (XEP-0045) [1] room JID itself.

5. Usage Flow

5.1 Client request

When sending a join presence to a Multi-User Chat (XEP-0045) [1] room, a client may include a since attribute in the urn:xmpp:muc:affiliations:0 namespace on the <x xmlns='http://jabber.org/protocol/muc'> element. This attribute, a unique and opaque string, indicates the last affiliation version sent by the server that the client has seen, and cached. Sending an empty since attribute is a called bootstrap request, which asks the server for a full response.

This since attribute MUST NOT be broadcasted by the server to other participants. A room not stripping the attribute may disclose information about an occupant to other participants, even though this information is not intended for them.

Example 1. Bootstrap request to get the full list.
<presence to='news@chat.commons.example' from='louise@commons.example/desktop'>
  <x xmlns='http://jabber.org/protocol/muc'
     mav:since='' />
Example 2. Request since specific version.
<presence to='news@chat.commons.example' from='rosa@commons.example/toaster'>
  <x xmlns='http://jabber.org/protocol/muc'
     mav:since='9pacabr2q1' />

5.2 Server Response

5.2.1 On Join

Returning the list of affiliation changes is done as a <message/> stanza inside the <x xmlns='http://jabber.org/protocol/muc#user'> element to which since and/or until attributes of namespace urn:xmpp:muc:affiliations:0 MAY be added. Each affiliation is to be sent as an <item> element in the same namespace as its x parent, and MUST at least contain a jid attribute and an affiliation attribute, similarly to what is specified in MUC Affiliations.

The since attribute is used to reflect the version sent by the client and is the starting point of the diff that will be computed. The until attribute is the latest version the server has. When these attributes are present they MUST contain a valid version string (unique and opaque).

The reponse MUST be sent during the join process before any <presence/> is sent to the joining user.

If a client sends a version that the server doesn't know, (e.g., because it only stores the last N versions, or the client made a mistake), the response MUST be a full response, with the since attribute not present, and the until attribute filled with the latest version.

If both attributes have the same value, meaning a client already has the latest version, the x element MUST be empty, only containing the two filled attributes.

There can be no empty diff but there can be empty full reponses (no affiliations).

Example 3. Room full response for a version that it didn't know.
<message from='news@chat.commons.example'
  <x xmlns='http://jabber.org/protocol/muc#user'
    <item jid='louise@commons.example' affiliation='owner' />
    <item jid='peter@commons.example' affiliation='owner' />
    <item jid='rosa@commons.example' affiliation='owner' />
Example 4. Room versioned response.
<message from='news@chat.commons.example'
  <x xmlns='http://jabber.org/protocol/muc#user'
    <item jid='vladimir@commons.example' affiliation='none' />
    <item jid='rosa@commons.example' affiliation='owner' />
Example 5. Room full response with no affiliation
<message from='news@chat.commons.example'
  <x xmlns='http://jabber.org/protocol/muc#user'

5.2.2 Affiliation Changes

A new unique (to the room) version string MUST be generated for every affiliation change and included in the broadcast of this change.

When broadcasting an affiliation change (as a <presence/> or <message/>), on the <x xmlns='http://jabber.org/protocol/muc#user'>, a MUC room MUST add the since attribute in the urn:xmpp:muc:affiliations:0 namespace, containing the original version string (before the affiliation change), and the new version string (after the affiliation change) in the until attribute (of the same namespace).

Affiliation changes broadcasted to room occupants as <message/> defined as a MAY in Multi-User Chat (XEP-0045) [1], for example in Granting Owner Status, Granting Admin Status, or Revoking Admin Status, MUST be supported by the MUC room when implementing this specification.

Example 6. Room broadcasts an affiliation change for a user not in the room.
<message from='news@chat.commons.example'
  <x xmlns='http://jabber.org/protocol/muc#user'
    <item jid='peter@commons.example/mobile' affiliation='none' role='none'/>

5.2.3 Error Cases

Permissions are handled as with affiliation iq queries in Multi-User Chat (XEP-0045) [1], the same rules should be applied by the server when deciding who can use this protocol.

Some notes regarding permissions can be find in Multi-User Chat (XEP-0045) [1], for example in Affiliations, or Modifying the member list.

An auth forbidden error MUST be returned in a <message/> stanza if an observer doesn't have the necessary permissions to request affiliations.

Example 7. This observer isn't allowed to query affiliations in the room
<message from='news@chat.commons.example'
         id='foo' type='error'>
  <error by='news@chat.commons.example' type='auth'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>

6. Security Considerations

An observer has to join the MUC room to use the protocol as the since element must be included in the join presence. This makes this specification less prone to vulnerabilities that may have happened with protocols such as MAM in the past (i.e., scraping information without being joined).

A server should be careful not to disclose past affiliation states. If an observer requests a version of which they weren't a part of, a server MUST return an error as specified in Error Cases.

When caching server responses, a client should make sure to associate the received version string to the room JID and not have a global cache for affiliation versions to prevent any cache poisoning issues.

7. IANA Considerations

This document requires no interaction with the the Internet Assigned Numbers Authority (IANA) [3].

8. XMPP Registrar Considerations

The XMPP Registrar includes the urn:xmpp:muc:affiliations:0 namespace in its registry of protocol namespaces at https://xmpp.org/registrar/namespaces.html.

9. Design Considerations

This specification is based on the design of roster versioning, with the difference of since and until attributes, to ensure clients stay in sync because unlike roster versioning this may be running over c2s, and s2s which may break.

The <x xmlns='http://jabber.org/protocol/muc[#user]/> elements are not defined extensible in the Multi-User Chat (XEP-0045) [1] specification, but as this is a negociated change there shouldn't be any issue.

TODO? RSM. Pagination may have been useful for large rooms, when receiving a full response. Versioning will reduce the amount of bandwidth used for further queries though.

10. XML Schema

<?xml version='1.0' encoding='UTF-8'?>


      The protocol documented by this schema is defined
      in XEP-xxxx: https://xmpp.org/extensions/xep-xxxx.html.

  <!-- TODO: How do I schematize standalone attributes? -->

11. Acknowledgements

Thanks to Emmanuel Gil Peyrot and Matthew Wild for the valuable feedback.


Appendix A: Document Information

XMPP Standards Foundation
Standards Track
Last Updated
Approving Body
XMPP Council
XEP-0030, XEP-0045
Superseded By
Short Name
Source Control

This document in other formats: XML  PDF

Appendix B: Author Information

Maxime Buquet
Marvin Wißfeld


This XMPP Extension Protocol is copyright © 1999 – 2020 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.

Disclaimer of Warranty

## 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. ##

Limitation of Liability

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.

IPR Conformance

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).

Visual Presentation

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.

Appendix D: Relation to XMPP

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.

Appendix E: Discussion Venue

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/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

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".

Appendix G: Notes

1. XEP-0045: Multi-User Chat <https://xmpp.org/extensions/xep-0045.html>.

2. XEP-0030: Service Discovery <https://xmpp.org/extensions/xep-0030.html>.

3. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

Appendix H: Revision History

Note: Older versions of this specification might be available at https://xmpp.org/extensions/attic/

  1. Version 0.1.0 (2022-03-08)
    Accepted by vote of Council on 2022-02-16.
    XEP Editor (jsc)
  2. Version 0.0.1 (2022-02-12)

    First draft.


Appendix I: Bib(La)TeX Entry

  title = {MUC Affiliations Versioning},
  author = {Buquet, Maxime and Wißfeld, Marvin},
  type = {XEP},
  number = {0463},
  version = {0.1.0},
  institution = {XMPP Standards Foundation},
  url = {https://xmpp.org/extensions/xep-0463.html},
  date = {2022-02-12/2022-03-08},