[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00 01

jmap                                                         M. Loffredo
Internet-Draft                                       IIT-CNR/Registro.it
Intended status: Informational                               R. Stepanek
Expires: August 14, 2020                                        FastMail
                                                       February 11, 2020


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

Abstract

   This document provides an informational guideline 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 August 14, 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 August 14, 2020                [Page 1]


Internet-Draft               jscontact-vcard               February 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.  SOURCE  . . . . . . . . . . . . . . . . . . . . . . .   4
       2.1.2.  KIND  . . . . . . . . . . . . . . . . . . . . . . . .   5
     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 . . . . . . . . . . . . . . . .  15
       2.6.1.  TITLE . . . . . . . . . . . . . . . . . . . . . . . .  15
       2.6.2.  ROLE  . . . . . . . . . . . . . . . . . . . . . . . .  16
       2.6.3.  LOGO  . . . . . . . . . . . . . . . . . . . . . . . .  17
       2.6.4.  ORG . . . . . . . . . . . . . . . . . . . . . . . . .  17
       2.6.5.  MEMBER  . . . . . . . . . . . . . . . . . . . . . . .  18
       2.6.6.  RELATED . . . . . . . . . . . . . . . . . . . . . . .  19
       2.6.7.  CONTACT-URI . . . . . . . . . . . . . . . . . . . . .  21
     2.7.  Personal Information Properties . . . . . . . . . . . . .  21
       2.7.1.  EXPERTISE . . . . . . . . . . . . . . . . . . . . . .  21
       2.7.2.  HOBBY . . . . . . . . . . . . . . . . . . . . . . . .  22
       2.7.3.  INTEREST  . . . . . . . . . . . . . . . . . . . . . .  23
       2.7.4.  ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . .  24
     2.8.  Explanatory Properties  . . . . . . . . . . . . . . . . .  25
       2.8.1.  CATEGORIES  . . . . . . . . . . . . . . . . . . . . .  25
       2.8.2.  NOTE  . . . . . . . . . . . . . . . . . . . . . . . .  26
       2.8.3.  PROID . . . . . . . . . . . . . . . . . . . . . . . .  27
       2.8.4.  REV . . . . . . . . . . . . . . . . . . . . . . . . .  27
       2.8.5.  SOUND . . . . . . . . . . . . . . . . . . . . . . . .  27
       2.8.6.  UID . . . . . . . . . . . . . . . . . . . . . . . . .  28
       2.8.7.  PID Parameter and CLIENTPIDMAP  . . . . . . . . . . .  28
       2.8.8.  URL . . . . . . . . . . . . . . . . . . . . . . . . .  29
     2.9.  Security Properties . . . . . . . . . . . . . . . . . . .  29
       2.9.1.  KEY . . . . . . . . . . . . . . . . . . . . . . . . .  29



Loffredo & Stepanek      Expires August 14, 2020                [Page 2]


Internet-Draft               jscontact-vcard               February 2020


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

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 format 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 an informational
   guide 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.

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





Loffredo & Stepanek      Expires August 14, 2020                [Page 3]


Internet-Draft               jscontact-vcard               February 2020


   o  Some vCard elements represented individually have been modeled as
      members of JSCard elements.

   o  The vCard custom elements, identified by the prefix "x-", don't
      have a direct counterpart in 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 RFC 2119 ([RFC2119]).

2.  Mapping

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

2.1.  General Properties

2.1.1.  SOURCE

   The vCard SOURCE element is represented in JSCard as a "Resource"
   item of the "online" array (Figure 1).  The "type" and "label"
   members of the "Resource" object are set to "uri" and "source"
   respectively.

   The PREF and MEDIATYPE parameters can be represented by the
   "isPreferred" and "mediaType" properties respectively.






















Loffredo & Stepanek      Expires August 14, 2020                [Page 4]


Internet-Draft               jscontact-vcard               February 2020


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

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

                     Figure 1: SOURCE mapping example

2.1.2.  KIND

   The vCard KIND element is mapped onto the JSCard "kind" property
   (Figure 2).  Such property can contain one of the values, except
   "group", described in section 6.1.4 of RFC6350 [RFC6350] and extended
   with the values declared in RFC6473 [RFC6473] and RFC6969 [RFC6869].

   A group of cards is represented by a dedicated object named
   JSCardGroup.

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

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

                      Figure 2: KIND mapping example




Loffredo & Stepanek      Expires August 14, 2020                [Page 5]


Internet-Draft               jscontact-vcard               February 2020


2.2.  Identification Properties

2.2.1.  FN

   FN is converted into the "fullName" property.  The presence of more
   than one name is implicitly associated with the translation of the
   full name in various languages.  Each translation corresponds to a
   different entry of the "localizations" map that is an optional member
   of the "fullName" object (Figure 3).

2.2.2.  N and NICKNAME

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

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

   o  NICKNAME is mapped onto an item whose "type" is "nickname"; an
      item for each 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 August 14, 2020                [Page 6]


Internet-Draft               jscontact-vcard               February 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

   The vCard PHOTO element is represented in JSCard as a "Resource" item
   of the "online" array (Figure 4).  The "type" and "label" members are
   set to "uri" and "photo" respectively.

   The PREF and MEDIATYPE parameters can be represented by the
   "isPreferred" and "mediaType" properties respectively.
















Loffredo & Stepanek      Expires August 14, 2020                [Page 7]


Internet-Draft               jscontact-vcard               February 2020


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

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

                      Figure 4: PHOTO mapping example

2.2.4.  BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY

   The vCard BDAY and ANNIVERSARY elements and the vCard extensions
   BIRTHPLACE, DEATHDATE, DEATHPLACE described in RFC6474 [RFC6350] are
   represented in JSCard as "Anniversary" items of 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 can be expressed as corresponding entries of the
   "localizations" map included in the "fullAddress" object.







Loffredo & Stepanek      Expires August 14, 2020                [Page 8]


Internet-Draft               jscontact-vcard               February 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 August 14, 2020                [Page 9]


Internet-Draft               jscontact-vcard               February 2020


2.2.5.  GENDER

   TBD

2.3.  Delivery Addressing Properties

2.3.1.  ADR

   The vCard ADR element is represented in JSCard as an "Address" item
   of the "addresses" array (Figure 6).

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

                  +------------------+------------------+
                  | ADR component    | Address property |
                  +------------------+------------------+
                  | 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" property.

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

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

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

   The TYPE parameter is converted into the "context" property.  The
   "home" value is replaced by the "private" value.

   The LANGUAGE parameter values can be represented as different entries
   of the "localizations" map that is an optional member of the
   "fullAddress" object.

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






Loffredo & Stepanek      Expires August 14, 2020               [Page 10]


Internet-Draft               jscontact-vcard               February 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\USA"
                         },
            "street": "54321 Oak St",
            "locality": "Reston",
            "region": "VA",
            "country": "USA",
            "postcode": "20190",
            "countryCode": "US"
           },
           {
            "context": "private",
            "fullAddress":
                         {
                          "value": "12345 Elm St\nReston\nVA\n20190\USA"
                         },
            "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 August 14, 2020               [Page 11]


Internet-Draft               jscontact-vcard               February 2020


2.4.1.  TEL

   The vCard TEL element is represented in JSCard as a "Resource" item
   of the "phones" array (Figure 7).  The vCard "type-param-tel" values
   are represented by the "type" member while the "type-param" values
   are represented by the "context" member.  The "home" value is
   replaced by the "private" value.

   The PREF parameter can be represented by 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":[
               {
                "type": "voice",
                "context": "private",
                "value": "tel:+1-555-555-5555;ext=5555",
                "isPreferred": true
               },
               {
                "type": "voice",
                "context": "private",
                "value": "tel:+33-01-23-45-67"
               }
             ],
     ...
     }

                       Figure 7: TEL mapping example

2.4.2.  EMAIL

   The vCard EMAIL element is represented in JSCard as a "Resource" item
   of the "emails" array (Figure 8).  The vCard "type-param" values are
   represented by the "context" member.  The "home" value is replaced by
   the "private" value.

   The PREF parameter can be represented by the "isPreferred" member.





Loffredo & Stepanek      Expires August 14, 2020               [Page 12]


Internet-Draft               jscontact-vcard               February 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

   The vCard IMPP element is represented in JSCard as a "Resource" item
   of the "online" array (Figure 9).  The "type" and "label" members are
   set to "username" and "XMPP" respectively.

   The PREF and MEDIATYPE parameters can be represented by the
   "isPreferred" and "mediaType" properties respectively.

















Loffredo & Stepanek      Expires August 14, 2020               [Page 13]


Internet-Draft               jscontact-vcard               February 2020


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

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

                      Figure 9: IMPP mapping example

2.4.4.  LANG

   The vCard LANG element is represented in JSCard 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 items.

   The TYPE and PREF parameters can be represented by, respectively, the
   ContactLanguage properties "type" and "preference".

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















Loffredo & Stepanek      Expires August 14, 2020               [Page 14]


Internet-Draft               jscontact-vcard               February 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 elements because the same information is represented
   through equivalent "Address" properties.

2.6.  Organizational Properties

2.6.1.  TITLE

   The vCard TITLE element is mapped onto the JSCard "jobTitle" array;
   an item for each title (Figure 11).

   The LANGUAGE parameter values can be expressed as corresponding
   entries of the "localizations" map included in each "Resource" item.



Loffredo & Stepanek      Expires August 14, 2020               [Page 15]


Internet-Draft               jscontact-vcard               February 2020


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

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

                     Figure 11: TITLE mapping example

2.6.2.  ROLE

   The vCard ROLE element is mapped onto the JSCard "role" array; an
   item for each role (Figure 12).

   The LANGUAGE parameter values can be expressed as corresponding
   entries of the "localizations" map included in each "Resource" item.

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

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

                      Figure 12: ROLE mapping example






Loffredo & Stepanek      Expires August 14, 2020               [Page 16]


Internet-Draft               jscontact-vcard               February 2020


2.6.3.  LOGO

   The vCard LOGO element is represented in JSCard as a "Resource" item
   of the "online" array (Figure 13).  The "type" and "label" members
   are set to "uri" and "logo" respectively.

   The PREF and MEDIATYPE parameters can be represented by the
   "isPreferred" and "mediaType" properties respectively.

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

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

                      Figure 13: LOGO mapping example

2.6.4.  ORG

   The vCard ORG element is mapped onto the JSCard "organization" array;
   an item for each organization (Figure 14).  The organization name
   includes the organizational units if any.

   The LANGUAGE parameter values can be expressed as corresponding
   entries of the "localizations" map included in each "Resource" item.











Loffredo & Stepanek      Expires August 14, 2020               [Page 17]


Internet-Draft               jscontact-vcard               February 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 by a dedicated object named JSCardGroup (Figure 15).  The
   contact cards composing the group are included in the "cards" array.
   Therefore, the vCard MEMBER element doesn't have a direct match with
   a corresponding JSCard element.

























Loffredo & Stepanek      Expires August 14, 2020               [Page 18]


Internet-Draft               jscontact-vcard               February 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

   The vCard RELATED element is converted into the "relatedTo" map
   (Figure 16): an entry for each entity the entity described by the




Loffredo & Stepanek      Expires August 14, 2020               [Page 19]


Internet-Draft               jscontact-vcard               February 2020


   JSCard is associated with.  The map keys are the UUIDs of the
   associated cards.

   Each map value is an object including only the "relation" property
   represented as a set of relation types described in section 6.6.6 of
   RFC6350 [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 August 14, 2020               [Page 20]


Internet-Draft               jscontact-vcard               February 2020


2.6.7.  CONTACT-URI

   The vCard CONTACT-URI element defined by RFC8605 [RFC8605] is
   represented in JSCard as a "Resource" item of the "online" array
   (Figure 17).  The "type" and "label" members of the "Resource" object
   are set to "uri" and "contact-uri" respectively.

   The PREF parameter can be represented by the "isPreferred" property.

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

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

                  Figure 17: CONTACT-URI mapping example

2.7.  Personal Information Properties

2.7.1.  EXPERTISE

   The vCard EXPERTISE element defined by RFC6715 [RFC6715] is
   represented in JSCard as a "PersonalInformation" item of the
   "personalInfo" array (Figure 18).  The "type" property is set to
   "expertise".

   The LEVEL parameter can be represented by the "level" property with
   following mapping:

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



Loffredo & Stepanek      Expires August 14, 2020               [Page 21]


Internet-Draft               jscontact-vcard               February 2020


   The INDEX parameter is represented by the position 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

   The vCard HOBBY element defined by RFC6715 [RFC6715] is represented
   in JSCard as a "PersonalInformation" item of the "personalInfo" array
   (Figure 19).  The "type" property is set to "hobby".

   The LEVEL parameter can be represented by the "level" property with a
   direct mapping.

   The INDEX parameter is represented by the position of the hobby among
   the declared hobbies.








Loffredo & Stepanek      Expires August 14, 2020               [Page 22]


Internet-Draft               jscontact-vcard               February 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

   The vCard INTEREST element defined by RFC6715 [RFC6715] is
   represented in JSCard as a "PersonalInformation" item of the
   "personalInfo" array (Figure 20).  The "type" property is set to
   "interest".

   The LEVEL parameter can be represented by the "level" property with a
   direct mapping.

   The INDEX parameter is represented by the position of the interest
   among the declared interests.










Loffredo & Stepanek      Expires August 14, 2020               [Page 23]


Internet-Draft               jscontact-vcard               February 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

   The vCard ORG-DIRECTORY element is represented in JSCard as a
   "Resource" item of the "online" array (Figure 21).  The "type" and
   "label" members are set to "uri" and "org-directory" respectively.

   The PREF parameter can be represented by the "isPreferred" property.

   The INDEX parameter is represented by the position of the directory
   among the online resources with the "label" property set to "org-
   directory".











Loffredo & Stepanek      Expires August 14, 2020               [Page 24]


Internet-Draft               jscontact-vcard               February 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",
               "label": "org-directory",
               "value": "http://directory.mycompany.example.com"
              },
              {
               "type": "uri",
               "label": "org-directory",
               "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

   The vCard CATEGORIES element is converted into the JSCard
   "categories" array (Figure 22); an item for each category.















Loffredo & Stepanek      Expires August 14, 2020               [Page 25]


Internet-Draft               jscontact-vcard               February 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

   The vCard NOTE element is mapped onto the JSCard "notes" array
   (Figure 23); an item for each note.

   The LANGUAGE parameter values can be expressed as corresponding
   entries of the "localizations" map included in each "Resource" item.

    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





Loffredo & Stepanek      Expires August 14, 2020               [Page 26]


Internet-Draft               jscontact-vcard               February 2020


2.8.3.  PROID

   The vCard PRODID element is converted into the JSCard "prodId"
   property (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 vCard REV element is transformed into the JSCard "updated"
   property (Figure 25).

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

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

                      Figure 25: REV mapping example

2.8.5.  SOUND

   The vCard SOUND element is represented in JSCard as a "Resource" item
   of the "online" array (Figure 26).  The "type" and "label" members
   are set to "uri" and "sound" respectively.

   The PREF and MEDIATYPE parameters can be represented by the
   "isPreferred" and "mediaType" properties respectively.



Loffredo & Stepanek      Expires August 14, 2020               [Page 27]


Internet-Draft               jscontact-vcard               February 2020


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

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

                     Figure 26: SOUND mapping example

2.8.6.  UID

   The vCard UID element corresponds to the JSCard "uid" property
   (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.  PID Parameter and CLIENTPIDMAP

   TBD





Loffredo & Stepanek      Expires August 14, 2020               [Page 28]


Internet-Draft               jscontact-vcard               February 2020


2.8.8.  URL

   The vCard URL element is represented in JSCard as a "Resource" item
   of the "online" array (Figure 28).  The "type" and "label" members
   are set to "uri" and "url" respectively.

   The PREF and MEDIATYPE parameters can be represented by the
   "isPreferred" and "mediaType" properties respectively.

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

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

                      Figure 28: URL mapping example

2.9.  Security Properties

2.9.1.  KEY

   The vCard KEY element is represented in JSCard as a "Resource" item
   of the "online" array (Figure 29).  The "type" and "label" members
   are set to "uri" and "key" respectively.

   The PREF and MEDIATYPE parameters can be represented by the
   "isPreferred" and "mediaType" properties respectively.









Loffredo & Stepanek      Expires August 14, 2020               [Page 29]


Internet-Draft               jscontact-vcard               February 2020


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

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

                      Figure 29: KEY mapping example

2.10.  Calendar Properties

2.10.1.  FBURL

   The vCard FBURL element is represented in JSCard as a "Resource" item
   of the "online" array (Figure 30).  The "type" and "label" members
   are set to "uri" and "fburl" respectively.

   The PREF and MEDIATYPE parameters can be represented by the
   "isPreferred" and "mediaType" properties respectively.


















Loffredo & Stepanek      Expires August 14, 2020               [Page 30]


Internet-Draft               jscontact-vcard               February 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",
                 "label": "fburl",
                 "value": "http://www.example.com/busy/janedoe",
                 "isPreferred": true
                },
                {
                 "type": "uri",
                 "label": "fburl",
                 "value": "ftp://example.com/busy/project-a.ifb",
                 "mediaType": "text/calendar"
                },
                ...
              ],
      ...
      }

                     Figure 30: FBURL mapping example

2.10.2.  CALADRURI

   The vCard CALADRURI element is represented in JSCard as a "Resource"
   item of the "online" array (Figure 31).  The "type" and "label"
   members are set to "uri" and "caladruri" respectively.

   The PREF and MEDIATYPE parameters can be represented by the
   "isPreferred" and "mediaType" properties respectively.












Loffredo & Stepanek      Expires August 14, 2020               [Page 31]


Internet-Draft               jscontact-vcard               February 2020


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

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

                   Figure 31: CALADRURI mapping example

2.10.3.  CALURI

   The vCard CALURI element is represented in JSCard as a "Resource"
   item of the "online" array (Figure 32).  The "type" and "label"
   members are set to "uri" and "caluri" respectively.

   The PREF and MEDIATYPE parameters can be represented by the
   "isPreferred" and "mediaType" properties respectively.













Loffredo & Stepanek      Expires August 14, 2020               [Page 32]


Internet-Draft               jscontact-vcard               February 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",
                  "label": "caluri",
                  "value": "http://cal.example.com/calA",
                  "isPreferred": true
                 },
                 {
                  "type": "uri",
                  "label": "caluri",
                  "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" property to "other" and specifying
   a value for the "label" property.

   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's Required Properties

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






Loffredo & Stepanek      Expires August 14, 2020               [Page 33]


Internet-Draft               jscontact-vcard               February 2020


2.13.  JSCard's Unmatched Properties

   The "preferredContactMethod" property 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 August 14, 2020               [Page 34]


Internet-Draft               jscontact-vcard               February 2020


   [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", STD 90, RFC 8259,
              DOI 10.17487/RFC8259, December 2017,
              <https://www.rfc-editor.org/info/rfc8259>.

   [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 August 14, 2020               [Page 35]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/