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

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

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.

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

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

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

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

<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

Revision History

END