JSContact: Converting from and to vCard

2.2.1. ALTID

The ALTID parameter [RFC6350] (Section 5.4) does not convert to JSContact, but several conversion rules make use of this parameter to combine multiple vCard properties into one JSContact object. For an example of this, see Section 2.3.1.¶

2.2.2. AUTHOR

The AUTHOR parameter [RFC9554] (Section 4.1) on a NOTE property converts to the "uri" property of the Author object [RFC9553] (Section 2.8.3). That Author object is set as the value of the "author" property of the Note object [RFC9553] (Section 2.8.3).¶

2.2.3. AUTHOR-NAME

The AUTHOR-NAME parameter [RFC9554] (Section 4.2) on a NOTE property converts to the "name" property of the Author object [RFC9553] (Section 2.8.3). That Author object is set as the value of the "author" property of the Note object.¶

2.2.4. CALSCALE

The CALSCALE parameter [RFC6350] (Section 5.8) set on a BDAY, DEATHDATE, or ANNIVERSARY property converts to the "calendarScale" property of the PartialDate object [RFC9553] (Section 2.8.1).¶

2.2.5. CC

The CC parameter [RFC8605] (Section 3.1) on an ADR property converts to the "countryCode" property of the Address object [RFC9553] (Section 2.5.1.1).¶

2.2.6. CREATED

The CREATED parameter [RFC9554] (Section 4.3) on a NOTE property converts to the "created" property of the Note object [RFC9553] (Section 2.8.3).¶

2.2.7. DERIVED

The DERIVED parameter [RFC9554] (Section 4.4) does not convert to JSContact. If the DERIVED parameter is set to "true" on a vCard property, then implementations MUST NOT convert that property to JSContact.¶

2.2.8. GEO

The GEO parameter [RFC6350] (Section 5.10) set on an ADR property converts to the "coordinates" property of the Address object [RFC9553] (Section 2.5.1.1). Also see the conversion of the GEO property in Section 2.3.18.¶

2.2.9. GROUP

The GROUP parameter [RFC7095] (Section 3.3.1.2) 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 VCardProperty object's "parameters" property (Section 4.1.1).¶

The following examples illustrate how to convert the GROUP parameter:¶

item1.TEL;VALUE=uri:tel:+1-555-555-5555
item1.X-ABLabel:Test

"phones": {
  "p1": {
    "number": "tel:+1-555-555-5555",
    "label": "test"
  }
},
"vCard": {
  "convertedProperties": {
    "phones/p1/number": {
      "name": "tel",
      "parameters": {
        "group": "item1"
      }
    },
    "phones/p1/label": {
      "name": "x-ablabel",
      "parameters": {
        "group": "item1"
      }
    }
  }
}

item2.X-FOO:bar

"vCard": {
  "properties": [
    ["x-foo", {
      "group": "item2"
    }, "unknown", "bar"]
  ]
}

2.2.10. INDEX

The INDEX parameter [RFC6715] (Section 3.1) set on the EXPERTISE, HOBBY, INTEREST, and ORG-DIRECTORY properties converts to the PersonalInfo (Section 2.8.4 of [RFC9553]) and Directory (Section 2.6.2 of [RFC9553]) objects' "listAs" property.¶

2.2.11. LANGUAGE

The LANGUAGE parameter [RFC6350] (Section 5.1) converts to an entry in the Card object's "localizations" property (Section 2.7.1 of [RFC9553]) 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 [I-D.ietf-calext-jscontact-profiles] 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. Figure 8 illustrates this.¶

The following examples illustrate how to convert the LANGUAGE parameter:¶

FN;LANGUAGE=EN:John Doe
TITLE;ALTID=1;LANGUAGE=EN:Boss
TITLE;ALTID=1;LANGUAGE=fr:Patron

"language": "en",
"name": {
  "full": "John Doe"
},
"titles": {
  "t1": {
    "name": "Boss"
  }
},
"localizations": {
  "fr": {
    "titles/t1/name": "Patron"
  }
}

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. Figure 9 illustrates this.¶

FN:John Doe
TITLE;ALTID=1:Boss
TITLE;ALTID=1;LANGUAGE=fr:Patron

"name": {
  "full": "John Doe"
},
"titles": {
  "t1": {
    "name": "Boss"
  }
},
"localizations": {
  "fr": {
    "titles/t1/name": "Patron"
  }
}

2.2.12. LABEL

The LABEL parameter [RFC6350] (Section 6.3.1) on an ADR property converts to the "full" property of the Address object [RFC9553] (Section 2.5.1).¶

2.2.13. LEVEL

The LEVEL parameter [RFC6715] (Section 3.2) converts to the "level" property of the PersonalInfo object [RFC9553] (Section 2.8.4). 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.¶

2.2.14. MEDIATYPE

The MEDIATYPE parameter [RFC6350] (Section 5.7) converts to the "mediaType" property of the Resource object [RFC9553] (Section 1.4.4).¶

2.2.15. PHONETIC

The PHONETIC parameter [RFC9554] (Section 4.6) converts to the Name (Section 2.2.1 of [RFC9553]) and Address (Section 2.5.1 of [RFC9553]) 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 Section 2.2.15).¶

The related N or ADR property is defined by the vCard ALTID parameter. The conversion rules for the N (Section 2.3.29) and ADR (Section 2.3.1) 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 Section 2.2.11.¶

The following example illustrates how to convert the PHONETIC parameter:¶

LANGUAGE=zh-Hant
N;ALTID=1;LANGUAGE=zh-Hant:孫;中山;文,逸仙;;
N;ALTID=1;PHONETIC=jyut;
  SCRIPT=Latn;LANGUAGE=yue:syun1;zung1saan1;man4,jat6sin1;;

"language": "zh-Hant",
"name": {
  "components": [
    { "kind": "surname", "value": "孫" },
    { "kind": "given", "value": "中山" },
    { "kind": "given2", "value": "文" },
    { "kind": "given2", "value": "逸仙" }
  ]
},
"localizations": {
  "yue": {
    "name/phoneticSystem": "jyut",
    "name/phoneticScript": "Latn",
    "name/components/0/phonetic": "syun1",
    "name/components/1/phonetic": "zung1saan1",
    "name/components/2/phonetic": "man4",
    "name/components/3/phonetic": "jat6sin1"
  }
}

2.2.16. PID

The PID parameter [RFC6350] (Section 5.5) does not convert to JSContact.¶

2.2.17. PREF

The PREF parameter [RFC6350] (Section 5.3) converts to the "pref" property of that JSContact object, to which the vCard property having this parameter converts.¶

2.2.18. PROP-ID

The PROP-ID parameter [RFC9554] (Section 4.7) is deprecated. The JSID (Section 5.1.2) 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.¶

The following example illustrates how to convert the PROP-ID parameter:¶

TEL;PROP-ID=xyz;VALUE=uri:tel:+1-555-555-5555;ext=5555

"phones": {
  "xyz": {
    "number": "tel:+1-555-555-5555;ext=5555"
  }
}

2.2.19. SCRIPT

The SCRIPT parameter [RFC9554] (Section 4.8) converts to the Name (Section 2.2.1 of [RFC9553]) or Address (Section 2.5.1 of [RFC9553]) objects' "phoneticScript" property. Also see Section 2.2.15.¶

2.2.20. SERVICE-TYPE

The SERVICE-TYPE parameter [RFC9554] (Section 4.9) converts to the "service" property of the OnlineService object [RFC9553] (Section 2.3.2).¶

2.2.21. SORT-AS

The SORT-AS parameter [RFC6350] (Section 5.9) converts to the Name, Organization, and OrgUnit objects' "sortAs" properties.¶

2.2.22. TYPE

The TYPE parameter [RFC6350] (Section 5.6) 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.¶

2.2.23. TZ

The TZ parameter [RFC6350] (Section 5.11) on an ADR property converts to the "timeZone" property of the Address object [RFC9553] (Section 2.5.1). Also see the conversion of the TZ property in Section 2.3.45.¶

2.2.24. USERNAME

The USERNAME parameter [RFC9554] (Section 4.10) converts to the "user" property of the OnlineService object [RFC9553] (Section 2.3.2).¶

2.2.25. VALUE

The VALUE parameter [RFC6350] (Section 5.2) does not convert to JSContact.¶

2.3.1. ADR

The ADR property [RFC6350] (Section 6.3.1) converts to an Address object [RFC9553] (Section 2.5.1). The converted object is set in the "addresses" property of the Card object. The ADR property value converts to the "components" property of the Address object.¶

Each component in the structured value of the ADR property converts to an AddressComponent. The component value converts to the AddressComponent object's "value" property, the component position determines the value of the AddressComponent object's "kind" property as follows:¶

If the JSCOMPS (Section 5.1.1) 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 (Section 2.3.18) and TZ property (Section 2.3.45) 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 Section 2.2. The ADR-specific values of the TYPE parameter defined in Sections 5.1 and 5.2 of [RFC9554] convert to the corresponding entries of the "contexts" property as defined in Section 2.5.1 of [RFC9553].¶

The ALTID and LANGUAGE parameters convert according to the rules defined in Section 2.2. Each possible language-dependent alternative converts to an entry of the PatchObject where the key references the "full" property.¶

The path of the ADR property in the "convertedProperties" property (Section 4.1.1) is "addresses/{id}/components", where "{id}" denotes the identifier of the Address object.¶

The following example illustrates how to convert the ADR property:¶

ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA;;;;54321;Oak St;;;;;;

"addresses": {
  "ADDR-1" : {
    "contexts": { "work": true },
    "components": [
      { "kind": "number", "value": "54321" },
      { "kind": "name", "value": "Oak St" },
      { "kind": "locality", "value": "Reston" },
      { "kind": "region", "value": "VA" },
      { "kind": "postcode", "value": "20190" },
      { "kind": "country", "value": "USA" }
    ],
    "countryCode": "US"
  }
}

See Section 5.1.1 for examples of how to use the JSCOMPS parameter for structured property values.¶

2.3.2. ANNIVERSARY

The ANNIVERSARY property [RFC6350] (Section 6.2.6) converts to an Anniversary object. The converted object is set in the "anniversaries" property of the Card object. The ANNIVERSARY property value converts to the "date" property of the Anniversary object. The Anniversary "kind" is "wedding". See Section 2.3.3 how to convert property values of type TIMESTAMP and DATE.¶

The following example illustrates how to convert the ANNIVERSARY property:¶

ANNIVERSARY:19860201

"anniversaries": {
  "ANNIVERSARY-1" : {
    "kind": "wedding",
    "date": {
      "year": 1986,
      "month": 2,
      "day": 1
    }
  }
}

2.3.3. BDAY

The BDAY property [RFC6350] (Section 6.2.5) converts to an Anniversary object. The converted object is set in the "anniversaries" property of the Card object. The BDAY property value converts to the "date" property of the Anniversary object. The Anniversary "kind" is "birth".¶

If the property value type is DATE [RFC6350] (Section 4.3.5) 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 [RFC6350] (Section 4.3.5) then the value converts to the Timestamp object's "utc" property. Otherwise it does not convert to JSContact. A BDAY property and the BIRTHPLACE property (see Section 2.3.4) convert to the same Anniversary object if their ALTID parameter values match or are not set on either property.¶

The following example illustrates how to convert the BDAY property:¶

BDAY:19531015T231000Z
BIRTHPLACE:
 123 Main Street\nAny Town, CA 91921-1234\nU.S.A.

"anniversaries": {
  "ANNIVERSARY-1" : {
    "kind": "birth",
    "date": {
      "@type": "Timestamp",
      "utc": "1953-10-15T23:10:00Z"
    },
    "place": {
      "full":
         "123 Main Street\nAny Town, CA 91921-1234\nU.S.A."
    }
  }
}

2.3.4. BIRTHPLACE

The BIRTHPLACE property [RFC6474] (Section 2.1) converts to an Anniversary object. The converted object is set in the "anniversaries" property of the Card object. The BIRTHPLACE property value converts to the "place" property of the Anniversary object. The Anniversary "kind" is "birth". The BIRTHPLACE and the BDAY property can convert to the same Anniversary object, see Section 2.3.3.¶

The property value converts to an Address object. If the property value is of type TEXT it converts to the "full" property of the Address object. If the property value is of type URI and uses the "geo:" URI scheme then it converts to the "coordinates" property of the Address object. A property having any other value does not convert to an Anniversary object.¶

The path of the BIRTHPLACE property in the "convertedProperties" property (Section 4.1.1) is "anniversaries/{id}/place", where "{id}" denotes the identifier of the Anniversary object.¶

2.3.5. CALADRURI

The CALADRURI property [RFC6350] (Section 6.9.2) converts to a SchedulingAddress object [RFC9553] (Section 2.4.2). The converted object is set in the "schedulingAddresses" property of the Card object. The CALADRURI property value converts to the "uri" property of the SchedulingAddress object. The PREF parameter converts according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the CALADRURI property:¶

CALADRURI;PREF=1:mailto:janedoe@example.com
CALADRURI:https://example.com/calendar/jdoe

"schedulingAddresses": {
  "SCHEDULING-1": {
    "uri": "mailto:janedoe@example.com",
    "pref": 1
  },
  "SCHEDULING-2": {
    "uri": "https://example.com/calendar/jdoe"
  }
}

2.3.6. CALURI

The CALURI property [RFC6350] (Section 6.9.3) converts to a Calendar object [RFC9553] (Section 2.4.1). The converted object is set in the "calendars" property of the Card object. The "kind" property of the Calendar object is set to "calendar". The CALURI property value converts to the "uri" property of the Calendar object. The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the CALURI property:¶

CALURI;PREF=1:https://cal.example.com/calA
CALURI;MEDIATYPE=text/calendar:https://ftp.example.com/calA.ics

"calendars": {
  "CAL-1": {
    "kind": "calendar",
    "uri": "https://cal.example.com/calA",
    "pref": 1
  },
  "CAL-2": {
    "kind": "calendar",
    "uri": "https://ftp.example.com/calA.ics",
    "mediaType": "text/calendar"
  }
}

2.3.7. CATEGORIES

The CATEGORIES property [RFC6350] (Section 6.7.1) converts to the "keywords" property of the Card object. Each text value of the CATEGORIES property becomes a key in the "keywords" property.¶

The PREF parameter does not convert to JSContact; implementations MAY insert the keywords by order of preference.¶

The path of the CATEGORIES property in the "convertedProperties" property (Section 4.1.1) is "keywords". Because more than one vCard property can convert to the "keywords" property, preserving conversion information for a single CATEGORIES property is implementation-specific.¶

The following example illustrates how to convert the CATEGORIES property:¶

CATEGORIES:internet,IETF,Industry,Information Technology

"keywords": {
  "internet": true,
  "IETF": true,
  "Industry": true,
  "Information Technology": true
}

2.3.8. CLIENTPIDMAP

The CLIENTPIDMAP property [RFC6350] (Section 6.7.7) does not convert to JSContact.¶

2.3.9. CONTACT-URI

The CONTACT-URI property [RFC8605] (Section 2.1) converts to a Link object [RFC9553] (Section 2.6.3). The converted object is set in the "links" property of the Card object. The "kind" property of the Link object is set to "contact". The CONTACT-URI property value converts to the "uri" property of the Link object. The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the CONTACT-URI property:¶

CONTACT-URI;PREF=1:mailto:contact@example.com

"links": {
  "CONTACT-1": {
    "kind": "contact",
    "uri": "mailto:contact@example.com",
    "pref": 1
  }
}

2.3.10. CREATED

The CREATED property [RFC9554] (Section 3.1) converts to the "created" property of the Card object.¶

The following example illustrates how to convert the CREATED property:¶

CREATED:19940930T143510Z

"created": "1994-09-30T14:35:10Z"

2.3.11. EMAIL

The EMAIL property [RFC6350] (Section 6.4.2) converts to an EmailAddress object [RFC9553] (Section 2.3.1). The converted object is set in the "emails" property of the Card object. The EMAIL property value converts to the "address" property of the EmailAddress object. The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the EMAIL property:¶

EMAIL;TYPE=work:jqpublic@xyz.example.com
EMAIL;PREF=1:jane_doe@example.com

"emails": {
  "EMAIL-1": {
    "contexts": { "work": true },
    "address": "jqpublic@xyz.example.com"
  },
  "EMAIL-2": {
    "address": "jane_doe@example.com",
    "pref": 1
  }
}

2.3.12. DEATHDATE

The DEATHDATE property [RFC6474] (Section 2.3) converts to an Anniversary object. The converted object is set in the "anniversaries" property of the Card object. The DEATHDATE property value converts to the "date" property of the Anniversary object. The Anniversary "kind" is "death". See Section 2.3.3 how to convert property values of type TIMESTAMP and DATE. A DEATHDATE property and the DEATHPLACE property (see Section 2.3.13) convert to the same Anniversary object if their ALTID parameter values match or are not set on either property.¶

The following example illustrates how to convert the DEATHDATE property:¶

DEATHDATE:19960415
DEATHPLACE:
 5 Court Street\nNew England, ND 58647\nU.S.A.

"anniversaries": {
  "ANNIVERSARY-2" : {
    "kind": "death",
    "date": {
      "year": 1996,
      "month": 4,
      "day": 15
    },
    "place": {
      "full": "5 Court Street\nNew England, ND 58647\nU.S.A."
    }
  }
}

2.3.13. DEATHPLACE

The DEATHPLACE property [RFC6474] (Section 2.2) converts to an Anniversary object. The converted object is set in the "anniversaries" property of the Card object. The DEATHPLACE property value converts to the "place" property of the Anniversary object. The Anniversary "kind" is "death". The DEATHPLACE and the DEATHDATE property can convert to the same Anniversary object, see Section 2.3.12.¶

The property value converts to an Address object. If the property value is of type TEXT it converts to the "full" property of the Address object. If the property value is of type URI and uses the "geo:" URI scheme then it converts to the "coordinates" property of the Address object. A property having any other value does not convert to an Anniversary object.¶

The path of the DEATHPLACE property in the "convertedProperties" property (Section 4.1.1) is "anniversaries/{id}/place", where "{id}" denotes the identifier of the Anniversary object.¶

2.3.14. EXPERTISE

The EXPERTISE property [RFC6715] (Section 2.1) converts to a PersonalInfo object [RFC9553] (Section 2.8.4). The converted object is set in the "personalInfo" property of the Card object. The "kind" property of the PersonalInfo object is set to "expertise". The EXPERTISE property value converts to the "value" property of the PersonalInfo object. The INDEX and LEVEL parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the EXPERTISE property:¶

EXPERTISE;LEVEL=beginner;INDEX=2:Chinese literature
EXPERTISE;INDEX=1;LEVEL=expert:chemistry

"personalInfo": {
  "PERSINFO-1" : {
    "kind": "expertise",
    "value": "Chinese literature",
     "level": "low",
     "listAs": 2
  },
  "PERSINFO-2" : {
    "kind": "expertise",
    "value": "chemistry",
    "level": "high",
    "listAs": 1
  }
}

2.3.15. FBURL

The FBURL property [RFC6350] (Section 6.9.1) converts to a Calendar object [RFC9553] (Section 2.4.1). The converted object is set in the "calendars" property of the Card object. The "kind" property of the Calendar object is set to "freeBusy". The FBURL property value converts to the "uri" property of the Calendar object. The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the FBURL property:¶

FBURL;PREF=1:https://www.example.com/busy/janedoe
FBURL;MEDIATYPE=text/calendar:https://example.com/busy/project-a.ifb

"calendars": {
  "FBURL-1": {
    "kind": "freeBusy",
    "uri": "https://www.example.com/busy/janedoe",
    "pref": 1
  },
  "FBURL-2": {
    "kind": "freeBusy",
    "uri": "https://example.com/busy/project-a.ifb",
    "mediaType": "text/calendar"
  }
}

2.3.16. FN

The FN property [RFC6350] (Section 6.2.1) converts to the Name object [RFC9553] (Section 2.2.1) in the "name" property of the Card object. The FN property value converts to the "full" property of the Name object.¶

If the LANGUAGE parameter is set, then the FN property converts as outlined in Section 2.2.11. 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 JSContact. Implementations MAY convert them to the VCard object's "properties" property (Section 4.1.1).¶

The path of the FN property in the "convertedProperties" property (Section 4.1.1) is "name/full".¶

The following example illustrates how to convert the FN property:¶

FN:John Q. Public, Esq.

"name": {
  "full": "John Q. Public, Esq."
}

2.3.17. GENDER

The GENDER property [RFC6350] (Section 6.2.7) does not convert to JSContact. Note that 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 [RFC9554].¶

2.3.18. GEO

The GEO property [RFC6350] (Section 6.5.2) converts to an Address object [RFC9553] (Section 2.5.1). The converted object is set in the "addresses" property of the Card object. The GEO property value converts to the "coordinates" property of the Address object. See Section 2.3.1 how to convert the GEO property together with the ADR and TZ property.¶

The path of the GEO property in the "convertedProperties" property (Section 4.1.1) is "addresses/{id}/coordinates", where "{id}" denotes the identifier of the Address object.¶

2.3.19. GRAMGENDER

The GRAMGENDER property [RFC9554] (Section 3.2) converts to the SpeakToAs object [RFC9553] (Section 2.2.4). The converted object is set in the "speakToAs" property of the Card object. The GRAMGENDER property value converts to the "grammaticalGender" property of the SpeakToAs object.¶

The following example illustrates how to convert the GRAMGENDER property:¶

GRAMGENDER:NEUTER

"speakToAs": {
  "grammaticalGender": "neuter"
}

2.3.20. HOBBY

The HOBBY property [RFC6715] (Section 2.2) converts to a PersonalInfo object [RFC9553] (Section 2.8.4). The converted object is set in the "personalInfo" property of the Card object. The "kind" property of the PersonalInfo object is set to "hobby". The HOBBY property value converts to the "value" property of the PersonalInfo object. The INDEX and LEVEL parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the HOBBY property:¶

HOBBY;INDEX=1;LEVEL=high:reading
HOBBY;INDEX=2;LEVEL=high:sewing

"personalInfo": {
  "PERSINFO-1" : {
    "kind": "hobby",
    "value": "reading",
    "level": "high",
    "listAs": 1
  },
  "PERSINFO-2" : {
    "kind": "hobby",
    "value": "sewing",
    "level": "high",
    "listAs": 2
  }
}

2.3.21. IMPP

The IMPP property [RFC6350] (Section 6.4.3) converts to an OnlineService object [RFC9553] (Section 2.3.2). The converted object is set in the "onlineServices" property of the Card object. The IMPP property value converts to the "uri" property of the OnlineService object. The SERVICE-TYPE, USERNAME, PREF, and TYPE parameters convert according to the rules defined in Section 2.2.¶

Implementations MAY use the "vCard" property (Section 4.1.1) to indicate that the OnlineService object was converted from the IMPP property.¶

The following example illustrates how to convert the IMPP property:¶

IMPP;PREF=1:xmpp:alice@example.com

"onlineServices": {
  "OS-1": {
    "uri": "xmpp:alice@example.com",
    "pref": 1
  }
},
"vCard": {
  "convertedProperties": {
    "onlineServices/OS-1/uri": {
      "name": "impp"
    }
  }
}

2.3.22. INTEREST

The INTEREST property [RFC6715] (Section 2.3) converts to a PersonalInfo object [RFC9553] (Section 2.8.4). The converted object is set in the "personalInfo" property of the Card object. The "kind" property of the PersonalInfo object is set to "interest". The INTEREST property value converts to the "value" property of the PersonalInfo object. The INDEX and LEVEL parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the INTEREST property:¶

INTEREST;INDEX=1;LEVEL=medium:r&b music
INTEREST;INDEX=2;LEVEL=high:rock&roll music

"personalInfo": {
  "PERSINFO-1" : {
    "kind": "interest",
    "value": "r&b music",
    "level": "medium",
    "listAs": 1
  },
  "PERSINFO-2" : {
    "kind": "interest",
    "value": "rock&roll music",
    "level": "high",
    "listAs": 2
  }
}

2.3.23. KEY

The KEY property [RFC6350] (Section 6.8.1) converts to a CryptoKey object [RFC9553] (Section 2.6.1). The converted object is set in the "cryptoKeys" property of the Card object. The KEY property value converts to the "uri" property of the CryptoKey object. The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the KEY property:¶

KEY:https://www.example.com/keys/jdoe.cer

"cryptoKeys": {
  "KEY-1": {
    "uri": "https://www.example.com/keys/jdoe.cer"
  }
}

2.3.24. KIND

The KIND property [RFC6350] (Section 6.1.4) converts to the "kind" property of the Card object. Allowed values are those described in Section 6.1.4 of [RFC6350] and extended with the values declared in [RFC6473] and [RFC6869].¶

The following example illustrates how to convert the KIND property:¶

KIND:individual

"kind": "individual"

2.3.25. LANG

The LANG property [RFC6350] (Section 6.4.4) converts to a LanguagePref object [RFC9553] (Section 2.3.4). The converted object is set in the "preferredLanguages" property of the Card object. The LANG property value converts to the "language" property of the LanguagePref object. The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the LANG property:¶

LANG;TYPE=work;PREF=1:en
LANG;TYPE=work;PREF=2:fr
LANG;TYPE=home:fr

"preferredLanguages": {
  "LANG-1": {
    "language": "en",
    "contexts": { "work": true },
    "pref": 1
  },
  "LANG-2": {
    "language": "fr",
    "contexts": { "work": true },
    "pref": 2
  },
  "LANG-3": {
    "language": "fr",
    "contexts": { "private": true }
  }
}

2.3.26. LANGUAGE

The LANGUAGE property [RFC9554] (Section 3.3) converts to the "language" property of the Card object.¶

The following example illustrates how to convert the LANGUAGE property:¶

LANGUAGE:de-AT

"language": "de-AT"

2.3.27. LOGO

The LOGO property [RFC6350] (Section 6.6.3) converts to a Media object [RFC9553] (Section 2.6.4). The converted object is set in the "media" property of the Card object. The "kind" property of the Media object is set to "logo". The LOGO property value converts to the "uri" property of the Media object. The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the LOGO property:¶

LOGO:https://www.example.com/pub/logos/abccorp.jpg

"media": {
  "LOGO-1": {
    "kind": "logo",
    "uri": "https://www.example.com/pub/logos/abccorp.jpg"
  }
}

2.3.28. MEMBER

The MEMBER property [RFC6350] (Section 6.6.5) converts to the "members" property of the Card object. The MEMBER property value becomes a key in the "members" property.¶

[RFC6350] defines the MEMBER property value type to be URI only, but [I-D.ietf-calext-vcard4-bis] extends its definition to also allow free-form text. The PREF parameter does not convert to JSContact.¶

Implementations MAY use the "vCard" property (Section 4.1.1) to preserve the value type of the MEMBER property. The path of the MEMBER property in the "convertedProperties" property (Section 4.1.1) is "members/{value}", where "{value}" denotes the MEMBER property value.¶

The following examples illustrate how to convert the MEMBER property:¶

KIND:group
FN:The Doe family
MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af
MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519

"kind": "group",
"name": {
  "full": "The Doe family"
},
"uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667",
"members": {
  "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true,
  "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true
}

KIND:group
MEMBER;VALUE=text:AD8B50F23FF244F1@example.com

"kind": "group",
"members": {
  "AD8B50F23FF244F1@example.com": true
},
"vCard": {
  "convertedProperties": {
    "members/AD8B50F23FF244F1@example.com": {
      "name": "member",
      "valueType": "text"
    }
  }
}

2.3.29. N

The N property [RFC6350] (Section 6.2.2) converts to the Name object [RFC9553] (Section 2.2.1) in the "name" property of the Card object. The N property value converts to the "components" property of the Name object.¶

Each component in the structured value of the N property converts to a NameComponent. The component value converts to the NameComponent object's "value" property, the component position determines the value of the NameComponent object's "kind" property as follows:¶

If the JSCOMPS (Section 5.1.1) 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 Table 2. An empty or non-existent component value indicates that no sort is defined for this kind.¶

The path of the N property in the "convertedProperties" property (Section 4.1.1) is "name/components".¶

The following example illustrates how to convert the N property:¶

N;SORT-AS="Stevenson,John Philip":Stevenson;John;Philip,Paul;Dr.;Jr.,M.D.,A.C.P.;;Jr.

"name": {
  "components":[
    { "kind": "surname", "value": "Stevenson" },
    { "kind": "given", "value": "John" },
    { "kind": "given2", "value": "Philip" },
    { "kind": "given2", "value": "Paul" },
    { "kind": "title", "value": "Dr." },
    { "kind": "credential", "value": "M.D." },
    { "kind": "credential", "value": "A.C.P." },
    { "kind": "generation", "value": "Jr." }
  ],
  "sortAs": {
    "surname": "Stevenson",
    "given": "John Philip"
  }
}

See Section 5.1.1 for examples of how to use the JSCOMPS parameter for structured property values.¶

2.3.30. NICKNAME

The NICKNAME property [RFC6350] (Section 6.2.3) converts to a Nickname object [RFC9553] (Section 2.2.2). The converted object is set in the "nicknames" property of the Card object. The NICKNAME property value converts to the "name" property of the Nickname object. The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the NICKNAME property:¶

NICKNAME:Johnny

"nicknames": {
   "NICK-1": {
    "name": "Johnny"
   }
}

2.3.31. NOTE

The NOTE property [RFC6350] (Section 6.7.2) converts to a Note object [RFC9553] (Section 2.8.3). The converted object is set in the "notes" property of the Card object. The NOTE property value converts to the "note" property of the Note object. The ALTID and LANGUAGE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the NOTE property:¶

NOTE;CREATED=20221123T150132Z;AUTHOR-NAME="John":
  Office hours are from 0800 to 1715 EST\, Mon-Fri.

"notes": {
  "NOTE-1" : {
     "note": "Office hours are from 0800 to 1715 EST, Mon-Fri.",
     "created": "2022-11-23T15:01:32Z",
     "author": {
       "name": "John"
     }
  }
}

2.3.32. ORG

The ORG property [RFC6350] (Section 6.6.4) converts to an Organization object [RFC9553] (Section 2.2.3). The converted object is set in the "organizations" property of the Card object. The organization name in the ORG property value converts to the "name" property of the Organization object. Any organizational unit names convert to the "units" 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 and LANGUAGE parameters convert according to the rules defined in Section 2.2.¶

The first item of the comma-separated SORT-AS parameter value converts to the Organization object's "sortAs" property. The subsequent items convert to the "sortAs" property of the corresponding OrgUnit object. The TYPE parameter converts according to the rules defined in Section 2.2.¶

The path of the ORG property in the "convertedProperties" property (Section 4.1.1) is "organizations/{id}/name", where "{id}" denotes the identifier of the Organization object.¶

The following example illustrates how to convert the ORG property:¶

ORG;SORT-AS="ABC":ABC\, Inc.;North American Division;Marketing

"organizations": {
  "ORG-1": {
    "name": "ABC, Inc.",
    "units":[
      { "name": "North American Division" },
      { "name": "Marketing" }
    ],
    "sortAs": "ABC"
  }
}

2.3.33. ORG-DIRECTORY

The ORG-DIRECTORY property [RFC6715] (Section 2.4) converts to a Directory object [RFC9553] (Section 2.6.2). The converted object is set in the "directories" property of the Card object. The "kind" property of the Directory object is set to "directory". The ORG-DIRECTORY property value converts to the "uri" property of the Directory object. The INDEX, PREF, and TYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the ORG-DIRECTORY property:¶

ORG-DIRECTORY;INDEX=1:https://directory.mycompany.example.com
ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Tech,ou=Engineering

"directories": {
  "DIRECTORY-1": {
    "kind": "directory",
    "uri": "https://directory.mycompany.example.com",
    "listAs": 1
  },
  "DIRECTORY-2": {
    "kind": "directory",
    "uri": "ldap://ldap.tech.example/o=Tech,ou=Engineering",
    "pref": 1
  }
}

2.3.34. PHOTO

The PHOTO property [RFC6350] (Section 6.2.4) converts to a Media object [RFC9553] (Section 2.6.4). The converted object is set in the "media" property of the Card object. The "kind" property of the Media object is set to "photo". The PHOTO property value converts to the "uri" property of the Media object. The PREF and MEDIATYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the PHOTO property:¶

PHOTO:https://www.example.com/pub/photos/jqpublic.gif

"media": {
   "PHOTO-1": {
     "kind": "photo",
     "uri": "https://www.example.com/pub/photos/jqpublic.gif"
   }
}

2.3.35. PRODID

The PRODID property [RFC6350] (Section 6.7.3) converts to the "prodId" property of the Card object.¶

The following example illustrates how to convert the PRODID property:¶

PRODID:ACME Contacts App version 1.23.5

"prodId": "ACME Contacts App version 1.23.5"

2.3.36. PRONOUNS

The PRONOUNS property [RFC9554] (Section 3.4) converts to a Pronouns object (Section 2.2.4 of [RFC9553]). The converted object is set in the "pronouns" property of the SpeakToAs object, which is set in the "speakToAs" property of the Card object. The PRONOUNS property value converts to the "pronouns" property of the Pronouns object.¶

The following example illustrates how to convert the PRONOUNS property:¶

PRONOUNS;PREF=2:they/them
PRONOUNS;PREF=1:xe/xir

"speakToAs": {
  "pronouns": {
    "PRONOUNS-1": {
      "pronouns": "they/them",
      "pref": 2
    },
    "PRONOUNS-2": {
      "pronouns": "xe/xir",
      "pref": 1
    }
  }
}

2.3.37. RELATED

The RELATED property [RFC6350] (Section 6.6.6) converts to the "relatedTo" property of the Card object. The RELATED property value becomes a key in the "relatedTo" property, and the corresponding value is a Relation object [RFC9553] (Section 2.1.8). The TYPE parameters convert to the "relation" property of the Relation object. Any other parameters convert as defined in Section 4.1.1.¶

The path of the RELATED property in the "convertedProperties" property (Section 4.1.1) is "relatedTo/{value}", where "{value}" denotes the RELATED property value.¶

The following example illustrates how to convert the RELATED property:¶

RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
RELATED;TYPE=contact:https://example.com/directory/john.vcf
RELATED;VALUE=text:Please contact my deputy John for any inquiries.

"relatedTo" : {
  "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6" : {
    "relation" : {
      "friend" : true
    }
  },
  "https://example.com/directory/john.vcf" : {
    "relation" : {
      "contact" : true
    }
  },
  "Please contact my deputy John for any inquiries." : {
    "relation" : { }
  }
}

2.3.38. REV

The REV property [RFC6350] (Section 6.7.4) converts to the "updated" property of the Card object.¶

The following example illustrates how to convert the REV property:¶

REV:19951031T222710Z

"updated": "1995-10-31T22:27:10Z"

2.3.39. ROLE

The ROLE property [RFC6350] (Section 6.6.2) converts to a Title object [RFC9553] (Section 2.2.5). The converted object is set in the "titles" property of the Card object. The "kind" property of the Title object is set to "role". The ROLE property value converts to the "name" property of the Title object.¶

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 "organizationId" property of the Title object is set to the identifier to which the ORG property converts in the "organizations" property of the Card object. The ALTID and LANGUAGE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the ROLE property:¶

group1.ROLE:Project Leader
group1.ORG:ABC, Inc.

"titles": {
  "ROLE-1": {
    "kind": "role",
    "name": "Project Leader",
    "organizationId": "ORG-1"
  }
},
"organizations": {
  "ORG-1": {
    "name": "ABC, Inc."
  }
}

2.3.40. SOCIALPROFILE

The SOCIALPROFILE property [RFC9554] (Section 3.5) converts to an OnlineService object [RFC9553] (Section 2.3.2). The converted object is set in the "onlineServices" property of the Card object. If the SOCIALPROFILE property value is of type URI, then it converts to the "uri" property of the OnlineService object; otherwise it converts to the "user" property. The SERVICE-TYPE, USERNAME, PREF, and TYPE parameters convert according to the rules defined in Section 2.2.¶

Implementations MAY use the "vCard" property (Section 4.1.1) to indicate that the OnlineService object was converted from the SOCIALPROFILE property.¶

The following example illustrates how to convert the SOCIALPROFILE property:¶

SOCIALPROFILE;SERVICE-TYPE=Mastodon:https://example.com/@foo

"onlineServices": {
  "...": "",
  "OS-1": {
    "service": "Mastodon",
    "uri": "https://example.com/@foo"
  }
}

2.3.41. SOUND

The SOUND property [RFC6350] (Section 6.7.5) converts to a Media object [RFC9553] (Section 2.6.4). The converted object is set in the "media" property of the Card object. The "kind" property of the Media object is set to "sound". The SOUND property value converts to the "uri" property of the Media object. The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the SOUND property:¶

SOUND:CID:JOHNQPUBLIC.19960229T080000.xyzMail@example.com

"media": {
  "...": "",
  "SOUND-1": {
    "kind": "sound",
    "uri": "CID:JOHNQPUBLIC.19960229T080000.xyzMail@example.com"
  }
}

2.3.42. SOURCE

The SOURCE property [RFC6350] (Section 6.1.3) converts to a Directory object [RFC9553] (Section 2.6.2). The converted object is set in the "directories" property of the Card object. The "kind" property of the Directory object is set to "entry". The SOURCE property value converts to the "uri" property of the Directory object. The PREF and MEDIATYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the SOURCE property:¶

SOURCE:https://dir.example.com/addrbook/jdoe/Jean%20Dupont.vcf

"directories": {
   "ENTRY-1": {
     "kind": "entry",
     "uri": "https://dir.example.com/addrbook/jdoe/Jean%20Dupont.vcf"
   }
}

2.3.43. TEL

The TEL property [RFC6350] (Section 6.4.1) converts to a Phone object [RFC9553] (Section 2.3.3). The converted object is set in the "phones" property of the Card object.¶

The TEL-specific values of the TYPE parameter convert to the "features" property keys as outlined in Table 3. Note that Section 6.4.1 of [RFC6350] defines the default type to be "voice", but the default Phone object's "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.¶

The TEL property value converts to the "number" property of the Phone object. The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the TEL property:¶

TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555
TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67

"phones": {
  "PHONE-1": {
    "contexts": { "private": true },
    "features": { "voice": true },
    "number": "tel:+1-555-555-5555;ext=5555",
    "pref": 1
  },
  "PHONE-2": {
    "contexts": { "private": true },
    "number": "tel:+33-01-23-45-67"
  }
}

2.3.44. TITLE

The TITLE property [RFC6350] (Section 6.6.1) converts to a Title object [RFC9553] (Section 2.2.5). The converted object is set in the "titles" property of the Card object. The TITLE property value converts to the "name" property of the Title object. The same rules as in Section 2.3.39 apply for setting the Title object's "organizationId" property. The ALTID and LANGUAGE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the TITLE property:¶

TITLE:Research Scientist

"titles": {
  "TITLE-1": {
    "kind": "title",
    "name": "Research Scientist"
  }
}

2.3.45. TZ

The TZ property [RFC6350] (Section 6.5.1) converts to an Address object [RFC9553] (Section 2.5.1). The converted object is set in the "addresses" property of the Card object. The TZ property value converts to the "timeZone" property of the Address object. See Section 2.3.1 how to convert the TZ property together with the ADR and GEO property.¶

A value of type TEXT converts verbatim. A value of type UTC-OFFSET converts if the offset has zero minutes and the hour offset is between -12 and +14, both inclusively:¶

• 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".¶

Any other UTC-OFFSET property value, or any other value type, does not convert to JSContact.¶

The path of the TZ property in the "convertedProperties" property (Section 4.1.1) is "addresses/{id}/timeZone", where "{id}" denotes the identifier of the Address object.¶

2.3.46. UID

The UID property [RFC6350] (Section 6.7.6) converts to the "uid" property of the Card object.¶

Implementations MAY use the "vCard" property (Section 4.1.1) to preserve the value type of the UID property.¶

The following examples illustrate how to convert the UID property:¶

UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6

"uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"

UID;VALUE=text:77A50EF0-54CA-40B0-B878-B3580B4100A2

"uid": "77A50EF0-54CA-40B0-B878-B3580B4100A2",
"vCard": {
  "convertedProperties": {
    "uid": {
      "name": "uid",
      "valueType": "text"
    }
  }
}

2.3.47. URL

The URL property [RFC6350] (Section 6.7.8) converts to a Link object [RFC9553] (Section 2.6.3). The converted object is set in the "links" property of the Card object. The URL property value converts to the "uri" property of the Link object. The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

The following example illustrates how to convert the URL property:¶

URL:https://example.org/restaurant.french/~chezchic.html

"links": {
  "LINK-1": {
    "uri": "https://example.org/restaurant.french/~chezchic.html"
  }
}

2.3.48. VERSION

The VERSION property [RFC6350] (Section 6.7.9) does not convert to JSContact.¶

2.3.49. X-ABLabel

The X-ABLabel property is experimental but widely in use in existing vCard data. The X-ABLabel property is preceded by a vCard property group name, and it converts to the JSContact object that was converted from a vCard property of the same group. The X-ABLabel property value converts to the "label" property of that object.¶

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 Section 2.2.9. The path of the X-ABLabel property in the "convertedProperties" property (Section 4.1.1) is "*/label", where "*" denotes the path of the object on which the label is set.¶

The following example illustrates how to convert the X-ABLabel property:¶

item1.TEL;VALUE=uri:tel:+1-555-555-5555
item1.X-ABLabel:foo

"phones": {
  "p1": {
    "number": "tel:+1-555-555-5555",
    "label": "foo"
  }
}

2.3.50. XML

The XML property [RFC6350] (Section 6.1.5) does not convert to JSContact.¶

4.1.1. 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 the JSContact property that the vCard property value converts to (e.g., see Figure 27). A path MUST NOT point to or into the "localizations" property, but a localization MAY contain its own "vCard" property or patch the "vCard" property of the non-localized Card object.¶

The key MUST be a valid key of a PatchObject as defined in Section 1.4.3 of [RFC9553]. 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 Section 3.3 of [RFC7095].¶

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 Section 3.4 of [RFC7095].¶

The example in Figure 56 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.¶

BEGIN:VCARD
VERSION:4.0
FN;X-FOO=bar:test
...
X-BAR:bam
...

"name": {
  "full": "test"
},
"vCard": {
  "version": "4.0",
  "convertedProperties": {
    "name/full": {
      "name": "fn",
      "parameters": {
        "x-foo": "bar"
      }
    }
  },
  "properties": [
    [
      "x-bar",
      {},
      "unknown",
      "bam"
    ]
  ]
}

5.2.1. 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 Section 2 of [RFC8259]. 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 [RFC9553]. 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:¶

jsprop = "JSPROP" jsprop-param ":" TEXT

jsprop-param  = *(
            ; The following are MANDATORY and MUST NOT
            ; occur more than once
            ( ";" jsptr-param ) /    ; see next section
            ( ";" "VALUE" "=" "TEXT")
            ;
            ; The following is OPTIONAL
            ; and MAY occur more than once.
            ;
            (";" other-param)
            ;
            )

¶

Example(s):

This illustrates how to convert a property at the top level in a Card object that is unknown to the implementation.¶

"someUnknownProperty": true

JSPROP;JSPTR="someUnknownProperty":true

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.¶

"example.com:foo": {
  "bar": 1234
}

JSPROP;JSPTR="example.com:foo":{"bar":1234}

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.¶

"phones": {
  "phone1": {
    "number": "tel:+33-01-23-45-67",
    "example.com:foo/bar": "tux hux"
  }
}

TEL:tel:+33-01-23-45-67
JSPROP;JSPTR="phones/phone1/example.com:foo~1bar":
 "tux hux"