Internet DRAFT - draft-loffredo-jmap-jscontact-vcard

draft-loffredo-jmap-jscontact-vcard







jmap                                                         M. Loffredo
Internet-Draft                                       IIT-CNR/Registro.it
Intended status: Informational                               R. Stepanek
Expires: December 24, 2020                                      FastMail
                                                           June 22, 2020


                JSContact: Converting from and to vCard
                 draft-loffredo-jmap-jscontact-vcard-03

Abstract

   This document provides informational guidance for converting the
   contact card defined by JSContact specification, namely JSCard, from
   and to vCard.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   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."

   This Internet-Draft will expire on December 24, 2020.

Copyright Notice

   Copyright (c) 2020 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (https://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.




Loffredo & Stepanek     Expires December 24, 2020               [Page 1]

Internet-Draft               jscontact-vcard                   June 2020


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Motivation  . . . . . . . . . . . . . . . . . . . . . . .   3
     1.2.  Scope and Caveats . . . . . . . . . . . . . . . . . . . .   3
     1.3.  Conventions Used in This Document . . . . . . . . . . . .   4
   2.  Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . .   4
     2.1.  General Properties  . . . . . . . . . . . . . . . . . . .   4
       2.1.1.  BEGIN and END . . . . . . . . . . . . . . . . . . . .   4
       2.1.2.  SOURCE  . . . . . . . . . . . . . . . . . . . . . . .   4
       2.1.3.  KIND  . . . . . . . . . . . . . . . . . . . . . . . .   5
       2.1.4.  XML . . . . . . . . . . . . . . . . . . . . . . . . .   6
     2.2.  Identification Properties . . . . . . . . . . . . . . . .   6
       2.2.1.  FN  . . . . . . . . . . . . . . . . . . . . . . . . .   6
       2.2.2.  N and NICKNAME  . . . . . . . . . . . . . . . . . . .   6
       2.2.3.  PHOTO . . . . . . . . . . . . . . . . . . . . . . . .   7
       2.2.4.  BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY    8
       2.2.5.  GENDER  . . . . . . . . . . . . . . . . . . . . . . .  10
     2.3.  Delivery Addressing Properties  . . . . . . . . . . . . .  10
       2.3.1.  ADR . . . . . . . . . . . . . . . . . . . . . . . . .  10
     2.4.  Communications Properties . . . . . . . . . . . . . . . .  11
       2.4.1.  TEL . . . . . . . . . . . . . . . . . . . . . . . . .  12
       2.4.2.  EMAIL . . . . . . . . . . . . . . . . . . . . . . . .  12
       2.4.3.  IMPP  . . . . . . . . . . . . . . . . . . . . . . . .  13
       2.4.4.  LANG  . . . . . . . . . . . . . . . . . . . . . . . .  14
     2.5.  Geographical Properties . . . . . . . . . . . . . . . . .  15
     2.6.  Organizational Properties . . . . . . . . . . . . . . . .  16
       2.6.1.  TITLE . . . . . . . . . . . . . . . . . . . . . . . .  16
       2.6.2.  ROLE  . . . . . . . . . . . . . . . . . . . . . . . .  16
       2.6.3.  LOGO  . . . . . . . . . . . . . . . . . . . . . . . .  17
       2.6.4.  ORG . . . . . . . . . . . . . . . . . . . . . . . . .  18
       2.6.5.  MEMBER  . . . . . . . . . . . . . . . . . . . . . . .  19
       2.6.6.  RELATED . . . . . . . . . . . . . . . . . . . . . . .  20
       2.6.7.  CONTACT-URI . . . . . . . . . . . . . . . . . . . . .  22
     2.7.  Personal Information Properties . . . . . . . . . . . . .  22
       2.7.1.  EXPERTISE . . . . . . . . . . . . . . . . . . . . . .  22
       2.7.2.  HOBBY . . . . . . . . . . . . . . . . . . . . . . . .  23
       2.7.3.  INTEREST  . . . . . . . . . . . . . . . . . . . . . .  24
       2.7.4.  ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . .  25
     2.8.  Explanatory Properties  . . . . . . . . . . . . . . . . .  26
       2.8.1.  CATEGORIES  . . . . . . . . . . . . . . . . . . . . .  26
       2.8.2.  NOTE  . . . . . . . . . . . . . . . . . . . . . . . .  27
       2.8.3.  PRODID  . . . . . . . . . . . . . . . . . . . . . . .  28
       2.8.4.  REV . . . . . . . . . . . . . . . . . . . . . . . . .  28
       2.8.5.  SOUND . . . . . . . . . . . . . . . . . . . . . . . .  29
       2.8.6.  UID . . . . . . . . . . . . . . . . . . . . . . . . .  30
       2.8.7.  CLIENTPIDMAP and PID Parameter  . . . . . . . . . . .  30
       2.8.8.  URL . . . . . . . . . . . . . . . . . . . . . . . . .  30



Loffredo & Stepanek     Expires December 24, 2020               [Page 2]

Internet-Draft               jscontact-vcard                   June 2020


       2.8.9.  VERSION . . . . . . . . . . . . . . . . . . . . . . .  31
     2.9.  Security Properties . . . . . . . . . . . . . . . . . . .  31
       2.9.1.  KEY . . . . . . . . . . . . . . . . . . . . . . . . .  31
     2.10. Calendar Properties . . . . . . . . . . . . . . . . . . .  32
       2.10.1.  FBURL  . . . . . . . . . . . . . . . . . . . . . . .  32
       2.10.2.  CALADRURI  . . . . . . . . . . . . . . . . . . . . .  33
       2.10.3.  CALURI . . . . . . . . . . . . . . . . . . . . . . .  34
     2.11. Extended Properties . . . . . . . . . . . . . . . . . . .  35
     2.12. JSCard Required Properties  . . . . . . . . . . . . . . .  35
     2.13. JSCard Unmatched Properties . . . . . . . . . . . . . . .  36
   3.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  36
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .  36
   5.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  36
     5.1.  Normative References  . . . . . . . . . . . . . . . . . .  36
     5.2.  Informative References  . . . . . . . . . . . . . . . . .  37
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  37

1.  Introduction

1.1.  Motivation

   The JSContact specification [draft-ietf-jmap-jscontact] has been
   defined to represent contact card information as a more efficient
   alternative to vCard [RFC6350] and its JSON-based version named jCard
   [RFC7095].

   While new applications might adopt JSContact as their main format to
   exchange contact card data, they are likely to interoperate with
   services and clients that just support vCard/jCard.  Similarly,
   existing contact data providers and consumers already using vCard/
   jCard might want to represent their data also according to the
   JSContact specification.

   To facilitate this use cases, this document provides informational
   guidance about how to convert the card defined in JSContact, namely
   JSCard, from and to vCard.

1.2.  Scope and Caveats

   JSContact and vCard have a lot of semantics in common, however some
   differences must be outlined:

   o  The JSContact data model defines some contact information that
      doesn't have a direct mapping with vCard elements.  In particular,
      unlike vCard, JSContact distinguishes between a single contact
      card, named JSCard, and a group of contact cards, named
      JSCardGroup.




Loffredo & Stepanek     Expires December 24, 2020               [Page 3]

Internet-Draft               jscontact-vcard                   June 2020


   o  The vCard specification includes some features (like parameters)
      that have been formally removed from JSCard due to a complete
      refactoring of vCard content.  Anyway, the vCard parameters may
      appear as JSCard features.

   o  Some vCard elements represented individually have been mapped onto
      members of JSCard objects.

   o  The vCard custom elements, identified by the prefix "x-", don't
      have a direct counterpart among the JSContact specification.

1.3.  Conventions Used in This Document

   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].

2.  Mapping

   This section contains the mapping between vCard and JSCard.  The
   vCard properties are grouped according to the categories defined by
   [RFC6350].

   Where it is needed, the JCardGroup is taken into account.

   In the following of this document, the vCard features, namely
   properties and parameters, are written in uppercase while the JSCard
   features are written in camel case.

2.1.  General Properties

2.1.1.  BEGIN and END

   The BEGIN and END properties don't have a direct match with a JSCard
   feature.

2.1.2.  SOURCE

   A SOURCE element is represented as a "Resource" object in the
   "online" array (Figure 1) whose "type" member is set to "uri" and
   "labels" map contains the entry <"source",true>.

   The PREF and MEDIATYPE parameters are mapped onto the "isPreferred"
   and "mediaType" members respectively.







Loffredo & Stepanek     Expires December 24, 2020               [Page 4]

Internet-Draft               jscontact-vcard                   June 2020


    BEGIN:VCARD
    VERSION:4.0
    ...
    SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf
    ...
    END:VCARD

    {
    ...
    "online":[
              ...
              {
               "type": "uri",
               "labels": { "source": true },
               "value": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf"
              },
              ...
            ],
    ...
    }

                     Figure 1: SOURCE mapping example

2.1.3.  KIND

   The KIND element is mapped onto the "kind" member (Figure 2).
   Allowed values are those, except "group", described in section 6.1.4
   of [RFC6350] and extended with the values declared in [RFC6473] and
   [RFC6869].  A group of cards is represented through a JSCardGroup.

       BEGIN:VCARD
       VERSION:4.0
       ...
       KIND:individual
       ...
       END:VCARD

       {
       ...
       "kind": "individual",
       ...
       }

                      Figure 2: KIND mapping example







Loffredo & Stepanek     Expires December 24, 2020               [Page 5]

Internet-Draft               jscontact-vcard                   June 2020


2.1.4.  XML

   The XML property doesn't have a direct match with a JSCard feature.

2.2.  Identification Properties

2.2.1.  FN

   All the FN elements are globally represented through the "fullName"
   member.  The presence of more than one name is implicitly associated
   with the full name translations in various languages regardless of
   the presence of the ALTID parameter.  Each translation corresponds to
   a different entry of the "localizations" map (Figure 3).

2.2.2.  N and NICKNAME

   Both the N and NICKNAME elements are converted into equivalent items
   of the "name" array (Figure 3):

   o  the N components are transformed into related "NameComponent"
      objects as reported in Table 1.  Name components SHOULD be ordered
      such that their values joined by whitespace produce a valid full
      name of this entity;

   o  Each NICKNAME element is mapped onto an object whose "type" member
      is set to "nickname"

                   +--------------------+--------------+
                   | N component        | "type" value |
                   +--------------------+--------------+
                   | Honorific Prefixes | prefix       |
                   | Given Names        | personal     |
                   | Family Names       | surname      |
                   | Additional Names   | additional   |
                   | Honorific Suffixes | suffix       |
                   +--------------------+--------------+

                       Table 1: N components mapping













Loffredo & Stepanek     Expires December 24, 2020               [Page 6]

Internet-Draft               jscontact-vcard                   June 2020


       BEGIN:VCARD
       VERSION:4.0
       ...
       FN:Mr. John Q. Public\, Esq.
       N:Public;John;Quinlan;Mr.;Esq.
       NICKNAME:Johnny
       ...
       END:VCARD

       {
       ...
       "fullName":{
                  "value": "Mr. John Q. Public, Esq."
                  },
       "name":[
                { "value":"Mr.", "type": "prefix" },
                { "value":"John", "type": "personal" },
                { "value":"Public", "type": "surname" },
                { "value":"Quinlan", "type": "additional" },
                { "value":"Esq.", "type": "suffix" },
                { "value":"Johnny", "type": "nickname" }
              ],
       ...
       }

                 Figure 3: FN, N, NICKNAME mapping example

2.2.3.  PHOTO

   A PHOTO element is represented as a "Resource" object in the "online"
   array (Figure 4) whose "type" member is set to "uri" and "labels" map
   contains the entry <"photo",true>.

   The PREF and MEDIATYPE parameters are mapped onto the "isPreferred"
   and "mediaType" members respectively.
















Loffredo & Stepanek     Expires December 24, 2020               [Page 7]

Internet-Draft               jscontact-vcard                   June 2020


    BEGIN:VCARD
    VERSION:4.0
    ...
    PHOTO:http://www.example.com/pub/photos/jqpublic.gif
    ...
    END:VCARD

    {
    ...
    "online":[
              ...
              {
               "type": "uri",
               "labels": { "photo": true },
               "value": "http://www.example.com/pub/photos/jqpublic.gif"
              },
              ...
            ],
    ...
    }

                      Figure 4: PHOTO mapping example

2.2.4.  BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY

   The BDAY and ANNIVERSARY elements and the extensions BIRTHPLACE,
   DEATHDATE, DEATHPLACE described in [RFC6350] are represented as
   "Anniversary" objects included in the "anniversaries" array
   (Figure 5):

   o  BDAY and BIRTHPLACE are mapped onto "date" and "place" where
      "type" is set to "birth"

   o  DEATHDATE and DEATHPLACE are mapped onto "date" and "place" where
      "type" is set to "death"

   o  ANNIVERSARY is mapped onto "date" where "type" is set to "other"
      and "label" is set to a value describing in detail the kind of
      anniversary (e.g. "marriage date" for the wedding anniversary).

   Both birth and death places are represented as instances of the
   "Address" object.  The LANGUAGE parameter values of both BIRTHPLACE
   and DEATHPLACE elements are represented as corresponding entries of
   the "fullAddress.localizations" map.







Loffredo & Stepanek     Expires December 24, 2020               [Page 8]

Internet-Draft               jscontact-vcard                   June 2020


    BEGIN:VCARD
    VERSION:4.0
    ...
    BDAY:19531015T231000Z
    BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A.
    DEATHDATE:19960415
    DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A.
    ANNIVERSARY:19860201
    ...
    END:VCARD

    {
    ...
    "anniversaries":[
              {
               "type": "birth",
               "date": "19531015T231000Z",
               "place":
                      {
                      "fullAddress":
                                  {
                                   "value": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A."
                                  }
                      }
              },
              {
               "type": "birth",
               "date": "19531015T231000Z",
               "place":
                      {
                      "fullAddress":
                                  {
                                   "value": "4445 Courtright Street\nNew England, ND 58647\nU.S.A."
                                  }
                      }
              },
              {
               "type": "other",
               "label": "marriage date",
               "date": "19860201"
              }
            ],
    ...
    }

      Figure 5: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY
                              mapping example




Loffredo & Stepanek     Expires December 24, 2020               [Page 9]

Internet-Draft               jscontact-vcard                   June 2020


2.2.5.  GENDER

   TBD

2.3.  Delivery Addressing Properties

2.3.1.  ADR

   An ADR element is represented as an "Address" object in the
   "addresses" array (Figure 6).

   The ADR components are transformed into the "Address" members as
   reported in Table 2.

                   +------------------+----------------+
                   | ADR component    | Address member |
                   +------------------+----------------+
                   | p.o. box         | postOfficeBox  |
                   | extended address | extension      |
                   | street address   | street         |
                   | locality         | locality       |
                   | region           | region         |
                   | postal code      | postcode       |
                   | country name     | country        |
                   +------------------+----------------+

                      Table 2: ADR components mapping

   The LABEL parameter is converted into the "fullAddress" member.

   The PREF parameter is converted into the "isPreferred" member.

   The GEO parameter is converted into the "coordinates" member.

   The TZ parameter is converted into by the "timeZone" member.

   The TYPE parameter is converted into the "context" member.  The
   "home" value is replaced with the "private" value.

   The LANGUAGE parameter values are represented as different entries of
   the "fullAddress.localizations" map.

   The CC parameter defined by [RFC8605] is converted into the
   "countryCode" member.







Loffredo & Stepanek     Expires December 24, 2020              [Page 10]

Internet-Draft               jscontact-vcard                   June 2020


    BEGIN:VCARD
    VERSION:4.0
    ...
    ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA
    ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA
    ...
    END:VCARD

    {
    ...
    "addresses": [
          {
           "context": "work",
           "fullAddress":
                        {
                         "value": "54321 Oak St\nReston\nVA\n20190\nUSA"
                        },
           "street": "54321 Oak St",
           "locality": "Reston",
           "region": "VA",
           "country": "USA",
           "postcode": "20190",
           "countryCode": "US"
          },
          {
           "context": "private",
           "fullAddress":
                        {
                         "value": "12345 Elm St\nReston\nVA\n20190\nUSA"
                        },
           "street": "12345 Elm St",
           "locality": "Reston",
           "region": "VA",
           "country": "USA",
           "postcode": "20190",
           "countryCode": "US"
          }
    ]
    ...
    }

                       Figure 6: ADR mapping example

2.4.  Communications Properties







Loffredo & Stepanek     Expires December 24, 2020              [Page 11]

Internet-Draft               jscontact-vcard                   June 2020


2.4.1.  TEL

   A TEL element is represented as a "Resource" object in the "phones"
   array (Figure 7).  The vCard "type-param-tel" values are mapped onto
   the "type" member values.  Those vCard "type-param-tel" values that
   don't have a counterpart among the "type" member values are
   represented as entry keys of the "labels" map with the corresponding
   entry value set to true.  The "type-param" values are are mapped onto
   the "context" member values.  The "home" value is replaced with the
   "private" value.

   The PREF parameter is mapped onto the "isPreferred" member.

     BEGIN:VCARD
     VERSION:4.0
     ...
     TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555
     TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67
     ...
     END:VCARD

     {
     ...
     "phones":[
               {
                "context": "private",
                "type": "voice",
                "value": "tel:+1-555-555-5555;ext=5555",
                "isPreferred": true
               },
               {
                "context": "private",
                "value": "tel:+33-01-23-45-67"
               }
             ],
     ...
     }

                       Figure 7: TEL mapping example

2.4.2.  EMAIL

   An EMAIL element is represented as a "Resource" object in the
   "emails" array (Figure 8).  The vCard "type-param" values are mapped
   onto the "context" member values.  The "home" value is replaced with
   the "private" value.

   The PREF parameter is mapped onto the "isPreferred" member.



Loffredo & Stepanek     Expires December 24, 2020              [Page 12]

Internet-Draft               jscontact-vcard                   June 2020


       BEGIN:VCARD
       VERSION:4.0
       ...
       EMAIL;TYPE=work:jqpublic@xyz.example.com
       EMAIL;PREF=1:jane_doe@example.com
       ...
       END:VCARD

       {
       ...
       "emails":[
                 {
                  "context": "work",
                  "value": "jqpublic@xyz.example.com",
                 },
                 {
                  "context": "private",
                  "value": "jane_doe@example.com"
                  "isPreferred": true
                 }
               ],
       ...
       }

                      Figure 8: EMAIL mapping example

2.4.3.  IMPP

   An IMPP element is represented as a "Resource" object in the "online"
   array (Figure 9) whose "type" member is set to "username" and
   "labels" map contains the entry <"XMPP",true>.

   In case of a contact card related to an acconunt on another online
   service, the entry key SHOULD be the canonical service name,
   including capitalisation (e.g.  "Twitter", "Facebook", "Skype",
   "GitHub")

   The PREF and MEDIATYPE parameters are mapped onto the "isPreferred"
   and "mediaType" members respectively.












Loffredo & Stepanek     Expires December 24, 2020              [Page 13]

Internet-Draft               jscontact-vcard                   June 2020


       BEGIN:VCARD
       VERSION:4.0
       ...
       IMPP;PREF=1:xmpp:alice@example.com
       ...
       END:VCARD

       {
       ...
       "online":[
                 ...
                 {
                  "type": "username",
                  "labels": { "XMPP": true },
                  "value": "alice@example.com"
                 },
                 ...
               ],
       ...
       }

                      Figure 9: IMPP mapping example

2.4.4.  LANG

   A LANG element is represented through the "preferredContactLanguages"
   map (Figure 10): an entry for each language that may be used for
   contacting the entity associated with the JSCard.  The entry keys
   correspond to the language tags, the corresponding entry values are
   arrays of "ContactLanguage" objects.

   The TYPE and PREF parameters are mapped onto the "ContactLanguage"
   members "type" and "preference" respectively.

   If both PREF and TYPE parameters are missing, the array of
   "ContactLanguage" objects MUST be empty.















Loffredo & Stepanek     Expires December 24, 2020              [Page 14]

Internet-Draft               jscontact-vcard                   June 2020


       BEGIN:VCARD
       VERSION:4.0
       ...
       LANG;TYPE=work;PREF=1:en
       LANG;TYPE=work;PREF=2:fr
       LANG;TYPE=home:fr
       ...
       END:VCARD

       {
       ...
       "preferredContactLanguages" : {
                                      "en": [
                                             {
                                              "type": "work",
                                              "preference": 1
                                             }
                                            ],
                                      "fr": [
                                             {
                                              "type": "work",
                                              "preference": 2
                                             },
                                             {
                                              "type": "home",
                                             }
                                            ]
                                     },
       ...
       }

                      Figure 10: LANG mapping example

2.5.  Geographical Properties

   The GEO and TZ elements are not directly mapped into equivalent
   topmost JSCard members because the same information is represented
   through equivalent "Address" members.

   The ALTID parameter is used for associating both GEO and TZ elements
   with the related address information.  When the ALTID parameter is
   missing, the element should be associated with the first contact
   address.








Loffredo & Stepanek     Expires December 24, 2020              [Page 15]

Internet-Draft               jscontact-vcard                   June 2020


2.6.  Organizational Properties

2.6.1.  TITLE

   A TITLE element is mapped onto a "LocalizedString" object included in
   the "jobTitle" array (Figure 11).

   The ALTID parameter is used for for associating the language-
   dependent alternatives with a given element.

   The LANGUAGE parameter values are represented as corresponding
   entries of the "localizations" map.

       BEGIN:VCARD
       VERSION:4.0
       ...
       TITLE:Research Scientist
       ...
       END:VCARD

       {
       ...
       "jobTitle":[
                   {
                    "value": "Research Scientist"
                   }
                  ],
       ...
       }

                     Figure 11: TITLE mapping example

2.6.2.  ROLE

   A ROLE element is mapped onto a "LocalizedString" object included in
   the "role" array (Figure 12).

   The ALTID parameter is used for for associating the language-
   dependent alternatives with a given element.

   The LANGUAGE parameter values are represented as corresponding
   entries of the "localizations" map.









Loffredo & Stepanek     Expires December 24, 2020              [Page 16]

Internet-Draft               jscontact-vcard                   June 2020


       BEGIN:VCARD
       VERSION:4.0
       ...
       ROLE:Project Leader
       ...
       END:VCARD

       {
       ...
       "role":[
               {
                "value": "Project Leader"
               }
              ],
       ...
       }

                      Figure 12: ROLE mapping example

2.6.3.  LOGO

   A LOGO element is represented as a "Resource" object in the "online"
   array (Figure 13) whose "type" member is set to "uri" and "labels"
   map contains the entry <"logo",true>.

   The PREF and MEDIATYPE parameters are mapped onto the "isPreferred"
   and "mediaType" members respectively.
























Loffredo & Stepanek     Expires December 24, 2020              [Page 17]

Internet-Draft               jscontact-vcard                   June 2020


      BEGIN:VCARD
      VERSION:4.0
      ...
      LOGO:http://www.example.com/pub/logos/abccorp.jpg
      ...
      END:VCARD

      {
      ...
      "online":[
                ...
                {
                 "type": "uri",
                 "labels": { "logo": true },
                 "value": "http://www.example.com/pub/logos/abccorp.jpg"
                },
                ...
              ],
      ...
      }

                      Figure 13: LOGO mapping example

2.6.4.  ORG

   An ORG element is mapped onto a "LocalizedString" object included in
   the "organization" array (Figure 14).  The organization name includes
   the organizational units if any.

   The ALTID parameter is used for for associating the language-
   dependent alternatives with a given element.

   The LANGUAGE parameter values are represented as corresponding
   entries of the "localizations" map.

















Loffredo & Stepanek     Expires December 24, 2020              [Page 18]

Internet-Draft               jscontact-vcard                   June 2020


     BEGIN:VCARD
     VERSION:4.0
     ...
     ORG:ABC\, Inc.;North American Division;Marketing
     ...
     END:VCARD

     {
     ...
     "organization":[
                 {
                  "value": "ABC, Inc.;North American Division;Marketing"
                  }
                 ],
     ...
     }

                      Figure 14: ORG mapping example

2.6.5.  MEMBER

   According to the JSContact specification, a group of contact cards is
   represented through a JSCardGroup (Figure 15).  The contact cards
   composing the group are included in the "cards" array.  Therefore,
   the MEMBER element doesn't have a direct match with a JSCard feature.


























Loffredo & Stepanek     Expires December 24, 2020              [Page 19]

Internet-Draft               jscontact-vcard                   June 2020


      BEGIN:VCARD
      VERSION:4.0
      KIND:group
      FN:The Doe family
      MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af
      MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519
      END:VCARD
      BEGIN:VCARD
      VERSION:4.0
      FN:John Doe
      UID:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af
      END:VCARD
      BEGIN:VCARD
      VERSION:4.0
      FN:Jane Doe
      UID:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519
      END:VCARD

      {
      "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667",
      "name": "The Doe family",
      "cards": [
                {
                 "name": {
                          "fullName": {
                                       "value": "John Doe"
                                      }
                         },
                 "uid": "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af"
                },
                {
                 "name": {
                          "fullName": {
                                       "value": "Jane Doe"
                                      }
                         },
                 "uid": "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519f"
                }
               ]
      }

                         Figure 15: Group example

2.6.6.  RELATED

   All the RELATED elements are globally converted into the "relatedTo"
   map (Figure 16): an entry for each entity the entity described by the




Loffredo & Stepanek     Expires December 24, 2020              [Page 20]

Internet-Draft               jscontact-vcard                   June 2020


   JSCard is associated with.  The map keys are the "uid" values of the
   associated cards.

   Each map value is a "Relation" object including only the "relation"
   member represented as a set of relation types described in section
   6.6.6 of [RFC6350].

   If the relation type is unspecified, the "relation" is empty.

    BEGIN:VCARD
    VERSION:4.0
    ...
    RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
    RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf
    RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries.
    ...
    END:VCARD

    {
    ...
    "relatedTo":{
                  {
                   "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6":
                        {
                         "relation": {
                                      "friend": true
                                     }
                        }
                  },
                  {
                   "http://example.com/directory/jdoe.vcf":
                        {
                         "relation": {
                                      "contact": true
                                     }
                        }
                  },
                  {
                   "Please contact my assistant Jane Doe for any inquiries.":
                        {
                         "relation": { }
                        }
                  }
                }
    ...
    }

                    Figure 16: RELATED mapping example



Loffredo & Stepanek     Expires December 24, 2020              [Page 21]

Internet-Draft               jscontact-vcard                   June 2020


2.6.7.  CONTACT-URI

   A CONTACT-URI element defined by [RFC8605] is represented as a
   "Resource" object of the "online" array (Figure 17) whose "type"
   member is set to "uri" and "labels" map contains the entry <"contact-
   uri",true>.

   The PREF parameter is mapped onto the "isPreferred" member.

       BEGIN:VCARD
       VERSION:4.0
       ...
       CONTACT-URI;PREF=1:mailto:contact@example.com
       ...
       END:VCARD

       {
       ...
       "online":[
                 ...
                 {
                  "type": "uri",
                  "labels": { "contact-uri": true },
                  "value": "mailto:contact@example.com",
                  "isPreferred": true
                 },
                 ...
               ],
       ...
       }

                  Figure 17: CONTACT-URI mapping example

2.7.  Personal Information Properties

2.7.1.  EXPERTISE

   An EXPERTISE element defined by [RFC6715] is represented as a
   "PersonalInformation" object in the "personalInfo" array (Figure 18).
   The "type" member is set to "expertise".

   The LEVEL parameter is mapped onto the "level" member with following
   mapping:

   o  "beginner" is converted into "low";
   o  "average" is converted into "medium";
   o  "expert" is converted into "high".




Loffredo & Stepanek     Expires December 24, 2020              [Page 22]

Internet-Draft               jscontact-vcard                   June 2020


   The INDEX parameter is represented as the index of the expertise
   among the declared expertises.

       BEGIN:VCARD
       VERSION:4.0
       ...
       EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature
       EXPERTISE;INDEX=1;LEVEL=expert:chemistry
       ...
       END:VCARD

       {
       ...
       "personalInfo":[
                       ...
                       {
                        "type": "expertise",
                        "value": "chemistry",
                        "level": "high"
                       },
                       {
                        "type": "expertise",
                        "value": "chinese literature",
                        "level": "low"
                       }
                       ...
                      ]
       ...
       }

                   Figure 18: EXPERTISE mapping example

2.7.2.  HOBBY

   An HOBBY element defined by [RFC6715] is represented as a
   "PersonalInformation" object in the "personalInfo" array (Figure 19).
   The "type" member is set to "hobby".

   The LEVEL parameter is mapped onto the "level" member with a direct
   mapping.

   The INDEX parameter is represented as the index of the hobby among
   the declared hobbies.








Loffredo & Stepanek     Expires December 24, 2020              [Page 23]

Internet-Draft               jscontact-vcard                   June 2020


       BEGIN:VCARD
       VERSION:4.0
       ...
       HOBBY;INDEX=1;LEVEL=high:reading
       HOBBY;INDEX=2;LEVEL=high:sewing
       ...
       END:VCARD

       {
       ...
       "personalInfo":[
                       ...
                       {
                        "type": "hobby",
                        "value": "reading",
                        "level": "high"
                       },
                       {
                        "type": "hobby",
                        "value": "sewing",
                        "level": "high"
                       }
                       ...
                      ]
       ...
       }

                     Figure 19: HOBBY mapping example

2.7.3.  INTEREST

   An INTEREST element defined by [RFC6715] is represented as a
   "PersonalInformation" object in the "personalInfo" array (Figure 20).
   The "type" member is set to "interest".

   The LEVEL parameter is mapped onto the "level" member with a direct
   mapping.

   The INDEX parameter is represented as the index of the interest among
   the declared interests.











Loffredo & Stepanek     Expires December 24, 2020              [Page 24]

Internet-Draft               jscontact-vcard                   June 2020


       BEGIN:VCARD
       VERSION:4.0
       ...
       INTEREST;INDEX=1;LEVEL=medium:r&b music
       INTEREST;INDEX=2;LEVEL=high:rock 'n' roll music
       ...
       END:VCARD

       {
       ...
       "personalInfo":[
                       ...
                       {
                        "type": "interest",
                        "value": "r&b music",
                        "level": "medium"
                       },
                       {
                        "type": "interest",
                        "value": "rock 'n' roll music",
                        "level": "high"
                       }
                       ...
                      ]
       ...
       }

                    Figure 20: INTEREST mapping example

2.7.4.  ORG-DIRECTORY

   An ORG-DIRECTORY element is represented as a "Resource" object in the
   "online" array (Figure 21) whose "type" member is set to "uri" and
   "labels" map contains the entry <"org-directory",true>.

   The PREF parameter is mapped onto the "isPreferred" member.

   The INDEX parameter is represented as the index of the directory
   among the online resources with the "org-directory" key in the
   "labels" map.











Loffredo & Stepanek     Expires December 24, 2020              [Page 25]

Internet-Draft               jscontact-vcard                   June 2020


    BEGIN:VCARD
    VERSION:4.0
    ...
    ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com
    ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering
    ...
    END:VCARD

    {
    ...
    "online":[
              ...
              {
               "type": "uri",
               "labels": { "org-directory": true },
               "value": "http://directory.mycompany.example.com"
              },
              {
               "type": "uri",
               "labels": { "org-directory": true },
               "value": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering",
               "isPreferred": true
              },
              ...
            ],
    ...
    }

                 Figure 21: ORG-DIRECTORY mapping example

2.8.  Explanatory Properties

2.8.1.  CATEGORIES

   A CATEGORIES element is converted into an object in the "categories"
   array (Figure 22).















Loffredo & Stepanek     Expires December 24, 2020              [Page 26]

Internet-Draft               jscontact-vcard                   June 2020


       BEGIN:VCARD
       VERSION:4.0
       ...
       CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY
       ...
       END:VCARD

       {
       ...
       "categories":[
                     "INTERNET",
                     "IETF",
                     "INDUSTRY",
                     "INFORMATION TECHNOLOGY"
                    ]
       ...
       }

                   Figure 22: CATEGORIES mapping example

2.8.2.  NOTE

   A NOTE element is mapped onto a "LocalizedString" object included in
   the "notes" array (Figure 23).

   The ALTID parameter is used for associating the language-dependent
   alternatives with a given element.

   The LANGUAGE parameter values are represented as corresponding
   entries of the "localizations" map.





















Loffredo & Stepanek     Expires December 24, 2020              [Page 27]

Internet-Draft               jscontact-vcard                   June 2020


    BEGIN:VCARD
    VERSION:4.0
    ...
    NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri.
    ...
    END:VCARD

    {
    ...
    "notes":[
             {
              "value": "This fax number is operational 0800 to 1715 EST, Mon-Fri."
             }
            ]
    ...
    }

                      Figure 23: NOTE mapping example

2.8.3.  PRODID

   The PRODID element is converted into the "prodId" member (Figure 24).

       BEGIN:VCARD
       VERSION:4.0
       ...
       PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN
       ...
       END:VCARD

       {
       ...
       "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN"
       ...
       }

                     Figure 24: PRODID mapping example

2.8.4.  REV

   The REV element is transformed into the "updated" member (Figure 25).










Loffredo & Stepanek     Expires December 24, 2020              [Page 28]

Internet-Draft               jscontact-vcard                   June 2020


       BEGIN:VCARD
       VERSION:4.0
       ...
       REV:19951031T222710Z
       ...
       END:VCARD

       {
       ...
       "updated": "19951031T222710Z"
       ...
       }

                      Figure 25: REV mapping example

2.8.5.  SOUND

   A SOUND element is represented as a "Resource" object in the "online"
   array (Figure 26) whose "type" member is set to "uri" and "labels"
   map contains the entry <"sound",true>.

   The PREF and MEDIATYPE parameters are mapped onto the "isPreferred"
   and "mediaType" members respectively.

    BEGIN:VCARD
    VERSION:4.0
    ...
    SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com
    ...
    END:VCARD

    {
    ...
    "online":[
              ...
              {
               "type": "uri",
               "labels": { "sound": true },
               "value": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com"
              },
              ...
            ],
    ...
    }

                     Figure 26: SOUND mapping example





Loffredo & Stepanek     Expires December 24, 2020              [Page 29]

Internet-Draft               jscontact-vcard                   June 2020


2.8.6.  UID

   The UID element corresponds to the "uid" member (Figure 27).

       BEGIN:VCARD
       VERSION:4.0
       ...
       UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
       ...
       END:VCARD

       {
       ...
       "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
       ...
       }

                      Figure 27: UID mapping example

2.8.7.  CLIENTPIDMAP and PID Parameter

   TBD

2.8.8.  URL

   An URL element is represented as a "Resource" object in the "online"
   array (Figure 28) whose "type" member is set to "uri" and "labels"
   map contains the entry <"url",true>.

   The PREF and MEDIATYPE parameters are mapped onto the "isPreferred"
   and "mediaType" members respectively.




















Loffredo & Stepanek     Expires December 24, 2020              [Page 30]

Internet-Draft               jscontact-vcard                   June 2020


    BEGIN:VCARD
    VERSION:4.0
    ...
    URL:http://example.org/restaurant.french/~chezchic.html
    ...
    END:VCARD

    {
    ...
    "online":[
              ...
              {
               "type": "uri",
               "labels": { "url": true },
               "value": "http://example.org/restaurant.french/~chezchic.html"
              },
              ...
            ],
    ...
    }

                      Figure 28: URL mapping example

2.8.9.  VERSION

   The VERSION property doesn't have a direct match with a JSCard
   feature.

2.9.  Security Properties

2.9.1.  KEY

   A KEY element is represented as a "Resource" object in the "online"
   array (Figure 29) whose "type" member is set to "uri" and "labels"
   map contains the entry <"key",true>.

   The PREF and MEDIATYPE parameters are mapped onto the "isPreferred"
   and "mediaType" members respectively.













Loffredo & Stepanek     Expires December 24, 2020              [Page 31]

Internet-Draft               jscontact-vcard                   June 2020


       BEGIN:VCARD
       VERSION:4.0
       ...
       KEY:http://www.example.com/keys/jdoe.cer
       ...
       END:VCARD

       {
       ...
       "online":[
                 ...
                 {
                  "type": "uri",
                  "labels": { "key": true },
                  "value": "http://www.example.com/keys/jdoe.cer"
                 },
                 ...
               ],
       ...
       }

                      Figure 29: KEY mapping example

2.10.  Calendar Properties

2.10.1.  FBURL

   A FBURL element is represented as a "Resource" object of the "online"
   array (Figure 30) whose "type" member is set to "uri" and "labels"
   map contains the entry <"fburl",true>.

   The PREF and MEDIATYPE parameters are mapped ontoy the "isPreferred"
   and "mediaType" members respectively.


















Loffredo & Stepanek     Expires December 24, 2020              [Page 32]

Internet-Draft               jscontact-vcard                   June 2020


      BEGIN:VCARD
      VERSION:4.0
      ...
      FBURL;PREF=1:http://www.example.com/busy/janedoe
      FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb
      ...
      END:VCARD

      {
      ...
      "online":[
                ...
                {
                 "type": "uri",
                 "labels": { "fburl": true },
                 "value": "http://www.example.com/busy/janedoe",
                 "isPreferred": true
                },
                {
                 "type": "uri",
                 "labels": { "fburl": true },
                 "value": "ftp://example.com/busy/project-a.ifb",
                 "mediaType": "text/calendar"
                },
                ...
              ],
      ...
      }

                     Figure 30: FBURL mapping example

2.10.2.  CALADRURI

   A CALADRURI element is represented as a "Resource" object of the
   "online" array (Figure 31) whose "type" member is set to "uri" and
   "labels" map contains the entry <"caladruri",true>.

   The PREF and MEDIATYPE parameters are mapped onto the "isPreferred"
   and "mediaType" members respectively.












Loffredo & Stepanek     Expires December 24, 2020              [Page 33]

Internet-Draft               jscontact-vcard                   June 2020


       BEGIN:VCARD
       VERSION:4.0
       ...
       CALADRURI;PREF=1:mailto:janedoe@example.com
       CALADRURI:http://example.com/calendar/jdoe
       ...
       END:VCARD

       {
       ...
       "online":[
                 ...
                 {
                  "type": "uri",
                  "labels": { "caladruri": true },
                  "value": "mailto:janedoe@example.com",
                  "isPreferred": true
                 },
                 {
                  "type": "uri",
                  "labels": { "caladruri": true },
                  "value": "http://example.com/calendar/jdoe"
                 },
                 ...
               ],
       ...
       }

                   Figure 31: CALADRURI mapping example

2.10.3.  CALURI

   A CALURI element is represented as a "Resource" object of the
   "online" array (Figure 32) whose "type" member is set to "uri" and
   "labels" map contains the entry <"caluri",true>.

   The PREF and MEDIATYPE parameters are mapped onto the "isPreferred"
   and "mediaType" members respectively.













Loffredo & Stepanek     Expires December 24, 2020              [Page 34]

Internet-Draft               jscontact-vcard                   June 2020


       BEGIN:VCARD
       VERSION:4.0
       ...
       CALURI;PREF=1:http://cal.example.com/calA
       CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics
       ...
       END:VCARD

       {
       ...
       "online":[
                 ...
                 {
                  "type": "uri",
                  "labels": { "caluri": true },
                  "value": "http://cal.example.com/calA",
                  "isPreferred": true
                 },
                 {
                  "type": "uri",
                  "labels": { "caluri": true },
                  "value": "ftp://ftp.example.com/calA.ics",
                  "mediaType": "text/calendar"
                 },
                 ...
               ],
       ...
       }

                     Figure 32: CALURI mapping example

2.11.  Extended Properties

   If an extended property is a resource, JSCard already allows to
   represent it by setting the "type" member to "other" and specifying a
   value for the "labels" map.

   Any other property supporting a custom feature MAY be added and its
   name MUST be prefixed with a specific domain name to avoid conflict,
   e.g. "example.com/customprop".

2.12.  JSCard Required Properties

   While converting a vCard into a JSCard, only the topmost "uid" member
   is required.






Loffredo & Stepanek     Expires December 24, 2020              [Page 35]

Internet-Draft               jscontact-vcard                   June 2020


2.13.  JSCard Unmatched Properties

   The "preferredContactMethod" member doesn't match any vCard element.

3.  IANA Considerations

   This document has no actions for IANA.

4.  Security Considerations

   This document doesn't report any security consideration.

5.  References

5.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC6350]  Perreault, S., "vCard Format Specification", RFC 6350,
              DOI 10.17487/RFC6350, August 2011,
              <https://www.rfc-editor.org/info/rfc6350>.

   [RFC6473]  Saint-Andre, P., "vCard KIND:application", RFC 6473,
              DOI 10.17487/RFC6473, December 2011,
              <https://www.rfc-editor.org/info/rfc6473>.

   [RFC6474]  Li, K. and B. Leiba, "vCard Format Extensions: Place of
              Birth, Place and Date of Death", RFC 6474,
              DOI 10.17487/RFC6474, December 2011,
              <https://www.rfc-editor.org/info/rfc6474>.

   [RFC6715]  Cauchie, D., Leiba, B., and K. Li, "vCard Format
              Extensions: Representing vCard Extensions Defined by the
              Open Mobile Alliance (OMA) Converged Address Book (CAB)
              Group", RFC 6715, DOI 10.17487/RFC6715, August 2012,
              <https://www.rfc-editor.org/info/rfc6715>.

   [RFC6869]  Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard
              KIND:device", RFC 6869, DOI 10.17487/RFC6869, February
              2013, <https://www.rfc-editor.org/info/rfc6869>.

   [RFC7095]  Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095,
              DOI 10.17487/RFC7095, January 2014,
              <https://www.rfc-editor.org/info/rfc7095>.




Loffredo & Stepanek     Expires December 24, 2020              [Page 36]

Internet-Draft               jscontact-vcard                   June 2020


   [RFC8605]  Hollenbeck, S. and R. Carney, "vCard Format Extensions:
              ICANN Extensions for the Registration Data Access Protocol
              (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019,
              <https://www.rfc-editor.org/info/rfc8605>.

5.2.  Informative References

   [draft-ietf-jmap-jscontact]
              "JSContact: A JSON representation of contact data",
              <https://datatracker.ietf.org/doc/draft-ietf-jmap-
              jscontact/>.

Authors' Addresses

   Mario Loffredo
   IIT-CNR/Registro.it
   Via Moruzzi,1
   Pisa  56124
   IT

   Email: mario.loffredo@iit.cnr.it
   URI:   http://www.iit.cnr.it


   Robert Stepanek
   FastMail
   PO Box 234, Collins St West
   Melbourne  VIC 8007
   AU

   Email: rsto@fastmailteam.com
   URI:   https://www.fastmail.com



















Loffredo & Stepanek     Expires December 24, 2020              [Page 37]