draft-ietf-jmap-jscontact-vcard-08.txt   draft-ietf-jmap-jscontact-vcard-09.txt 
jmap M. Loffredo jmap M. Loffredo
Internet-Draft IIT-CNR/Registro.it Internet-Draft IIT-CNR/Registro.it
Intended status: Standards Track R. Stepanek Intended status: Standards Track R. Stepanek
Expires: 4 June 2022 FastMail Expires: 20 July 2022 FastMail
1 December 2021 16 January 2022
JSContact: Converting from and to vCard JSContact: Converting from and to vCard
draft-ietf-jmap-jscontact-vcard-08 draft-ietf-jmap-jscontact-vcard-09
Abstract Abstract
This document defines how to convert contact information as defined This document defines how to convert contact information as defined
in the JSContact [draft-ietf-jmap-jscontact] specification from and in the JSContact [draft-ietf-jmap-jscontact] specification from and
to vCard. to vCard.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
skipping to change at page 1, line 33 skipping to change at page 1, line 33
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 4 June 2022. This Internet-Draft will expire on 20 July 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License. provided without warranty as described in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Scope and Caveats . . . . . . . . . . . . . . . . . . . . 4 1.2. Scope and Caveats . . . . . . . . . . . . . . . . . . . . 4
1.2.1. Extensions . . . . . . . . . . . . . . . . . . . . . 4
1.3. Conventions Used in This Document . . . . . . . . . . . . 4 1.3. Conventions Used in This Document . . . . . . . . . . . . 4
1.4. Extensions . . . . . . . . . . . . . . . . . . . . . . . 4
2. Translating vCard properties to JSContact . . . . . . . . . . 5 2. Translating vCard properties to JSContact . . . . . . . . . . 5
2.1. Common Parameters . . . . . . . . . . . . . . . . . . . . 5 2.1. Common Parameters . . . . . . . . . . . . . . . . . . . . 5
2.2. Unmapped JSContact Information . . . . . . . . . . . . . 5 2.2. Unmapped JSContact Information . . . . . . . . . . . . . 5
2.3. General Properties . . . . . . . . . . . . . . . . . . . 5 2.3. General Properties . . . . . . . . . . . . . . . . . . . 5
2.3.1. BEGIN and END . . . . . . . . . . . . . . . . . . . . 6 2.3.1. BEGIN and END . . . . . . . . . . . . . . . . . . . . 6
2.3.2. SOURCE . . . . . . . . . . . . . . . . . . . . . . . 6 2.3.2. SOURCE . . . . . . . . . . . . . . . . . . . . . . . 6
2.3.3. KIND . . . . . . . . . . . . . . . . . . . . . . . . 6 2.3.3. KIND . . . . . . . . . . . . . . . . . . . . . . . . 6
2.3.4. XML . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.3.4. XML . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4. Identification Properties . . . . . . . . . . . . . . . . 7 2.4. Identification Properties . . . . . . . . . . . . . . . . 7
2.4.1. FN . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.4.1. FN . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.4.2. N and NICKNAME . . . . . . . . . . . . . . . . . . . 7 2.4.2. N and NICKNAME . . . . . . . . . . . . . . . . . . . 7
2.4.3. PHOTO . . . . . . . . . . . . . . . . . . . . . . . . 9 2.4.3. PHOTO . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, 2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE,
ANNIVERSARY . . . . . . . . . . . . . . . . . . . . . 9 ANNIVERSARY . . . . . . . . . . . . . . . . . . . . . 9
2.4.5. GENDER . . . . . . . . . . . . . . . . . . . . . . . 11 2.4.5. GENDER . . . . . . . . . . . . . . . . . . . . . . . 11
2.5. Delivery Addressing Properties . . . . . . . . . . . . . 11 2.5. Delivery Addressing Properties . . . . . . . . . . . . . 12
2.5.1. ADR . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.5.1. ADR . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.6. Communications Properties . . . . . . . . . . . . . . . . 14 2.6. Communications Properties . . . . . . . . . . . . . . . . 15
2.6.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.6.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 15
2.6.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 15 2.6.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 16
2.6.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 16 2.6.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 17
2.7. Geographical Properties . . . . . . . . . . . . . . . . . 17 2.7. Geographical Properties . . . . . . . . . . . . . . . . . 18
2.7.1. Time Zone Representation . . . . . . . . . . . . . . 18 2.7.1. Time Zone Representation . . . . . . . . . . . . . . 18
2.8. Organizational Properties . . . . . . . . . . . . . . . . 18 2.8. Organizational Properties . . . . . . . . . . . . . . . . 19
2.8.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 18 2.8.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 19
2.8.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 19 2.8.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 20
2.8.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.8.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.8.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 21 2.8.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 21
2.8.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 23 2.8.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 23
2.8.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 24 2.8.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 24
2.9. Personal Information Properties . . . . . . . . . . . . . 24 2.9. Personal Information Properties . . . . . . . . . . . . . 24
2.9.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 25 2.9.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 25
2.9.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 25 2.9.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 25
2.9.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 26 2.9.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 26
2.9.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 27 2.9.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 27
2.10. Explanatory Properties . . . . . . . . . . . . . . . . . 28 2.10. Explanatory Properties . . . . . . . . . . . . . . . . . 28
skipping to change at page 4, line 24 skipping to change at page 4, line 24
* The JSContact data model defines some contact information that * The JSContact data model defines some contact information that
doesn't have a direct mapping with vCard properties. In doesn't have a direct mapping with vCard properties. In
particular, unlike vCard, JSContact distinguishes between a single particular, unlike vCard, JSContact distinguishes between a single
contact card, named Card, and a group of contact cards, named contact card, named Card, and a group of contact cards, named
CardGroup. CardGroup.
* The properties that can be present multiple times in a vCard are * The properties that can be present multiple times in a vCard are
represented through different collections in JSContact; mainly as represented through different collections in JSContact; mainly as
maps, sometimes as lists, in some cases condensed in a single maps, sometimes as lists, in some cases condensed in a single
value. value.
1.2.1. Extensions
While translating vCard properties to JSContact, any vCard property
that doesn't have a direct counterpart in JSContact MUST be converted
into a property whose name is prefixed by "ietf.org/<RFC defining the
extension>/".
Any custom extension MAY be added and its name MUST be prefixed with
a specific domain name to avoid conflict, e.g. "example.com/
customprop".
Similarly, the reversed rules are applied while translating JSContact
properties to vCard.
1.3. Conventions Used in This Document 1.3. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
In the following of this document, the vCard features, namely In the following of this document, the vCard features, namely
properties and parameters, are written in uppercase while the Card/ properties and parameters, are written in uppercase while the Card/
CardGroup features are written in camel case wrapped in double CardGroup features are written in camel case wrapped in double
quotes. quotes.
1.4. Extensions
While translating vCard to JSContact, any vCard property that doesn't
have a direct counterpart in JSContact MUST be converted into a
property whose name is prefixed by "ietf.org:<RFC defining the
extension>:" (e.g. "ietf.org:rfc6350:").
Any custom extension MAY be added and its name MUST be prefixed with
a specific domain name to avoid conflict, e.g.
"example.com:customprop".
Likewise, while translating JSContact to vCard, a JSContact property
that doesn't have a direct counterpart in vCard MUST be converted
into a property whose name is prefixed with "X-" as specified in
Section 6.10 of [RFC6350].
2. Translating vCard properties to JSContact 2. Translating vCard properties to JSContact
This section contains the translation rules from vCard to Card/ This section contains the translation rules from vCard to Card/
CardGroup. The vCard properties are grouped according to the CardGroup. The vCard properties are grouped according to the
categories as defined in [RFC6350]. categories as defined in [RFC6350].
If a vCard represents a group of contacts, those vCard properties If a vCard represents a group of contacts, those vCard properties
which don't have a counterpart in CardGroup are converted into which don't have a counterpart in CardGroup are converted into
related properties of the "CardGroup.card" object. In this case, the related properties of the "CardGroup.card" object. In this case, the
"uid" member of both the resulting CardGroup object and its "card" "uid" member of both the resulting CardGroup object and its "card"
skipping to change at page 6, line 17 skipping to change at page 6, line 17
JSContact feature. JSContact feature.
2.3.2. SOURCE 2.3.2. SOURCE
A SOURCE property is represented as an entry of the "online" map A SOURCE property is represented as an entry of the "online" map
(Figure 1). The entry value is a "Resource" object whose "type" (Figure 1). The entry value is a "Resource" object whose "type"
member is set to "uri", the "label" member is set to "source" and the member is set to "uri", the "label" member is set to "source" and the
"resource" member is the SOURCE value. "resource" member is the SOURCE value.
The PREF and MEDIATYPE parameters are mapped according to the rules The PREF and MEDIATYPE parameters are mapped according to the rules
as defined in (Section 2.1). as defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf
... ...
END:VCARD END:VCARD
{ {
... ...
skipping to change at page 7, line 33 skipping to change at page 7, line 33
feature. feature.
2.4. Identification Properties 2.4. Identification Properties
2.4.1. FN 2.4.1. FN
All the FN instances are represented through the "fullName" member All the FN instances are represented through the "fullName" member
(Figure 3). The presence of multiple instances is implicitly (Figure 3). The presence of multiple instances is implicitly
associated with the full name translations in various languages associated with the full name translations in various languages
regardless of the presence of the ALTID parameter. Each translation regardless of the presence of the ALTID parameter. Each translation
is mapped according to the rules as defined in (Section 2.1). is mapped according to the rules as defined in Section 2.1.
If the vCard represents a group of contacts, implementers MAY convert If the vCard represents a group of contacts, implementers MAY convert
the FN property into either "CardGroup.card.fullName" or the FN property into either "CardGroup.card.fullName" or
"CardGroup.name" or both properties. "CardGroup.name" or both properties.
2.4.2. N and NICKNAME 2.4.2. N and NICKNAME
The N instances are converted into equivalent items of the The N instances are converted into equivalent items of the
"components" array of the "name" property (Figure 3): the N "components" array of the "name" property (Figure 3): the N
components are transformed into related "NameComponent" objects as components are transformed into related "NameComponent" objects as
skipping to change at page 9, line 12 skipping to change at page 9, line 12
Figure 3: FN, N, NICKNAME mapping example Figure 3: FN, N, NICKNAME mapping example
2.4.3. PHOTO 2.4.3. PHOTO
A PHOTO property is represented as an entry of the "photos" map A PHOTO property is represented as an entry of the "photos" map
(Figure 4). The entry value is a "File" object whose "href" member (Figure 4). The entry value is a "File" object whose "href" member
is the PHOTO value. is the PHOTO value.
The PREF and MEDIATYPE parameters are mapped according to the rules The PREF and MEDIATYPE parameters are mapped according to the rules
as defined in (Section 2.1). as defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
PHOTO:http://www.example.com/pub/photos/jqpublic.gif PHOTO:http://www.example.com/pub/photos/jqpublic.gif
... ...
END:VCARD END:VCARD
{ {
... ...
skipping to change at page 10, line 12 skipping to change at page 10, line 12
Both birth and death places are represented as instances of the Both birth and death places are represented as instances of the
"Address" object. "Address" object.
The BIRTHPLACE and DEATHPLACE properties that are represented as geo The BIRTHPLACE and DEATHPLACE properties that are represented as geo
URIs are converted into "Address" instances including only the URIs are converted into "Address" instances including only the
"coordinates" member. If the URI value is not a geo URI, the place "coordinates" member. If the URI value is not a geo URI, the place
is ignored. is ignored.
The ALTID and LANGUAGE parameters of both BIRTHPLACE and DEATHPLACE The ALTID and LANGUAGE parameters of both BIRTHPLACE and DEATHPLACE
properties are mapped according to the rules as defined in properties are mapped according to the rules as defined in
(Section 2.1). Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
BDAY:19531015T231000Z BDAY:19531015T231000Z
BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A. BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A.
DEATHDATE:19960415 DEATHDATE:19960415
DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A. DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A.
ANNIVERSARY:19860201 ANNIVERSARY:19860201
... ...
skipping to change at page 11, line 9 skipping to change at page 11, line 9
"date": "1986-02-01" "date": "1986-02-01"
} }
}, },
... ...
} }
Figure 5: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY Figure 5: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY
mapping example mapping example
2.4.5. GENDER 2.4.5. GENDER
The GENDER property doesn't have a direct match with a JSContact The GENDER property is a single structured value with two optional
feature. components: the biological sex and the gender information. The
former is represented as an enumerated value, while the latter as a
free-form text. As opposed to such a representation, the JSContact
specification includes the "SpeakToAs" object just to represent how
to address, speak to or refer to the contact. In particular, some
pre-defined values are allowed for the "grammaticalGender" member.
For the reasons stated above, the GENDER property doesn't have a
direct match with the "SpeakToAs" object. However, on the assumption
that the GENDER property doesn't store the actual biological sex of
the contact, implementations MAY use the conversion rules shown in
Table 2 and Table 3.
+==============+=====================================+
| GENDER value | "SpeakToAs.grammaticalGender" value |
+==============+=====================================+
| M | male |
+--------------+-------------------------------------+
| F | female |
+--------------+-------------------------------------+
| N | neuter |
+--------------+-------------------------------------+
| O | animate |
+--------------+-------------------------------------+
| U | SpeakToAs = null |
+--------------+-------------------------------------+
Table 2: GENDER to SpeakToAs conversion
+=====================================+==============+
| "SpeakToAs.grammaticalGender" value | GENDER value |
+=====================================+==============+
| male | M |
+-------------------------------------+--------------+
| female | F |
+-------------------------------------+--------------+
| neuter | N |
+-------------------------------------+--------------+
| animate | O |
+-------------------------------------+--------------+
| inanimate | N;inanimate |
+-------------------------------------+--------------+
Table 3: SpeakToAs to GENDER conversion
2.5. Delivery Addressing Properties 2.5. Delivery Addressing Properties
2.5.1. ADR 2.5.1. ADR
An ADR property is represented as an entry of the "addresses" map An ADR property is represented as an entry of the "addresses" map
(Figure 6). The entry value is an "Address" object. (Figure 6). The entry value is an "Address" object.
The ADR components are transformed into the "Address" members as The ADR components are transformed into the "Address" members as
presented in Table 2 and Table 3. presented in Table 4 and Table 5.
The "street address" and "extended address" ADR components MAY be The "street address" and "extended address" ADR components MAY be
converted into either a single StreetComponent item or a combination converted into either a single StreetComponent item or a combination
of StreetComponent items. of StreetComponent items.
+===============+================+ +===============+================+
| ADR component | Address member | | ADR component | Address member |
+===============+================+ +===============+================+
| locality | locality | | locality | locality |
+---------------+----------------+ +---------------+----------------+
| region | region | | region | region |
+---------------+----------------+ +---------------+----------------+
| postal code | postcode | | postal code | postcode |
+---------------+----------------+ +---------------+----------------+
| country name | country | | country name | country |
+---------------+----------------+ +---------------+----------------+
Table 2: ADR components vs. Table 4: ADR components vs.
Address members mapping Address members mapping
+===============+======================+========================+ +===============+======================+========================+
| ADR component | Single | Combination of | | ADR component | Single | Combination of |
| | StreetComponent item | StreetComponent items | | | StreetComponent item | StreetComponent items |
+===============+======================+========================+ +===============+======================+========================+
| post office | postOfficeBox | | | post office | postOfficeBox | |
| box | | | | box | | |
+---------------+----------------------+------------------------+ +---------------+----------------------+------------------------+
| extended | extension | extension, building, | | extended | extension | extension, building, |
| address | | floor, room, apartment | | address | | floor, room, apartment |
+---------------+----------------------+------------------------+ +---------------+----------------------+------------------------+
| street | name | name, number, | | street | name | name, number, |
| address | | direction | | address | | direction |
+---------------+----------------------+------------------------+ +---------------+----------------------+------------------------+
Table 3: ADR components vs. StreetComponent items mapping Table 5: ADR components vs. StreetComponent items mapping
The LABEL parameter is converted into the "fullAddress" member. The LABEL parameter is converted into the "fullAddress" member.
The GEO parameter is converted into the "coordinates" member. The GEO parameter is converted into the "coordinates" member.
The TZ parameter is converted into the "timeZone" member. The TZ parameter is converted into the "timeZone" member.
The CC parameter as defined in [RFC8605] is converted into the The CC parameter as defined in [RFC8605] is converted into the
"countryCode" member. "countryCode" member.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
The ALTID and LANGUAGE parameters are mapped according to the rules The ALTID and LANGUAGE parameters are mapped according to the rules
as defined in (Section 2.1). Each possible language-dependent as defined in Section 2.1. Each possible language-dependent
alternative is represented as an entry of the PatchObject map where alternative is represented as an entry of the PatchObject map where
the key references the "fullAddress" member. the key references the "fullAddress" member.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA
ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA
... ...
END:VCARD END:VCARD
skipping to change at page 14, line 17 skipping to change at page 15, line 17
2.6.1. TEL 2.6.1. TEL
A TEL property is represented as an entry of the "phones" map A TEL property is represented as an entry of the "phones" map
(Figure 7). The entry value is a "Phone" object. The TEL-specific (Figure 7). The entry value is a "Phone" object. The TEL-specific
values of the TYPE parameter are mapped to 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 The values that don't match a key are represented as comma-separated
values of the "label" member. The "phone" member is set to the TEL values of the "label" member. The "phone" member is set to the TEL
value. value.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555 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 TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67
... ...
END:VCARD END:VCARD
{ {
skipping to change at page 15, line 6 skipping to change at page 16, line 6
Figure 7: TEL mapping example Figure 7: TEL mapping example
2.6.2. EMAIL 2.6.2. EMAIL
An EMAIL property is represented as an entry of the "emails" map An EMAIL property is represented as an entry of the "emails" map
(Figure 8). The entry value is an "EmailAddress" object. The (Figure 8). The entry value is an "EmailAddress" object. The
"email" member is set to the EMAIL value. "email" member is set to the EMAIL value.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
EMAIL;TYPE=work:jqpublic@xyz.example.com EMAIL;TYPE=work:jqpublic@xyz.example.com
EMAIL;PREF=1:jane_doe@example.com EMAIL;PREF=1:jane_doe@example.com
... ...
END:VCARD END:VCARD
{ {
skipping to change at page 15, line 42 skipping to change at page 16, line 42
Figure 8: EMAIL mapping example Figure 8: EMAIL mapping example
2.6.3. IMPP 2.6.3. IMPP
An IMPP property is represented as an entry of the "online" map An IMPP property is represented as an entry of the "online" map
(Figure 9). The entry value is a "Resource" object whose "type" (Figure 9). The entry value is a "Resource" object whose "type"
member is set to "username", the "label" member is set to "XMPP" and member is set to "username", the "label" member is set to "XMPP" and
the "resource" member is the IMPP value. the "resource" member is the IMPP value.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
IMPP;PREF=1:xmpp:alice@example.com IMPP;PREF=1:xmpp:alice@example.com
... ...
END:VCARD END:VCARD
{ {
... ...
skipping to change at page 16, line 36 skipping to change at page 17, line 36
Figure 9: IMPP mapping example Figure 9: IMPP mapping example
2.6.4. LANG 2.6.4. LANG
A LANG property is represented as an entry of the A LANG property is represented as an entry of the
"preferredContactLanguages" map (Figure 10). The entry keys "preferredContactLanguages" map (Figure 10). The entry keys
correspond to the language tags, the corresponding entry values are correspond to the language tags, the corresponding entry values are
arrays of "ContactLanguage" objects. arrays of "ContactLanguage" objects.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
If both PREF and TYPE parameters are missing, the array of If both PREF and TYPE parameters are missing, the array of
"ContactLanguage" objects MUST be empty. "ContactLanguage" objects MUST be empty.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
LANG;TYPE=work;PREF=1:en LANG;TYPE=work;PREF=1:en
LANG;TYPE=work;PREF=2:fr LANG;TYPE=work;PREF=2:fr
LANG;TYPE=home:fr LANG;TYPE=home:fr
skipping to change at page 18, line 8 skipping to change at page 18, line 52
equivalent "Address" members. equivalent "Address" members.
The ALTID parameter is used for associating both GEO and TZ The ALTID parameter is used for associating both GEO and TZ
properties with the related address information. When the ALTID properties with the related address information. When the ALTID
parameter is missing, the matched members SHOULD be included in the parameter is missing, the matched members SHOULD be included in the
first "Address" object. first "Address" object.
2.7.1. Time Zone Representation 2.7.1. Time Zone Representation
As specified in Section 6.5.1 of [RFC6350], the time zone information 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 can be represented as a time zone name, as a UTC offset or as a URI.
offset or as a URI.
* If the TZ value is defined in the IANA timezone database, it is * If the TZ value is defined in the IANA timezone database, it is
directly matched by the "timeZone" member in JSContact. directly matched by the "timeZone" member in JSContact.
* An UTC offset MUST be converted into the related "Etc/GMT" time * 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 zone (e.g. the value "-0500" converts to "Etc/GMT+5"). If the UTC
offset value contains minutes information or is not an IANA offset value contains minutes information or is not an IANA
timezone name, it requires special handling. timezone name, it requires special handling.
* Since there is no URI scheme defined for time zones [uri-schemes], * 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 any implementation that does use some a custom URI for a time zone
is not interoperable anyway. In this case, if the URI corresponds is not interoperable anyway. In this case, if the URI corresponds
skipping to change at page 18, line 34 skipping to change at page 19, line 28
2.8.1. TITLE and ROLE 2.8.1. TITLE and ROLE
Both TITLE and ROLE properties are represented as entries of the Both TITLE and ROLE properties are represented as entries of the
"titles" map (Figure 11). The entry value is a "Title" object whose "titles" map (Figure 11). The entry value is a "Title" object whose
"title" member includes information about the title or role. The "title" member includes information about the title or role. The
rules to set the "organization" member are out of the scope of this rules to set the "organization" member are out of the scope of this
document. document.
The ALTID and LANGUAGE parameters are mapped according to the rules The ALTID and LANGUAGE parameters are mapped according to the rules
as defined in (Section 2.1). as defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
TITLE:Research Scientist TITLE:Research Scientist
ROLE:Project Leader ROLE:Project Leader
... ...
END:VCARD END:VCARD
{ {
skipping to change at page 19, line 36 skipping to change at page 20, line 13
Figure 11: TITLE and ROLE mapping example Figure 11: TITLE and ROLE mapping example
2.8.2. LOGO 2.8.2. LOGO
A LOGO property is represented as an entry of the "online" map A LOGO property is represented as an entry of the "online" map
(Figure 12). The entry value is a "Resource" object whose "type" (Figure 12). The entry value is a "Resource" object whose "type"
member is set to "uri", the "label" member is set to "logo" and the member is set to "uri", the "label" member is set to "logo" and the
"resource" member is the LOGO value. "resource" member is the LOGO value.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
LOGO:http://www.example.com/pub/logos/abccorp.jpg LOGO:http://www.example.com/pub/logos/abccorp.jpg
... ...
END:VCARD END:VCARD
{ {
... ...
skipping to change at page 20, line 36 skipping to change at page 20, line 46
Figure 12: LOGO mapping example Figure 12: LOGO mapping example
2.8.3. ORG 2.8.3. ORG
An ORG property is represented as an entry of the "organizations" map An ORG property is represented as an entry of the "organizations" map
(Figure 13). The entry value is an "Organization" object whose (Figure 13). The entry value is an "Organization" object whose
"name" member contains the organizational name and the "units" member "name" member contains the organizational name and the "units" member
contains the organizational units. contains the organizational units.
The ALTID and LANGUAGE parameters are mapped according to the rules The ALTID and LANGUAGE parameters are mapped according to the rules
as defined in (Section 2.1). as defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
ORG:ABC\, Inc.;North American Division;Marketing ORG:ABC\, Inc.;North American Division;Marketing
... ...
END:VCARD END:VCARD
{ {
... ...
skipping to change at page 24, line 14 skipping to change at page 24, line 14
2.8.6. CONTACT-URI 2.8.6. CONTACT-URI
A CONTACT-URI property as defined in [RFC8605] is represented as an A CONTACT-URI property as defined in [RFC8605] is represented as an
entry of the "online" map (Figure 17). 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" "Resource" object whose "type" member is set to "uri", the "label"
member is set to "contact-uri" and the "resource" member is the member is set to "contact-uri" and the "resource" member is the
CONTACT-URI value. CONTACT-URI value.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
CONTACT-URI;PREF=1:mailto:contact@example.com CONTACT-URI;PREF=1:mailto:contact@example.com
... ...
END:VCARD END:VCARD
{ {
... ...
skipping to change at page 27, line 42 skipping to change at page 27, line 42
Figure 20: INTEREST mapping example Figure 20: INTEREST mapping example
2.9.4. ORG-DIRECTORY 2.9.4. ORG-DIRECTORY
An ORG-DIRECTORY property is represented as an entry of the "online" An ORG-DIRECTORY property is represented as an entry of the "online"
map (Figure 21). 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" member is set to "uri", the "label" member is set to "org-directory"
and the "resource" member is the ORG-DIRECTORY value. and the "resource" member is the ORG-DIRECTORY value.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
The INDEX parameter is represented as the index of the directory The INDEX parameter is represented as the index of the directory
among the online resources with the "org-directory" label. among the online resources with the "org-directory" label.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com
ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering
... ...
skipping to change at page 29, line 32 skipping to change at page 29, line 32
Figure 22: CATEGORIES mapping example Figure 22: CATEGORIES mapping example
2.10.2. NOTE 2.10.2. NOTE
A NOTE property is mapped to the "notes" property (Figure 23). All A NOTE property is mapped to the "notes" property (Figure 23). All
the NOTE instances are condensed into a single note and separated by the NOTE instances are condensed into a single note and separated by
newline. newline.
The ALTID and LANGUAGE parameters are mapped according to the rules The ALTID and LANGUAGE parameters are mapped according to the rules
as defined in (Section 2.1). as defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri. NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri.
... ...
END:VCARD END:VCARD
{ {
... ...
skipping to change at page 31, line 6 skipping to change at page 31, line 6
Figure 25: REV mapping example Figure 25: REV mapping example
2.10.5. SOUND 2.10.5. SOUND
A SOUND property is represented as an entry of the "online" map A SOUND property is represented as an entry of the "online" map
(Figure 26). 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 member is set to "uri", the "label" member is set to "sound" and the
"resource" member is the SOUND value. "resource" member is the SOUND value.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com
... ...
END:VCARD END:VCARD
{ {
... ...
skipping to change at page 32, line 18 skipping to change at page 32, line 18
match with a Card feature. match with a Card feature.
2.10.8. URL 2.10.8. URL
An URL property is represented as an entry of the "online" map An URL property is represented as an entry of the "online" map
(Figure 28). 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 member is set to "uri", the "label" member is set to "url" and the
"resource" member is the URL value. "resource" member is the URL value.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
URL:http://example.org/restaurant.french/~chezchic.html URL:http://example.org/restaurant.french/~chezchic.html
... ...
END:VCARD END:VCARD
{ {
... ...
skipping to change at page 33, line 12 skipping to change at page 33, line 12
2.11. Security Properties 2.11. Security Properties
2.11.1. KEY 2.11.1. KEY
A KEY property is represented as an entry of the "online" map A KEY property is represented as an entry of the "online" map
(Figure 29). 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 member is set to "uri", the "label" member is set to "key" and the
"resource" member is the KEY value. "resource" member is the KEY value.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
KEY:http://www.example.com/keys/jdoe.cer KEY:http://www.example.com/keys/jdoe.cer
... ...
END:VCARD END:VCARD
{ {
... ...
skipping to change at page 33, line 47 skipping to change at page 33, line 47
2.12. Calendar Properties 2.12. Calendar Properties
2.12.1. FBURL 2.12.1. FBURL
An FBURL property is represented as an entry of the "online" map An FBURL property is represented as an entry of the "online" map
(Figure 30). 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 member is set to "uri", the "label" member is set to "fburl" and the
"resource" member is the FBURL value. "resource" member is the FBURL value.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
FBURL;PREF=1:http://www.example.com/busy/janedoe FBURL;PREF=1:http://www.example.com/busy/janedoe
FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb
... ...
END:VCARD END:VCARD
{ {
skipping to change at page 34, line 44 skipping to change at page 34, line 44
Figure 30: FBURL mapping example Figure 30: FBURL mapping example
2.12.2. CALADRURI 2.12.2. CALADRURI
A CALADRURI property is represented as an entry of the "online" map A CALADRURI property is represented as an entry of the "online" map
(Figure 31). 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 member is set to "uri", the "label" member is set to "caladruri" and
the "resource" member is the CALADRURI value. the "resource" member is the CALADRURI value.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
CALADRURI;PREF=1:mailto:janedoe@example.com CALADRURI;PREF=1:mailto:janedoe@example.com
CALADRURI:http://example.com/calendar/jdoe CALADRURI:http://example.com/calendar/jdoe
... ...
END:VCARD END:VCARD
{ {
skipping to change at page 35, line 43 skipping to change at page 35, line 43
Figure 31: CALADRURI mapping example Figure 31: CALADRURI mapping example
2.12.3. CALURI 2.12.3. CALURI
A CALURI property is represented as an entry of the "online" map A CALURI property is represented as an entry of the "online" map
(Figure 32). 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 member is set to "uri", the "label" member is set to "caluri" and the
"resource" member is the CALURI value. "resource" member is the CALURI value.
The PREF and TYPE parameters are mapped according to the rules as The PREF and TYPE parameters are mapped according to the rules as
defined in (Section 2.1). defined in Section 2.1.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
CALURI;PREF=1:http://cal.example.com/calA CALURI;PREF=1:http://cal.example.com/calA
CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics
... ...
END:VCARD END:VCARD
{ {
skipping to change at page 36, line 39 skipping to change at page 36, line 39
... ...
}, },
... ...
} }
Figure 32: CALURI mapping example Figure 32: CALURI mapping example
2.13. vCard Unmatched Properties 2.13. vCard Unmatched Properties
The unmatched vCard properties MAY be converted into JSContact The unmatched vCard properties MAY be converted into JSContact
properties whose name contains the prefix "ietf.org/RFC6350/" properties whose name contains the prefix "ietf.org:rfc6350:"
followed by property name in uppercase (i.e. ietf.org/RFC6350/ followed by property name in uppercase (i.e.
GENDER"). ietf.org:rfc6350:CLIENTPIDMAP").
2.14. Card Required Properties 2.14. Card Required Properties
While converting a vCard into a Card/CardGroup, 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 "uid" member is mandatory. Implementers are REQUIRED to set it when
it is missing. it is missing.
3. Translating JSContact properties to vCard 3. Translating JSContact properties to vCard
In most of the cases, the rules about the translation from Card/ In most of the cases, the rules about the translation from Card/
skipping to change at page 37, line 26 skipping to change at page 37, line 26
3.2. Localizations 3.2. Localizations
Each PatchObject entry value of each "localizations" entry is Each PatchObject entry value of each "localizations" entry is
converted into a instance of the vCard property matching the converted into a instance of the vCard property matching the
JSContact member referenced by the PatchObject entry key. The JSContact member referenced by the PatchObject entry key. The
LANGUAGE parameter of such alternative MUST be set to the value of LANGUAGE parameter of such alternative MUST be set to the value of
the given "localizations" entry. The LANGUAGE parameter of a vCard the given "localizations" entry. The LANGUAGE parameter of a vCard
property presenting, at least, a language-dependent alternative MUST property presenting, at least, a language-dependent alternative MUST
be set to the value of the JSContact "language" property if it is be set to the value of the JSContact "language" property if it is
valued. Implementers MAY set the ALTID parameter to couple language- valued. Implementers MAY set the ALTID parameter to group language-
based alternatives of the same value. based alternatives of the same value.
Note also that the components of some vCard values and their Note also that the components of some vCard values and their
language-dependent alternatives are split into different JSContact language-dependent alternatives are split into different JSContact
values. For example, the "name" and "units" values for a given values. For example, the "name" and "units" values for a given
language must be grouped to make a single ORG value where components language must be grouped to make a single ORG value where components
are separated by ";". are separated by ";".
3.3. Date and Time Representations 3.3. Date and Time Representations
The JSContact spec defines the "UTCDateTime" type to represent The JSContact spec defines the "UTCDateTime" type to represent
[RFC3339] "date-time" format with further restrictions. This means [RFC3339] "date-time" format with further restrictions. This means
that the matched vCard format for a "UTCDateTime" value MUST be one that the matched vCard format for a "UTCDateTime" value MUST be one
of the formats shown in Section 4.3.5 of [RFC6350] (i.e. of the formats shown in Section 4.3.5 of [RFC6350] (i.e.
"19961022T140000Z"). "19961022T140000Z").
In addition to such format, the "date" member of the "Anniversary" In addition to such format, the "date" member of the "Anniversary"
type allows specifying both a date without the time and a partial type allows to specify both dates without the time and partial dates.
date. In this case, the corresponding vCard format is that defined In such cases, the corresponding vCard format is that defined in
in Section 4.3.1. Section 4.3.1.
3.4. Time Zone 3.4. Time Zone
The time zone name as represented by the "timeZone" property is The time zone name as represented by the "timeZone" property is
mapped to the TZ parameter. mapped to the TZ parameter.
Implementers MAY map an "Etc/GMT" time zone either preserving the Implementers MAY map an "Etc/GMT" time zone either preserving the
time zone name or converting it into a UTC offset. time zone name or converting it into a UTC offset.
3.5. JSContact Types Matching Multiple vCard Properties 3.5. JSContact Types Matching Multiple vCard Properties
3.5.1. Title 3.5.1. Title
The "titles" property contains information about the job, the The "titles" property contains information about the job, the
position or the role of the entity the card represents. In vCard, position or the role of the entity the card represents. In vCard,
such information is split into the TITLE and ROLE properties. This such information is split into the TITLE and the ROLE properties.
specification defines TITLE as the default target property when This specification defines TITLE as the default target property when
converting the "titles" property. converting the "titles" property.
3.5.2. Resource 3.5.2. Resource
The "online" property includes resources that are usually represented The "online" property includes resources that are usually represented
through different vCard properties. The matched vCard property of a through different vCard properties. The matched vCard property of a
"Resource" object can be derived from the value of its "label" "Resource" object can be derived from the value of its "label"
member. member.
Any resource included in the "online" map that doesn't match a vCard Any resource included in the "online" map that doesn't match a vCard
property MAY be converted into vCard extended properties. property MAY be converted into a vCard extended property.
3.6. CardGroup 3.6. CardGroup
A CardGroup object is converted into a vCard by merging its A CardGroup object is converted into a vCard by merging its
properties with the properties of "CardGroup.card" object. If the properties with the properties of "CardGroup.card" object. If the
"CardGroup.card.fullName" property exists, it MUST be used to set the "CardGroup.card.fullName" property exists, it MUST be used to set the
FN value. FN value.
3.7. Card Unmatched Properties 3.7. Card Unmatched Properties
 End of changes. 42 change blocks. 
70 lines changed or deleted 114 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/