draft-murchison-imap-list-metadata.xml

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc [
  <!ENTITY nbsp    "&#160;">
  <!ENTITY zwsp   "&#8203;">
  <!ENTITY nbhy   "&#8209;">
  <!ENTITY wj     "&#8288;">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc strict="yes"?>
<rfc xmlns:xi="http://www.w3.org/2001/XInclude"
     category="std"
     ipr="trust200902"
     docName="draft-murchison-imap-list-metadata-02"
     obsoletes=""
     updates=""
     submissionType="IETF"
     xml:lang="en"
     tocInclude="true"
     symRefs="true"
     sortRefs="true"
     consensus="true"
     version="3">
  <!-- xml2rfc v2v3 conversion 3.14.2 -->
  <front>
    <title abbrev="IMAP LIST-METADATA">IMAP4 Extension for Returning
    Mailbox METADATA in Extended LIST</title>
    <seriesInfo name="Internet-Draft"
                value="draft-murchison-imap-list-metadata-02"/>

    <author initials="K." surname="Murchison" fullname="Kenneth Murchison">
      <organization abbrev="Fastmail">Fastmail US LLC</organization>
      <address>
        <postal>
          <street>1429 Walnut Street - Suite 1201</street>
          <city>Philadelphia</city> <region>PA</region>
          <code>19102</code> <country>USA</country>
        </postal>
        <email>murch@fastmailteam.com</email>
      </address>
    </author>

    <author initials="B." surname="Gondwana" fullname="Bron Gondwana">
      <organization abbrev="Fastmail">Fastmail Pty Ltd</organization>
      <address>
        <postal>
          <street>Level 2, 114 William Street</street>
          <city>Melbourne</city>
          <region>VIC</region>
          <code>3000</code>
          <country>Australia</country>
        </postal>
        <email>brong@fastmailteam.com</email>
      </address>
    </author>

    <date/>

    <area>ART</area>
    <workgroup>EXTRA</workgroup>
    <keyword>IMAP4</keyword>
    <keyword>LIST</keyword>
    <keyword>METADATA</keyword>

    <abstract>
      <t>This document defines an extension to the to IMAP LIST
      command that allows the client to request mailbox annotations
      (metadata), along with other information typically returned by
      the LIST command.</t>
    </abstract>
  </front>

  <middle>
    <section numbered="true" toc="default">
      <name>Introduction</name>
      <t>IMAP clients sometimes fetch mailbox metadata (e.g. color) to
      augment the display of mailboxes to the logged-in user.
      In order to do that, the client is 
      forced to issue a LIST or LSUB command to list all available
      mailboxes, followed by a GETMETADATA command for each mailbox
      found.  This document defines an extension to the to IMAP LIST
      command that is identified by the capability string
      "LIST-METADATA".  The LIST-METADATA extension allows the client
      to request annotations on available mailboxes, along with other
      information typically returned by the LIST command.</t>
    </section>
    <section numbered="true" toc="default">
      <name>Conventions Used in This Document</name>
      <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
      client.</t>

      <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
      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>
    <!-- Intro -->
    
    <section anchor="metadata" numbered="true" toc="default">
      <name>METADATA Return Option to LIST Command</name>
      <t><xref target="RFC5464"/> defines the
      GETMETADATA command which is 
      used by an IMAP client to retrieve mailbox annotations.
      Sometimes,
      a client will have to look up the metadata for some or all of
      the mailboxes returned by the LIST command.  Doing so in
      multiple GETMETADATA commands wastes bandwidth and can degrade
      performance if the client does not pipeline the requests.</t>

      <t>This document extends the LIST command with a new return option,
      "METADATA", which allows the client to request all of the
      desired information in a single command.  For each listable
      mailbox matching the list pattern and selection options, the
      server MUST return an untagged LIST response followed by one or more
      untagged METADATA responses containing the mailbox annotations
      requested by the client.
      The untagged METADATA responses to an extended LIST command have
      the same syntax and semantics as those that would be returned by
      GETMETADATA commands on the same set of listable mailboxes.
      As per <xref target="RFC5464"/>, the server may
      return all requested annotations in a single METADATA response
      for each mailbox, or it may split the requested annotations into
      multiple METADATA responses for each mailbox, if it desires.</t>

      <t>If the server is unable to look up the annotations for
      given mailbox, it MAY drop the corresponding METADATA response.
      In such a situation, the LIST command would still return a tagged
      OK reply.</t>
    </section>
    <!-- MYRIGHTS -->

    <section numbered="true" toc="default">
      <name>Examples</name>
      <t>Note that the line wrapping of the extended LIST commands
      below is for editorial purposes only.</t>

      <t keepWithNext="true">
	In this example:
      </t>
      <ul spacing="normal">
        <li>The "color" annotation for the "foo" mailbox has not been
        set, so the METADATA response has a value of "NIL" (has no
        value).</li>
        <li>The "bar" mailbox doesn't exist, so it has no METADATA
        response.</li>
      </ul>

      <artwork name="" type="" align="left" alt=""><![CDATA[
C: A01 LIST "" %
         RETURN (METADATA ("/shared/vendor/cmu/cyrus-imapd/color"))
S: * LIST () "." "INBOX"
S: * METADATA INBOX ("/shared/vendor/cmu/cyrus-imapd/color" "#b71c1c")
S: * LIST () "." "foo"
S: * METADATA "foo" ("/shared/vendor/cmu/cyrus-imapd/color" NIL)
S: * LIST (\NonExistent) "." "bar"
S: A01 OK List completed.
]]></artwork>

      <t keepWithNext="true">
	  In this example the LIST response for the "foo" mailbox is
          returned because it has matching children, but no METADATA
          response is returned because "foo" itself doesn't match the
          selection criteria.
      </t>

      <artwork name="" type="" align="left" alt=""><![CDATA[
C: A02 LIST (SUBSCRIBED RECURSIVEMATCH) "" %
         RETURN (METADATA ("/shared/vendor/cmu/cyrus-imapd/color"))
S: * LIST (\Subscribed) "." "INBOX"
S: * METADATA INBOX ("/shared/vendor/cmu/cyrus-imapd/color" "#b71c1c")
S: * LIST () "." "foo" (CHILDINFO ("SUBSCRIBED"))
S: A02 OK List completed.
]]></artwork>
    </section>

    <section numbered="true" toc="default">
      <name>Formal Syntax</name>
      <t>The following syntax specification uses the augmented Backus-Naur
      Form (BNF) as described in <xref target="RFC5234"/>.

      Note that "return-option" is defined in
      <xref target="RFC5258"/>
      and "entry" is defined in
      <xref target="RFC5464"/>.</t>

      <artwork name="" type="" align="left" alt=""><![CDATA[
return-option =/ "METADATA" "(" entry *(SP entry) ")"
]]></artwork>

    </section>
    <section anchor="security" numbered="true" toc="default">
      <name>Security Considerations</name>
      <t>This specification does not introduce any additional security
      concerns beyond those described in
      <xref target="RFC5258"/>.</t>
    </section>
    <section anchor="privacy" numbered="true" toc="default">
      <name>Privacy Considerations</name>
      <t>This specification does not introduce any additional privacy
      concerns beyond those described in
      <xref target="RFC5464"/>.</t>
    </section>

    <section numbered="true" toc="default">
      <name>IANA Considerations</name>
      <section numbered="true" toc="default">
        <name>Registration of IMAP capability LIST-METADATA</name>
        <t>This document defines the "LIST-METADATA" IMAP capability
        to be added to the registry defined in
        <xref target="RFC9051" section="12.1"/>.</t>
      </section>
      <section numbered="true" toc="default">
        <name>Registration of LIST-EXTENDED option METADATA</name>
        <t>This section registers the "METADATA" option to be added to the
        registry defined in
        <xref target="RFC5258" section="9"/>.
        </t>
        <dl newline="true" spacing="normal">
          <dt>LIST-EXTENDED option name:</dt>
          <dd>
	    METADATA
	  </dd>
          <dt>LIST-EXTENDED option type:</dt>
          <dd>
	    RETURN
	  </dd>
          <dt>LIST-EXTENDED option description:</dt>
          <dd>
	    Causes the LIST command to return METADATA responses in
            addition to LIST responses.
	  </dd>
          <dt>Published specification:</dt>
          <dd>
	    RFC XXXX, <xref target="metadata"/>
          </dd>
          <dt>Security considerations:</dt>
          <dd>
	    RFC XXXX, <xref target="security"/>
          </dd>
          <dt>Intended usage:</dt>
          <dd>
	    COMMON
	  </dd>
          <dt>Person and email address to contact for further information:</dt>
          <dd>
	    Kenneth Murchison &lt;murch@fastmailteam.com&gt;,
	    Bron Gondwana &lt;brong@fastmailteam.com&gt;
	  </dd>
          <dt>Owner/Change controller:</dt>
          <dd>
	    IESG &lt;iesg@ietf.org&gt;
	  </dd>
        </dl>
      </section>
    </section>
    <!-- IANA -->
<!--
    <section numbered="true" toc="default">
      <name>Acknowledgments</name>
      <t>This document is based largely on
      <xref target="RFC5819"/>.
      The author would like to thank the authors of that document for
      providing both inspiration and some borrowed text for this
      document.</t>

      <t>The author would also like to thank the following individuals for
      contributing their ideas and support for writing this
      specification: Cyrus Daboo.</t>
    </section>
-->
  </middle>

  <back>
    <references>
      <name>References</name>
      <references>
        <name>Normative References</name>
        <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
        <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5258.xml"/>
        <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5234.xml"/>
        <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5464.xml"/>
        <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>
        <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9051.xml"/>
      </references>
<!--
      <references>
        <name>Informative References</name>
        <xi:include href="http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5819.xml"?>
        </references>
-->
    </references>

    <section numbered="true" toc="default">
      <name>Change History (To be removed by RFC Editor before     publication)</name>
      <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>
</rfc>