JSContact: Converting from and to vCard

Converting vCard to JSContact This section contains the conversion rules from vCard to JSContact Card. Its follows the same structure as the vCard v4 RFC document. Properties and parameters of vCard extension RFCs, including the vCard JSContact Extension RFC are added to appropriate subsections.

General rules

The uid property The UID property in vCard is optional, but the uid property in JSContact is mandatory. Implementations that convert a vCard without UID property MUST generate a unique identifier as a 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 not convert to one exact instance of a JSContact card.

Choosing identifiers Multi-valued properties in JSContact typically are represented as a JSON object where the object keys are of the Id type and the object values are the converted vCard property. In absence of the PROP-ID parameter (see ), implementations are free to choose any identifier for such entries. Whatever identifier generation scheme implementations use, they SHOULD generate values of short character length. For example, this could be an incrementing number across all Ids or only unique within one JSON object.

vCard Value Data Types

BOOLEAN This converts to the JSContact Boolean type.

DATE, TIME, DATE-TIME, DATE-AND-OR-TIME, and TIMESTAMP The TIMESTAMP type generally converts to the UTCDateTime. It converts to the Timestamp type for anniversaries. The DATE type converts to the PartialDate type, which only is relevant for anniversaries. This does not apply to DATE values that only define a month or a day. The TIME, DATE-TIME, DATE-AND-OR-TIME types and DATE type values that only define a month or day do not convert to any JSContact type. vCard properties or parameters having such values MAY convert as defined in .

INTEGER This converts to the JSContact Int and UnsignedInt types.

FLOAT This converts to the JSContact Number type.

LANGUAGE-TAG This converts to the JSContact String type.

TEXT This converts to the JSContact String type.

URI This converts to the JSContact String type.

UTC-OFFSET This either converts to a String containing an IANA TimeZone Database entry name (see ), 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 .

vCard Parameters

ALTID This 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 extension properties props or params defined in .

AUTHOR The AUTHOR parameter value of a vCard NOTE property converts to the uri property of the Author object for this note. To convert this parameter for other vCard properties, see . Note: This parameter is defined in .

AUTHOR-NAME The AUTHOR-NAME parameter value of a vCard NOTE property converts to the name property of the Author object for this note. To convert this parameter for other vCard properties, see . Note: This parameter is defined in .

CALSCALE This parameter set on a BDAY, DEATHDATE or ANNIVERSARY property converts to the calendarScale property of the PartialDate object type. To convert this parameter for other vCard properties, see .

CREATED The CREATED parameter value of a vCard NOTE property converts to the created property of the Note object. To convert this parameter for other vCard properties, see . Note: This parameter is defined in .

DERIVED If this parameter is set to true on a vCard property, then implementations MAY choose to not convert that property. Note: This parameter is defined in .

GEO This parameter set on an 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 .

GROUP This parameter exclusively is for use in jCard (see ). It 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 that still wish to preserve the exact property group name of a vCard property MAY set the group parameter in the JSContact extension properties props or params defined in .

An example how to preserve the group name in params during conversion.

An example how to preserve the group name in props during conversion.

INDEX This parameter set on the EXPERTISE, HOBBY, INTEREST and ORG-DIRECTORY properties defined in converts to the JSContact listAs property of the PersonalInfo and DirectoryResource objects. To convert this parameter for other vCard properties, see .

LANGUAGE This converts to an entry in the localizations property for the vCard property that this parameter is set on. The value of the LANGUAGE parameter defines the language 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. 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 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.

A non-localized Card SHOULD NOT provide less information than any of its localizations. As a general rule, an implementation SHOULD choose those vCard properties to convert to the non-localized card, that either all have the same LANGUAGE parameter value or none at all. 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, then choose them to the non-localized Card. Convert any with LANGUAGE parameters to the localizations property. illustrates this.

LANGUAGE conversion example: property without language As the least preferred option, illustrates how all vCard properties of the same type have the LANGUAGE parameter set, but none of their language tags match the locale of the main Card. In this case, implementations MAY choose to add the localized vCard properties only to the localizations object. Implementations SHOULD avoid this scenario as much as possible.

LANGUAGE conversion example: conflicting locale and language

LEVEL The LEVEL parameter as defined in is directly converted to the level property of the PersonalInfo type apart from when LEVEL is used in the EXPERTISE property; in this case, the values convert as in the following:

"beginner" converts to "low";
"average" converts to "medium";
"expert" converts to "high".

To convert this parameter for other vCard properties, see .

MEDIATYPE This converts to the mediaType property of the Resource object type. To convert this parameter for other vCard properties, see .

PID This does not convert to an IANA-registered property in JSContact. To convert this parameter, see .

PREF This converts to the pref property.

PROP-ID The PROP-ID parameter value of a vCard property converts to the Id of the JSContact property to which the vCard property converts to.

PROP-ID conversion example Note: This parameter is defined in .

RANKS The values of this parameter convert to the rank property of the NameComponent objects inferred from the N property value. To convert this parameter for other vCard properties, see . Note: This parameter is defined in .

SERVICE-TYPE This converts to the service property of the OnlineService object type. To convert this parameter for other vCard properties, see . Note: This parameter is defined in .

SORT-AS This converts to the sortAs properties defined for the Name, Organization and OrgUnit object types. To convert this parameter for other vCard properties, see .

TYPE This converts to the contexts property as well as property-specific type property values defined in later sections.

TZ This parameter set on an 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 . To convert this parameter for other vCard properties, see .

VALUE This does not convert to an IANA-registered property in JSContact. To preserve properties with experimental values, see and .

General Properties

BEGIN and END These do not convert to IANA-registered properties in JSContact.

KIND The KIND property converts to the kind property (). Allowed values are those described in Section 6.1.4 of and extended with the values declared in and .

KIND conversion example

SOURCE A SOURCE property converts to an entry in the directories property (). 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 .

SOURCE conversion example

XML This does not convert to an IANA-registered property in JSContact.

Identification Properties

BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY The BDAY and ANNIVERSARY properties and the extensions BIRTHPLACE, DEATHDATE, DEATHPLACE described in are represented as Anniversary objects included in the anniversaries property ():

BDAY and BIRTHPLACE convert to date and place where type is set to "birth";
DEATHDATE and DEATHPLACE convert to date and place where type is set to "death";
ANNIVERSARY converts to date where type is "wedding".

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 .

BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY conversion example

GENDER This does not map to an IANA-registered property in JSContact. To convert this property, see . 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 .

GRAMMATICAL-GENDER and PRONOUNS The GRAMMATICAL-GENDER property converts to the grammaticalGender property of the SpeakToAs object (). The PRONOUNS property converts to an entry in the pronouns property of the SpeakToAs object ().

GRAMMATICAL-GENDER and PRONOUNS conversion example

FN All the FN instances are represented through the fullName property (). 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 .

N and NICKNAME The N instances convert to equivalent items of the components array of the name property (): the N components convert into related NameComponent objects as presented in . Name components SHOULD be ordered such that their values joined by whitespace produce a valid full name of this entity. Each comma-separated item of the SORT-AS parameter value converts to an entry of the sortAs property where the key is the "type" value related to the sorted N component and the value is the corresponding item. Absence of a key in the sortAs indicates that its related part in the SORT-AS parameter value MUST either the empty string followed by COMMA, or no further SORT-AS parts are defined. N components conversion

N component	"type" value
Honorific Prefixes	prefix
Given Names	given
Family Names	surname
Additional Names	middle
Honorific Suffixes	suffix

A NICKNAME property converts to an entry in the nickNames property (). 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 .

FN, N, NICKNAME conversion example

PHOTO A PHOTO property converts to an entry in the media property (). 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 .

PHOTO conversion example

Delivery Addressing Properties

ADR An ADR property converts to an entry in the addresses property (). The entry value is an Address object. The ADR components convert into the Address properties as presented in and . The "street address" and "extended address" ADR components MAY be converted into either a single StreetComponent item or a combination of StreetComponent items. ADR components vs. Address members conversion

ADR component	Address member
locality	locality
region	region
postal code	postcode
country name	country

ADR components vs. StreetComponent items conversion

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 converts to the countryCode property. The PREF and TYPE parameters convert according to the rules as defined in . The ALTID and LANGUAGE parameters convert according to the rules as defined in . Each possible language-dependent alternative is represented as an entry of the PatchObject map where the key references the fullAddress property.

ADR conversion example

Communications Properties

CONTACT-CHANNEL-PREF A CONTACT-CHANNEL-PREF property converts to an entry in the preferredContactChannels property (). The entry key set is defined in , the related entry values are arrays of ContactChannelPreference objects. CONTACT-CHANNEL-PREF values conversion

CONTACT-CHANNEL-PREF value	"preferredContactChannels" key
ADR	addresses
EMAIL	emails
IMPP	onlineServices
TEL	phones

The PREF and TYPE parameters convert according to the rules as defined in . If both PREF and TYPE parameters are missing, the array of ContactChannelPreference objects MUST be empty.

LANG conversion example Note: This property is defined in .

EMAIL An EMAIL property converts to an entry in the emails property (). The entry value is an EmailAddress object. The address property is set to the EMAIL value. The PREF and TYPE parameters convert according to the rules as defined in .

EMAIL conversion example

IMPP An IMPP property converts to an entry in the onlineServices property (). The type of the OnlineService is set to impp. The entry value is a OnlineService object and the user property is set to the IMPP value. The PREF and TYPE parameters convert according to the rules as defined in .

IMPP conversion example

LANG A LANG property converts to an entry in the preferredLanguages property (). The entry keys correspond to the language tags, the related entry values are arrays of LanguagePreference objects. The PREF and TYPE parameters convert according to the rules as defined in . If both PREF and TYPE parameters are missing, the array of LanguagePreference objects MUST be empty.

LANG conversion example

LOCALE The LOCALE property converts to the locale property ().

LOCALE conversion example Note: This property is defined in .

SOCIALPROFILE A SOCIALPROFILE property converts to an entry in the onlineServices property (). If the value type of the SOCIALPROFILE is TEXT, then the type of the OnlineService is set to username. Otherwise, the type is set to uri. The entry value is a OnlineService object and the user property is set to the property value. The PREF and TYPE parameters convert according to the rules as defined in .

IMPP conversion example Note: This property is defined in .

TEL A TEL property converts to an entry in the phones property (). The entry value is a Phone object. The TEL-specific values of the TYPE parameter convert to the features property keys. The number property is set to the TEL value. The PREF and TYPE parameters convert according to the rules as defined in .

TEL conversion example

Geographical Properties

GEO This converts to the coordinates property of the Address object. Also see to determine which Address object instance to convert to.

TZ A value of type TEXT converts to the timeZone property in the Address object. A value of type UTC-OFFSET converts to the timeZone property in the Address object if the offset has zero minutes and the hour offset is in the range -12 <= 14:

If the hour offset is zero, use the time zone name Etc/UTC.
Otherwise construct the time zone name with ETC/GMT suffixed with the string representation of the reversed sign hour offset, including the sign but excluding leading zeros and minutes. For example, the UTC offset value -0500 converts to ETC/GMT+5.

For such property values, also see to determine which Address object instance to convert to. Any other value of type UTC-OFFSET or URI does not convert to an IANA-registered property in JSContact. To convert such property, see .

Combining geographical properties In vCard the properties ADR, GEO and TZ occur independently of each other. In JSContact, they all convert to properties of an Address object. It is implementation-specific if these vCard properties convert to separate address instances in JSContact, or if some or all of them convert to the same address. That being said, implementations SHOULD convert the properties to the same address for the following cases:

The ALTID parameter values of the properties match.
The ALTID parameters are not set, but are set on any other ADR, GEO and TZ properties.

Organizational Properties

CONTACT-URI A CONTACT-URI property as defined in is represented as an entry of the links property (). 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 .

CONTACT-URI conversion example

LOGO A LOGO property converts to an entry in the media property (). 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 .

LOGO conversion example

MEMBER The uids of the contact cards composing the group are included in the members property (). In this case, the PREF parameter does not have a JSContact counterpart; however, the implementers MAY insert the map entries by order of preference.

Group example

ORG An ORG property converts to an entry in the organizations property (). The entry value is an Organization object whose name property contains the organizational name, and the units property is an array of OrgUnit objects each containing the organizational unit name in the name property. 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, LANGUAGE parameters convert according to the rules as 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 as defined in .

ORG conversion example

RELATED This converts to an entry in the relatedTo property (). The property value converts to the key in the relatedTo property. The TYPE parameters convert to the relation of the Relation object value. Any other parameters convert as defined in .

RELATED conversion example

TITLE and ROLE Both TITLE and ROLE properties are represented as entries of the titles property (). The entry value is a Title object whose type property is set to title or role for TITLE and ROLE vCard properties, respectively. The name property is set to the vCard property value. The value of the organization property can be derived if the TITLE or ROLE property is member of a vCard property group and exactly one other ORG property also is part of that group. The ALTID and LANGUAGE parameters convert according to the rules as defined in .

TITLE and ROLE conversion example

Personal Information Properties

EXPERTISE An EXPERTISE property as defined in is represented as a PersonalInfo object in the personalInfo property (). The type property is set to "expertise". The INDEX parameter converts according to the rules as defined in .

EXPERTISE conversion example

HOBBY A HOBBY property as defined in is represented as a PersonalInfo object in the personalInfo property (). The type property is set to "hobby". The INDEX parameter converts according to the rules as defined in .

HOBBY conversion example

INTEREST An INTEREST property as defined in is represented as a PersonalInfo object in the personalInfo property (). The type property is set to "interest". The INDEX parameter converts according to the rules as defined in .

INTEREST conversion example

ORG-DIRECTORY An ORG-DIRECTORY property as defined in is represented as an entry of the directories property (). 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 INDEX, PREF and TYPE parameters convert according to the rules as defined in .

ORG-DIRECTORY conversion example

Explanatory Properties

CATEGORIES A CATEGORIES property converts to a set of entries of the 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 implementers MAY insert the map entries by order of preference.

CATEGORIES conversion example

CLIENTPIDMAP and PID Parameter The CLIENTPIDMAP property and the PDI parameter don't have a direct match with a Card feature.

CREATED The CREATED property converts to the created property ().

CREATED conversion example Note: This property is defined in .

NOTE A NOTE property converts to a Note object in the notes map () The ALTID and LANGUAGE parameters convert according to the rules as defined in .

NOTE conversion example

PRODID The PRODID property converts to the prodId property ().

PRODID conversion example

REV The REV property converts to the updated property ().

REV conversion example

SOUND A SOUND property converts to an entry in the media property (). 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 .

SOUND conversion example

UID The UID property corresponds to the uid property ().

UID conversion example

URL An URL property converts to an entry in the links property (). 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 .

URL conversion example

VERSION The VERSION property doesn't have a direct match with a JSContact feature.

X-ABLabel This property is experimental 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. The group name is not preserved, implementations are free to choose any unique group name when converting back to vCard. For an example how to preserve the group name see .

X-ABLabel conversion example

Security Properties

KEY A KEY property converts to an entry in the cryptoKeys property (). 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 .

KEY conversion example

Calendar Properties

CALADRURI A CALADRURI property converts to an entry in the schedulingAddresses property (). The entry value is a SchedulingAddress object whose uri property is set to the CALADRURI value. The PREF parameter converts according to the rules as defined in .

CALADRURI conversion example

CALURI A CALURI property converts to an entry in the calendars property (). 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 .

CALURI conversion example

FBURL An FBURL property converts to an entry in the calendars property (). 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 .

FBURL conversion example

Extended Properties and Parameters These convert as specified in .

New JSContact properties vCards may contain properties or parameters for which no IANA-registered JSContact property is defined. For example, a vCard may contain extended properties and parameters of which the semantics or purposes are unknown . 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.

Property vCardProps

Name:: vCardProps
Type:: JCardProp[], where JCardProp denotes a jCard-encoded vCard property as defined in .
Definition:: This property is set on a JSContact object that represents a vCard. It contains properties that are set in the vCard represented by this JSContact object. Each entry in this list typically represents a vCard property for which no conversion to an IANA-registered JSContact property is defined. It MAY contain vCard IANA-registered properties which also got converted to an IANA-registered property in the same JSContact object. In case of conflict, the values of the JSContact property MUST be used.
Example:: This illustrates how to convert a vCard extension property:
JSContact props example

Property vCardParams

Name:: vCardParams
Type:: String[String|String[]]
Definition:: This property is set on a JSContact object that represents a vCard property. Its value MUST be a JSON object containing vCard property parameters, defined as array element 2 in . Each entry represents a parameter of the vCard property that converts to the JSContact object. Typically, these are parameters for which no IANA-registered property is defined in the JSContact object. It MAY contain vCard IANA-registered parameters which also got converted to an IANA-registered property in the same JSContact object. In case of conflict, the values of the JSContact property MUST be used.
Example:: converts to

Converting JSContact to vCard

Conversion Rules A Card converts to vCard by applying the reverse rules of converting vCard to JSContact. lists the relevant document sections for each JSContact object type and property. The following additional rules apply:

Multi-valued JSContact properties convert to separate instances of their equivalent vCard property, and for each the PROP-ID parameter MUST be set to the Id of the converted value (see ).
The fullName property in JSContact is optional, but it is mandatory in vCard. If the fullName is not set but the name property is, then implementations MAY derive the value of the FN property from it. In this case, they MUST set the DERIVED parameter on the FN property. Otherwise, they MUST set the FN property with an empty value.
Vendor-extension and unknown properties convert to vCard as outlined in section .

Conversion rules by JSContact property

JSContact Type	Property Name	Relevant Section(s)
Address	@type	not applicable
Address	contexts
Address	coordinates	,
Address	country
Address	countryCode
Address	fullAddress
Address	locality
Address	postcode
Address	pref
Address	region
Address	street
Address	timeZone	,
Anniversary	@type	not applicable
Anniversary	date
Anniversary	place
Anniversary	type
Author	@type	not applicable
Author	name
Author	uri
CalendarResource	@type	not applicable
CalendarResource	contexts
CalendarResource	label
CalendarResource	mediaType
CalendarResource	pref
CalendarResource	type	,
CalendarResource	uri	,
Card	@type	not applicable
Card	@version	not applicable
Card	addresses
Card	anniversaries
Card	calendars	,
Card	created
Card	directories	,
Card	emails
Card	fullName
Card	keywords
Card	kind
Card	links	,
Card	locale
Card	localizations
Card	media	, ,
Card	members
Card	name
Card	nickNames
Card	notes
Card	onlineServices
Card	organizations
Card	personalInfo	, ,
Card	phones
Card	preferredContactChannels
Card	preferredLanguages
Card	prodId
Card	relatedTo
Card	schedulingAddresses
Card	speakToAs
Card	titles
Card	uid
Card	updated
ContactChannelPreference	@type	not applicable
ContactChannelPreference	contexts
ContactChannelPreference	pref
CryptoResource	@type	not applicable
CryptoResource	contexts
CryptoResource	label
CryptoResource	mediaType
CryptoResource	pref
CryptoResource	type	not applicable
CryptoResource	uri
DirectoryResource	@type	not applicable
DirectoryResource	contexts
DirectoryResource	label
DirectoryResource	listAs
DirectoryResource	mediaType
DirectoryResource	pref
DirectoryResource	type	,
DirectoryResource	uri	,
EmailAddress	@type	not applicable
EmailAddress	address
EmailAddress	contexts
EmailAddress	label
EmailAddress	pref
LanguagePreference	@type	not applicable
LanguagePreference	contexts
LanguagePreference	pref
LinkResource	@type	not applicable
LinkResource	contexts
LinkResource	label
LinkResource	mediaType
LinkResource	pref
LinkResource	type	,
LinkResource	uri	, >
MediaResource	@type	not applicable
MediaResource	contexts
MediaResource	label
MediaResource	mediaType
MediaResource	pref
MediaResource	type	, ,
MediaResource	uri	, ,
Name	@type	not applicable
Name	components
Name	sortAs
NameComponent	@type	not applicable
NameComponent	rank
NameComponent	type
NameComponent	value
NickName	@type	not applicable
NickName	contexts
NickName	name
NickName	pref
Note	@type	not applicable
Note	author	,
Note	created
Note	note
OnlineService	@type	not applicable
OnlineService	contexts
OnlineService	label
OnlineService	pref
OnlineService	service
OnlineService	type	,
OnlineService	user	,
OrgUnit	@type	not applicable
OrgUnit	name
OrgUnit	sortAs
Organization	@type	not applicable
Organization	contexts
Organization	name
Organization	sortAs
Organization	units
PartialDate	@type	not applicable
PartialDate	calendarScale
PartialDate	day
PartialDate	month
PartialDate	year
PatchObject	@type	not applicable
PersonalInfo	@type	not applicable
PersonalInfo	listAs
PersonalInfo	level
PersonalInfo	type	, ,
PersonalInfo	value	, ,
Phone	@type	not applicable
Phone	contexts
Phone	features
Phone	label
Phone	number
Phone	pref
Pronouns	@type	not applicable
Pronouns	contexts
Pronouns	pref
Pronouns	pronouns
Relation	@type	not applicable
Relation	relation
Resource	@type	not applicable
SchedulingAddress	@type	not applicable
SchedulingAddress	contexts
SchedulingAddress	label
SchedulingAddress	pref
SchedulingAddress	uri
SpeakToAs	@type	not applicable
SpeakToAs	grammaticalGender
SpeakToAs	pronouns
StreetComponent	@type	not applicable
StreetComponent	type
StreetComponent	value
Timestamp	@type	not applicable
Timestamp	utc
Title	@type	not applicable
Title	name
Title	organization
Title	type

New vCard Properties and Parameters JSContact object types may contain properties for which no IANA-registered vCard property is defined. For example, a JSContact object may contain vendor-specific properties of which the semantics or purpose are unknown. This section defines new vCard properties and parameters by which such JSContact properties MAY be represented in JSContact. Implementations MAY choose to convert differently if they deem that more appropriate.

Property JSCONTACT-PROP

Property name:: JSCONTACT-PROP
Purpose:: This property represents a JSContact property in vCard.
Value type:: TEXT, also see Format Definition for value restrictions.
Conformance:: The property can be specified multiple times in a vCard.
Property parameters:: The JSPTR parameter MUST be set exactly once for this property. The VALUE parameter MAY be set once, in which case its value MUST be URI. Other IANA-registered and experimental property parameters can be specified on this property.
Description:: This property converts a JSContact property 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 SHOULD be compact, e.g. without insignificant whitespace. The value of the JSPTR parameter defines the path to that JSContact value within the Card. The last segment of the JSON pointer either defines the property name or array position of the JSContact value. The root of the JSON pointer always is the Card object that this vCard converts to, irrespective if the JSON pointer starts with the SOLIDUS (U+002F) character. If any but the last segment of the JSON pointer points to a non-existent JSContact property or array entry in the Card, then the JSCONTACT-PROP property MUST be ignored and SHOULD be discarded from the vCard.
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-extension 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-extension conversion example
This illustrates how to convert a vendor-extension 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 property example with path relative to Card

Parameter JSPTR

Parameter name:: JSPTR
Purpose:: This parameter contains a JSON pointer that relates its vCard property to some JSON data. Its exact semantics depend on the definition of the property where this parameter is set on.
Description:: This parameter has a single value that MUST be a valid JSON pointer as defined in . Currently, its semantics only are defined for the JSCONTACT-PROP property (see ), but it may also be used for other use cases in the future.
Format definition:
Example(s):: This illustrates a simple example. For further examples see .

Property Name	Property Type	Property Context	Reference or Description	Intended Usage	Since Version	Until Version	Change Controller
vCardParams	String[String]	Any JSContact object type that contains the `@type` property.		common	1.0		IETF
vCardProps	JCardProp[]	Card		common	1.0		IETF