JSContact: Converting from and to vCard

2.4.2. KIND

The KIND property converts to the kind property (Figure 8). 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 converts to a Directory object in the directories property (Figure 9). The 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 as 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

This converts to an entry in the vCardProps property, see Section 2.15.1.¶

2.5.1. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY

The BDAY and ANNIVERSARY properties and the extensions BIRTHPLACE, DEATHDATE, DEATHPLACE described in [RFC6474] are represented as Anniversary objects included in the anniversaries property (Figure 10):¶

• BDAY and BIRTHPLACE convert to date and place where kind is set to "birth";¶

• DEATHDATE and DEATHPLACE convert to date and place where kind is set to "death";¶

• ANNIVERSARY converts to date where kind is "wedding".¶

Both birth and death places are represented as instances of the Address object.¶

The BIRTHPLACE and DEATHPLACE properties that are represented as geo URIs convert to Address instances including only the coordinates property. If the URI value is not a geo URI, the place is ignored.¶

The ALTID and LANGUAGE parameters of both BIRTHPLACE and DEATHPLACE properties convert according to the rules as 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 converts to the Name object in the name property. Its value converts to the Name object full property (Figure 11). If the LANGUAGE parameter is set, then the FN property converts as outlined in Section 2.3.10. In the unexpected case that the vCard contains more than one FN property without LANGUAGE parameter, then convert the FN property that has the least parameters set to the full property. If multiple such FN properties are present, choose any of them. All other FN properties convert to the vCardProps (Section 2.15.1) property.¶

FN:John Q. Public, Esq.

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

2.5.3. GENDER

This does not map to an IANA-registered property in JSContact. To convert this property, see Section 2.15.1. Note the alternative JSContact speakToAs property which defines how to address and refer to an individual represented by the card, as do the newly defined vCard GRAMGENDER and PRONOUNS properties of [I-D.ietf-calext-vcard-jscontact-extensions].¶

2.5.4. GRAMGENDER and PRONOUNS

The GRAMGENDER property converts to the grammaticalGender property of the SpeakToAs object (Figure 12).¶

The PRONOUNS property converts to an entry in the pronouns property of the SpeakToAs object (Figure 12).¶

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

If the JSCOMPS (Section 3.3.1) parameter is set, then the Name isOrdered property value is "true", and the defaultSeparator and any separator name components are set according to the parameter value. The components list MUST adhere to the order of the JSCOMPS parameter value.¶

If the JSCOMPS parameter is not set, then the Name isOrdered property value is "false" and the defaultSeparator property MUST NOT be set. The components list 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 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 3.3.1 for examples of using the JSCOMPS parameter for vCard structured property values.¶

2.5.6. NICKNAME

A NICKNAME property converts to Nickname object in the nicknames property (Figure 14). The name property is set to the NICKNAME property value.¶

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

NICKNAME:Johnny

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

2.5.7. PHOTO

A PHOTO property converts to an entry in the media property (Figure 15). The entry value is a Media object whose kind property is set to photo and uri property is set to the PHOTO value.¶

The PREF and MEDIATYPE parameters convert according to the rules as 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 converts to an Address object in the addresses property. Each component in the ADR property structured value converts to an AddressComponent in the Address components property.¶

[I-D.ietf-calext-vcard-jscontact-extensions] defines new component for the ADR property. Implementations SHOULD set these new components, even if all their values are the empty string.¶

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

If the JSCOMPS (Section 3.3.1) parameter is set, then the Address isOrdered property value is "true", and the defaultSeparator and any separator name components are set according to the parameter value. The components list MUST adhere to the order of the JSCOMPS parameter value.¶

If the JSCOMPS parameter is not set, then the Address isOrdered property value is "false" and the defaultSeparator property MUST NOT be set. The components list MUST follow the order of values in the ADR structured value when read from left to right.¶

The LABEL parameter converts to the Address full property.¶

The GEO parameter converts to the Address coordinates property.¶

The TZ parameter converts to the Address timeZone property.¶

The CC parameter as defined in [RFC8605] converts to the Address countryCode property.¶

The PREF and TYPE parameters convert according to the rules as defined in Section 2.3. The ADR-specific values of the TYPE parameter defined in Sections 5.1 and 5.2 of [I-D.ietf-calext-vcard-jscontact-extensions] convert to the corresponding entries of the contexts property as defined in Section 2.5.1 of [I-D.ietf-calext-jscontact].¶

The ALTID and LANGUAGE parameters convert according to the rules as defined in Section 2.3. Each possible language-dependent alternative is represented as an entry of the PatchObject map where the key references the full property.¶

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

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

2.7.1. EMAIL

An EMAIL property converts to an entry in the emails property (Figure 17). The entry value is an EmailAddress object. The address property is set to the EMAIL value.¶

The PREF and TYPE parameters convert according to the rules as 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

An IMPP property converts to an entry in the onlineServices property (Figure 18). The entry value is an OnlineService object. The vCardName property is set to "impp" and the uri property is set to the IMPP value.¶

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

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

"onlineServices": {
  "OS-1": {
    "uri": "xmpp:alice@example.com",
    "pref": 1,
    "vCardName": "impp"
  }
}

2.7.3. LANG

A LANG property converts to an entry in the preferredLanguages property (Figure 19). The entry value is an LanguagePref object. The LanguagePref language property value is the LANG property value.¶

The PREF and TYPE parameters convert according to the rules as 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 converts to the language property (Figure 20).¶

LANGUAGE:de-AT

"language": "de-AT"

Note: This property is defined in [I-D.ietf-calext-vcard-jscontact-extensions].¶

2.7.5. SOCIALPROFILE

A SOCIALPROFILE property converts to an entry in the onlineServices property (Figure 21). The entry value is an OnlineService object. The vCardName property is set to "socialprofile" or can be omitted. If the value type of the SOCIALPROFILE is URI, the uri property is set to the SOCIALPROFILE value. Otherwise, the user property is set to the SOCIALPROFILE value.¶

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

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

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

Note: This property is defined in [I-D.ietf-calext-vcard-jscontact-extensions].¶

2.7.6. TEL

A TEL property converts to an entry in the phones property (Figure 22). The entry value is a Phone object.¶

The TEL-specific values of the TYPE parameter convert to the features property keys as outlined in table Table 3. Note that Section 6.4.1 of [RFC6350] defines the default TYPE of TEL to be voice, but the default Phone features property is absent by default. Accordingly, an implementation SHOULD only set the Phone features property if the TEL property actually has a TEL-specific TYPE parameter set.¶

The value of the TEL property converts to the Phone number property.¶

The PREF and TYPE parameters convert according to the rules as 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

This converts to the coordinates property of the Address object. Also see Section 2.8.3 to determine which Address object instance to convert to.¶

2.8.2. TZ

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

A value of type UTC-OFFSET converts to the timeZone property in the Address object if the offset has zero minutes and the hour offset is in the range -12 <= 14:¶

• 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 2.15.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 are set on any other ADR, GEO and TZ properties.¶

2.9.1. CONTACT-URI

A CONTACT-URI property as defined in [RFC8605] is represented as an entry of the links property (Figure 23). The entry value is a Link object whose kind property is set to contact and uri property is set to the CONTACT-URI value.¶

The PREF and TYPE parameters convert according to the rules as 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

A LOGO property converts to an entry in the media property (Figure 24). The entry value is a Media object whose kind property is set to logo and uri property is set to the LOGO value.¶

The PREF and TYPE parameters convert according to the rules as 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 uids of the contact cards composing the group are included in the members property (Figure 25).¶

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

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

An ORG property converts to an entry in the organizations property (Figure 26). The entry value is an Organization object whose name property contains the organizational name, and the units property is an array of OrgUnit objects each containing the organizational unit name in the name 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, LANGUAGE parameters convert according to the rules as 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 as 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

This converts to an entry in the relatedTo property (Figure 27). The property value converts to the key in the relatedTo property. The TYPE parameters convert to the relation of the Relation object value. Any other parameters convert as defined in Section 2.15.2.¶

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

Both TITLE and ROLE properties are represented as entries of the titles property (Figure 28). The entry value is a Title object whose kind property is set to title or role for TITLE and ROLE vCard properties, respectively. The name property is set to the vCard property value.¶

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

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

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

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

2.10.1. EXPERTISE

An EXPERTISE property as defined in [RFC6715] is represented as a PersonalInfo object in the personalInfo property (Figure 29). The kind property is set to "expertise".¶

The INDEX parameter converts according to the rules as 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

A HOBBY property as defined in [RFC6715] is represented as a PersonalInfo object in the personalInfo property (Figure 30). The kind property is set to "hobby".¶

The INDEX parameter converts according to the rules as 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

An INTEREST property as defined in [RFC6715] is represented as a PersonalInfo object in the personalInfo property (Figure 31). The kind property is set to "interest".¶

The INDEX parameter converts according to the rules as 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 [RFC6715] converts to a Directory object in the directories property (Figure 32). The 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 as 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

A CATEGORIES property converts to a set of entries of the keywords property (Figure 33). 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 map 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 and PID Parameter

These convert to the vCardProps (Section 2.15.1) and vCardParams (Section 2.15.2) properties.¶

2.11.3. CREATED

The CREATED property converts to the created property (Figure 34).¶

CREATED:19940930T143510Z

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

Note: This property is defined in [I-D.ietf-calext-vcard-jscontact-extensions].¶

2.11.4. NOTE

A NOTE property converts to a Note object in the notes map (Figure 35).¶

The ALTID and LANGUAGE parameters convert according to the rules as 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 converts to the prodId property (Figure 36).¶

PRODID:ACME Contacts App version 1.23.5

"prodId": "ACME Contacts App version 1.23.5"

2.11.6. REV

The REV property converts to the updated property (Figure 37).¶

REV:19951031T222710Z

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

2.11.7. SOUND

A SOUND property converts to an entry in the media property (Figure 38). The entry value is a Media object whose kind property is set to sound and uri property is set to the SOUND value.¶

The PREF and TYPE parameters convert according to the rules as 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 corresponds to the uid property (Figure 39).¶

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

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

2.11.9. URL

A URL property converts to an entry in the links property (Figure 40). The entry value is a Link object whose uri property is set to the URL value.¶

The PREF and TYPE parameters convert according to the rules as 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

This converts to an entry in the vCardProps (Section 2.15.1) property.¶

2.11.11. X-ABLabel

This property is experimental but widely in use in existing vCard data. It converts to the label property of a JSContact object type. The X-ABLabel property is preceded by a vCard property group name, and the label converts to the JSContact object which got converted from a vCard property having 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 how to preserve the group name see Section 2.3.8.¶

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

A KEY property converts to an entry in the cryptoKeys property (Figure 42). The entry value is a CryptoKey object whose uri property is set to the KEY value.¶

The PREF and TYPE parameters convert according to the rules as 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

A CALADRURI property converts to an entry in the schedulingAddresses property (Figure 43). The entry value is a SchedulingAddress object whose uri property is set to the CALADRURI value.¶

The PREF parameter converts according to the rules as 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

A CALURI property converts to an entry in the calendars property (Figure 44). The entry value is a Calendar object whose kind property is set to calendar and uri property is set to the CALURI value.¶

The PREF and TYPE parameters convert according to the rules as 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

An FBURL property converts to an entry in the calendars property (Figure 45). The entry value is a Calendar object whose kind property is set to freeBusy and uri property is set to the FBURL value.¶

The PREF and TYPE parameters convert according to the rules as 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 object types 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 3.2.1) vCard property and JSPTR (Section 3.3.2) vCard parameter by which such JSContact properties MAY be represented in vCard. Implementations MAY choose to convert differently if they deem that more appropriate.¶

3.3.1. JSCOMPS

Parameter name:

JSCOMPS¶

Purpose:

This parameter 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 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 two 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 by default is zero, 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. Figure 52 and Figure 53 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 COMMA (U+002C), followed by zero or more Section 3.3 of [RFC6350] characters, where the COMMA (U+002c) and SEMICOLON (U+003B) character MUST be escaped according to the rules defined in Section 3.4 of [RFC6350]. Figure 54 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 [I-D.ietf-calext-vcard-jscontact-extensions].¶
  • 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

¶

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,\, ;11;s, ;10;3":;;54321 Oak St;Reston;;;;;;;Oak St;54321;;;;;;

3.3.2. JSPTR

Parameter name:

JSPTR¶

Purpose:

This parameter contains a JSON pointer [RFC6901] that relates the vCard JSPROP (Section 3.2.1) property to a JSContact 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 3.2.1.¶

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

¶