]> JSContact: Converting from and to vCard IIT-CNR/Registro.it
Via Moruzzi, 1 Pisa Italy 56124 mario.loffredo@iit.cnr.it https://www.iit.cnr.it
Fastmail
PO Box 234 Collins St. West Melbourne VIC 8007 Australia rsto@fastmailteam.com https://www.fastmail.com
art calext JSON contacts vCard jCard This document defines how to convert contact information between the JSContact and vCard data formats. It defines conversion rules for every JSContact and vCard element registered at IANA at the time of publication. It also defines new JSContact properties as well as vCard properties and parameters, to support converting arbitrary or unknown JSContact and vCard elements. This document obsoletes RFC 9555 and updates its definitions for JSContact version "2.0". Differences from RFC 9555 are documented in .
Introduction
Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The ABNF definitions in this document use the notations of . ABNF rules not defined in this document are defined in either (such as the ABNF for CRLF, WSP, DQUOTE, VCHAR, ALPHA, and DIGIT) or .
Scope and Goals This document outlines how to convert between the vCard and JSContact data formats. It describes which elements are common to both, but also highlights where the two formats differ. For each common element, it defines a conversion rule and includes an example of how to convert that element. All vCard and JSContact elements currently registered at IANA are in scope, but not all of these elements are common to both formats. For elements that have no counterpart in the other format, it is the goal of this document to define how to preserve them during conversion, but in general it is not the goal to achieve this by defining new standard elements. Instead, this document updates and by defining vCard and JSContact elements to preserve elements that have no equivalent in the other format. These conversion-specific properties are defined in Section for vCard, and for JSContact. This document obsoletes . For contents that remain unchanged, it includes all verified errata for the obsoleted document. The conversion rules are updated for JSContact version "2.0", defined in . replaces the JSContact "vCardProps", "vCardParams" and "vCardParam" properties originally defined in with the new "vCard" property. The new property allows for edge cases where the former elements were insufficient. For vCard, replaces the PROP-ID parameter with the new JSID parameter. Both changes align the conversion-specific elements of vCard and JSContact with those defined for iCalendar and JSCalendar in , allowing for code reuse for implementations that support these formats.
How to Read the Examples Later sections contain examples that illustrate how to convert between the vCard and JSContact data formats. The notation of these examples is such that their main points should be clear to the reader, but their contents can also be parsed for automated testing. The following sections define the notation for such examples.
vCard Examples A vCard example contains either an extract or a complete representation of vCard data. The following rules apply:
  • An example that only contains vCard properties implicitly represents a vCard (e.g. the BEGIN:VCARD and END:VCARD lines are implicit).
  • The vCard implicitly contains all mandatory properties with some value. If they are not included in the example, then their actual value is irrelevant for the example. The default value for the VERSION property is "4.0".
contains three examples, all of which represent the same vCard data. In the first example, the BEGIN and END lines and the mandatory properties are implicit. In the second example, only the BEGIN and END lines of the vCard are implicit. The third example depicts a complete vCard, nothing is implicit.
Examples for implicit and explicit vCard notation
A line containing just the value ... stands for any other properties that might be present in the vCard but are irrelevant for this example. illustrates this as an alternative representation for the examples of .
Example for additional properties represented by ...
A line starting with a single space represents the continuation of a folded content line (). illustrates this.
Example for a folded content line
JSContact Examples A JSContact example always represents a Card object, even if the example only depicts other JSContact objects and properties. JSContact objects are depicted either explicitly or implicitly. An explicit JSContact object starts and ends with braces. An implicit JSContact object omits braces, it only consists of JSON name/value pairs, separated by comma. An implicit JSContact object is assumed to be of type Card, unless it contains the @type property with a different value. It is assumed to contain all mandatory properties with some value; if they are not depicted, their actual value is irrelevant for the main point of the example. The default version of the Card is "2.0". illustrates this with multiple examples, all of which represent the same JSContact data. The first example contains an implicit JSContact object of type Card. The second example contains an explicit Name object but the Card object containing it is omitted. The third example contains the full Card object, nothing is omitted.
Examples for implicit and explicit JSContact object notation
A property with name "..." and value "" stands for additional properties that might be present in a JSContact object but are irrelevant for this example, including mandatory properties. illustrates this as an alternative representation for the examples of .
Example for additional properties represented by ...
Converting vCard to JSContact This section contains the conversion rules from the vCard to the JSContact Card.
General Rules
The Card uid Property The UID property converts to the "uid" property of the Card object, see . In contrast to JSContact version "2.0", the Card "uid" property was mandatory in version "1.0". Implementations that convert a vCard without a UID property to a Card of version "2.0" or higher MUST NOT generate a unique identifier as value for the uid property. When converting a vCard without UID property to JSContact version "1.0", implementations MUST generate a value for the uid property. Generating unique identifiers is implementation-specific. An implementation SHOULD generate the same value when generating the same Card multiple times. describes why this is problematic. Consequently, implementations SHOULD NOT convert to version "1.0" Card objects.
Choosing Identifiers Multivalued properties in JSContact are typically represented as a JSON object where the object keys are of the Id type () and the object values are the converted vCard property. In the absence of the JSID parameter (see ), implementations are free to choose any identifier as key for such entries. Whatever identifier generation scheme implementations use, they MUST generate values that are valid according to the definition of the Id type in . For example, this could be an incrementing number across all identifier keys in the Card object or only unique within one JSON object.
Converting Unknown Elements vCards may contain elements for which no IANA-registered JSContact property is defined, such as extended properties and parameters (see ). defines the "vCard" property to represent arbitrary vCard elements in JSContact.
vCard Parameters This section contains the conversion rules for vCard parameters. A rule typically applies only for specific vCard properties. To convert a vCard parameter on an arbitrary vCard property, see .
ALTID The ALTID parameter () does not convert to an IANA-registered property in JSContact, but several conversion rules make use of this parameter to combine multiple vCard properties into a single JSContact object instance. For an example of this, see . To preserve the verbatim value of the ALTID parameter, set the JSContact properties defined in .
AUTHOR The AUTHOR parameter () on a NOTE property converts to the Author object's uri property (). That Author object is set as the value of the Note object's author property ().
AUTHOR-NAME The AUTHOR-NAME parameter () on a NOTE property converts to the Author object's name property (). That Author object is set as the value of the Note object's author property.
CALSCALE The CALSCALE parameter () set on a BDAY, DEATHDATE, or ANNIVERSARY property converts to the PartialDate object's calendarScale property ().
CC The CC parameter () on an ADR property converts to the Address object's countryCode property ().
CREATED The CREATED parameter () on a NOTE property converts to the Note object's created property ().
DERIVED The DERIVED parameter () does not convert to JSContact. If the DERIVED parameter is set to "true" on a vCard property, then implementations MAY choose not to convert that property.
GEO The GEO parameter () set on an ADR property converts to the Address object's coordinates property (). Also see the conversion of the GEO property in .
GROUP The GROUP parameter () does not convert to JSContact. It exclusively is for use in jCard and MUST NOT be set in a vCard. Preserving the exact group name when converting from vCard to JSContact and back to vCard is not necessary. Any group identifiers will do, as long as the resulting vCard groups its properties equally to the original vCard. Implementations MAY preserve the original group name in the "parameters" property of the VCardProperty object ().
Example of How to Preserve the Group Name for a Known Property
Example of How to Preserve the Group Name for an Unknown Property
INDEX The INDEX parameter () set on the EXPERTISE, HOBBY, INTEREST, and ORG-DIRECTORY properties converts to the PersonalInfo () and Directory () objects' listAs property.
LANGUAGE The LANGUAGE parameter () converts to an entry in the Card object's localizations property () for that vCard property on which this parameter is set. The value of the LANGUAGE parameter defines the language tag key in the localizations property. This specification does not define a single standard conversion rule for how to convert the property values. Instead, building the localizations value is implementation-specific. Implementations that convert to a JSContact profile MUST adhere to the profile-specific restrictions, if any. Two options to populate the localizations property are:
  • One Patch per Property: For each vCard property with a LANGUAGE parameter, set the complete path in the PatchObject to the JSContact property that the vCard property converts to. The value of the patch is the converted property value. This is simple to process and adequate if the vCard only contains a few properties with the LANGUAGE parameter.
  • Bundle Patches by Parent: If a PatchObject contains multiple paths that have the same parent paths, then it might be possible to combine these patches into one patch that patches the parent property. This is possible if the property in the Card is patched in its entirety.
Generally, localizations only localize properties that are present in the non-localized version of this Card. illustrates this.
LANGUAGE Conversion Example: One Dominant Language
As a special case, if one or more vCard properties of the same type do not have the LANGUAGE parameter set, add them to the non-localized Card. Convert any with LANGUAGE parameters to the localizations property. illustrates this.
LANGUAGE Conversion Example: Property without Language
LABEL The LABEL parameter () on an ADR property converts to the Address object's full property ().
LEVEL The LEVEL parameter () converts to the PersonalInfo object's level property (). If this parameter is set on the EXPERTISE property, then its values convert as follows:
  • "beginner" converts to "low";
  • "average" converts to "medium"; and
  • "expert" converts to "high".
In all other cases, the values convert verbatim, but lowercase MUST be used for the JSContact value.
MEDIATYPE The MEDIATYPE parameter () converts to the Resource object's mediaType property ().
PHONETIC The PHONETIC parameter () converts to the Name () and Address () objects' phoneticSystem property unless the parameter value is "script", in which case the phoneticSystem property is not set. The value of the SCRIPT parameter converts to the phoneticScript property (see ). The related N or ADR property is defined by the vCard ALTID parameter. The conversion rules for the N and ADR properties define how the vCard components convert to JSContact. The component values of the property on which the PHONETIC parameter is set, convert to the respective NameComponent or AddressComponent objects' phonetic properties. If more than one property has the PHONETIC parameter set and relates to the same property, then they convert to the Card object's localizations property according to their LANGUAGE parameter values as outlined in .
PHONETIC Conversion Example
PID The PID parameter () does not convert to a standard JSContact element. Implementations MAY convert it to the "parameters" property of the VCardProperty object ().
PREF The PREF parameter () converts to the pref property of that JSContact object, to which the vCard property having this parameter converts.
PROP-ID The PROP-ID parameter () is deprecated. The JSID parameter replaces it. The PROP-ID parameter MUST be ignored if the JSID parameter is set on the same property. If the JSID parameter is not set, implementations MAY convert the PROP-ID parameter to the key of the JSContact object to which the vCard property converts to.
PROP-ID Conversion Example
SCRIPT The SCRIPT parameter () converts to the Name () or Address () objects' phoneticScript property. Also see .
SERVICE-TYPE The SERVICE-TYPE parameter () converts to the OnlineService object's service property ().
SORT-AS The SORT-AS parameter () converts to the Name, Organization, and OrgUnit objects' sortAs properties.
TYPE The TYPE parameter () either converts to the contexts property or the kind property, as defined in later sections. If not specified otherwise, the vCard "home" and "work" parameter values convert to the JSContact "private" and "work" contexts, respectively.
TZ The TZ parameter () on an ADR property converts to the Address object's timeZone property (). Also see the conversion of the TZ property in .
USERNAME The USERNAME parameter () converts to the OnlineService object's user property ().
VALUE The VALUE parameter () does not convert to an IANA-registered property in JSContact. To preserve properties with experimental values, see .
vCard Properties
ADR The ADR property () converts to an Address object () in the Card object's addresses property. Each component in the structured value of the ADR property converts to an AddressComponent in the Address components property. The component value converts to the AddressComponent value property, the component position determines the value of the AddressComponent kind property as follows: ADR Components Conversion
ADR component AddressComponent kind Remarks
post office box postOfficeBox recommends that this component not be set, but this is now disputable given the new components. Instead, set this component and use the new ADR value format defined in .
extended address apartment Do not convert if the ADR property value includes extended ADR components defined in .
street address name Do not convert if the ADR property value includes extended ADR components defined in .
locality locality
region region
postal code postcode
country country
apartment apartment Defined in .
block block Defined in .
building building Defined in .
direction direction Defined in .
district district Defined in .
floor floor Defined in .
landmark landmark Defined in .
room room Defined in .
street number number Defined in .
subdistrict subdistrict Defined in .
If the JSCOMPS parameter is set and valid, then the Address object's isOrdered property value is "true", and the defaultSeparator property and any separator name components are set according to the parameter value. The order in the components property MUST adhere to the order of the JSCOMPS parameter value. If the JSCOMPS parameter is not set, then the Address object's isOrdered property value is "false", and the defaultSeparator property MUST NOT be set. The order in the components property MUST follow the order of values in the ADR structured value when read from left to right.
  • The LABEL parameter converts to the Address object's full property.
  • The GEO parameter converts to the Address object's coordinates property.
  • The TZ parameter converts to the Address object's timeZone property.
  • The CC parameter converts to the Address object's countryCode property.
The ADR property converts to the same Address object as the GEO property and TZ property if either they are members of the same vCard property group, or if they are part of no group. The PREF and TYPE parameters convert according to the rules defined in . The ADR-specific values of the TYPE parameter defined in Sections and of convert to the corresponding entries of the contexts property as defined in . The ALTID and LANGUAGE parameters convert according to the rules defined in . Each possible language-dependent alternative converts to an entry of the PatchObject where the key references the full property.
ADR Conversion Example
See for examples of using the JSCOMPS parameter for vCard-structured property values.
ANNIVERSARY The ANNIVERSARY property () converts to an Anniversary object in the Card object's anniversaries property (). The Anniversary kind is "wedding". See how to convert property values of type TIMESTAMP and DATE.
ANNIVERSARY Conversion Example
BDAY The BDAY property () converts to an Anniversary object in the Card object's anniversaries property (). Its value converts to the Anniversary date property. The Anniversary kind is "birth". If the property value type is DATE and defines at least a year or a month and day, then the value converts to a PartialDate object. If the property value type is TIMESTAMP then the value converts to the utc property of the Timestamp object. Otherwise it does not convert to a standard JSContact element. A BDAY property and the BIRTHPLACE property (see ) convert to the same Anniversary object if their ALTID parameter values match or are not set on either property.
BDAY Conversion Example
BIRTHPLACE The BIRTHPLACE property () converts to an Anniversary object in the Card object's anniversaries property (). Its value converts to an Address object in the Anniversary place property. The Anniversary kind is "birth". A property value of type TEXT converts to the Address object's full property. A property value of type URI using the "geo:" URI scheme converts to the Address object's coordinates property. A property having any other value type does not convert to an Anniversary object. See for an example and how to convert a BIRTHPLACE property together with a BDAY property.
CALADRURI The CALADRURI property () converts to a SchedulingAddress object () in the Card object's schedulingAddresses property (). The SchedulingAddress object's uri property is set to the CALADRURI value. The PREF parameter () converts according to the rules defined in .
CALADRURI Conversion Example
CALURI The CALURI property () converts to a Calendar object () in the Card object's calendars property (). The Calendar object's kind property is set to "calendar" and the uri property is set to the CALURI value. The PREF and TYPE parameters convert according to the rules defined in .
CALURI Conversion Example
CATEGORIES The CATEGORIES property () converts to a set of entries of the Card object's keywords property (). The keys are the comma-separated text values of the CATEGORIES property. In this case, the PREF parameter does not have a JSContact counterpart; however, the implementors MAY insert the entries by order of preference.
CATEGORIES Conversion Example
CLIENTPIDMAP The CLIENTPIDMAP property () does not convert to a standard JSContact element. Implementations MAY convert it to the "properties" property of the VCard object ().
CONTACT-URI The CONTACT-URI property () converts to a Link object () in the Card object's links property (). The Link object's kind property is set to "contact" and the uri property is set to the CONTACT-URI property value. The PREF and TYPE parameters convert according to the rules defined in .
CONTACT-URI Conversion Example
CREATED The CREATED property () converts to the Card object's created property ().
CREATED Conversion Example
EMAIL The EMAIL property () converts to an EmailAddress object () in the Card object's emails property (). The EmailAddress object's address property is set to the EMAIL value. The PREF and TYPE parameters convert according to the rules defined in .
EMAIL Conversion Example
DEATHDATE The DEATHDATE property () converts to an Anniversary object in the Card object's anniversaries property (). Its value converts to the Anniversary date property. The Anniversary kind is "death". See how to convert property values of type TIMESTAMP and DATE. A DEATHDATE property and the DEATHPLACE property (see ) convert to the same Anniversary object if their ALTID parameter values match or are not set on either property.
DEATHDATE Conversion Example
DEATHPLACE The DEATHPLACE property () converts to an Anniversary object in the Card object's anniversaries property (). Its value converts to an Address object in the Anniversary place property. The Anniversary kind is "death". A property value of type TEXT converts to the Address object's full property. A property value of type URI using the "geo:" URI scheme converts to the Address object's coordinates property. A property having any other value type does not convert to an Anniversary object. See for an example and how to convert a DEATHPLACE property together with a DEATHDATE property.
EXPERTISE The EXPERTISE property () converts to a PersonalInfo object () in the Card object's personalInfo property (). The PersonalInfo object's kind property is set to "expertise". The INDEX and LEVEL parameters convert according to the rules defined in .
EXPERTISE Conversion Example
FBURL The FBURL property () converts to a Calendar object () in the Card object's calendars property (). The Calendar object's kind property is set to "freeBusy" and the uri property is set to the FBURL value. The PREF and TYPE parameters convert according to the rules defined in .
FBURL Conversion Example
FN The FN property () converts to the Name object's full property (). If the LANGUAGE parameter is set, then the FN property converts as outlined in . In the unexpected case where the vCard contains more than one FN property without the LANGUAGE parameter, convert the FN property that has the least parameters. If multiple such FN properties are present, choose any of them. All other FN properties do not convert to a standard JSContact element. Implementations MAY convert them to the "properties" property of the VCard object ().
FN Conversion Example
GENDER The GENDER property () does not convert to an IANA-registered property in JSContact. To convert this property, see . Alternatively, the Card object's speakToAs property defines how to address and refer to an individual represented by the Card, as do the newly defined vCard GRAMGENDER and PRONOUNS properties of .
GEO The GEO property () converts to the Address object's coordinates property (). See how to convert the GEO property together with the ADR and TZ property.
GRAMGENDER The GRAMGENDER property () converts to the SpeakToAs object's grammaticalGender property ().
GRAMGENDER Conversion Example
HOBBY The HOBBY property () converts to a PersonalInfo object () in the Card object's personalInfo property (). The PersonalInfo object's kind property is set to "hobby". The INDEX and LEVEL parameters convert according to the rules defined in .
HOBBY Conversion Example
IMPP The IMPP property () converts to an OnlineService object () in the Card object's onlineServices property (). The "uri" property is set to the IMPP value. Implementations MAY indicate that the OnlineService object converted from the IMPP property by adding an entry for the "uri" property of the OnlineService object in the "vCard/convertedProperties" property. The SERVICE-TYPE, USERNAME, PREF, and TYPE parameters convert according to the rules defined in .
IMPP Conversion Example
INTEREST The INTEREST property () converts to a PersonalInfo object () in the Card object's personalInfo property (). The PersonalInfo object's kind property is set to "interest". The INDEX and LEVEL parameters convert according to the rules defined in .
INTEREST Conversion Example
KEY The KEY property () converts to a CryptoKey object () in the Card object's cryptoKeys property (). The CryptoKey object's uri property is set to the KEY property value. The PREF and TYPE parameters convert according to the rules defined in .
KEY Conversion Example
KIND The KIND property () converts to the kind property (). Allowed values are those described in and extended with the values declared in and .
KIND Conversion Example
LANG The LANG property () converts to a LanguagePref object () in the Card object's preferredLanguages property (). The LANG property value converts to the LanguagePref object's language property value. The PREF and TYPE parameters convert according to the rules defined in .
LANG Conversion Example
LANGUAGE The LANGUAGE property () converts to the Card object's language property ().
LANGUAGE Conversion Example
LOGO The LOGO property () converts to a Media object () in the Card object's media property (). The Media object's kind property is set to "logo" and the uri property is set to the LOGO property value. The PREF and TYPE parameters convert according to the rules defined in .
LOGO Conversion Example
MEMBER The MEMBER property () converts to the Card object's members property (). Each MEMBER property value is a key in the members property. The PREF parameter () does not convert to JSContact.
Group Example
N The N property () converts to a Name object () in the Card object's name property. Each component in the structured value of the N property converts to a NameComponent in the Name components property. The component value converts to the NameComponent value property, the component position determines the value of the NameComponent kind property as follows: N Components Conversion
N component NameComponent kind Remarks
Family name surname Ignore any value that also occurs in the Secondary surname component.
Given name given
Additional name given2
Honorific prefix title
Honorific suffix credential Ignore any value that also occurs in the Generation component.
Secondary surname surname2
Generation generation
If the JSCOMPS parameter is set, then the Name object's isOrdered property value is "true", and the defaultSeparator property and any "separator" NameComponent objects are set according to the parameter value. The order in the components property MUST adhere to the order of the JSCOMPS parameter value. If the JSCOMPS parameter is not set, then the Name object's isOrdered property value is "false", and the defaultSeparator property MUST NOT be set. The order in the components property MUST follow the order of values in the N structured value when read from left to right. If the SORT-AS parameter is set, then its structured value converts to the Name object's sortAs property according to . An empty or non-existent component value indicates that no sort is defined for this kind.
N Conversion Example
See for examples of using the JSCOMPS parameter for vCard-structured property values.
NICKNAME The NICKNAME property () converts to a Nickname object () in the Card object's nicknames property (). The name property is set to the NICKNAME property value. The PREF and TYPE parameters convert according to the rules defined in .
NICKNAME Conversion Example
NOTE The NOTE property () converts to a Note object () in the Card object's notes property (). The ALTID and LANGUAGE parameters convert according to the rules defined in .
NOTE Conversion Example
ORG The ORG property () converts to an Organization object () in the Card object's organizations property (). The Organization object's name property is set to the ORG property organizational name component. The Organization object's units property is an array of OrgUnit objects that each contain an organizational unit name component value of the ORG property value. Implementations MAY allow representation of organizational units 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 defined in . The first item of the comma-separated SORT-AS parameter value converts to the sortAs property of the Organization object. The subsequent items convert to the sortAs property of the corresponding OrgUnit object. The TYPE parameter converts according to the rules defined in .
ORG Conversion Example
ORG-DIRECTORY The ORG-DIRECTORY property () converts to a Directory object () in the Card object's directories property (). The Directory object's kind property is set to "directory". The uri property is set to the ORG-DIRECTORY property value. The INDEX, PREF, and TYPE parameters convert according to the rules defined in .
ORG-DIRECTORY Conversion Example
PHOTO The PHOTO property () converts to a Media object () in the Card object's media property (). The Media object's kind property is set to "photo" and the uri property is set to the PHOTO value. The PREF and MEDIATYPE parameters convert according to the rules defined in .
PHOTO Conversion Example
PRODID The PRODID property () converts to the Card object's prodId property ().
PRODID Conversion Example
PRONOUNS The PRONOUNS property () converts to the SpeakToAs object's pronouns property ().
PRONOUNS Conversion Example
RELATED The RELATED property () converts to the Card object's relatedTo property (). The property value converts to the key in the relatedTo property. The TYPE parameters convert to the Relation object's relation property (). Any other parameters convert as defined in .
RELATED Conversion Example
REV The REV property () converts to the Card object's updated property ().
REV Conversion Example
ROLE The ROLE property () converts to a Title object () in the Card object's titles property (). The Title object kind is "role". The ROLE property value converts to the Title object name property. If the vCard contains an ORG property and either the ROLE and ORG property are not part of a vCard property group, or they are both in the same group, then the Title organizationId property is set to the identifier to which the ORG property converts in the Card object's organizations property. The ALTID and LANGUAGE parameters convert according to the rules defined in .
ROLE Conversion Example
SOCIALPROFILE The SOCIALPROFILE property () converts to an OnlineService object () in the Card object's onlineServices property (). If the SOCIALPROFILE property value is of type URI, then the "uri" property is set, otherwise, the "user" property is set. Implementations MAY indicate that the OnlineService object converted from the SOCIALPROFILE property by adding an entry for the "uri" or "user" property of the OnlineService object in the "vCard/convertedProperties" property. The SERVICE-TYPE, USERNAME, PREF, and TYPE parameters convert according to the rules defined in .
SOCIALPROFILE Conversion Example
SOUND The SOUND property () converts to a Media object () in the Card object's media property (). The Media object's kind property is set to "sound" and the uri property is set to the SOUND value. The PREF and TYPE parameters convert according to the rules defined in .
SOUND Conversion Example
SOURCE The SOURCE property () converts to a Directory object () in the Card object's directories property (). The Directory object's kind property is set to "entry". The uri property is set to the SOURCE property value. The PREF and MEDIATYPE parameters convert according to the rules defined in .
SOURCE Conversion Example
TEL The TEL property () converts to a Phone object () in the Card object's phones property (). The TEL-specific values of the TYPE parameter convert to the features property keys as outlined in . Note that defines the default type to be "voice", but the default Phone features property is absent by default. Accordingly, an implementation SHOULD only set the Phone object's features property if the TEL property actually has a TEL-specific TYPE parameter set. TEL TYPE Conversion
TYPE value Phone feature
cell mobile
fax fax
main-number main-number
pager pager
text text
textphone textphone
video video
voice voice
The value of the TEL property converts to the Phone object's number property. The PREF and TYPE parameters convert according to the rules defined in .
TEL Conversion Example
TITLE The TITLE property () converts to a Title object () in the Card object's titles property (). The TITLE property value converts to the Title object name property. The same rules as in apply for setting the organizationId property of the Title object. The ALTID and LANGUAGE parameters convert according to the rules defined in .
TITLE Conversion Example
TZ The TZ property () converts to an Address object () in the Card object's addresses property. A value of type TEXT converts to the Address object's timeZone property. A value of type UTC-OFFSET converts to the Address object's timeZone property if the offset has zero minutes and the hour offset is between -12 and +14, both inclusively. Note that:
  • 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".
See how to convert the TZ property together with the ADR and GEO property. Any other value of type UTC-OFFSET or URI does not convert to an IANA-registered property in JSContact. To convert such property, see .
UID The UID property () converts to the Card object's uid property ().
UID Conversion Example
URL The URL property () converts to a Link object () in the Card object's links property (). The Link object's uri property is set to the URL value. The PREF and TYPE parameters convert according to the rules defined in .
URL Conversion Example
VERSION The VERSION property () does not convert to a standard JSContact element. Implementations MAY convert it to the "properties" property of the VCard object ().
X-ABLabel The X-ABLabel property is experimental but widely in use in existing vCard data. It converts to the label property of a JSContact object. The X-ABLabel property is preceded by a vCard property group name, and the label converts to the JSContact object, which was converted from a vCard property of the same group. The group name is not preserved; implementations are free to choose any unique group name when converting back to vCard. For an example on how to preserve the group name, see .
X-ABLabel Conversion Example
XML The XML property () does not convert to a standard JSContact element. Implementations MAY convert it to the "properties" property of the VCard object ().
Converting JSContact to vCard This section defines the conversion rules for each JSContact object type. Each subsection lists the properties of one object type and the relevant document sections for their conversion to vCard.
Address The Address object converts to the ADR property. Each AddressComponent object in the components property converts to a component in the structured value of the ADR property. AddressComponent conversion
AddressComponent kind ADR component Remarks
apartment apartment , and remarks below
block block , and remarks below
building building , and remarks below
country country
direction direction , and remarks below
district district , and remarks below
floor floor , and remarks below
landmark landmark , and remarks below
locality locality
name street address , and remarks below
number street number , and remarks below
postcode postal code
postOfficeBox post office box
region region
room room , and remarks below
subdistrict subdistrict , and remarks below
Remarks:
  • In addition to setting the "block", "direction", "district", "landmark", "name", "number", and "subdistrict" components, implementations MAY combine these values to set the "street address" component in the ADR property value.
  • In addition to setting the "apartment", "building", "floor" and "room" components, implementations MAY combine these values to set the "extended address" component in the ADR property value.
The other properties convert as follows: Properties of the Address object
Name Reference Parameter (or other) See
contexts TYPE
coordinates GEO Sections and , and remarks below
countryCode CC
defaultSeparator JSCOMPS
full LABEL
isOrdered JSCOMPS
phoneticScript SCRIPT
phoneticSystem PHONETIC
pref PREF
timeZone TZ Sections and , and remarks below
Remarks:
  • The "coordinates" and "timeZone" properties SHOULD convert to the GEO and TZ parameters, but implementations MAY alternatively convert them to the same-named properties e.g. to preserve original vCard data.
Other properties MAY be converted to JSPROP properties.
Anniversary The Anniversary object converts to one of the following properties, determined by the Anniversary kind property value:
  • If the kind is "wedding" and the Anniversary date property is set, then it converts to the ANNIVERSARY property. How to convert the place property is implementation-specific.
  • If the kind is "birth", then the date property value converts to the BDAY property and the place property converts to the BIRTHPLACE property.
  • If the kind is "death", then the date property value converts to the DEATHDATE property and the place property converts to the DEATHPLACE property.
A date property value of type PartialDate converts to the DATE property value type. The calendarScale property converts to the CALSCALE parameter. A date property value of type Timestamp converts to the TIMESTAMP property value type by converting the "utc" property. How to convert a place property value having any Address property other than the "full" property set is implementation-specific. Other properties MAY be converted to JSPROP properties.
Calendar The Calendar object converts to one of the following properties, determined by the Calendar kind property value. If the kind is "calendar" then it converts to the CALURI property. If the kind is "freeBusy" then it converts to the FBURL property. Its uri property converts to the property value. Its other properties convert as follows: Properties of the Calendar object
Name Reference Parameter (or other) See
contexts TYPE
label X-ABLabel (Property)
mediaType MEDIATYPE
pref PREF
Other properties MAY be converted to JSPROP properties.
Card The Card object converts to a vCard. Its properties other than the localizations property convert as follows: Properties of the Card object
Name Reference Property (or Parameter) See
addresses ADR Address object
anniversaries ANNIVERSARY Anniversary object
calendars CALURI, FBURL Calendar object
created CREATED
directories SOURCE, ORG-DIRECTORY Directory object
emails EMAIL EmailAddress object
keywords CATEGORIES
kind KIND
language LANGUAGE
links CONTACT-URI, URL Link object
media PHOTO, LOGO, SOUND Media object
members MEMBER
name N Name object
nicknames NICKNAME Nickname object
notes NOTE Note object
onlineServices IMPP, SOCIALPROFILE OnlineService object
organizations ORG Organization object
personalInfo EXPERTISE, HOBBY, INTEREST PersonalInfo object
phones TEL Phone object
preferredLanguages LANG
prodId PRODID
relatedTo RELATED
schedulingAddresses CALADRURI SchedulingAddress object
speakToAs GRAMGENDER, PRONOUNS SpeakToAs object
titles TITLE Title object
uid UID
updated REV
The localizations property converts by converting the properties in the PatchObject using the same rules as outlined in . The LANGUAGE parameter MUST be set on each resulting property with the parameter value being the language key of the localizations property. The ALTID parameter MUST be set and its value be equal for all properties having the same JSON pointer path in the localizations property and the non-localized Card. Other properties MAY be converted to JSPROP properties.
CryptoKey The CryptoKey object converts to the KEY property. Its uri property converts to the property value. Its other properties convert as follows: Properties of the CryptoKey object
Name Reference Parameter (or other) See
contexts TYPE
label X-ABLabel (Property)
mediaType MEDIATYPE
pref PREF
Other properties MAY be converted to JSPROP properties.
Directory The Directory object converts to one of the following properties, determined by the Directory kind property value. If the kind is "entry" then it converts to the SOURCE property. If the kind is "directory" then it converts to the ORG-DIRECTORY property. Its uri property converts to the property value. Its other properties convert as follows: Properties of the Directory object
Name Reference Parameter (or other) See
contexts TYPE
label X-ABLabel (Property)
listAs INDEX
mediaType MEDIATYPE
pref PREF
Other properties MAY be converted to JSPROP properties.
EmailAddress The EmailAddress object converts to the EMAIL property. Its address property converts to the property value. Its other properties convert as follows: Properties of the EmailAddress object
Name Reference Parameter (or other) See
contexts TYPE
label X-ABLabel (Property)
pref PREF
Other properties MAY be converted to JSPROP properties.
LanguagePref The LanguagePref object converts to the LANG property. Its language property converts to the property value. Its other properties convert as follows: Properties of the LanguagePref object
Name Reference Parameter (or other) See
contexts TYPE
pref PREF
Other properties MAY be converted to JSPROP properties.
Link The Link object converts to one of the following properties, determined by the Link kind property value. If the kind property is not set then it converts to the URL property.. If the kind is "contact" then it converts to the CONTACT-URI property. Its uri property converts to the property value. Its other properties convert as follows: Properties of the Link object
Name Reference Parameter (or other) See
contexts TYPE
label X-ABLabel (Property)
mediaType MEDIATYPE
pref PREF
Other properties MAY be converted to JSPROP properties.
Media The Media object converts to one of the following properties, determined by the Media kind property value. If the kind is "photo" then it converts to the PHOTO property.. If the kind is "logo" then it converts to the LOGO property. If the kind is "sound" then it converts to the "SOUND property. Its uri property converts to the property value. Its other properties convert as follows: Properties of the Media object
Name Reference Parameter (or other) See
contexts TYPE
label X-ABLabel (Property)
mediaType MEDIATYPE
pref PREF
Other properties MAY be converted to JSPROP properties.
Name The Name object converts to the N property. Each NameComponent object in the components property converts to a component in the structured value of the N property. NameComponent conversion
NameComponent kind N component Remarks
credential Honorific suffix
generation Generation , and remarks below
given Given name
given2 Additional name
surname Family name
surname2 Secondary surname , and remarks below
title Honorific prefix
Remarks:
  • In addition to converting the "generation" kind to the "Generation" component, implementations MAY also append the value to the "Honorific Suffixes" component of the N property value.
  • In addition to converting the "surname2" kind to the "Secondary surname" component, implementations MAY also append the value to the "Surname" component of the N property value.
The full property converts to the FN property. The full property is optional, but the FN property is defined to be mandatory in . How to set the FN property if the full property is not set is implementation-specific. Implementations MAY derive the full name from the NameComponents objects. If the isOrdered property value is "true", then this can be done by concatenating the name component values. Alternatively, an implementation can choose any other heuristic to generate the full name from its components such as . If the FN property value is derived, implementations SHOULD set the DERIVED parameter. The other properties convert as follows: Properties of the Name object
Name Reference Parameter (or other) See
defaultSeparator JSCOMPS
phoneticScript SCRIPT
phoneticSystem PHONETIC
isOrdered JSCOMPS
sortAs SORT-AS
Other properties MAY be converted to JSPROP properties.
Nickname The Nickname object converts to NICKNAME property. Its name property converts to the property value. Its other properties convert as follows: Properties of the Nickname object
Name Reference Parameter (or other) See
contexts TYPE
pref PREF
Other properties MAY be converted to JSPROP properties.
Note The Note object converts to the NOTE property. Its note property converts to the property value. The Author object set as the value of its author property converts as follows: Properties of the Author object
Name Reference Parameter (or other) See
name AUTHOR-NAME
uri AUTHOR
Its other properties convert as follows: Properties of the Note object
Name Reference Parameter (or other) See
created CREATED
Other properties MAY be converted to JSPROP properties.
OnlineService The OnlineService object converts to the IMPP property or SOCIALPROFILE property. Which property to convert to is implementation-specific. Implementations SHOULD preserve the property name indicated in the vCard property. If its uri property is set, but neither the user or service properties are set, then implementations SHOULD choose IMPP if the uri property value is a URI with scheme "xmpp". It other properties convert as follows: Properties of the OnlineService object
Name Reference Parameter (or other) See
contexts TYPE
label X-ABLabel (Property)
pref PREF
service SERVICE-TYPE
user USERNAME
Other properties MAY be converted to JSPROP properties.
Organization The Organization object converts to the ORG property. Its name property converts the first component in the structured property value. The name property of any OrgUnit object in its units property converts to additional components in the structured property value, in order to appearance. Its sortAs property converts the first component in the structured value of the SORT-AS parameter. The sortAs property of any OrgUnit object in its units property converts to additional components in the structured parameter value, in order to appearance. Its other properties convert as follows: Properties of the Organization object
Name Reference Parameter (or other) See
contexts TYPE
Other properties MAY be converted to JSPROP properties.
PersonalInfo The PersonalInfo object converts to one of the following properties, determined by the PersonalInfo kind property value. If the kind is "expertise" then it converts to the EXPERTISE property.. If the kind is "hobby" then it converts to the HOBBY property. If the kind is "interest" then it converts to the "INTEREST property. Its value property converts to the property value. Its other properties convert as follows: Properties of the PersonalInfo object
Name Reference Parameter (or other) See
listAs INDEX
level LEVEL
Other properties MAY be converted to JSPROP properties.
Phone The Phone object converts to the TEL property Its number property converts to the property value. Its other properties convert as follows: Properties of the Phone object
Name Reference Parameter (or other) See
contexts TYPE
features TYPE
label X-ABLabel (Property)
pref PREF
Other properties MAY be converted to JSPROP properties.
SchedulingAddress The SchedulingAddress object converts to the CALADRURI property. Its uri property converts to the property value. Its other properties convert as follows: Properties of the SchedulingAddress object
Name Reference Parameter (or other) See
contexts TYPE
label X-ABLabel (Property)
pref PREF
Other properties MAY be converted to JSPROP properties.
SpeakToAs The SpeakToAs object converts to the GRAMGENDER property and PRONOUNS property.. Its grammaticalGender property converts to the property value of the GRAMGENDER property. Its pronouns property converts to PRONOUNS properties, one for each entry. The pronouns property of the Pronouns object converts the property value. Its other properties convert as follows: Properties of the Pronouns object
Name Reference Parameter (or other) See
contexts TYPE
pref PREF
Other properties MAY be converted to JSPROP properties.
Title The Title object converts to one of the following properties, determined by the Title kind property value. If the kind is "title" or not set then it converts to the TITLE property.. If the kind is "role" then it converts to the ROLE property. Its name property converts the property value. Its organizationId property converts by assigning the TITLE property and the ORG property to the same vCard property group (see ). Other properties MAY be converted to JSPROP properties.
New vCard Parameters
Updates to JSContact
New Properties
vCard
Name:
vCard
Context:
A Card object
Type:
VCard (optional)
Description
This property contains information about vCard data that got converted to a JSContact Card object. It allows for preserving arbitrary vCard elements, such as extension properties and parameters. This specification defines the VCard object type for converting a vCard to a JSContact Card object. Future specifications MAY define additional value types for this property. A VCard object has the following properties:
@type: String
This specifies the type of this object. This MUST be VCard, if set.
convertedProperties: String[VCardProperty] (optional)
This contains conversion-related information about the vCard properties that got partially or fully converted to JSContact. Each key defines the path to a JSContact element. The value for each key contains information about the vCard property which converted to the JSContact element located at that key. Unless otherwise defined for a specific vCard property, the path points to that JSContact object property to which the vCard property value converted to. The key MUST be a valid key of a PatchObject as defined in . The key MAY point into a nested object.
properties: *[][] (optional)
This contains properties of the vCard which did not convert to standard JSContact elements. The value MUST be a list of vCard properties formatted in jCard as defined in .
A VCardProperty object has the following properties:
@type: String
This specifies the type of this object. This MUST be VCardProperty, if set.
name: String (mandatory)
This is the name of the vCard property in lowercase.
valueType: String (optional)
This is the name of the vCard property value type in lowercase.
parameters: String[String|String[]] (optional)
This contains parameters of the vCard property. The value MUST comply with vCard parameters formatted in jCard as defined in .
The example in describes how to convert unknown vCard elements to the "vCard" property. The "X-FOO" parameter set on the FN property illustrates how to preserve an unknown vCard parameter on a property that does convert to a standard JSContact element. The "X-BAR" property and "X-BAZ" component illustrate how to convert entirely unknown vCard properties.
Converting unknown vCard elements to the vCard property
Updates to vCard
New Parameters
JSCOMPS
Parameter name:
JSCOMPS
Purpose:
Defines the order and separators for the elements of a structured property value.
Description:
The JSCOMPS parameter value facilitates converting name and address components between JSContact and vCard. It preserves the order of the components of the JSContact property and contains the verbatim values of separator components. If this parameter is set and its value is valid (see later), then implementations MUST set the isOrdered property of the Name or Address object to "true". Otherwise, they MUST set the isOrdered property value to "false". The JSCOMPS parameter value is a structured type value. Its value MUST be quoted. The parameter value consists of a sequence of entries, separated by the SEMICOLON character (U+003B). The first entry defines the value of the defaultSeparator property. If it is the empty string, then no default separator is defined. Otherwise, the first entry MUST be a separator entry. All following entries processed in order result in an ordered list of JSContact components and MUST be one of the following two kinds:
  1. A positional. This refers to a component value in the vCard structured value. A position consists of the numeric index of a component in the structured value, optionally followed by a COMMA (U+002C) character and the non-zero index of a value within that component. The zero index selects the first component or value, respectively. The second index is zero by default, in which case it MUST be omitted (as well as the leading COMMA). The resulting JSContact component is formed by determining its kind by the position in the vCard structured value. The component value is the verbatim value of the vCard component. Figures and illustrate this by example.
  2. A separator. This contains the verbatim value of a separator component. It starts with the LATIN SMALL LETTER S (U+0073) character, followed by the COMMA (U+002C) character, followed by zero or more "param-value" characters (see ), where the COMMA (U+002C) and SEMICOLON (U+003B) characters MUST be escaped according to the rules defined in . illustrates this by example. The resulting JSContact component is formed by setting its kind to "separator" and its value to the verbatim value of the entry.
A JSCOMPS parameter value is valid if and only if:
  • All indexes in the positional entries refer to an existing component value in the vCard property value.
  • The count of positional entries equals the count of deduplicated component values. Deduplication is required because some values may occur in both their designated and backwards-compatible components in the vCard property value:
    • A value that occurs in both the N property secondary surname component and the family name component only counts once.
    • A value that occurs in both the N property generation component and the honorific suffix component only counts once.
    • A value in the ADR property street address component does not count if the ADR property value contains a value in one of the new components defined in .
    • All other values count once each.
Format definition:
Example(s):
The following example demonstrates the use of positional entries for the name "Jane Doe". The given name is ordered before the surname. No secondary index is required for either positional because both are zero.
Example of a Secondary Positional Index
The following example demonstrates a secondary positional index. The "Jr." generation marker only counts once because it occurs in both the designated generation component and the backwards-compatible honorific suffixes component.
Example of Positional Entries
The following example demonstrates the use of separator entries for the (shortened for brevity) address "54321 Oak St, Reston". The first entry defines the default separator to be ", ". The second and fourth positional entries are separated with the separator value " ". For backwards compatibility, the street address component of the ADR property contains both the street number and name, but it is not referred to in the JSCOMPS parameter and does not contribute to the count of values.
Example of Separator Entries
JSID
Parameter Name:
JSID
Purpose:
Specifies the JSContact identifier of the associated property.
Description:
This parameter specifies the JSON object key of the JSContact object to which a vCard property converts to. For example, this parameter set on an EMAIL property defines the key of the EmailAddress object in the Card object's "emails" property (see below for an example). The value of the JSID parameter MUST be a valid key according to the definition of the JSContact property to which the property that this parameter is set on converts to. Typically, this requires the value to be a valid Id.
Format Definition:
Example(s):
Converting the JSID parameter on an EMAIL property
JSPTR
Parameter name:
JSPTR
Purpose:
To specify a pointer to a JSContact property.
Description:
This parameter is set on a JSPROP property. Its value points to a JSContact property. The parameter has a single value that MUST be a valid PatchObject key as defined in . The parameter value MUST be quoted and is case-sensitive.
Format definition:
Example(s):
For further examples, see .
New vCard Properties
JSPROP
Property name:
JSPROP
Purpose:
Represents a JSContact property in vCard.
Value type:
TEXT; also see "Format definition" below for value restrictions.
Conformance:
Can be specified multiple times in a vCard.
Property parameters:
The JSPTR parameter MUST be set for this property. Other IANA-registered and experimental property parameters can be specified on this property.
Description:
This property converts an arbitrary JSContact property from and to vCard. The vCard property value is the JSON-encoded value of the JSContact property, represented as a TEXT value. The format of the JSON value MUST be compact, e.g., without insignificant whitespace as defined in . The value of the JSPTR parameter points to the JSContact property within the Card. The root of the JSON pointer is always the Card object that this vCard converts to, irrespective if the JSON pointer starts with the SOLIDUS (U+002F) character. The pointer MUST NOT reference into an array. All JSPROP properties in a vCard together form a PatchObject as defined in . The value of its JSPTR parameter corresponds to a key in the PatchObject; the value of the JSPROP property corresponds to the value for that key. When converting from vCard to JSContact, the PatchObject MUST only be applied after all other vCard properties have already been converted. The PatchObject MUST be valid, including the restriction that an invalid PatchObject MUST NOT be applied.
Format definition:
This property is defined by the following notation:
Example(s):
This illustrates how to convert a property at the top level in a Card object that is unknown to the implementation.
Unknown Property Example
This illustrates how to convert a vendor-specific property at the top level of a Card object. Note the required use of quoted string for the JSPTR value, which allows the path to include the COLON (U+003A) character.
Vendor-Specific Property Conversion Example
This illustrates how to convert a vendor-specific property at a nested level in a Card object using a path relative to the Card object. Although not recommended, the property name includes the SOLIDUS (U+002F) character, which requires escaping in the JSON pointer.
Nested Vendor-Specific Property Example with a Path Relative to Card
Security Considerations This specification defines how to convert between the JSContact and vCard formats. The security considerations for parsing and formatting such data apply and are outlined in and .
IANA Considerations TBD
References Normative References JSContact: A JSON Representation of Contact Data vCard Format Extension for JSContact Fastmail IIT-CNR Informative References vObject Internationalization Ribose Ribose Spherical Cow Group Unicode Locale Data Markup Language (LDML) Part 8: Person Names other CLDR committee members
Differences from RFC 9555 This section documents all significant differences from RFC 9555. Insignificant differences, such as formatting, grammar or typos are not documented.
Applied Errata The following errrata was applied to to this document:
  • Errata 8555
Changed Conversion Rules
vCard to JSContact
  • Converting the UID property to the "uid" property is redefined for JSContact version "2.0". See .
Changes to JSContact
Obsoleted Properties The following JSContact properties became obsolete:
vCardProps
This property is deprecated, the "properties" property of the newly defined VCard type replaces it. illustrates this using the same example as.
Example for Representing the Obsolete vCardProps Property
vCardParams
This property is deprecated, the "parameters" property of the newly defined VCardProperty type replaces it. illustrates this using the same example as .
Example for Representing the Obsolete vCardParams Property
vCardName
This property is deprecated, the "name" property of the newly defined VCardProperty type replaces it. illustrates this using the same example as .
Example for Representing the Obsolete vCardName Property
Obsoleted Types The following JSContact type definitions became obsolete:
JCardProp
This type is deprecated because the "vCardProps" property became deprecated. Also see .
Changes to vCard
Obsoleted Parameters The following vCard parameters became obsolete:
PROP-ID
This parameter is deprecated, the newly defined JSID parameter replaces it. defines how to process the PROP-ID in presence and absence of the JSID parameter.
Acknowledgements The definition and examples of the PHONETIC and SCRIPT parameters are based on the initial draft version of .