If you want to post ideas or comments, do so down below.

Unified Logging Format: The "Official" Spec, v0.4


  • 0.4.2 - 02/14/2007 - The standards process for ULF seems mostly dead. Bringing this document into line with Adium's implementation.
  • 0.4 - 06/03/2006 - Adding the optional transport attribute to <chat />
  • 0.3.1 - 05/29/2006 - Switching back to per-conversation logging.
  • 0.3 - 12/08/2005 - Switched to a one-log-a-day plan, changed the timestamps to the ISO date format, added the event tag, and made status tags optionally self closing. Also fixed some typos and reworded some sections, and updated the unresolved issues section.
  • 0.2 - 11/30/2005 - Removed the type attribute for messages, and fixed a typo in the sample code
  • 0.1 - 11/28/2005 - Initial release

Mailing List

There is a mailing list for this format located here:


Adium is switching to a new log (chat transcript) format, based on XML. XML is a standardized document format created by the W3C, an internet standard body. The following snippet gives an overview of what sample conversation in this new format looks like. N.B. The time tags are not filled in to increase readability. The format looks like: 2006-07-14T12:42:01-05:00

<chat account="mactigerz" service="AIM" version="0.4">
    <event type="windowOpened" time=""/>
    <message sender="chz16" time="">'sup?</message>
    <message sender="mactigerz" time="">trying to get to work on the the new XML log format</message>
    <message sender="chz16" time="">Doesn't sound bad.</message>
    <message sender="chz16" time="">Providing you have the log specs, of course.</message>
    <message sender="mactigerz" time="">that's what I'm creating.</message>
    <status type="offline" sender="chz16" time=""/>
    <status type="online" sender="chz16" time=""/>
    <status type="away" sender="mactigerz" time="">brb, working on the XML log format</status>
    <event type="windowClosed" time=""/>

The elements shown above are described in detail below:

The chat element


Each log file has one (and only one) chat element. It is the root element of log files.


  • account: The unformatted ID account with which the following messages were sent.
  • service: The service identifier of the account used to send the messages.
  • version: The version of this document you are adhering to. The current version is 0.4.
OPTIONAL Attributes
  • transport: This attribute MAY only exist if service="XMPP" and serves as a helpful hint to the logreader about metacontact information. This helps the logreader identify when a single person on AIM/MSN/YIM/etc can be contacted using their corresponding protocols or by a use of an XMPP transport. For example, if the AIM user AIMUser2 is contacted by the Jabber user, a transport="AIM" can be saved into the logfile.

The message element


The data contained in this element represents a message, either sent or received. May contain XHTML elements.


  • sender: The unformatted UID of the contact who sent you the message. This will be the same as the chat element's account attribute for messages sent by the user.
  • time: The time, in ISO format, when this message was sent (or received).

The status element


This element represents a change in status, either by the user or one of the participants in the chat. The data enclosed in the element represents any text associated with the status -- e.g. the text of a users away message, or a user's quit message when leaving a group chat. If there is no relevant data, the element may be self-closing.


  • type: This type corresponds, roughly, to the status types in Adium. Common values are: online, offline, away and available.
  • sender: The unformatted ID of the contact whose status changed. This will be the same as the chat element's account attribute for status changes of the user. Similar to the same attribute on the message element.
  • time: The time, in ISO format, when this status change occurred.

The event element


This element represents an event that is not related to status. For example, windows opening and closing, file transfers, authorization requests, etc. This element may be self-closing.


  • type: This type corresponds, roughly, to the event types in Adium. Common values are: windowOpened and windowClosed.
  • sender: The unformatted ID of the contact who generated the event. This will be the same as the chat element's account attribute for events generated by the user. Similar to the same attribute on the message element.
  • time: The time, in ISO format, when this event occurred.


  • The XML has been designed in such a way as to easily facilitate styling with raw CSS. CSS2 provides the ability to define styles based on attributes. Here is an example:
    status[type=online] { color: blue; }
    status[type=offline] { color: red; }
  • When styling the XML with CSS, it may be useful to have an easy way of telling which messages the user sent. Below is a JavaScript code snippet to demonstrate a way to add a specific class to an element which has a sender identical to the account given in the chat element.
    function addMeClass() {
        //Documents should only have one chat element
        chat = document.getElementsByTagName("chat")[0];
        //Store the account for later use
        account = chat.getAttribute("account");
        //We want to check *all* possible nodes of this chat
        nodes = chat.childNodes;
        for (int i = 0; i < nodes.length; i++) {
            node = nodes[i];
            //If the sender attribute of this node is the same as the account name
            if (node.hasAttribute("sender") && node.getAttribute("sender") == account) {
                //We append and put a space before "me"
                //to take advantage of CSS's little known feature
                //whereby elements may have multiple, space separated classes
                node.className += " me";

Unresolved Issues

To do

The ULF spec probably has a pretty good list, but we should be mapping Adium's values, here

  • Build a complete list of the values for status[type].
    • online
    • offline
    • away
    • idle
    • etc..
  • Build a complete list of the values for event[type].
    • windowOpened
    • windowClosed
    • fileTransferRequested
    • fileTransferAccepted
    • fileTransferCompleted
    • authorizationRequested
    • authorizationGranted
    • authorizationDenied
    • etc..


  • Use something similar to the include-pattern used in microformats for contact markup?
  • Figure the impact of putting ulf in its own namespace, e.g. <ulf:chat/>.

Comments and Questions

Post your comments and questions here. Be sure to identify yourself, the date, and what version of the spec you are referring to. New comments should go above older ones.

The include pattern mentioned above would look something like this:

<chat service="AIM">
  <participant id="notabigtruck" formattedid="not a big truck" alias="Colin Barrett"/>
  <participant id="catfishman42" formattedid="CatfishMan42" alias="David Smith"/>
  <message sender="#notabigtruck" time="">hi</message>
  <message sender="#catfishman42" time="">lo</message>

I'm using the id attribute, because then sender takes a URI.

Unresolved issues with it:

  • when a information in the participant tag changes, a new one will be written. How, if at all, should these be uniquely identified?

~cbarrett, 2007-02-14, version 0.4.2

I've been thinking about the changes that would be needed to synchronize logs with XEP-0313 (as far as I know the only protocol we support with (although yet Experimental) in-band log syncing).

  1. The XEP only covers normal chats, not group chats. Logs currently don't store anywhere whether they were for group chats or 1-1 chats, although this could be deduced in many cases (people joining, the name of the file), it would be prettier to store it somewhere (on the chat element?). Already reported: #12352, has a patch.
  2. The server generates an UID for every message when it stores it, and to be able to synchronize messages this UID needs to be stored with the message. While incoming messages might include their UID, an outgoing message's UID will not be immediately known (how it can be obtained is still being discussed:

xnyhps, 2012-05-25, version 0.4.2

Page last modified by sphynx, 4 years ago