rfc9590.original.xml   rfc9590.xml 
<?xml version='1.0' encoding='utf-8'?> <?xml version='1.0' encoding='UTF-8'?>
<!-- pre-edited by ST 04/08/24 -->
<!-- draft submitted in xml v3 -->
<!DOCTYPE rfc [ <!DOCTYPE rfc [
<!ENTITY nbsp "&#160;"> <!ENTITY nbsp "&#160;">
<!ENTITY zwsp "&#8203;"> <!ENTITY zwsp "&#8203;">
<!ENTITY nbhy "&#8209;"> <!ENTITY nbhy "&#8209;">
<!ENTITY wj "&#8288;"> <!ENTITY wj "&#8288;">
]> ]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes"?> <rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="std" ipr="trust200902"
<?rfc symrefs="yes"?> docName="draft-ietf-extra-imap-list-metadata-05"
<?rfc sortrefs="yes"?> number="9590" obsoletes="" updates="" submissionType="IETF" xml:lang="en" tocInc
<?rfc compact="yes"?> lude="true" symRefs="true" sortRefs="true" consensus="true" version="3">
<?rfc strict="yes"?>
<rfc xmlns:xi="http://www.w3.org/2001/XInclude"
category="std"
ipr="trust200902"
docName="draft-ietf-extra-imap-list-metadata-05"
obsoletes=""
updates=""
submissionType="IETF"
xml:lang="en"
tocInclude="true"
symRefs="true"
sortRefs="true"
consensus="true"
version="3">
<!-- xml2rfc v2v3 conversion 3.14.2 -->
<front> <front>
<title abbrev="IMAP LIST-METADATA">IMAP4 Extension for Returning <title abbrev="IMAP LIST-METADATA">IMAP Extension for Returning
Mailbox METADATA in Extended LIST</title> Mailbox METADATA in Extended LIST</title>
<seriesInfo name="Internet-Draft" <seriesInfo name="RFC" value="9590"/>
value="draft-ietf-extra-imap-list-metadata-05"/>
<author initials="K." surname="Murchison" fullname="Kenneth Murchison"> <author initials="K." surname="Murchison" fullname="Kenneth Murchison">
<organization abbrev="Fastmail">Fastmail US LLC</organization> <organization abbrev="Fastmail">Fastmail US LLC</organization>
<address> <address>
<postal> <postal>
<street>1429 Walnut Street - Suite 1201</street> <street>1429 Walnut Street</street>
<city>Philadelphia</city> <region>PA</region> <street>Suite 1201</street>
<code>19102</code> <country>USA</country> <city>Philadelphia</city>
<region>PA</region>
<code>19102</code>
<country>United States of America</country>
</postal> </postal>
<email>murch@fastmailteam.com</email> <email>murch@fastmailteam.com</email>
</address> </address>
</author> </author>
<author initials="B." surname="Gondwana" fullname="Bron Gondwana"> <author initials="B." surname="Gondwana" fullname="Bron Gondwana">
<organization abbrev="Fastmail">Fastmail Pty Ltd</organization> <organization abbrev="Fastmail">Fastmail Pty Ltd</organization>
<address> <address>
<postal> <postal>
<street>Level 2, 114 William Street</street> <street>Level 2, 114 William Street</street>
<city>Melbourne</city> <city>Melbourne</city>
<region>VIC</region> <region>VIC</region>
<code>3000</code> <code>3000</code>
<country>Australia</country> <country>Australia</country>
</postal> </postal>
<email>brong@fastmailteam.com</email> <email>brong@fastmailteam.com</email>
</address> </address>
</author> </author>
<date/> <date year="2024" month="May"/>
<area>ART</area> <area>ART</area>
<workgroup>EXTRA</workgroup> <workgroup>extra</workgroup>
<keyword>IMAP4</keyword> <keyword>IMAP4</keyword>
<keyword>LIST</keyword> <keyword>LIST</keyword>
<keyword>METADATA</keyword> <keyword>METADATA</keyword>
<abstract> <abstract>
<t>This document defines an extension to the to IMAP LIST <t>This document defines an extension to the Internet Message Access Prot ocol (IMAP) LIST
command that allows the client to request mailbox annotations command that allows the client to request mailbox annotations
(metadata), along with other information typically returned by (metadata), along with other information typically returned by
the LIST command.</t> the LIST command.</t>
</abstract> </abstract>
</front> </front>
<middle> <middle>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Introduction</name> <name>Introduction</name>
<t>IMAP clients sometimes fetch mailbox metadata (e.g. color) to <t>IMAP clients sometimes fetch mailbox metadata (e.g., color) to
augment the display of mailboxes to the logged-in user. augment the display of mailboxes for the logged-in user.
In order to do that, the client is In order to do that, the client is
forced to issue a LIST or LSUB command to list all available forced to issue a LIST or LSUB command to list all available
mailboxes, followed by a GETMETADATA command for each mailbox mailboxes, followed by a GETMETADATA command for each mailbox
found. This document defines an extension to the to IMAP LIST found. This document defines an extension to the IMAP LIST
command that is identified by the capability string command that is identified by the capability string
"LIST-METADATA". The LIST-METADATA extension allows the client "LIST-METADATA". The LIST-METADATA extension allows the client
to request annotations on available mailboxes, along with other to request annotations on available mailboxes, along with other
information typically returned by the LIST command.</t> information typically returned by the LIST command.</t>
</section> <!-- Intro --> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Conventions Used in This Document</name> <name>Conventions Used in This Document</name>
<t>In examples, "C:" indicates lines sent by a client that is connected <t>In examples, "C:" indicates lines sent by a client that is connected
to a server. "S:" indicates lines sent by the server to the to a server. "S:" indicates lines sent by the server to the
client.</t> client.</t>
<t>
The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>",
"<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>
",
"<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>",
"<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
"<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to
be
interpreted as described in BCP&nbsp;14 <xref target="RFC2119"/> <xref
target="RFC8174"/> when, and only when, they appear in all capitals, as
shown here.
</t>
<t>
Long lines in examples are wrapped using "The Single Backslash Strategy" des
cribed in <xref target="RFC8792"/>.
</t>
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL </section>
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in BCP&nbsp;14 <xref target="RFC2119"/>
<xref target="RFC8174"/>
when, and only when, they appear in all capitals, as shown here.
</t>
</section> <!-- Conventions -->
<section anchor="metadata" numbered="true" toc="default"> <section anchor="metadata" numbered="true" toc="default">
<name>METADATA Return Option to LIST Command</name> <name>METADATA Return Option to LIST Command</name>
<t><xref target="RFC5464"/> defines the <t><xref target="RFC5464"/> defines the
GETMETADATA command which is GETMETADATA command that is
used by an IMAP client to retrieve mailbox annotations. used by an IMAP client to retrieve mailbox annotations.
Sometimes, Sometimes,
a client will have to look up the metadata for some or all of a client will have to look up the metadata for some or all of
the mailboxes returned by the LIST command. Doing so in the mailboxes returned by the LIST command. Doing so in
multiple GETMETADATA commands wastes bandwidth and can degrade multiple GETMETADATA commands wastes bandwidth and can degrade
performance if the client does not pipeline the requests.</t> performance if the client does not pipeline the requests.</t>
<t>This document extends the LIST command with a new return option, <t>This document extends the LIST command with a new return option,
"METADATA", which allows the client to request all of the "METADATA", which allows the client to request all of the
desired information in a single command. For each listable desired information in a single command. For each listable
mailbox matching the list pattern and selection options, the mailbox matching the list pattern and selection options, the
server MUST return an untagged LIST response followed by one or more server <bcp14>MUST</bcp14> return an untagged LIST response, followed by o ne or more
untagged METADATA responses containing the mailbox annotations untagged METADATA responses containing the mailbox annotations
requested by the client. requested by the client.
The untagged METADATA responses to an extended LIST command have The untagged METADATA responses to an extended LIST command have
the same syntax and semantics as those that would be returned by the same syntax and semantics as those that would be returned by
GETMETADATA commands on the same set of listable mailboxes GETMETADATA commands on the same set of listable mailboxes
(see <xref target="RFC5464" section="4.4.1"/>). (see <xref target="RFC5464" section="4.4.1"/>).
As per <xref target="RFC5464" section="4.4"/>, the server may As per <xref target="RFC5464" section="4.4"/>, the server may
return all requested annotations in a single METADATA response return all requested annotations in a single METADATA response
for each mailbox, or it may split the requested annotations into for each mailbox, or it may split the requested annotations into
multiple METADATA responses for each mailbox.</t> multiple METADATA responses for each mailbox.</t>
<t>If the server is unable to look up the annotations for <t>If the server is unable to look up the annotations for
given mailbox, it MAY drop the corresponding METADATA response. given mailbox, it <bcp14>MAY</bcp14> drop the corresponding METADATA respo nse.
In such a situation, the LIST command would still return a tagged In such a situation, the LIST command would still return a tagged
OK reply.</t> OK reply.</t>
</section> <!-- METADATA --> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Examples</name> <name>Examples</name>
<t>The following are examples of fetching metadata of
only the top level of the mailbox hierarchies with different <t>The following are examples of fetching metadata from only
the top-level hierarchies of the mailbox using different
sets of selection criteria sets of selection criteria
(see <xref target="RFC9051" section="6.3.9"/>).</t> (see <xref target="RFC9051" section="6.3.9"/>).</t>
<t keepWithNext="true"> <t keepWithNext="true">
In this example: In this example:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li>The "color" annotation for the "foo" mailbox has not been <li>The "color" annotation for the "foo" mailbox has not been
set, so the METADATA response has a value of "NIL" (has no set, so the METADATA response has a value of "NIL" (i.e., has no
value).</li> value).</li>
<li>"bar" has children, but isn't an actual mailbox itself, <li>"bar" has children, but isn't an actual mailbox itself,
so it has no METADATA response.</li> so it has no METADATA response.</li>
</ul> </ul>
<t>NOTE: '\' line wrapping per <xref target="RFC8792"/></t>
<artwork name="" type="" align="left" alt=""><![CDATA[ <artwork name="" type="" align="left" alt=""><![CDATA[
========== NOTE: '\' line wrapping per RFC 8792 ===========
C: A00 CAPABILITY C: A00 CAPABILITY
S: * CAPABILITY IMAP4rev1 IMAP4rev2 \ S: * CAPABILITY IMAP4rev1 IMAP4rev2 \
LIST-EXTENDED LIST-METADATA METADATA LIST-EXTENDED LIST-METADATA METADATA
S: A00 OK Completed. S: A00 OK Completed.
C: A01 LIST "" % \ C: A01 LIST "" % \
RETURN (METADATA ("/shared/vendor/cmu/cyrus-imapd/color")) RETURN (METADATA ("/shared/vendor/cmu/cyrus-imapd/color"))
S: * LIST () "." "INBOX" S: * LIST () "." "INBOX"
S: * METADATA INBOX ("/shared/vendor/cmu/cyrus-imapd/color" "#b71c1c") S: * METADATA INBOX ("/shared/vendor/cmu/cyrus-imapd/color" "#b71c1c")
S: * LIST () "." "foo" S: * LIST () "." "foo"
S: * METADATA "foo" ("/shared/vendor/cmu/cyrus-imapd/color" NIL) S: * METADATA "foo" ("/shared/vendor/cmu/cyrus-imapd/color" NIL)
S: * LIST (\NonExistent) "." "bar" S: * LIST (\NonExistent) "." "bar"
S: A01 OK List completed. S: A01 OK List completed.
]]></artwork> ]]></artwork>
<t keepWithNext="true"> <t keepWithNext="true">
In this example the LIST response for the "foo" mailbox is In this example, the LIST response for the "foo" mailbox is
returned because it has matching children, but no METADATA returned because it has matching children, but no METADATA
response is returned because "foo" itself doesn't match the response is returned because "foo" itself doesn't match the
selection criteria. selection criteria.
</t> </t>
<t>NOTE: '\' line wrapping per <xref target="RFC8792"/></t>
<artwork name="" type="" align="left" alt=""><![CDATA[ <artwork name="" type="" align="left" alt=""><![CDATA[
========== NOTE: '\' line wrapping per RFC 8792 ===========
C: A02 LIST (SUBSCRIBED RECURSIVEMATCH) "" % \ C: A02 LIST (SUBSCRIBED RECURSIVEMATCH) "" % \
RETURN (METADATA ("/shared/vendor/cmu/cyrus-imapd/color")) RETURN (METADATA ("/shared/vendor/cmu/cyrus-imapd/color"))
S: * LIST (\Subscribed) "." "INBOX" S: * LIST (\Subscribed) "." "INBOX"
S: * METADATA INBOX ("/shared/vendor/cmu/cyrus-imapd/color" "#b71c1c") S: * METADATA INBOX ("/shared/vendor/cmu/cyrus-imapd/color" "#b71c1c")
S: * LIST () "." "foo" (CHILDINFO ("SUBSCRIBED")) S: * LIST () "." "foo" (CHILDINFO ("SUBSCRIBED"))
S: A02 OK List completed. S: A02 OK List completed.
]]></artwork> ]]></artwork>
</section> <!-- Examples --> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Formal Syntax</name> <name>Formal Syntax</name>
<t>The following syntax specification uses the augmented Backus-Naur <t>The following syntax specification uses the Augmented Backus-Naur
Form (BNF) as described in <xref target="RFC5234"/>. Form (ABNF) as described in <xref target="RFC5234"/>.
Note that "return-option" is defined in Note that "return-option" is defined in
<xref target="RFC5258"/> <xref target="RFC5258"/> and "entry" is defined in
and "entry" is defined in
<xref target="RFC5464"/>.</t> <xref target="RFC5464"/>.</t>
<artwork name="" type="" align="left" alt=""><![CDATA[ <sourcecode type="abnf"><![CDATA[
return-option =/ "METADATA" SP "(" entry *(SP entry) ")" return-option =/ "METADATA" SP "(" entry *(SP entry) ")"
]]></artwork> ]]></sourcecode>
</section> <!-- Syntax --> </section>
<section anchor="security" numbered="true" toc="default"> <section anchor="security" numbered="true" toc="default">
<name>Security Considerations</name> <name>Security Considerations</name>
<t>This specification does not introduce any additional security <t>This specification does not introduce any additional security
concerns beyond those described in concerns beyond those described in
<xref target="RFC5258"/> and <xref target="RFC5464"/>.</t> <xref target="RFC5258"/> and <xref target="RFC5464"/>.</t>
</section> <!-- Security --> </section>
<section anchor="privacy" numbered="true" toc="default"> <section anchor="privacy" numbered="true" toc="default">
<name>Privacy Considerations</name> <name>Privacy Considerations</name>
<t>This specification does not introduce any additional privacy <t>This specification does not introduce any additional privacy
concerns beyond those described in concerns beyond those described in
<xref target="RFC5464"/>.</t> <xref target="RFC5464"/>.</t>
</section> <!-- Privacy --> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>IANA Considerations</name> <name>IANA Considerations</name>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Registration of IMAP capability LIST-METADATA</name> <name>Registration of IMAP Capability LIST-METADATA</name>
<t>This document defines the "LIST-METADATA" IMAP capability <t>Per this document, IANA has added the "LIST-METADATA" IMAP capability
to be added to registry located at to the "IMAP Capabilities" registry located at <eref target="https://www
<eref target="https://www.iana.org/assignments/imap-capabilities/imap-ca .iana.org/assignments/imap4-capabilities/" brackets="angle"/>.</t>
pabilities.xhtml"/>.</t>
</section> </section>
<section numbered="true" toc="default"> <section numbered="true" toc="default">
<name>Registration of LIST-EXTENDED option METADATA</name> <name>Registration of LIST-EXTENDED Option METADATA</name>
<t>This section registers the "METADATA" LIST-EXTENDED option <t>Per this document, IANA has registered the "METADATA" LIST-EXTENDED o
to be added to the registry located at ption
<eref target="https://www.iana.org/assignments/imap-list-extended/imap-l in the "LIST-EXTENDED options" registry located at
ist-extended.xhtml#imap-list-extended-1"/>.</t> <eref target="https://www.iana.org/assignments/imap-list-extended/" brac
kets="angle"/>.</t>
<dl newline="true" spacing="normal"> <dl newline="true" spacing="normal">
<dt>LIST-EXTENDED option name:</dt> <dt>LIST-EXTENDED option name:</dt>
<dd> <dd>
METADATA METADATA
</dd> </dd>
<dt>LIST-EXTENDED option type:</dt> <dt>LIST-EXTENDED option type:</dt>
<dd> <dd>
RETURN RETURN
</dd> </dd>
<dt>LIST-EXTENDED option description:</dt> <dt>LIST-EXTENDED option description:</dt>
<dd> <dd>
Causes the LIST command to return METADATA responses in Causes the LIST command to return METADATA responses in
addition to LIST responses. addition to LIST responses.
</dd> </dd>
<dt>Published specification:</dt> <dt>Published specification:</dt>
<dd> <dd>
RFC XXXX, <xref target="metadata"/> RFC 9590, <xref target="metadata"/>
</dd> </dd>
<dt>Security considerations:</dt> <dt>Security considerations:</dt>
<dd> <dd>
RFC XXXX, <xref target="security"/> RFC 9590, <xref target="security"/>
</dd> </dd>
<dt>Intended usage:</dt> <dt>Intended usage:</dt>
<dd> <dd>
COMMON COMMON
</dd> </dd>
<dt>Person and email address to contact for further information:</dt> <dt>Person and email address to contact for further information:</dt>
<dd> <dd>
Kenneth Murchison &lt;murch@fastmailteam.com&gt;, Kenneth Murchison &lt;murch@fastmailteam.com&gt; and
Bron Gondwana &lt;brong@fastmailteam.com&gt; Bron Gondwana &lt;brong@fastmailteam.com&gt;
</dd> </dd>
<dt>Owner/Change controller:</dt> <dt>Owner/Change controller:</dt>
<dd> <dd>
IESG &lt;iesg@ietf.org&gt; IESG &lt;iesg@ietf.org&gt;
</dd> </dd>
</dl> </dl>
</section> </section>
</section> <!-- IANA --> </section>
</middle> </middle>
<back> <back>
<references> <references>
<name>References</name> <name>References</name>
<references> <references>
<name>Normative References</name> <name>Normative References</name>
<xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.2119.xml"/> <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.2119.xml"/>
<xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.5258.xml"/> <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.5258.xml"/>
<xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.5234.xml"/> <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.5234.xml"/>
<xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.5464.xml"/> <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.5464.xml"/>
<xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.8174.xml"/> <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.8174.xml"/>
<xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.9051.xml"/> <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.9051.xml"/>
</references> </references>
<references> <references>
<name>Informative References</name> <name>Informative References</name>
<xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.8792.xml"/> <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF C.8792.xml"/>
</references> </references>
</references> </references>
<section numbered="true" toc="default">
<name>Change History (To be removed by RFC Editor before
publication)</name>
<t>Changes from draft-ietf-extra-imap-list-metadata-04:
</t>
<ul spacing="normal">
<li>Added CAPABILITY command/response to example.</li>
<li>Reference IANA registries by their URLs.</li>
</ul>
<t>Changes from draft-ietf-extra-imap-list-metadata-03:
</t>
<ul spacing="normal">
<li>Clarified why "bar" is returned in the first example.</li>
</ul>
<t>Changes from draft-ietf-extra-imap-list-metadata-02:
</t>
<ul spacing="normal">
<li>Used RFC 8792 '\' folding of the examples.</li>
</ul>
<t>Changes from draft-ietf-extra-imap-list-metadata-01:
</t>
<ul spacing="normal">
<li>Updated Security Considerations to also reference RFC 5464.</li>
</ul>
<t>Changes from draft-ietf-extra-imap-list-metadata-00:
</t>
<ul spacing="normal">
<li>Added missing SP in ABNF.</li>
</ul>
<t>Changes from draft-murchison-imap-list-metadata-02:
</t>
<ul spacing="normal">
<li>Renamed as a WG document.</li>
<li>Clarified that the METADATA response with values is used.</li>
<li>Miscellaneous editorial changes.</li>
</ul>
<t>Changes from draft-murchison-imap-list-metadata-01:
</t>
<ul spacing="normal">
<li>None.</li>
</ul>
<t>Changes from draft-murchison-imap-list-metadata-00:
</t>
<ul spacing="normal">
<li>Updated Keywords boilerplate.</li>
<li>Changed RFC 3501 reference to RFC 9051.</li>
</ul>
</section>
</back> </back>
</rfc> </rfc>
 End of changes. 39 change blocks. 
137 lines changed or deleted 81 lines changed or added

This html diff was produced by rfcdiff 1.48.