--- 1/draft-ietf-jmap-jscontact-vcard-03.txt 2021-05-28 07:13:22.646834820 -0700 +++ 2/draft-ietf-jmap-jscontact-vcard-04.txt 2021-05-28 07:13:22.706836325 -0700 @@ -1,19 +1,19 @@ jmap M. Loffredo Internet-Draft IIT-CNR/Registro.it Intended status: Standards Track R. Stepanek -Expires: October 16, 2021 FastMail - April 14, 2021 +Expires: November 29, 2021 FastMail + May 28, 2021 JSContact: Converting from and to vCard - draft-ietf-jmap-jscontact-vcard-03 + draft-ietf-jmap-jscontact-vcard-04 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 @@ -22,21 +22,21 @@ 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. + This Internet-Draft will expire on November 29, 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 @@ -62,75 +62,76 @@ 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 - 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 + 2.6. Communications Properties . . . . . . . . . . . . . . . . 14 + 2.6.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 14 + 2.6.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 14 + 2.6.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 15 + 2.6.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 16 + 2.7. Geographical Properties . . . . . . . . . . . . . . . . . 17 + 2.7.1. Time Zone Representation . . . . . . . . . . . . . . 18 + 2.8. Organizational Properties . . . . . . . . . . . . . . . . 18 + 2.8.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 18 + 2.8.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 19 + 2.8.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 2.8.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 21 + 2.8.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 23 + 2.8.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 24 + 2.9. Personal Information Properties . . . . . . . . . . . . . 24 + 2.9.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 25 + 2.9.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 25 + 2.9.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 26 + 2.9.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 27 + 2.10. Explanatory Properties . . . . . . . . . . . . . . . . . 28 + 2.10.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 28 + 2.10.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 29 + 2.10.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 30 + 2.10.4. REV . . . . . . . . . . . . . . . . . . . . . . . . 30 + 2.10.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . 30 + 2.10.6. UID . . . . . . . . . . . . . . . . . . . . . . . . 31 + 2.10.7. CLIENTPIDMAP and PID Parameter . . . . . . . . . . . 32 + 2.10.8. URL . . . . . . . . . . . . . . . . . . . . . . . . 32 + 2.10.9. VERSION . . . . . . . . . . . . . . . . . . . . . . 32 + 2.11. Security Properties . . . . . . . . . . . . . . . . . . . 32 + 2.11.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . 33 + 2.12. Calendar Properties . . . . . . . . . . . . . . . . . . . 33 + 2.12.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 33 + 2.12.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 34 + 2.12.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 35 + 2.13. vCard Unmatched Properties . . . . . . . . . . . . . . . 36 + 2.14. Card Required Properties . . . . . . . . . . . . . . . . 36 + 3. Translating JSContact properties to vCard . . . . . . . . . . 37 + 3.1. Id . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 + 3.2. Localizations . . . . . . . . . . . . . . . . . . . . . . 37 + 3.3. Date and Time Representations . . . . . . . . . . . . . . 37 + 3.4. Time Zone . . . . . . . . . . . . . . . . . . . . . . . . 37 + 3.5. JSContact Types Matching Multiple vCard Properties . . . 38 + 3.5.1. Title . . . . . . . . . . . . . . . . . . . . . . . . 38 + 3.5.2. Resource . . . . . . . . . . . . . . . . . . . . . . 38 + 3.6. CardGroup . . . . . . . . . . . . . . . . . . . . . . . . 38 + 3.7. Card Unmatched Properties . . . . . . . . . . . . . . . . 38 + 3.8. vCard Required Properties . . . . . . . . . . . . . . . . 38 + 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 + 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 39 + 5.1. CNR . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 39 + 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 + 7.1. Normative References . . . . . . . . . . . . . . . . . . 40 + 7.2. Informative References . . . . . . . . . . . . . . . . . 41 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 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]. @@ -146,22 +147,22 @@ 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. + contact card, named Card, and a group of contact cards, named + CardGroup. 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 @@ -175,66 +176,63 @@ 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 + properties and parameters, are written in uppercase while the Card/ + CardGroup features are written in camel case wrapped in double quotes. 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 + This section contains the translation rules from vCard to Card/ + CardGroup. The vCard properties are grouped according to the categories as defined in [RFC6350]. + If a vCard represents a group of contacts, those vCard properties + which don't have a counterpart in CardGroup are converted into + related properties of the "CardGroup.card" object. In this case, the + "uid" member of both the resulting CardGroup object and its "card" + member MUST have the same value. + 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 + o The generic values of the TYPE parameter are mapped to 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. + the TEL and RELATED properties are defined in Section 2.6.1 and + Section 2.8.5. - o The PREF parameter is mapped onto the "pref" property. + o The PREF parameter is mapped to 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 + o The MEDIATYPE parameter is mapped to 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. 2.3. General Properties 2.3.1. BEGIN and END The BEGIN and END properties don't have a direct match with a @@ -268,24 +266,24 @@ }, ... }, ... } 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. + The KIND property is mapped to 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 CardGroup instance. BEGIN:VCARD VERSION:4.0 ... KIND:individual ... END:VCARD { ... @@ -297,35 +295,39 @@ 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). + All the FN instances are 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). + + If the vCard represents a group of contacts, implementers MAY convert + the FN property into either "CardGroup.card.fullName" or + "CardGroup.name" or both properties. 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. + Each NICKNAME instance is mapped to an item of "nickNames" array. +--------------------+--------------+ | N component | "type" value | +--------------------+--------------+ | Honorific Prefixes | prefix | | Given Names | personal | | Family Names | surname | | Additional Names | additional | | Honorific Suffixes | suffix | +--------------------+--------------+ @@ -389,28 +391,28 @@ 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 BDAY and BIRTHPLACE are mapped to "date" and "place" where "type" + is set to "birth"; - o DEATHDATE and DEATHPLACE are mapped onto "date" and "place" where + o DEATHDATE and DEATHPLACE are mapped to "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 + o ANNIVERSARY is mapped to "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. @@ -469,35 +471,51 @@ 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. + presented in Table 2 and Table 3. - +------------------+----------------+ + The "street address" and "extended address" ADR components MAY be + converted into either a single StreetComponent item or a combination + of StreetComponent items. + + +---------------+----------------+ | 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 + Table 2: ADR components vs. Address members mapping + + +-------------+---------------------+-------------------------------+ + | ADR | Single | Combination of | + | component | StreetComponent | StreetComponent items | + | | item | | + +-------------+---------------------+-------------------------------+ + | post office | postOfficeBox | | + | box | | | + | extended | extension | extension, building, floor, | + | address | | room, apartment | + | street | name | name, number, direction | + | address | | | + +-------------+---------------------+-------------------------------+ + + Table 3: ADR components vs. StreetComponent items 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. @@ -517,53 +535,58 @@ END:VCARD { ... "addresses":{ "work-address" :{ "contexts":{ "work": true }, "fullAddress":{ "value": "54321 Oak St\nReston\nVA\n20190\nUSA" }, - "street": "54321 Oak St", + "street": [ + { "name": "Oak St" }, + { "number" : "54321" } + ], "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", + "street": [ + { "name": "Elm St" }, + { "number" : "12345" } + ], "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. - + values of the TYPE parameter are mapped to the "features" map keys. 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 @@ -701,42 +724,42 @@ } ] }, ... } 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 GEO and TZ properties are not directly mapped to topmost Card + 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. 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 If the TZ value is defined in the IANA timezone database, it 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:". + offset value contains minutes information or is not an IANA + timezone name, it requires special handling. 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 @@ -835,72 +858,76 @@ } }, ... } 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. + represented through a CardGroup (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. 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 } - }, + } + + Figure 14: Group example + + Only if the GROUP contains properties that don't have a mapping to + CardGroup properties, then the CardGroup.card property MAY contain + the optional Card object of this group. + { - "fullName":{ "value": "John Doe" }, - "uid": "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af" + "name": "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": "Jane Doe" }, - "uid": "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519" + "card": { + "fullName":{ "value": "The Doe family" }, + "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", + "photos":{ + "a-photo":{ + "href": "http://www.example.com/pub/photos/jqpublic.gif" + } + } + } } - ] - Figure 14: Group example + Figure 15: card member of CardGroup object 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 + All the RELATED instances are converted into the "relatedTo" map + (Figure 16): an entry for each entity the entity described by the + Card 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 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 @@ -927,26 +954,26 @@ }, { "Please contact my assistant Jane Doe for any inquiries.":{ "relation":{ } } } }, ... } - Figure 15: RELATED mapping example + Figure 16: 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 + entry of the "online" map (Figure 17). 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. The PREF and TYPE parameters are mapped according to the rules as defined in (Section 2.1). BEGIN:VCARD VERSION:4.0 ... @@ -962,36 +989,42 @@ "type": "uri", "label": "contact-uri", "resource": "mailto:contact@example.com", "pref": 1 }, ... }, ... } - Figure 16: CONTACT-URI mapping example + Figure 17: CONTACT-URI mapping example 2.9. Personal Information Properties + The LEVEL parameter as defined in [RFC6715] is directly mapped to 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: + + o "beginner" is converted into "low"; + o "average" is converted into "medium"; + o "expert" is converted into "high". + 2.9.1. EXPERTISE An EXPERTISE property as defined in [RFC6715] is represented as a - "PersonalInformation" object in the "personalInfo" array (Figure 17). + "PersonalInformation" object in the "personalInfo" array (Figure 18). 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). - BEGIN:VCARD VERSION:4.0 ... EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature EXPERTISE;INDEX=1;LEVEL=expert:chemistry ... END:VCARD { ... @@ -1005,34 +1038,31 @@ { "type": "expertise", "value": "chinese literature", "level": "low" }, ... ], ... } - Figure 17: EXPERTISE mapping example + Figure 18: 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). + "PersonalInformation" object in the "personalInfo" array (Figure 19). 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). - BEGIN:VCARD VERSION:4.0 ... HOBBY;INDEX=1;LEVEL=high:reading HOBBY;INDEX=2;LEVEL=high:sewing ... END:VCARD { ... @@ -1046,34 +1076,31 @@ { "type": "hobby", "value": "sewing", "level": "high" }, ... ], ... } - Figure 18: HOBBY mapping example + Figure 19: 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). + "PersonalInformation" object in the "personalInfo" array (Figure 20). 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). - BEGIN:VCARD VERSION:4.0 ... INTEREST;INDEX=1;LEVEL=medium:r&b music INTEREST;INDEX=2;LEVEL=high:rock 'n' roll music ... END:VCARD { ... @@ -1087,26 +1114,26 @@ { "type": "interest", "value": "rock 'n' roll music", "level": "high" }, ... ], ... } - Figure 19: INTEREST mapping example + Figure 20: 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" + map (Figure 21). 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. BEGIN:VCARD @@ -1130,28 +1157,28 @@ "type": "uri", "label": "org-directory", "resource": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering", "pref": 1 }, ... }, ... } - Figure 20: ORG-DIRECTORY mapping example + Figure 21: 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 + "categories" map (Figure 22). 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. BEGIN:VCARD VERSION:4.0 ... CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY @@ -1162,26 +1189,26 @@ ... "categories":{ "INTERNET": true, "IETF": true, "INDUSTRY": true, "INFORMATION TECHNOLOGY": true }, ... } - Figure 21: CATEGORIES mapping example + Figure 22: 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 + A NOTE property is mapped to the "notes" property (Figure 23). All + the NOTE instances are condensed into 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. @@ -1189,66 +1216,66 @@ END:VCARD { ... "notes": { "value": "This fax number is operational 0800 to 1715 EST, Mon-Fri." }, ... } - Figure 22: NOTE mapping example + Figure 23: NOTE mapping example 2.10.3. PRODID The PRODID property is converted into the "prodId" member - (Figure 23). + (Figure 24). 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 + Figure 24: PRODID mapping example 2.10.4. REV The REV property is transformed into the "updated" member - (Figure 24). + (Figure 25). BEGIN:VCARD VERSION:4.0 ... REV:19951031T222710Z ... END:VCARD { ... "updated": "1995-10-31T22:27:10Z", ... } - Figure 24: REV mapping example + Figure 25: 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" + (Figure 26). 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. 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 @@ -1262,50 +1289,51 @@ "a-sound":{ "type": "uri", "label": "sound", "resource": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com" }, ... }, ... } - Figure 25: SOUND mapping example + Figure 26: SOUND mapping example 2.10.6. UID - The UID property corresponds to the "uid" property (Figure 26). + The UID property corresponds to the "uid" property (Figure 27) in + both Card and CardGroup. 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 + Figure 27: UID mapping example 2.10.7. CLIENTPIDMAP and PID Parameter The CLIENTPIDMAP property and the PDI parameter don't have a direct - match with a JSCard feature. + match with a Card 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" + (Figure 28). 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 @@ -1319,32 +1347,32 @@ "an-url":{ "type": "uri", "label": "url", "resource": "http://example.org/restaurant.french/~chezchic.html" }, ... }, ... } - Figure 27: URL mapping example + Figure 28: URL mapping example 2.10.9. VERSION The VERSION property doesn't have a direct match with a JSContact feature. 2.11. Security Properties 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" + (Figure 29). 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 @@ -1358,28 +1386,28 @@ "a-key":{ "type": "uri", "label": "key", "resource": "http://www.example.com/keys/jdoe.cer" }, ... }, ... } - Figure 28: KEY mapping example + Figure 29: 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" + (Figure 30). 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). BEGIN:VCARD VERSION:4.0 ... FBURL;PREF=1:http://www.example.com/busy/janedoe @@ -1401,26 +1429,26 @@ "type": "uri", "label": "fburl", "resource": "ftp://example.com/busy/project-a.ifb", "mediaType": "text/calendar" }, ... }, ... } - Figure 29: FBURL mapping example + Figure 30: 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" + (Figure 31). 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). BEGIN:VCARD VERSION:4.0 ... CALADRURI;PREF=1:mailto:janedoe@example.com @@ -1441,26 +1469,26 @@ "another-caladruri":{ "type": "uri", "label": "caladruri", "resource": "http://example.com/calendar/jdoe" }, ... }, ... } - Figure 30: CALADRURI mapping example + Figure 31: 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" + (Figure 32). 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). BEGIN:VCARD VERSION:4.0 ... CALURI;PREF=1:http://cal.example.com/calA @@ -1482,41 +1510,41 @@ "type": "uri", "label": "caluri", "resource": "ftp://ftp.example.com/calA.ics", "mediaType": "text/calendar" }, ... }, ... } - Figure 31: CALURI mapping example + Figure 32: 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 +2.14. Card Required Properties - While converting a vCard into a JSCard/JSCardGroup, only the topmost + While converting a vCard into a Card/CardGroup, only the topmost "uid" member is mandatory. Implementers are REQUIRED to set it when it is missing. 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. + In most of the cases, the rules about the translation from Card/ + CardGroup 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 @@ -1537,21 +1565,21 @@ "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. + mapped to the TZ parameter. Implementers MAY map an "Etc/GMT" time zone either preserving the time zone name or converting it into a UTC offset. 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, @@ -1562,31 +1590,39 @@ 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 +3.6. CardGroup + + A CardGroup object is converted into a vCard by merging its + properties with the properties of "CardGroup.card" object. If the + "CardGroup.card.fullName" property exists, it MUST be used to set the + FN value. + +3.7. Card 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 +3.8. 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. + While converting a Card/CardGroup into a vCard, only the FN property + is required. Since both the "Card.fullName" and "CardGroup.name" + properties are 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.