JSContact: Converting from and to vCard

2.2.1. ALTID

The ALTID parameter (Section 5.4 of [RFC6350]) 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 Section 2.3.1. To preserve the verbatim value of the ALTID parameter, set the JSContact properties defined in Section 4.¶

2.2.2. AUTHOR

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

2.2.3. AUTHOR-NAME

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

2.2.4. CALSCALE

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

2.2.5. CC

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

2.2.6. CREATED

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

2.2.7. DERIVED

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

2.2.8. GEO

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

2.2.9. GROUP

The GROUP parameter (Section 7.1 of [RFC7095]) does not convert to JSContact. It exclusively is for use in jCard and MUST NOT be set in a vCard.¶

Preserving the exact group name when converting from vCard to JSContact and back to vCard is not necessary. Any group identifiers will do, as long as the resulting vCard groups its properties equally to the original vCard. Implementations MAY preserve the original group name in the "parameters" property of the VCardProperty object (Section 4.1.1).¶

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 (Section 3.1 of [RFC6715]) 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 (Section 5.1 of [RFC6350]) 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.¶

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 (Section 6.3.1 of [RFC6350]) on an ADR property converts to the Address object's full property (Section 2.5.1 of [RFC9553]).¶

2.2.13. LEVEL

The LEVEL parameter (Section 3.2 of [RFC6715]) converts to the PersonalInfo object's level property (Section 2.8.4 of [RFC9553]). 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 (Section 5.7 of [RFC6350]) converts to the Resource object's mediaType property (Section 1.4.4 of [RFC9553]).¶

2.2.15. PHONETIC

The PHONETIC parameter (Section 4.6 of [RFC9554]) 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.¶

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 (Section 5.5 of [RFC6350]) does not convert to a standard JSContact element. Implementations MAY convert it to the "parameters" property of the VCardProperty object (Section 4.1.1).¶

2.2.17. PREF

The PREF parameter (Section 5.3 of [RFC6350]) 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 (Section 4.7 of [RFC9554]) 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.¶

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 (Section 4.8 of [RFC9554]) 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 (Section 4.9 of [RFC9554]) converts to the OnlineService object's service property (Section 2.3.2 of [RFC9553]).¶

2.2.21. SORT-AS

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

2.2.22. TYPE

The TYPE parameter (Section 5.6 of [RFC6350]) 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 (Section 5.11 of [RFC6350]) on an ADR property converts to the Address object's timeZone property (Section 2.5.1 of [RFC9553]). Also see the conversion of the TZ property in Section 2.3.45.¶

2.2.24. USERNAME

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

2.2.25. VALUE

The VALUE parameter (Section 5.2 of [RFC6350]) does not convert to an IANA-registered property in JSContact. To preserve properties with experimental values, see Section 4.1.1.¶

2.3.1. ADR

The ADR property (Section 6.3.1 of [RFC6350]) converts to an Address object (Section 2.5.1 of [RFC9553]) in the Card object's addresses property.¶

Each component in the structured value of the ADR property converts to an AddressComponent in the Address components property. The component value converts to the AddressComponent value property, the component position determines the value of the AddressComponent kind property as follows:¶

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

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 using the JSCOMPS parameter for vCard-structured property values.¶

2.3.2. ANNIVERSARY

The ANNIVERSARY property (Section 6.2.6 of [RFC6350]) converts to an Anniversary object in the Card object's anniversaries property (Figure 13). The Anniversary kind is "wedding".¶

See Section 2.3.3 how to convert property values of type TIMESTAMP and DATE.¶

ANNIVERSARY:19860201

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

2.3.3. BDAY

The BDAY property (Section 6.2.5 of [RFC6350]) converts to an Anniversary object in the Card object's anniversaries property (Figure 13). Its value converts to the Anniversary date property. 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 utc property of the Timestamp object. Otherwise it does not convert to a standard JSContact element.¶

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

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 (Section 2.1 of [RFC6474]) converts to an Anniversary object in the Card object's anniversaries property (Figure 13). Its value converts to an Address object in the Anniversary place property. The Anniversary kind is "birth".¶

A property value of type TEXT converts to the Address object's full property. A property value of type URI using the "geo:" URI scheme converts to the Address object's coordinates property. A property having any other value type does not convert to an Anniversary object.¶

See Section 2.3.3 for an example and how to convert a BIRTHPLACE property together with a BDAY property.¶

2.3.5. CALADRURI

The CALADRURI property (Section 6.9.2 of [RFC6350]) converts to a SchedulingAddress object (Section 2.4.2 of [RFC9553]) in the Card object's schedulingAddresses property (Figure 15). The SchedulingAddress object's uri property is set to the CALADRURI value.¶

The PREF parameter (Section 5.3 of [RFC6350]) converts according to the rules defined in Section 2.2.¶

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 (Section 6.9.3 of [RFC6350]) converts to a Calendar object (Section 2.4.1 of [RFC9553]) in the Card object's calendars property (Figure 16). The Calendar object's kind property is set to "calendar" and the uri property is set to the CALURI value.¶

The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.7.1 of [RFC6350]) converts to a set of entries of the Card object's keywords property (Figure 17). The keys are the comma-separated text values of the CATEGORIES property.¶

In this case, the PREF parameter does not have a JSContact counterpart; however, the implementors MAY insert the entries by order of preference.¶

CATEGORIES:internet,IETF,Industry,Information Technology

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

2.3.8. CLIENTPIDMAP

The CLIENTPIDMAP property (Section 6.7.7 of [RFC6350]) does not convert to a standard JSContact element. Implementations MAY convert it to the "properties" property of the VCard object (Section 4.1.1).¶

2.3.9. CONTACT-URI

The CONTACT-URI property (Section 2.1 of [RFC8605]) converts to a Link object (Section 2.6.3 of [RFC9553]) in the Card object's links property (Figure 18). The Link object's kind property is set to "contact" and the uri property is set to the CONTACT-URI property value.¶

The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 3.1 of [RFC9554]) converts to the Card object's created property (Figure 19).¶

CREATED:19940930T143510Z

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

2.3.11. EMAIL

The EMAIL property (Section 6.4.2 of [RFC6350]) converts to an EmailAddress object (Section 2.3.1 of [RFC9553]) in the Card object's emails property (Figure 20). The EmailAddress object's address property is set to the EMAIL value.¶

The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 2.3 of [RFC6474]) converts to an Anniversary object in the Card object's anniversaries property (Figure 13). Its value converts to the Anniversary date property. 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.¶

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

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

2.3.13. DEATHPLACE

The DEATHPLACE property (Section 2.2 of [RFC6474]) converts to an Anniversary object in the Card object's anniversaries property (Figure 13). Its value converts to an Address object in the Anniversary place property. The Anniversary kind is "death".¶

A property value of type TEXT converts to the Address object's full property. A property value of type URI using the "geo:" URI scheme converts to the Address object's coordinates property. A property having any other value type does not convert to an Anniversary object.¶

See Section 2.3.12 for an example and how to convert a DEATHPLACE property together with a DEATHDATE property.¶

2.3.14. EXPERTISE

The EXPERTISE property (Section 2.1 of [RFC6715]) converts to a PersonalInfo object (Section 2.8.4 of [RFC9553]) in the Card object's personalInfo property (Figure 22). The PersonalInfo object's kind property is set to "expertise".¶

The INDEX and LEVEL parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.9.1 of [RFC6350]) converts to a Calendar object (Section 2.4.1 of [RFC9553]) in the Card object's calendars property (Figure 23). The Calendar object's kind property is set to "freeBusy" and the uri property is set to the FBURL value.¶

The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.2.1 of [RFC6350]) converts to the Name object's full property (Figure 24). 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 a standard JSContact element. Implementations MAY convert them to the "properties" property of the VCard object (Section 4.1.1).¶

FN:John Q. Public, Esq.

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

2.3.17. GENDER

The GENDER property (Section 6.2.7 of [RFC6350]) does not convert to an IANA-registered property in JSContact. To convert this property, see Section 4.1.1. Alternatively, the Card object's speakToAs property defines how to address and refer to an individual represented by the Card, as do the newly defined vCard GRAMGENDER and PRONOUNS properties of [RFC9554].¶

2.3.18. GEO

The GEO property (Section 6.5.2 of [RFC6350]) converts to the Address object's coordinates property (Section 2.5.1 of [RFC9553]).¶

See Section 2.3.1 how to convert the GEO property together with the ADR and TZ property.¶

2.3.19. GRAMGENDER

The GRAMGENDER property (Section 3.2 of [RFC9554]) converts to the SpeakToAs object's grammaticalGender property (Figure 25).¶

GRAMGENDER:NEUTER

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

2.3.20. HOBBY

The HOBBY property (Section 2.2 of [RFC6715]) converts to a PersonalInfo object (Section 2.8.4 of [RFC9553]) in the Card object's personalInfo property (Figure 26). The PersonalInfo object's kind property is set to "hobby".¶

The INDEX and LEVEL parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.4.3 of [RFC6350]) converts to an OnlineService object (Section 2.3.2 of [RFC9553]) in the Card object's onlineServices property (Figure 27). The "uri" property is set to the IMPP value.¶

Implementations MAY indicate that the OnlineService object converted from the IMPP property by adding an entry for the "uri" property of the OnlineService object in the "vCard/convertedProperties" property.¶

The SERVICE-TYPE, USERNAME, PREF, and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 2.3 of [RFC6715]) converts to a PersonalInfo object (Section 2.8.4 of [RFC9553]) in the Card object's personalInfo property (Figure 28). The PersonalInfo object's kind property is set to "interest".¶

The INDEX and LEVEL parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.8.1 of [RFC6350]) converts to a CryptoKey object (Section 2.6.1 of [RFC9553]) in the Card object's cryptoKeys property (Figure 29). The CryptoKey object's uri property is set to the KEY property value.¶

The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.1.4 of [RFC6350]) converts to the kind property (Figure 30). Allowed values are those described in Section 6.1.4 of [RFC6350] and extended with the values declared in [RFC6473] and [RFC6869].¶

KIND:individual

"kind": "individual"

2.3.25. LANG

The LANG property (Section 6.4.4 of [RFC6350]) converts to a LanguagePref object (Section 2.3.4 of [RFC9553]) in the Card object's preferredLanguages property (Figure 31). The LANG property value converts to the LanguagePref object's language property value.¶

The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 3.3 of [RFC9554]) converts to the Card object's language property (Figure 32).¶

LANGUAGE:de-AT

"language": "de-AT"

2.3.27. LOGO

The LOGO property (Section 6.6.3 of [RFC6350]) converts to a Media object (Section 2.6.4 of [RFC9553]) in the Card object's media property (Figure 33). The Media object's kind property is set to "logo" and the uri property is set to the LOGO property value.¶

The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.6.5 of [RFC6350]) converts to the Card object's members property (Figure 34). Each MEMBER property value is a key in the members property. The PREF parameter (Section 5.3 of [RFC6350]) does not convert to JSContact.¶

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
}

2.3.29. N

The N property (Section 6.2.2 of [RFC6350]) converts to a Name object (Section 2.2.1 of [RFC9553]) in the Card object's name property.¶

Each component in the structured value of the N property converts to a NameComponent in the Name components property. The component value converts to the NameComponent value property, the component position determines the value of the NameComponent kind property as follows:¶

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

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 using the JSCOMPS parameter for vCard-structured property values.¶

2.3.30. NICKNAME

The NICKNAME property (Section 6.2.3 of [RFC6350]) converts to a Nickname object (Section 2.2.2 of [RFC9553]) in the Card object's nicknames property (Figure 36). The name property is set to the NICKNAME property value.¶

The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

NICKNAME:Johnny

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

2.3.31. NOTE

The NOTE property (Section 6.7.2 of [RFC6350]) converts to a Note object (Section 2.8.3 of [RFC9553]) in the Card object's notes property (Figure 37).¶

The ALTID and LANGUAGE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.6.4 of [RFC6350]) converts to an Organization object (Section 2.2.3 of [RFC9553]) in the Card object's organizations property (Figure 38). The Organization object's name property is set to the ORG property organizational name component. The Organization object's units property is an array of OrgUnit objects that each contain an organizational unit name component value of the ORG property value.¶

Implementations MAY allow representation of organizational units without the organizational name. In this case, the first component of the ORG value MUST be an empty string (e.g., ORG:;DepartmentA).¶

The ALTID and LANGUAGE parameters convert according to the rules defined in Section 2.2.¶

The first item of the comma-separated SORT-AS parameter value converts to the sortAs property of the Organization object. The subsequent items convert to the sortAs property of the corresponding OrgUnit object.¶

The TYPE parameter converts according to the rules defined in Section 2.2.¶

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 (Section 2.4 of [RFC6715]) [RFC6715] converts to a Directory object (Section 2.6.2 of [RFC9553]) in the Card object's directories property (Figure 39). The Directory object's kind property is set to "directory". The uri property is set to the ORG-DIRECTORY property value.¶

The INDEX, PREF, and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.2.4 of [RFC6350]) converts to a Media object (Section 2.6.4 of [RFC9553]) in the Card object's media property (Figure 40). The Media object's kind property is set to "photo" and the uri property is set to the PHOTO value.¶

The PREF and MEDIATYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.7.3 of [RFC6350]) converts to the Card object's prodId property (Figure 41).¶

PRODID:ACME Contacts App version 1.23.5

"prodId": "ACME Contacts App version 1.23.5"

2.3.36. PRONOUNS

The PRONOUNS property (Section 3.4 of [RFC9554]) converts to the SpeakToAs object's pronouns property (Figure 42).¶

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 (Section 6.6.6 of [RFC6350]) converts to the Card object's relatedTo property (Figure 43). The property value converts to the key in the relatedTo property. The TYPE parameters convert to the Relation object's relation property (Section 2.1.8 of [RFC9553]). Any other parameters convert as defined in Section 4.1.1.¶

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 (Section 6.7.4 of [RFC6350]) converts to the Card object's updated property (Figure 44).¶

REV:19951031T222710Z

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

2.3.39. ROLE

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

If the vCard contains an ORG property and either the ROLE and ORG property are not part of a vCard property group, or they are both in the same group, then the Title organizationId property is set to the identifier to which the ORG property converts in the Card object's organizations property.¶

The ALTID and LANGUAGE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 3.5 of [RFC9554]) converts to an OnlineService object (Section 2.3.2 of [RFC9553]) in the Card object's onlineServices property (Figure 46). If the SOCIALPROFILE property value is of type URI, then the "uri" property is set, otherwise, the "user" property is set.¶

Implementations MAY indicate that the OnlineService object converted from the SOCIALPROFILE property by adding an entry for the "uri" or "user" property of the OnlineService object in the "vCard/convertedProperties" property.¶

The SERVICE-TYPE, USERNAME, PREF, and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.7.5 of [RFC6350]) converts to a Media object (Section 2.6.4 of [RFC9553]) in the Card object's media property (Figure 47). The Media object's kind property is set to "sound" and the uri property is set to the SOUND value.¶

The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.1.3 of [RFC6350]) converts to a Directory object (Section 2.6.2 of [RFC9553]) in the Card object's directories property (Figure 48). The Directory object's kind property is set to "entry". The uri property is set to the SOURCE property value.¶

The PREF and MEDIATYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.4.1 of [RFC6350]) converts to a Phone object (Section 2.3.3 of [RFC9553]) in the Card object's phones property (Figure 49).¶

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 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 value of the TEL property converts to the Phone object's number property.¶

The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.6.1 of [RFC6350]) converts to a Title object (Section 2.2.5 of [RFC9553]) in the Card object's titles property (Figure 50). The TITLE property value converts to the Title object name property.¶

The same rules as in Section 2.3.39 apply for setting the organizationId property of the Title object.¶

The ALTID and LANGUAGE parameters convert according to the rules defined in Section 2.2.¶

TITLE:Research Scientist

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

2.3.45. TZ

The TZ property (Section 6.5.1 of [RFC6350]) converts to an Address object (Section 2.5.1 of [RFC9553]) in the Card object's addresses property.¶

A value of type TEXT converts to the Address object's timeZone property.¶

A value of type UTC-OFFSET converts to the Address object's timeZone property if the offset has zero minutes and the hour offset is between -12 and +14, both inclusively. Note that:¶

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

See Section 2.3.1 how to convert the TZ property together with the ADR and GEO property.¶

Any other value of type UTC-OFFSET or URI does not convert to an IANA-registered property in JSContact. To convert such property, see Section 4.1.1.¶

2.3.46. UID

The UID property (Section 6.7.6 of [RFC6350]) converts to the Card object's uid property (Figure 51).¶

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

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

2.3.47. URL

The URL property (Section 6.7.8 of [RFC6350]) converts to a Link object (Section 2.6.3 of [RFC9553]) in the Card object's links property (Figure 52). The Link object's uri property is set to the URL value.¶

The PREF and TYPE parameters convert according to the rules defined in Section 2.2.¶

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 (Section 6.7.9 of [RFC6350]) does not convert to a standard JSContact element. Implementations MAY convert it to the "properties" property of the VCard object (Section 4.1.1).¶

2.3.49. X-ABLabel

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

The group name is not preserved; implementations are free to choose any unique group name when converting back to vCard. For an example on how to preserve the group name, see Section 2.2.9.¶

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 (Section 6.1.5 of [RFC6350]) does not convert to a standard JSContact element. Implementations MAY convert it to the "properties" property of the VCard object (Section 4.1.1).¶

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 that JSContact object property to which the vCard property value converted to.¶

The key MUST be a valid key of a PatchObject as defined in 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 54 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"