jmap M. Loffredo Internet-Draft IIT-CNR/Registro.it Intended status: Informational R. Stepanek Expires: September 19, 2020 FastMail March 18, 2020 JSContact: Converting from and to vCard draft-loffredo-jmap-jscontact-vcard-01 Abstract This document provides an informational guideline for converting the contact card defined by JSContact specification, namely JSCard, from and to vCard. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on September 19, 2020. Copyright Notice Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Loffredo & Stepanek Expires September 19, 2020 [Page 1] Internet-Draft jscontact-vcard March 2020 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Scope and Caveats . . . . . . . . . . . . . . . . . . . . 3 1.3. Conventions Used in This Document . . . . . . . . . . . . 4 2. Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. General Properties . . . . . . . . . . . . . . . . . . . 4 2.1.1. SOURCE . . . . . . . . . . . . . . . . . . . . . . . 4 2.1.2. KIND . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2. Identification Properties . . . . . . . . . . . . . . . . 6 2.2.1. FN . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.2.2. N and NICKNAME . . . . . . . . . . . . . . . . . . . 6 2.2.3. PHOTO . . . . . . . . . . . . . . . . . . . . . . . . 7 2.2.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 8 2.2.5. GENDER . . . . . . . . . . . . . . . . . . . . . . . 10 2.3. Delivery Addressing Properties . . . . . . . . . . . . . 10 2.3.1. ADR . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.4. Communications Properties . . . . . . . . . . . . . . . . 11 2.4.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.4.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 12 2.4.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 13 2.4.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 14 2.5. Geographical Properties . . . . . . . . . . . . . . . . . 15 2.6. Organizational Properties . . . . . . . . . . . . . . . . 15 2.6.1. TITLE . . . . . . . . . . . . . . . . . . . . . . . . 15 2.6.2. ROLE . . . . . . . . . . . . . . . . . . . . . . . . 16 2.6.3. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 17 2.6.4. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.6.5. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 18 2.6.6. RELATED . . . . . . . . . . . . . . . . . . . . . . . 19 2.6.7. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 21 2.7. Personal Information Properties . . . . . . . . . . . . . 21 2.7.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 21 2.7.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 22 2.7.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 23 2.7.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 24 2.8. Explanatory Properties . . . . . . . . . . . . . . . . . 25 2.8.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 25 2.8.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 26 2.8.3. PROID . . . . . . . . . . . . . . . . . . . . . . . . 27 2.8.4. REV . . . . . . . . . . . . . . . . . . . . . . . . . 27 2.8.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . . 27 2.8.6. UID . . . . . . . . . . . . . . . . . . . . . . . . . 28 2.8.7. PID Parameter and CLIENTPIDMAP . . . . . . . . . . . 29 2.8.8. URL . . . . . . . . . . . . . . . . . . . . . . . . . 29 2.9. Security Properties . . . . . . . . . . . . . . . . . . . 29 2.9.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . . 29 Loffredo & Stepanek Expires September 19, 2020 [Page 2] Internet-Draft jscontact-vcard March 2020 2.10. Calendar Properties . . . . . . . . . . . . . . . . . . . 30 2.10.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 30 2.10.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 31 2.10.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 32 2.11. Extended Properties . . . . . . . . . . . . . . . . . . . 33 2.12. JSCard's Required Properties . . . . . . . . . . . . . . 33 2.13. JSCard's Unmatched Properties . . . . . . . . . . . . . . 34 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 4. Security Considerations . . . . . . . . . . . . . . . . . . . 34 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 5.1. Normative References . . . . . . . . . . . . . . . . . . 34 5.2. Informative References . . . . . . . . . . . . . . . . . 35 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 1. Introduction 1.1. Motivation The JSContact specification [draft-ietf-jmap-jscontact] has been defined to represent contact card information as a more efficient alternative to vCard [RFC6350] and its JSON format named jCard [RFC7095]. While new applications might adopt JSContact as their main format to exchange contact card data, they are likely to interoperate with services and clients that just support vCard/jCard. Similarly, existing contact data providers and consumers already using vCard/ jCard might want to represent their data also according to the JSContact specification. To facilitate this use cases, this document provides an informational guide about how to convert the card defined in JSContact, namely JSCard, from and to vCard. 1.2. Scope and Caveats JSContact and vCard have a lot of semantics in common, however some differences must be outlined: o The JSContact data model defines some contact information that doesn't have a direct mapping with vCard elements. o The vCard specification includes some features (like parameters) that have been formally removed from JSCard due to a complete refactoring of vCard content. Anyway, the vCard parameters may appear as JSCard properties. Loffredo & Stepanek Expires September 19, 2020 [Page 3] Internet-Draft jscontact-vcard March 2020 o Some vCard elements represented individually have been modeled as members of JSCard elements. o The vCard custom elements, identified by the prefix "x-", don't have a direct counterpart in the JSContact specification. 1.3. Conventions Used in This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 ([RFC2119]). 2. Mapping This section contains the mapping between vCard and JSCard. The vCard properties are grouped according to the categories defined by RFC6350 [RFC6350]. 2.1. General Properties 2.1.1. SOURCE The vCard SOURCE element is represented in JSCard as a "Resource" item of the "online" array (Figure 1). In the "Resource" item, the "type" member is set to "uri" as well as a key of the "labels" is set to "source". The PREF and MEDIATYPE parameters can be represented by the "isPreferred" and "mediaType" properties respectively. Loffredo & Stepanek Expires September 19, 2020 [Page 4] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf ... END:VCARD { ... "online":[ ... { "type": "uri", "labels": { "source" : true }, "value": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf" }, ... ], ... } Figure 1: SOURCE mapping example 2.1.2. KIND The vCard KIND element is mapped onto the JSCard "kind" property (Figure 2). Such property can contain one of the values, except "group", described in section 6.1.4 of RFC6350 [RFC6350] and extended with the values declared in RFC6473 [RFC6473] and RFC6969 [RFC6869]. A group of cards is represented by a dedicated object named JSCardGroup. BEGIN:VCARD VERSION:4.0 ... KIND:individual ... END:VCARD { ... "kind": "individual", ... } Figure 2: KIND mapping example Loffredo & Stepanek Expires September 19, 2020 [Page 5] Internet-Draft jscontact-vcard March 2020 2.2. Identification Properties 2.2.1. FN FN is converted into the "fullName" property. The presence of more than one name is implicitly associated with the translation of the full name in various languages. Each translation corresponds to a different entry of the "localizations" map that is an optional member of the "fullName" object (Figure 3). 2.2.2. N and NICKNAME The vCard elements N and NICKNAME are converted into equivalent items of the JSCard "name" array (Figure 3): o the N components are transformed into related "NameComponent" items as reported in Table 1; an item for each name component. Name components SHOULD be ordered such that their values joined by whitespace produce a valid full name of this entity; o NICKNAME is mapped onto an item whose "type" is "nickname"; an item for each nickname. +--------------------+--------------+ | N component | "type" value | +--------------------+--------------+ | Honorific Prefixes | prefix | | Given Names | personal | | Family Names | surname | | Additional Names | additional | | Honorific Suffixes | suffix | +--------------------+--------------+ Table 1: N components mapping Loffredo & Stepanek Expires September 19, 2020 [Page 6] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... FN:Mr. John Q. Public\, Esq. N:Public;John;Quinlan;Mr.;Esq. NICKNAME:Johnny ... END:VCARD { ... "fullName":{ "value": "Mr. John Q. Public, Esq." }, "name":[ { "value":"Mr.", "type": "prefix" }, { "value":"John", "type": "personal" }, { "value":"Public", "type": "surname" }, { "value":"Quinlan", "type": "additional" }, { "value":"Esq.", "type": "suffix" }, { "value":"Johnny", "type": "nickname" } ], ... } Figure 3: FN, N, NICKNAME mapping example 2.2.3. PHOTO The vCard PHOTO element is represented in JSCard as a "Resource" item of the "online" array (Figure 4). In the "Resource" item, the "type" member is set to "uri" as well as a key of the "labels" is set to "photo". The PREF and MEDIATYPE parameters can be represented by the "isPreferred" and "mediaType" properties respectively. Loffredo & Stepanek Expires September 19, 2020 [Page 7] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... PHOTO:http://www.example.com/pub/photos/jqpublic.gif ... END:VCARD { ... "online":[ ... { "type": "uri", "labels": { "photo" : true }, "value": "http://www.example.com/pub/photos/jqpublic.gif" }, ... ], ... } Figure 4: PHOTO mapping example 2.2.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY The vCard BDAY and ANNIVERSARY elements and the vCard extensions BIRTHPLACE, DEATHDATE, DEATHPLACE described in RFC6474 [RFC6350] are represented in JSCard as "Anniversary" items of the "anniversaries" array (Figure 5): o BDAY and BIRTHPLACE are mapped onto "date" and "place" where "type" is set to "birth" o DEATHDATE and DEATHPLACE are mapped onto "date" and "place" where "type" is set to "death" o ANNIVERSARY is mapped onto "date" where "type" is set to "other" and "label" is set to a value describing in detail the kind of anniversary (e.g. "marriage date" for the wedding anniversary). Both birth and death places are represented as instances of the Address object. The LANGUAGE parameter values of both BIRTHPLACE and DEATHPLACE elements can be expressed as corresponding entries of the "localizations" map included in the "fullAddress" object. Loffredo & Stepanek Expires September 19, 2020 [Page 8] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... BDAY:19531015T231000Z BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A. DEATHDATE:19960415 DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A. ANNIVERSARY:19860201 ... END:VCARD { ... "anniversaries":[ { "type": "birth", "date": "19531015T231000Z", "place": { "fullAddress": { "value": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A." } } }, { "type": "birth", "date": "19531015T231000Z", "place": { "fullAddress": { "value": "4445 Courtright Street\nNew England, ND 58647\nU.S.A." } } }, { "type": "other", "label": "marriage date", "date": "19860201" } ], ... } Figure 5: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY mapping example Loffredo & Stepanek Expires September 19, 2020 [Page 9] Internet-Draft jscontact-vcard March 2020 2.2.5. GENDER TBD 2.3. Delivery Addressing Properties 2.3.1. ADR The vCard ADR element is represented in JSCard as an "Address" item of the "addresses" array (Figure 6). The ADR components are transformed into the "Address" properties as reported in Table 2. +------------------+------------------+ | ADR component | Address property | +------------------+------------------+ | p.o. box | postOfficeBox | | extended address | extension | | street address | street | | locality | locality | | region | region | | postal code | postcode | | country name | country | +------------------+------------------+ Table 2: ADR components mapping The LABEL parameter is converted into the "fullAddress" property. The PREF parameter is converted into the "isPreferred" property. The GEO parameter is converted into the "coordinates" property. The TZ parameter is converted into by the "timeZone" property. The TYPE parameter is converted into the "context" property. The "home" value is replaced by the "private" value. The LANGUAGE parameter values can be represented as different entries of the "localizations" map that is an optional member of the "fullAddress" object. The CC parameter defined by RFC8605 [RFC8605] is converted into the "countryCode" property. Loffredo & Stepanek Expires September 19, 2020 [Page 10] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA ... END:VCARD { ... "addresses": [ { "context": "work", "fullAddress": { "value": "54321 Oak St\nReston\nVA\n20190\USA" }, "street": "54321 Oak St", "locality": "Reston", "region": "VA", "country": "USA", "postcode": "20190", "countryCode": "US" }, { "context": "private", "fullAddress": { "value": "12345 Elm St\nReston\nVA\n20190\USA" }, "street": "12345 Elm St", "locality": "Reston", "region": "VA", "country": "USA", "postcode": "20190", "countryCode": "US" } ] ... } Figure 6: ADR mapping example 2.4. Communications Properties Loffredo & Stepanek Expires September 19, 2020 [Page 11] Internet-Draft jscontact-vcard March 2020 2.4.1. TEL The vCard TEL element is represented in JSCard as a "Resource" item of the "phones" array (Figure 7). The vCard "type-param-tel" values are represented by the "type" member while the "type-param" values are represented by the "context" member. The "home" value is replaced by the "private" value. The PREF parameter can be represented by the "isPreferred" member. BEGIN:VCARD VERSION:4.0 ... TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555 TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67 ... END:VCARD { ... "phones":[ { "type": "voice", "context": "private", "value": "tel:+1-555-555-5555;ext=5555", "isPreferred": true }, { "type": "voice", "context": "private", "value": "tel:+33-01-23-45-67" } ], ... } Figure 7: TEL mapping example 2.4.2. EMAIL The vCard EMAIL element is represented in JSCard as a "Resource" item of the "emails" array (Figure 8). The vCard "type-param" values are represented by the "context" member. The "home" value is replaced by the "private" value. The PREF parameter can be represented by the "isPreferred" member. Loffredo & Stepanek Expires September 19, 2020 [Page 12] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... EMAIL;TYPE=work:jqpublic@xyz.example.com EMAIL;PREF=1:jane_doe@example.com ... END:VCARD { ... "emails":[ { "context": "work", "value": "jqpublic@xyz.example.com", }, { "context": "private", "value": "jane_doe@example.com" "isPreferred": true } ], ... } Figure 8: EMAIL mapping example 2.4.3. IMPP The vCard IMPP element is represented in JSCard as a "Resource" item of the "online" array (Figure 9). In the "Resource" item, the "type" member is set to "username" as well as a key of the "labels" is set to "XMPP". The PREF and MEDIATYPE parameters can be represented by the "isPreferred" and "mediaType" properties respectively. Loffredo & Stepanek Expires September 19, 2020 [Page 13] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... IMPP;PREF=1:xmpp:alice@example.com ... END:VCARD { ... "online":[ ... { "type": "username", "labels": { "XMPP" : true }, "value": "alice@example.com" }, ... ], ... } Figure 9: IMPP mapping example 2.4.4. LANG The vCard LANG element is represented in JSCard through the "preferredContactLanguages" map (Figure 10): an entry for each language that may be used for contacting the entity associated with the JSCard. The entry keys correspond to the language tags, the corresponding entry values are arrays of ContactLanguage items. The TYPE and PREF parameters can be represented by, respectively, the ContactLanguage properties "type" and "preference". If both PREF and TYPE parameters are missing, the array of ContactLanguage items MUST be empty. Loffredo & Stepanek Expires September 19, 2020 [Page 14] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... LANG;TYPE=work;PREF=1:en LANG;TYPE=work;PREF=2:fr LANG;TYPE=home:fr ... END:VCARD { ... "preferredContactLanguages" : { "en": [ { "type": "work", "preference": 1 } ], "fr": [ { "type": "work", "preference": 2 }, { "type": "home", } ] }, ... } Figure 10: LANG mapping example 2.5. Geographical Properties The GEO and TZ elements are not directly mapped into equivalent topmost JSCard elements because the same information is represented through equivalent "Address" properties. 2.6. Organizational Properties 2.6.1. TITLE The vCard TITLE element is mapped onto the JSCard "jobTitle" array; an item for each title (Figure 11). The LANGUAGE parameter values can be expressed as corresponding entries of the "localizations" map included in each "Resource" item. Loffredo & Stepanek Expires September 19, 2020 [Page 15] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... TITLE:Research Scientist ... END:VCARD { ... "jobTilte":[ { "value": "Research Scientist" } ], ... } Figure 11: TITLE mapping example 2.6.2. ROLE The vCard ROLE element is mapped onto the JSCard "role" array; an item for each role (Figure 12). The LANGUAGE parameter values can be expressed as corresponding entries of the "localizations" map included in each "Resource" item. BEGIN:VCARD VERSION:4.0 ... ROLE:Project Leader ... END:VCARD { ... "role":[ { "value": "Project Leader" } ], ... } Figure 12: ROLE mapping example Loffredo & Stepanek Expires September 19, 2020 [Page 16] Internet-Draft jscontact-vcard March 2020 2.6.3. LOGO The vCard LOGO element is represented in JSCard as a "Resource" item of the "online" array (Figure 13). In the "Resource" item, the "type" member is set to "uri" as well as a key of the "labels" is set to "logo". The PREF and MEDIATYPE parameters can be represented by the "isPreferred" and "mediaType" properties respectively. BEGIN:VCARD VERSION:4.0 ... LOGO:http://www.example.com/pub/logos/abccorp.jpg ... END:VCARD { ... "online":[ ... { "type": "uri", "labels": { "logo" : true }, "value": "http://www.example.com/pub/logos/abccorp.jpg" }, ... ], ... } Figure 13: LOGO mapping example 2.6.4. ORG The vCard ORG element is mapped onto the JSCard "organization" array; an item for each organization (Figure 14). The organization name includes the organizational units if any. The LANGUAGE parameter values can be expressed as corresponding entries of the "localizations" map included in each "Resource" item. Loffredo & Stepanek Expires September 19, 2020 [Page 17] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... ORG:ABC\, Inc.;North American Division;Marketing ... END:VCARD { ... "organization":[ { "value": "ABC, Inc.;North American Division;Marketing" } ], ... } Figure 14: ORG mapping example 2.6.5. MEMBER According to the JSContact specification, a group of contact cards is represented by a dedicated object named JSCardGroup (Figure 15). The contact cards composing the group are included in the "cards" array. Therefore, the vCard MEMBER element doesn't have a direct match with a corresponding JSCard element. Loffredo & Stepanek Expires September 19, 2020 [Page 18] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 KIND:group FN:The Doe family MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 END:VCARD BEGIN:VCARD VERSION:4.0 FN:John Doe UID:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af END:VCARD BEGIN:VCARD VERSION:4.0 FN:Jane Doe UID:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 END:VCARD { "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", "name": "The Doe family", "cards": [ { "name": { "fullName": { "value": "John Doe" } }, "uid": "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af" }, { "name": { "fullName": { "value": "Jane Doe" } }, "uid": "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519f" } ] } Figure 15: Group example 2.6.6. RELATED The vCard RELATED element is converted into the "relatedTo" map (Figure 16): an entry for each entity the entity described by the Loffredo & Stepanek Expires September 19, 2020 [Page 19] Internet-Draft jscontact-vcard March 2020 JSCard is associated with. The map keys are the UUIDs of the associated cards. Each map value is an object including only the "relation" property represented as a set of relation types described in section 6.6.6 of RFC6350 [RFC6350]. If the relation type is unspecified, the "relation" is empty. BEGIN:VCARD VERSION:4.0 ... RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries. ... END:VCARD { ... "relatedTo":{ { "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6": { "relation": { "friend": true } } }, { "http://example.com/directory/jdoe.vcf": { "relation": { "contact": true } } }, { "Please contact my assistant Jane Doe for any inquiries.": { "relation": { } } } } ... } Figure 16: RELATED mapping example Loffredo & Stepanek Expires September 19, 2020 [Page 20] Internet-Draft jscontact-vcard March 2020 2.6.7. CONTACT-URI The vCard CONTACT-URI element defined by RFC8605 [RFC8605] is represented in JSCard as a "Resource" item of the "online" array (Figure 17). In the "Resource" item, the "type" member is set to "uri" as well as a key of the "labels" is set to "contact-uri". The PREF parameter can be represented by the "isPreferred" property. BEGIN:VCARD VERSION:4.0 ... CONTACT-URI;PREF=1:mailto:contact@example.com ... END:VCARD { ... "online":[ ... { "type": "uri", "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 The vCard EXPERTISE element defined by RFC6715 [RFC6715] is represented in JSCard as a "PersonalInformation" item of the "personalInfo" array (Figure 18). The "type" property is set to "expertise". The LEVEL parameter can be represented by the "level" property with following mapping: o "beginner" is converted into "low"; o "average" is converted into "medium"; o "expert" is converted into "high". Loffredo & Stepanek Expires September 19, 2020 [Page 21] Internet-Draft jscontact-vcard March 2020 The INDEX parameter is represented by the position of the expertise among the declared expertises. BEGIN:VCARD VERSION:4.0 ... EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature EXPERTISE;INDEX=1;LEVEL=expert:chemistry ... END:VCARD { ... "personalInfo":[ ... { "type": "expertise", "value": "chemistry", "level": "high" }, { "type": "expertise", "value": "chinese literature", "level": "low" } ... ] ... } Figure 18: EXPERTISE mapping example 2.7.2. HOBBY The vCard HOBBY element defined by RFC6715 [RFC6715] is represented in JSCard as a "PersonalInformation" item of the "personalInfo" array (Figure 19). The "type" property is set to "hobby". The LEVEL parameter can be represented by the "level" property with a direct mapping. The INDEX parameter is represented by the position of the hobby among the declared hobbies. Loffredo & Stepanek Expires September 19, 2020 [Page 22] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... HOBBY;INDEX=1;LEVEL=high:reading HOBBY;INDEX=2;LEVEL=high:sewing ... END:VCARD { ... "personalInfo":[ ... { "type": "hobby", "value": "reading", "level": "high" }, { "type": "hobby", "value": "sewing", "level": "high" } ... ] ... } Figure 19: HOBBY mapping example 2.7.3. INTEREST The vCard INTEREST element defined by RFC6715 [RFC6715] is represented in JSCard as a "PersonalInformation" item of the "personalInfo" array (Figure 20). The "type" property is set to "interest". The LEVEL parameter can be represented by the "level" property with a direct mapping. The INDEX parameter is represented by the position of the interest among the declared interests. Loffredo & Stepanek Expires September 19, 2020 [Page 23] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... INTEREST;INDEX=1;LEVEL=medium:r&b music INTEREST;INDEX=2;LEVEL=high:rock 'n' roll music ... END:VCARD { ... "personalInfo":[ ... { "type": "interest", "value": "r&b music", "level": "medium" }, { "type": "interest", "value": "rock 'n' roll music", "level": "high" } ... ] ... } Figure 20: INTEREST mapping example 2.7.4. ORG-DIRECTORY The vCard ORG-DIRECTORY element is represented in JSCard as a "Resource" item of the "online" array (Figure 21). In the "Resource" item, the "type" member is set to "uri" as well as a key of the "labels" is set to "org-directory". The PREF parameter can be represented by the "isPreferred" property. The INDEX parameter is represented by the position of the directory among the online resources with the "org-directory" key in the "labels" map. Loffredo & Stepanek Expires September 19, 2020 [Page 24] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering ... END:VCARD { ... "online":[ ... { "type": "uri", "labels": { "org-directory" : true }, "value": "http://directory.mycompany.example.com" }, { "type": "uri", "labels": { "org-directory" : true }, "value": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering", "isPreferred": true }, ... ], ... } Figure 21: ORG-DIRECTORY mapping example 2.8. Explanatory Properties 2.8.1. CATEGORIES The vCard CATEGORIES element is converted into the JSCard "categories" array (Figure 22); an item for each category. Loffredo & Stepanek Expires September 19, 2020 [Page 25] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY ... END:VCARD { ... "categories":[ "INTERNET", "IETF", "INDUSTRY", "INFORMATION TECHNOLOGY" ] ... } Figure 22: CATEGORIES mapping example 2.8.2. NOTE The vCard NOTE element is mapped onto the JSCard "notes" array (Figure 23); an item for each note. The LANGUAGE parameter values can be expressed as corresponding entries of the "localizations" map included in each "Resource" item. BEGIN:VCARD VERSION:4.0 ... NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri. ... END:VCARD { ... "notes":[ { "value": "This fax number is operational 0800 to 1715 EST, Mon-Fri." } ] ... } Figure 23: NOTE mapping example Loffredo & Stepanek Expires September 19, 2020 [Page 26] Internet-Draft jscontact-vcard March 2020 2.8.3. PROID The vCard PRODID element is converted into the JSCard "prodId" property (Figure 24). BEGIN:VCARD VERSION:4.0 ... PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN ... END:VCARD { ... "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN" ... } Figure 24: PRODID mapping example 2.8.4. REV The vCard REV element is transformed into the JSCard "updated" property (Figure 25). BEGIN:VCARD VERSION:4.0 ... REV:19951031T222710Z ... END:VCARD { ... "updated": "19951031T222710Z" ... } Figure 25: REV mapping example 2.8.5. SOUND The vCard SOUND element is represented in JSCard as a "Resource" item of the "online" array (Figure 26). In the "Resource" item, the "type" member is set to "uri" as well as a key of the "labels" is set to "sound". Loffredo & Stepanek Expires September 19, 2020 [Page 27] Internet-Draft jscontact-vcard March 2020 The PREF and MEDIATYPE parameters can be represented by the "isPreferred" and "mediaType" properties 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 vCard UID element corresponds to the JSCard "uid" property (Figure 27). BEGIN:VCARD VERSION:4.0 ... UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 ... END:VCARD { ... "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6" ... } Figure 27: UID mapping example Loffredo & Stepanek Expires September 19, 2020 [Page 28] Internet-Draft jscontact-vcard March 2020 2.8.7. PID Parameter and CLIENTPIDMAP TBD 2.8.8. URL The vCard URL element is represented in JSCard as a "Resource" item of the "online" array (Figure 28). In the "Resource" item, the "type" member is set to "uri" as well as a key of the "labels" is set to "url". The PREF and MEDIATYPE parameters can be represented by the "isPreferred" and "mediaType" properties respectively. BEGIN:VCARD VERSION:4.0 ... URL:http://example.org/restaurant.french/~chezchic.html ... END:VCARD { ... "online":[ ... { "type": "uri", "labels": { "url" : true }, "value": "http://example.org/restaurant.french/~chezchic.html" }, ... ], ... } Figure 28: URL mapping example 2.9. Security Properties 2.9.1. KEY The vCard KEY element is represented in JSCard as a "Resource" item of the "online" array (Figure 29). In the "Resource" item, the "type" member is set to "uri" as well as a key of the "labels" is set to "key". The PREF and MEDIATYPE parameters can be represented by the "isPreferred" and "mediaType" properties respectively. Loffredo & Stepanek Expires September 19, 2020 [Page 29] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... KEY:http://www.example.com/keys/jdoe.cer ... END:VCARD { ... "online":[ ... { "type": "uri", "labels": { "key" : true }, "value": "http://www.example.com/keys/jdoe.cer" }, ... ], ... } Figure 29: KEY mapping example 2.10. Calendar Properties 2.10.1. FBURL The vCard FBURL element is represented in JSCard as a "Resource" item of the "online" array (Figure 30). In the "Resource" item, the "type" member is set to "uri" as well as a key of the "labels" is set to "fburl". The PREF and MEDIATYPE parameters can be represented by the "isPreferred" and "mediaType" properties respectively. Loffredo & Stepanek Expires September 19, 2020 [Page 30] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... FBURL;PREF=1:http://www.example.com/busy/janedoe FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb ... END:VCARD { ... "online":[ ... { "type": "uri", "labels": { "fburl" : true }, "value": "http://www.example.com/busy/janedoe", "isPreferred": true }, { "type": "uri", "labels": { "fburl" : true }, "value": "ftp://example.com/busy/project-a.ifb", "mediaType": "text/calendar" }, ... ], ... } Figure 30: FBURL mapping example 2.10.2. CALADRURI The vCard CALADRURI element is represented in JSCard as a "Resource" item of the "online" array (Figure 31). In the "Resource" item, the "type" member is set to "uri" as well as a key of the "labels" is set to "caladruri". The PREF and MEDIATYPE parameters can be represented by the "isPreferred" and "mediaType" properties respectively. Loffredo & Stepanek Expires September 19, 2020 [Page 31] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... CALADRURI;PREF=1:mailto:janedoe@example.com CALADRURI:http://example.com/calendar/jdoe ... END:VCARD { ... "online":[ ... { "type": "uri", "labels": { "caladruri" : true }, "value": "mailto:janedoe@example.com", "isPreferred": true }, { "type": "uri", "labels": { "caladruri" : true }, "value": "http://example.com/calendar/jdoe" }, ... ], ... } Figure 31: CALADRURI mapping example 2.10.3. CALURI The vCard CALURI element is represented in JSCard as a "Resource" item of the "online" array (Figure 32). In the "Resource" item, the "type" member is set to "uri" as well as a key of the "labels" is set to "caluri". The PREF and MEDIATYPE parameters can be represented by the "isPreferred" and "mediaType" properties respectively. Loffredo & Stepanek Expires September 19, 2020 [Page 32] Internet-Draft jscontact-vcard March 2020 BEGIN:VCARD VERSION:4.0 ... CALURI;PREF=1:http://cal.example.com/calA CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics ... END:VCARD { ... "online":[ ... { "type": "uri", "labels": { "caluri" : true }, "value": "http://cal.example.com/calA", "isPreferred": true }, { "type": "uri", "labels": { "caluri" : true }, "value": "ftp://ftp.example.com/calA.ics", "mediaType": "text/calendar" }, ... ], ... } Figure 32: CALURI mapping example 2.11. Extended Properties If an extended property is a resource, JSCard already allows to represent it by setting the "type" property to "other" and specifying a value for the "labels" map. Any other property supporting a custom feature MAY be added and its name MUST be prefixed with a specific domain name to avoid conflict, e.g. "example.com/customprop". 2.12. JSCard's Required Properties While converting a vCard into a JSCard, only the JSCard topmost "uid" property is required. Loffredo & Stepanek Expires September 19, 2020 [Page 33] Internet-Draft jscontact-vcard March 2020 2.13. JSCard's Unmatched Properties The "preferredContactMethod" property doesn't match any vCard element. 3. IANA Considerations This document has no actions for IANA. 4. Security Considerations This document doesn't report any security consideration. 5. References 5.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, DOI 10.17487/RFC6350, August 2011, . [RFC6473] Saint-Andre, P., "vCard KIND:application", RFC 6473, DOI 10.17487/RFC6473, December 2011, . [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, . [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, . [RFC6869] Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard KIND:device", RFC 6869, DOI 10.17487/RFC6869, February 2013, . [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, DOI 10.17487/RFC7095, January 2014, . Loffredo & Stepanek Expires September 19, 2020 [Page 34] Internet-Draft jscontact-vcard March 2020 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . [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, . 5.2. Informative References [draft-ietf-jmap-jscontact] "JSContact: A JSON representation of contact data", . 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 September 19, 2020 [Page 35]