XEP-0398: User Avatar to vCard-Based Avatars Conversion

This specification describes a method for using PEP based avatars and vCard based avatars in parallel by having the user’s server do a conversion between the two.
Daniel Gultsch
© 2017 – 2024 XMPP Standards Foundation. SEE LEGAL NOTICES.


NOTICE: The protocol defined herein is a Stable Standard of the XMPP Standards Foundation. Implementations are encouraged and the protocol is appropriate for deployment in production systems, but some changes to the protocol are possible before it becomes a Final Standard.
Standards Track
1.0.0 (2024-05-06)
Document Lifecycle
  1. Experimental
  2. Proposed
  3. Stable
  4. Final

1. Introduction

User Avatar (XEP-0084) [1] and vCard-Based Avatars (XEP-0153) [2] are usually considered to stand in competition with each other. XEP-0084 even talks about superseding XEP-0153 in the future. While XEP-0084 provides a more efficient interface to upload avatars by separating metadata and data (thus saving the client from having to download its own avatar on every connect) it has the significant downside of not working with Multi-User Chat (XEP-0045) [3].

Server implementations can aid to resolve this conflict by automatically putting avatars uploaded with XEP-0084 into XEP-0153 storage and vice versa. This allows clients to use the more efficient XEP-0084 for uploading avatars and XEP-0153 to retrieve avatars in Multi-User Chats.

2. Discovery

The conversion is transparent to the uploading entity. However an entity might want to discover if a service will be performing the conversion from XEP-0084 to XEP-0153 so it doesn’t have to maintain a vCard avatar itself.

The service MUST include a Service Discovery (XEP-0030) [4] feature of "urn:xmpp:pep-vcard-conversion:0" on the account.

Example 1. Client sends service discovery request to own account
<iq from='romeo@montague.tld/garden'
  <query xmlns='http://jabber.org/protocol/disco#info'/>
Example 2. Server includes feature namespace in response
<iq from='romeo@montague.tld'
  <query  xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='urn:xmpp:pep-vcard-conversion:0'/>

3. Conversion

Modern clients are expected to use PEP (XEP-0084) as the interface to upload their avatar and use vCard (XEP-0153) only as a read only fallback. Thus a service MUST support conversion from PEP to vCard. A service MAY support conversion from vCard to PEP in order to display avatars in clients that only support XEP-0084.

3.1 From PEP to vCard

Upon receiving a publication request to the 'urn:xmpp:avatar:metadata' node the service MUST look up the corresponding item published in the 'urn:xmpp:avatar:data' node and store the content of the data element as a photo in the vcard. Services MUST consider the fact that the metadata node might contain multiple info elements and MUST pick the info element that does not point to an exernal URL. Services SHOULD verify that the SHA-1 hash of the image matches the id.

3.2 From vCard to PEP

Upon receiving a vCard publication request with a valid photo attached to it a service MUST first publish an item to the 'urn:xmpp:avatar:data' node on behalf of the requesting entity. The id of that item MUST be the SHA-1 hash of the image as described in XEP-0084. Afterwards the service MUST publish a new item to the 'urn:xmpp:avatar:metadata' node with one info element that represents the newly published image using the type value from the vCard as a type attribute in the info element.

After publication the service SHOULD send out notification messages to all subscribers of the metadata node.

4. Presence Broadcast

The “Business Rules” section of XEP-0153 tells entities to include a hash of the vCard avatar in their presence. However this requires clients to retrieve the avatar on every connect to calculate the hash. To avoid this, services MUST include the hash on behalf of their users in every available presence that does not contain an empty photo element wrapped in an x element qualified by the 'vcard-temp:x:update' namespace. Empty x elements qualified by the 'vcard-temp:x:update' namespace (those without a photo element as child) MUST be overwritten. Presences where the content of the photo element is not empty and not equal to the hash calculated by the service MAY be overwritten.

Example 3. Client sends presence to server
Example 4. Server forwards presence to other entities that have presence subscription
<presence to='juliet@capulet.tld' from='romeo@montague.tld/garden'>
  <x xmlns='vcard-temp:x:update'>
Example 5. Client sends a presence containing an empty photo element
  <x xmlns='vcard-temp:x:update'>
Example 6. The server redirects the presence but doesn’t touch the photo element
<presence to='juliet@capulet.tld' from='romeo@montague.tld/garden'>
  <x xmlns='vcard-temp:x:update'>

The hash MUST also be injected into directed presences such as MUC joins

5. Implementation Notes

5.1 Client

Implementing clients SHOULD use the more efficient XEP-0084 to access their own avatar storage and implement XEP-0153 only to download avatars from other entities if they do not have mutual presence subscription with said entity. (For example participants in a Multi-User Chat.)

Services will inject the hash in directed presences automatically but will not resend the presence if the avatar gets updated. Thus clients MAY resend directed available presence to all Multi-User Chats after receiving a 'urn:xmpp:avatar:metadata' update notification. The service will then inject an updated version of the hash. To avoid sending unnecassary presence updates, resending should only occur if the service annouces the 'urn:xmpp:pep-vcard-conversion:0' feature.

5.2 Server

While this specification is worded in a way that implies PEP and vCard are two different storages and a publication to one copies the avatar to another an alternative implementation, that also satisfies the requirements, is one that dynamically injects the PEP avatar into the vCard upon request. If this approach is taken services SHOULD check if the requestor of the vCard has access to the PEP nodes.

6. Accessibility Considerations

This specification has no accessibility considerations beyond those introduced by User Avatar (XEP-0084) [1].

7. Security Considerations

Services that copy the avatar from PEP to vCard upon publication SHOULD perform conversion only if the access model of the 'urn:xmpp:avatar:data' node has been set to 'open' as described in Publish-Subscribe (XEP-0060) [5].

Services that dynamically inject the PEP avatar into a vCard response SHOULD check if the entity that requested the vCard has access to both PEP nodes. This can be the case if the access model has been set top 'open' or if the requesting entity has a presence subscription of the owner.

8. Privacy Considerations

World readable avatars (access model open) will be made available through semi-anonymous MUCs and can be used to de-anonymize users.

9. IANA Considerations

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

10. XMPP Registrar Considerations

This specification defines the following XML namespace:

11. Acknowledgements

Special thanks to Evgeny Khramtsov who implemented what is now written down as a XEP in ejabberd and created the inspiration for this XEP.


Appendix A: Document Information

XMPP Standards Foundation
Standards Track
Last Updated
Approving Body
XMPP Council
XMPP Core, XEP-0084, XEP-0153
Superseded By
Short Name
Source Control

This document in other formats: XML  PDF

Appendix B: Author Information

Daniel Gultsch


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.

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/community/> 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-0084: User Avatar <https://xmpp.org/extensions/xep-0084.html>.

2. XEP-0153: vCard-Based Avatars <https://xmpp.org/extensions/xep-0153.html>.

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

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

5. XEP-0060: Publish-Subscribe <https://xmpp.org/extensions/xep-0060.html>.

Appendix H: Revision History

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

  1. Version 1.0.0 (2024-05-06)
    Accept as Stable as per Council Vote from 2024-04-30.
    XEP Editor (dg)
  2. Version 0.3.0 (2024-03-08)
  3. Version 0.2.1 (2018-08-27)
    Add missing article "the".
  4. Version 0.2.0 (2018-01-25)
    Accepted by vote of Council on 2018-01-10.
    XEP Editor (jwi)
  5. Version 0.1.0 (2017-12-18)
    First draft.

Appendix I: Bib(La)TeX Entry

  title = {User Avatar to vCard-Based Avatars Conversion},
  author = {Gultsch, Daniel},
  type = {XEP},
  number = {0398},
  version = {1.0.0},
  institution = {XMPP Standards Foundation},
  url = {https://xmpp.org/extensions/xep-0398.html},
  date = {2017-12-18/2024-05-06},