draft-ietf-extra-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-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>
    <title abbrev="IMAP LIST-METADATA">IMAP4 Extension for Returning
    Mailbox METADATA in Extended LIST</title>
    <seriesInfo name="Internet-Draft"
                value="draft-ietf-extra-imap-list-metadata-05"/>

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

    <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> <!-- Conventions -->
    
    <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
      (see <xref target="RFC5464" section="4.4.1"/>).
      As per <xref target="RFC5464" section="4.4"/>, 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.</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> <!-- METADATA -->

    <section numbered="true" toc="default">
      <name>Examples</name>
      <t>The following are examples of fetching metadata of
      only the top level of the mailbox hierarchies with different
      sets of selection criteria
      (see <xref target="RFC9051" section="6.3.9"/>).</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>"bar" has children, but isn't an actual mailbox itself,
        so it has no METADATA response.</li>
      </ul>

      <t>NOTE: '\' line wrapping per <xref target="RFC8792"/></t>

      <artwork name="" type="" align="left" alt=""><![CDATA[
C: A00 CAPABILITY
S: * CAPABILITY IMAP4rev1 IMAP4rev2 \
                LIST-EXTENDED LIST-METADATA METADATA
S: A00 OK Completed.      
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>

      <t>NOTE: '\' line wrapping per <xref target="RFC8792"/></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> <!-- Examples -->

    <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" SP "(" entry *(SP entry) ")"
]]></artwork>

    </section> <!-- Syntax -->

    <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"/> and <xref target="RFC5464"/>.</t>
    </section> <!-- Security -->

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

    <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 registry located at
        <eref target="https://www.iana.org/assignments/imap-capabilities/imap-capabilities.xhtml"/>.</t>
      </section>

      <section numbered="true" toc="default">
        <name>Registration of LIST-EXTENDED option METADATA</name>
        <t>This section registers the "METADATA" LIST-EXTENDED option
        to be added to the registry located at
        <eref target="https://www.iana.org/assignments/imap-list-extended/imap-list-extended.xhtml#imap-list-extended-1"/>.</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 -->
  </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.8792.xml"/>
      </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>
</rfc>