JSContact: Converting from and to vCard

This section contains the mapping between vCard and JSCard. The vCard properties are grouped according to the categories defined by . Where it is needed, the JCardGroup is taken into account. In the following of this document, the vCard features, namely properties and parameters, are written in uppercase while the JSCard features are written in camel case.

The BEGIN and END properties don't have a direct match with a JSCard feature.

A SOURCE element is represented as a "Resource" object in the "online" array () whose "type" member is set to "uri" and "labels" map contains the entry <"source",true>. The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" and "mediaType" members respectively.

The KIND element is mapped onto the "kind" member (). Allowed values are those, except "group", described in section 6.1.4 of and extended with the values declared in and . A group of cards is represented through a JSCardGroup.

The XML property doesn't have a direct match with a JSCard feature.

All the FN elements are globally represented through the "fullName" member. The presence of more than one name is implicitly associated with the full name translations in various languages regardless of the presence of the ALTID parameter. Each translation corresponds to a different entry of the "localizations" map ().

Both the N and NICKNAME elements are converted into equivalent items of the "name" array (): the N components are transformed 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 NICKNAME element is mapped onto an object whose "type" member is set to "nickname" N component "type" value Honorific Prefixesprefix Given Namespersonal Family Namessurname Additional Namesadditional Honorific Suffixessuffix

A PHOTO element is represented as a "Resource" object in the "online" array () whose "type" member is set to "uri" and "labels" map contains the entry <"photo",true>. The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" and "mediaType" members respectively.

The BDAY and ANNIVERSARY elements and the extensions BIRTHPLACE, DEATHDATE, DEATHPLACE described in are represented as "Anniversary" objects included in the "anniversaries" array (): BDAY and BIRTHPLACE are mapped onto "date" and "place" where "type" is set to "birth"; DEATHDATE and DEATHPLACE are mapped onto "date" and "place" where "type" is set to "death"; ANNIVERSARY is mapped onto "date" where "type" is set to "other" and "label" is set to a value describing in detail the kind of anniversary (e.g. "marriage date" for the wedding anniversary). Both birth and death places are represented as instances of the "Address" object. BIRTHPLACE and DEATHPLACE that are represented as geo URIs are converted into "Address" instances including only the "coordinates" member. If the URI value is not a geo URI, the place is ignored. The LANGUAGE parameter values of both BIRTHPLACE and DEATHPLACE elements are represented as corresponding entries of the "fullAddress.localizations" map.

TBD

An ADR element is represented as an "Address" object in the "addresses" array (). The ADR components are transformed into the "Address" members as presented in . ADR component Address member p.o. boxpostOfficeBox extended addressextension street addressstreet localitylocality regionregion postal codepostcode country namecountry The LABEL parameter is converted into the "fullAddress" member. The PREF parameter is converted into the "isPreferred" member. The GEO parameter is converted into the "coordinates" member. The TZ parameter is converted into by the "timeZone" member. The TYPE parameter is converted into the "context" member. The "home" value is replaced with the "private" value. The LANGUAGE parameter values are represented as different entries of the "fullAddress.localizations" map. The CC parameter defined by is converted into the "countryCode" member.

A TEL element is represented as a "Resource" object in the "phones" array (). The vCard "type-param-tel" values are mapped onto the "type" member values. Those vCard "type-param-tel" values that don't have a counterpart among the "type" member values are represented as entry keys of the "labels" map with the corresponding entry value set to true. The "type-param" values are are mapped onto the "context" member values. The "home" value is replaced with the "private" value. The PREF parameter is mapped onto the "isPreferred" member.

An EMAIL element is represented as a "Resource" object in the "emails" array (). The vCard "type-param" values are mapped onto the "context" member values. The "home" value is replaced with the "private" value. The PREF parameter is mapped onto the "isPreferred" member.

An IMPP element is represented as a "Resource" object in the "online" array () whose "type" member is set to "username" and "labels" map contains the entry <"XMPP",true>. In case of a contact card related to an acconunt on another online service, the entry key SHOULD be the canonical service name, including capitalisation (e.g. "Twitter", "Facebook", "Skype", "GitHub") The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" and "mediaType" members respectively.

A LANG element is represented through the "preferredContactLanguages" map (): an entry for each language that may be used for contacting the entity associated with the JSCard. The entry keys correspond to the language tags, the corresponding entry values are arrays of "ContactLanguage" objects. The TYPE and PREF parameters are mapped onto the "ContactLanguage" members "type" and "preference" respectively. If both PREF and TYPE parameters are missing, the array of "ContactLanguage" objects MUST be empty.

The GEO and TZ elements are not directly mapped into equivalent topmost JSCard members because the same information is represented through equivalent "Address" members. The ALTID parameter is used for associating both GEO and TZ elements with the related address information. When the ALTID parameter is missing, the element should be associated with the first contact address.

A TITLE element is mapped onto a "LocalizedString" object included in the "jobTitle" array (). The ALTID parameter is used for for associating the language-dependent alternatives with a given element. The LANGUAGE parameter values are represented as corresponding entries of the "localizations" map.

A ROLE element is mapped onto a "LocalizedString" object included in the "role" array (). The ALTID parameter is used for for associating the language-dependent alternatives with a given element. The LANGUAGE parameter values are represented as corresponding entries of the "localizations" map.

A LOGO element is represented as a "Resource" object in the "online" array () whose "type" member is set to "uri" and "labels" map contains the entry <"logo",true>. The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" and "mediaType" members respectively.

An ORG element is mapped onto a "LocalizedString" object included in the "organization" array (). The organization name includes the organizational units if any. The ALTID parameter is used for for associating the language-dependent alternatives with a given element. The LANGUAGE parameter values are represented as corresponding entries of the "localizations" map.

According to the JSContact specification, a group of contact cards is represented through a JSCardGroup (). The contact cards composing the group are included in the "cards" array. Therefore, the MEMBER element doesn't have a direct match with a JSCard feature.

All the RELATED elements are globally converted into the "relatedTo" map (): an entry for each entity the entity described by the JSCard is associated with. The map keys are the "uid" values of the associated cards. Each map value is a "Relation" object including only the "relation" member represented as a set of relation types described in section 6.6.6 of . If the relation type is unspecified, the "relation" is empty.

A CONTACT-URI element defined by is represented as a "Resource" object of the "online" array () whose "type" member is set to "uri" and "labels" map contains the entry <"contact-uri",true>. The PREF parameter is mapped onto the "isPreferred" member.

An EXPERTISE element defined by is represented as a "PersonalInformation" object in the "personalInfo" array (). The "type" member is set to "expertise". The LEVEL parameter is mapped onto the "level" member with following mapping: "beginner" is converted into "low"; "average" is converted into "medium"; "expert" is converted into "high". The INDEX parameter is represented as the index of the expertise among the declared expertises.

An HOBBY element defined by is represented as a "PersonalInformation" object in the "personalInfo" array (). The "type" member is set to "hobby". The LEVEL parameter is mapped onto the "level" member with a direct mapping. The INDEX parameter is represented as the index of the hobby among the declared hobbies.

An INTEREST element defined by is represented as a "PersonalInformation" object in the "personalInfo" array (). The "type" member is set to "interest". The LEVEL parameter is mapped onto the "level" member with a direct mapping. The INDEX parameter is represented as the index of the interest among the declared interests.

An ORG-DIRECTORY element is represented as a "Resource" object in the "online" array () whose "type" member is set to "uri" and "labels" map contains the entry <"org-directory",true>. The PREF parameter is mapped onto the "isPreferred" member. The INDEX parameter is represented as the index of the directory among the online resources with the "org-directory" key in the "labels" map.

A CATEGORIES element is converted into an object in the "categories" array ().

A NOTE element is mapped onto a "LocalizedString" object included in the "notes" array (). The ALTID parameter is used for associating the language-dependent alternatives with a given element. The LANGUAGE parameter values are represented as corresponding entries of the "localizations" map.

The PRODID element is converted into the "prodId" member ().

The REV element is transformed into the "updated" member ().

A SOUND element is represented as a "Resource" object in the "online" array () whose "type" member is set to "uri" and "labels" map contains the entry <"sound",true>. The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" and "mediaType" members respectively.

The UID element corresponds to the "uid" member ().

TBD

An URL element is represented as a "Resource" object in the "online" array () whose "type" member is set to "uri" and "labels" map contains the entry <"url",true>. The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" and "mediaType" members respectively.

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

A KEY element is represented as a "Resource" object in the "online" array () whose "type" member is set to "uri" and "labels" map contains the entry <"key",true>. The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" and "mediaType" members respectively.

A FBURL element is represented as a "Resource" object of the "online" array () whose "type" member is set to "uri" and "labels" map contains the entry <"fburl",true>. The PREF and MEDIATYPE parameters are mapped ontoy the "isPreferred" and "mediaType" members respectively.

A CALADRURI element is represented as a "Resource" object of the "online" array () whose "type" member is set to "uri" and "labels" map contains the entry <"caladruri",true>. The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" and "mediaType" members respectively.

A CALURI element is represented as a "Resource" object of the "online" array () whose "type" member is set to "uri" and "labels" map contains the entry <"caluri",true>. The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" and "mediaType" members respectively.

As described in section 5.7 of , the media type of a resource can be identified by its URI. For example, "image/gif" can be derived from the ".gif" extension of a GIF image URI. JSContact producers MAY provide the media type information even when it is not specified in the vCard.

As specified in section 6.5.1 of , the time zone information can be represented in three ways: as a time zone name, as an UTC offset or as an URI. The time zone name is directly matched by the "timeZone" member in JSContact. An UTC offset MUST be converted into the related "Etc/GMT" time zone (e.g. the value "-0500" converts to "Etc/GMT+5"). If the UTC offset value contains minutes information, it MUST be mapped to map it to the zone "Etc/GMT<sign><hour>:<minute>". Since there is no URI scheme defined for time zones , any implementation that does use some a custom URI for a time zone is not interoperable anyway. In this case, if the URI corresponds to an a IANA time zone , this latter SHOULD be used. Otherwise, the URI value is dumped into a string.

If an extended property is a resource, JSCard already allows to represent it by setting the "type" member to "other" and specifying a value for the "labels" map. Any other property supporting a custom feature MAY be added and its name MUST be prefixed with a specific domain name to avoid conflict, e.g. "example.com/customprop".

Any vCard property that doesn't have a direct counterpart in JSContact is treated as an extended property whose name is prefixed by "ietf.org/rfc6350/". The resulting name MUST be in lowercase.

While converting a vCard into a JSCard, only the topmost "uid" member is required.

The "preferredContactMethod" member doesn't match any vCard element.