Unless you're specifically interested in this revision of the draft, check out the current version at IETF.

Network Working Group                                           C. Daboo
Internet-Draft                                              ISAMET, Inc.
Expires: August 2, 2005                                   February  2005

                      IMAP ANNOTATEMORE Extension
                    draft-daboo-imap-annotatemore-07

Status of this Memo

   This document is an Internet-Draft and is subject to all provisions
   of section 3 of RFC 3667.  By submitting this Internet-Draft, each
   author represents that any applicable patent or other IPR claims of
   which he or she is aware have been or will be disclosed, and any of
   which he or she become aware will be disclosed, in accordance with
   RFC 3668.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as
   Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on August 2, 2005.

Copyright Notice

   Copyright (C) The Internet Society (2005).

Abstract

   The ANNOTATEMORE extension to the Internet Message Access Protocol
   permits clients and servers to maintain "metadata" on IMAP servers.
   It is possible to store data on a per-mailbox basis or on the server
   as a whole.

Change History (to be removed prior to publication as an RFC)

   Changes from -06 to -07:


Daboo                    Expires August 2, 2005                 [Page 1]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

   1.  Reworded /checkperiod item.
   2.  Clarified unsolicited response behaviour.

   Changes from -05 to -06:
   1.  Removed 'modifiedsince' attribute as there is currently no use
       for it.
   2.  Added content-language attribute.
   3.  Changed access to allow .priv and .shared on any mailbox returned
       by LIST/LSUB.
   4.  Added IANA registrations for items defined in this document.
   5.  Added latest IPR statement.
   6.  Updated references.

   Changes from -04 to -05:
   1.  Fix for valid IMAP state of commands.
   2.  Fix formatting, ID nits etc.

   Changes from -03 to -04:
   1.  Allow retrieval of shared annotations for READ-ONLY mailbox.
   2.  Clarification of annotation loss on implicit removal of \Noselect
       mailboxes.
   3.  Now requires roll-back of all changes to matching mailboxes if
       there is a partial failure in SETANNOTATION.

   Changes from -02 to -03:
   1.  Reworked entry naming scheme to split out mailbox name and use
       empty string for server items.

   Changes from -01 to -02:
   1.  SETANNOTATION lists use (..).
   2.  Explicitly state behaviour of unsolicited responses.
   3.  Adding SHOULD behaviour for rename/delete of mailboxes.
   4.  Added statement about supporting annotations on \Noselect
       mailboxes.
   5.  Cleaned up formal syntax to use IMAP string type for entry and
       attributes, with requirements on how the string is formatted.
   6.  Use of ACAP vendor subtree registry for vendor tokens.

   Changes from -00 to -01:
   1.  Multiple entry-att responses are now simply delimited by spaces
       in line with ANNOTATE spec.  Adjusted examples to match.
   2.  Fixed entry-list formal syntax item to account for unsolicited
       parenthesised list of entries.
   3.  Removed setentries formal syntax item for simplicity since its
       only used once.
   4.  Removed reference to 'message annotation' in section 5.1.
   5.  Changed formal syntax to restrict top level entries to /server
       and /mailbox/{...} only.  Re-arranged entry names section to


Daboo                    Expires August 2, 2005                 [Page 2]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

       account for this change.
   6.  Added comment and example for ANNOTATION response to allow
       servers to return separate responses for each entry if desired.

Table of Contents

   1.  Introduction and Overview  . . . . . . . . . . . . . . . . . .  4
   2.  Data Model . . . . . . . . . . . . . . . . . . . . . . . . . .  4
     2.1   Overview . . . . . . . . . . . . . . . . . . . . . . . . .  4
     2.2   Namespace of entries and attributes  . . . . . . . . . . .  5
       2.2.1   Entry Names  . . . . . . . . . . . . . . . . . . . . .  5
       2.2.2   Attribute Names  . . . . . . . . . . . . . . . . . . .  7
     2.3   Private versus Shared and Access Control . . . . . . . . .  7
   3.  IMAP Protocol Changes  . . . . . . . . . . . . . . . . . . . .  8
     3.1   General Considerations . . . . . . . . . . . . . . . . . .  8
     3.2   GETANNOTATION Command  . . . . . . . . . . . . . . . . . .  8
     3.3   SETANNOTATION Command  . . . . . . . . . . . . . . . . . . 10
     3.4   ANNOTATION Response  . . . . . . . . . . . . . . . . . . . 12
       3.4.1   ANNOTATION response with attributes and values . . . . 13
       3.4.2   Unsolicited ANNOTATION response without attributes
               and values . . . . . . . . . . . . . . . . . . . . . . 14
   4.  Formal Syntax  . . . . . . . . . . . . . . . . . . . . . . . . 15
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 16
     5.1   Entry and Attribute Registration Template  . . . . . . . . 17
     5.2   Server Entry Registrations . . . . . . . . . . . . . . . . 17
       5.2.1   /comment . . . . . . . . . . . . . . . . . . . . . . . 17
       5.2.2   /motd  . . . . . . . . . . . . . . . . . . . . . . . . 18
       5.2.3   /admin . . . . . . . . . . . . . . . . . . . . . . . . 18
     5.3   Mailbox Entry Registrations  . . . . . . . . . . . . . . . 18
       5.3.1   /comment . . . . . . . . . . . . . . . . . . . . . . . 19
       5.3.2   /sort  . . . . . . . . . . . . . . . . . . . . . . . . 19
       5.3.3   /thread  . . . . . . . . . . . . . . . . . . . . . . . 20
       5.3.4   /check . . . . . . . . . . . . . . . . . . . . . . . . 20
       5.3.5   /checkperiod . . . . . . . . . . . . . . . . . . . . . 21
     5.4   Attribute Registrations  . . . . . . . . . . . . . . . . . 21
       5.4.1   value  . . . . . . . . . . . . . . . . . . . . . . . . 21
       5.4.2   size . . . . . . . . . . . . . . . . . . . . . . . . . 22
       5.4.3   content-type . . . . . . . . . . . . . . . . . . . . . 22
       5.4.4   content-language . . . . . . . . . . . . . . . . . . . 23
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 23
   7.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 23
   7.1   Normative References . . . . . . . . . . . . . . . . . . . . 23
   7.2   Informative References . . . . . . . . . . . . . . . . . . . 24
       Author's Address . . . . . . . . . . . . . . . . . . . . . . . 24
   A.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 24
       Intellectual Property and Copyright Statements . . . . . . . . 25



Daboo                    Expires August 2, 2005                 [Page 3]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

1.  Introduction and Overview

   The ANNOTATEMORE extension is present in any IMAP [RFC3501]
   implementation which returns "ANNOTATEMORE" as one of the supported
   capabilities in the CAPABILITY command response.

   The goal of ANNOTATEMORE is to provide a means for clients to store
   and retrieve "metadata" on an IMAP server.  The metadata can be
   associated with specific mailboxes or the server as a whole.

   The ANNOTATEMORE extension adds two new commands and one new untagged
   response to the IMAP base protocol.

   This extension makes the following changes to the IMAP protocol:

      adds a new SETANNOTATION command
      adds a new GETANNOTATION command
      adds a new ANNOTATION untagged response
      adds a new ANNOTATEMORE response code

   The data model used in ANNOTATEMORE is exactly the same as that used
   in the ANNOTATE [ANNOTATE] extension to IMAP.  This is modeled after
   that of the Application Configuration Access Protocol [RFC2244] with
   the exception of inheritance which is not deemed necessary here.

   The rest of this document describes the data model and protocol
   changes more rigorously.

2.  Data Model

2.1  Overview

   The data model used in ANNOTATEMORE is one of a uniquely named entry
   with a set of uniquely named attributes, each of which has a value.
   Annotations can be added to mailboxes when a mailbox name is provided
   as the first argument to the new commands, or to the server as a
   whole when the empty string is provided as the first argument to the
   new commands.

   An annotation can contain multiple named entries.  For example, a
   general comment being added to a mailbox may have an entry name of "/
   comment".  This entry could include named attributes such as "value",
   "size", "content-type" etc to represent properties and data
   associated with the entry.

   The protocol changes to IMAP described below allow a client to access
   or change the values of any attributes in any entries in an
   annotation, assuming it has sufficient access rights to do so.


Daboo                    Expires August 2, 2005                 [Page 4]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

2.2  Namespace of entries and attributes

   Each annotation is made up of a set of entries.  Each entry has a
   hierarchical name in UTF-8, with each component of the name separated
   by a slash ("/").

   Each entry is made up of a set of attributes.  Each attribute has a
   hierarchical name in UTF-8, with each component of the name separated
   by a period (".").

   The value of an attribute is NIL (has no value), or a string of zero
   or more octets.

   Entry and attribute names are not permitted to contain asterisk ("*")
   or percent ("%") characters and MUST be valid UTF-8 strings which do
   not contain NUL.  Invalid entry or attribute names result in a BAD
   response in any IMAP commands where they are used.

   Use of non-visible UTF-8 characters in entry and attribute names is
   discouraged.

   This specification defines an initial set of entry and attribute
   names available for use with mailbox and server annotations.  In
   addition an extension mechanism is described to allow additional
   names to be added for extensibility.

2.2.1  Entry Names

   Entry names MUST be specified in a standards track or IESG approved
   experimental RFC, or fall under the vendor namespace.  See Section
   5.1 for the registration template.  This specification only allows
   two top-level entry types for servers and mailboxes.

2.2.1.1  Server Entries

   These entries are used when the mailbox name argument to the new
   commands is the empty string.

   /comment
      Defines a comment or note associated with the server.

   /motd
      Defines a "message of the day" for the server.  This entry is
      always read-only - clients cannot change it.

   /admin
      Indicates a method for contacting the server administrator.  This
      may be a URI (e.g.  a mailto URL) or other contact information,


Daboo                    Expires August 2, 2005                 [Page 5]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

      such as a telephone number.  This entry is always read-only -
      clients cannot change it.

   /vendor/<vendor-token>
      Defines the top-level of entries associated with the server as
      created by a particular product of some vendor.  This entry can be
      used by vendors to provide server or client specific attributes.
      The vendor-token MUST be registered with IANA, using the ACAP
      [RFC2244] vendor subtree registry.

2.2.1.2  Mailbox Entries

   These entries are used when the mailbox name argument to the new
   commands is not the empty string.

   /comment
      Defines a comment or note associated with a mailbox.

   /sort
      Defines the default sort criteria [SORT] to use when first
      displaying the mailbox contents to the user, or NIL if sorting is
      not required.

   /thread
      Defines the default thread criteria [SORT] to use when first
      displaying the mailbox contents to the user, or NIL if threading
      is not required.  If both sort and thread are not NIL, then
      threading should take precedence over sorting.

   /check
      Boolean value "true" or "false" that indicates whether this
      mailbox should be checked at regular intervals by the client.  The
      interval in minutes is specified by the /checkperiod entry.

   /checkperiod
      Numeric value indicating a period of minutes that the client uses
      to determine the interval of regular 'new mail' checks for the
      corresponding mailbox.

   /vendor/<vendor-token>
      Defines the top-level of entries associated with a specific
      mailbox as created by a particular product of some vendor.  This
      entry can be used by vendors to provide client specific
      attributes.  The vendor-token MUST be registered with IANA, using
      the ACAP [RFC2244] vendor subtree registry.



Daboo                    Expires August 2, 2005                 [Page 6]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

2.2.2  Attribute Names

   Attribute names MUST be specified in a standards track or IESG
   approved experimental RFC, or fall under the vendor namespace.  See
   Section 5.1 for the registration template.

   All attribute names implicitly have a ".priv" and a ".shared" suffix
   which maps to private and shared versions of the entry.  Searching or
   fetching without using either suffix includes both.  The client MUST
   specify either a ".priv" or ".shared" suffix when storing an
   annotation.

   value
      The data value of the attribute.

   size
      The size of the value, in octets.  Set automatically by the
      server, read-only to clients.

   content-type
      A MIME [RFC2046] content type and subtype that describes the
      nature of the content of the "value" attribute.

   content-language
      Indicates the language used for the value.  This follows the
      format described in [RFC3282].  Clients SHOULD set this value when
      storing an annotation that uses text that can be presented to the
      user.  It is not required for enumerated or numeric values such as
      flags etc.

   vendor.<vendor-token>
      Defines an attribute associated with a particular product of some
      vendor.  This attribute can be used by vendors to provide client
      specific attributes.  The vendor-token MUST be registered with
      IANA, using the ACAP [RFC2244] vendor subtree registry.

2.3  Private versus Shared and Access Control

   As discussed in the ANNOTATE [ANNOTATE] extension there is a need to
   support both private and shared annotations.  This document adopts
   the scheme used in [ANNOTATE] that adds two standard suffixes for all
   attributes: ".shared" and ".priv".  A GETANNOTATION command which
   specifies neither uses both.  SETANNOTATION commands MUST explicitly
   use .priv or .shared suffixes.

   A user can only store and retrieve private or shared annotations on a
   mailbox which is returned to them via a LIST or LSUB command.  If the
   client attempts to store or retrieve annotations on other mailboxes,


Daboo                    Expires August 2, 2005                 [Page 7]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

   the MUST respond with a NO response

3.  IMAP Protocol Changes

3.1  General Considerations

   The new commands and response each have a mailbox name argument,
   indicating that the annotations being referred to are attached to the
   specified mailbox.  An empty string can be used for the mailbox name
   to signify server annotations.

   Both "*" and "%" list wildcard characters MAY be used in the mailbox
   name argument to commands to match all possible occurrences of a
   mailbox name pattern.  However, "*" or "%" by themselves MUST NOT
   match the empty string (server) entries.  Server entries can only be
   accessed by explicitly using the empty string as the mailbox name.

   Servers SHOULD ensure that mailbox annotations are automatically
   moved when the mailbox they refer to is renamed, i.e.  the
   annotations follow the mailbox.  Servers SHOULD delete annotations
   for a mailbox when the mailbox is deleted, so that a mailbox created
   with the same name as a previously existing mailbox does not inherit
   the old mailbox annotations.  Servers SHOULD allow annotations on all
   'types' of mailbox, including ones reporting \Noselect for their LIST
   response.  Servers can implicitly remove \Noselect mailboxes when all
   child mailboxes are removed, and as such any annotations associated
   with the \Noselect mailbox SHOULD be removed.

   The server is allowed to impose limitations on the size of any one
   annotation or the total number of annotations for a single mailbox or
   for the server as a whole.  However, the server MUST accept a minimum
   annotation data size of at least 1024 bytes, and a minimum annotation
   count per server or mailbox of at least 10.

3.2  GETANNOTATION Command

   This extension adds the GETANNOTATION command.  This allows clients
   to retrieve annotations.

   This command is only available in authenticated or selected state
   [RFC3501].





Daboo                    Expires August 2, 2005                 [Page 8]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

       Arguments:  mailbox-name
                   entry-specifier
                   attribute-specifier

       Responses:  required ANNOTATION response

       Result:     OK - command completed
                   NO - command failure: can't access annotations on that mailbox
                   BAD - command unknown or arguments invalid

   The mailbox-name argument MUST be a valid mailbox name or the empty
   string.  In the later case, the annotations being referred to are the
   ones for the server as a whole.

   Example:

           C: a GETANNOTATION "" "/comment" "value.priv"
           S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
           S: a OK GETANNOTATION complete

      In the above example, the contents of the "value" attribute for
      the "/comment" server entry is requested by the client and
      returned by the server.

   "*" and "%" wildcard characters can be used in either specifier to
   match one or more characters at that position, with the exception
   that "%" does not match the hierarchy delimiter for the specifier it
   appears in (i.e.  "/" for an entry specifier or "." for an attribute
   specifier).  Thus an entry specifier of "/%" would match entries such
   as "/comment" and "/version", but not "/comment/note".

   Example:

           C: a GETANNOTATION "" "/*" "value.priv"
           S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
                            "/version" ("value.priv" "1.1")
                            "/motd/today" ("value.priv" "Closed at 1 pm")
           S: a OK GETANNOTATION complete

      In the above example, the contents of the "value" attributes for
      any server entries are requested by the client and returned by the
      server.

   Example:




Daboo                    Expires August 2, 2005                 [Page 9]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

           C: a GETANNOTATION "" "/%" "value"
           S: * ANNOTATION "/comment" ("value.priv" "My comment")
                                             ("value.shared" "Your comment")
                           "/motd" ("value.priv" "Its sunny outside!"
                                          ("value.shared" "Today is a Holiday")
           S: a OK GETANNOTATION complete

      In the above example, the contents of the "value" attributes for
      server entries at the top level of the entry hierarchy only, are
      requested by the client and returned by the server.  Both the
      .priv and .shared values are returned, as neither were explicitly
      requested.

   Entry and attribute specifiers can be lists of atomic specifiers, so
   that multiple items of each type may be returned in a single
   GETANNOTATION command.

   Example:

           C: a GETANNOTATION "" ("/comment" "/motd") "value.priv"
           S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
                              "/motd" ("value.priv" "Its sunny outside!")
           S: a OK GETANNOTATION complete

      In the above example, the contents of the "value" attributes for
      the two server entries "/comment" and "/motd" are requested by the
      client and returned by the server.

   Example:

           C: a GETANNOTATION "" "/comment" ("value.priv" "content-type.priv")
           S: * ANNOTATION "" "/comment" ("value.priv" "My comment"
                                          "content-type.priv" "text/plain")
           S: a OK GETANNOTATION complete

      In the above example, the contents of the "value" and
      "content-type" attributes for the "/comment" server entry are
      requested by the client and returned by the server.

3.3  SETANNOTATION Command

   This extension adds the SETANNOTATION command.  This allows clients
   to set annotations.

   This command is only available in authenticated or selected state
   [RFC3501].



Daboo                    Expires August 2, 2005                [Page 10]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

       Arguments:  mailbox-name
                   entry
                   attribute-value
                   list of entry, attribute-values

       Responses:  no specific responses for this command

       Result:     OK - command completed
                   NO - command failure: can't set annotations,
                        or annotation too big or too many
                   BAD - command unknown or arguments invalid

   Sets the specified list of entries by adding or replacing the
   specified attributes with the values provided.  Clients can use NIL
   for values of attributes it wants to remove from entries.  The server
   MAY return an ANNOTATION response containing the updated annotation
   data.  Clients MUST NOT assume that an ANNOTATION response will be
   sent, and MUST assume that if the command succeeds then the
   annotation has been changed.

   If the server is unable to store an annotation because the size of
   its value is too large, the server MUST return a tagged NO response
   with a "[ANNOTATEMORE TOOBIG]" response code.

   If the server is unable to store a new annotation because the maximum
   number of allowed annotations has already been reached, the server
   MUST return a tagged NO response with a "[ANNOTATEMORE TOOMANY]"
   response code.

   If the server is unable to store the annotations for one or more
   mailboxes matching the mailbox-name pattern, then the SETANNOTATION
   command MUST fail and there MUST NOT be any changes to any of the
   matching mailboxes, even those for which annotations could have been
   changed successfully.

   Example:

           C: a SETANNOTATION "INBOX" "/comment" ("value.priv" "My new comment")
           S: a OK SETANNOTATION complete

      In the above example, the entry "/comment" for the mailbox "INBOX"
      is created (if not already present) and the private attribute
      "value" with data set to "My new comment" is created if not
      already present, or replaced if it previously exists.

   Example:

           C: a SETANNOTATION "INBOX" "/comment" ("value.priv" NIL)


Daboo                    Expires August 2, 2005                [Page 11]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

           S: a OK SETANNOTATION complete

      In the above example, the private "value" attribute of the entry
      "/comment" is removed from the mailbox "INBOX".

   Multiple entries can be set in a single SETANNOTATION command by
   listing entry-attribute-value pairs in the list.

   Example:

           C: a SETANNOTATION "INBOX.%" "/comment" ("value.priv" "My new comment")
           S: a OK SETANNOTATION complete

      In the above example, the entry "/comment" for all mailboxes at
      the top-level of the "INBOX" hierarchy are created (if not already
      present) and the private and shared attributes "value" are created
      respectively for each entry if not already present, or replaced if
      they previously existed.

   Multiple attributes can be set in a single SETANNOTATION command by
   listing multiple attribute-value pairs in the entry list.

   Example:

           C: a SETANNOTATION "INBOX" "/comment"
                                ("value.priv" "My new comment"
                                 "vendor.foobar.bloop.priv" "foo's bar")
           S: a OK SETANNOTATION complete

      In the above example, the entry "/comment" for the mailbox "INBOX"
      is created (if not already present) and the private attributes
      "value" and "vendor.foobar.bloop" are created if not already
      present, or replaced if they previously existed.

   Example:

           C: a SETANNOTATION "INBOX" "/comment" ("value.priv" "My new comment")
           S: a NO [ANNOTATEMORE TOOMANY] SETANNOTATION failed

      In the above example, the server is unable to store the requested
      (new) annotation as it has reached the limit on the number of
      annotations it can support on the specified mailbox.

3.4  ANNOTATION Response

   The ANNOTATION response displays results of a GETANNOTATION command,
   or can be returned as a unsolicited response at anytime by the server
   in response to a change in an annotation.


Daboo                    Expires August 2, 2005                [Page 12]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

   Servers SHOULD send unsolicited ANNOTATION responses if mailbox or
   server annotations are changed by a third-party, allowing servers to
   keep clients updated with changes.  Unsolicited mailbox annotations
   MUST only be returned for the currently selected mailbox.

   Unsolicited ANNOTATION responses MUST only contain entry names, not
   the attributes and values.  If the client wants to update any cached
   values it must explicitly retrieve those using a GETANNOTATION
   command.

   Separate ANNOTATION responses MUST be used when more than one mailbox
   matches the mailbox name argument pattern to the command.

   The ANNOTATION response can contain multiple entries in a single
   response,  but the server is free to return multiple responses for
   each entry or group of entries if it desires.

   This response is only available in authenticated state [RFC3501].

3.4.1  ANNOTATION response with attributes and values

   The response consists of a list of entries each of which has a list
   of attribute-value pairs.

   Example:

           C: a GETANNOTATION "" "/comment" "value.priv"
           S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
           S: a OK GETANNOTATION complete

      In the above example, a single entry with a single attribute-value
      pair is returned by the server.

   Example:

           C: a GETANNOTATION "" ("/comment" "/motd") "value.priv"
           S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
                              "/motd" ("value.priv" "Its sunny outside!")
           S: a OK GETANNOTATION complete

      In the above example, two entries each with a single
      attribute-value pair is returned by the server.

   Example:

           C: a GETANNOTATION "" ("/comment" "/motd") "value.priv"
           S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
           S: * ANNOTATION "" "/motd" ("value.priv" "Its sunny outside!")


Daboo                    Expires August 2, 2005                [Page 13]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

           S: a OK GETANNOTATION complete

      In the above example, the server returns two separate responses
      for each of the two entries requested.

   Example:

           C: a GETANNOTATION "" "/comment" ("value.priv" "size.priv")
           S: * ANNOTATION "" "/comment" ("value.priv" "My comment"
                                          "size.priv" "10")
           S: a OK GETANNOTATION complete

      In the above example, a single entry with two attribute-value
      pairs is returned by the server.

   Example:

           C: a GETANNOTATION "INBOX.%" "/comment" "value.priv"
           S: * ANNOTATION "INBOX.1" "/comment" ("value.priv" "My comment for 1")
           S: * ANNOTATION "INBOX.2" "/comment" ("value.priv" "My comment for 2")
           S: * ANNOTATION "INBOX.3" "/comment" ("value.priv" "My comment for 3")
           S: a OK GETANNOTATION complete

      In the above example, separate responses are returned for each
      matching mailbox, each containing a single entry with a single
      attribute-value pair.

3.4.2  Unsolicited ANNOTATION response without attributes and values

   The response consists of a parenthesised list of entries, each of
   which have changed on the server.

   Example:

           C: a NOOP
           S: * ANNOTATION "" ("/comment")
           S: a OK NOOP complete

      In the above example, the server indicates that the "/comment"
      server entry has been changed.

   Example:

           C: a NOOP
           S: * ANNOTATION "" ("/comment" "/motd")
           S: a OK NOOP complete



Daboo                    Expires August 2, 2005                [Page 14]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

      In the above example, the server indicates a change to two server
      entries.

   Example:

           C: a NOOP
           S: * ANNOTATION "" ("/motd")
           S: * ANNOTATION "INBOX" ("/comment")
           S: a OK NOOP complete

      In the above example, the server indicates a change to a server
      entry, and to the an entry for the currently selected mailbox.

4.  Formal Syntax

   The following syntax specification uses the Augmented Backus-Naur
   Form (ABNF) notation as specified in [RFC2234].

   Non-terminals referenced but not defined below are as defined by
   [RFC3501].

   Except as noted otherwise, all alphabetic characters are case-
   insensitive.  The use of upper or lower case characters to define
   token strings is for editorial clarity only.  Implementations MUST
   accept these strings in a case-insensitive fashion.

       annotate-data     = "ANNOTATION" SP mailbox SP entry-list
                           ; empty string for mailbox implies
                           ; server annotation.

       att-value         = attrib SP value

       attrib            = string
                           ; dot-separated attribute name
                           ; MUST NOT contain "*" or "%"
       attrib-match      = string
                           ; dot-separated attribute name
                           ; MAY contain "*" or "%" for use as wildcards

       attribs           = attrib-match / "(" attrib-match *(SP attrib-match) ")"
                           ; attribute specifiers that can include wildcards

       command-auth      /= setannotation / getannotation
                           ; adds to original IMAP command

       entries           = entry-match / "(" entry-match *(SP entry-match) ")"
                           ; entry specifiers that can include wildcards


Daboo                    Expires August 2, 2005                [Page 15]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

       entry             = string
                           ; slash-separated path to entry
                           ; MUST NOT contain "*" or "%"

       entry-att         = entry SP "(" att-value *(SP att-value) ")"

       entry-list        = entry-att *(SP entry-att) /
                           "(" entry *(SP entry) ")"
                           ; entry attribute-value pairs list for
                           ; GETANNOTATION response, or
                           ; parenthesised entry list for unsolicited
                           ; notification of annotation changes

       entry-match       = string
                           ; slash-separated path to entry
                           ; MAY contain "*" or "%" for use as wildcards

       getannotation     = "GETANNOTATION" SP list-mailbox SP entries SP attribs
                           ; empty string for list-mailbox implies
                           ; server annotation.

       response-data     /= "*" SP annotate-data CRLF
                           ; adds to original IMAP data responses

       resp-text-code    =/ "ANNOTATEMORE" SP "TOOBIG" /
                            "ANNOTATEMORE" SP "TOOMANY"
                           ; new response codes for SETANNOTATION failures

       setannotation     = "SETANNOTATION" SP list-mailbox SP setentryatt
                           ; empty string for list-mailbox implies
                           ; server annotation.

       setentryatt       = entry-att / "(" entry-att *(SP entry-att) ")"

       value             = nstring

5.  IANA Considerations

   Both entry names and attribute names MUST be specified in a standards
   track or IESG approved experimental RFC, or fall under the vendor
   namespace.





Daboo                    Expires August 2, 2005                [Page 16]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

5.1  Entry and Attribute Registration Template

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [ ] Entry        [ ] Attribute

       [ ] Mailbox      [ ] Server

       Name: ______________________________

       Description: _______________________

       ____________________________________

       ____________________________________

       Contact person: ____________________

               email:  ____________________

5.2  Server Entry Registrations

   The following templates specify the IANA registrations of annotation
   entries specified in this document.

5.2.1  /comment

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [x] Entry        [ ] Attribute

       [ ] Mailbox      [x] Server

       Name: /comment

       Description: Defined in IMAP ANNOTATEMORE extension document.

       Contact person: Cyrus Daboo

               email:  daboo@isamet.com


Daboo                    Expires August 2, 2005                [Page 17]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

5.2.2  /motd

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [x] Entry        [ ] Attribute

       [ ] Mailbox      [x] Server

       Name: /motd

       Description: Defined in IMAP ANNOTATEMORE extension document.

       Contact person: Cyrus Daboo

               email:  daboo@isamet.com

5.2.3  /admin

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [x] Entry        [ ] Attribute

       [ ] Mailbox      [x] Server

       Name: /admin

       Description: Defined in IMAP ANNOTATEMORE extension document.

       Contact person: Cyrus Daboo

               email:  daboo@isamet.com

5.3  Mailbox Entry Registrations

   The following templates specify the IANA registrations of annotation
   entries specified in this document.




Daboo                    Expires August 2, 2005                [Page 18]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

5.3.1  /comment

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [x] Entry        [ ] Attribute

       [x] Mailbox      [ ] Server

       Name: /comment

       Description: Defined in IMAP ANNOTATEMORE extension document.

       Contact person: Cyrus Daboo

               email:  daboo@isamet.com

5.3.2  /sort

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [x] Entry        [ ] Attribute

       [x] Mailbox      [ ] Server

       Name: /sort

       Description: Defined in IMAP ANNOTATEMORE extension document.

       Contact person: Cyrus Daboo

               email:  daboo@isamet.com







Daboo                    Expires August 2, 2005                [Page 19]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

5.3.3  /thread

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [x] Entry        [ ] Attribute

       [x] Mailbox      [ ] Server

       Name: /thread

       Description: Defined in IMAP ANNOTATEMORE extension document.

       Contact person: Cyrus Daboo

               email:  daboo@isamet.com

5.3.4  /check

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [x] Entry        [ ] Attribute

       [x] Mailbox      [ ] Server

       Name: /check

       Description: Defined in IMAP ANNOTATEMORE extension document.

       Contact person: Cyrus Daboo

               email:  daboo@isamet.com







Daboo                    Expires August 2, 2005                [Page 20]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

5.3.5  /checkperiod

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [x] Entry        [ ] Attribute

       [x] Mailbox      [ ] Server

       Name: /checkperiod

       Description: Defined in IMAP ANNOTATEMORE extension document.

       Contact person: Cyrus Daboo

               email:  daboo@isamet.com

5.4  Attribute Registrations

   The following templates specify the IANA registrations of annotation
   attributes specified in this document.

5.4.1  value

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [ ] Entry        [x] Attribute

       [ ] Mailbox      [ ] Server

       Name: value

       Description: Defined in IMAP ANNOTATEMORE extension document.

       Contact person: Cyrus Daboo

               email:  daboo@isamet.com




Daboo                    Expires August 2, 2005                [Page 21]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

5.4.2  size

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [ ] Entry        [x] Attribute

       [ ] Mailbox      [ ] Server

       Name: size

       Description: Defined in IMAP ANNOTATEMORE extension document.

       Contact person: Cyrus Daboo

               email:  daboo@isamet.com

5.4.3  content-type

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [ ] Entry        [x] Attribute

       [ ] Mailbox      [ ] Server

       Name: content-type

       Description: Defined in IMAP ANNOTATEMORE extension document.

       Contact person: Cyrus Daboo

               email:  daboo@isamet.com







Daboo                    Expires August 2, 2005                [Page 22]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

5.4.4  content-language

       To: iana@iana.org
       Subject: IMAP ANNOTATEMORE Registration

       Please register the following IMAP ANNOTATEMORE item:

       [ ] Entry        [x] Attribute

       [ ] Mailbox      [ ] Server

       Name: content-language

       Description: Defined in IMAP ANNOTATEMORE extension document.

       Contact person: Cyrus Daboo

               email:  daboo@isamet.com

6.  Security Considerations

   Annotations whose values are intended to remain private MUST be
   stored in .priv values, and not .shared values which may be
   accessible to other users.

   >Excluding the above issues the ANNOTATEMORE extension does not raise
   any security considerations that are not present in the base IMAP
   protocol, and these issues are discussed in [RFC3501].

7.  References

7.1  Normative References

   [RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part Two: Media Types", RFC 2046,
              November 1996.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
              Specifications: ABNF", RFC 2234, November 1997.

   [RFC2244]  Newman, C. and J. Myers, "ACAP -- Application
              Configuration Access Protocol", RFC 2244, November 1997.

   [RFC3282]  Alvestrand, H., "Content Language Headers", RFC 3282, May


Daboo                    Expires August 2, 2005                [Page 23]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

              2002.

   [RFC3501]  Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
              4rev1", RFC 3501, March 2003.

   [SORT]     Crispin, M. and K. Murchison, "Internet Message Access
              Protocol - Sort and Thread Extension",
              draft-ietf-imapext-sort-17.txt, May 2004.

7.2  Informative References

   [ANNOTATE]
              Daboo, C. and R. Gellens, "IMAP ANNOTATE Extension",
              draft-ietf-imapext-annotate-11.txt, October 2004.

Author's Address

   Cyrus Daboo
   ISAMET, Inc.
   5001 Baum Blvd.
   Suite 650
   Pittsburgh, PA  15213
   US

   EMail: daboo@isamet.com

Appendix A.  Acknowledgments

   The ideas expressed in this document are based on the message
   annotation document that was co-authored by Randall Gellens.










Daboo                    Expires August 2, 2005                [Page 24]
 
Internet-Draft        IMAP ANNOTATEMORE Extension         February  2005

Intellectual Property Statement

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.

Disclaimer of Validity

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Copyright Statement

   Copyright (C) The Internet Society (2005).  This document is subject
   to the rights, licenses and restrictions contained in BCP 78, and
   except as set forth therein, the authors retain all their rights.

Acknowledgment

   Funding for the RFC Editor function is currently provided by the
   Internet Society.


Daboo                    Expires August 2, 2005                [Page 25]


Html markup produced by rfcmarkup 1.41, available from http://tools.ietf.org/tools/rfcmarkup/