calext M. Loffredo
Internet-Draft IIT-CNR/Registro.it
Intended status: Standards Track R. Stepanek
Expires: 27 April 2023 FastMail
24 October 2022
JSContact: Converting from and to vCard
draft-ietf-calext-jscontact-vcard-03
Abstract
This document defines how to convert contact information defined in
the JSContact specification from and to vCard.
Note
This note is to be removed before publishing as an RFC.
The verbatim string 0000 in this document is a placeholder. It will
be replaced with the RFC number of this document.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 27 April 2023.
Copyright Notice
Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
Loffredo & Stepanek Expires 27 April 2023 [Page 1]
Internet-Draft jscontact-vcard October 2022
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Scope and Caveats . . . . . . . . . . . . . . . . . . . . 4
1.3. Conventions Used in This Document . . . . . . . . . . . . 5
2. Converting vCard to JSContact . . . . . . . . . . . . . . . . 5
2.1. General rules . . . . . . . . . . . . . . . . . . . . . . 5
2.1.1. Card or CardGroup . . . . . . . . . . . . . . . . . . 5
2.1.2. The uid property . . . . . . . . . . . . . . . . . . 6
2.1.3. Choosing identifiers . . . . . . . . . . . . . . . . 6
2.2. vCard Value Data Types . . . . . . . . . . . . . . . . . 6
2.2.1. TEXT . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2.2. URI . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2.3. DATE, TIME, DATE-TIME, DATE-AND-OR-TIME, and
TIMESTAMP . . . . . . . . . . . . . . . . . . . . . . 6
2.2.4. BOOLEAN . . . . . . . . . . . . . . . . . . . . . . . 7
2.2.5. INTEGER . . . . . . . . . . . . . . . . . . . . . . . 7
2.2.6. FLOAT . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2.7. UTC-OFFSET . . . . . . . . . . . . . . . . . . . . . 7
2.2.8. LANGUAGE-TAG . . . . . . . . . . . . . . . . . . . . 7
2.3. vCard Parameters . . . . . . . . . . . . . . . . . . . . 7
2.3.1. LANGUAGE . . . . . . . . . . . . . . . . . . . . . . 7
2.3.2. VALUE . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.3. PREF . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.4. ALTID . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.5. PID . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.6. TYPE . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.7. MEDIATYPE . . . . . . . . . . . . . . . . . . . . . . 10
2.3.8. CALSCALE . . . . . . . . . . . . . . . . . . . . . . 10
2.3.9. SORT-AS . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.10. GEO . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.11. TZ . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.12. DERIVED . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.13. PROP-ID . . . . . . . . . . . . . . . . . . . . . . . 11
2.4. General Properties . . . . . . . . . . . . . . . . . . . 11
2.4.1. BEGIN and END . . . . . . . . . . . . . . . . . . . . 11
2.4.2. SOURCE . . . . . . . . . . . . . . . . . . . . . . . 12
2.4.3. KIND . . . . . . . . . . . . . . . . . . . . . . . . 12
2.4.4. XML . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.5. Identification Properties . . . . . . . . . . . . . . . . 13
2.5.1. FN . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.5.2. N and NICKNAME . . . . . . . . . . . . . . . . . . . 13
Loffredo & Stepanek Expires 27 April 2023 [Page 2]
Internet-Draft jscontact-vcard October 2022
2.5.3. PHOTO . . . . . . . . . . . . . . . . . . . . . . . . 15
2.5.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE,
ANNIVERSARY . . . . . . . . . . . . . . . . . . . . . 16
2.5.5. GENDER . . . . . . . . . . . . . . . . . . . . . . . 18
2.5.6. GRAMMATICAL-GENDER and PRONOUNS . . . . . . . . . . . 18
2.6. Delivery Addressing Properties . . . . . . . . . . . . . 19
2.6.1. ADR . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.7. Communications Properties . . . . . . . . . . . . . . . . 21
2.7.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.7.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 22
2.7.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 23
2.7.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 24
2.7.5. CONTACT-CHANNEL-PREF . . . . . . . . . . . . . . . . 25
2.7.6. LOCALE . . . . . . . . . . . . . . . . . . . . . . . 27
2.8. Geographical Properties . . . . . . . . . . . . . . . . . 27
2.8.1. TZ . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.8.2. GEO . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.8.3. Combining geographical properties . . . . . . . . . . 28
2.9. Organizational Properties . . . . . . . . . . . . . . . . 28
2.9.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 28
2.9.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 29
2.9.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.9.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 31
2.9.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 33
2.9.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 34
2.10. Personal Information Properties . . . . . . . . . . . . . 34
2.10.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . 35
2.10.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . 35
2.10.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 36
2.10.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . 37
2.11. Explanatory Properties . . . . . . . . . . . . . . . . . 38
2.11.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 38
2.11.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 39
2.11.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 40
2.11.4. REV . . . . . . . . . . . . . . . . . . . . . . . . 40
2.11.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . 40
2.11.6. UID . . . . . . . . . . . . . . . . . . . . . . . . 41
2.11.7. CLIENTPIDMAP and PID Parameter . . . . . . . . . . . 42
2.11.8. URL . . . . . . . . . . . . . . . . . . . . . . . . 42
2.11.9. VERSION . . . . . . . . . . . . . . . . . . . . . . 42
2.11.10. CREATED . . . . . . . . . . . . . . . . . . . . . . 42
2.11.11. X-ABLabel . . . . . . . . . . . . . . . . . . . . . 43
2.12. Security Properties . . . . . . . . . . . . . . . . . . . 44
2.12.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . 44
2.13. Calendar Properties . . . . . . . . . . . . . . . . . . . 44
2.13.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 44
2.13.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 45
2.13.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 46
Loffredo & Stepanek Expires 27 April 2023 [Page 3]
Internet-Draft jscontact-vcard October 2022
2.14. Extended Properties and Parameters . . . . . . . . . . . 47
2.15. New JSContact properties . . . . . . . . . . . . . . . . 47
2.15.1. Property props . . . . . . . . . . . . . . . . . . . 48
2.15.2. Property params . . . . . . . . . . . . . . . . . . 48
3. Converting JSContact to vCard . . . . . . . . . . . . . . . . 49
3.1. Conversion Rules . . . . . . . . . . . . . . . . . . . . 49
3.2. New vCard Properties and Parameters . . . . . . . . . . . 50
3.2.1. Property JSPROP . . . . . . . . . . . . . . . . . . . 50
3.2.2. Parameter JSPATH . . . . . . . . . . . . . . . . . . 52
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52
5. Implementation Status . . . . . . . . . . . . . . . . . . . . 52
5.1. CNR . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6. Security Considerations . . . . . . . . . . . . . . . . . . . 53
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 53
7.1. Normative References . . . . . . . . . . . . . . . . . . 53
7.2. Informative References . . . . . . . . . . . . . . . . . 54
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55
1. Introduction
1.1. Motivation
The JSContact data model and format [I-D.ietf-calext-jscontact] aims
to be an alternative to the widely used vCard [RFC6350] standard and
jCard [RFC7095].
While applications might prefer JSContact to exchange contact card
data with other systems, they are likely to interoperate with
services and clients that only support vCard or jCard. Similarly,
existing contact data providers and consumers already using vCard or
jCard might want to represent their contact data also in JSContact.
To achieve this, this document defines a standard how to convert
contact data between JSContact and vCard (and consequently jCard).
1.2. Scope and Caveats
JSContact and vCard have a lot of semantics in common, however some
differences must be outlined:
* The JSContact data model defines some contact information that
doesn't have a direct conversion with vCard properties. In
particular, unlike vCard, JSContact distinguishes between a single
contact card, named Card, and a group of contact cards, named
CardGroup.
Loffredo & Stepanek Expires 27 April 2023 [Page 4]
Internet-Draft jscontact-vcard October 2022
* The properties that can be present multiple times in a vCard are
represented through different collections in JSContact; mainly as
maps, sometimes as arrays, in some cases condensed in a single
value.
1.3. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
In the following of this document, the vCard features, namely
properties and parameters, are written in uppercase while the Card/
CardGroup features are written in camel case wrapped in double
quotes.
2. Converting vCard to JSContact
This section contains the conversion rules from vCard to JSContact
Card/CardGroup. Its follows the same structure as the vCard v4 RFC
document [RFC6350]. Properties and parameters of vCard extension
RFCs, including the vCard JSContact Extension RFC
[I-D.ietf-calext-vcard-jscontact-extensions] are added to appropriate
subsections.
2.1. General rules
2.1.1. Card or CardGroup
The vCard format represents a contact and a _group_ of contacts both
as a vCard object. In contrast, JSContact defines two distinct
object types: Card for a contact representing a single entity,
CardGroup for a group of contacts. The following rules define which
JSContact object type to choose:
* If the vCard does not contain the KIND property, or the value of
this property is anything but group then convert it to a Card
object.
* If the KIND property value is group then choose a CardGroup
object. If the vCard contains any standard properties that do not
convert to a standard CardGroup property, convert the vCard _also_
to a Card and use that as the value of the card property in the
CardGroup.
Loffredo & Stepanek Expires 27 April 2023 [Page 5]
Internet-Draft jscontact-vcard October 2022
2.1.2. The uid property
The UID property in vCard is optional, but the uid property in
JSContact is mandatory. Implementations that convert a vCard without
UID property MUST generate a unique identifier as value for the uid
property. They SHOULD generate the same identifier when repeatedly
converting the same vCard, but they MAY generate different values.
Consequently, a vCard without UID property MAY does not convert to
one exact instance of a JSContact card or card group.
2.1.3. Choosing identifiers
Multi-valued properties in JSContact typically are represented as a
JSON object where the object keys are of the Id type and the object
values are the converted vCard property. In absence of the PROP-ID
parameter (see Section 2.3.13), implementations are free to choose
any identifier for such entries. Whatever identifier generation
scheme implementations use, they SHOULD generate values of short
character length. For example, this could be an incrementing number
across all Ids or only unique within one JSON object.
2.2. vCard Value Data Types
2.2.1. TEXT
This converts to the JSContact String type.
2.2.2. URI
This converts to the JSContact String type.
2.2.3. DATE, TIME, DATE-TIME, DATE-AND-OR-TIME, and TIMESTAMP
The TIMESTAMP type generally converts to the UTCDateTime. It
converts to the Timestamp type for anniversaries.
The DATE type converts to the PartialDate type, which only is
relevant for anniversaries. This does not apply to DATE values that
only define a month or a day.
The TIME, DATE-TIME, DATE-AND-OR-TIME types and DATE type values that
only define a month or day do not convert to any JSContact type.
vCard properties or parameters having such values MAY convert as
defined in Section 2.15.
Loffredo & Stepanek Expires 27 April 2023 [Page 6]
Internet-Draft jscontact-vcard October 2022
2.2.4. BOOLEAN
This converts to the JSContact Boolean type.
2.2.5. INTEGER
This converts to the JSContact Number type.
2.2.6. FLOAT
This converts to the JSContact Int and UnsignedInt types.
2.2.7. UTC-OFFSET
This either converts to a String containing an IANA TimeZone Database
entry name (see Section 2.8.1), or it does not convert to any
JSContact type. For the latter, vCard properties or parameters
having such values MAY convert to JSContact as defined in
Section 2.15.
2.2.8. LANGUAGE-TAG
This converts to the JSContact String type.
2.3. vCard Parameters
2.3.1. LANGUAGE
This converts to an entry in the localizations property for the vCard
property that this parameter is set on. The value of the LANGUAGE
parameter defines the language key in the localizations property.
The JSON pointer in the PatchObject is the path to the JSContact
property that the vCard property converts to. The value of the
PatchObject is the converted property value.
Note that an entry in the localizations MAY but need not point to an
existing property. The following two examples illustrate each case.
Loffredo & Stepanek Expires 27 April 2023 [Page 7]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
TITLE:Boss
TITLE;LANGUAGE=fr:Patron
...
END:VCARD
{
"@type": "Card",
...
"titles": {
"t1": {
"@type": "Title",
"title": "Boss"
}
},
"localizations": {
"fr": {
"titles/t1/title": "Patron"
}
}
}
Figure 1: LANGUAGE conversion example: patch existing property
Loffredo & Stepanek Expires 27 April 2023 [Page 8]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
TITLE;LANGUAGE=en:Boss
TITLE;LANGUAGE=fr:Patron
...
END:VCARD
{
"@type": "Card",
...
"localizations": {
"en": {
"titles": {
"t1": {
"@type": "Title",
"title": "Boss"
}
}
}
"fr": {
"titles": {
"t1": {
"@type": "Title",
"title": "Patron"
}
}
}
}
}
Figure 2: LANGUAGE conversion example: patch new property
2.3.2. VALUE
This does not convert to a standard property in JSContact. It is
implicit for standard types and conversion. For extended values, see
Section 2.15.2.
2.3.3. PREF
This converts to the pref property defined in Section 1.6.3 of
[I-D.ietf-calext-jscontact]
2.3.4. ALTID
This does not convert to a standard property in JSContact. To
convert this parameter, see Section 2.15.2.
Loffredo & Stepanek Expires 27 April 2023 [Page 9]
Internet-Draft jscontact-vcard October 2022
2.3.5. PID
This does not convert to a standard property in JSContact. To
convert this parameter, see Section 2.15.2.
2.3.6. TYPE
This converts to the contexts property defined in Section 1.6.1 of
[I-D.ietf-calext-jscontact] as well as property-specific type
property values defined in later sections.
2.3.7. MEDIATYPE
This converts to the mediaType property of the Resource object type.
2.3.8. CALSCALE
This parameter set on a BDAY or ANNIVERSARY property converts to the
calendarScale property of the PartialDate object type. To convert
this parameter for other vCard properties, see Section 2.15.2.
2.3.9. SORT-AS
This does not convert to a standard property in JSContact. To
convert this parameter, see Section 2.15.2.
2.3.10. GEO
This parameter set on a ADR property converts to the JSContact
coordinates property of the Address object that represents the vCard
ADR. To convert this parameter for other vCard properties, see
Section 2.15.2.
2.3.11. TZ
This parameter set on a ADR property converts to the JSContact
timeZone property of the Address object that represents the vCard
ADR. Also see the conversion of the TZ property in Section 2.8.1.
To convert this parameter for other vCard properties, see
Section 2.15.2.
2.3.12. DERIVED
If this parameter is set to true on a vCard property, then
implementations MAY choose to not convert that property. Note: This
parameter is defined in [I-D.ietf-calext-vcard-jscontact-extensions].
Loffredo & Stepanek Expires 27 April 2023 [Page 10]
Internet-Draft jscontact-vcard October 2022
2.3.13. PROP-ID
The PROP-ID parameter value of a vCard property converts to the Id of
the JSContact property to which the vCard property converts to.
BEGIN:VCARD
VERSION:4.0
...
TEL;PROP-ID=PHONE-A;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555
TEL;PROP-ID=PHONE-B;VALUE=uri;TYPE=home:tel:+33-01-23-45-67
...
END:VCARD
{
"@type": "Card",
...
"phones": {
"PHONE-A": {
"@type": "Phone",
"contexts": { "private": true },
"features": { "voice": true },
"phone": "tel:+1-555-555-5555;ext=5555",
"pref": 1
},
"PHONE-B": {
"@type": "Phone",
"contexts": { "private": true },
"phone": "tel:+33-01-23-45-67"
}
],
...
}
Figure 3: PROP-ID conversion example
Note: This parameter is defined in
[I-D.ietf-calext-vcard-jscontact-extensions].
2.4. General Properties
2.4.1. BEGIN and END
These do not convert to standard properties in JSContact.
Loffredo & Stepanek Expires 27 April 2023 [Page 11]
Internet-Draft jscontact-vcard October 2022
2.4.2. SOURCE
A SOURCE property converts to an entry in the directories property
(Figure 4). The entry value is a DirectoryResource object whose type
property is set to entry and uri property is set to the SOURCE value.
The PREF and MEDIATYPE parameters convert according to the rules as
defined in Section 2.3.
BEGIN:VCARD
VERSION:4.0
...
SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf
...
END:VCARD
{
"@type": "Card",
...
"directories": {
...
"ENTRY-1": {
"@type": "DirectoryResource",
"type": "entry",
"uri": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf"
},
...
},
...
}
Figure 4: SOURCE conversion example
2.4.3. KIND
The KIND property converts to the kind property (Figure 5). Allowed
values are those described in Section 6.1.4 of [RFC6350] and extended
with the values declared in [RFC6473] and [RFC6869]. The value group
is reserved for a CardGroup instance.
Loffredo & Stepanek Expires 27 April 2023 [Page 12]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
KIND:individual
...
END:VCARD
{
"@type": "Card",
...
"kind": "individual",
...
}
Figure 5: KIND conversion example
2.4.4. XML
This does not convert to a standard property in JSContact.
2.5. Identification Properties
2.5.1. FN
All the FN instances are represented through the fullName property
(Figure 6). The presence of multiple instances is implicitly
associated with the full name translation in various languages
regardless of the presence of the ALTID parameter. Each translation
converts according to the rules as defined in Section 2.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.5.2. N and NICKNAME
The N instances convert to equivalent items of the components array
of the name property (Figure 6): the N components convert into
related NameComponent objects as presented in Table 1. Name
componentsSHOULDbe ordered such that their values joined by
whitespace produce a valid full name of this entity.
Loffredo & Stepanek Expires 27 April 2023 [Page 13]
Internet-Draft jscontact-vcard October 2022
+====================+==============+
| N component | "type" value |
+====================+==============+
| Honorific Prefixes | prefix |
+--------------------+--------------+
| Given Names | personal |
+--------------------+--------------+
| Family Names | surname |
+--------------------+--------------+
| Additional Names | additional |
+--------------------+--------------+
| Honorific Suffixes | suffix |
+--------------------+--------------+
Table 1: N components conversion
A NICKNAME property converts to an entry in the nickNames property
(Figure 6). The entry value is a NickName object. The name property
is set to the NICKNAME value.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
Loffredo & Stepanek Expires 27 April 2023 [Page 14]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
FN:Mr. John Q. Public\, Esq.
N:Public;John;Quinlan;Mr.;Esq.
NICKNAME:Johnny
...
END:VCARD
{
"@type": "Card",
...
"fullName": "Mr. John Q. Public, Esq.",
"name": {
"@type": "Name",
"components":[
{ "@type": "NameComponent", "type": "prefix", "value": "Mr." },
{ "@type": "NameComponent", "type": "personal", "value": "John" },
{ "@type": "NameComponent", "type": "surname", "value": "Public" },
{ "@type": "NameComponent", "type": "additional", "value": "Quinlan" },
{ "@type": "NameComponent", "type": "suffix", "value": "Esq." }
]
},
"nickNames": {
"NICK-1": {
"@type": "NickName",
"name": "Johnny"
}
},
...
}
Figure 6: FN, N, NICKNAME conversion example
2.5.3. PHOTO
A PHOTO property converts to an entry in the media property
(Figure 7). The entry value is a MediaResource object whose type
property is set to photo and uri property is set to the PHOTO value.
The PREF and MEDIATYPE parameters convert according to the rules as
defined in Section 2.3.
Loffredo & Stepanek Expires 27 April 2023 [Page 15]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
PHOTO:http://www.example.com/pub/photos/jqpublic.gif
...
END:VCARD
{
"@type": "Card",
...
"media": {
...
"PHOTO-1": {
"@type": "MediaResource",
"type": "photo",
"uri": "http://www.example.com/pub/photos/jqpublic.gif"
},
...
},
...
}
Figure 7: PHOTO conversion example
2.5.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY
The BDAY and ANNIVERSARY properties and the extensions BIRTHPLACE,
DEATHDATE, DEATHPLACE described in [RFC6474] are represented as
Anniversary objects included in the anniversaries property
(Figure 8):
* BDAY and BIRTHPLACE convert to date and place where type is set to
"birth";
* DEATHDATE and DEATHPLACE convert to date and place where type is
set to "death";
* ANNIVERSARY converts to date where type is empty and label is set
to a value describing in detail the kind of anniversary (e.g.
"marriage date" for the wedding anniversary).
Both birth and death places are represented as instances of the
Address object.
The BIRTHPLACE and DEATHPLACE properties that are represented as geo
URIs convert to Address instances including only the coordinates
property. If the URI value is not a geo URI, the place is ignored.
The ALTID and LANGUAGE parameters of both BIRTHPLACE and DEATHPLACE
properties convert according to the rules as defined in Section 2.3.
Loffredo & Stepanek Expires 27 April 2023 [Page 16]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
BDAY:19531015T231000Z
BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A.
DEATHDATE:19960415
DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A.
ANNIVERSARY:19860201
...
END:VCARD
{
"@type": "Card",
...
"anniversaries": {
"ANNIVERSARY-1" : {
"@type": "Anniversary",
"type": "birth",
"date": "1953-10-15T23:10:00Z",
"place": {
"@type": "Address",
"fullAddress": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A."
}
},
"ANNIVERSARY-2" : {
"@type": "Anniversary",
"type": "death",
"date": "1996-04-15",
"place": {
"@type": "Address",
"fullAddress": "4445 Courtright Street\nNew England, ND 58647\nU.S.A."
}
},
"ANNIVERSARY-3" : {
"@type": "Anniversary",
"label": "marriage date",
"date": "1986-02-01"
}
},
...
}
Figure 8: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY
conversion example
Loffredo & Stepanek Expires 27 April 2023 [Page 17]
Internet-Draft jscontact-vcard October 2022
2.5.5. GENDER
This does not map to a standard property in JSContact. To convert
this property, see Section 2.15.1. Note the alternative JSContact
speakToAs property which defines how to address and refer to an
individual represented by the card, as do the newly defined vCard
GRAMMATICAL-GENDER and PRONOUNS properties of
[I-D.ietf-calext-vcard-jscontact-extensions].
2.5.6. GRAMMATICAL-GENDER and PRONOUNS
The GRAMMATICAL-GENDER property converts to the grammaticalGender
property of the SpeakToAs object (Figure 9).
The PRONOUNS property converts to an entry in the pronouns property
of the SpeakToAs object (Figure 9).
BEGIN:VCARD
VERSION:4.0
...
GRAMMATICAL-GENDER:NEUTER
PRONOUNS;PREF=2:they/them
PRONOUNS;PREF=1:xe/xir
...
END:VCARD
{
"@type": "Card",
...
"speakToAs": {
"grammaticalGender": "neuter",
"pronouns": {
"PRONOUNS-1": {
"@type": "Pronouns",
"pronouns": "they/them",
"pref": 2
},
"PRONOUNS-2": {
"@type": "Pronouns",
"pronouns": "xe/xir",
"pref": 1
}
}
},
...
}
Figure 9: GRAMMATICAL-GENDER and PRONOUNS conversion example
Loffredo & Stepanek Expires 27 April 2023 [Page 18]
Internet-Draft jscontact-vcard October 2022
2.6. Delivery Addressing Properties
2.6.1. ADR
An ADR property converts to an entry in the addresses property
(Figure 10). The entry value is an Address object.
The ADR components convert into the Address properties as presented
in Table 2 and Table 3.
The "street address" and "extended address" ADR components MAY be
converted into either a single StreetComponent item or a combination
of StreetComponent items.
+===============+================+
| ADR component | Address member |
+===============+================+
| locality | locality |
+---------------+----------------+
| region | region |
+---------------+----------------+
| postal code | postcode |
+---------------+----------------+
| country name | country |
+---------------+----------------+
Table 2: ADR components vs.
Address members conversion
+===============+======================+========================+
| ADR component | Single | Combination of |
| | StreetComponent item | StreetComponent items |
+===============+======================+========================+
| post office | postOfficeBox | |
| box | | |
+---------------+----------------------+------------------------+
| extended | extension | extension, building, |
| address | | floor, room, apartment |
+---------------+----------------------+------------------------+
| street | name | name, number, |
| address | | direction |
+---------------+----------------------+------------------------+
Table 3: ADR components vs. StreetComponent items conversion
The LABEL parameter converts to the fullAddress property.
The GEO parameter converts to the coordinates property.
Loffredo & Stepanek Expires 27 April 2023 [Page 19]
Internet-Draft jscontact-vcard October 2022
The TZ parameter converts to the timeZone property.
The CC parameter as defined in [RFC8605] converts to the countryCode
property.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
The ALTID and LANGUAGE parameters convert according to the rules as
defined in Section 2.3. Each possible language-dependent alternative
is represented as an entry of the PatchObject map where the key
references the fullAddress property.
Loffredo & Stepanek Expires 27 April 2023 [Page 20]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA
ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA
...
END:VCARD
{
"@type": "Card",
...
"addresses": {
"ADDR-1" : {
"@type": "Address",
"contexts": { "work": true },
"fullAddress": "54321 Oak St\nReston\nVA\n20190\nUSA",
"street": [
{ "@type": "StreetComponent", "type": "name", "value": "Oak St" },
{ "@type": "StreetComponent", "type": "number", "value": "54321" }
],
"locality": "Reston",
"region": "VA",
"country": "USA",
"postcode": "20190",
"countryCode": "US"
},
"ADDR-2": {
"@type": "Address",
"contexts": { "private": true },
"fullAddress": "12345 Elm St\nReston\nVA\n20190\nUSA",
"street": [
{ "@type": "StreetComponent", "type": "name", "value": "Elm St" },
{ "@type": "StreetComponent", "type": "number", "value": "12345" }
],
"locality": "Reston",
"region": "VA",
"country": "USA",
"postcode": "20190",
"countryCode": "US"
}
},
...
}
Figure 10: ADR conversion example
2.7. Communications Properties
Loffredo & Stepanek Expires 27 April 2023 [Page 21]
Internet-Draft jscontact-vcard October 2022
2.7.1. TEL
A TEL property converts to an entry in the phones property
(Figure 11). The entry value is a Phone object. The TEL-specific
values of the TYPE parameter convert to the features property keys.
The phone property is set to the TEL value.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
BEGIN:VCARD
VERSION:4.0
...
TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555
TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67
...
END:VCARD
{
"@type": "Card",
...
"phones": {
"PHONE-1": {
"@type": "Phone",
"contexts": { "private": true },
"features": { "voice": true },
"phone": "tel:+1-555-555-5555;ext=5555",
"pref": 1
},
"PHONE-2": {
"@type": "Phone",
"contexts": { "private": true },
"phone": "tel:+33-01-23-45-67"
}
],
...
}
Figure 11: TEL conversion example
2.7.2. EMAIL
An EMAIL property converts to an entry in the emails property
(Figure 12). The entry value is an EmailAddress object. The email
property is set to the EMAIL value.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
Loffredo & Stepanek Expires 27 April 2023 [Page 22]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
EMAIL;TYPE=work:jqpublic@xyz.example.com
EMAIL;PREF=1:jane_doe@example.com
...
END:VCARD
{
"@type": "Card",
...
"emails": {
"EMAIL-1": {
"@type": "EmailAddress",
"contexts": { "work": true },
"email": "jqpublic@xyz.example.com"
},
"EMAIL-2": {
"@type": "EmailAddress",
"email": "jane_doe@example.com",
"pref": 1
}
},
...
}
Figure 12: EMAIL conversion example
2.7.3. IMPP
An IMPP property converts to an entry in the onlineServices property
(Figure 13). The entry value is a OnlineService object and the uri
property is set to the IMPP value.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
Loffredo & Stepanek Expires 27 April 2023 [Page 23]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
IMPP;PREF=1:xmpp:alice@example.com
...
END:VCARD
{
"@type": "Card",
...
"onlineServices": {
...
"OS-1": {
"@type": "OnlineService",
"uri": "xmpp:alice@example.com",
"pref": 1
},
...
},
...
}
Figure 13: IMPP conversion example
2.7.4. LANG
A LANG property converts to an entry in the preferredContactLanguages
property (Figure 14). The entry keys correspond to the language
tags, the related entry values are arrays of ContactLanguage objects.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
If both PREF and TYPE parameters are missing, the array of
ContactLanguage objects MUST be empty.
Loffredo & Stepanek Expires 27 April 2023 [Page 24]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
LANG;TYPE=work;PREF=1:en
LANG;TYPE=work;PREF=2:fr
LANG;TYPE=home:fr
...
END:VCARD
{
"@type": "Card",
...
"preferredContactLanguages": {
"en":[
{
"@type": "ContactLanguage",
"contexts": { "work": true },
"pref": 1
}
],
"fr":[
{
"@type": "ContactLanguage",
"contexts": { "work": true },
"pref": 2
},
{
"@type": "ContactLanguage",
"contexts": { "private": true }
}
]
},
...
}
Figure 14: LANG conversion example
2.7.5. CONTACT-CHANNEL-PREF
A CONTACT-CHANNEL-PREF property converts to an entry in the
preferredContactChannels property (Figure 15). The entry key set is
defined in Table 4, the related entry values are arrays of
ContactChannelPreference objects.
Loffredo & Stepanek Expires 27 April 2023 [Page 25]
Internet-Draft jscontact-vcard October 2022
+============================+================================+
| CONTACT-CHANNEL-PREF value | "preferredContactChannels" key |
+============================+================================+
| ADR | addresses |
+----------------------------+--------------------------------+
| EMAIL | emails |
+----------------------------+--------------------------------+
| IMPP | onlineServices |
+----------------------------+--------------------------------+
| TEL | phones |
+----------------------------+--------------------------------+
Table 4: CONTACT-CHANNEL-PREF values conversion
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
If both PREF and TYPE parameters are missing, the array of
ContactChannelPreference objects MUST be empty.
BEGIN:VCARD
VERSION:4.0
...
CONTACT-CHANNEL-PREF;PREF=1:EMAIL
CONTACT-CHANNEL-PREF;PREF=2:TEL
...
END:VCARD
{
"@type": "Card",
...
"preferredContactChannels": {
"emails":[
{
"@type": "ContactChannelPreference",
"pref": 1
}
],
"phones":[
{
"@type": "ContactChannelPreference",
"pref": 2
}
]
},
...
}
Loffredo & Stepanek Expires 27 April 2023 [Page 26]
Internet-Draft jscontact-vcard October 2022
Figure 15: LANG conversion example
Note: This property is defined in
[I-D.ietf-calext-vcard-jscontact-extensions].
2.7.6. LOCALE
The LOCALE property converts to the locale property (Figure 16).
BEGIN:VCARD
VERSION:4.0
...
LOCALE:de-AT
...
END:VCARD
{
"@type": "Card",
...
"locale": "de-AT",
...
}
Figure 16: LOCALE conversion example
Note: This property is defined in
[I-D.ietf-calext-vcard-jscontact-extensions].
2.8. Geographical Properties
2.8.1. TZ
A value of type TEXT converts to the timeZone property in the Address
object.
A value of type UTC-OFFSET converts to the timeZone property in the
Address object if the offset has zero minutes and the hour offset is
in the range -12 <= 14:
* If the hour offset is zero, use the time zone name Etc/UTC.
* Otherwise construct the time zone name with ETC/GMT suffixed with
the string representation of the reversed sign hour offset,
including the sign but excluding leading zeros and minutes. For
example, the UTC offset value -0500 converts to ETC/GMT+5.
For such property values, also see Section 2.8.3 to determine which
Address object instance to convert to.
Loffredo & Stepanek Expires 27 April 2023 [Page 27]
Internet-Draft jscontact-vcard October 2022
Any other value of type UTC-OFFSET or URI does not convert to a
standard property in JSContact. To convert such property, see
Section 2.15.1.
2.8.2. GEO
This converts to the coordinates property of the Address object.
Also see Section 2.8.3 to determine which Address object instance to
convert to.
2.8.3. Combining geographical properties
In vCard the properties ADR, GEO and TZ occur independently of each
other. In JSContact, they all convert to properties of an Address
object. It is implementation-specific if these vCard properties
convert to _separate_ address instances in JSContact, or if some or
all of them convert to the _same_ address. That being said,
implementations SHOULD convert the properties to the _same_ address
for the following cases:
* The ALTID parameter values of the properties match.
* The ALTID parameters are not set, but are set on any other ADR,
GEO and TZ properties.
2.9. Organizational Properties
2.9.1. TITLE and ROLE
Both TITLE and ROLE properties are represented as entries of the
titles property (Figure 17). The entry value is a Title object whose
type property is set to "title"/"role" and title property is set to
the TITLE/ROLE value. The rules to set the organization property are
out of the scope of this document.
The ALTID and LANGUAGE parameters convert according to the rules as
defined in Section 2.3.
Loffredo & Stepanek Expires 27 April 2023 [Page 28]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
TITLE:Research Scientist
ROLE:Project Leader
...
END:VCARD
{
"@type": "Card",
...
"titles": {
"TITLE-1": {
"@type": "Title",
"type": "title",
"title": "Project Leader"
},
"TITLE-2": {
"@type": "Title",
"type": "role",
"title": "Research Scientist"
}
},
...
}
Figure 17: TITLE and ROLE conversion example
2.9.2. LOGO
A LOGO property converts to an entry in the media property
(Figure 18). The entry value is a MediaResource object whose type
property is set to logo and uri property is set to the LOGO value.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
Loffredo & Stepanek Expires 27 April 2023 [Page 29]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
LOGO:http://www.example.com/pub/logos/abccorp.jpg
...
END:VCARD
{
"@type": "Card",
...
"media": {
...
"LOGO-1": {
"@type": "MediaResource",
"type": "logo",
"uri": "http://www.example.com/pub/logos/abccorp.jpg"
},
...
},
...
}
Figure 18: LOGO conversion example
2.9.3. ORG
An ORG property converts to an entry in the organizations property
(Figure 19). The entry value is an Organization object whose name
property contains the organizational name and the units property
contains the organizational units.
Implementations MAY allow to represent organizational untits without
the organizational name. In this case, the first component of the
ORG value MUST be an empty string (e.g. ORG:;DepartmentA).
The ALTID and LANGUAGE parameters convert according to the rules as
defined in Section 2.3.
Loffredo & Stepanek Expires 27 April 2023 [Page 30]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
ORG:ABC\, Inc.;North American Division;Marketing
...
END:VCARD
{
"@type": "Card",
...
"organizations": {
"ORG-1": {
"@type": "Organization",
"name": "ABC, Inc.",
"units":[
"North American Division",
"Marketing"
]
}
},
...
}
Figure 19: ORG conversion example
2.9.4. MEMBER
According to the JSContact specification, a group of contact cards is
represented through a CardGroup (Figure 20). The uids of the contact
cards composing the group are included in the members property.
In this case, the PREF parameter has not a JSContact counterpart;
however, the implementers MAY insert the map entries by order of
preference.
Loffredo & Stepanek Expires 27 April 2023 [Page 31]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
KIND:group
FN:The Doe family
MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af
MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519
END:VCARD
{
"@type": "CardGroup",
"kind": "group",
"fullName": "The Doe family",
"uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667",
"members": {
"urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true,
"urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true
}
}
Figure 20: Group example
Only if the GROUP contains properties that don't have a conversion to
CardGroup properties, then the CardGroup.card property MAY contain
the optional Card object of this group.
{
"@type": "CardGroup",
"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": {
"@type": "Card",
"fullName": "The Doe family",
"uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667",
"photos": {
"PHOTO-1": {
"@type": "File",
"href": "http://www.example.com/pub/photos/jqpublic.gif"
}
}
}
}
Figure 21: card member of CardGroup object
Loffredo & Stepanek Expires 27 April 2023 [Page 32]
Internet-Draft jscontact-vcard October 2022
2.9.5. RELATED
All the RELATED instances convert to the relatedTo property
(Figure 22): an entry for each entity the entity described by the
Card is associated with. The map keys are the uid values of the
associated cards.
Each map value is a Relation object including only the relation
property represented as a set of the RELATED-specific values of the
TYPE parameter as defined in Section 6.6.6 of [RFC6350].
If the relation type is unspecified, the relation property MUST be
empty.
BEGIN:VCARD
VERSION:4.0
...
RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf
RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries.
...
END:VCARD
{
"@type": "Card",
...
"relatedTo": {
{
"@type": "Relation",
"urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6": {
"relation": { "friend": true }
}
},
{
"@type": "Relation",
"http://example.com/directory/jdoe.vcf": {
"relation": { "contact": true }
}
},
{
"@type": "Relation",
"Please contact my assistant Jane Doe for any inquiries.": {
"relation": { }
}
}
},
...
}
Loffredo & Stepanek Expires 27 April 2023 [Page 33]
Internet-Draft jscontact-vcard October 2022
Figure 22: RELATED conversion example
2.9.6. CONTACT-URI
A CONTACT-URI property as defined in [RFC8605] is represented as an
entry of the links property (Figure 23). The entry value is a
LinkResource object whose type property is set to contact and uri
property is set to the CONTACT-URI value.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
BEGIN:VCARD
VERSION:4.0
...
CONTACT-URI;PREF=1:mailto:contact@example.com
...
END:VCARD
{
"@type": "Card",
...
"links": {
...
"CONTACT-1": {
"@type": "LinkResource",
"type": "contact",
"uri": "mailto:contact@example.com",
"pref": 1
},
...
},
...
}
Figure 23: CONTACT-URI conversion example
2.10. Personal Information Properties
The LEVEL parameter as defined in [RFC6715] is directly converted to
the level property of the PersonalInformation type apart from when
LEVEL is used in the EXPERTISE property; in this case, the values
convert as in the following:
* "beginner" converts to "low";
* "average" converts to "medium";
* "expert" converts to "high".
Loffredo & Stepanek Expires 27 April 2023 [Page 34]
Internet-Draft jscontact-vcard October 2022
2.10.1. EXPERTISE
An EXPERTISE property as defined in [RFC6715] is represented as a
PersonalInformation object in the personalInfo property (Figure 24).
The type property is set to "expertise".
The INDEX parameter is represented as the index of the expertise
among the declared expertises.
BEGIN:VCARD
VERSION:4.0
...
EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature
EXPERTISE;INDEX=1;LEVEL=expert:chemistry
...
END:VCARD
{
"@type": "Card",
...
"personalInfo": {
...
"PERSINFO-1" : {
"@type": "PersonalInformation",
"type": "expertise",
"value": "chemistry",
"level": "high"
},
"PERSINFO-2" : {
"@type": "PersonalInformation",
"type": "expertise",
"value": "chinese literature",
"level": "low"
},
...
},
...
}
Figure 24: EXPERTISE conversion example
2.10.2. HOBBY
A HOBBY property as defined in [RFC6715] is represented as a
PersonalInformation object in the personalInfo property (Figure 25).
The type property is set to "hobby".
Loffredo & Stepanek Expires 27 April 2023 [Page 35]
Internet-Draft jscontact-vcard October 2022
The INDEX parameter is represented as the index of the hobby among
the declared hobbies.
BEGIN:VCARD
VERSION:4.0
...
HOBBY;INDEX=1;LEVEL=high:reading
HOBBY;INDEX=2;LEVEL=high:sewing
...
END:VCARD
{
"@type": "Card",
...
"personalInfo": {
...
"PERSINFO-1" : {
"@type": "PersonalInformation",
"type": "hobby",
"value": "reading",
"level": "high"
},
"PERSINFO-2" : {
"@type": "PersonalInformation",
"type": "hobby",
"value": "sewing",
"level": "high"
},
...
},
...
}
Figure 25: HOBBY conversion example
2.10.3. INTEREST
An INTEREST property as defined in [RFC6715] is represented as a
PersonalInformation object in the personalInfo property (Figure 26).
The type property is set to "interest".
The INDEX parameter is represented as the index of the interest among
the declared interests.
Loffredo & Stepanek Expires 27 April 2023 [Page 36]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
INTEREST;INDEX=1;LEVEL=medium:r&b music
INTEREST;INDEX=2;LEVEL=high:rock ’n’ roll music
...
END:VCARD
{
"@type": "Card",
...
"personalInfo": {
...
"PERSINFO-1" : {
"@type": "PersonalInformation",
"type": "interest",
"value": "r&b music",
"level": "medium"
},
"PERSINFO-2" : {
"@type": "PersonalInformation",
"type": "interest",
"value": "rock ’n’ roll music",
"level": "high"
},
...
},
...
}
Figure 26: INTEREST conversion example
2.10.4. ORG-DIRECTORY
An ORG-DIRECTORY property as defined in [RFC6715] is represented as
an entry of the directories property (Figure 27). The entry value is
a DirectoryResource object whose type property is set to directory
and uri property is set to the ORG-DIRECTORY value.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
The INDEX parameter is represented as the index of the directory
among the online resources with the directory type.
Loffredo & Stepanek Expires 27 April 2023 [Page 37]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com
ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering
...
END:VCARD
{
...
"directories": {
"@type": "Card",
...
"DIRECTORY-1": {
"@type": "DirectoryResource",
"type": "directory",
"uri": "http://directory.mycompany.example.com"
},
"DIRECTORY-2": {
"@type": "DirectoryResource",
"type": "directory",
"uri": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering",
"pref": 1
},
...
},
...
}
Figure 27: ORG-DIRECTORY conversion example
2.11. Explanatory Properties
2.11.1. CATEGORIES
A CATEGORIES property converts to a set of entries of the keywords
property (Figure 28). The keys are the comma-separated text values
of the CATEGORIES property.
In this case, the PREF parameter has not a JSContact counterpart;
however, the implementers MAY insert the map entries by order of
preference.
Loffredo & Stepanek Expires 27 April 2023 [Page 38]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY
...
END:VCARD
{
"@type": "Card",
...
"keywords": {
"INTERNET": true,
"IETF": true,
"INDUSTRY": true,
"INFORMATION TECHNOLOGY": true
},
...
}
Figure 28: CATEGORIES conversion example
2.11.2. NOTE
A NOTE property converts to a Note object in the notes array
(Figure 29)
The ALTID and LANGUAGE parameters convert according to the rules as
defined in Section 2.3.
BEGIN:VCARD
VERSION:4.0
...
NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri.
...
END:VCARD
{
"@type": "Card",
...
"notes": [
{
"note": "This fax number is operational 0800 to 1715 EST, Mon-Fri."
}
],
...
}
Figure 29: NOTE conversion example
Loffredo & Stepanek Expires 27 April 2023 [Page 39]
Internet-Draft jscontact-vcard October 2022
2.11.3. PRODID
The PRODID property converts to the prodId property (Figure 30).
BEGIN:VCARD
VERSION:4.0
...
PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN
...
END:VCARD
{
"@type": "Card",
...
"prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN",
...
}
Figure 30: PRODID conversion example
2.11.4. REV
The REV property converts to the updated property (Figure 31).
BEGIN:VCARD
VERSION:4.0
...
REV:19951031T222710Z
...
END:VCARD
{
"@type": "Card",
...
"updated": "1995-10-31T22:27:10Z",
...
}
Figure 31: REV conversion example
2.11.5. SOUND
A SOUND property converts to an entry in the media property
(Figure 32). The entry value is a MediaResource object whose type
property is set to sound and uri property is set to the SOUND value.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
Loffredo & Stepanek Expires 27 April 2023 [Page 40]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com
...
END:VCARD
{
"@type": "Card",
...
"media": {
...
"SOUND-1": {
"@type": "MediaResource",
"type": "sound",
"uri": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com"
},
...
},
...
}
Figure 32: SOUND conversion example
2.11.6. UID
The UID property corresponds to the uid property (Figure 33) in both
Card and CardGroup.
BEGIN:VCARD
VERSION:4.0
...
UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
...
END:VCARD
{
"@type": "Card",
...
"uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
...
}
Figure 33: UID conversion example
Loffredo & Stepanek Expires 27 April 2023 [Page 41]
Internet-Draft jscontact-vcard October 2022
2.11.7. CLIENTPIDMAP and PID Parameter
The CLIENTPIDMAP property and the PDI parameter don't have a direct
match with a Card feature.
2.11.8. URL
An URL property converts to an entry in the links property
(Figure 34). The entry value is a LinkResource object whose uri
property is set to the URL value.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
BEGIN:VCARD
VERSION:4.0
...
URL:http://example.org/restaurant.french/~chezchic.html
...
END:VCARD
{
"@type": "Card",
...
"links": {
...
"LINK-1": {
"@type": "LinkResource",
"uri": "http://example.org/restaurant.french/~chezchic.html"
},
...
},
...
}
Figure 34: URL conversion example
2.11.9. VERSION
The VERSION property doesn't have a direct match with a JSContact
feature.
2.11.10. CREATED
The CREATED property converts to the created property (Figure 35).
Loffredo & Stepanek Expires 27 April 2023 [Page 42]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
CREATED:19940930T143510Z
...
END:VCARD
{
"@type": "Card",
...
"created": "1994-09-30T14:35:10Z",
...
}
Figure 35: CREATED conversion example
Note: This property is defined in
[I-D.ietf-calext-vcard-jscontact-extensions].
2.11.11. X-ABLabel
This property is non-standard but widely in use in existing vCard
data. It converts to the label property of a JSContact object type.
The X-ABLabel property is preceded by a vCard property group name,
and the label converts to the JSContact object which got converted
from a vCard property having the same group.
BEGIN:VCARD
VERSION:4.0
...
item1.TEL;VALUE=uri:tel:+1-555-555-5555
item1.X-ABLabel:foo
...
END:VCARD
{
"@type": "Card",
...
"phones": {
"p1": {
"@type": "Phone",
"phone": "tel:+1-555-555-5555",
"label": "foo"
}
}
...
}
Loffredo & Stepanek Expires 27 April 2023 [Page 43]
Internet-Draft jscontact-vcard October 2022
Figure 36: X-ABLabel conversion example
2.12. Security Properties
2.12.1. KEY
A KEY property converts to an entry in the cryptoKeys property
(Figure 37). The entry value is a CryptoResource object whose uri
property is set to the KEY value.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
BEGIN:VCARD
VERSION:4.0
...
KEY:http://www.example.com/keys/jdoe.cer
...
END:VCARD
{
"@type": "Card",
...
"cryptoKeys": {
...
"KEY-1": {
"@type": "CryptoResource",
"uri": "http://www.example.com/keys/jdoe.cer"
},
...
},
...
}
Figure 37: KEY conversion example
2.13. Calendar Properties
2.13.1. FBURL
An FBURL property converts to an entry in the calendars property
(Figure 38). The entry value is a CalendarResource object whose type
property is set to freeBusy and uri property is set to the FBURL
value.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
Loffredo & Stepanek Expires 27 April 2023 [Page 44]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
FBURL;PREF=1:http://www.example.com/busy/janedoe
FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb
...
END:VCARD
{
"@type": "Card",
...
"calendars": {
...
"FBURL-1": {
"@type": "CalendarResource",
"type": "freeBusy",
"uri": "http://www.example.com/busy/janedoe",
"pref": 1
},
"FBURL-2": {
"@type": "CalendarResource",
"type": "freeBusy",
"uri": "ftp://example.com/busy/project-a.ifb",
"mediaType": "text/calendar"
},
...
},
...
}
Figure 38: FBURL conversion example
2.13.2. CALADRURI
A CALADRURI property converts to an entry in the scheduling property
(Figure 39). The entry value is a Scheduling object whose sendTo
property includes an entry whose key is set to imip and value is set
to the CALADRURI value.
The PREF parameter converts according to the rules as defined in
Section 2.3.
Loffredo & Stepanek Expires 27 April 2023 [Page 45]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
CALADRURI;PREF=1:mailto:janedoe@example.com
CALADRURI:http://example.com/calendar/jdoe
...
END:VCARD
{
"@type": "Card",
...
"scheduling": {
...
"SCHEDULING-1": {
"@type": "Scheduling",
"sendTo": {
"imip": "mailto:janedoe@example.com"
},
"pref": 1
},
"SCHEDULING-2": {
"@type": "Scheduling",
"sendTo": {
"imip": "http://example.com/calendar/jdoe"
}
},
...
},
...
}
Figure 39: CALADRURI conversion example
2.13.3. CALURI
A CALURI property converts to an entry in the calendars property
(Figure 40). The entry value is a CalendarResource object whose type
property is set to calendar and uri property is set to the CALURI
value.
The PREF and TYPE parameters convert according to the rules as
defined in Section 2.3.
Loffredo & Stepanek Expires 27 April 2023 [Page 46]
Internet-Draft jscontact-vcard October 2022
BEGIN:VCARD
VERSION:4.0
...
CALURI;PREF=1:http://cal.example.com/calA
CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics
...
END:VCARD
{
"@type": "Card",
...
"calendars": {
...
"CAL-1": {
"@type": "CalendarResource",
"type": "calendar",
"uri": "http://cal.example.com/calA",
"pref": 1
},
"CAL-2": {
"@type": "CalendarResource",
"type": "calendar",
"uri": "ftp://ftp.example.com/calA.ics",
"mediaType": "text/calendar"
},
...
},
...
}
Figure 40: CALURI conversion example
2.14. Extended Properties and Parameters
These convert as specified in Section 2.15.
2.15. New JSContact properties
vCards may contain properties or parameters for which no standard
JSContact property is defined. For example, a vCard may contain
extended properties and parameters of which the semantics or purpose
are unknown Section 6.10 of [RFC6350].
This section defines JSContact extension properties by which such
vCard properties and parameters MAY be represented in JSContact.
Implementations MAY choose to convert differently if they deem that
more appropriate.
Loffredo & Stepanek Expires 27 April 2023 [Page 47]
Internet-Draft jscontact-vcard October 2022
2.15.1. Property props
Name: ietf.org:rfc0000:props
Type: JCardProp[], where JCardProp denotes a jCard-encoded vCard
property as defined in Section 3.3 of [RFC7095].
Definition: This property is set on a JSContact object that
represents a vCard. It contains properties that are set in the
vCard represented by this JSContact object. Each entry in this
list typically represents a vCard property for which no conversion
to a standard JSContact property is defined. It MAY contain vCard
standard properties which also got converted to a standard
property in the same JSContact object. In case of conflict, the
values of the JSContact property MUST be used.
Example: This illustrates how to convert a vCard extension property:
BEGIN:VCARD
VERSION:4.0
...
item1.X-FOO;X-BAR=Hello:World!
...
END:VCARD
{
"@type": "Card",
...
"ietf:rfc0000:props": [
["x-foo", {
"x-bar": "Hello",
"group": "item1"
}, "unknown", "World!"]
]
...
}
Figure 41: JSContact props example
2.15.2. Property params
Name: ietf.org:rfc0000:params
Type: String[String|String[]]
Definition: This property is set on a JSContact object that
Loffredo & Stepanek Expires 27 April 2023 [Page 48]
Internet-Draft jscontact-vcard October 2022
represents a vCard property. Its value MUST be a JSON object
containing vCard property parameters, defined as array element 2
in Section 3.3 of [RFC7095]. Each entry represents a parameter of
the vCard property that converts to the JSContact object.
Typically, these are parameters for which no standard property is
defined in the JSContact object. It MAY contain vCard standard
parameters which also got converted to a standard property in the
same JSContact object. In case of conflict, the values of the
JSContact property MUST be used.
Example:
EMAIL;X-FOO=Bar:jane_doe@example.com
converts to
"emails": {
"email1": {
"@type": "EmailAddress",
"email": "jane_doe@example.com",
"ietf.org:rfc0000:params": {
"x-foo": "Bar"
}
}
}
3. Converting JSContact to vCard
3.1. Conversion Rules
A Card or CardGroup converts to vCard by applying the reserve rules
of section Section 2. The following additional rules apply:
* Multi-valued JSContact properties convert to separate instances of
the same vCard property, and for each the PROP-ID parameter MUST
be set to the Id of the converted value (see Section 2.3.13).
* The fullName property in JSContact is optional, but it is
mandatory in vCard. If the fullName is not set but the name
property is, then implementations MAY derive the value of the FN
property from it. In this case, they MUST the DERIVED parameter
on the FN property. Otherwise they MUST set the FN property with
an empty value.
* Vendor-extension and unknown properties convert to vCard as
outlined in section Section 3.2.
Loffredo & Stepanek Expires 27 April 2023 [Page 49]
Internet-Draft jscontact-vcard October 2022
3.2. New vCard Properties and Parameters
JSContact objects and their embedded object types may contain
properties for which no standard vCard property is defined. For
example, a JSContact object may contain extended properties of which
the semantics or purpose is unknown Section 1.5.2 of
[I-D.ietf-calext-jscontact].
This section defines an vCard extension property and parameter by
which such JSContact properties MAY be represented in JSContact.
Implementations MAY choose to convert differently if they deem that
more appropriate.
3.2.1. Property JSPROP
Property name: X-RFC0000-JSPROP
Purpose: This property represents a JSContact property in vCard.
Value type: URI, also see Format Definition for value restrictions.
Conformance: The property can be specified multiple times in a
vCard.
Property parameters: The X-RFC0000-JSPATH parameter MUST be set
exactly once for this property. The VALUE parameter MAY be set
once, in which case its value MUST be URI. Other IANA and non-
standard property parameters can be specified on this property.
Description: This property converts a JSContact property to
iCalendar. The property name is defined using the
X-RFC0000-JSPATH parameter (Section 3.2.2). A JSContact property
value is represented as a data URL using the data scheme
[RFC2397]. The mediatype part of the URL MUST be application/json
and MUST NOT define parameters. The data part of the URL contains
the value of the JSContact property. The value MAY
base64-encoded, in which case the data URL MUST set the base64
part accordingly.
Format definition: This property is defined by the following
notation:
Loffredo & Stepanek Expires 27 April 2023 [Page 50]
Internet-Draft jscontact-vcard October 2022
jsprop = "X-RFC0000-JSPROP" jsprop-param ":" jsprop-value CRLF
jsprop-value = "data:application/json" [";base64"] "," data
; data is defined in RFC 2397, section 3
jsprop-param = *(
; The following is MANDATORY and MUST NOT
; occur more than once
jspath-param /
;
; The following is OPTIONAL,
; but MUST NOT occur more than once.
;
(";" "VALUE" "=" "URI" ) /
;
; The following is OPTIONAL,
; and MAY occur more than once.
;
(";" other-param)
;
)
Example(s): This illustrates how to convert both complex and simple
typed JSContact properties.
{
"@type": "Card",
...
"foo": {
"bar": 1234
}
}
BEGIN:VCARD
VERSION:4.0
...
X-RFC0000-JSPROP;X-RFC0000-JSPATH="foo":
data:application/json;base64,eyJiYXIiOiAxMjM0fQo=
...
END:VCARD
Figure 42: JSON object value conversion example
Loffredo & Stepanek Expires 27 April 2023 [Page 51]
Internet-Draft jscontact-vcard October 2022
{
"@type": "Card",
...
"foo": true
}
BEGIN:VCARD
VERSION:4.0
...
X-RFC0000-JSPROP;X-RFC0000-JSPATH="foo":
data:application/json;true
...
END:VCARD
Figure 43: JSON boolean value conversion example
3.2.2. Parameter JSPATH
Parameter name: X-RFC0000-JSPATH
Purpose: This parameter defines the name of a JSContact property
that got converted to a vCard property. It is encoded as a
PatchObject pointer as defined in Section 1.5.3 of
[I-D.ietf-calext-jscontact]
Format definition:
jspath-param = "X-RFC0000-JSPATH" "=" DQUOTE *QSAFE-CHAR DQUOTE
; also see param-value in RFC 6350, section 3.3
Description: This parameter is set on a X-RFC0000-JSPROP or
X-RFC0000-PROP property. Its value defines the name of the
JSContact property that got converted to this vCard property. The
parameter value contains the JSON pointer of the JSContact
property. It MUST be quoted to preserve case.
Example(s):
X-RFC0000-PROP;X-RFC0000-JSPATH="fooBar":baz
4. IANA Considerations
This document has no actions for IANA.
5. Implementation Status
NOTE: Please remove this section and the reference to RFC 7942 prior
to publication as an RFC.
Loffredo & Stepanek Expires 27 April 2023 [Page 52]
Internet-Draft jscontact-vcard October 2022
This section records the status of known implementations of the
protocol as defined in this specification at the time of posting of
this Internet-Draft, and is based on a proposal described in
[RFC7942]. The description of implementations in this section is
intended to assist the IETF in its decision processes in progressing
drafts to RFCs. Please note that the listing of any individual
implementation here does not imply endorsement by the IETF.
Furthermore, no effort has been spent to verify the information
presented here that was supplied by IETF contributors. This is not
intended as, and must not be construed to be, a catalog of available
implementations or their features. Readers are advised to note that
other implementations may exist.
According to RFC 7942, "this will allow reviewers and working groups
to assign due considerationto documents that have the benefit of
running code, which may serve as evidence of valuable experimentation
and feedback that have made the implemented protocols more mature.
It is up to the individual working groups to use this information as
they see fit".
5.1. CNR
* Responsible Organization: National Research Council (CNR) of Italy
* Location: https://github.com/consiglionazionaledellericerche/
jscontact-tools
* Description: This implementation includes tools for JSContact
creation, validation, serialization/deserialization, and
conversion from vCard, xCard and jCard.
* Level of Maturity: This is an "alpha" test implementation.
* Coverage: This implementation includes all of the features
described in this specification.
* Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it
6. Security Considerations
This document doesn't present any security consideration.
7. References
7.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
Loffredo & Stepanek Expires 27 April 2023 [Page 53]
Internet-Draft jscontact-vcard October 2022
[RFC2397] Masinter, L., "The "data" URL scheme", RFC 2397,
DOI 10.17487/RFC2397, August 1998,
<https://www.rfc-editor.org/info/rfc2397>.
[RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
DOI 10.17487/RFC6350, August 2011,
<https://www.rfc-editor.org/info/rfc6350>.
[RFC6473] Saint-Andre, P., "vCard KIND:application", RFC 6473,
DOI 10.17487/RFC6473, December 2011,
<https://www.rfc-editor.org/info/rfc6473>.
[RFC6474] Li, K. and B. Leiba, "vCard Format Extensions: Place of
Birth, Place and Date of Death", RFC 6474,
DOI 10.17487/RFC6474, December 2011,
<https://www.rfc-editor.org/info/rfc6474>.
[RFC6715] Cauchie, D., Leiba, B., and K. Li, "vCard Format
Extensions: Representing vCard Extensions Defined by the
Open Mobile Alliance (OMA) Converged Address Book (CAB)
Group", RFC 6715, DOI 10.17487/RFC6715, August 2012,
<https://www.rfc-editor.org/info/rfc6715>.
[RFC6869] Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard
KIND:device", RFC 6869, DOI 10.17487/RFC6869, February
2013, <https://www.rfc-editor.org/info/rfc6869>.
[RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095,
DOI 10.17487/RFC7095, January 2014,
<https://www.rfc-editor.org/info/rfc7095>.
[RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running
Code: The Implementation Status Section", BCP 205,
RFC 7942, DOI 10.17487/RFC7942, July 2016,
<https://www.rfc-editor.org/info/rfc7942>.
7.2. Informative References
[I-D.ietf-calext-jscontact]
Stepanek, R. and M. Loffredo, "JSContact: A JSON
representation of contact data", Work in Progress,
Internet-Draft, draft-ietf-calext-jscontact-04, 24 October
2022, <https://datatracker.ietf.org/doc/html/draft-ietf-
calext-jscontact-04>.
[I-D.ietf-calext-vcard-jscontact-extensions]
Stepanek, R. and M. Loffredo, "vCard Format Extension for
JSContact", Work in Progress, Internet-Draft, draft-ietf-
Loffredo & Stepanek Expires 27 April 2023 [Page 54]
Internet-Draft jscontact-vcard October 2022
calext-vcard-jscontact-extensions-00, 11 July 2022,
<https://datatracker.ietf.org/doc/html/draft-ietf-calext-
vcard-jscontact-extensions-00>.
[RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions:
ICANN Extensions for the Registration Data Access Protocol
(RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019,
<https://www.rfc-editor.org/info/rfc8605>.
Authors' Addresses
Mario Loffredo
IIT-CNR/Registro.it
Via Moruzzi,1
56124 Pisa
Italy
Email: mario.loffredo@iit.cnr.it
URI: http://www.iit.cnr.it
Robert Stepanek
FastMail
PO Box 234, Collins St West
Melbourne VIC 8007
Australia
Email: rsto@fastmailteam.com
URI: https://www.fastmail.com
Loffredo & Stepanek Expires 27 April 2023 [Page 55]