XEP-0038: Icon Styles

A protocol for specifying exchangeable styles of emoticons and genicons within Jabber IM clients.
Adam Theo
© 2002 – 2022 XMPP Standards Foundation. SEE LEGAL NOTICES.


WARNING: This document has been obsoleted by the XMPP Standards Foundation. Implementation of the protocol described herein is not recommended. Developers desiring similar functionality are advised to implement the protocol that supersedes this one (Unicode, XEP-0231).
Superseded By
Unicode, XEP-0231
Standards Track
0.5.1 (2022-03-08)
Document Lifecycle
  1. Experimental
  2. Proposed
  3. Stable
  4. Final
  5. Deprecated
  6. Obsolete

1. Introduction

This proposal standardizes the use of graphical emoticons and "genicons" in Jabber IM clients to prevent confusion and competing conventions that will soon arise, enabling client developers to spend their energy on more important parts of their projects.

Emoticons are the text string 'smiley' or 'frowny' faces such as :-) and :-( that people often use in email or instant messaging to represent emotions. Genicons are a term being coined here to mean non-emotive text pictures (often called 'ASCII Art') that serve to replace typing the full word or to simply be cute or creative in the conversation.

Many new Internet users demand graphical emoticon and genicon support in their IM clients. We should satisfy their needs if we ever wish to see them use Jabber instead of another IM system.

While traditionally emoticons and genicons have been typed and displayed as text, the recent trend of using graphics, and sometimes sounds, instead of text to represent these pictures will be assumed for purposes of this proposal. Also, the term "icon" will be used in place of "emoticon" and "genicon" for purposes of convenience.

2. Requirements

The following issues must be solved for in this specification.

Because icons in Jabber should be easy to use, extensible, and customizable, they will be created using style definition files which can be exchanged between users and supporting clients. The specification will not allow external data, in order to protect the privacy of users, and will not rely on file transfers or directory services in order to not break old clients or components.

3. Discovery

To find out if an entity supports Jabber Icon Styles, look for the feature category of http://jabber.org/protocol/icon-styles using jabber:iq:browse or http://jabber.org/protocol/disco. The same feature category can be used with feature negotiation.

4. Specification

Because icons in Jabber should be easy to use, extensible, and customizable, they will be created using style definition files which can be exchanged between users and supporting clients. The specification will not require external data, in order to protect the privacy of users, and will not rely on file transfers or directory services in order to not break old clients or components. How these icon styles are exchanged - as well as advertised - is out of the scope of this specification. The text strings representing the icons will be sent like any other text (this document doesn't require extra tags or attributes in the messages being sent).

All icons are created by defining each icon then grouping them together into "Icon Definition Files". These files, along with the object files associated with the icons, are called "icon styles". Icon styles may be traded and shared among users of all supporting clients like skins or themes, similar to WinAmp, XMMS, GNOME, and other customizable applications. This creates a platform-independent system, providing a great degree of customization for the user, and allowing client developers to focus on other features.

4.1 Definition File

Each icon in a style is defined and grouped together in an XML document, the "Icon Definition File". Each definition file for all styles is named "icondef.xml". There is only one such Icon Definition File per style. The W3C Schema for the Icon Definition File plus an example finished Icon Definition File can be found under Schema, below.

4.2 Meta Elements

The meta elements contain information about the Icon Style itself, rather that the individual icons. They are contained within the <meta> element, which is directly under the root element. There is one and only one the <meta> element.

4.3 Text Strings

The <text/> element defines what text string(s) are recognized by the client as an icon. There may be multiple <text/> elements in an <icon/>, such as for different languages or simply for multiple text strings producing the same result (for example: :-) and :))

4.3.1 Internationalization

Each may have an xml:lang attribute, as defined in Section 2.12 in the official XML 1.0 reference document. The xml:lang attribute allows for two-letter language codes, dialects, and custom "languages" to define foreign IM protocols, for example.

4.3.2 Whitespace

In order to be more accurate in recognizing text strings intended to be icons from those that are just coincidences in normal conversation, the client should follow the "whitespace rule" of making sure there is some form of whitespace on at least one side of the text string. This is only a guideline; individual clients can implement different rules as needed. A newline and tabs count as whitespace in addition to spaces. This is to make sure that chunks of code and URIs are not accidentally converted into graphical pictures. Also, text strings cannot include newlines or tabs. All characters must be on the same line with only spaces within the string, and extra spaces should not be ignored. This is to make it much easier on text parsers looking for these text strings.

4.3.3 Case Sensitivity

The text strings must be case sensitive. This is a rule that compliant clients must follow. "Cat" cannot be used in place of "cat" or "CAT". All three are separate text strings, and therefore must have separate <text/> elements, although they may of course use the same objects.

4.4 Objects

The <object/> element defines what multimedia objects are inserted into the displayed message, replacing the text string(s) defined in <text/>. An object may be a bitmap graphic, vector graphic, audio clip, rich text formatting rules, or any other media that can be stored in a separate file. The <object/> element is identical to the OBJECT element used in XHTML 2.0, and the specification used there should be used to govern the <object/> element here. Note that because the XHTML 2.0 OBJECT specification is quite complex (although very flexible and future-proof), client developers are encouraged to only implement compliant sub-sets of the OBJECT specification for their clients. There may be one or multiple <object/> elements in an <icon/>, such as for alternative file formats (such as GIF vs. PNG), or multiple objects to use at the same time (such as graphic and sound files).

4.5 X Tags

The <x/> element allows any type of extensions to the icondef.xml file, such as to specify how the user's nickname can be colored in multi-user chat windows or defining additional data about the style or authors. Each must have an xmlns attribute with a namespace that the extension operates under. Multiple <x/> elements may be in the <icon/> or <icondef/> elements. This functionality is optional for clients to support, and clients should ignore all extensions they do not understand.

4.6 Hierarchy

The icondef.xml file must all be located in the root directory, which is named after the style and version (example: ./happy_days-1.2 or ./gold_angelic-1.0.0). There is only one root directory per style. The object files may either be in the root directory as well, or be in sub-directories for categorization and easier maintenance reasons. If sub-directories are used, they must match the URIs used in the <object/> element in the icondef.xml file.

Example 1. Gold Angelic v1.0.0 Hierarchy Example

4.7 Packaging

The icondef.xml file and all object files must be packaged in the ZIP format following the above hierarchy (the directory must exist in the package, with all files in it). The package must have the file extension .jisp (Jabber Icon Style Package), and the MIME type application/vnd.jisp as defined in the official IANA registration. This allows Jabber clients to automatically install icon styles through web browsers. When the client installs the package, it should probably be kept in the archived format, instead of unzipped. This not only saves disk space, but also makes the packages easier to manage and exchange.

5. Implementation Notes

Icons styles should be easy to create, distribute, and most importantly, use. The packaging and official MIME type helps with the first steps, but it is ultimately up to the client developers to fully support the specification and make sure it is easy for users to manage.

5.1 Procedure

The procedure for using Jabber icons is simple and straightforward.

  1. The user installs and turns on ("activates") an icon style (using their client's GUI, most likely) they have received off the Internet or somewhere else.
  2. The user selects the desired icon they wish to include in their message from their client's GUI (a drop-down list of installed icons, for example).
  3. The client translates the selected icon into its main text string equivelent, which is found in the icon's <text> element. If there are multiple <text> elements, follow the procedure under "Text Strings", below.
  4. The client sends the message with the text string to the intended recipient.
  5. The recipient client receives the message with the text string.
  6. If the recipient has an icon style activated that defines that text string, it is converted into the appropriate object. If there are multiple objects files for each icon, follow the procedure under "Object Files", below. If there are multiple icon styles installed which define that text string, follow the procedure under "Combining Styles", below. If the recipient does not have such an icon activated, then they simply see the text string without any changes.

5.2 Text Strings

Because icons may have multiple text strings associated with them, clients need to be able to figure out which one to use when a user selects the desired icon from their GUI. This is ultimately completely up to the implementation, but here is a suggestion:

  1. First look for any text strings that are the same language as what the user is using (if the user is using english, then look for English text strings, ignoring languages like German or Simplified Chinese). Optionally, if the client is smart enough, it can instead look for text strings in the language that the intended recipient is using (using Browse/Disco or simply keeping track of languages used in an ongoing conversation). The language for text strings is found in the xml:lang attribute for <text/> elements.
  2. If there are no text strings that match the user's language, then look for one that has no defined language.
  3. If there are multiple options even after the above steps, select the one that comes first in the <icon/> element.
  4. If there are no text strings that are in the user's language or no language defined at all, then it is probably best for the client to not even display the icon as a choice at all. But if the client still wants to allow it, then simply select the text string of any language that comes first in the <icon/> element.

5.3 Objects

Like multiple text strings, icons can have multiple object data files associated with them, and therefore clients also need to be able to figure out which ones to use when a user selects the desired icon from their GUI. Here is a suggestion of how those files can be chosen among multiple options, although this is completely an implementation issue (as with multiple text strings).

  1. First look for any of these objects that are of MIME types the client can understand and use. For example, most clients could only use image/bmp and maybe audio/x-wav, but some newer clients may be able to support image/png, image/svg+xml and audio/x-ogg.
  2. If there are still multiple object MIME types which the client can understand and use, then the client should rank the MIME types it can support, choosing its favorite.
  3. If there are still multiple objects of the same MIME type, then the client should choose the first one in order in the <icon/> element.
  4. If there are no files of any MIME type the client can understand, then it should ignore using any objects or even the entire icon.

The Rules for processing objects in the XHTML 2.0 OBJECT specification may also be of help in coding the procedure of choosing an object to use, especially when it comes to nested and author-preferred objects.

The client should also take note of the file sizes. The client should set (possibly as a user-defined option) the maximum file size in kilobytes for object files. Anything above this amount implies the file will be too big to properly render, and the icon style developer is probably being abusive.

Also, if you are developing an icon style, please make sure the MIME types specified in your icondef.xml file are correct. And also make sure that the files you use are reasonable in any byte, pixel, and timelength size. And although any file format can be supported, try to use BMP, PNG, SVG, WAV, OGG formats because they are open, free, and becoming increasingly supported in developer tools and programming languages.

5.4 Combining Styles

A client may permit the user to activate multiple icon styles at one time. This would be useful for styles which make use of different text strings, and the user wants them all. The client should force the user to rank the multiple styles for purposes of conflict resolution between icons. The highest ranking style gets preference over lower ranking styles. This ranking doesn't have to be anything more than simply dragging the style names into top-to-bottom rows, with the styles on top being higher ranked than those below.

5.5 Core Icons

Although any text string can be turned into an icon by defining it in an icondef.xml file, it is highly reccomended they either follow traditional ASCII Art (smileys and frownys, for example) or full keywords in simple markup such as double-colons. If you want to design icons, always keep in mind that not every Jabber user uses graphics to "translate" this to something visual, as explained in the "Meaningful" requirement, above. Here is a short list of recommended "core" icons that should be in most definitions, as well as possibly be used by transports:

6. Security Considerations

There are no security features or concerns related to this proposal.

7. IANA Considerations

The XMPP Standards Foundation (XSF) [1] shall register and maintain a MIME type and file extension for icon style packages with the IANA. Ones have already been registered by Sebastiaan Deckers (aka 'CBAS') as application/vnd.jisp and .jisp, respectively. The registration can be found at http://www.iana.org/assignments/media-types/application/vnd.jisp. Sebastiaan's registration shall be considered the official MIME type and file extension of this specification.

Also, this specification uses other MIME types that are maintained by IANA for the object and xml files that are included in the icon style packages.

8. XMPP Registrar Considerations

JANA shall register the namespace http://jabber.org/protocol/icon-styles as an official feature category.

Also, JANA may choose to define IM-specific xml:lang "language codes" for use within Jabber (in addition to those defined in the XML specification). Such language codes would allow Jabber developers to support icons from MSN, Yahoo, and popular web message programs.

9. Formal Definition

9.1 Schema

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

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="icondef">
            <xs:element name="name" type="xs:string"/>
            <xs:element name="version" type="xs:string"/>
            <xs:element name="description" type="xs:string"/>
            <xs:element name="author" type="xs:string" maxOccurs="unbounded">
                <xs:attribute name="jid" type="xs:string" use="optional"/>
            <xs:element name="creation" type="xs:date"/>
        <xs:element name="icon" minOccurs="1" maxOccurs="unbounded">
              <xs:element name="text" type="xs:string" minOccurs="1" maxOccurs="unbounded">
                  <xs:attribute name="xml:lang" type="xs:language" use="optional"/>
              <xs:element name="object" type="xs:string" minOccurs="1" maxOccurs="unbounded">
                  <xs:attribute name="mime" type="xs:string" use="required"/>
              <xs:element name="x" type="xs:string" minOccurs="0" maxOccurs="unbounded">
                  <xs:attribute name="xmlns" type="xs:anyURI" use="required"/>
        <xs:element name="x" type="xs:string" minOccurs="0" maxOccurs="unbounded">
            <xs:attribute name="xmlns" type="xs:anyURI" use="required"/>

9.2 icondef.xml file example

<?xml version='1.0' encoding='UTF-8'?>
    <name>Gold Angelic</name>
    <description>Angelic faces and themes with gold highlights.</description>
    <author jid="theo@theoretic.com">Adam Theo</author>
    <author jid="cbas@rhymbox.com">Sebastiaan Deckers</author>
    <author jid="cobnet@jabber.org">Mattias Campe</author>
    <object mime="image/png">happy.png</object>
    <object mime="audio/x-wav">choir.wav</object>
    <object mime="image/png">sad.png</object>
    <object mime="audio/x-wav">boohoo.wav</object>
    <object mime="image/svg+xml">shocked.svg</object>
    <text xml:lang="en">::man::</text>
    <text xml:lang="de">::mann::</text>
    <text xml:lang="cs">::muz::</text>
    <text xml:lang="x-msn">(z)</text>
    <object mime="image/png">man.png</object>
    <text xml:lang="en">::woman::</text>
    <text xml:lang="x-msn">(x)</text>
    <object mime="image/svg+xml">woman.svg</object>
    <object mime="image/png">woman.png</object>
    <text xml:lang="en">::alert::</text>
    <object mime="image/svg+xml">red-exclamation-mark.svg</object>
    <object mime="audio/x-ogg">alert.ogg</object>
    <object mime="audio/x-wav">alert.wav</object>

10. Future Considerations

  1. This proposes a standard, simple, plaintext-based icon convention. It does not attempt to create a powerful XML-based convention wherein XML tags are used to extensibly represent the icons. However, this proposal isn't exclusive, and does not prevent such an XML-based convention from being created at a later date. It may also be possible to build such an extensible XML-based convention on top of this plaintext one.
  2. The Icon Styles that the sender used to create the message may be of use to the recipient. A separate specification can be developed for the transferring of the name and version of the Icon Styles used by the sender. The recipient's client may then be smart enough to automatically use the same icons as the sender intended, possibly even fetching and downloading the icon styles as needed. This would likely require directory services, so has not been included in this proposal.
  3. The functionality of the icondef.xml files may be useful for variable text strings. Text strings that may change from session to session, such as the user's nickname in a multi-user chat. A set of variables could be defined that represent these variable datas, therefore allowing them to be manipulated in the same way set text strings are.
  4. This convention may be adopted beyond the scope of Jabber into web browsers, email clients, and Wiki sites. There is great potential for a generalized, exchangeable convention for emoticons and genicons.
  5. A "SVG Transport" may be created to enable clients to send SVG icons to it and get back icons in another format of their choice, such as PNG or JPG. This would speed up the adoption of SVG within Jabber greatly.
  6. An online Web- (or even Jabber-) based editor to create icon style packages from the individual components would be a great tool for developers. This would be a great project for JabberStudio or even the Ransom model.


Appendix A: Document Information

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

This document in other formats: XML  PDF

Appendix B: Author Information

Adam Theo


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. The XMPP Standards Foundation (XSF) is an independent, non-profit membership organization that develops open extensions to the IETF's Extensible Messaging and Presence Protocol (XMPP). For further information, see <https://xmpp.org/about/xmpp-standards-foundation>.

Appendix H: Revision History

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

  1. Version 0.5.1 (2022-03-08)

    Obsolete due to the omnipresence of Unicode emoji, as well as Bits of Binary stickers.

  2. Version 0.5 (2003-06-02)
    Bent to public will on using a common object element and enveloping all meta information into a meta element.
  3. Version 0.4 (2003-03-05)
    Added "format" back in. Refused to simplify to use "object" for everything. Fixed some typos.
  4. Version 0.3 (2002-11-05)
    Simplified, even though it loses some flexibility. Should be the final version.
  5. Version 0.2 (2002-07-24)
    Added feedback, still needs serious Schema work
  6. Version 0.1 (2002-06-28)
    Initial version

Appendix I: Bib(La)TeX Entry

  title = {Icon Styles},
  author = {Theo, Adam},
  type = {XEP},
  number = {0038},
  version = {0.5.1},
  institution = {XMPP Standards Foundation},
  url = {https://xmpp.org/extensions/xep-0038.html},
  date = {2002-06-28/2022-03-08},