WDIFF

draft-daboo-imap-annotatemore-12.txt --> draft-daboo-imap-annotatemore-13.txt

Network Working Group C. Daboo
Internet-Draft Apple
Intended status: Standards Track December 22, 2007 April 21, 2008
Expires: June 24, October 23, 2008

IMAP METADATA Extension
draft-daboo-imap-annotatemore-12
draft-daboo-imap-annotatemore-13

Status of this Memo

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 becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.

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 June 24, October 23, 2008.

Abstract

The METADATA extension to the Internet Message Access Protocol
permits clients and servers to maintain "annotations" or "meta data"
on IMAP servers. It is possible to have annotations on a per-mailbox
basis or on the server as a whole. For example, this would allow
comments about the purpose of a particular mailbox to be "attached"
to that mailbox, or a "message of the day" containing server status
information to be made available to anyone logging in to the server.

Daboo Expires June 24, October 23, 2008 [Page 1]

Internet-Draft IMAP METADATA Extension December 2007 April 2008

Table of Contents

1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in This Document . . . . . . . . . . . . . . 4 3
3. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Namespace of entries and attributes . . . . . . . . . . . 5
3.2.1. Entry Names . . . . . . . . . . . . . . . . . . . 4
3.2.1. Entry Names . . 5
3.2.2. Attribute Names . . . . . . . . . . . . . . . . . . . 7 5
3.3. Private versus Shared Public and Access Control . . . . . . . . . 8 6
4. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 8 6
4.1. General Considerations . . . . . . . . . . . . . . . . . . 8 6
4.2. GETMETADATA Command . . . . . . . . . . . . . . . . . . . 9 7
4.3. Extended LIST Command Extensions . . . . . . . . . . . . . 11
4.3.1. Unsolicited LIST response . . . . . . . . . . . . . . 16
4.4. SETMETADATA Command . . . . . . . . . . . . . . . . . . . 16
4.5. 9
4.4. METADATA Response . . . . . . . . . . . . . . . . . . . . 19
4.5.1. 10
4.4.1. METADATA response with attributes and values . . . . . 19
4.5.2. Unsolicited METADATA response without attributes
and values . . . . . . . . . . . . 11
4.4.2. Unsolicited METADATA response without values . . . . . . . . . . 20 11
5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 21 12
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 14
6.1. Entry and Attribute Registration Template . . . . . . . . 23 14
6.2. Server Entry Registrations . . . . . . . . . . . . . . . . 23 14
6.2.1. /comment . /public/comment . . . . . . . . . . . . . . . . . . . . . . 24 15
6.2.2. /motd . . . . . . . . . . . . . . . . . . . . . . . . 24
6.2.3. /admin /public/admin . . . . . . . . . . . . . . . . . . . . . . . . 25 15
6.3. Mailbox Entry Registrations . . . . . . . . . . . . . . . 25 15
6.3.1. /comment . . . . /public/comment . . . . . . . . . . . . . . . . . . . 25 16
6.3.2. /sort . . . . . . . . . . . . . . . . . . . . . . . . 26
6.3.3. /thread . . . . . . . . . . . . . . . . . . . . . . . 26
6.3.4. /check . . . . . . . . . . . . . /private/comment . . . . . . . . . . . 27
6.3.5. /checkperiod . . . . . . . . . . 16
7. Security Considerations . . . . . . . . . . . 27
6.4. LIST-EXTENDED Registration . . . . . . . . 16
8. Normative References . . . . . . . . 27
7. Security Considerations . . . . . . . . . . . . . 17
Appendix A. Acknowledgments . . . . . . 28
8. References . . . . . . . . . . . . . 17
Appendix B. Change History (to be removed prior to
publication as an RFC) . . . . . . . . . . . . . 29
8.1. Normative References . . 17
Author's Address . . . . . . . . . . . . . . . . . 29
8.2. Informative References . . . . . . . . 20
Intellectual Property and Copyright Statements . . . . . . . . . . 30
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 30
Appendix B. Change History (to be removed prior to
publication as an RFC) . . . . . . . . . . . . . . . 30
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 33
Intellectual Property and Copyright Statements . . . . . . . . . . 34 21

Daboo Expires June 24, October 23, 2008 [Page 2]

Internet-Draft IMAP METADATA Extension December 2007 April 2008

1. Introduction and Overview

The goal of the METADATA extension is to provide a means for clients
to set and retrieve "annotations" or "meta data" on an IMAP server.
The annotations can be associated with specific mailboxes or the
server as a whole. The server can choose to support only server
annotations or both server and mailbox annotations.

A server that supports both server and mailbox annotations indicates
the presence of this extension by returning "METADATA" as one of the
supported capabilities in the CAPABILITY command response. The
"LIST-EXTENDED" [I-D.ietf-imapext-list-extensions] and
"ENABLE"
[I-D.gulbrandsen-imap-enable] [RFC5161] extensions MUST also be present.

A server that supports only server annotations indicates the presence
of this extension by returning "METADATA-SERVER" as one of the
supported capabilities in the CAPABILITY command response. The
"ENABLE" [I-D.gulbrandsen-imap-enable] [RFC5161] extension MUST also be present. There is no requirement that other extensions, including
"LIST-EXTENDED", be present in this case.

The METADATA extension adds two new commands and one new untagged
response to the IMAP base protocol. It adds one new LIST-EXTENDED
"selection" [I-D.ietf-imapext-list-extensions] option type and one
new LIST-EXTENDED "return" [I-D.ietf-imapext-list-extensions] option
type.

This extension makes the following changes to the IMAP protocol:

For server annotations only:

* adds a new SETMETADATA command
* adds a new GETMETADATA command
* adds a new METADATA untagged response
* adds a new METADATA response code

For server and mailbox annotation support:

o adds a new SETMETADATA command
*
o adds a new GETMETADATA command
*
o adds a new METADATA untagged response
*
o adds a new METADATA response code
* adds a new METADATA LIST-EXTENDED selection option type
* adds a new METADATA LIST-EXTENDED return option type

The data model used in METADATA is exactly the same as that used in
the ANNOTATE [I-D.ietf-imapext-annotate] extension to IMAP. This is
modeled after that of the Application Configuration Access Protocol

Daboo Expires June 24, 2008 [Page 3]

Internet-Draft IMAP METADATA Extension December 2007

[RFC2244] with the exception of inheritance which is not deemed
necessary here.

Text comparisons may be done as part of the GETMETADATA or LIST-
EXTENDED commands. command. If
the COMPARATOR [I-D.ietf-imapext-i18n] extension is present, then
comparisons are done using the comparator in effect at the time. If
the COMPARATOR extension is not present, then comparisons MUST use
the i;unicode-casemap comparator, as defined in [RFC5051].

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

2. Conventions Used in This Document

In examples, "C:" and "S:" indicate lines sent by the client and
server respectively.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].

Daboo Expires October 23, 2008 [Page 3]

Internet-Draft IMAP METADATA Extension April 2008

Whitespace and line breaks have been added to the examples in this
document to promote readability.

3. Data Model

3.1. Overview

Mailboxes or the server as a whole may have zero or more annotations
associated with them. An annotation contains 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
SETMETADATA command, or to the server as a whole when the empty
string is provided as the first argument to the new command.

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" and "size" etc to represent properties "/comment" and data
associated with the entry. a value "Really useful mailbox".

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

Daboo Expires June 24, 2008 [Page 4]

Internet-Draft IMAP METADATA Extension December 2007

3.2. Namespace of entries and attributes

Each annotation is an entry that has a hierarchical name, with each
component of the name separated by a slash ("/"). An entry name MUST
NOT contain two consecutive "/" characters and MUST NOT end with a
"/" character.

Each entry is made up of a set of attributes. Each attribute has a
hierarchical name, with each component of the name separated by a
period ("."). An attribute name MUST NOT contain two consecutive "."
characters and MUST NOT end with a "." character.

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

Entry and attribute names MUST NOT contain asterisk ("*") or percent ("%")
characters and MUST NOT contain non-ASCII characters or the NUL
octet. Invalid entry or attribute names result in a BAD response in any IMAP
commands where they are used.

Attribute names MUST NOT contain any hierarchical components with the
names "priv" or "shared" as those have special meaning (see
Section 3.3).

Entry and attribute names are case-sensitive. case-insensitive.

Use of control or punctuation characters in entry and attribute names is strongly
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.

The first component in entry names defines the scope of the

Daboo Expires October 23, 2008 [Page 4]

Internet-Draft IMAP METADATA Extension April 2008

annotation. Currently only the prefixes "/private" or "/public" are
defined. These prefixes are used to indicate whether an annotation
is stored on a per-user basis ("/private") and not visible to other
users, or whether and annotations is shared between all users
("/public") with a single value that can be read and changed by all
users with appropriate access. See Section 3.3 for details.

3.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 6.1 for the registration template.

3.2.1.1. Server Entries

These entries are used set or retrieved when the mailbox name argument to
the new SETMETADATA command or GETMETATDATA commands is the empty string or with the new GETMETADATA
command.

/comment

Daboo Expires June 24, 2008 [Page 5]

Internet-Draft IMAP METADATA Extension December 2007 string.

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

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

/admin

/public/admin
Indicates a method for contacting the server administrator. The
value MUST be a URI (e.g., a mailto: or tel: URL). This entry is
always read-only - clients cannot change it.

/vendor/<vendor-token> It is visible to all
users of the system.

/public/vendor/<vendor-token>
Defines the top-level of public 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
annotations. The vendor-token MUST be registered with IANA, using
the ACAP [RFC2244] vendor subtree registry.

/private/vendor/<vendor-token>
Defines the top-level of private 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
annotations. The vendor-token MUST be registered with IANA, using
the ACAP [RFC2244] vendor subtree registry.

3.2.1.2. Mailbox Entries

These entries are used set or retrieved when the mailbox name argument to
the new SETMETADATA command or GETMETADATA commands is not the empty string, string.

/public/comment

Daboo Expires October 23, 2008 [Page 5]

Internet-Draft IMAP METADATA Extension April 2008

Defines a public comment or note associated with the new LIST-
EXTENDED selection option type, or in responses to these commands.

/comment a mailbox.

/private/comment
Defines a private (per-user) comment or note associated with a
mailbox.

/sort

/public/vendor/<vendor-token>
Defines the default sort criteria [I-D.ietf-imapext-sort] to use
when first displaying the top-level of public entries associated with a specific
mailbox contents as created by a particular product of some vendor. This
entry can be used by vendors to the user, or NIL if
sorting is not required. provide client specific
annotations. The text value vendor-token MUST use be registered with IANA, using
the 'sort-
criteria' syntax defined by ACAP [RFC2244] vendor subtree registry.

/private/vendor/<vendor-token>
Defines the Formal Syntax top-level of
[I-D.ietf-imapext-sort] Section 5. Note that the presence private entries associated with a
specific mailbox as created by a particular product of this
attribute does not imply that the server supports the IMAP SORT
[I-D.ietf-imapext-sort] extension - servers some
vendor. This entry can choose be used by vendors to support
or not support SORT independently of this extension. In the
absence of provide client
specific annotations. The vendor-token MUST be registered with
IANA, using the SORT extension, clients ACAP [RFC2244] vendor subtree registry.

3.3. Private versus Public and Access Control

A user can choose only set and retrieve private or public annotations on a
mailbox which exists and is returned to interpret
this entry as suggesting them via a client-side sort ordering LIST or LSUB
command, irrespective of whether they have read or write access to
the actual message content of the
corresponding mailbox.

/thread
Defines If the default thread criteria [I-D.ietf-imapext-sort] client attempts to use
when first displaying
set or retrieve annotations on other mailboxes, the mailbox contents to server MUST
respond with a NO response.

If the user, or NIL if
threading METADATA extension is not required. If both sort and thread are not NIL,
then threading should take precedence over sorting. present, support for public annotations
is REQUIRED, whilst support for private annotations is OPTIONAL.
This recognizes the fact that support for private annotations may
introduce significantly more complexity to a server in terms of
tracking ownership of the annotations, how quota is determined for
users based on their own annotations etc.

4. IMAP Protocol Changes

4.1. General Considerations

The text
value MUST use new SETMETADATA command and the 'thread-alg' syntax defined by METADATA response each have a
mailbox name argument. An empty string is used for the Formal
Syntax of [I-D.ietf-imapext-sort] Section 5. Note that mailbox name
to signify server annotations. A non-empty string is used to signify
mailbox annotations attached to the
presence of this attribute does not imply corresponding mailbox.

Servers SHOULD ensure that mailbox annotations are automatically
moved when the server supports mailbox they refer to is renamed, i.e. the annotations

Daboo Expires June 24, October 23, 2008 [Page 6]

Internet-Draft IMAP METADATA Extension December 2007 April 2008

follow the IMAP THREAD [I-D.ietf-imapext-sort] extension - servers can
choose mailbox. This applies to support or not support THREAD independently a rename of this
extension. In the absence of INBOX, with the THREAD extension, clients can
choose
additional behavior that the annotations are copied from the original
INBOX to interpret this entry as a client-side thread ordering of the corresponding renamed mailbox.

/check
Boolean value "true" or "false" that indicates whether this i.e. mailbox should be checked at regular intervals by annotations are preserved
on the client. The
interval in minutes INBOX when it is specified by the /checkperiod entry. When
appropriate clients renamed.

Servers SHOULD use the IMAP IDLE [RFC2177] extension
to poll the currently selected delete annotations for a mailbox even when this value the mailbox is set
to "true".

/checkperiod
Numeric value indicating a period of minutes
deleted, so that a mailbox created with 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
annotations. The vendor-token MUST be registered with IANA, using
the ACAP [RFC2244] vendor subtree registry.

3.2.2. Attribute Names

This specification defines two attribute names. Each attribute name
implicitly has a ".priv" and a ".shared" suffix which maps to private
and shared versions of the entry. Retrieving an annotation without
using either suffix includes both. The client MUST specify either a
".priv" or ".shared" suffix when setting an annotation.

value
A string or binary data representing the value of the annotation.
To delete an annotation, the client can store "NIL" into the
value. The content represented by the string is determined by the
Content-Type used to register the entry (see Section 6.1 for entry
registration templates). Where applicable, the registered
Content-Type MUST include a charset parameter. Text values SHOULD
use the utf-8 [RFC3629] charset.
Note that binary data (data which may contain the NUL octet) is
allowed (e.g., for storing images etc), and this extension uses
the "literal8" syntax element [RFC4466] to allow such data to be
written to or read from the server.

size

Daboo Expires June 24, 2008 [Page 7]

Internet-Draft IMAP METADATA Extension December 2007

The size of the value, in octets. Set automatically by the
server, read-only to clients. The text value MUST use the
'number' syntax defined by the Formal Syntax of [RFC3501] Section
9. In particular neither "NIL" nor the empty string are allowed.
If the client requests the size attribute for a non-existent
entry, then the server MUST return "0" (zero) for the size.

3.3. Private versus Shared and Access Control

As discussed in the ANNOTATE [I-D.ietf-imapext-annotate] extension
there is a need to support both private and shared annotations. This
document adopts the scheme used in [I-D.ietf-imapext-annotate] that
adds two standard suffixes for all attributes: ".shared" and ".priv".
A GETMETADATA or extended LIST command which specifies neither uses
both. SETMETADATA commands MUST explicitly use .priv or .shared
suffixes.

A user can only set and retrieve private or shared annotations on a
mailbox which exists and is returned to them via a LIST or LSUB
command, irrespective of whether they have read or write access to
the actual message content of the mailbox. If the client attempts to
set or retrieve annotations on other mailboxes, the server MUST
respond with a NO response.

If the METADATA extension is present, support for shared annotations
is REQUIRED, whilst support for private annotations is OPTIONAL.
This recognizes the fact that support for private annotations may
introduce significantly more complexity to a server in terms of
tracking ownership of the annotations, how quota is determined for
users based on their own annotations etc. Clients that support the
METADATA extension MUST handle both shared and private annotations.

4. IMAP Protocol Changes

4.1. General Considerations

The new SETMETADATA command and the METADATA response each have a
mailbox name argument. An empty string is used for the mailbox name
to signify server annotations. A non-empty string is used to signify
mailbox annotations attached to the corresponding mailbox.

Both "*" and "%" list wildcard characters MAY be used in the mailbox
name argument in the SETMETADATA command 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.

Daboo Expires June 24, 2008 [Page 8]

Internet-Draft IMAP METADATA Extension December 2007

Servers SHOULD ensure that mailbox annotations are automatically
moved when the mailbox they refer to is renamed, i.e. the annotations
follow the mailbox. This applies to a rename of the INBOX, with the
additional behavior that the annotations are copied from the original
INBOX to the renamed mailbox. i.e. mailbox annotations are preserved
on the INBOX when it is renamed.

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.

Some annotations may be "read-only" - i.e. they are set by the server
and cannot be changed by the client. Also, such annotations may be
"computed" - i.e. the value changes based on underlying properties of
the mailbox. For example, an annotation reporting the total size of
all messages in the mailbox would change as messages are added or
removed. Or, an annotation containing an IMAP URL for the mailbox
would change if the mailbox was renamed.

This extension defines some unsolicited responses for use when
annotations are changed by some "third-party" (see Section 4.3.1 and
Section 4.5). The server MUST only send these unsolicited responses
if the client used the ENABLE command [I-D.gulbrandsen-imap-enable]
extension with the capability string "METADATA" earlier in the
session.

4.2. GETMETADATA Command

This extension adds the GETMETADATA command. This allows clients to
retrieve server annotations. Mailbox annotations are retrieved via
the extended LIST command described in the next section.

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

Daboo Expires June 24, 2008 [Page 9]

Internet-Draft IMAP METADATA Extension December 2007

Arguments: entry-specifier
attribute-specifier

Responses: required METADATA response

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

Example:

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

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

"*" and "%" wildcard characters can be used in the entry specifier to
match one or more characters at that position, with the exception
that "%" does not match the "/" hierarchy delimiter. Thus an entry
specifier of "/%" would match entries such as "/comment" and "/motd",
but not "/comment/note".

Example:

C: a GETMETADATA /* value.priv
S: * METADATA /comment (value.priv "My comment")
/motd (value.priv "Closed at 1 pm")
S: a OK GETMETADATA complete

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

Example:

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

Daboo Expires June 24, 2008 [Page 10]

Internet-Draft IMAP METADATA Extension December 2007

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
GETMETADATA command.

Example:

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

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

Example:

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

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

4.3. Extended LIST Command Extensions

This extension adds the METADATA LIST command selection and return
option types, extending the LIST-EXTENDED extension. This allows
clients to retrieve mailbox annotations.

The LIST-EXTENDED "METADATA" selection option type is used to request
that the extended LIST command match mailboxes which have an
annotation with a specific entry and value. It can also be used to
test for the existence of a particular annotation entry on a mailbox.
This selection option takes one or more entry/attribute/value triples
to use as tests. A mailbox matches this criteria if it has an entry,
attribute and value matching the ones specified. In the case of
multiple criteria being specified, mailbox MUST only match when all
criteria match ("and" operation). To test for the existence of an

Daboo Expires June 24, 2008 [Page 11]

Internet-Draft IMAP METADATA Extension December 2007

entry, a test for the attribute "value" with the empty string "" as
the value argument can be used. To test for the absence of an entry,
a test for the attribute "value" with NIL as the value argument can
be used. Clients SHOULD only use entries defined with a "text"
Content-Type in the selection option arguments.

Each entry/attribute/value triple specified in the selection option
MAY include a match type specifier and MAY include a collation
[I-D.ietf-imapext-i18n] identifier. If the match type is specified,
then that match operation MUST be used when matching the provided
value with the corresponding annotation entry values in mailboxes.
If the match type is not specified, then a default of "CONTAINS"
(substring match) MUST be used. If the collation identifier is
specified, then that collation MUST be used to do the comparison of
the annotation entry values being tested. If the collation
identifier is not specified, then the active collation as defined by
[I-D.ietf-imapext-i18n] is used. If the client specifies a collation
identifier not known to the server, the server MUST return a BAD
response. Possible values for the match type are:

+----------+-----------------------------------------------+
| Match | Description |
+----------+-----------------------------------------------+
| IS | Equality test is done |
| CONTAINS | Substring match is done |
| GT | Greater than relational test is done |
| GE | Greater than or equal relational test is done |
| LE | Less than or equal relational test is done |
| LT | Less than relational test is done |
+----------+-----------------------------------------------+

The "NOT" match type modifier results in a negation of the comparison
- i.e. it adds the ability to search for annotations that do not
match or contain specific text.

The LIST-EXTENDED "METADATA" return option type is used to request
that the extended LIST command return specific annotation entries for
each mailbox returned in the LIST responses. A list of entries and
attributes to return can be specified in a manner similar to the
GETMETADATA command.

Example:

C: a LIST "" "INBOX" RETURN (METADATA (/comment value.priv))
S: * LIST "/" "INBOX"
(METADATA (/comment (value.priv "My comment")))
S: a OK LIST complete

Daboo Expires June 24, 2008 [Page 12]

Internet-Draft IMAP METADATA Extension December 2007

In the above example, the contents of the "value.priv" attribute
for the "/comment" entry for the same name as a previously
existing mailbox INBOX is requested by the
client and returned by the server.

Example:

C: a LIST "" "INBOX" RETURN (METADATA (/* value.priv))
S: * LIST "/" "INBOX"
(METADATA (/comment (value.priv "My comment")
/check (value.priv "true")))
S: a OK LIST complete

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

Example:

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

In the above example, the contents annotations.

Servers SHOULD allow annotations on all 'types' of the "value" attributes for
entries mailbox, including
ones reporting \Noselect for the mailbox INBOX at the top level of the entry
hierarchy only, their LIST response. Servers can
implicitly remove \Noselect mailboxes when all child mailboxes are requested by the client and returned by the
server. Both the .priv
removed, 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 LIST
command.

Example:

Daboo Expires June 24, 2008 [Page 13]

Internet-Draft IMAP METADATA Extension December 2007

C: a LIST "" "INBOX" RETURN (METADATA ((/comment /motd)
value.priv))
S: * LIST "/" "INBOX"
(METADATA (/comment (value.priv "My comment")
/motd (value.priv "Its sunny outside!")))
S: a OK LIST complete

In such any annotations associated with the above example, \Noselect
mailbox SHOULD be removed.

The server is allowed to impose limitations on the contents size of any one
annotation or the "value.priv" attributes
for the two entries "/comment" and "/motd" total number of annotations for the a single mailbox INBOX
are requested by the client and returned by or
for the server.

Example:

C: a LIST "" "INBOX" RETURN (METADATA (/comment
(value.priv size.priv)))
S: * LIST "/" "INBOX"
(METADATA (/comment (value.priv "My comment"
size.priv "10")))
S: server as a OK LIST complete

In the above example, whole. However, the contents server MUST accept a minimum
annotation data size of the "value.priv" at least 1024 bytes, and
"size.priv" attributes for the "/comment" entry for the a minimum annotation
count per server or mailbox
INBOX of at least 10.

Some annotations may be "read-only" - i.e. they are requested set by the client server
and returned cannot be changed by the server.

Example:

C: a LIST "" ("INBOX" "FOOBOX" "BARBOX") RETURN
(METADATA (/comment value.priv))
S: * LIST "/" "INBOX"
(METADATA (/comment (value.priv "My comment")))
S: * LIST "/" "FOOBOX"
(METADATA (/comment (value.priv "Another comment")))
S: * LIST "/" "BARBOX"
(METADATA (/comment (value.priv NIL)))
S: a OK LIST complete

In client. Also, such annotations may be
"computed" - i.e. the above value changes based on underlying properties of
the mailbox or server. For example, an annotation reporting the contents
total size of all messages in the "value.priv" attribute mailbox would change as messages
are added or removed. Or, an annotation containing an IMAP URL for
the "/comment" entry for mailbox would change if the mailboxes INBOX, FOOBOX and
BARBOX mailbox was renamed.

This extension defines some unsolicited responses for use when
annotations are requested changed by some "third-party" (see Section 4.4). The
server MUST only send these unsolicited responses if the client and returned by used
the server.
Note that ENABLE command [RFC5161] extension with the capability string
"METADATA" earlier in the session.

4.2. GETMETADATA Command

This extension adds the GETMETADATA command. This allows clients to
retrieve server or mailbox BARBOX does not contain the entry, hence NIL annotations.

This command is returned for the attribute value.

Example:

C: a LIST (METADATA ("/comment" "value" "comm"
(NOT CONTAINS))) "" "*"
S: * LIST () "/" "INBOX"
S: * LIST (\NoInferiors) "/" "FOOBOX" only available in authenticated or selected state
[RFC3501].

Daboo Expires June 24, October 23, 2008 [Page 14] 7]

Internet-Draft IMAP METADATA Extension December 2007

S: a April 2008

Arguments: mailbox-name
entry-specifier

Responses: required METADATA response

Result: OK LIST complete

In the above example, the client requests that any mailbox in the
entire hierarchy that does not contain the text "comm" in any
"value" attribute of the "/comment" entry be returned. Two
mailboxes are returned in separate responses. Note that the
client did not ask for - command completed
NO - command failure: can't access annotations to be returned in the
responses.

Example:

C: a LIST (METADATA ("/comment" "value" ""))
"" "*"
S: * LIST () "/" "INBOX"
S: * LIST (\NoInferiors) "/" "FOOBOX"
S: a OK LIST complete

In on
the above example, server
BAD - command unknown or arguments invalid

When the client requests that any mailbox in the
entire hierarchy containing name is the "/comment" entry be returned. Two
mailboxes are returned in separate responses. Note that empty string, this command retrieves
server annotations. When the
client did mailbox name is not ask for empty, this command
retrieves annotations to be returned in on the
responses. specified mailbox.

Example:

C: a LIST (METADATA ("/comment" "value" NIL)) GETMETADATA "" "*" /public/comment
S: * LIST (\NoInferiors) "/" "BARBOX" METADATA "" (/public/comment "Shared comment")
S: a OK LIST GETMETADATA complete

In the above example, the client requests that any mailbox in contents of the
entire hierarchy that does not have a "/comment" value of the "/public/
comment" server entry be
returned. One mailbox is returned in a response. Note that requested by the client did not ask for annotations to be and returned in by
the
responses. server.

Example:

C: a LIST (METADATA ("/comment" "value" "HELP"
(IS "i;octet")) "" "*"
RETURN (METADATA (/comment size.priv))
S: * LIST "/" GETMETADATA "INBOX"
(METADATA (/comment (size.priv "10"))) /private/comment
S: * LIST "/" "FOOBOX"
(METADATA (/comment (size.priv "15")))
S: a OK LIST complete

Daboo Expires June 24, 2008 [Page 15]

Internet-Draft IMAP METADATA Extension December 2007 "INBOX" (/private/comment "My own comment")
S: a OK GETMETADATA complete

In the above example, the client requests that any mailbox in the
entire hierarchy with contents of the exact text "HELP" in any "value"
attribute value of the "/comment" "/private/
comment" mailbox entry be returned. The client
provides an explicit match type and collation identifier. Two
mailboxes are returned in separate responses. The client also
asked for annotation sizes to be returned in the responses.

4.3.1. Unsolicited LIST response

Subject to unsolicited responses being activated by the ENABLE
[I-D.gulbrandsen-imap-enable] command for this extension, servers
SHOULD send unsolicited LIST responses if mailbox annotations are
changed by a third-party, allowing servers to keep clients updated
with changes. Unless explicitly changed "INBOX" is requested by an IMAP extension,
unsolicited mailbox annotations MUST only be returned for the
currently selected mailbox.

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

The LIST response server.

Entry specifiers can contain be lists of atomic specifiers, so that multiple entries
annotations may be returned in a single response,
but the server is free to return multiple responses for each entry or
group of entries if it desires. GETMETADATA command.

Example:

C: a NOOP GETMETADATA "INBOX" (/public/comment /private/comment)
S: * LIST "/" METADATA "INBOX" (METADATA (/comment)) (/public/comment "Shared comment"
/private/comment "My own comment")
S: a OK NOOP GETMETADATA complete

In the above example, the server sends an unsolicited LIST
response indicating that the "/comment" entry values of the two server entries
"/public/comment" and "/private/comment" on the mailbox
"INBOX" has been changed.

4.4. "inbox"
are requested by the client and returned by the server.

Daboo Expires October 23, 2008 [Page 8]

Internet-Draft IMAP METADATA Extension April 2008

4.3. SETMETADATA Command

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

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

Daboo Expires June 24, 2008 [Page 16]

Internet-Draft IMAP METADATA Extension December 2007

Arguments: mailbox-name
entry
attribute-value
value
list of entry, attribute-values 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

This command sets the specified list of entries by adding or
replacing the specified attributes with the values provided, on the specified existing
mailboxes or on the server (if the mailbox argument is the empty
string). Clients can use NIL for values the value of
attributes entries it wants to remove from entries. to
remove. The server SHOULD NOT return a METADATA or LIST response containing
the updated annotation data. Clients MUST NOT assume that a METADATA or LIST
response will be sent, and MUST assume that if the command succeeds
then the annotation has been changed.

If the server is unable to set an annotation because the size of its
value is too large, the server MUST return a tagged NO response with
a "[METADATA TOOBIG]" MAXSIZE NNN]" response code. code when NNN is the maximum
octet count that it is willingly to accept.

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

If the server is unable to set a new annotation because it does not
support private annotations on one of the specified mailboxes, the
server MUST return a tagged NO response with a "[METADATA NOPRIVATE]"
response code.

Example:

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

Daboo Expires October 23, 2008 [Page 9]

Internet-Draft IMAP METADATA Extension April 2008

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

Example:

Daboo Expires June 24, 2008 [Page 17]

Internet-Draft IMAP METADATA Extension December 2007

C: a SETMETADATA INBOX /comment (value.priv (/private/comment NIL)
S: a OK SETMETADATA complete

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

Annotations on multiple mailboxes can be set in a single SETMETADATA
command by using a wildcard specification for the mailbox name.

Example:

C: a SETMETADATA INBOX.% /comment
(value.priv "My new comment")
S: a OK SETMETADATA 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 attribute "value" are created
respectively for each entry if not already present, or replaced if
they previously existed.

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

Example:

C: a SETMETADATA INBOX (/comment
(value.priv (/private/comment "My new comment")
/thread
(value.priv "REFERENCES ALL")) comment"
/public/comment "This one is for you!")
S: a OK SETMETADATA complete

In the above example, the entries "/comment" "/private/comment" and "/thread" "/public/
comment" for the mailbox "INBOX" are created (if not already
present) and the
"value.priv" attributes are created respectively for each entry if
not already present, or replaced if they previously existed.

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

Example:

C: a SETMETADATA INBOX /comment
(value.priv "My new comment"
value.shared "foo's bar")
S: a OK SETMETADATA complete

Daboo Expires June 24, 2008 [Page 18]

Internet-Draft IMAP METADATA Extension December 2007

In the above example, the entry "/comment" for the mailbox "INBOX"
is created (if not already present) and the attributes
"value.priv" and "value.shared" are created if not already
present, or replaced if they previously existed. as specified.

Example:

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

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

4.5.

4.4. METADATA Response

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

Subject to unsolicited responses being activated by the ENABLE
[I-D.gulbrandsen-imap-enable]
[RFC5161] command for this extension, servers SHOULD send unsolicited
METADATA responses if server or mailbox annotations are changed by a
third-party, allowing servers to keep clients updated with changes.

Unsolicited METADATA 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 GETMETADATA command.

Daboo Expires October 23, 2008 [Page 10]

Internet-Draft IMAP METADATA Extension April 2008

The METADATA 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 or selected state
[RFC3501].

4.5.1.

4.4.1. METADATA response with attributes and values

The response consists of a list of entries each

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

Example:

C: a GETMETADATA /comment value.priv "" /public/comment
S: * METADATA /comment (value.priv "" (/public/comment "My comment")
S: a OK GETMETADATA complete

Daboo Expires June 24, 2008 [Page 19]

Internet-Draft IMAP METADATA Extension December 2007

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

Example:

C: a GETMETADATA (/comment /motd) value.priv "INBOX" /private/comment /public/comment
S: * METADATA /comment (value.priv "INBOX" (/private/comment "My comment")
/motd (value.priv comment"
/public/comment "Its sunny outside!")
S: a OK GETMETADATA complete

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

Example:

C: a GETMETADATA (/comment /motd) value.priv "INBOX" /private/comment /public/comment
S: * METADATA /comment (value.priv "INBOX" (/private/comment "My comment")
S: * METADATA /motd (value.priv "INBOX" (/public/comment "Its sunny outside!")
S: a OK GETMETADATA complete

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

Example:

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

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

4.5.2.

4.4.2. Unsolicited METADATA response without attributes and values

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

Example:

Daboo Expires October 23, 2008 [Page 11]

Internet-Draft IMAP METADATA Extension April 2008

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

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

Example:

Daboo Expires June 24, 2008 [Page 20]

Internet-Draft IMAP METADATA Extension December 2007

C: a NOOP
S: * METADATA (/comment /motd) "INBOX" /public/comment /private/comment
S: a OK NOOP complete

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

5. Formal Syntax

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

Non-terminals referenced but not defined below are as defined by
[RFC3501] with the new definitions in [RFC4466] superseding those in
[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 = "METADATA" SP entry-list

att-select = "value" / "value.priv" / "value.shared"
; the only attributes that can be selected

att-value = attrib SP value

attrib = astring
; dot-separated attribute name
; MUST NOT contain "*" or "%"

attribs = attrib / "(" attrib *(SP attrib) ")"
; one or more attribute specifiers

Daboo Expires October 23, 2008 [Page 12]

Internet-Draft IMAP METADATA Extension April 2008

capability =/ "METADATA" / "METADATA-SERVER"
; defines the capabilities for this extension

command-auth =/ setmetadata / getmetadata
; adds to original IMAP command

collation = astring
; collation identifier as defined by
; [RFC4790]

entries = entry-match entry /
"(" entry-match entry *(SP entry-match) entry) ")"

Daboo Expires June 24, 2008 [Page 21]

Internet-Draft IMAP METADATA Extension December 2007
; entry specifiers that can include wildcards

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

entry-att

entry-value = entry SP value

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

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

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

getmetadata = "GETMETADATA" SP entries SP attribs

list-select-base-opt =/ "METADATA" SP
"(" list-select-metadata
*(SP list-select-metadata) ")"
; adds a new selection option type to
; LIST-EXTENDED. When evaluating multiple entry,
; attribute, value combinations, a match to used in unsolicited
; a mailbox must occur when all items match.

list-select-metadata METADATA response

getmetadata = entry-match "GETMETADATA" SP att-select mailbox SP value
[SP "(" matchtype [SP collation] ")"] entries
; value set to the empty string means match
; if that entry and attribute exist.
; value set to NIL means match if that entry
; and attribute do not exist.
; An optional match type and collation can also for mailbox implies
; be specified.

matchtype server annotation.

metadata-resp = ["NOT" SP] ("IS" / "CONTAINS" /
"GT" / "GE" / "LE" "METADATA" SP mailbox SP
(entry-values / "LT") entry-list)
; match types for LIST-EXTENDED empty string for mailbox implies
; comparisons - see Section 4.3. server annotation.

response-payload =/ annotate-data metadata-resp
; adds to original IMAP data responses

resp-text-code =/ "METADATA" SP ("TOOBIG" ("MAXSIZE" SP number /
"TOOMANY" /

Daboo Expires June 24, 2008 [Page 22]

Internet-Draft IMAP METADATA Extension December 2007 "NOPRIVATE")
; new response codes for SETMETADATA
; failures

setmetadata = "SETMETADATA" SP list-mailbox mailbox
SP setentryatt entry-values
; empty string for list-mailbox mailbox implies
; server annotation.

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

value = nstring / literal8

Daboo Expires October 23, 2008 [Page 13]

Internet-Draft IMAP METADATA Extension April 2008

6. IANA Considerations

Entry names MUST be specified in a standards track or IESG approved
experimental RFC, or fall under the vendor namespace. All entries
MUST have either "/public" or "/private" as a prefix.

Each entry registration MUST include a content-type that is used to
indicate the nature of the annotation value. Where applicable a
charset parameter MUST be included with the content-type.

6.1. Entry and Attribute Registration Template

To: iana@iana.org
Subject: IMAP METADATA Entry Registration

Type: [Either "Mailbox" or "Server"]

Name: [the name of the entry]

Description: [a description of what the entry is for]

Content-type: [MIME Content-Type and charset for the entry value]

RFC Number: [for entries published as RFCs]

Contact: [email and/or physical address to contact for
additional information]

6.2. Server Entry Registrations

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

Daboo Expires June 24, 2008 [Page 23]

Internet-Draft IMAP METADATA Extension December 2007

6.2.1. /comment

To: iana@iana.org
Subject: IMAP METADATA Entry Registration

Type: Server

Name: /comment

Description: Defined in IMAP METADATA extension document.

Content-type: text/plain; charset=utf-8

RFC Number: This RFC.

Contact: IMAP Extensions <ietf-imapext@imc.org>

6.2.2. /motd

To: iana@iana.org
Subject: IMAP METADATA Entry Registration

Type: Server

Name: /motd

Description: Defined in IMAP METADATA extension document.

Content-type: text/plain; charset=utf-8

RFC Number: This RFC.

Contact: IMAP Extensions <ietf-imapext@imc.org>

Daboo Expires June 24, 2008 [Page 24]

Internet-Draft IMAP METADATA Extension December 2007

6.2.3. /admin

To: iana@iana.org
Subject: IMAP METADATA Entry Registration

Type: Server

Name: /admin

Description: Defined in IMAP METADATA extension document.

Content-type: text/plain; charset=utf-8

RFC Number: This RFC.

Contact: IMAP Extensions <ietf-imapext@imc.org>

6.3. Mailbox Entry Registrations

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

6.3.1. /comment

To: iana@iana.org
Subject: IMAP METADATA Entry Registration

Type: Mailbox

Name: /comment

Description: Defined in IMAP METADATA extension document.

Content-type: text/plain; charset=utf-8

RFC Number: This RFC.

Contact: IMAP Extensions <ietf-imapext@imc.org>

Daboo Expires June 24, October 23, 2008 [Page 25] 14]

Internet-Draft IMAP METADATA Extension December 2007

6.3.2. /sort April 2008

6.2.1. /public/comment

To: iana@iana.org
Subject: IMAP METADATA Entry Registration

Type: Mailbox Server

Name: /sort /public/comment

Description: Defined in IMAP METADATA extension document. Defines a comment or note associated with the server
shared with all users of the server.

Content-type: text/plain; charset=utf-8

RFC Number: This RFC.

Contact: IMAP Extensions <ietf-imapext@imc.org>

6.3.3. /thread

6.2.2. /public/admin

To: iana@iana.org
Subject: IMAP METADATA Entry Registration

Type: Mailbox Server

Name: /thread /public/admin

Description: Defined in IMAP METADATA extension document. Indicates a method for contacting the server
administrator. The value MUST be a URI (e.g., a
mailto: or tel: URL). This entry is always
read-only - clients cannot change it. It is visible
to all users of the system.

Content-type: text/plain; charset=utf-8

RFC Number: This RFC.

Contact: IMAP Extensions <ietf-imapext@imc.org>

6.3. Mailbox Entry Registrations

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

Daboo Expires June 24, October 23, 2008 [Page 26] 15]

Internet-Draft IMAP METADATA Extension December 2007

6.3.4. /check April 2008

6.3.1. /public/comment

To: iana@iana.org
Subject: IMAP METADATA Entry Registration

Type: Mailbox

Name: /check /public/comment

Description: Defined in IMAP METADATA extension document. Defines a public comment or note associated with a
mailbox.

Content-type: text/plain; charset=utf-8

RFC Number: This RFC.

Contact: IMAP Extensions <ietf-imapext@imc.org>

6.3.5. /checkperiod

6.3.2. /private/comment

To: iana@iana.org
Subject: IMAP METADATA Entry Registration

Please register the following IMAP METADATA entry:

Type: Mailbox

Name: /checkperiod /private/comment

Description: Defined in IMAP METADATA extension document. Defines a public comment or note associated with a
mailbox.

Content-type: text/plain; charset=utf-8

RFC Number: This RFC.

Contact: IMAP Extensions <ietf-imapext@imc.org>

6.4. LIST-EXTENDED Registration

To: iana@iana.org
Subject: Registration of LIST-EXTENDED option METADATA

LIST-EXTENDED option name: METADATA

LIST-EXTENDED option type: SELECTION

Implied return options(s): (none)

LIST-EXTENDED option description:

Daboo Expires June 24, 2008 [Page 27]

Internet-Draft IMAP METADATA Extension December 2007

The "METADATA" selection option type is used to request
that the extended LIST command match mailboxes which have
an annotation with a specific entry and value. It can
also be used to test for the existence of a particular
annotation entry on a mailbox.

Published specification : XXXX, Section 4.3.

Security considerations: XXXX, Section 7.

Intended usage: COMMON

Person and email address to contact for further information:
IMAP Extensions <ietf-imapext@imc.org>

Owner/Change controller: iesg@ietf.org

To: iana@iana.org
Subject: Registration of LIST-EXTENDED option METADATA

LIST-EXTENDED option name: METADATA

LIST-EXTENDED option type: RETURN

LIST-EXTENDED option description: Causes the LIST command to
return the specified mailbox annotations.

Published specification : XXXX, Section 4.3.

Security considerations: XXXX, Section 7.

Intended usage: COMMON

Person and email address to contact for further information:
IMAP Extensions <ietf-imapext@imc.org>

Owner/Change controller: iesg@ietf.org

7. Security Considerations

Annotations whose values are intended to remain private MUST use
.priv values, and not .shared values which may be accessible to other
users.
stored only in entries that have the "/private" prefix on the entry
name.

Annotations can contain arbitrary sized data. As such servers MUST

Daboo Expires June 24, 2008 [Page 28]

Internet-Draft IMAP METADATA Extension December 2007
ensure that size limits are enforced to prevent a user from using up
all available space on a server and preventing use by others.

Excluding the above issues the METADATA extension does not raise any

Daboo Expires October 23, 2008 [Page 16]

Internet-Draft IMAP METADATA Extension April 2008

security considerations that are not present in the base IMAP
protocol, and these issues are discussed in [RFC3501].

8. References

8.1. Normative References

[I-D.gulbrandsen-imap-enable]
Gulbrandsen, A. and A. Melnikov, "The IMAP ENABLE
Extension", draft-gulbrandsen-imap-enable-05 (work in
progress), December 2007.

[I-D.ietf-imapext-i18n]
Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet
Message Access Protocol Internationalization",
draft-ietf-imapext-i18n-14 (work in progress),
December 2007.

[I-D.ietf-imapext-list-extensions]
Leiba, B. and A. Melnikov, "IMAP4 LIST Command
Extensions", draft-ietf-imapext-list-extensions-18 (work
in progress), September 2006.

[I-D.ietf-imapext-sort]
Crispin, M. and K. Murchison, "INTERNET MESSAGE ACCESS
PROTOCOL - SORT AND THREAD EXTENSIONS",
draft-ietf-imapext-sort-19
draft-ietf-imapext-i18n-15 (work in progress),
September 2007.
February 2008.

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

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

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

[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.

[RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 4234, October 2005.

Daboo Expires June 24, 2008 [Page 29]

Internet-Draft IMAP METADATA Extension December 2007

[RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
ABNF", RFC 4466, April 2006.

[RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
Application Protocol Collation Registry", RFC 4790,
March 2007.

[RFC5051] Crispin, M., "i;unicode-casemap - Simple Unicode Collation
Algorithm", RFC 5051, October 2007.

8.2. Informative References

[I-D.ietf-imapext-annotate]
Gellens, R.

[RFC5161] Gulbrandsen, A. and C. Daboo, "IMAP ANNOTATE A. Melnikov, "The IMAP ENABLE
Extension",
draft-ietf-imapext-annotate-16 (work in progress),
October 2006.

[RFC2177] Leiba, B., "IMAP4 IDLE command", RFC 2177, June 1997. 5161, March 2008.

[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.

Appendix A. Acknowledgments

The ideas expressed in this document are based on the message
annotation document that was co-authored by Randall Gellens. The
participants of the IMAPext working group made significant
contributions to this work.

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

Changes from -12 to -13:

Daboo Expires October 23, 2008 [Page 17]

Internet-Draft IMAP METADATA Extension April 2008

1. Major changes to simplify things.
2. Removed dependency on LISTEXT - GETMETADATA now used to get
annotations on mailboxes.
3. Changed data model to remove attributes - annotations are now
only entry-value pairs.
4. Removed all wildcard behavior on entry names.
5. Cut down the registered annotations to only a few essential ones.

Changes from -11 to -12:
1. Allow server annotations to be used without mailbox annotations.
2. Require i;unicode-casemap when COMPARATOR is not present.
3. Use ENABLE to turn on unsolicited responses.
4. Use formal syntax elements from SORT/THREAD extensions to define
the values for /sort and /thread entries.
5. Added a comment that use of IDLE is preferred even when /check
is true.
6. Use formal syntax element from base spec for the /size value.
7. Removed IANA registration for attributes as we don't expect any
more to be defined.
8. Tweaked IANA registration template to be more compact and add
RFC Number reference.
9. Some minor re-phrasing was done.
10. Added text about handling of annotations on INBOX when it is
renamed.

Daboo Expires June 24, 2008 [Page 30]

Internet-Draft IMAP METADATA Extension December 2007
11. Require a BAD response when an unknown collation is used in
LISTEXT selection option.

Changes from -10 to -11:
1. Added new paragraph to indicate that values may be read-only or
computed.
2. /admin server annotation value now must be a URI.
3. Clarified that SORT and THREAD extensions are not required.
4. Fixed use of undefined entries in some examples.
5. Fixed many examples.
6. Added IANA registration for LIST-EXTENDED items.
7. Added match type and collation identifier to the LIST-EXTENDED
selection option.
8. Made support for IMAP-I18N a requirement.
9. Minor text clarifications applied.
10. Remove mailbox list set atomicity requirement.
11. Clarified that annotations can only be set on mailboxes that
actually exist.

Changes from -09 to -10:
1. Updated to rfc 4466 reference.
2. Reworded data model description.

Daboo Expires October 23, 2008 [Page 18]

Internet-Draft IMAP METADATA Extension April 2008

3. Reworked LIST-EXTENDED so that responses have metadata items
after the mailbox info.
4. Various spelling fixes.

Changes from -08 to -09:
1. Remove content-language attribute and reference.
2. Changed capability and command names.
3. Revised abstract.

Changes from -07 to -08:
1. Changed 'string' formal syntax to 'list-mailbox' and 'astring'
for entry/attribute names.
2. Updated examples to match new astring syntax.
3. Changed CAPABILITY name due to incompatible syntax change.
4. Removed content-type attribute.
5. Added Content-type to IANA registration for entries.
6. Removed vendor attributes.
7. Fixed examples in section 3.3 for multi-mailbox and multi-entry
cases.
8. Removed wildcards for attributes.
9. Entry/attributes can now only be ASCII.
10. Tied up text wrt storing/fetching.
11. Added Conventions section
12. Entry/attributes MUST NOT contain consecutive or trailing '/' or
'.'.

Daboo Expires June 24, 2008 [Page 31]

Internet-Draft IMAP METADATA Extension December 2007
13. Changed to use IMAP ABNF extensions document for some formal
syntax items.

Changes from -06 to -07:
1. Reworded /checkperiod item.
2. Clarified unsolicited response behavior.

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:

Daboo Expires October 23, 2008 [Page 19]

Internet-Draft IMAP METADATA Extension April 2008

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 behavior of unsolicited responses.
3. Adding SHOULD behavior 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
parenthesized list of entries.

Daboo Expires June 24, 2008 [Page 32]

Internet-Draft IMAP METADATA Extension December 2007
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
account for this change.
6. Added comment and example for ANNOTATION response to allow
servers to return separate responses for each entry if desired.

Author's Address

Cyrus Daboo
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
USA

Email: cyrus@daboo.name
URI: http://www.apple.com/

Daboo Expires June 24, October 23, 2008 [Page 33] 20]

Internet-Draft IMAP METADATA Extension December 2007 April 2008

Full Copyright Statement

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.

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, THE IETF TRUST 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.

Intellectual Property

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.

Acknowledgment

Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).

Daboo Expires June 24, October 23, 2008 [Page 34] 21]

----