Skip to main content

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

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Replaced".
Authors Mario Loffredo , Robert Stepanek
Last updated 2021-04-14
Replaces draft-loffredo-jmap-jscontact-vcard
Replaced by draft-ietf-calext-jscontact-vcard
RFC stream Internet Engineering Task Force (IETF)
Formats
Additional resources Mailing list discussion
Stream WG state WG Document
Document shepherd (None)
IESG IESG state I-D Exists
Consensus boilerplate Unknown
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-ietf-jmap-jscontact-vcard-03
jmap                                                         M. Loffredo
Internet-Draft                                       IIT-CNR/Registro.it
Intended status: Standards Track                             R. Stepanek
Expires: October 16, 2021                                       FastMail
                                                          April 14, 2021

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

Abstract

   This document defines how to convert contact information as defined
   in the JSContact [draft-ietf-jmap-jscontact] specification 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 October 16, 2021.

Copyright Notice

   Copyright (c) 2021 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 October 16, 2021                [Page 1]
Internet-Draft               jscontact-vcard                  April 2021

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Motivation  . . . . . . . . . . . . . . . . . . . . . . .   3
     1.2.  Scope and Caveats . . . . . . . . . . . . . . . . . . . .   4
       1.2.1.  Extensions  . . . . . . . . . . . . . . . . . . . . .   4
     1.3.  Conventions Used in This Document . . . . . . . . . . . .   4
   2.  Translating vCard properties to JSContact . . . . . . . . . .   5
     2.1.  Common Parameters . . . . . . . . . . . . . . . . . . . .   5
     2.2.  JSContact Id  . . . . . . . . . . . . . . . . . . . . . .   5
     2.3.  General Properties  . . . . . . . . . . . . . . . . . . .   6
       2.3.1.  BEGIN and END . . . . . . . . . . . . . . . . . . . .   6
       2.3.2.  SOURCE  . . . . . . . . . . . . . . . . . . . . . . .   6
       2.3.3.  KIND  . . . . . . . . . . . . . . . . . . . . . . . .   6
       2.3.4.  XML . . . . . . . . . . . . . . . . . . . . . . . . .   7
     2.4.  Identification Properties . . . . . . . . . . . . . . . .   7
       2.4.1.  FN  . . . . . . . . . . . . . . . . . . . . . . . . .   7
       2.4.2.  N and NICKNAME  . . . . . . . . . . . . . . . . . . .   7
       2.4.3.  PHOTO . . . . . . . . . . . . . . . . . . . . . . . .   8
       2.4.4.  BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY    9
       2.4.5.  GENDER  . . . . . . . . . . . . . . . . . . . . . . .  11
     2.5.  Delivery Addressing Properties  . . . . . . . . . . . . .  11
       2.5.1.  ADR . . . . . . . . . . . . . . . . . . . . . . . . .  11
     2.6.  Communications Properties . . . . . . . . . . . . . . . .  12
       2.6.1.  TEL . . . . . . . . . . . . . . . . . . . . . . . . .  12
       2.6.2.  EMAIL . . . . . . . . . . . . . . . . . . . . . . . .  13
       2.6.3.  IMPP  . . . . . . . . . . . . . . . . . . . . . . . .  14
       2.6.4.  LANG  . . . . . . . . . . . . . . . . . . . . . . . .  15
     2.7.  Geographical Properties . . . . . . . . . . . . . . . . .  16
       2.7.1.  Time Zone Representation  . . . . . . . . . . . . . .  17
     2.8.  Organizational Properties . . . . . . . . . . . . . . . .  17
       2.8.1.  TITLE and ROLE  . . . . . . . . . . . . . . . . . . .  17
       2.8.2.  LOGO  . . . . . . . . . . . . . . . . . . . . . . . .  18
       2.8.3.  ORG . . . . . . . . . . . . . . . . . . . . . . . . .  19
       2.8.4.  MEMBER  . . . . . . . . . . . . . . . . . . . . . . .  20
       2.8.5.  RELATED . . . . . . . . . . . . . . . . . . . . . . .  21
       2.8.6.  CONTACT-URI . . . . . . . . . . . . . . . . . . . . .  22
     2.9.  Personal Information Properties . . . . . . . . . . . . .  23
       2.9.1.  EXPERTISE . . . . . . . . . . . . . . . . . . . . . .  23
       2.9.2.  HOBBY . . . . . . . . . . . . . . . . . . . . . . . .  24
       2.9.3.  INTEREST  . . . . . . . . . . . . . . . . . . . . . .  25
       2.9.4.  ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . .  26
     2.10. Explanatory Properties  . . . . . . . . . . . . . . . . .  27
       2.10.1.  CATEGORIES . . . . . . . . . . . . . . . . . . . . .  27
       2.10.2.  NOTE . . . . . . . . . . . . . . . . . . . . . . . .  28
       2.10.3.  PRODID . . . . . . . . . . . . . . . . . . . . . . .  29
       2.10.4.  REV  . . . . . . . . . . . . . . . . . . . . . . . .  29
       2.10.5.  SOUND  . . . . . . . . . . . . . . . . . . . . . . .  29

Loffredo & Stepanek     Expires October 16, 2021                [Page 2]
Internet-Draft               jscontact-vcard                  April 2021

       2.10.6.  UID  . . . . . . . . . . . . . . . . . . . . . . . .  30
       2.10.7.  CLIENTPIDMAP and PID Parameter . . . . . . . . . . .  31
       2.10.8.  URL  . . . . . . . . . . . . . . . . . . . . . . . .  31
       2.10.9.  VERSION  . . . . . . . . . . . . . . . . . . . . . .  31
     2.11. Security Properties . . . . . . . . . . . . . . . . . . .  31
       2.11.1.  KEY  . . . . . . . . . . . . . . . . . . . . . . . .  32
     2.12. Calendar Properties . . . . . . . . . . . . . . . . . . .  32
       2.12.1.  FBURL  . . . . . . . . . . . . . . . . . . . . . . .  32
       2.12.2.  CALADRURI  . . . . . . . . . . . . . . . . . . . . .  33
       2.12.3.  CALURI . . . . . . . . . . . . . . . . . . . . . . .  34
     2.13. vCard Unmatched Properties  . . . . . . . . . . . . . . .  35
     2.14. JSCard Required Properties  . . . . . . . . . . . . . . .  35
   3.  Translating JSContact properties to vCard . . . . . . . . . .  36
     3.1.  Id  . . . . . . . . . . . . . . . . . . . . . . . . . . .  36
     3.2.  Localizations . . . . . . . . . . . . . . . . . . . . . .  36
     3.3.  Date and Time Representations . . . . . . . . . . . . . .  36
     3.4.  Time Zone . . . . . . . . . . . . . . . . . . . . . . . .  36
     3.5.  JSContact Types Matching Multiple vCard Properties  . . .  37
       3.5.1.  Title . . . . . . . . . . . . . . . . . . . . . . . .  37
       3.5.2.  Resource  . . . . . . . . . . . . . . . . . . . . . .  37
     3.6.  JSCard Unmatched Properties . . . . . . . . . . . . . . .  37
     3.7.  vCard Required Properties . . . . . . . . . . . . . . . .  37
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  37
   5.  Implementation Status . . . . . . . . . . . . . . . . . . . .  37
     5.1.  CNR . . . . . . . . . . . . . . . . . . . . . . . . . . .  38
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  38
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  38
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  38
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  39
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  40

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.

Loffredo & Stepanek     Expires October 16, 2021                [Page 3]
Internet-Draft               jscontact-vcard                  April 2021

   To facilitate this, this document defines how to convert contact
   information as defined in the JSContact [draft-ietf-jmap-jscontact]
   specification 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 properties.  In
      particular, unlike vCard, JSContact distinguishes between a single
      contact card, named JSCard, and a group of contact cards, named
      JSCardGroup.

   o  The properties that can be present multiple times in a vCard are
      represented through different collections in JSContact; mainly as
      maps, sometimes as lists, in some cases condensed in a single
      value.

1.2.1.  Extensions

   While translating vCard properties to JSContact, any vCard property
   that doesn't have a direct counterpart in JSContact MUST be converted
   into a property whose name is prefixed by "ietf.org/<RFC defining the
   extension>/".

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

   Similarly, the reversed rules are applied while translating JSContact
   properties to vCard.

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

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

Loffredo & Stepanek     Expires October 16, 2021                [Page 4]
Internet-Draft               jscontact-vcard                  April 2021

2.  Translating vCard properties to JSContact

   This section contains the translation rules from vCard to JSCard/
   JSCardGroup.  The vCard properties are grouped according to the
   categories as defined in [RFC6350].

2.1.  Common Parameters

   The following mapping rules apply to parameters that are common to
   most of the vCard properties:

   o  The generic values of the TYPE parameter are mapped onto the
      values of the "Context" type as defined in Section 1.5.1 of
      [draft-ietf-jmap-jscontact].  The "home" value corresponds to the
      "private" key.  The mapping of those specific TYPE values used in
      the TEL and RELATED properties are defined in the following of the
      document.

   o  The PREF parameter is mapped onto the "pref" property.

   o  The MEDIATYPE parameter is mapped onto the "mediaType" property.
      As described in Section 5.7 of [RFC6350], the media type of a
      resource can be identified by its URI.  For example, "image/gif"
      can be derived from the ".gif" extension of a GIF image URI.
      JSContact producers MAY provide the media type information even
      when it is not specified in the vCard.

   o  The ALTID and LANGUAGE parameters are used in combination for
      associating the language-dependent alternatives with a given
      property.  Such alternatives are represented by using the
      "localizations" map of a "LocalizedString" member inside the
      matching JSContact object.

   o  The LEVEL parameter as defined in [RFC6715] is directly mapped
      onto the "level" property of the "PersonalInformation" type apart
      from when LEVEL is used in the EXPERTISE property; in this case,
      the values are converted as in the following:

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

2.2.  JSContact Id

   The rules to generate a map key of type Id are out of the scope of
   this document.

Loffredo & Stepanek     Expires October 16, 2021                [Page 5]
Internet-Draft               jscontact-vcard                  April 2021

2.3.  General Properties

2.3.1.  BEGIN and END

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

2.3.2.  SOURCE

   A SOURCE property is represented as an entry of the "online" map
   (Figure 1).  The entry value is a "Resource" object whose "type"
   member is set to "uri", the "label" member is set to "source" and the
   "resource" member is the SOURCE value.

   The PREF and MEDIATYPE parameters are mapped according to the rules
   as defined in (Section 2.1).

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

    {
    ...
    "online":{
       ...
       "a-source":{
         "type": "uri",
         "label": "source",
         "resource": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf"
       },
       ...
    },
    ...
    }

                     Figure 1: SOURCE mapping example

2.3.3.  KIND

   The KIND property is mapped onto the "kind" member (Figure 2).
   Allowed values are those described in Section 6.1.4 of [RFC6350] and
   extended with the values declared in [RFC6473] and [RFC6869].  The
   value "group" is reserved for a JSCardGroup instance.

Loffredo & Stepanek     Expires October 16, 2021                [Page 6]
Internet-Draft               jscontact-vcard                  April 2021

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

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

                      Figure 2: KIND mapping example

2.3.4.  XML

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

2.4.  Identification Properties

2.4.1.  FN

   All the FN instances are globally represented through the "fullName"
   member.  The presence of multiple instances 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.4.2.  N and NICKNAME

   The N instances are converted into equivalent items of the "name"
   array (Figure 3): the N components are transformed into related
   "NameComponent" objects as presented in Table 1.  Name components
   SHOULD be ordered such that their values joined by whitespace produce
   a valid full name of this entity.

   Each NICKNAME instance is mapped onto an item of "nickNames" array.

Loffredo & Stepanek     Expires October 16, 2021                [Page 7]
Internet-Draft               jscontact-vcard                  April 2021

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

                       Table 1: N components mapping

       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" }
       ],
       "nickNames":[
         { "value": "Johnny" }
       ],
       ...
       }

                 Figure 3: FN, N, NICKNAME mapping example

2.4.3.  PHOTO

   A PHOTO property is represented as an entry of the "photos" map
   (Figure 4).  The entry value is a "File" object whose "href" member
   is the PHOTO value.

   The PREF and MEDIATYPE parameters are mapped according to the rules
   as defined in (Section 2.1).

Loffredo & Stepanek     Expires October 16, 2021                [Page 8]
Internet-Draft               jscontact-vcard                  April 2021

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

       {
       ...
       "photos":{
          ...
          "a-photo":{
            "href": "http://www.example.com/pub/photos/jqpublic.gif"
          },
          ...
       },
       ...
       }

                      Figure 4: PHOTO mapping example

2.4.4.  BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY

   The BDAY and ANNIVERSARY properties 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 BIRTHPLACE and DEATHPLACE properties that are represented as geo
   URIs are converted into "Address" instances including only the
   "coordinates" member.  If the URI value is not a geo URI, the place
   is ignored.

   The ALTID and LANGUAGE parameters of both BIRTHPLACE and DEATHPLACE
   properties are mapped according to the rules as defined in

Loffredo & Stepanek     Expires October 16, 2021                [Page 9]
Internet-Draft               jscontact-vcard                  April 2021

   (Section 2.1).  The "fullAddress.localizations" includes possible
   language-dependent alternatives.

    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": "1953-10-15T23:10:00Z",
        "place":{
          "fullAddress":{
            "value": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A."
          }
        }
      },
      {
        "type": "birth",
        "date": "1953-10-15T23:10:00Z",
        "place":{
          "fullAddress":{
            "value": "4445 Courtright Street\nNew England, ND 58647\nU.S.A."
          }
        }
      },
      {
        "type": "other",
        "label": "marriage date",
        "date": "1986-02-01"
      }
    ],
    ...
    }

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

Loffredo & Stepanek     Expires October 16, 2021               [Page 10]
Internet-Draft               jscontact-vcard                  April 2021

2.4.5.  GENDER

   The GENDER property doesn't have a direct match with a JSContact
   feature.

2.5.  Delivery Addressing Properties

2.5.1.  ADR

   An ADR property is represented as an entry of the "addresses" map
   (Figure 6).  The entry value is an "Address" object.

   The ADR components are transformed into the "Address" members as
   presented 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 GEO parameter is converted into the "coordinates" member.

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

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

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

   The ALTID and LANGUAGE parameters are mapped according to the rules
   as defined in (Section 2.1).  The "fullAddress.localizations"
   includes possible language-dependent alternatives.

Loffredo & Stepanek     Expires October 16, 2021               [Page 11]
Internet-Draft               jscontact-vcard                  April 2021

       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":{
         "work-address" :{
           "contexts":{ "work": true },
           "fullAddress":{
             "value": "54321 Oak St\nReston\nVA\n20190\nUSA"
           },
           "street": "54321 Oak St",
           "locality": "Reston",
           "region": "VA",
           "country": "USA",
           "postcode": "20190",
           "countryCode": "US"
         },
         "private-address":{
           "contexts":{ "private": true },
           "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.6.  Communications Properties

2.6.1.  TEL

   A TEL property is represented as an entry of the "phones" map
   (Figure 7).  The entry value is a "Phone" object.  The TEL-specific
   values of the TYPE parameter are mapped onto the "features" map keys.

Loffredo & Stepanek     Expires October 16, 2021               [Page 12]
Internet-Draft               jscontact-vcard                  April 2021

   The values that don't match a key are represented as comma-separated
   values of the "label" member.  If the "features" map is empty and the
   "label" member is not empty, the "other" feature is added.  The
   "phone" member is set to the TEL value.

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

     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":{
       "a-phone":{
         "contexts":{ "private": true },
         "features":{ "voice": true },
         "phone": "tel:+1-555-555-5555;ext=5555",
         "pref": 1
       },
       "another-phone":{
         "contexts":{ "private": true },
         "phone": "tel:+33-01-23-45-67"
       }
     ],
     ...
     }

                       Figure 7: TEL mapping example

2.6.2.  EMAIL

   An EMAIL property is represented as an entry of the "emails" map
   (Figure 8).  The entry value is an "EmailAddress" object.  The
   "email" member is set to the EMAIL value.

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

Loffredo & Stepanek     Expires October 16, 2021               [Page 13]
Internet-Draft               jscontact-vcard                  April 2021

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

       {
       ...
       "emails":{
         "work-email":{
           "contexts":{ "work": true },
           "email": "jqpublic@xyz.example.com"
         },
         "private-email":{
           "contexts":{ "private", true },
           "email": "jane_doe@example.com",
           "pref": 1
         }
       },
       ...
       }

                      Figure 8: EMAIL mapping example

2.6.3.  IMPP

   An IMPP property is represented as an entry of the "online" map
   (Figure 9).  The entry value is a "Resource" object whose "type"
   member is set to "username", the "label" member is set to "XMPP" and
   the "resource" member is the IMPP value.

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

Loffredo & Stepanek     Expires October 16, 2021               [Page 14]
Internet-Draft               jscontact-vcard                  April 2021

       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.6.4.  LANG

   A LANG property is represented as an entry of the
   "preferredContactLanguages" map (Figure 10).  The entry keys
   correspond to the language tags, the corresponding entry values are
   arrays of "ContactLanguage" objects.

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

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

Loffredo & Stepanek     Expires October 16, 2021               [Page 15]
Internet-Draft               jscontact-vcard                  April 2021

       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":[
           {
             "context": "work",
             "pref": 1
           }
         ],
         "fr":[
           {
             "context": "work",
             "pref": 2
           },
           {
             "context": "private"
           }
         ]
       },
       ...
       }

                      Figure 10: LANG mapping example

2.7.  Geographical Properties

   The GEO and TZ properties are not directly mapped onto topmost
   JSCard/JSCardGroup members because the same information is
   represented through equivalent "Address" members.

   The ALTID parameter is used for associating both GEO and TZ
   properties with the related address information.  When the ALTID
   parameter is missing, the matched members SHOULD be included in the
   first "Address" object.

Loffredo & Stepanek     Expires October 16, 2021               [Page 16]
Internet-Draft               jscontact-vcard                  April 2021

2.7.1.  Time Zone Representation

   As specified in Section 6.5.1 of [RFC6350], the time zone information
   can be represented in three ways: as a time zone name, as a UTC
   offset or as a URI.

   o  The time zone name is directly matched by the "timeZone" member in
      JSContact.

   o  An UTC offset MUST be converted into the related "Etc/GMT" time
      zone (e.g. the value "-0500" converts to "Etc/GMT+5").  If the UTC
      offset value contains minutes information, it MUST be mapped to
      the zone "Etc/GMT<sign><hour>:<minute>".

   o  Since there is no URI scheme defined for time zones [uri-schemes],
      any implementation that does use some a custom URI for a time zone
      is not interoperable anyway.  In this case, if the URI corresponds
      to an IANA time zone [time-zones], this latter SHOULD be used.
      Otherwise, the URI value is dumped into a string.

2.8.  Organizational Properties

2.8.1.  TITLE and ROLE

   Both TITLE and ROLE properties are represented as entries of the
   "titles" map (Figure 11).  The entry value is a "Title" object whose
   "title" member includes information about the language.

   The ALTID and LANGUAGE parameters are mapped according to the rules
   as defined in (Section 2.1).  The "title.localizations" includes
   possible language-dependent alternatives.

Loffredo & Stepanek     Expires October 16, 2021               [Page 17]
Internet-Draft               jscontact-vcard                  April 2021

       BEGIN:VCARD
       VERSION:4.0
       ...
       TITLE:Research Scientist
       ROLE:Project Leader
       ...
       END:VCARD

       {
       ...
       "titles":{
         "a-title":{
           "title":{ "value" : "Project Leader" }
         },
         "another-title":{
           "title":{ "value" : "Research Scientist" }
         }
       },
       ...
       }

                 Figure 11: TITLE and ROLE mapping example

2.8.2.  LOGO

   A LOGO property is represented as an entry of the "online" map
   (Figure 12).  The entry value is a "Resource" object whose "type"
   member is set to "uri", the "label" member is set to "logo" and the
   "resource" member is the LOGO value.

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

Loffredo & Stepanek     Expires October 16, 2021               [Page 18]
Internet-Draft               jscontact-vcard                  April 2021

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

       {
       ...
       "online":{
         ...
         "a-logo":{
           "type": "uri",
           "label": "logo",
           "resource": "http://www.example.com/pub/logos/abccorp.jpg"
         },
         ...
       },
       ...
       }

                      Figure 12: LOGO mapping example

2.8.3.  ORG

   An ORG property is represented as an entry of the "organizations" map
   (Figure 13).  The entry value is an "Organization" object whose
   "name" member contains the organizational name and the "units" member
   contains the organizational units.

   The ALTID and LANGUAGE parameters are mapped according to the rules
   as defined in (Section 2.1).  The "localizations" maps for both
   "name" and "units" include possible language-dependent alternatives.

Loffredo & Stepanek     Expires October 16, 2021               [Page 19]
Internet-Draft               jscontact-vcard                  April 2021

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

       {
       ...
       "organizations":{
         "an-organization":{
           "name":{ "value": "ABC, Inc." },
           "units":[
             { "value": "North American Division" },
             { "value": "Marketing" }
           ]
         }
       },
       ...
       }

                      Figure 13: ORG mapping example

2.8.4.  MEMBER

   According to the JSContact specification, a group of contact cards is
   represented through a JSCardGroup (Figure 14).  The uids of the
   contact cards composing the group are included in the "members" map.

   In this case, the PREF parameter has not a JSContact counterpart;
   however, the implementers MAY insert the map entries by order of
   preference.

Loffredo & Stepanek     Expires October 16, 2021               [Page 20]
Internet-Draft               jscontact-vcard                  April 2021

       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

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

                         Figure 14: Group example

2.8.5.  RELATED

   All the RELATED instances are globally converted into the "relatedTo"
   map (Figure 15): an entry for each entity the entity described by the
   JSCard is associated with.  The map keys are the "uid" values of the
   associated cards.

Loffredo & Stepanek     Expires October 16, 2021               [Page 21]
Internet-Draft               jscontact-vcard                  April 2021

   Each map value is a "Relation" object including only the "relation"
   member represented as a set of the RELATED-specific values of the
   TYPE parameter as defined in Section 6.6.6 of [RFC6350].

   If the relation type is unspecified, the "relation" member MUST be
   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 15: RELATED mapping example

2.8.6.  CONTACT-URI

   A CONTACT-URI property as defined in [RFC8605] is represented as an
   entry of the "online" map (Figure 16).  The entry value is a
   "Resource" object whose "type" member is set to "uri", the "label"
   member is set to "contact-uri" and the "resource" member is the
   CONTACT-URI value.

Loffredo & Stepanek     Expires October 16, 2021               [Page 22]
Internet-Draft               jscontact-vcard                  April 2021

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

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

       {
       ...
       "online":{
         ...
         "a-contact-uri":{
           "type": "uri",
           "label": "contact-uri",
           "resource": "mailto:contact@example.com",
           "pref": 1
         },
         ...
       },
       ...
       }

                  Figure 16: CONTACT-URI mapping example

2.9.  Personal Information Properties

2.9.1.  EXPERTISE

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

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

   The LEVEL parameter is mapped according to the rules as defined in
   (Section 2.1).

Loffredo & Stepanek     Expires October 16, 2021               [Page 23]
Internet-Draft               jscontact-vcard                  April 2021

       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 17: EXPERTISE mapping example

2.9.2.  HOBBY

   A HOBBY property as defined in [RFC6715] is represented as a
   "PersonalInformation" object in the "personalInfo" array (Figure 18).
   The "type" member is set to "hobby".

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

   The LEVEL parameter is mapped according to the rules as defined in
   (Section 2.1).

Loffredo & Stepanek     Expires October 16, 2021               [Page 24]
Internet-Draft               jscontact-vcard                  April 2021

       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 18: HOBBY mapping example

2.9.3.  INTEREST

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

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

   The LEVEL parameter is mapped according to the rules as defined in
   (Section 2.1).

Loffredo & Stepanek     Expires October 16, 2021               [Page 25]
Internet-Draft               jscontact-vcard                  April 2021

       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 19: INTEREST mapping example

2.9.4.  ORG-DIRECTORY

   An ORG-DIRECTORY property is represented as an entry of the "online"
   map (Figure 20).  The entry value is a "Resource" object whose "type"
   member is set to "uri", the "label" member is set to "org-directory"
   and the "resource" member is the ORG-DIRECTORY value.

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

   The INDEX parameter is represented as the index of the directory
   among the online resources with the "org-directory" label.

Loffredo & Stepanek     Expires October 16, 2021               [Page 26]
Internet-Draft               jscontact-vcard                  April 2021

    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":{
      ...
      "an-org-directory":{
        "type": "uri",
        "label": "org-directory",
        "resource": "http://directory.mycompany.example.com"
      },
      "another-org-directory":{
        "type": "uri",
        "label": "org-directory",
        "resource": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering",
        "pref": 1
      },
      ...
    },
    ...
    }

                 Figure 20: ORG-DIRECTORY mapping example

2.10.  Explanatory Properties

2.10.1.  CATEGORIES

   A CATEGORIES property is converted into a set of entries of the
   "categories" map (Figure 21).  The keys are the comma-separated text
   values of the CATEGORIES property.

   In this case, the PREF parameter has not a JSContact counterpart;
   however, implementers MAY use a map preserving the order of insertion
   and the map entries can be inserted by order of preference.

Loffredo & Stepanek     Expires October 16, 2021               [Page 27]
Internet-Draft               jscontact-vcard                  April 2021

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

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

                   Figure 21: CATEGORIES mapping example

2.10.2.  NOTE

   A NOTE property is mapped onto the "notes" property (Figure 22).  All
   the NOTE instances are condensed in a single note and separated by
   newline.

   The ALTID and LANGUAGE parameters are mapped according to the rules
   as defined in (Section 2.1).  The "localizations" map includes
   possible language-dependent alternatives.

    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 22: NOTE mapping example

Loffredo & Stepanek     Expires October 16, 2021               [Page 28]
Internet-Draft               jscontact-vcard                  April 2021

2.10.3.  PRODID

   The PRODID property is converted into the "prodId" member
   (Figure 23).

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

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

                     Figure 23: PRODID mapping example

2.10.4.  REV

   The REV property is transformed into the "updated" member
   (Figure 24).

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

       {
       ...
       "updated": "1995-10-31T22:27:10Z",
       ...
       }

                      Figure 24: REV mapping example

2.10.5.  SOUND

   A SOUND property is represented as an entry of the "online" map
   (Figure 25).  The entry value is a "Resource" object whose "type"
   member is set to "uri", the "label" member is set to "sound" and the
   "resource" member is the SOUND value.

Loffredo & Stepanek     Expires October 16, 2021               [Page 29]
Internet-Draft               jscontact-vcard                  April 2021

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

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

    {
    ...
    "online":{
      ...
      "a-sound":{
        "type": "uri",
        "label": "sound",
        "resource": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com"
      },
      ...
    },
    ...
    }

                     Figure 25: SOUND mapping example

2.10.6.  UID

   The UID property corresponds to the "uid" property (Figure 26).

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

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

                      Figure 26: UID mapping example

Loffredo & Stepanek     Expires October 16, 2021               [Page 30]
Internet-Draft               jscontact-vcard                  April 2021

2.10.7.  CLIENTPIDMAP and PID Parameter

   The CLIENTPIDMAP property and the PDI parameter don't have a direct
   match with a JSCard feature.

2.10.8.  URL

   An URL property is represented as an entry of the "online" map
   (Figure 27).  The entry value is a "Resource" object whose "type"
   member is set to "uri", the "label" member is set to "url" and the
   "resource" member is the URL value.

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

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

    {
    ...
    "online":{
      ...
      "an-url":{
        "type": "uri",
        "label": "url",
        "resource": "http://example.org/restaurant.french/~chezchic.html"
      },
      ...
    },
    ...
    }

                      Figure 27: URL mapping example

2.10.9.  VERSION

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

2.11.  Security Properties

Loffredo & Stepanek     Expires October 16, 2021               [Page 31]
Internet-Draft               jscontact-vcard                  April 2021

2.11.1.  KEY

   A KEY property is represented as an entry of the "online" map
   (Figure 28).  The entry value is a "Resource" object whose "type"
   member is set to "uri", the "label" member is set to "key" and the
   "resource" member is the KEY value.

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

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

       {
       ...
       "online":{
         ...
         "a-key":{
           "type": "uri",
           "label": "key",
           "resource": "http://www.example.com/keys/jdoe.cer"
         },
         ...
       },
       ...
       }

                      Figure 28: KEY mapping example

2.12.  Calendar Properties

2.12.1.  FBURL

   An FBURL property is represented as an entry of the "online" map
   (Figure 29).  The entry value is a "Resource" object whose "type"
   member is set to "uri", the "label" member is set to "fburl" and the
   "resource" member is the FBURL value.

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

Loffredo & Stepanek     Expires October 16, 2021               [Page 32]
Internet-Draft               jscontact-vcard                  April 2021

      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":{
        ...
        "an-fburl":{
          "type": "uri",
          "label": "fburl",
          "resource": "http://www.example.com/busy/janedoe",
          "pref": 1
        },
        "another-fburl":{
          "type": "uri",
          "label": "fburl",
          "resource": "ftp://example.com/busy/project-a.ifb",
          "mediaType": "text/calendar"
        },
        ...
      },
      ...
      }

                     Figure 29: FBURL mapping example

2.12.2.  CALADRURI

   A CALADRURI property is represented as an entry of the "online" map
   (Figure 30).  The entry value is a "Resource" object whose "type"
   member is set to "uri", the "label" member is set to "caladruri" and
   the "resource" member is the CALADRURI value.

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

Loffredo & Stepanek     Expires October 16, 2021               [Page 33]
Internet-Draft               jscontact-vcard                  April 2021

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

       {
       ...
       "online":{
         ...
         "a-caladruri":{
           "type": "uri",
           "label": "caladruri",
           "resource": "mailto:janedoe@example.com",
           "pref": 1
         },
         "another-caladruri":{
           "type": "uri",
           "label": "caladruri",
           "resource": "http://example.com/calendar/jdoe"
         },
         ...
       },
       ...
       }

                   Figure 30: CALADRURI mapping example

2.12.3.  CALURI

   A CALURI property is represented as an entry of the "online" map
   (Figure 31).  The entry value is a "Resource" object whose "type"
   member is set to "uri", the "label" member is set to "caluri" and the
   "resource" member is the CALURI value.

   The PREF and TYPE parameters are mapped according to the rules as
   defined in (Section 2.1).

Loffredo & Stepanek     Expires October 16, 2021               [Page 34]
Internet-Draft               jscontact-vcard                  April 2021

       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":{
         ...
         "a-caluri":{
           "type": "uri",
           "label": "caluri",
           "resource": "http://cal.example.com/calA",
           "pref": 1
         },
         "another-caluri":{
           "type": "uri",
           "label": "caluri",
           "resource": "ftp://ftp.example.com/calA.ics",
           "mediaType": "text/calendar"
         },
         ...
       },
       ...
       }

                     Figure 31: CALURI mapping example

2.13.  vCard Unmatched Properties

   The unmatched vCard properties MAY be converted into JSContact
   properties whose name contains the prefix "ietf.org/RFC6350/"
   followed by property name in uppercase (i.e. ietf.org/RFC6350/
   GENDER").

2.14.  JSCard Required Properties

   While converting a vCard into a JSCard/JSCardGroup, only the topmost
   "uid" member is mandatory.  Implementers are REQUIRED to set it when
   it is missing.

Loffredo & Stepanek     Expires October 16, 2021               [Page 35]
Internet-Draft               jscontact-vcard                  April 2021

3.  Translating JSContact properties to vCard

   In most of the cases, the rules about the translation from JSCard/
   JSCardGroup to vCard can be derived by reversing the rules presented
   in Section 2.  The remaining cases are treated in the following of
   this section.

3.1.  Id

   Where a map key is of type Id, implementers are free to either ignore
   it or preserve it as a vCard information (e.g. a vCard parameter).

3.2.  Localizations

   A LocalizedString object is converted in multiple instances of the
   same vCard property having different values of the LANGUAGE
   parameter.  Implementers MAY set the ALTID parameter to couple
   language-based alternatives of the same value.

   Note also that the components of some vCard values and their related
   alternatives are split into different JSContact values.  For example,
   the "name" and "units" values for a given language must be grouped to
   make a single ORG value where components are separated by ";".

3.3.  Date and Time Representations

   The JSContact spec defines the "UTCDateTime" type to represent
   [RFC3339] "date-time" format with further restrictions.  This means
   that the matched vCard format for a "UTCDateTime" value MUST be one
   of the formats shown in Section 4.3.5 of [RFC6350] (i.e.
   "19961022T140000Z").

   In addition to such format, the "date" member of the "Anniversary"
   type allows specifying both a date without the time and a partial
   date.  In this case, the corresponding vCard format is that defined
   in Section 4.3.1.

3.4.  Time Zone

   The time zone name as represented by the "timeZone" property is
   mapped onto the TZ parameter.

   Implementers MAY map an "Etc/GMT" time zone either preserving the
   time zone name or converting it into a UTC offset.

Loffredo & Stepanek     Expires October 16, 2021               [Page 36]
Internet-Draft               jscontact-vcard                  April 2021

3.5.  JSContact Types Matching Multiple vCard Properties

3.5.1.  Title

   The "titles" property contains information about the job, the
   position or the role of the entity the card represents.  In vCard,
   such information is split into the TITLE and ROLE properties.  This
   specification defines TITLE as the default target property when
   converting the "titles" property.

3.5.2.  Resource

   The "online" property includes resources that are usually represented
   through different vCard properties.  The matched vCard property of a
   "Resource" object can be derived from the value of its "label"
   member.

   Any resource included in the "online" map that doesn't match a vCard
   property MAY be converted into vCard extended properties.

3.6.  JSCard Unmatched Properties

   Both the "preferredContactMethod" and "created" members don't match
   any vCard property.  Implementers MAY represent them as vCard
   extended properties.

3.7.  vCard Required Properties

   While converting a JSCard/JSCardGroup into a vCard, only the FN
   property is required.  Since the "fullName" property is optional,
   implementers are REQUIRED to generate an FN value when it is missing.

4.  IANA Considerations

   This document has no actions for IANA.

5.  Implementation Status

   NOTE: Please remove this section and the reference to RFC 7942 prior
   to publication as an RFC.

   This section records the status of known implementations of the
   protocol as defined in this specification at the time of posting of
   this Internet-Draft, and is based on a proposal described in
   [RFC7942].  The description of implementations in this section is
   intended to assist the IETF in its decision processes in progressing
   drafts to RFCs.  Please note that the listing of any individual
   implementation here does not imply endorsement by the IETF.

Loffredo & Stepanek     Expires October 16, 2021               [Page 37]
Internet-Draft               jscontact-vcard                  April 2021

   Furthermore, no effort has been spent to verify the information
   presented here that was supplied by IETF contributors.  This is not
   intended as, and must not be construed to be, a catalog of available
   implementations or their features.  Readers are advised to note that
   other implementations may exist.

   According to RFC 7942, "this will allow reviewers and working groups
   to assign due considerationto documents that have the benefit of
   running code, which may serve as evidence of valuable experimentation
   and feedback that have made the implemented protocols more mature.
   It is up to the individual working groups to use this information as
   they see fit".

5.1.  CNR

      Responsible Organization: National Research Council (CNR) of Italy
      Location: https://github.com/consiglionazionaledellericerche/
      jscontact-tools
      Description: This implementation includes tools for JSContact
      creation, validation, serialization/deserialization, and
      conversion from vCard, xCard and jCard.
      Level of Maturity: This is an "alpha" test implementation.
      Coverage: This implementation includes all of the features
      described in this specification.
      Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it

6.  Security Considerations

   This document doesn't present any security consideration.

7.  References

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

   [RFC3339]  Klyne, G. and C. Newman, "Date and Time on the Internet:
              Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
              <https://www.rfc-editor.org/info/rfc3339>.

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

Loffredo & Stepanek     Expires October 16, 2021               [Page 38]
Internet-Draft               jscontact-vcard                  April 2021

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

   [RFC7942]  Sheffer, Y. and A. Farrel, "Improving Awareness of Running
              Code: The Implementation Status Section", BCP 205,
              RFC 7942, DOI 10.17487/RFC7942, July 2016,
              <https://www.rfc-editor.org/info/rfc7942>.

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

7.2.  Informative References

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

   [time-zones]
              "Time Zone Database", <https://www.iana.org/time-zones>.

   [uri-schemes]
              "Uniform Resource Identifier (URI) Schemes",
              <https://www.iana.org/assignments/uri-schemes/uri-
              schemes.xhtml>.

Loffredo & Stepanek     Expires October 16, 2021               [Page 39]
Internet-Draft               jscontact-vcard                  April 2021

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 October 16, 2021               [Page 40]