Internet-Draft | jscontact-vcard | October 2022 |
Loffredo & Stepanek | Expires 27 April 2023 | [Page] |
This document defines how to convert contact information defined in the JSContact specification from and to vCard.¶
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.¶
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 (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 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.¶
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).¶
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.¶
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.¶
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.¶
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:¶
KIND
property, or the value of this property is anything but group
then convert it to a Card
object.¶
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
.¶
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.¶
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 Id
s or only unique within one JSON object.¶
This converts to the JSContact String
type.¶
This converts to the JSContact String
type.¶
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.¶
This converts to the JSContact Boolean
type.¶
This converts to the JSContact Number
type.¶
This converts to the JSContact Int
and UnsignedInt
types.¶
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.¶
This converts to the JSContact String
type.¶
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.¶
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" } } }
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" } } } } }
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.¶
This converts to the pref
property defined in Section 1.6.3 of [I-D.ietf-calext-jscontact]¶
This does not convert to a standard property in JSContact. To convert this parameter, see Section 2.15.2.¶
This does not convert to a standard property in JSContact. To convert this parameter, see Section 2.15.2.¶
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.¶
This converts to the mediaType
property of the Resource
object type.¶
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.¶
This does not convert to a standard property in JSContact. To convert this parameter, see Section 2.15.2.¶
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.¶
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.¶
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].¶
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" } ], ... }
Note: This parameter is defined in [I-D.ietf-calext-vcard-jscontact-extensions].¶
These do not convert to standard properties in JSContact.¶
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" }, ... }, ... }
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.¶
BEGIN:VCARD VERSION:4.0 ... KIND:individual ... END:VCARD { "@type": "Card", ... "kind": "individual", ... }
This does not convert to a standard property in JSContact.¶
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.¶
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.¶
N component | "type" value |
---|---|
Honorific Prefixes | prefix |
Given Names | personal |
Family Names | surname |
Additional Names | additional |
Honorific Suffixes | suffix |
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.¶
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" } }, ... }
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.¶
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" }, ... }, ... }
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";¶
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.¶
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" } }, ... }
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].¶
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 } } }, ... }
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 |
ADR component | Single StreetComponent item | Combination of StreetComponent items |
---|---|---|
post office box | postOfficeBox | |
extended address | extension | extension, building, floor, room, apartment |
street address | name | name, number, direction |
The LABEL parameter converts to the fullAddress
property.¶
The GEO parameter converts to the coordinates
property.¶
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.¶
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" } }, ... }
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" } ], ... }
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.¶
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 } }, ... }
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.¶
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 }, ... }, ... }
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.¶
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 } } ] }, ... }
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.¶
CONTACT-CHANNEL-PREF value | "preferredContactChannels" key |
---|---|
ADR | addresses |
emails | |
IMPP | onlineServices |
TEL | phones |
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 } ] }, ... }
Note: This property is defined in [I-D.ietf-calext-vcard-jscontact-extensions].¶
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", ... }
Note: This property is defined in [I-D.ietf-calext-vcard-jscontact-extensions].¶
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:¶
Etc/UTC
.¶
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.¶
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.¶
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.¶
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:¶
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.¶
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" } }, ... }
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.¶
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" }, ... }, ... }
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.¶
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" ] } }, ... }
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.¶
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 } }
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" } } } }
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.¶
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 }, ... }, ... }
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:¶
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" }, ... }, ... }
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".¶
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" }, ... }, ... }
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.¶
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" }, ... }, ... }
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.¶
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 }, ... }, ... }
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.¶
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 }, ... }
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." } ], ... }
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", ... }
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", ... }
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.¶
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" }, ... }, ... }
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", ... }
The CLIENTPIDMAP property and the PDI parameter don't have a direct match with a Card feature.¶
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" }, ... }, ... }
The VERSION property doesn't have a direct match with a JSContact feature.¶
The CREATED property converts to the created
property (Figure 35).¶
BEGIN:VCARD VERSION:4.0 ... CREATED:19940930T143510Z ... END:VCARD { "@type": "Card", ... "created": "1994-09-30T14:35:10Z", ... }
Note: This property is defined in [I-D.ietf-calext-vcard-jscontact-extensions].¶
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" } } ... }
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" }, ... }, ... }
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.¶
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" }, ... }, ... }
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.¶
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" } }, ... }, ... }
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.¶
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" }, ... }, ... }
These convert as specified in Section 2.15.¶
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.¶
props
ietf.org:rfc0000:props
¶
JCardProp[]
, where JCardProp
denotes a jCard-encoded vCard property as defined in Section 3.3 of [RFC7095].¶
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!"] ] ... }
props
example
params
ietf.org:rfc0000:params
¶
String[String|String[]]
¶
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" } } }¶
A Card
or CardGroup
converts to vCard by applying the reserve rules of section Section 2. The following additional rules apply:¶
Id
of the converted value (see Section 2.3.13).¶
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.¶
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.¶
JSPROP
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.¶
This property is defined by the following notation:¶
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) ; )¶
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
{ "@type": "Card", ... "foo": true } BEGIN:VCARD VERSION:4.0 ... X-RFC0000-JSPROP;X-RFC0000-JSPATH="foo": data:application/json;true ... END:VCARD
JSPATH
jspath-param = "X-RFC0000-JSPATH" "=" DQUOTE *QSAFE-CHAR DQUOTE ; also see param-value in RFC 6350, section 3.3¶
X-RFC0000-PROP;X-RFC0000-JSPATH="fooBar":baz¶
This document has no actions for IANA.¶
NOTE: Please remove this section and the reference to RFC 7942 prior to publication as an RFC.¶
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".¶
This document doesn't present any security consideration.¶