JSContact: Converting from and to vCard

2.1.1. The Card uid Property

The UID property converts to the "uid" property of the Card object, see Section 2.11.8. In contrast to JSContact version "2.0", the Card "uid" property was mandatory in version "1.0".¶

Implementations that convert a vCard without a UID property [RFC6350] (Section 6.7.6) to a Card of version "2.0" or higher MUST NOT generate a unique identifier as value for the uid property [RFC9553] (Section 2.1.9).¶

When converting a vCard without UID property to JSContact version "1.0", implementations MUST generate a value for the uid property. Generating unique identifiers is implementation-specific. An implementation SHOULD generate the same value when generating the same Card multiple times. Section 2 of [I-D.ietf-calext-jscontact-uid] describes why this is problematic. Consequently, implementations SHOULD NOT convert to version "1.0" Card objects.¶

2.4.2. KIND

The KIND property (Section 6.1.4 of [RFC6350]) converts to the kind property (Figure 7). 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.4.3. 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 8). 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.3.¶

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

2.5.1. ANNIVERSARY, BDAY, BIRTHPLACE, DEATHDATE, and DEATHPLACE

The following properties all convert to Anniversary objects in the Card object's anniversaries property (Figure 9):¶

• ANNIVERSARY (Section 6.2.6 of [RFC6350])¶
• BDAY (Section 6.2.5 of [RFC6350])¶
• BIRTHPLACE (Section 2.1 of [RFC6474])¶
• DEATHDATE (Section 2.3 of [RFC6474])¶
• DEATHPLACE (Section 2.2 of [RFC6474])¶

BDAY and BIRTHPLACE convert to an Anniversary object (Section 2.8.1 of [RFC9553]) having the date and place properties set. The kind property is set to "birth".¶

DEATHDATE and DEATHPLACE convert to an Anniversary object having the date and place properties set. The Anniversary object's kind property is set to "death".¶

ANNIVERSARY converts to the Anniversary object's date property. The Anniversary object's kind property is set to "wedding".¶

If the BIRTHPLACE or DEATHPLACE property value is of type URI using the "geo:" URI scheme, then it converts to the Address object's coordinates property. If the value type is TEXT then it converts to the Address object's full property. Otherwise it does not convert to a standard JSContact element. Implementations MAY convert it to the "properties" property of the VCard object (Section 4.1.1).¶

The ALTID and LANGUAGE parameters of both the BIRTHPLACE and DEATHPLACE properties convert according to the rules defined in Section 2.3.¶

BDAY:19531015T231000Z
BIRTHPLACE:
 123 Main Street\nAny Town, CA 91921-1234\nU.S.A.
DEATHDATE:19960415
DEATHPLACE:
 5 Court Street\nNew England, ND 58647\nU.S.A.
ANNIVERSARY:19860201

"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."
    }
  },
  "ANNIVERSARY-2" : {
    "kind": "death",
    "date": {
      "year": 1996,
      "month": 4,
      "year": 15
    },
    "place": {
      "full": "5 Court Street\nNew England, ND 58647\nU.S.A."
    }
  },
  "ANNIVERSARY-3" : {
    "kind": "wedding",
    "date": {
      "year": 1986,
      "month": 2,
      "day": 1
    }
  }
}

2.5.2. FN

The FN property (Section 6.2.1 of [RFC6350]) converts to the Name object's full property (Figure 10). If the LANGUAGE parameter is set, then the FN property converts as outlined in Section 2.3.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.5.3. 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.5.4. GRAMGENDER and PRONOUNS

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

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

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

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

2.5.5. 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 N property structured value converts to a NameComponent in the Name object's components property. The following table shows this relation:¶

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 1. 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.5.6. 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 13). The name property is set to the NICKNAME property value.¶

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

NICKNAME:Johnny

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

2.5.7. 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 14). 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.3.¶

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

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

2.6.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 ADR-structured property value converts to an AddressComponent in the Address object's components property.¶

[RFC9554] defines new components for the ADR property. Implementations SHOULD set these new components, even if all their values are the empty string.¶

The following table shows how the ADR component and AddressComponent kind relate:¶

If the JSCOMPS (Section 5.1.1) parameter is set, 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 PREF and TYPE parameters convert according to the rules defined in Section 2.3. 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.3. 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.7.1. 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 16). 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.3.¶

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.7.2. 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 17). 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.3.¶

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.7.3. 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 18). 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.3.¶

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.7.4. LANGUAGE

The LANGUAGE property (Section 3.3 of [RFC9554]) converts to the Card object's language property (Figure 19).¶

LANGUAGE:de-AT

"language": "de-AT"

2.7.5. 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 20). 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.3.¶

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

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

2.7.6. 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 21).¶

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

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.8.1. GEO

The GEO property (Section 6.5.2 of [RFC6350]) converts to the Address object's coordinates property (Section 2.5.1 of [RFC9553]). Also see Section 2.8.3 to determine which Address object instance to convert to.¶

2.8.2. TZ

The TZ property (Section 6.5.1 of [RFC6350]) converts 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".¶

For such property values, also see Section 2.8.3 to determine which Address object instance to convert to.¶

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

2.8.3. Combining Geographical Properties

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

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

2.9.1. 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 22). 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.3.¶

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

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

2.9.2. 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 23). 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.3.¶

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

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

2.9.3. MEMBER

The MEMBER property (Section 6.6.5 of [RFC6350]) converts to the Card object's members property (Figure 24). 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.9.4. 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 25). 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.3.¶

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

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.9.5. RELATED

The RELATED property (Section 6.6.6 of [RFC6350]) converts to the Card object's relatedTo property (Figure 26). 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.9.6. TITLE and ROLE

The TITLE (Section 6.6.1 of [RFC6350]) and ROLE (Section 6.6.2 of [RFC6350]) properties convert to a Title object (Section 2.2.5 of [RFC9553]) in the Card object's titles property (Figure 27). The Title object's kind property is set to "title" or "role" for the TITLE and ROLE vCard properties, respectively. The name property is set to the vCard property value.¶

The value of the organizationId property can be derived if the TITLE or ROLE property is a member of a vCard property group and if exactly one other ORG property is also a part of that group.¶

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

TITLE:Research Scientist
group1.ROLE:Project Leader
group1.ORG:ABC, Inc.

"titles": {
  "TITLE-1": {
    "kind": "title",
    "name": "Research Scientist"
  },
  "TITLE-2": {
    "kind": "role",
    "name": "Project Leader",
    "organizationId": "ORG-1"
  }
},
"organizations": {
  "ORG-1": {
    "name": "ABC, Inc."
  }
}

2.10.1. 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 28). The PersonalInfo object's kind property is set to "expertise".¶

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

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.10.2. 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 29). The PersonalInfo object's kind property is set to "hobby".¶

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

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.10.3. 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 30). The PersonalInfo object's kind property is set to "interest".¶

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

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.10.4. 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 31). 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.3.¶

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.11.1. CATEGORIES

The CATEGORIES property (Section 6.7.1 of [RFC6350]) converts to a set of entries of the Card object's keywords property (Figure 32). 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.11.2. 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.11.3. CREATED

The CREATED property (Section 3.1 of [RFC9554]) converts to the Card object's created property (Figure 33).¶

CREATED:19940930T143510Z

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

2.11.4. 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 34).¶

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

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.11.5. PRODID

The PRODID property (Section 6.7.3 of [RFC6350]) converts to the Card object's prodId property (Figure 35).¶

PRODID:ACME Contacts App version 1.23.5

"prodId": "ACME Contacts App version 1.23.5"

2.11.6. REV

The REV property (Section 6.7.4 of [RFC6350]) converts to the Card object's updated property (Figure 36).¶

REV:19951031T222710Z

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

2.11.7. 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 37). 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.3.¶

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

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

2.11.8. UID

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

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

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

2.11.9. 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 39). 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.3.¶

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

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

2.11.10. VERSION

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

2.11.11. 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.3.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.12.1. 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 41). 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.3.¶

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

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

2.13.1. 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 42). 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.3.¶

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.13.2. 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 43). 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.3.¶

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.13.3. 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 44). 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.3.¶

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"
  }
}

3.1.1. Converting Unknown Properties

JSContact objects may contain properties for which no IANA-registered vCard property is defined. For example, a JSContact object may contain vendor-specific properties of which the semantics or purpose are unknown.¶

This specification defines the new JSPROP (Section 5.2.1) vCard property and JSPTR (Section 5.1.3) vCard parameter by which such JSContact properties MAY be represented in vCard. Implementations MAY choose to convert differently if they deem that more appropriate.¶

5.1.1. JSCOMPS

Parameter name:

JSCOMPS¶

Purpose:

Defines the order and separators for the elements of a structured property value.¶

Description:

The JSCOMPS parameter value facilitates converting name and address components between JSContact and vCard. It preserves the order of the components of the JSContact property and contains the verbatim values of separator components.¶

If this parameter is set and its value is valid (see later), then implementations MUST set the isOrdered property of the Name or Address object to "true". Otherwise, they MUST set the isOrdered property value to "false".¶

The JSCOMPS parameter value is a structured type value. Its value MUST be quoted. The parameter value consists of a sequence of entries, separated by the SEMICOLON character (U+003B). The first entry defines the value of the defaultSeparator property. If it is the empty string, then no default separator is defined. Otherwise, the first entry MUST be a separator entry. All following entries processed in order result in an ordered list of JSContact components and MUST be one of the following two kinds:¶

1. A positional. This refers to a component value in the vCard structured value. A position consists of the numeric index of a component in the structured value, optionally followed by a COMMA (U+002C) character and the non-zero index of a value within that component. The zero index selects the first component or value, respectively. The second index is zero by default, in which case it MUST be omitted (as well as the leading COMMA).¶

   The resulting JSContact component is formed by determining its kind by the position in the vCard structured value. The component value is the verbatim value of the vCard component. Figures 46 and 47 illustrate this by example.¶

2. A separator. This contains the verbatim value of a separator component. It starts with the LATIN SMALL LETTER S (U+0073) character, followed by the COMMA (U+002C) character, followed by zero or more "param-value" characters (see Section 3.3 of [RFC6350]), where the COMMA (U+002C) and SEMICOLON (U+003B) characters MUST be escaped according to the rules defined in Section 3.4 of [RFC6350]. Figure 48 illustrates this by example.¶

   The resulting JSContact component is formed by setting its kind to "separator" and its value to the verbatim value of the entry.¶

A JSCOMPS parameter value is valid if and only if:¶

• All indexes in the positional entries refer to an existing component value in the vCard property value.¶

• The count of positional entries equals the count of deduplicated component values. Deduplication is required because some values may occur in both their designated and backwards-compatible components in the vCard property value:¶

  • A value that occurs in both the N property secondary surname component and the family name component only counts once.¶
  • A value that occurs in both the N property generation component and the honorific suffix component only counts once.¶
  • A value in the ADR property street address component does not count if the ADR property value contains a value in one of the new components defined in [RFC9554].¶
  • All other values count once each.¶

Format definition:

jscomps-param     = "JSCOMPS" "="
                      DQUOTE [jscomps-entry-sep ] ";" jscomps-entrylist DQUOTE

jscomps-entrylist  = jscomps-entry *(";" jscomps-entry)
jscomps-entry      = jscomps-entry-pos / jscomps-entry-sep
jscomps-entry-pos  = 1*DIGIT [ "," 1*DIGIT ]
jscomps-entry-sep  = "s" "," jscomps-entry-verb
jscomps-entry-verb = *QSAFE-CHAR ; encode special characters according to RFC 6868

¶

Example(s):

The following example demonstrates the use of positional entries for the name "Jane Doe". The given name is ordered before the surname. No secondary index is required for either positional because both are zero.¶

"name": {
  "components": [
    { "kind": "given", "value": "Jane" },
    { "kind": "surname", "value": "Doe" }
  ],
  "isOrdered": true
}

N;JSCOMPS=";1;0":Doe;Jane;;;;;;
FN;DERIVED=TRUE:Jane Doe

The following example demonstrates a secondary positional index. The "Jr." generation marker only counts once because it occurs in both the designated generation component and the backwards-compatible honorific suffixes component.¶

"name": {
  "components": [
    { "kind": "given", "value": "John" },
    { "kind": "given2", "value": "Philip" },
    { "kind": "given2", "value": "Paul" },
    { "kind": "surname", "value": "Stevenson" },
    { "kind": "generation", "value": "Jr." },
    { "kind": "credential", "value": "M.D." }
  ],
  "isOrdered": true
}

N;JSCOMPS=";1;2;2,1;0;6;4,1":Stevenson;John;Philip,Paul;;Jr.,M.D.;;Jr.

The following example demonstrates the use of separator entries for the (shortened for brevity) address "54321 Oak St, Reston". The first entry defines the default separator to be ", ". The second and fourth positional entries are separated with the separator value " ". For backwards compatibility, the street address component of the ADR property contains both the street number and name, but it is not referred to in the JSCOMPS parameter and does not contribute to the count of values.¶

"addresses": {
  "a1": {
    "components": [
      { "kind": "number", "value": "54321" },
      { "kind": "separator", "value": " " },
      { "kind": "name", "value": "Oak St" },
      { "kind": "locality", "value": "Reston" }
    ],
    "defaultSeparator": ", ",
    "isOrdered": true
  }
}

ADR;JSCOMPS="s,\, ;10;s, ;11;3":;;54321 Oak St;Reston;;;;;;;Oak St;54321;;;;;;

5.1.2. JSID

Parameter Name:

JSID¶

Purpose:

Specifies the JSContact identifier of the associated property.¶

Description:

This parameter specifies the JSON object key of the JSContact object to which a vCard property converts to. For example, this parameter set on an EMAIL property defines the key of the EmailAddress object in the Card object's "emails" property (see below for an example).¶

The value of the JSID parameter MUST be a valid key according to the definition of the JSContact property to which the property that this parameter is set on converts to. Typically, this requires the value to be a valid Id [RFC9553] (Section 1.4.1).¶

Format Definition:

jsid-param  = "JSID" "=" param-value

¶

Example(s):

EMAIL;JSID=xyz:jane_doe@example.com

"emails": {
  "xyz": {
    "address": "jane_doe@example.com"
  }
}

¶

5.1.3. JSPTR

Parameter name:

JSPTR¶

Purpose:

This parameter is set on a JSPROP (Section 5.2.1) property. Its value is a JSON pointer [RFC6901] that points to the JSContact property having the value of the JSPROP property.¶

Description:

This parameter has a single value that MUST be a valid JSON pointer as defined in [RFC6901]. Note that the value MUST be quoted according to the "param-value" ABNF in [RFC6350].¶

Format definition:

jsptr-param  = "JSPTR" "=" param-value
             ; also see param-value in RFC 6350, Section 3.3

¶

Example(s):

This illustrates a simple example. For further examples, see Section 5.2.1.¶

JSPROP;JSPTR="example.com:foo":"bar"

¶