draft-ietf-jmap-jscontact-vcard-03.txt | draft-ietf-jmap-jscontact-vcard-04.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: October 16, 2021 FastMail | Expires: November 29, 2021 FastMail | |||
April 14, 2021 | May 28, 2021 | |||
JSContact: Converting from and to vCard | JSContact: Converting from and to vCard | |||
draft-ietf-jmap-jscontact-vcard-03 | draft-ietf-jmap-jscontact-vcard-04 | |||
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 October 16, 2021. | This Internet-Draft will expire on November 29, 2021. | |||
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/license-info) in effect on the date of | (https://trustee.ietf.org/license-info) in effect on the date of | |||
publication of this document. Please review these documents | publication of this document. Please review these documents | |||
skipping to change at page 2, line 28 ¶ | skipping to change at page 2, line 28 ¶ | |||
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 . . . . . . . . . . . . . . . . 12 | 2.6. Communications Properties . . . . . . . . . . . . . . . . 14 | |||
2.6.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 12 | 2.6.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 14 | |||
2.6.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 13 | 2.6.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 14 | |||
2.6.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 14 | 2.6.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 15 | |||
2.6.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 15 | 2.6.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 16 | |||
2.7. Geographical Properties . . . . . . . . . . . . . . . . . 16 | 2.7. Geographical Properties . . . . . . . . . . . . . . . . . 17 | |||
2.7.1. Time Zone Representation . . . . . . . . . . . . . . 17 | 2.7.1. Time Zone Representation . . . . . . . . . . . . . . 18 | |||
2.8. Organizational Properties . . . . . . . . . . . . . . . . 17 | 2.8. Organizational Properties . . . . . . . . . . . . . . . . 18 | |||
2.8.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 17 | 2.8.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 18 | |||
2.8.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 18 | 2.8.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 19 | |||
2.8.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 19 | 2.8.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 20 | |||
2.8.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 20 | 2.8.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 21 | |||
2.8.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 21 | 2.8.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 23 | |||
2.8.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 22 | 2.8.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 24 | |||
2.9. Personal Information Properties . . . . . . . . . . . . . 23 | 2.9. Personal Information Properties . . . . . . . . . . . . . 24 | |||
2.9.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 23 | 2.9.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 25 | |||
2.9.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 24 | 2.9.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 25 | |||
2.9.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 25 | 2.9.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 26 | |||
2.9.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 26 | 2.9.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 27 | |||
2.10. Explanatory Properties . . . . . . . . . . . . . . . . . 27 | 2.10. Explanatory Properties . . . . . . . . . . . . . . . . . 28 | |||
2.10.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 27 | 2.10.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 28 | |||
2.10.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 28 | 2.10.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 29 | |||
2.10.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 29 | 2.10.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
2.10.4. REV . . . . . . . . . . . . . . . . . . . . . . . . 29 | 2.10.4. REV . . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
2.10.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . 29 | 2.10.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
2.10.6. UID . . . . . . . . . . . . . . . . . . . . . . . . 30 | 2.10.6. UID . . . . . . . . . . . . . . . . . . . . . . . . 31 | |||
2.10.7. CLIENTPIDMAP and PID Parameter . . . . . . . . . . . 31 | 2.10.7. CLIENTPIDMAP and PID Parameter . . . . . . . . . . . 32 | |||
2.10.8. URL . . . . . . . . . . . . . . . . . . . . . . . . 31 | 2.10.8. URL . . . . . . . . . . . . . . . . . . . . . . . . 32 | |||
2.10.9. VERSION . . . . . . . . . . . . . . . . . . . . . . 31 | 2.10.9. VERSION . . . . . . . . . . . . . . . . . . . . . . 32 | |||
2.11. Security Properties . . . . . . . . . . . . . . . . . . . 31 | 2.11. Security Properties . . . . . . . . . . . . . . . . . . . 32 | |||
2.11.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . 32 | 2.11.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . 33 | |||
2.12. Calendar Properties . . . . . . . . . . . . . . . . . . . 32 | 2.12. Calendar Properties . . . . . . . . . . . . . . . . . . . 33 | |||
2.12.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 32 | 2.12.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 33 | |||
2.12.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 33 | 2.12.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 34 | |||
2.12.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 34 | 2.12.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 35 | |||
2.13. vCard Unmatched Properties . . . . . . . . . . . . . . . 35 | 2.13. vCard Unmatched Properties . . . . . . . . . . . . . . . 36 | |||
2.14. JSCard Required Properties . . . . . . . . . . . . . . . 35 | 2.14. Card Required Properties . . . . . . . . . . . . . . . . 36 | |||
3. Translating JSContact properties to vCard . . . . . . . . . . 36 | 3. Translating JSContact properties to vCard . . . . . . . . . . 37 | |||
3.1. Id . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 | 3.1. Id . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 | |||
3.2. Localizations . . . . . . . . . . . . . . . . . . . . . . 36 | 3.2. Localizations . . . . . . . . . . . . . . . . . . . . . . 37 | |||
3.3. Date and Time Representations . . . . . . . . . . . . . . 36 | 3.3. Date and Time Representations . . . . . . . . . . . . . . 37 | |||
3.4. Time Zone . . . . . . . . . . . . . . . . . . . . . . . . 36 | 3.4. Time Zone . . . . . . . . . . . . . . . . . . . . . . . . 37 | |||
3.5. JSContact Types Matching Multiple vCard Properties . . . 37 | 3.5. JSContact Types Matching Multiple vCard Properties . . . 38 | |||
3.5.1. Title . . . . . . . . . . . . . . . . . . . . . . . . 37 | 3.5.1. Title . . . . . . . . . . . . . . . . . . . . . . . . 38 | |||
3.5.2. Resource . . . . . . . . . . . . . . . . . . . . . . 37 | 3.5.2. Resource . . . . . . . . . . . . . . . . . . . . . . 38 | |||
3.6. JSCard Unmatched Properties . . . . . . . . . . . . . . . 37 | 3.6. CardGroup . . . . . . . . . . . . . . . . . . . . . . . . 38 | |||
3.7. vCard Required Properties . . . . . . . . . . . . . . . . 37 | 3.7. Card Unmatched Properties . . . . . . . . . . . . . . . . 38 | |||
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 | 3.8. vCard Required Properties . . . . . . . . . . . . . . . . 38 | |||
5. Implementation Status . . . . . . . . . . . . . . . . . . . . 37 | 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 | |||
5.1. CNR . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 | 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 39 | |||
6. Security Considerations . . . . . . . . . . . . . . . . . . . 38 | 5.1. CNR . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 | |||
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 | 6. Security Considerations . . . . . . . . . . . . . . . . . . . 39 | |||
7.1. Normative References . . . . . . . . . . . . . . . . . . 38 | 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 | |||
7.2. Informative References . . . . . . . . . . . . . . . . . 39 | 7.1. Normative References . . . . . . . . . . . . . . . . . . 40 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 | 7.2. Informative References . . . . . . . . . . . . . . . . . 41 | |||
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 17 ¶ | skipping to change at page 4, line 17 ¶ | |||
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 | o 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 JSCard, and a group of contact cards, named | contact card, named Card, and a group of contact cards, named | |||
JSCardGroup. | CardGroup. | |||
o 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 | |||
skipping to change at page 4, line 46 ¶ | skipping to change at page 4, line 46 ¶ | |||
Similarly, the reversed rules are applied while translating JSContact | Similarly, the reversed rules are applied while translating JSContact | |||
properties to vCard. | 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 JSCard/ | properties and parameters, are written in uppercase while the Card/ | |||
JSCardGroup features are written in camel case wrapped in double | CardGroup features are written in camel case wrapped in double | |||
quotes. | quotes. | |||
2. Translating vCard properties to JSContact | 2. Translating vCard properties to JSContact | |||
This section contains the translation rules from vCard to JSCard/ | This section contains the translation rules from vCard to Card/ | |||
JSCardGroup. 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 | ||||
which don't have a counterpart in CardGroup are converted into | ||||
related properties of the "CardGroup.card" object. In this case, the | ||||
"uid" member of both the resulting CardGroup object and its "card" | ||||
member MUST have the same value. | ||||
2.1. Common Parameters | 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 onto the | o The generic values of the TYPE parameter are mapped to the values | |||
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 the following of the | the TEL and RELATED properties are defined in Section 2.6.1 and | |||
document. | Section 2.8.5. | |||
o The PREF parameter is mapped onto the "pref" property. | o The PREF parameter is mapped to the "pref" property. | |||
o The MEDIATYPE parameter is mapped onto the "mediaType" property. | o The MEDIATYPE parameter is mapped to the "mediaType" property. As | |||
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. | |||
o 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 of a "LocalizedString" member inside the | |||
matching JSContact object. | matching JSContact object. | |||
o The LEVEL parameter as defined in [RFC6715] is directly mapped | ||||
onto the "level" property of the "PersonalInformation" type apart | ||||
from when LEVEL is used in the EXPERTISE property; in this case, | ||||
the values are converted as in the following: | ||||
* "beginner" is converted into "low"; | ||||
* "average" is converted into "medium"; | ||||
* "expert" is converted into "high". | ||||
2.2. JSContact Id | 2.2. JSContact Id | |||
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 are out of the scope of | |||
this document. | 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 | |||
skipping to change at page 6, line 47 ¶ | skipping to change at page 6, line 47 ¶ | |||
}, | }, | |||
... | ... | |||
}, | }, | |||
... | ... | |||
} | } | |||
Figure 1: SOURCE mapping example | Figure 1: SOURCE mapping example | |||
2.3.3. KIND | 2.3.3. KIND | |||
The KIND property is mapped onto the "kind" member (Figure 2). | The KIND property is mapped to the "kind" member (Figure 2). Allowed | |||
Allowed values are those described in Section 6.1.4 of [RFC6350] and | values are those described in Section 6.1.4 of [RFC6350] and extended | |||
extended with the values declared in [RFC6473] and [RFC6869]. The | with the values declared in [RFC6473] and [RFC6869]. The value | |||
value "group" is reserved for a JSCardGroup instance. | "group" is reserved for a CardGroup instance. | |||
BEGIN:VCARD | BEGIN:VCARD | |||
VERSION:4.0 | VERSION:4.0 | |||
... | ... | |||
KIND:individual | KIND:individual | |||
... | ... | |||
END:VCARD | END:VCARD | |||
{ | { | |||
... | ... | |||
skipping to change at page 7, line 29 ¶ | skipping to change at page 7, line 29 ¶ | |||
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 globally represented through the "fullName" | All the FN instances are represented through the "fullName" member. | |||
member. The presence of multiple instances is implicitly associated | The presence of multiple instances is implicitly associated with the | |||
with the full name translations in various languages regardless of | full name translations in various languages regardless of the | |||
the presence of the ALTID parameter. Each translation corresponds to | presence of the ALTID parameter. Each translation corresponds to a | |||
a different entry of the "localizations" map (Figure 3). | different entry of the "localizations" map (Figure 3). | |||
If the vCard represents a group of contacts, implementers MAY convert | ||||
the FN property into either "CardGroup.card.fullName" or | ||||
"CardGroup.name" or both properties. | ||||
2.4.2. N and NICKNAME | 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 onto 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 | | |||
+--------------------+--------------+ | +--------------------+--------------+ | |||
skipping to change at page 9, line 33 ¶ | skipping to change at page 9, line 33 ¶ | |||
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" array | "Anniversary" objects included in the "anniversaries" array | |||
(Figure 5): | (Figure 5): | |||
o BDAY and BIRTHPLACE are mapped onto "date" and "place" where | o BDAY and BIRTHPLACE are mapped to "date" and "place" where "type" | |||
"type" is set to "birth"; | is set to "birth"; | |||
o DEATHDATE and DEATHPLACE are mapped onto "date" and "place" where | o DEATHDATE and DEATHPLACE are mapped to "date" and "place" where | |||
"type" is set to "death"; | "type" is set to "death"; | |||
o ANNIVERSARY is mapped onto "date" where "type" is set to "other" | o ANNIVERSARY is mapped to "date" where "type" is set to "other" and | |||
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. | |||
skipping to change at page 11, line 18 ¶ | skipping to change at page 11, line 18 ¶ | |||
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. | presented in Table 2 and Table 3. | |||
+------------------+----------------+ | The "street address" and "extended address" ADR components MAY be | |||
| ADR component | Address member | | converted into either a single StreetComponent item or a combination | |||
+------------------+----------------+ | of StreetComponent items. | |||
| p.o. box | postOfficeBox | | ||||
| extended address | extension | | ||||
| street address | street | | ||||
| locality | locality | | ||||
| region | region | | ||||
| postal code | postcode | | ||||
| country name | country | | ||||
+------------------+----------------+ | ||||
Table 2: ADR components mapping | +---------------+----------------+ | |||
| ADR component | Address member | | ||||
+---------------+----------------+ | ||||
| locality | locality | | ||||
| region | region | | ||||
| postal code | postcode | | ||||
| country name | country | | ||||
+---------------+----------------+ | ||||
Table 2: ADR components vs. Address members mapping | ||||
+-------------+---------------------+-------------------------------+ | ||||
| ADR | Single | Combination of | | ||||
| component | StreetComponent | StreetComponent items | | ||||
| | item | | | ||||
+-------------+---------------------+-------------------------------+ | ||||
| post office | postOfficeBox | | | ||||
| box | | | | ||||
| extended | extension | extension, building, floor, | | ||||
| address | | room, apartment | | ||||
| street | name | name, number, direction | | ||||
| address | | | | ||||
+-------------+---------------------+-------------------------------+ | ||||
Table 3: ADR components vs. StreetComponent items mapping | ||||
The LABEL parameter is converted into the "fullAddress" member. | The 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. | |||
skipping to change at page 12, line 21 ¶ | skipping to change at page 13, line 21 ¶ | |||
END:VCARD | END:VCARD | |||
{ | { | |||
... | ... | |||
"addresses":{ | "addresses":{ | |||
"work-address" :{ | "work-address" :{ | |||
"contexts":{ "work": true }, | "contexts":{ "work": true }, | |||
"fullAddress":{ | "fullAddress":{ | |||
"value": "54321 Oak St\nReston\nVA\n20190\nUSA" | "value": "54321 Oak St\nReston\nVA\n20190\nUSA" | |||
}, | }, | |||
"street": "54321 Oak St", | "street": [ | |||
{ "name": "Oak St" }, | ||||
{ "number" : "54321" } | ||||
], | ||||
"locality": "Reston", | "locality": "Reston", | |||
"region": "VA", | "region": "VA", | |||
"country": "USA", | "country": "USA", | |||
"postcode": "20190", | "postcode": "20190", | |||
"countryCode": "US" | "countryCode": "US" | |||
}, | }, | |||
"private-address":{ | "private-address":{ | |||
"contexts":{ "private": true }, | "contexts":{ "private": true }, | |||
"fullAddress":{ | "fullAddress":{ | |||
"value": "12345 Elm St\nReston\nVA\n20190\nUSA" | "value": "12345 Elm St\nReston\nVA\n20190\nUSA" | |||
}, | }, | |||
"street": "12345 Elm St", | "street": [ | |||
{ "name": "Elm St" }, | ||||
{ "number" : "12345" } | ||||
], | ||||
"locality": "Reston", | "locality": "Reston", | |||
"region": "VA", | "region": "VA", | |||
"country": "USA", | "country": "USA", | |||
"postcode": "20190", | "postcode": "20190", | |||
"countryCode": "US" | "countryCode": "US" | |||
} | } | |||
}, | }, | |||
... | ... | |||
} | } | |||
Figure 6: ADR mapping example | Figure 6: ADR mapping example | |||
2.6. Communications Properties | 2.6. Communications Properties | |||
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 onto the "features" map keys. | values of the TYPE parameter are mapped to the "features" map keys. | |||
The values that don't match a key are represented as comma-separated | The values that don't match a key are represented as comma-separated | |||
values of the "label" member. If the "features" map is empty and the | values of the "label" member. If the "features" map is empty and the | |||
"label" member is not empty, the "other" feature is added. The | "label" member is not empty, the "other" feature is added. The | |||
"phone" member is set to the TEL value. | "phone" member is set to the TEL 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 16, line 40 ¶ | skipping to change at page 17, line 40 ¶ | |||
} | } | |||
] | ] | |||
}, | }, | |||
... | ... | |||
} | } | |||
Figure 10: LANG mapping example | Figure 10: LANG mapping example | |||
2.7. Geographical Properties | 2.7. Geographical Properties | |||
The GEO and TZ properties are not directly mapped onto topmost | The GEO and TZ properties are not directly mapped to topmost Card | |||
JSCard/JSCardGroup members because the same information is | members because the same information is represented through | |||
represented through 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 in three ways: as a time zone name, as a UTC | |||
offset or as a URI. | offset or as a URI. | |||
o The time zone name is directly matched by the "timeZone" member in | o If the TZ value is defined in the IANA timezone database, it is | |||
JSContact. | directly matched by the "timeZone" member in JSContact. | |||
o An UTC offset MUST be converted into the related "Etc/GMT" time | o An UTC offset MUST be converted into the related "Etc/GMT" time | |||
zone (e.g. the value "-0500" converts to "Etc/GMT+5"). If the UTC | zone (e.g. the value "-0500" converts to "Etc/GMT+5"). If the UTC | |||
offset value contains minutes information, it MUST be mapped to | offset value contains minutes information or is not an IANA | |||
the zone "Etc/GMT<sign><hour>:<minute>". | timezone name, it requires special handling. | |||
o Since there is no URI scheme defined for time zones [uri-schemes], | o Since there is no URI scheme defined for time zones [uri-schemes], | |||
any implementation that does use some a custom URI for a time zone | 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 | |||
to an IANA time zone [time-zones], this latter SHOULD be used. | to an IANA time zone [time-zones], this latter SHOULD be used. | |||
Otherwise, the URI value is dumped into a string. | Otherwise, the URI value is dumped into a string. | |||
2.8. Organizational Properties | 2.8. Organizational Properties | |||
2.8.1. TITLE and ROLE | 2.8.1. TITLE and ROLE | |||
skipping to change at page 20, line 31 ¶ | skipping to change at page 21, line 31 ¶ | |||
} | } | |||
}, | }, | |||
... | ... | |||
} | } | |||
Figure 13: 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 JSCardGroup (Figure 14). The uids of the | represented through a CardGroup (Figure 14). The uids of the contact | |||
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 | |||
MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af | MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af | |||
MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 | MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 | |||
END:VCARD | END:VCARD | |||
BEGIN:VCARD | ||||
VERSION:4.0 | ||||
FN:John Doe | ||||
UID:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af | ||||
END:VCARD | ||||
BEGIN:VCARD | ||||
VERSION:4.0 | ||||
FN:Jane Doe | ||||
UID:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 | ||||
END:VCARD | ||||
[ | ||||
{ | { | |||
"kind": "group", | "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 | |||
} | } | |||
}, | ||||
{ | ||||
"fullName":{ "value": "John Doe" }, | ||||
"uid": "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af" | ||||
}, | ||||
{ | ||||
"fullName":{ "value": "Jane Doe" }, | ||||
"uid": "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519" | ||||
} | } | |||
] | ||||
Figure 14: Group example | Figure 14: Group example | |||
Only if the GROUP contains properties that don't have a mapping to | ||||
CardGroup properties, then the CardGroup.card property MAY contain | ||||
the optional Card object of this group. | ||||
{ | ||||
"name": "The Doe family", | ||||
"uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", | ||||
"members":{ | ||||
"urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, | ||||
"urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true | ||||
}, | ||||
"card": { | ||||
"fullName":{ "value": "The Doe family" }, | ||||
"uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", | ||||
"photos":{ | ||||
"a-photo":{ | ||||
"href": "http://www.example.com/pub/photos/jqpublic.gif" | ||||
} | ||||
} | ||||
} | ||||
} | ||||
Figure 15: card member of CardGroup object | ||||
2.8.5. RELATED | 2.8.5. RELATED | |||
All the RELATED instances are globally converted into the "relatedTo" | All the RELATED instances are converted into the "relatedTo" map | |||
map (Figure 15): an entry for each entity the entity described by the | (Figure 16): an entry for each entity the entity described by the | |||
JSCard is associated with. The map keys are the "uid" values of the | 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. | |||
BEGIN:VCARD | BEGIN:VCARD | |||
skipping to change at page 22, line 43 ¶ | 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 15: 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 16). The entry value is a | entry of the "online" map (Figure 17). The entry value is a | |||
"Resource" object whose "type" member is set to "uri", the "label" | "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 23, line 30 ¶ | 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 16: 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 | ||||
"level" property of the "PersonalInformation" type apart from when | ||||
LEVEL is used in the EXPERTISE property; in this case, the values are | ||||
converted as in the following: | ||||
o "beginner" is converted into "low"; | ||||
o "average" is converted into "medium"; | ||||
o "expert" is converted into "high". | ||||
2.9.1. EXPERTISE | 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" array (Figure 17). | "PersonalInformation" object in the "personalInfo" array (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. | |||
The LEVEL parameter is mapped according to the rules as defined in | ||||
(Section 2.1). | ||||
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 | |||
... | ... | |||
END:VCARD | END:VCARD | |||
{ | { | |||
... | ... | |||
skipping to change at page 24, line 32 ¶ | skipping to change at page 25, line 41 ¶ | |||
{ | { | |||
"type": "expertise", | "type": "expertise", | |||
"value": "chinese literature", | "value": "chinese literature", | |||
"level": "low" | "level": "low" | |||
}, | }, | |||
... | ... | |||
], | ], | |||
... | ... | |||
} | } | |||
Figure 17: 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" array (Figure 18). | "PersonalInformation" object in the "personalInfo" array (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. | |||
The LEVEL parameter is mapped according to the rules as defined in | ||||
(Section 2.1). | ||||
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 | |||
... | ... | |||
END:VCARD | END:VCARD | |||
{ | { | |||
... | ... | |||
skipping to change at page 25, line 32 ¶ | skipping to change at page 26, line 32 ¶ | |||
{ | { | |||
"type": "hobby", | "type": "hobby", | |||
"value": "sewing", | "value": "sewing", | |||
"level": "high" | "level": "high" | |||
}, | }, | |||
... | ... | |||
], | ], | |||
... | ... | |||
} | } | |||
Figure 18: 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" array (Figure 19). | "PersonalInformation" object in the "personalInfo" array (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. | |||
The LEVEL parameter is mapped according to the rules as defined in | ||||
(Section 2.1). | ||||
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 | |||
{ | { | |||
... | ... | |||
skipping to change at page 26, line 32 ¶ | skipping to change at page 27, line 32 ¶ | |||
{ | { | |||
"type": "interest", | "type": "interest", | |||
"value": "rock 'n' roll music", | "value": "rock 'n' roll music", | |||
"level": "high" | "level": "high" | |||
}, | }, | |||
... | ... | |||
], | ], | |||
... | ... | |||
} | } | |||
Figure 19: 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 20). The entry value is a "Resource" object whose "type" | map (Figure 21). The entry value is a "Resource" object whose "type" | |||
member is set to "uri", the "label" member is set to "org-directory" | 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 27, 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 20: 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 21). 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 28, 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 21: CATEGORIES mapping example | Figure 22: CATEGORIES mapping example | |||
2.10.2. NOTE | 2.10.2. NOTE | |||
A NOTE property is mapped onto the "notes" property (Figure 22). All | A NOTE property is mapped to the "notes" property (Figure 23). All | |||
the NOTE instances are condensed in 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). The "localizations" map includes | |||
possible language-dependent alternatives. | 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. | |||
skipping to change at page 28, line 50 ¶ | skipping to change at page 29, line 50 ¶ | |||
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 22: 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 23). | (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 23: 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 24). | (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 24: 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 25). The entry value is a "Resource" object whose "type" | (Figure 26). The entry value is a "Resource" object whose "type" | |||
member is set to "uri", the "label" member is set to "sound" and the | 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 30, 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 25: 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 26). | The UID property corresponds to the "uid" property (Figure 27) in | |||
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 26: 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 JSCard 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 27). The entry value is a "Resource" object whose "type" | (Figure 28). The entry value is a "Resource" object whose "type" | |||
member is set to "uri", the "label" member is set to "url" and the | 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 31, 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 27: 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 28). The entry value is a "Resource" object whose "type" | (Figure 29). The entry value is a "Resource" object whose "type" | |||
member is set to "uri", the "label" member is set to "key" and the | 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 32, 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 28: 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 29). The entry value is a "Resource" object whose "type" | (Figure 30). The entry value is a "Resource" object whose "type" | |||
member is set to "uri", the "label" member is set to "fburl" and the | 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 33, 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 29: 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 30). The entry value is a "Resource" object whose "type" | (Figure 31). The entry value is a "Resource" object whose "type" | |||
member is set to "uri", the "label" member is set to "caladruri" and | 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 34, 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 30: 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 31). The entry value is a "Resource" object whose "type" | (Figure 32). The entry value is a "Resource" object whose "type" | |||
member is set to "uri", the "label" member is set to "caluri" and the | 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 35, 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 31: 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. JSCard Required Properties | 2.14. Card Required Properties | |||
While converting a vCard into a JSCard/JSCardGroup, only the topmost | While converting a vCard into a Card/CardGroup, only the topmost | |||
"uid" member is mandatory. Implementers are REQUIRED to set it when | "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 JSCard/ | In most of the cases, the rules about the translation from Card/ | |||
JSCardGroup to vCard can be derived by reversing the rules presented | CardGroup to vCard can be derived by reversing the rules presented in | |||
in Section 2. The remaining cases are treated in the following of | Section 2. The remaining cases are treated in the following of this | |||
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 | A LocalizedString object is converted in multiple instances of the | |||
same vCard property having different values of the LANGUAGE | same vCard property having different values of the LANGUAGE | |||
skipping to change at page 36, line 45 ¶ | skipping to change at page 37, line 45 ¶ | |||
"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 specifying both a date without the time and a partial | |||
date. In this case, the corresponding vCard format is that defined | date. In this case, the corresponding vCard format is that defined | |||
in Section 4.3.1. | in 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 onto 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, | |||
skipping to change at page 37, line 25 ¶ | skipping to change at page 38, line 25 ¶ | |||
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 vCard extended properties. | |||
3.6. JSCard Unmatched Properties | 3.6. CardGroup | |||
A CardGroup object is converted into a vCard by merging its | ||||
properties with the properties of "CardGroup.card" object. If the | ||||
"CardGroup.card.fullName" property exists, it MUST be used to set the | ||||
FN value. | ||||
3.7. Card Unmatched Properties | ||||
Both the "preferredContactMethod" and "created" members don't match | Both the "preferredContactMethod" and "created" members don't match | |||
any vCard property. Implementers MAY represent them as vCard | any vCard property. Implementers MAY represent them as vCard | |||
extended properties. | extended properties. | |||
3.7. vCard Required Properties | 3.8. vCard Required Properties | |||
While converting a JSCard/JSCardGroup into a vCard, only the FN | While converting a Card/CardGroup into a vCard, only the FN property | |||
property is required. Since the "fullName" property is optional, | is required. Since both the "Card.fullName" and "CardGroup.name" | |||
implementers are REQUIRED to generate an FN value when it is missing. | properties are optional, implementers are REQUIRED to generate an FN | |||
value when it is missing. | ||||
4. IANA Considerations | 4. IANA Considerations | |||
This document has no actions for IANA. | This document has no actions for IANA. | |||
5. Implementation Status | 5. Implementation Status | |||
NOTE: Please remove this section and the reference to RFC 7942 prior | NOTE: Please remove this section and the reference to RFC 7942 prior | |||
to publication as an RFC. | to publication as an RFC. | |||
End of changes. 80 change blocks. | ||||
201 lines changed or deleted | 237 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/ |