XEP-0145: Annotations

This document defines an XML data format for making annotations about XMPP roster items and other entities.


NOTICE: This document is currently within Last Call or under consideration by the XMPP Council for advancement to the next stage in the XSF standards process.


Document Information

Series: XEP
Number: 0145
Publisher: XMPP Standards Foundation
Status: Proposed
Type: Standards Track
Version: 1.1pre3
Last Updated: in progress, last updated 2007-09-27
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0060, XEP-0223
Supersedes: None
Superseded By: None
Short Name: rosternotes
Schema: <http://www.xmpp.org/schemas/rosternotes.xsd>
Wiki Page: <http://wiki.jabber.org/index.php/Annotations (XEP-0145)>

Author Information

Stefan Strigler

Email: steve@zeank.in-berlin.de
JabberID: zeank@jwchat.org

Peter Saint-Andre

JabberID: stpeter@jabber.org
URI: https://stpeter.im/

Legal Notice

This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy <http://www.xmpp.org/extensions/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) 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.

Conformance Terms

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


Table of Contents


1. Introduction
2. Data Format
3. Storage Methods
    3.1. Uploading Data
    3.2. Receiving Notifications
    3.3. Retrieving Data
4. Security Considerations
5. IANA Considerations
6. XMPP Registrar Considerations
7. XML Schema
Notes
Revision History


1. Introduction

Many modern IM clients offer functionality that enables a user to make notes about the contacts in their roster. This is helpful if such contacts do not have meaningful information in their vCard or if the user needs to remember additional information related to a roster item. To define such functionality, we specify a <storage> element (similar to that introduced in Bookmark Storage [1]) and appropriate child elements, qualified by a new namespace of 'storage:rosternotes'. While the <storage/> element can be stored using any XML storage mechanism, this document describes two such methods that are specific to XMPP.

2. Data Format

Annotations are stored using a <storage/> element qualified by the 'storage:rosternotes' namespace. This element contains a collection of one or more <note/> elements, each representing a note about a given entity. For any given JID there MUST NOT be more than one note.

The 'jid' attribute of the <note/> element SHOULD be used without a resource, i.e., it SHOULD be a bare JID (<node@domain.tld>) rather than a full JID (<node@domain.tld/resource>). Along with the annotation a client MAY choose to store the creation time ('cdate') and modification time ('mdate') as attributes to the <note/> element containing the annotation; these attributes MUST conform to the DateTime profile specified in XMPP Date and Time Profiles [2] and the timezone SHOULD be UTC.

Example 1. Some annotations

    <storage xmlns='storage:rosternotes'>
      <note jid='hamlet@shakespeare.lit'
            cdate='2004-09-24T15:23:21Z'
            mdate='2004-09-24T15:23:21Z'>Seems to be a good writer</note>
      <note jid='juliet@capulet.com'
            cdate='2004-09-27T17:23:14Z'
            mdate='2004-09-28T12:43:12Z'>Oh my sweetest love ...</note>
    </storage>
  

Note: All notes are stored as a "bundle" within the same <storage/> element.

3. Storage Methods

It is RECOMMENDED to use Publish-Subscribe [3] for data storage, specifically through the use of personal data nodes hosted at the user's virtual publish-subscribe service as described in Personal Information via Pubsub [4] and illustrated in the following sections.

Note: In the past, Private XML Storage [5] was the recommended method (see the archived version of this specification at <http://www.xmpp.org/extensions/attic/xep-0048-1.0.html>). In addition, other methods could be used, such as HTTP or WebDAV.

3.1 Uploading Data

Example 2. Client uploads data

<iq from='juliet@capulet.lit/balcony' type='set' id='pip1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='storage:rosternotes'>
      <item id='current'>
        <storage xmlns='storage:rosternotes'>
        <note jid='hamlet@shakespeare.lit'
              cdate='2004-09-24T15:23:21Z'
              mdate='2004-09-24T15:23:21Z'>Seems to be a good writer</note>
        <note jid='juliet@capulet.com'
              cdate='2004-09-27T17:23:14Z'
              mdate='2004-09-28T12:43:12Z'>Oh my sweetest love ...</note>
        </storage>
      </item>
    </publish>
    <publish-options>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#publish-options</value>
        </field>
        <field var='pubsub#persist_items'>
          <value>true</value>
        </field>
        <field var='pubsub#access_model'>
          <value>whitelist</value>
        </field>
      </x>
    </publish-options>
  </pubsub>
</iq>
    

Example 3. Server acknowledges successful storage

q to='juliet@capulet.lit/balcony' type='result' id='pip1'/>
    

3.2 Receiving Notifications

The stored data is automatically pushed to all of the user's connected resources.

Example 4. Publisher receives event notification

<message from='juliet@capulet.lit'
         to='juliet@capulet.lit/balcony'
         type='headline'
         id='rnfoo1'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='storage:rosternotes'>
      <item id='current'>
        <storage xmlns='storage:rosternotes'>
        <note jid='hamlet@shakespeare.lit'
              cdate='2004-09-24T15:23:21Z'
              mdate='2004-09-24T15:23:21Z'>Seems to be a good writer</note>
        <note jid='juliet@capulet.com'
              cdate='2004-09-27T17:23:14Z'
              mdate='2004-09-28T12:43:12Z'>Oh my sweetest love ...</note>
        </storage>
      </item>
    </items>
  </event>
</message>

<message from='juliet@capulet.lit'
         to='juliet@capulet.lit/chamber'
         type='headline'
         id='rnfoo2'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='storage:rosternotes'>
      <item id='current'>
        <storage xmlns='storage:rosternotes'>
        <note jid='hamlet@shakespeare.lit'
              cdate='2004-09-24T15:23:21Z'
              mdate='2004-09-24T15:23:21Z'>Seems to be a good writer</note>
        <note jid='juliet@capulet.com'
              cdate='2004-09-27T17:23:14Z'
              mdate='2004-09-28T12:43:12Z'>Oh my sweetest love ...</note>
        </storage>
      </item>
    </items>
  </event>
</message>
    

3.3 Retrieving Data

In order to retrieve stored data without receiving notifications (e.g., upon initial login), the user's client sends a retrieve-items request as specified in XEP-0060.

Example 5. Client requests all items

<iq from='juliet@capulet.lit/randomID' type='get' id='retrieve1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <items node='storage:rosternotes'/>
  </pubsub>
</iq>
    

Example 6. Server returns all items

<iq type='result'
    to='juliet@capulet.lit/randomID'
    id='retrieve1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <items node='storage:rosternotes'>
      <item id='current'>
        <storage xmlns='storage:rosternotes'>
          <note jid='hamlet@shakespeare.lit'
                cdate='2004-09-24T15:23:21Z'
                mdate='2004-09-24T15:23:21Z'>Seems to be a good writer</note>
          <note jid='juliet@capulet.com'
                cdate='2004-09-27T17:23:14Z'
                mdate='2004-09-28T12:43:12Z'>Oh my sweetest love ...</note>
        </storage>
      </item>
    </items>
  </pubsub>
</iq>
    

4. Security Considerations

Security considerations related to object persistent via publish-subscribe are described in XEP-0060 and XEP-0223.

5. IANA Considerations

No interaction with the Internet Assigned Numbers Authority (IANA) [6] is required as a result of this document.

6. XMPP Registrar Considerations

No action by the XMPP Registrar [7] is required, since the 'storage:rosternotes' namespace is already included in the protocol namespaces registry (see <http://www.xmpp.org/registrar/namespaces.html>).

7. XML Schema

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='storage:rosternotes'
    xmlns='storage:rosternotes'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0145: http://www.xmpp.org/extensions/xep-0145.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='storage'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='note' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='note'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute name='jid' type='xs:string' use='required'/>
          <xs:attribute name='cdate' type='xs:dateTime' use='optional'/>
          <xs:attribute name='mdate' type='xs:dateTime' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

</xs:schema>
 

Notes

1. XEP-0048: Bookmark Storage <http://www.xmpp.org/extensions/xep-0048.html>.

2. XEP-0082: XMPP Date and Time Profiles <http://www.xmpp.org/extensions/xep-0082.html>.

3. XEP-0060: Publish-Subscribe <http://www.xmpp.org/extensions/xep-0060.html>.

4. XEP-0223: Personal Information via Pubsub <http://www.xmpp.org/extensions/xep-0223.html>.

5. XEP-0049: Private XML Storage <http://www.xmpp.org/extensions/xep-0049.html>.

6. 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/>.

7. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://www.xmpp.org/registrar/>.


Revision History

Version 1.1pre3 (in progress, last updated 2007-09-27)

Specified use of publish-subscribe private information nodes as the preferred storage mechanism.

(psa)

Version 1.0 (2006-03-23)

Per a vote of the Jabber Council, advanced to Active.

(psa)

Version 0.2 (2005-07-15)

Editorial review: changed type to Historical; changed namespace to storage:rosternotes; corrected schema; specified use of DateTime profile from XEP-0082; corrected some small textual errors.

(psa)

Version 0.1 (2004-11-05)

Initial version.

(st)

END