Network Working Group                                          C. Newman
Internet Draft: ACAP Addressbook Dataset Class                  Innosoft
Document: draft-ietf-acap-abook-00.txt                         S. Hubert
                                                University of Washington
                                                               July 1997
                                                   Expires in six months


                ACAP Personal Addressbook Dataset Class


Status of this memo

     This document is an Internet-Draft.  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."

     To view the entire list of current Internet-Drafts, please check
     the "1id-abstracts.txt" listing contained in the Internet-Drafts
     Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net
     (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East
     Coast), or ftp.isi.edu (US West Coast).

Abstract

     IMAP [IMAP4] allows nomadic users to access their mailstore from
     any client, but it does not support storage of personal
     addressbooks.  Application Configuration Access Protocol [ACAP]
     provides an ideal mechanism for storage of personal addressbooks.
     While ACAP permits the definition of vendor specific solutions to
     this problem, having a standard addressbook dataset class permits
     clients from different vendors to interoperably share the same
     personal addressbooks.  This specification defines a standard
     dataset class for personal addressbooks.

     Personal addressbooks differ from white pages services because all
     the attributes and entries are controlled by the user who owns the
     addressbook rather than a directory administrator.  The user or the
     clients he uses may add new attributes at any time and some of
     these attributes are not suitable for a white pages service.




Newman                                                          [Page i]


Internet Draft       ACAP Addressbook Dataset Class            July 1997





                           Table of Contents



Status of this memo ...............................................    i
Abstract ..........................................................    i
0.5. Open Issues ..................................................    1
1.   Conventions Used in this Document ............................    1
2.   ACAP Personal Addressbooks ...................................    1
2.1. ACAP Addressbook Dataset Class ...............................    1
2.2. ACAP Addressbook Capability ..................................    1
2.3. ACAP Addressbook Hierarchy ...................................    1
3.   Recommended ACAP Attributes ..................................    1
3.1. Basic Attributes .............................................    2
3.2. Naming Attributes ............................................    3
3.3. Reference Attribute ..........................................    4
3.4. Computer Communication Attributes ............................    4
3.5. Telephone Number Attributes ..................................    6
3.6. Postal Address Attributes ....................................    7
3.7. Commentary Attributes ........................................    7
3.8. Locational Attributes ........................................    8
4.   Examples .....................................................    9
5.   References ...................................................   10
6.   Security Considerations ......................................   11
7.   Authors' Addresses ...........................................   11
Appendix ..........................................................   12
A.   Attribute Index ..............................................   12





















Newman                                                         [Page ii]


0.5. Open Issues

     1) add addressbook.Source to refer to a directory (or other source)
     from which the entry was imported?

     2) Certificates?

     3) Interaction with vCard?

1.   Conventions Used in this Document

     The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
     in this document are to be interpreted as defined in "Key words for
     use in RFCs to Indicate Requirement Levels" [KEYWORDS].

     The attribute syntax specifications use the Augmented Backus-Naur
     Form (ABNF) notation as specified in [IMAIL].

     When UTF-8 [UTF8] is referred to in this document, it refers to
     Unicode version 2.0, and not Unicode version 1.1.

2.   ACAP Personal Addressbooks

2.1. ACAP Addressbook Dataset Class

     Datasets whose names begin with "/addressbook" are assumed to
     contain addressbook entries as defined in this specification.

2.2. ACAP Addressbook Capability

     The "addressbook.Expand.Address" and "addressbook.Expand.Complete"
     attributes require active client or server support.  The attribute
     "capability.addressbook.expand" in the "/capability/~/addressbook"
     entry is non-NIL if they are supported.

2.3. ACAP Addressbook Hierarchy

     Hierarchical addressbooks SHOULD be represented using ACAP
     hierarchy.  Any entry in an addressbook can also be a hierarchy
     node by setting the "subdataset" attribute.  This structure is used
     to represent both sub-addressbooks and mailing lists.

3.   Recommended ACAP Attributes

     The following attributes MAY be used in an ACAP addressbook entry.
     An addressbook entry MUST have an "entry" attribute, and one or
     more of "addressbook.Alias", "addressbook.CommonName" and
     "addressbook.Email" attributes.  The purpose of this rule is to



Newman                                                          [Page 1]


Internet Draft       ACAP Addressbook Dataset Class            July 1997


     make it possible to easily select an attribute which can be
     displayed to a user.

     An addressbook entry MUST have at most one of the attributes
     "addressbook.List", "addressbook.Reference", and
     "addressbook.Email".  The purpose of this rule is to force each
     entry to be either a regular addressbook entry with an Email
     address, a pointer to another addressbook entry, or a distribution
     list.  In order to resolve ambiguities, if there is an
     "addressbook.List" attribute, both "addressbook.Email" and
     "addressbook.Reference" attributes MUST be ignored. If there is no
     "addressbook.List" attribute but there is an "addressbook.Email"
     attribute, then the "addressbook.Reference" attribute MUST be
     ignored. Beyond these rule, clients MAY choose any subset of these
     attributes as well as using registered private attributes.  Clients
     are encouraged to provide a way to view all textual attributes in
     an entry regardless of whether the client knows the special
     semantics associated with them.

     The ABNF defines the content of the attribute values prior to their
     encoding as an ACAP string.  Clients MUST conform to the syntax
     when generating these attributes, but MUST NOT assume that the
     attribute values will conform to this syntax on access.  Servers
     MUST NOT enforce the syntax.

     Unless otherwise stated, all attributes in this specification are
     single-valued and textual.

3.1. Basic Attributes

     These attributes are defined in ACAP [ACAP] and have meaning in all
     dataset classes.  This section describes how they are used in an
     addressbook dataset.

     entry
          The "entry" attribute is a unique string used to refer to an
          addressbook entry within an addressbook dataset.  It is client
          defined and may not be suitable for display to users.

     subdataset
          The "subdataset" attribute is used both for addressbook
          hierarchy and for addressbook distribution lists.  It
          indicates there is another addressbook dataset underneath this
          entry.  If there is also an "addressbook.List" attribute, then
          this entry is an email distribution list and the subdataset
          contains the members of that list.  If "subdataset" exists,
          then any "addressbook.Email" or "addressbook.Reference"
          attributes SHOULD be ignored.



Newman                                                          [Page 2]


Internet Draft       ACAP Addressbook Dataset Class            July 1997


3.2. Naming Attributes

     These attributes contain information about the name of the person
     or entity to which the entry refers.

     addressbook.CommonName
          The "addressbook.CommonName" attribute holds the full common
          name of the person or entity to which the addressbook entry
          refers.  If a person has multiple names, they may be stored in
          the "addressbook.AlternateNames" attribute.

          abook-common-name    = 1*TEXT-UTF8-CHAR

     addressbook.GivenName
          The "addressbook.GivenName" attribute holds the given name of
          the person to which the addressbook entry refers.

          abook-given-name     = 1*TEXT-UTF8-CHAR

     addressbook.Surname
          The "addressbook.Surname" attribute holds the surname (or
          family name) of the person to which the addressbook entry
          refers.

          abook-surname        = 1*TEXT-UTF8-CHAR

     addressbook.AlternateNames
          This is a multi-value attribute containing a list of alternate
          names for the entry.

          abook-alt-name       = 1*TEXT-UTF8-CHAR
                                 ;; multi-valued

     addressbook.Alias
          A shorthand way to refer to this entry (e.g. a nickname).
          Clients MUST NOT store characters which fall into the class of
          "white-space" or "specials" as defined in Internet Message
          Format [IMAIL] with the exception of period (".").  The alias
          is typically used by clients as as a way for users to quickly
          refer to a particular addressbook entry via a type-in field.
          For this to work best, clients are encouraged to avoid using
          the same alias in multiple entries within a dataset.

          abook-alias          = 1*<"." or any TEXT-UTF8-CHAR except
                               white-space or specials as defined in [IMAIL]>






Newman                                                          [Page 3]


Internet Draft       ACAP Addressbook Dataset Class            July 1997


     addressbook.CommonName.MIME
          This contains the CommonName encoded as a US-ASCII string
          according to the rules in MIME Headers [MIME-HDRS].  This is
          set when a personal addressbook entry is created from an
          Internet Mail Address [IMAIL] which uses MIME Header encoding
          for the common name portion of the address.  This is the
          preferred attribute to use for the phrase portion of the
          Internet Mail Address as it preserves the sender's preferred
          character set.  Otherwise, the phrase is constructed from the
          "addressbook.CommonName" field with all non US-ASCII
          characters encoded according to MIME headers using UTF-8.
          This attribute SHOULD be NIL if the CommonName is made up of
          only US-ASCII characters or the sender's preferred character
          set is UTF-8.

          abook-mime-hdr       = phrase
                                 ;; as defined in [IMAIL]


3.3. Reference Attribute


     addressbook.Reference
          This addressbook entry is a reference to another ACAP
          addressbook entry, or an LDAP white pages entry.  The
          reference is in the form of a relative URL.  Clients SHOULD
          support this attribute for the local ACAP server and MAY
          support it for other ACAP or LDAP servers.

          abook-reference      = relativeURL
                                 ;; as defined in [REL-URL]
                                 ;; ACAP relative URL is defined in [ACAP]


3.4. Computer Communication Attributes

     These attributes are related to computer communication.  The format
     for email addresses MUST be canonicalized so it is suitable for use
     in both [IMAIL] and [SMTP].  This restricts the format for an
     addr-spec as follows.  This uses terminals from [IMAIL], except
     that free insertion of linear-white-space is not permitted.

     canon-addr-spec      = canon-local-part "@" domain

     canon-local-part     = quoted-string / (atom *("." atom))






Newman                                                          [Page 4]


Internet Draft       ACAP Addressbook Dataset Class            July 1997


     addressbook.Email
          The primary email address for contacting this entry.
          Alternate email addresses may be indicated by appending an
          appropriate qualifer to the end of the attribute name, such as
          ".work" for a work-related email address, ".personal" for a
          personal email address, or ".alt" for a multi-valued list of
          alternate email addresses of equal weight.

          abook-email          = canon-addr-spec

     addressbook.List
          If both this attribute and the "subdataset" attribute exist
          then this entry is an email distribution list.  The entries in
          the subdataset are the members of the list.  When this
          attribute exists, then any "addressbook.Email" or
          "addressbook.Reference" attributes should be ignored. If this
          attribute exists but no "subdataset" attribute exists, then
          this attribute should be ignored.

          abook-list           = "1"

     addressbook.Expand.Address
          This is an operational attribute which is present if the ACAP
          server announces the ADDRESSBOOK capability.  It's value is
          computed by the ACAP server.  The result is a CRLF-separated
          list of all the addr-spec from the addressbook.Email
          attributes of this entry, any entry referred to by
          "addressbook.Reference" on the local server, and any entries
          contained in the "subdataset" on this server.  This expansion
          is recursive.

          abook-expand-addr    = canon-addr-spec *(CRLF canon-addr-spec)

     addressbook.Expand.Complete
          This is an operational attribute which is present if the ACAP
          server announces the ADDRESSBOOK capability.  It's value is
          computed by the ACAP server.  The result is a CRLF-separated
          list of all the Internet Mail Addresses as computed from the
          addressbook.Email, addressbook.CommonName, and
          addressbook.CommonName.MIME attributes.  The entry itself, any
          entry referred to by "addressbook.Reference" on the local
          server, and any entries contained in the "subdataset" on the
          local server are expanded.  This expansion is recursive.

          abook-expand-compl   = mailbox *(CRLF mailbox)
                                 ;; mailbox defined in [IMAIL] without folding





Newman                                                          [Page 5]


Internet Draft       ACAP Addressbook Dataset Class            July 1997


     addressbook.RequestAddress
          If the entry refers to a mailing list address rather than a
          person, then this attribute may be used to store the address
          used to subscribe or unsubscribe from the mailing list.  If
          not present, clients should default the value to the standard
          request address defined in [MBOX-NAMES].

          abook-request        = canon-addr-spec

     addressbook.Subscribed
          If this attribute is non-NIL, then the entry refers to a
          mailing list address to which the addressbook's owner is
          currently subscribed.

          abook-subscribed     = "1"

     addressbook.PreferredTextFormat
          This attribute contains the media type and parameters for the
          preferred text format of for the mailbox referred to by the
          "addressbook.Email" attribute.  The syntax does not permit
          free insertion of linear white space as defined in [IMAIL].
          Values can include "text/enriched", "text/html", "text/plain",
          "multipart/alternative".  There is no defined default value,
          although clients should be aware that the only format all
          recipients support is "text/plain; charset=us-ascii".

          abook-text-format    = type "/" subtype *(";" SPACE parameter)
                                 ;; as defined in [MIME-TYPES]

     addressbook.HomePage
          This contains the URL [BASIC-URL] to the home page describing
          the person or entity to which the addressbook entry refers.

          abook-home-page      = url
                                 ;; as defined in [BASIC-URL]


3.5. Telephone Number Attributes


     Telephone numbers all have the syntax "1*TEXT-UTF8-CHAR".    Fully
     qualified international form is preferred:
        +1 555 555 1234 ext 54
     but as these are likely to be human-entered any form is permitted.

     addressbook.TelephoneNumber
          This is the preferred telephone number for the person referred
          to by the entry.  A suffix such as ".work" or ".home" can be



Newman                                                          [Page 6]


Internet Draft       ACAP Addressbook Dataset Class            July 1997


          added to indicate alternate numbers.

     addressbook.Fax
          This is the preferred fax number for the person or entity
          referred to by the entry.  A suffix such as ".work" or ".home"
          can be added to indicate alternate numbers.

     addressbook.MobilePhone
          This is the preferred mobile phone number for the person
          referred to by the entry.  A suffix such as ".work" or ".home"
          can be added to indicate alternate numbers.

     addressbook.PagerNumber
          This is the preferred pager number for the person or entity
          referred to by the entry.  A suffix such as ".work" or ".home"
          can be added to indicate alternate numbers.


3.6. Postal Address Attributes

     Postal addresses should be in the same format that they appear on
     an envelope, preferably fully qualified.  The multiple lines are
     CRLF separated within the attribute.

     addressbook.PostalAddress
          This contains the preferred postal address for the person or
          entity referred to by the entry.  A suffix such as ".work" or
          ".home" can be added to indicate alternate addresses.

          abook-postal        = 1*TEXT-UTF8-CHAR *(CRLF *TEXT-UTF8-CHAR)


3.7. Commentary Attributes

     These are free-form text attributes used to store commentary about
     the entry.

     addressbook.Comment
          This is a freeform comment field where the owner of the
          addressbook may put comments about the person or entity
          referred to by the entry.

          abook-comment        = 1*UTF8-CHAR








Newman                                                          [Page 7]


Internet Draft       ACAP Addressbook Dataset Class            July 1997


     addressbook.Description
          This is a freeform comment field for a self-description of the
          person or entity referred to by the entry.  It is primarily
          used when an entry is imported from a remote directory.

          abook-description    = 1*UTF8-CHAR

3.8. Locational Attributes

     These contain information about the location of the person or
     entity referred to by this entry.

     addressbook.Organization
          This is the name of the organization with which the person or
          entity is associated.

          abook-organization   = 1*TEXT-UTF8-CHAR

     addressbook.Title
          This is the title of the person referred to by the entry.

          abook-title          = 1*TEXT-UTF8-CHAR

     addressbook.Locality
          This is the name of the locality where the person or entity is
          normally located.

          abook-locality       = 1*TEXT-UTF8-CHAR

     addressbook.Country
          This is the ISO 3166 country code where the person or entity
          is normally located.

          abook-country        = 2*3ALPHA

     addressbook.LanguageSpoken
          This is the RFC 1766 language code for the language which the
          person or entity prefers to speak.

          abook-language       = Language-Tag
                                ;; as defined in RFC 1766










Newman                                                          [Page 8]


Internet Draft       ACAP Addressbook Dataset Class            July 1997


4.   Examples

     Some sample entries:

     In addressbook /addressbook/user/hubert

     attribute name                value
     --------------                -----
     entry                         ABC123
     addressbook.CommonName        Patrik Faltstrom
     addressbook.GivenName         Patrik
     addressbook.Surname           Faltstrom
     addressbook.Email             paf@swip.net
     addressbook.CommonName.MIME   =?ISO-8859-1?Q?Patrik_F=E4ltstr=F6m?=
     addressbook.Expand.Address    paf@swip.net
     addressbook.Expand.Complete
                       =?ISO-8859-1?Q?Patrik_F=E4ltstr=F6m?= <paf@swip.net>

     entry                         ABC567
     addressbook.CommonName        Terry Gray
     addressbook.GivenName         Terry
     addressbook.Surname           Gray
     addressbook.Alias             teg
     addressbook.Email             gray@cac.washington.edu
     addressbook.Expand.Address    gray@cac.washington.edu
     addressbook.Expand.Complete   Terry Gray <gray@cac.washington.edu>

     entry                         defghi
     subdataset                    .
     addressbook.List              "1"
     addressbook.CommonName        List of Two
     addressbook.CommonName.MIME   List of Two
     addressbook.Expand.Address    paf@swip.net
                                   gray@cac.washington.edu
                                   fred@bedrock.com
     addressbook.Expand.Complete
                       =?ISO-8859-1?Q?Patrik_F=E4ltstr=F6m?= <paf@swip.net>
                                   Terry Gray <gray@cac.washington.edu>
                                   Fred Flintstone <fred@bedrock.com>

     In dataset /addressbook/user/hubert/defghi

     entry                         xyz1
     addressbook.Reference         ../ABC123
     addressbook.Expand.Address    paf@swip.net
     addressbook.Expand.Complete
                        =?ISO-8859-1?Q?Patrik_F=E4ltstr=F6m?= <paf@swip.net>




Newman                                                          [Page 9]


Internet Draft       ACAP Addressbook Dataset Class            July 1997


     entry                         xyz2
     addressbook.Reference         ../ABC567
     addressbook.Expand.Address    gray@cac.washington.edu
     addressbook.Expand.Complete   Terry Gray <gray@cac.washington.edu>

     entry                         z2t
     addressbook.CommonName        Fred Flintstone
     addressbook.GivenName         Fred
     addressbook.Surname           Flintstone
     addressbook.Email             fred@bedrock.com
     addressbook.CommonName.MIME   Fred Flintstone
     addressbook.Expand.Address    fred@bedrock.com
     addressbook.Expand.Complete   Fred Flintstone <fred@bedrock.com>

5.   References

     [ACAP] Newman, Myers, "ACAP -- Application Configuration Access
     Protocol", work in progress, June 1997.

     [BASIC-URL] Berners-Lee, Masinter, McCahill, "Uniform Resource
     Locators (URL)", RFC 1738, CERN, Xerox Coproration, University of
     Minnesota, December 1994.

         <ftp://ds.internic.net/rfc/rfc1738.txt>

     [IMAIL] Crocker, "Standard for the Format of ARPA Internet Text
     Messages", STD 11, RFC 822, University of Delaware, August 1982.

         <ftp://ds.internic.net/rfc/rfc822.txt>

     [IMAP4] Crispin, "Internet Message Access Protocol - Version
     4rev1", RFC 2060, University of Washington, December 1996.

         <ftp://ds.internic.net/rfc/rfc2060.txt>

     [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate
     Requirement Levels", RFC 2119, Harvard University, March 1997.

         <ftp://ds.internic.net/rfc/rfc2119.txt>

     [MBOX-NAMES] Crocker, D., "Mailbox Names for Common Services, Roles
     and Functions", RFC 2142, Internet Mail Consortium, May 1997.

             <ftp://ds.internic.net/rfc/rfc2142.txt>







Newman                                                         [Page 10]


Internet Draft       ACAP Addressbook Dataset Class            July 1997


     [REL-URL] Fielding, "Relative Uniform Resource Locators", RFC 1808,
     UC Irvine, June 1995.

         <ftp://ds.internic.net/rfc/rfc1808.txt>

     [SMTP] Postel, "Simple Mail Transfer Protocol", RFC 821,
     Information Sciences Institute, August 1982.

         <ftp://ds.internic.net/rfc/rfc821.txt>

     [UTF8] Yergeau, "UTF-8, a transformation format of Unicode and ISO
     10646", RFC 2044, Alis Technologies, October 1996.

         <ftp://ds.internic.net/rfc/rfc2044.txt>

6.   Security Considerations

     It is important to make sure that access controls are set correctly
     on personal addressbooks.  One should be careful of sharing
     information which might contain personal comments.

     This specification does not address storing certificates for
     entries in the addressbook.  This may be added to a future version
     of this specification when more experimentation has been done.

7.   Authors' Addresses

     Chris Newman
     Innosoft International, Inc.
     1050 Lakes Drive
     West Covina, CA 91790 USA

     Email: chris.newman@innosoft.com

     Steve Hubert
     Networks and Distributed Computing
     University of Washington
     4545 15th Ave. NorthEast
     Seattle, WA 98105-4527 USA

     Email: hubert@cac.washington.edu










Newman                                                         [Page 11]


Internet Draft       ACAP Addressbook Dataset Class            July 1997


Appendix

A.   Attribute Index


       addressbook.Alias ..........................................    3
       addressbook.AlternateNames .................................    3
       addressbook.Comment ........................................    7
       addressbook.CommonName .....................................    3
       addressbook.CommonName.MIME ................................    4
       addressbook.Country ........................................    8
       addressbook.Description ....................................    8
       addressbook.Email ..........................................    5
       addressbook.Expand.Address .................................    5
       addressbook.Expand.Complete ................................    5
       addressbook.Fax ............................................    7
       addressbook.GivenName ......................................    3
       addressbook.HomePage .......................................    6
       addressbook.LanguageSpoken .................................    8
       addressbook.List ...........................................    5
       addressbook.Locality .......................................    8
       addressbook.MobilePhone ....................................    7
       addressbook.Organization ...................................    8
       addressbook.PagerNumber ....................................    7
       addressbook.PostalAddress ..................................    7
       addressbook.PreferredTextFormat ............................    6
       addressbook.Reference ......................................    4
       addressbook.RequestAddress .................................    6
       addressbook.Subscribed .....................................    6
       addressbook.Surname ........................................    3
       addressbook.TelephoneNumber ................................    6
       addressbook.Title ..........................................    8
       entry ......................................................    2
       subdataset .................................................    2


















Newman                                                         [Page 12]