draft-ietf-jmap-jscontact-vcard-06.txt   draft-ietf-jmap-jscontact-vcard-07.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: January 13, 2022 FastMail Expires: 23 April 2022 FastMail
July 12, 2021 20 October 2021
JSContact: Converting from and to vCard JSContact: Converting from and to vCard
draft-ietf-jmap-jscontact-vcard-06 draft-ietf-jmap-jscontact-vcard-07
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 January 13, 2022. This Internet-Draft will expire on 23 April 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 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 Provisions Relating to IETF Documents (https://trustee.ietf.org/
(https://trustee.ietf.org/license-info) in effect on the date of license-info) in effect on the date of publication of this document.
publication of this document. Please review these documents Please review these documents carefully, as they describe your rights
carefully, as they describe your rights and restrictions with respect and restrictions with respect to this document. Code Components
to this document. Code Components extracted from this document must extracted from this document must include Simplified BSD License text
include Simplified BSD License text as described in Section 4.e of as described in Section 4.e of the Trust Legal Provisions and are
the Trust Legal Provisions and are provided without warranty as provided without warranty as described in the Simplified BSD License.
described in the Simplified 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.2.1. Extensions . . . . . . . . . . . . . . . . . . . . . 4
1.3. Conventions Used in This Document . . . . . . . . . . . . 4 1.3. Conventions Used in This Document . . . . . . . . . . . . 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. JSContact Id . . . . . . . . . . . . . . . . . . . . . . 5 2.2. Unmapped JSContact Information . . . . . . . . . . . . . 5
2.3. General Properties . . . . . . . . . . . . . . . . . . . 6 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 . . . . . . . . . . . . . . . . . . . . . . . . 8 2.4.3. PHOTO . . . . . . . . . . . . . . . . . . . . . . . . 8
2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 9 2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE,
ANNIVERSARY . . . . . . . . . . . . . . . . . . . . . 9
2.4.5. GENDER . . . . . . . . . . . . . . . . . . . . . . . 11 2.4.5. GENDER . . . . . . . . . . . . . . . . . . . . . . . 11
2.5. Delivery Addressing Properties . . . . . . . . . . . . . 11 2.5. Delivery Addressing Properties . . . . . . . . . . . . . 11
2.5.1. ADR . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.5.1. ADR . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.6. Communications Properties . . . . . . . . . . . . . . . . 14 2.6. Communications Properties . . . . . . . . . . . . . . . . 14
2.6.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.6.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 14
2.6.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 15 2.6.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 15
2.6.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 16 2.6.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 16
2.7. Geographical Properties . . . . . . . . . . . . . . . . . 17 2.7. Geographical Properties . . . . . . . . . . . . . . . . . 17
2.7.1. Time Zone Representation . . . . . . . . . . . . . . 18 2.7.1. Time Zone Representation . . . . . . . . . . . . . . 18
2.8. Organizational Properties . . . . . . . . . . . . . . . . 19 2.8. Organizational Properties . . . . . . . . . . . . . . . . 18
2.8.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 19 2.8.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 18
2.8.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 20 2.8.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 19
2.8.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 21 2.8.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.8.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 22 2.8.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 21
2.8.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 24 2.8.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 23
2.8.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 25 2.8.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 24
2.9. Personal Information Properties . . . . . . . . . . . . . 25 2.9. Personal Information Properties . . . . . . . . . . . . . 24
2.9.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 26 2.9.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 25
2.9.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 26 2.9.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 25
2.9.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 27 2.9.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 26
2.9.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 28 2.9.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 27
2.10. Explanatory Properties . . . . . . . . . . . . . . . . . 29 2.10. Explanatory Properties . . . . . . . . . . . . . . . . . 28
2.10.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 29 2.10.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 28
2.10.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 30 2.10.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 29
2.10.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 31 2.10.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 30
2.10.4. REV . . . . . . . . . . . . . . . . . . . . . . . . 31 2.10.4. REV . . . . . . . . . . . . . . . . . . . . . . . . 30
2.10.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . 31 2.10.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . 30
2.10.6. UID . . . . . . . . . . . . . . . . . . . . . . . . 32 2.10.6. UID . . . . . . . . . . . . . . . . . . . . . . . . 31
2.10.7. CLIENTPIDMAP and PID Parameter . . . . . . . . . . . 33 2.10.7. CLIENTPIDMAP and PID Parameter . . . . . . . . . . . 32
2.10.8. URL . . . . . . . . . . . . . . . . . . . . . . . . 33 2.10.8. URL . . . . . . . . . . . . . . . . . . . . . . . . 32
2.10.9. VERSION . . . . . . . . . . . . . . . . . . . . . . 33 2.10.9. VERSION . . . . . . . . . . . . . . . . . . . . . . 32
2.11. Security Properties . . . . . . . . . . . . . . . . . . . 33 2.11. Security Properties . . . . . . . . . . . . . . . . . . . 32
2.11.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . 34 2.11.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . 33
2.12. Calendar Properties . . . . . . . . . . . . . . . . . . . 34 2.12. Calendar Properties . . . . . . . . . . . . . . . . . . . 33
2.12.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 34 2.12.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 33
2.12.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 35 2.12.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 34
2.12.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 36 2.12.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 35
2.13. vCard Unmatched Properties . . . . . . . . . . . . . . . 37 2.13. vCard Unmatched Properties . . . . . . . . . . . . . . . 36
2.14. Card Required Properties . . . . . . . . . . . . . . . . 37 2.14. Card Required Properties . . . . . . . . . . . . . . . . 36
3. Translating JSContact properties to vCard . . . . . . . . . . 38 3. Translating JSContact properties to vCard . . . . . . . . . . 37
3.1. Id . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3.1. Id . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.2. Localizations . . . . . . . . . . . . . . . . . . . . . . 38 3.2. Localizations . . . . . . . . . . . . . . . . . . . . . . 37
3.3. Date and Time Representations . . . . . . . . . . . . . . 38 3.3. Date and Time Representations . . . . . . . . . . . . . . 37
3.4. Time Zone . . . . . . . . . . . . . . . . . . . . . . . . 38 3.4. Time Zone . . . . . . . . . . . . . . . . . . . . . . . . 37
3.5. JSContact Types Matching Multiple vCard Properties . . . 39 3.5. JSContact Types Matching Multiple vCard Properties . . . 38
3.5.1. Title . . . . . . . . . . . . . . . . . . . . . . . . 39 3.5.1. Title . . . . . . . . . . . . . . . . . . . . . . . . 38
3.5.2. Resource . . . . . . . . . . . . . . . . . . . . . . 39 3.5.2. Resource . . . . . . . . . . . . . . . . . . . . . . 38
3.6. CardGroup . . . . . . . . . . . . . . . . . . . . . . . . 39 3.6. CardGroup . . . . . . . . . . . . . . . . . . . . . . . . 38
3.7. Card Unmatched Properties . . . . . . . . . . . . . . . . 39 3.7. Card Unmatched Properties . . . . . . . . . . . . . . . . 38
3.8. vCard Required Properties . . . . . . . . . . . . . . . . 39 3.8. vCard Required Properties . . . . . . . . . . . . . . . . 38
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
5. Implementation Status . . . . . . . . . . . . . . . . . . . . 40 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 39
5.1. CNR . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 5.1. CNR . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6. Security Considerations . . . . . . . . . . . . . . . . . . . 40 6. Security Considerations . . . . . . . . . . . . . . . . . . . 39
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.1. Normative References . . . . . . . . . . . . . . . . . . 41 7.1. Normative References . . . . . . . . . . . . . . . . . . 39
7.2. Informative References . . . . . . . . . . . . . . . . . 42 7.2. Informative References . . . . . . . . . . . . . . . . . 40
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41
1. Introduction 1. Introduction
1.1. Motivation 1.1. Motivation
The JSContact specification [draft-ietf-jmap-jscontact] has been The JSContact specification [draft-ietf-jmap-jscontact] has been
defined to represent contact card information as a more efficient defined to represent contact card information as a more efficient
alternative to vCard [RFC6350] and its JSON-based version named jCard alternative to vCard [RFC6350] and its JSON-based version named jCard
[RFC7095]. [RFC7095].
skipping to change at page 4, line 14 skipping to change at page 4, line 14
To facilitate this, this document defines how to convert contact To facilitate this, this document defines how to convert contact
information as defined in the JSContact [draft-ietf-jmap-jscontact] information as defined in the JSContact [draft-ietf-jmap-jscontact]
specification from and to vCard. specification from and to vCard.
1.2. Scope and Caveats 1.2. Scope and Caveats
JSContact and vCard have a lot of semantics in common, however some JSContact and vCard have a lot of semantics in common, however some
differences must be outlined: differences must be outlined:
o 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
o 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 1.2.1. Extensions
While translating vCard properties to JSContact, any vCard property While translating vCard properties to JSContact, any vCard property
that doesn't have a direct counterpart in JSContact MUST be converted 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 into a property whose name is prefixed by "ietf.org/<RFC defining the
extension>/". extension>/".
skipping to change at page 5, line 22 skipping to change at page 5, line 22
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"
member MUST have the same value. member MUST have the same value.
2.1. Common Parameters 2.1. Common Parameters
The following mapping rules apply to parameters that are common to The following mapping rules apply to parameters that are common to
most of the vCard properties: most of the vCard properties:
o The generic values of the TYPE parameter are mapped to the values * The generic values of the TYPE parameter are mapped to the values
of the "Context" type as defined in Section 1.5.1 of of the "Context" type as defined in Section 1.5.1 of
[draft-ietf-jmap-jscontact]. The "home" value corresponds to the [draft-ietf-jmap-jscontact]. The "home" value corresponds to the
"private" key. The mapping of those specific TYPE values used in "private" key. The mapping of those specific TYPE values used in
the TEL and RELATED properties are defined in Section 2.6.1 and the TEL and RELATED properties are defined in Section 2.6.1 and
Section 2.8.5. Section 2.8.5.
* The PREF parameter is mapped to the "pref" property.
o The PREF parameter is mapped to the "pref" property. * The MEDIATYPE parameter is mapped to the "mediaType" property. As
o The MEDIATYPE parameter is mapped to the "mediaType" property. As
described in Section 5.7 of [RFC6350], the media type of a described in Section 5.7 of [RFC6350], the media type of a
resource can be identified by its URI. For example, "image/gif" resource can be identified by its URI. For example, "image/gif"
can be derived from the ".gif" extension of a GIF image URI. can be derived from the ".gif" extension of a GIF image URI.
JSContact producers MAY provide the media type information even JSContact producers MAY provide the media type information even
when it is not specified in the vCard. when it is not specified in the vCard.
* The ALTID and LANGUAGE parameters are used in combination for
o The ALTID and LANGUAGE parameters are used in combination for
associating the language-dependent alternatives with a given associating the language-dependent alternatives with a given
property. Such alternatives are represented by using the property. Such alternatives are represented by using the
"localizations" map of a "LocalizedString" member inside the "localizations" map: the "localizations" key is the LANGUAGE
matching JSContact object. value, the key of the related PatchObject map is the JSON pointer
of the JSContact member matching the vCard property while the
value is the JSContact member itself.
2.2. JSContact Id 2.2. Unmapped JSContact Information
The rules to generate a map key of type Id are out of the scope of The rules to generate a map key of type Id as well as a value for
this document. "created", "language" and "preferredContactMethod" properties are out
of the scope of this document.
2.3. General Properties 2.3. General Properties
2.3.1. BEGIN and END 2.3.1. BEGIN and END
The BEGIN and END properties don't have a direct match with a The BEGIN and END properties don't have a direct match with a
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
skipping to change at page 6, line 43 skipping to change at page 6, line 40
"a-source":{ "a-source":{
"type": "uri", "type": "uri",
"label": "source", "label": "source",
"resource": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf" "resource": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf"
}, },
... ...
}, },
... ...
} }
Figure 1: SOURCE mapping example Figure 1: SOURCE mapping example
2.3.3. KIND 2.3.3. KIND
The KIND property is mapped to the "kind" member (Figure 2). Allowed 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 values are those described in Section 6.1.4 of [RFC6350] and extended
with the values declared in [RFC6473] and [RFC6869]. The value with the values declared in [RFC6473] and [RFC6869]. The value
"group" is reserved for a CardGroup instance. "group" is reserved for a CardGroup instance.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
skipping to change at page 7, line 18 skipping to change at page 7, line 18
KIND:individual KIND:individual
... ...
END:VCARD END:VCARD
{ {
... ...
"kind": "individual", "kind": "individual",
... ...
} }
Figure 2: KIND mapping example Figure 2: KIND mapping example
2.3.4. XML 2.3.4. XML
The XML property doesn't have a direct match with a JSContact The XML property doesn't have a direct match with a JSContact
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
The presence of multiple instances is implicitly associated with the (Figure 3). The presence of multiple instances is implicitly
full name translations in various languages regardless of the associated with the full name translations in various languages
presence of the ALTID parameter. Each translation corresponds to a regardless of the presence of the ALTID parameter. Each translation
different entry of the "localizations" map (Figure 3). 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 "name" The N instances are converted into equivalent items of the "name"
array (Figure 3): the N components are transformed into related array (Figure 3): the N components are transformed into related
"NameComponent" objects as presented in Table 1. Name components "NameComponent" objects as presented in Table 1. Name components
SHOULD be ordered such that their values joined by whitespace produce SHOULD be ordered such that their values joined by whitespace produce
a valid full name of this entity. a valid full name of this entity.
Each NICKNAME instance is mapped to an item of "nickNames" array. Each NICKNAME instance is mapped to an item of "nickNames" array.
+--------------------+--------------+ +====================+==============+
| N component | "type" value | | N component | "type" value |
+--------------------+--------------+ +====================+==============+
| Honorific Prefixes | prefix | | Honorific Prefixes | prefix |
+--------------------+--------------+
| Given Names | personal | | Given Names | personal |
+--------------------+--------------+
| Family Names | surname | | Family Names | surname |
+--------------------+--------------+
| Additional Names | additional | | Additional Names | additional |
+--------------------+--------------+
| Honorific Suffixes | suffix | | Honorific Suffixes | suffix |
+--------------------+--------------+ +--------------------+--------------+
Table 1: N components mapping Table 1: N components mapping
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
FN:Mr. John Q. Public\, Esq. FN:Mr. John Q. Public\, Esq.
N:Public;John;Quinlan;Mr.;Esq. N:Public;John;Quinlan;Mr.;Esq.
skipping to change at page 9, line 32 skipping to change at page 9, line 35
} }
Figure 4: PHOTO mapping example Figure 4: PHOTO mapping example
2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY
The BDAY and ANNIVERSARY properties and the extensions BIRTHPLACE, The BDAY and ANNIVERSARY properties and the extensions BIRTHPLACE,
DEATHDATE, DEATHPLACE described in [RFC6350] are represented as DEATHDATE, DEATHPLACE described in [RFC6350] are represented as
"Anniversary" objects included in the "anniversaries" map (Figure 5): "Anniversary" objects included in the "anniversaries" map (Figure 5):
o BDAY and BIRTHPLACE are mapped to "date" and "place" where "type" * BDAY and BIRTHPLACE are mapped to "date" and "place" where "type"
is set to "birth"; is set to "birth";
* DEATHDATE and DEATHPLACE are mapped to "date" and "place" where
o DEATHDATE and DEATHPLACE are mapped to "date" and "place" where
"type" is set to "death"; "type" is set to "death";
* ANNIVERSARY is mapped to "date" where "type" is set to "other" and
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 "label" is set to a value describing in detail the kind of
anniversary (e.g. "marriage date" for the wedding anniversary). anniversary (e.g. "marriage date" for the wedding anniversary).
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). The "fullAddress.localizations" includes possible (Section 2.1).
language-dependent alternatives.
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 10, line 48 skipping to change at page 10, line 50
}, },
"ANNIVERSARY-3" : { "ANNIVERSARY-3" : {
"type": "other", "type": "other",
"label": "marriage date", "label": "marriage date",
"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 doesn't have a direct match with a JSContact
feature. feature.
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 2 and Table 3.
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. Address members mapping Table 2: ADR components vs.
Address members mapping
+-------------+---------------------+-------------------------------+ +===============+======================+========================+
| ADR | Single | Combination of | | ADR component | Single | Combination of |
| component | StreetComponent | StreetComponent items | | | StreetComponent item | StreetComponent items |
| | item | | +===============+======================+========================+
+-------------+---------------------+-------------------------------+ | post office | postOfficeBox | |
| post office | postOfficeBox | | | box | | |
| box | | | +---------------+----------------------+------------------------+
| extended | extension | extension, building, floor, | | extended | extension | extension, building, |
| address | | room, apartment | | address | | floor, room, apartment |
| street | name | name, number, direction | +---------------+----------------------+------------------------+
| address | | | | street | name | name, number, |
+-------------+---------------------+-------------------------------+ | address | | direction |
+---------------+----------------------+------------------------+
Table 3: ADR components vs. StreetComponent items mapping Table 3: 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). The "fullAddress.localizations" as defined in (Section 2.1). Each possible language-dependent
includes possible language-dependent alternatives. alternative is represented as an entry of the PatchObject map where
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 45 skipping to change at page 14, line 45
"pref": 1 "pref": 1
}, },
"another-phone":{ "another-phone":{
"contexts":{ "private": true }, "contexts":{ "private": true },
"phone": "tel:+33-01-23-45-67" "phone": "tel:+33-01-23-45-67"
} }
], ],
... ...
} }
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).
skipping to change at page 16, line 26 skipping to change at page 16, line 26
{ {
"type": "username", "type": "username",
"label": "XMPP", "label": "XMPP",
"value": "alice@example.com" "value": "alice@example.com"
}, },
... ...
}, },
... ...
} }
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).
skipping to change at page 18, line 11 skipping to change at page 18, line 11
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 in three ways: as a time zone name, as a UTC
offset or as a URI. offset or as a URI.
o 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
o An UTC offset with zero minutes MUST be converted into one its zone (e.g. the value "-0500" converts to "Etc/GMT+5"). If the UTC
equivalent IANA "Etc/GMT" time zone to set in the "timeZone" offset value contains minutes information or is not an IANA
property. For example, the value "-0500" converts to "Etc/GMT+5". timezone name, it requires special handling.
Implementations MUST make sure that such IANA timezone exists. * 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
o An UTC offset with non-zero minutes MAY be converted to a custom is not interoperable anyway. In this case, if the URI corresponds
"TimeZone" object in the JSContact "timeZones" property (see to an IANA time zone [time-zones], this latter SHOULD be used.
example below). Otherwise, the URI value is dumped into a string.
o A non-IANA timezone name or URI MAY be converted to a custom
"TimeZone" object in the JSContact "timeZones" property. It is up
to the implementation to determine the time zone definition.
BEGIN:VCARD
VERSION:4.0
...
ADR;TZ=-0530:;;123 Main Street;Any Town;CA;91921-1234;U.S.A.
...
END:VCARD
{
...
"addresses": {
"addr1" : {
"timeZone": "/tz1"
...
}
},
"timeZones": {
"/tz1": {
"@type": "TimeZone",
"tzId": "TZ-0530",
"updated": "2021-06-07T14:24:45Z",
"standard": [{
"@type": "TimeZoneRule",
"offsetFrom": "-0530",
"offsetTo": "-0530",
"start": "1601-01-01T00:00:00"
}]
}
}
...
}
Figure 11: Mapping a TZ UTC offset value with non-zero minutes
2.8. Organizational Properties 2.8. Organizational Properties
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 12). 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 language. "title" member includes information about the title or role. The
rules to set the "organization" member are out of the scope of this
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). The "title.localizations" includes as defined in (Section 2.1).
possible language-dependent alternatives.
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 20, line 26 skipping to change at page 19, line 26
"a-title":{ "a-title":{
"title":{ "value" : "Project Leader" } "title":{ "value" : "Project Leader" }
}, },
"another-title":{ "another-title":{
"title":{ "value" : "Research Scientist" } "title":{ "value" : "Research Scientist" }
} }
}, },
... ...
} }
Figure 12: 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 13). 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
skipping to change at page 21, line 26 skipping to change at page 20, line 26
"a-logo":{ "a-logo":{
"type": "uri", "type": "uri",
"label": "logo", "label": "logo",
"resource": "http://www.example.com/pub/logos/abccorp.jpg" "resource": "http://www.example.com/pub/logos/abccorp.jpg"
}, },
... ...
}, },
... ...
} }
Figure 13: 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 14). 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). The "localizations" maps for both as defined in (Section 2.1).
"name" and "units" include possible language-dependent alternatives.
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 22, line 26 skipping to change at page 21, line 26
"name":{ "value": "ABC, Inc." }, "name":{ "value": "ABC, Inc." },
"units":[ "units":[
{ "value": "North American Division" }, { "value": "North American Division" },
{ "value": "Marketing" } { "value": "Marketing" }
] ]
} }
}, },
... ...
} }
Figure 14: ORG mapping example Figure 13: ORG mapping example
2.8.4. MEMBER 2.8.4. MEMBER
According to the JSContact specification, a group of contact cards is According to the JSContact specification, a group of contact cards is
represented through a CardGroup (Figure 15). The uids of the contact represented through a CardGroup (Figure 14). The uids of the contact
cards composing the group are included in the "members" map. cards composing the group are included in the "members" map.
In this case, the PREF parameter has not a JSContact counterpart; In this case, the PREF parameter has not a JSContact counterpart;
however, the implementers MAY insert the map entries by order of however, the implementers MAY insert the map entries by order of
preference. preference.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
KIND:group KIND:group
FN:The Doe family FN:The Doe family
skipping to change at page 23, line 23 skipping to change at page 22, line 23
{ {
"kind": "group", "kind": "group",
"fullName":{ "value": "The Doe family" }, "fullName":{ "value": "The Doe family" },
"uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667",
"members":{ "members":{
"urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true,
"urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true
} }
} }
Figure 15: Group example Figure 14: Group example
Only if the GROUP contains properties that don't have a mapping to Only if the GROUP contains properties that don't have a mapping to
CardGroup properties, then the CardGroup.card property MAY contain CardGroup properties, then the CardGroup.card property MAY contain
the optional Card object of this group. the optional Card object of this group.
{ {
"name": "The Doe family", "name": "The Doe family",
"uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667",
"members":{ "members":{
"urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true,
skipping to change at page 23, line 47 skipping to change at page 22, line 47
"fullName":{ "value": "The Doe family" }, "fullName":{ "value": "The Doe family" },
"uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667",
"photos":{ "photos":{
"a-photo":{ "a-photo":{
"href": "http://www.example.com/pub/photos/jqpublic.gif" "href": "http://www.example.com/pub/photos/jqpublic.gif"
} }
} }
} }
} }
Figure 16: card member of CardGroup object Figure 15: card member of CardGroup object
2.8.5. RELATED 2.8.5. RELATED
All the RELATED instances are converted into the "relatedTo" map All the RELATED instances are converted into the "relatedTo" map
(Figure 17): an entry for each entity the entity described by the (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 Card is associated with. The map keys are the "uid" values of the
associated cards. associated cards.
Each map value is a "Relation" object including only the "relation" Each map value is a "Relation" object including only the "relation"
member represented as a set of the RELATED-specific values of the member represented as a set of the RELATED-specific values of the
TYPE parameter as defined in Section 6.6.6 of [RFC6350]. TYPE parameter as defined in Section 6.6.6 of [RFC6350].
If the relation type is unspecified, the "relation" member MUST be If the relation type is unspecified, the "relation" member MUST be
empty. empty.
skipping to change at page 24, line 50 skipping to change at page 23, line 50
}, },
{ {
"Please contact my assistant Jane Doe for any inquiries.":{ "Please contact my assistant Jane Doe for any inquiries.":{
"relation":{ } "relation":{ }
} }
} }
}, },
... ...
} }
Figure 17: RELATED mapping example Figure 16: RELATED mapping example
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 18). 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
... ...
skipping to change at page 25, line 38 skipping to change at page 24, line 38
"type": "uri", "type": "uri",
"label": "contact-uri", "label": "contact-uri",
"resource": "mailto:contact@example.com", "resource": "mailto:contact@example.com",
"pref": 1 "pref": 1
}, },
... ...
}, },
... ...
} }
Figure 18: CONTACT-URI mapping example Figure 17: CONTACT-URI mapping example
2.9. Personal Information Properties 2.9. Personal Information Properties
The LEVEL parameter as defined in [RFC6715] is directly mapped to the The LEVEL parameter as defined in [RFC6715] is directly mapped to the
"level" property of the "PersonalInformation" type apart from when "level" property of the "PersonalInformation" type apart from when
LEVEL is used in the EXPERTISE property; in this case, the values are LEVEL is used in the EXPERTISE property; in this case, the values are
converted as in the following: converted as in the following:
o "beginner" is converted into "low"; * "beginner" is converted into "low";
o "average" is converted into "medium"; * "average" is converted into "medium";
o "expert" is converted into "high". * "expert" is converted into "high".
2.9.1. EXPERTISE 2.9.1. EXPERTISE
An EXPERTISE property as defined in [RFC6715] is represented as a An EXPERTISE property as defined in [RFC6715] is represented as a
"PersonalInformation" object in the "personalInfo" map (Figure 19). "PersonalInformation" object in the "personalInfo" map (Figure 18).
The "type" member is set to "expertise". The "type" member is set to "expertise".
The INDEX parameter is represented as the index of the expertise The INDEX parameter is represented as the index of the expertise
among the declared expertises. among the declared expertises.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature
EXPERTISE;INDEX=1;LEVEL=expert:chemistry EXPERTISE;INDEX=1;LEVEL=expert:chemistry
skipping to change at page 26, line 41 skipping to change at page 25, line 41
"PERSINFO-2" : { "PERSINFO-2" : {
"type": "expertise", "type": "expertise",
"value": "chinese literature", "value": "chinese literature",
"level": "low" "level": "low"
}, },
... ...
}, },
... ...
} }
Figure 19: EXPERTISE mapping example Figure 18: EXPERTISE mapping example
2.9.2. HOBBY 2.9.2. HOBBY
A HOBBY property as defined in [RFC6715] is represented as a A HOBBY property as defined in [RFC6715] is represented as a
"PersonalInformation" object in the "personalInfo" map (Figure 20). "PersonalInformation" object in the "personalInfo" map (Figure 19).
The "type" member is set to "hobby". The "type" member is set to "hobby".
The INDEX parameter is represented as the index of the hobby among The INDEX parameter is represented as the index of the hobby among
the declared hobbies. the declared hobbies.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
HOBBY;INDEX=1;LEVEL=high:reading HOBBY;INDEX=1;LEVEL=high:reading
HOBBY;INDEX=2;LEVEL=high:sewing HOBBY;INDEX=2;LEVEL=high:sewing
skipping to change at page 27, line 32 skipping to change at page 26, line 32
"PERSINFO-2" : { "PERSINFO-2" : {
"type": "hobby", "type": "hobby",
"value": "sewing", "value": "sewing",
"level": "high" "level": "high"
}, },
... ...
}, },
... ...
} }
Figure 20: HOBBY mapping example Figure 19: HOBBY mapping example
2.9.3. INTEREST 2.9.3. INTEREST
An INTEREST property as defined in [RFC6715] is represented as a An INTEREST property as defined in [RFC6715] is represented as a
"PersonalInformation" object in the "personalInfo" map (Figure 21). "PersonalInformation" object in the "personalInfo" map (Figure 20).
The "type" member is set to "interest". The "type" member is set to "interest".
The INDEX parameter is represented as the index of the interest among The INDEX parameter is represented as the index of the interest among
the declared interests. the declared interests.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
INTEREST;INDEX=1;LEVEL=medium:r&b music INTEREST;INDEX=1;LEVEL=medium:r&b music
INTEREST;INDEX=2;LEVEL=high:rock 'n' roll music INTEREST;INDEX=2;LEVEL=high:rock ā€™nā€™ roll music
... ...
END:VCARD END:VCARD
{ {
... ...
"personalInfo":{ "personalInfo":{
... ...
"PERSINFO-1" : { "PERSINFO-1" : {
"type": "interest", "type": "interest",
"value": "r&b music", "value": "r&b music",
"level": "medium" "level": "medium"
}, },
"PERSINFO-2" : { "PERSINFO-2" : {
"type": "interest", "type": "interest",
"value": "rock 'n' roll music", "value": "rock ā€™nā€™ roll music",
"level": "high" "level": "high"
}, },
... ...
}, },
... ...
} }
Figure 21: 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 22). 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
skipping to change at page 29, line 33 skipping to change at page 28, line 33
"type": "uri", "type": "uri",
"label": "org-directory", "label": "org-directory",
"resource": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering", "resource": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering",
"pref": 1 "pref": 1
}, },
... ...
}, },
... ...
} }
Figure 22: ORG-DIRECTORY mapping example Figure 21: ORG-DIRECTORY mapping example
2.10. Explanatory Properties 2.10. Explanatory Properties
2.10.1. CATEGORIES 2.10.1. CATEGORIES
A CATEGORIES property is converted into a set of entries of the A CATEGORIES property is converted into a set of entries of the
"categories" map (Figure 23). The keys are the comma-separated text "categories" map (Figure 22). The keys are the comma-separated text
values of the CATEGORIES property. values of the CATEGORIES property.
In this case, the PREF parameter has not a JSContact counterpart; In this case, the PREF parameter has not a JSContact counterpart;
however, implementers MAY use a map preserving the order of insertion however, implementers MAY use a map preserving the order of insertion
and the map entries can be inserted by order of preference. and the map entries can be inserted by order of preference.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY
skipping to change at page 30, line 23 skipping to change at page 29, line 23
... ...
"categories":{ "categories":{
"INTERNET": true, "INTERNET": true,
"IETF": true, "IETF": true,
"INDUSTRY": true, "INDUSTRY": true,
"INFORMATION TECHNOLOGY": true "INFORMATION TECHNOLOGY": true
}, },
... ...
} }
Figure 23: 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 24). 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). The "localizations" map includes as defined in (Section 2.1).
possible language-dependent alternatives.
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
{ {
... ...
"notes": { "notes": {
"value": "This fax number is operational 0800 to 1715 EST, Mon-Fri." "value": "This fax number is operational 0800 to 1715 EST, Mon-Fri."
}, },
... ...
} }
Figure 24: NOTE mapping example Figure 23: NOTE mapping example
2.10.3. PRODID 2.10.3. PRODID
The PRODID property is converted into the "prodId" member The PRODID property is converted into the "prodId" member
(Figure 25). (Figure 24).
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN
... ...
END:VCARD END:VCARD
{ {
... ...
"prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN", "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN",
... ...
} }
Figure 25: PRODID mapping example Figure 24: PRODID mapping example
2.10.4. REV 2.10.4. REV
The REV property is transformed into the "updated" member The REV property is transformed into the "updated" member
(Figure 26). (Figure 25).
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
REV:19951031T222710Z REV:19951031T222710Z
... ...
END:VCARD END:VCARD
{ {
... ...
"updated": "1995-10-31T22:27:10Z", "updated": "1995-10-31T22:27:10Z",
... ...
} }
Figure 26: 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 27). 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
skipping to change at page 32, line 29 skipping to change at page 31, line 29
"a-sound":{ "a-sound":{
"type": "uri", "type": "uri",
"label": "sound", "label": "sound",
"resource": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com" "resource": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com"
}, },
... ...
}, },
... ...
} }
Figure 27: SOUND mapping example Figure 26: SOUND mapping example
2.10.6. UID 2.10.6. UID
The UID property corresponds to the "uid" property (Figure 28) in The UID property corresponds to the "uid" property (Figure 27) in
both Card and CardGroup. both Card and CardGroup.
BEGIN:VCARD BEGIN:VCARD
VERSION:4.0 VERSION:4.0
... ...
UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
... ...
END:VCARD END:VCARD
{ {
... ...
"uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6", "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
... ...
} }
Figure 28: UID mapping example Figure 27: UID mapping example
2.10.7. CLIENTPIDMAP and PID Parameter 2.10.7. CLIENTPIDMAP and PID Parameter
The CLIENTPIDMAP property and the PDI parameter don't have a direct The CLIENTPIDMAP property and the PDI parameter don't have a direct
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 29). 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
skipping to change at page 33, line 41 skipping to change at page 32, line 41
"an-url":{ "an-url":{
"type": "uri", "type": "uri",
"label": "url", "label": "url",
"resource": "http://example.org/restaurant.french/~chezchic.html" "resource": "http://example.org/restaurant.french/~chezchic.html"
}, },
... ...
}, },
... ...
} }
Figure 29: URL mapping example Figure 28: URL mapping example
2.10.9. VERSION 2.10.9. VERSION
The VERSION property doesn't have a direct match with a JSContact The VERSION property doesn't have a direct match with a JSContact
feature. feature.
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 30). 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
skipping to change at page 34, line 35 skipping to change at page 33, line 35
"a-key":{ "a-key":{
"type": "uri", "type": "uri",
"label": "key", "label": "key",
"resource": "http://www.example.com/keys/jdoe.cer" "resource": "http://www.example.com/keys/jdoe.cer"
}, },
... ...
}, },
... ...
} }
Figure 30: KEY mapping example Figure 29: KEY mapping example
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 31). 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
skipping to change at page 35, line 34 skipping to change at page 34, line 34
"type": "uri", "type": "uri",
"label": "fburl", "label": "fburl",
"resource": "ftp://example.com/busy/project-a.ifb", "resource": "ftp://example.com/busy/project-a.ifb",
"mediaType": "text/calendar" "mediaType": "text/calendar"
}, },
... ...
}, },
... ...
} }
Figure 31: 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 32). 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
skipping to change at page 36, line 33 skipping to change at page 35, line 33
"another-caladruri":{ "another-caladruri":{
"type": "uri", "type": "uri",
"label": "caladruri", "label": "caladruri",
"resource": "http://example.com/calendar/jdoe" "resource": "http://example.com/calendar/jdoe"
}, },
... ...
}, },
... ...
} }
Figure 32: 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 33). 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
skipping to change at page 37, line 34 skipping to change at page 36, line 34
"type": "uri", "type": "uri",
"label": "caluri", "label": "caluri",
"resource": "ftp://ftp.example.com/calA.ics", "resource": "ftp://ftp.example.com/calA.ics",
"mediaType": "text/calendar" "mediaType": "text/calendar"
}, },
... ...
}, },
... ...
} }
Figure 33: 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. ietf.org/RFC6350/
GENDER"). GENDER").
2.14. Card Required Properties 2.14. Card Required Properties
skipping to change at page 38, line 19 skipping to change at page 37, line 19
Section 2. The remaining cases are treated in the following of this Section 2. The remaining cases are treated in the following of this
section. section.
3.1. Id 3.1. Id
Where a map key is of type Id, implementers are free to either ignore 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). it or preserve it as a vCard information (e.g. a vCard parameter).
3.2. Localizations 3.2. Localizations
A LocalizedString object is converted in multiple instances of the Each PatchObject entry value of each "localizations" entry is
same vCard property having different values of the LANGUAGE converted into a instance of the vCard property matching the
parameter. Implementers MAY set the ALTID parameter to couple JSContact member referenced by the PatchObject entry key. The
language-based alternatives of the same value. LANGUAGE parameter of such alternative MUST be set to the value of
the given "localizations" entry. The LANGUAGE parameter of a vCard
property presenting, at least, a language-dependent alternative MUST
be set to the value of the JSContact "language" property if it is
valued. Implementers MAY set the ALTID parameter to couple language-
based alternatives of the same value.
Note also that the components of some vCard values and their related Note also that the components of some vCard values and their
alternatives are split into different JSContact values. For example, language-dependent alternatives are split into different JSContact
the "name" and "units" values for a given language must be grouped to values. For example, the "name" and "units" values for a given
make a single ORG value where components are separated by ";". language must be grouped to make a single ORG value where components
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"
skipping to change at page 40, line 32 skipping to change at page 39, line 32
According to RFC 7942, "this will allow reviewers and working groups According to RFC 7942, "this will allow reviewers and working groups
to assign due considerationto documents that have the benefit of to assign due considerationto documents that have the benefit of
running code, which may serve as evidence of valuable experimentation running code, which may serve as evidence of valuable experimentation
and feedback that have made the implemented protocols more mature. and feedback that have made the implemented protocols more mature.
It is up to the individual working groups to use this information as It is up to the individual working groups to use this information as
they see fit". they see fit".
5.1. CNR 5.1. CNR
Responsible Organization: National Research Council (CNR) of Italy * Responsible Organization: National Research Council (CNR) of Italy
Location: https://github.com/consiglionazionaledellericerche/ * Location: https://github.com/consiglionazionaledellericerche/
jscontact-tools jscontact-tools
Description: This implementation includes tools for JSContact * Description: This implementation includes tools for JSContact
creation, validation, serialization/deserialization, and creation, validation, serialization/deserialization, and
conversion from vCard, xCard and jCard. conversion from vCard, xCard and jCard.
Level of Maturity: This is an "alpha" test implementation. * Level of Maturity: This is an "alpha" test implementation.
Coverage: This implementation includes all of the features * Coverage: This implementation includes all of the features
described in this specification. described in this specification.
Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it * Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it
6. Security Considerations 6. Security Considerations
This document doesn't present any security consideration. This document doesn't present any security consideration.
7. References 7. References
7.1. Normative References 7.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>. <https://www.rfc-editor.org/info/rfc3339>.
skipping to change at page 42, line 25 skipping to change at page 41, line 23
[uri-schemes] [uri-schemes]
"Uniform Resource Identifier (URI) Schemes", "Uniform Resource Identifier (URI) Schemes",
<https://www.iana.org/assignments/uri-schemes/uri- <https://www.iana.org/assignments/uri-schemes/uri-
schemes.xhtml>. schemes.xhtml>.
Authors' Addresses Authors' Addresses
Mario Loffredo Mario Loffredo
IIT-CNR/Registro.it IIT-CNR/Registro.it
Via Moruzzi,1 Via Moruzzi,1
Pisa 56124 56124 Pisa
IT Italy
Email: mario.loffredo@iit.cnr.it Email: mario.loffredo@iit.cnr.it
URI: http://www.iit.cnr.it URI: http://www.iit.cnr.it
Robert Stepanek Robert Stepanek
FastMail FastMail
PO Box 234, Collins St West PO Box 234, Collins St West
Melbourne VIC 8007 Melbourne VIC 8007
AU Australia
Email: rsto@fastmailteam.com Email: rsto@fastmailteam.com
URI: https://www.fastmail.com URI: https://www.fastmail.com
 End of changes. 100 change blocks. 
236 lines changed or deleted 210 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/