]> IIT-CNR/Registro.it

Via Moruzzi,1 Pisa IT 56124 mario.loffredo@iit.cnr.it http://www.iit.cnr.it

FastMail

PO Box 234, Collins St West Melbourne AU VIC 8007 rsto@fastmailteam.com https://www.fastmail.com

Applications jmap JSON contacts vCard jCard This document defines how to convert contact information as defined in the JSContact specification from and to vCard.

The JSContact specification has been defined to represent contact card information as a more efficient alternative to vCard and its JSON-based version named jCard . While new applications might adopt JSContact as their main format to exchange contact card data, they are likely to interoperate with services and clients that just support vCard/jCard. Similarly, existing contact data providers and consumers already using vCard/jCard might want to represent their data also according to the JSContact specification. To facilitate this, this document defines how to convert contact information as defined in the JSContact specification from and to vCard.

JSContact and vCard have a lot of semantics in common, however some differences must be outlined: The JSContact data model defines some contact information that doesn't have a direct mapping with vCard properties. In particular, unlike vCard, JSContact distinguishes between a single contact card, named JSCard, and a group of contact cards, named JSCardGroup. The properties that can be present multiple times in a vCard are represented through different collections in JSContact; mainly as maps, sometimes as lists, in some cases condensed in a single value.

While translating vCard properties to JSContact, any vCard property that doesn't have a direct counterpart in JSContact MUST be converted into a property whose name is prefixed by "ietf.org/<RFC defining the extension>/". Any custom extension MAY be added and its name MUST be prefixed with a specific domain name to avoid conflict, e.g. "example.com/customprop". Similarly, the reversed rules are applied while translating JSContact properties to vCard.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in . In the following of this document, the vCard features, namely properties and parameters, are written in uppercase while the JSCard/JSCardGroup features are written in camel case wrapped in double quotes.

This section contains the translation rules from vCard to JSCard/JSCardGroup. The vCard properties are grouped according to the categories as defined in .

The following mapping rules apply to parameters that are common to most of the vCard properties: The generic values of the TYPE parameter are mapped onto the values of the "Context" type as defined in Section 1.5.1 of . The "home" value corresponds to the "private" key. The mapping of those specific TYPE values used in the TEL and RELATED properties are defined in the following of the document. The PREF parameter is mapped onto the "pref" property. The MEDIATYPE parameter is mapped onto the "mediaType" property. 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. The ALTID and LANGUAGE parameters are used in combination for associating the language-dependent alternatives with a given property. Such alternatives are represented by using the "localizations" map of a "LocalizedString" member inside the matching JSContact object. The LEVEL parameter as defined in is directly mapped onto the "level" property of the "PersonalInformation" type apart from when LEVEL is used in the EXPERTISE property; in this case, the values are converted as in the following: "beginner" is converted into "low"; "average" is converted into "medium"; "expert" is converted into "high".

The rules to generate a map key of type Id are out of the scope of this document.

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

A SOURCE property is represented as an entry of the "online" map (). The entry value is a "Resource" object whose "type" member is set to "uri", the "label" member is set to "source" and the "resource" member is the SOURCE value. The PREF and MEDIATYPE parameters are mapped according to the rules as defined in ().

The KIND property is mapped onto the "kind" member (). Allowed values are those described in Section 6.1.4 of and extended with the values declared in and . The value "group" is reserved for a JSCardGroup instance.

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

All the FN instances are globally represented through the "fullName" member. The presence of multiple instances 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 ().

The N instances 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 instance is mapped onto an item of "nickNames" array. N component "type" value Honorific Prefixesprefix Given Namespersonal Family Namessurname Additional Namesadditional Honorific Suffixessuffix

A PHOTO property is represented as an entry of the "photos" map (). The entry value is a "File" object whose "href" member is the PHOTO value. The PREF and MEDIATYPE parameters are mapped according to the rules as defined in ().

The BDAY and ANNIVERSARY properties 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. The BIRTHPLACE and DEATHPLACE properties 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 ALTID and LANGUAGE parameters of both BIRTHPLACE and DEATHPLACE properties are mapped according to the rules as defined in (). The "fullAddress.localizations" includes possible language-dependent alternatives.

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

An ADR property is represented as an entry of the "addresses" map (). The entry value is an "Address" object. 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 GEO parameter is converted into the "coordinates" member. The TZ parameter is converted into the "timeZone" member. The CC parameter as defined in is converted into the "countryCode" member. The PREF and TYPE parameters are mapped according to the rules as defined in (). The ALTID and LANGUAGE parameters are mapped according to the rules as defined in (). The "fullAddress.localizations" includes possible language-dependent alternatives.

A TEL property is represented as an entry of the "phones" map (). The entry value is a "Phone" object. The TEL-specific values of the TYPE parameter are mapped onto the "features" map keys. The values that don't match a key are represented as comma-separated values of the "label" member. If the "features" map is empty and the "label" member is not empty, the "other" feature is added. The "phone" member is set to the TEL value. The PREF and TYPE parameters are mapped according to the rules as defined in ().

An EMAIL property is represented as an entry of the "emails" map (). The entry value is an "EmailAddress" object. The "email" member is set to the EMAIL value. The PREF and TYPE parameters are mapped according to the rules as defined in ().

An IMPP property is represented as an entry of the "online" map (). The entry value is a "Resource" object whose "type" member is set to "username", the "label" member is set to "XMPP" and the "resource" member is the IMPP value. The PREF and TYPE parameters are mapped according to the rules as defined in ().

A LANG property is represented as an entry of the "preferredContactLanguages" map (). The entry keys correspond to the language tags, the corresponding entry values are arrays of "ContactLanguage" objects. The PREF and TYPE parameters are mapped according to the rules as defined in (). If both PREF and TYPE parameters are missing, the array of "ContactLanguage" objects MUST be empty.

The GEO and TZ properties are not directly mapped onto topmost JSCard/JSCardGroup members because the same information is represented through equivalent "Address" members. The ALTID parameter is used for associating both GEO and TZ properties with the related address information. When the ALTID parameter is missing, the matched members SHOULD be included in the first "Address" object.

As specified in Section 6.5.1 of , the time zone information can be represented in three ways: as a time zone name, as a UTC offset or as a 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 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 IANA time zone , this latter SHOULD be used. Otherwise, the URI value is dumped into a string.

Both TITLE and ROLE properties are represented as entries of the "titles" map (). The entry value is a "Title" object whose "title" member includes information about the language. The ALTID and LANGUAGE parameters are mapped according to the rules as defined in (). The "title.localizations" includes possible language-dependent alternatives.

A LOGO property is represented as an entry of the "online" map (). The entry value is a "Resource" object whose "type" member is set to "uri", the "label" member is set to "logo" and the "resource" member is the LOGO value. The PREF and TYPE parameters are mapped according to the rules as defined in ().

An ORG property is represented as an entry of the "organizations" map (). The entry value is an "Organization" object whose "name" member contains the organizational name and the "units" member contains the organizational units. The ALTID and LANGUAGE parameters are mapped according to the rules as defined in (). The "localizations" maps for both "name" and "units" include possible language-dependent alternatives.

According to the JSContact specification, a group of contact cards is represented through a JSCardGroup (). The uids of the contact cards composing the group are included in the "members" map. In this case, the PREF parameter has not a JSContact counterpart; however, the implementers MAY insert the map entries by order of preference.

All the RELATED instances 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 the RELATED-specific values of the TYPE parameter as defined in Section 6.6.6 of . If the relation type is unspecified, the "relation" member MUST be empty.

A CONTACT-URI property as defined in is represented as an entry of the "online" map (). The entry value is a "Resource" object whose "type" member is set to "uri", the "label" member is set to "contact-uri" and the "resource" member is the CONTACT-URI value. The PREF and TYPE parameters are mapped according to the rules as defined in ().

An EXPERTISE property as defined in is represented as a "PersonalInformation" object in the "personalInfo" array (). The "type" member is set to "expertise". The INDEX parameter is represented as the index of the expertise among the declared expertises. The LEVEL parameter is mapped according to the rules as defined in ().

A HOBBY property as defined in is represented as a "PersonalInformation" object in the "personalInfo" array (). The "type" member is set to "hobby". The INDEX parameter is represented as the index of the hobby among the declared hobbies. The LEVEL parameter is mapped according to the rules as defined in ().

An INTEREST property as defined in is represented as a "PersonalInformation" object in the "personalInfo" array (). The "type" member is set to "interest". The INDEX parameter is represented as the index of the interest among the declared interests. The LEVEL parameter is mapped according to the rules as defined in ().

An ORG-DIRECTORY property is represented as an entry of the "online" map (). The entry value is a "Resource" object whose "type" member is set to "uri", the "label" member is set to "org-directory" and the "resource" member is the ORG-DIRECTORY value. The PREF and TYPE parameters are mapped according to the rules as defined in (). The INDEX parameter is represented as the index of the directory among the online resources with the "org-directory" label.

A CATEGORIES property is converted into a set of entries of the "categories" map (). The keys are the comma-separated text values of the CATEGORIES property. In this case, the PREF parameter has not a JSContact counterpart; however, implementers MAY use a map preserving the order of insertion and the map entries can be inserted by order of preference.

A NOTE property is mapped onto the "notes" property (). All the NOTE instances are condensed in a single note and separated by newline. The ALTID and LANGUAGE parameters are mapped according to the rules as defined in (). The "localizations" map includes possible language-dependent alternatives.

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

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

A SOUND property is represented as an entry of the "online" map (). The entry value is a "Resource" object whose "type" member is set to "uri", the "label" member is set to "sound" and the "resource" member is the SOUND value. The PREF and TYPE parameters are mapped according to the rules as defined in ().

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

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

An URL property is represented as an entry of the "online" map (). The entry value is a "Resource" object whose "type" member is set to "uri", the "label" member is set to "url" and the "resource" member is the URL value. The PREF and TYPE parameters are mapped according to the rules as defined in ().

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

A KEY property is represented as an entry of the "online" map (). The entry value is a "Resource" object whose "type" member is set to "uri", the "label" member is set to "key" and the "resource" member is the KEY value. The PREF and TYPE parameters are mapped according to the rules as defined in ().

An FBURL property is represented as an entry of the "online" map (). The entry value is a "Resource" object whose "type" member is set to "uri", the "label" member is set to "fburl" and the "resource" member is the FBURL value. The PREF and TYPE parameters are mapped according to the rules as defined in ().

A CALADRURI property is represented as an entry of the "online" map (). The entry value is a "Resource" object whose "type" member is set to "uri", the "label" member is set to "caladruri" and the "resource" member is the CALADRURI value. The PREF and TYPE parameters are mapped according to the rules as defined in ().

A CALURI property is represented as an entry of the "online" map (). The entry value is a "Resource" object whose "type" member is set to "uri", the "label" member is set to "caluri" and the "resource" member is the CALURI value. The PREF and TYPE parameters are mapped according to the rules as defined in ().

The unmatched vCard properties MAY be converted into JSContact properties whose name contains the prefix "ietf.org/RFC6350/" followed by property name in uppercase (i.e. ietf.org/RFC6350/GENDER").

While converting a vCard into a JSCard/JSCardGroup, only the topmost "uid" member is mandatory. Implementers are REQUIRED to set it when it is missing.

In most of the cases, the rules about the translation from JSCard/JSCardGroup to vCard can be derived by reversing the rules presented in . The remaining cases are treated in the following of this section.

Where a map key is of type Id, implementers are free to either ignore it or preserve it as a vCard information (e.g. a vCard parameter).

A LocalizedString object is converted in multiple instances of the same vCard property having different values of the LANGUAGE parameter. Implementers MAY set the ALTID parameter to couple language-based alternatives of the same value. Note also that the components of some vCard values and their related alternatives are split into different JSContact values. For example, the "name" and "units" values for a given language must be grouped to make a single ORG value where components are separated by ";".

The JSContact spec defines the "UTCDateTime" type to represent "date-time" format with further restrictions. This means that the matched vCard format for a "UTCDateTime" value MUST be one of the formats shown in Section 4.3.5 of (i.e. "19961022T140000Z"). In addition to such format, the "date" member of the "Anniversary" type allows specifying both a date without the time and a partial date. In this case, the corresponding vCard format is that defined in Section 4.3.1.

The time zone name as represented by the "timeZone" property is mapped onto the TZ parameter. Implementers MAY map an "Etc/GMT" time zone either preserving the time zone name or converting it into a UTC offset.

The "titles" property contains information about the job, the position or the role of the entity the card represents. In vCard, such information is split into the TITLE and ROLE properties. This specification defines TITLE as the default target property when converting the "titles" property.

The "online" property includes resources that are usually represented through different vCard properties. The matched vCard property of a "Resource" object can be derived from the value of its "label" member. Any resource included in the "online" map that doesn't match a vCard property MAY be converted into vCard extended properties.

Both the "preferredContactMethod" and "created" members don't match any vCard property. Implementers MAY represent them as vCard extended properties.

While converting a JSCard/JSCardGroup into a vCard, only the FN property is required. Since the "fullName" property is optional, implementers are REQUIRED to generate an FN value when it is missing.

This document has no actions for IANA.

NOTE: Please remove this section and the reference to RFC 7942 prior to publication as an RFC. This section records the status of known implementations of the protocol as defined in this specification at the time of posting of this Internet-Draft, and is based on a proposal described in . The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist. According to RFC 7942, "this will allow reviewers and working groups to assign due considerationto documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit".

Responsible Organization: National Research Council (CNR) of Italy Location: https://github.com/consiglionazionaledellericerche/jscontact-tools Description: This implementation includes tools for JSContact creation, validation, serialization/deserialization, and conversion from vCard, xCard and jCard. Level of Maturity: This is an "alpha" test implementation. Coverage: This implementation includes all of the features described in this specification. Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it

This document doesn't present any security consideration.

&RFC2119; &RFC3339; &RFC6350; &RFC6473; &RFC6474; &RFC6715; &RFC6869; &RFC7095; &RFC7942; &RFC8605;