Internet-Draft jscontact-vcard October 2020
Loffredo & Stepanek Expires 14 April 2021 [Page]
Workgroup:
jmap
Internet-Draft:
draft-ietf-jmap-jscontact-vcard-01
Published:
Intended Status:
Informational
Expires:
Authors:
M. Loffredo
IIT-CNR/Registro.it
R. Stepanek
FastMail

JSContact: Converting from and to vCard

Abstract

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

Status of This Memo

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

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

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 14 April 2021.

▲

Table of Contents

1. Introduction

1.1. Motivation

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

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

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

1.2. Scope and Caveats

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

1.3. Conventions Used in This Document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

2. Mapping

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

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

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

2.1. General Properties

2.1.1. BEGIN and END

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

2.1.2. SOURCE

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

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

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

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

2.1.3. KIND

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

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

    {
    ...
    "kind": "individual",
    ...
    }
Figure 2: KIND mapping example

2.1.4. XML

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

2.2. Identification Properties

2.2.1. FN

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

2.2.2. N and NICKNAME

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

  • 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 element is mapped onto an object whose "type" member is set to "nickname"
Table 1: N components mapping
N component "type" value
Honorific Prefixes prefix
Given Names personal
Family Names surname
Additional Names additional
Honorific Suffixes suffix 
    BEGIN:VCARD
    VERSION:4.0
    ...
    FN:Mr. John Q. Public\, Esq.
    N:Public;John;Quinlan;Mr.;Esq.
    NICKNAME:Johnny
    ...
    END:VCARD

    {
    ...
    "fullName":{
               "value": "Mr. John Q. Public, Esq."
               },
    "name":[
             { "value":"Mr.", "type": "prefix" },
             { "value":"John", "type": "personal" },
             { "value":"Public", "type": "surname" },
             { "value":"Quinlan", "type": "additional" },
             { "value":"Esq.", "type": "suffix" },
             { "value":"Johnny", "type": "nickname" }
           ],
    ...
    }
Figure 3: FN, N, NICKNAME mapping example

2.2.3. PHOTO

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

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

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

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

2.2.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY

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

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

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

  • 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. BIRTHPLACE and DEATHPLACE 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 LANGUAGE parameter values of both BIRTHPLACE and DEATHPLACE elements are represented as corresponding entries of the "fullAddress.localizations" map.

    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

2.2.5. GENDER

TBD

2.3. Delivery Addressing Properties

2.3.1. ADR

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

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

Table 2: ADR components mapping
ADR component Address member
p.o. box postOfficeBox
extended address extension
street address street
locality locality
region region
postal code postcode
country name country

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

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

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

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

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

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

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

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

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

2.4. Communications Properties

2.4.1. TEL

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

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

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

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

2.4.2. EMAIL

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

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

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

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

2.4.3. IMPP

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

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

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

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

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

2.4.4. LANG

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

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

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

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

    {
    ...
    "preferredContactLanguages" : {
                                   "en": [
                                          {
                                           "type": "work",
                                           "preference": 1
                                          }
                                         ],
                                   "fr": [
                                          {
                                           "type": "work",
                                           "preference": 2
                                          },
                                          {
                                           "type": "home",
                                          }
                                         ]
                                  },
    ...
    }
Figure 10: LANG mapping example

2.5. Geographical Properties

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

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

2.6. Organizational Properties

2.6.1. TITLE

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

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

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

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

    {
    ...
    "jobTitle":[
                {
                 "value": "Research Scientist"
                }
               ],
    ...
    }
Figure 11: TITLE mapping example

2.6.2. ROLE

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

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

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

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

    {
    ...
    "role":[
            {
             "value": "Project Leader"
            }
           ],
    ...
    }
Figure 12: ROLE mapping example

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

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

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

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

2.6.4. ORG

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

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

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

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

    {
    ...
    "organization":[
                {
                 "value": "ABC, Inc.;North American Division;Marketing"
                 }
                ],
    ...
    }
Figure 14: ORG mapping example

2.6.5. MEMBER

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

    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

All the RELATED elements are globally converted into the "relatedTo" map (Figure 16): 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.

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

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

2.6.7. CONTACT-URI

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

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

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

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

2.7. Personal Information Properties

2.7.1. EXPERTISE

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

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

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

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

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

    {
    ...
    "personalInfo":[
                    ...
                    {
                     "type": "expertise",
                     "value": "chemistry",
                     "level": "high"
                    },
                    {
                     "type": "expertise",
                     "value": "chinese literature",
                     "level": "low"
                    }
                    ...
                   ]
    ...
    }
Figure 18: EXPERTISE mapping example

2.7.2. HOBBY

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

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

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

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

    {
    ...
    "personalInfo":[
                    ...
                    {
                     "type": "hobby",
                     "value": "reading",
                     "level": "high"
                    },
                    {
                     "type": "hobby",
                     "value": "sewing",
                     "level": "high"
                    }
                    ...
                   ]
    ...
    }
Figure 19: HOBBY mapping example

2.7.3. INTEREST

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

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

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

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

    {
    ...
    "personalInfo":[
                    ...
                    {
                     "type": "interest",
                     "value": "r&b music",
                     "level": "medium"
                    },
                    {
                     "type": "interest",
                     "value": "rock ’n’ roll music",
                     "level": "high"
                    }
                    ...
                   ]
    ...
    }
Figure 20: INTEREST mapping example

2.7.4. ORG-DIRECTORY

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

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

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

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

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

2.8. Explanatory Properties

2.8.1. CATEGORIES

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

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

    {
    ...
    "categories":[
                  "INTERNET",
                  "IETF",
                  "INDUSTRY",
                  "INFORMATION TECHNOLOGY"
                 ]
    ...
    }
Figure 22: CATEGORIES mapping example

2.8.2. NOTE

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

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

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

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

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

2.8.3. PRODID

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

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

    {
    ...
    "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN"
    ...
    }
Figure 24: PRODID mapping example

2.8.4. REV

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

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

    {
    ...
    "updated": "19951031T222710Z"
    ...
    }
Figure 25: REV mapping example

2.8.5. SOUND

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

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

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

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

2.8.6. UID

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

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

    {
    ...
    "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
    ...
    }
Figure 27: UID mapping example

2.8.7. CLIENTPIDMAP and PID Parameter

TBD

2.8.8. URL

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

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

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

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

2.8.9. VERSION

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

2.9. Security Properties

2.9.1. KEY

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

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

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

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

2.10. Calendar Properties

2.10.1. FBURL

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

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

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

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

2.10.2. CALADRURI

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

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

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

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

2.10.3. CALURI

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

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

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

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

2.11. Additional Clarifications about Mapping

2.11.1. Media type

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.

2.11.2. Timezone

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 an UTC offset or as an URI.

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

  • 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 map it to the zone "Etc/GMT<sign><hour>:<minute>".

  • 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 a IANA time zone [time-zones], this latter SHOULD be used. Otherwise, the URI value is dumped into a string.

2.12. Extended Properties

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

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

2.13. vCard Unmatched Properties

Any vCard property that doesn't have a direct counterpart in JSContact is treated as an extended property whose name is prefixed by "ietf.org/rfc6350/".

The resulting name MUST be in lowercase.

2.14. JSCard Required Properties

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

2.15. JSCard Unmatched Properties

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

3. IANA Considerations

This document has no actions for IANA.

4. 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 defined by 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. 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 consideration to 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".

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

5. Security Considerations

This document doesn't present any security consideration.

6. References

6.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC6350]
Perreault, S., "vCard Format Specification", RFC 6350, DOI 10.17487/RFC6350, , <https://www.rfc-editor.org/info/rfc6350>.
[RFC6473]
Saint-Andre, P., "vCard KIND:application", RFC 6473, DOI 10.17487/RFC6473, , <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, , <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, , <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, , <https://www.rfc-editor.org/info/rfc6869>.
[RFC7095]
Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, DOI 10.17487/RFC7095, , <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, , <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, , <https://www.rfc-editor.org/info/rfc8605>.

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

Authors' Addresses

Mario Loffredo
IIT-CNR/Registro.it
Via Moruzzi,1
56124 Pisa
Italy
URI: http://www.iit.cnr.it
Robert Stepanek
FastMail
PO Box 234, Collins St West
Melbourne VIC 8007
Australia
URI: https://www.fastmail.com