Skip to main content

JSContact: Converting from and to vCard
draft-ietf-calext-jscontact-vcard-04

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Active".
Authors Mario Loffredo , Robert Stepanek
Last updated 2022-11-25
Replaces draft-ietf-jmap-jscontact-vcard
RFC stream Internet Engineering Task Force (IETF)
Formats
Reviews
Additional resources Mailing list discussion
Stream WG state WG Document
Associated WG milestone
Nov 2022
Submit JSON Contact document to IESG
Document shepherd (None)
IESG IESG state I-D Exists
Consensus boilerplate Unknown
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-ietf-calext-jscontact-vcard-04
calext                                                       M. Loffredo
Internet-Draft                                       IIT-CNR/Registro.it
Intended status: Standards Track                             R. Stepanek
Expires: 29 May 2023                                            Fastmail
                                                        25 November 2022

                JSContact: Converting from and to vCard
                  draft-ietf-calext-jscontact-vcard-04

Abstract

   This document defines how to convert contact information defined in
   the JSContact specification from and to vCard.

Note

   This note is to be removed before publishing as an RFC.

   The verbatim case-insensitive string rfc0000 in this document is a
   placeholder.  It will be replaced with the RFC number of the
   JSContact specification.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 29 May 2023.

Copyright Notice

   Copyright (c) 2022 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.

Loffredo & Stepanek        Expires 29 May 2023                  [Page 1]
Internet-Draft               jscontact-vcard               November 2022

   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
     1.1.  Motivation  . . . . . . . . . . . . . . . . . . . . . . .   4
     1.2.  Conventions Used in This Document . . . . . . . . . . . .   5
   2.  Converting vCard to JSContact . . . . . . . . . . . . . . . .   5
     2.1.  General rules . . . . . . . . . . . . . . . . . . . . . .   5
       2.1.1.  The uid property  . . . . . . . . . . . . . . . . . .   5
       2.1.2.  Choosing identifiers  . . . . . . . . . . . . . . . .   5
     2.2.  vCard Value Data Types  . . . . . . . . . . . . . . . . .   5
       2.2.1.  BOOLEAN . . . . . . . . . . . . . . . . . . . . . . .   5
       2.2.2.  DATE, TIME, DATE-TIME, DATE-AND-OR-TIME, and
               TIMESTAMP . . . . . . . . . . . . . . . . . . . . . .   6
       2.2.3.  INTEGER . . . . . . . . . . . . . . . . . . . . . . .   6
       2.2.4.  FLOAT . . . . . . . . . . . . . . . . . . . . . . . .   6
       2.2.5.  LANGUAGE-TAG  . . . . . . . . . . . . . . . . . . . .   6
       2.2.6.  TEXT  . . . . . . . . . . . . . . . . . . . . . . . .   6
       2.2.7.  URI . . . . . . . . . . . . . . . . . . . . . . . . .   6
       2.2.8.  UTC-OFFSET  . . . . . . . . . . . . . . . . . . . . .   6
     2.3.  vCard Parameters  . . . . . . . . . . . . . . . . . . . .   6
       2.3.1.  ALTID . . . . . . . . . . . . . . . . . . . . . . . .   7
       2.3.2.  AUTHOR  . . . . . . . . . . . . . . . . . . . . . . .   7
       2.3.3.  AUTHOR-NAME . . . . . . . . . . . . . . . . . . . . .   7
       2.3.4.  CALSCALE  . . . . . . . . . . . . . . . . . . . . . .   7
       2.3.5.  CREATED . . . . . . . . . . . . . . . . . . . . . . .   7
       2.3.6.  DERIVED . . . . . . . . . . . . . . . . . . . . . . .   7
       2.3.7.  GEO . . . . . . . . . . . . . . . . . . . . . . . . .   8
       2.3.8.  GROUP . . . . . . . . . . . . . . . . . . . . . . . .   8
       2.3.9.  LANGUAGE  . . . . . . . . . . . . . . . . . . . . . .   9
       2.3.10. LEVEL . . . . . . . . . . . . . . . . . . . . . . . .  11
       2.3.11. MEDIATYPE . . . . . . . . . . . . . . . . . . . . . .  12
       2.3.12. PID . . . . . . . . . . . . . . . . . . . . . . . . .  12
       2.3.13. PREF  . . . . . . . . . . . . . . . . . . . . . . . .  12
       2.3.14. PROP-ID . . . . . . . . . . . . . . . . . . . . . . .  12
       2.3.15. RANKS . . . . . . . . . . . . . . . . . . . . . . . .  13
       2.3.16. SERVICE-TYPE  . . . . . . . . . . . . . . . . . . . .  13
       2.3.17. SORT-AS . . . . . . . . . . . . . . . . . . . . . . .  13
       2.3.18. TYPE  . . . . . . . . . . . . . . . . . . . . . . . .  13
       2.3.19. TZ  . . . . . . . . . . . . . . . . . . . . . . . . .  13
     2.4.  VALUE . . . . . . . . . . . . . . . . . . . . . . . . . .  13
     2.5.  General Properties  . . . . . . . . . . . . . . . . . . .  13
       2.5.1.  BEGIN and END . . . . . . . . . . . . . . . . . . . .  13

Loffredo & Stepanek        Expires 29 May 2023                  [Page 2]
Internet-Draft               jscontact-vcard               November 2022

       2.5.2.  KIND  . . . . . . . . . . . . . . . . . . . . . . . .  14
       2.5.3.  SOURCE  . . . . . . . . . . . . . . . . . . . . . . .  14
       2.5.4.  XML . . . . . . . . . . . . . . . . . . . . . . . . .  15
     2.6.  Identification Properties . . . . . . . . . . . . . . . .  15
       2.6.1.  BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE,
               ANNIVERSARY . . . . . . . . . . . . . . . . . . . . .  15
       2.6.2.  GENDER  . . . . . . . . . . . . . . . . . . . . . . .  18
       2.6.3.  GRAMMATICAL-GENDER and PRONOUNS . . . . . . . . . . .  18
       2.6.4.  FN  . . . . . . . . . . . . . . . . . . . . . . . . .  19
       2.6.5.  N and NICKNAME  . . . . . . . . . . . . . . . . . . .  19
       2.6.6.  PHOTO . . . . . . . . . . . . . . . . . . . . . . . .  20
     2.7.  Delivery Addressing Properties  . . . . . . . . . . . . .  21
       2.7.1.  ADR . . . . . . . . . . . . . . . . . . . . . . . . .  21
     2.8.  Communications Properties . . . . . . . . . . . . . . . .  24
       2.8.1.  CONTACT-CHANNEL-PREF  . . . . . . . . . . . . . . . .  24
       2.8.2.  EMAIL . . . . . . . . . . . . . . . . . . . . . . . .  25
       2.8.3.  IMPP  . . . . . . . . . . . . . . . . . . . . . . . .  26
       2.8.4.  LANG  . . . . . . . . . . . . . . . . . . . . . . . .  27
       2.8.5.  LOCALE  . . . . . . . . . . . . . . . . . . . . . . .  28
       2.8.6.  SOCIALPROFILE . . . . . . . . . . . . . . . . . . . .  29
       2.8.7.  TEL . . . . . . . . . . . . . . . . . . . . . . . . .  30
     2.9.  Geographical Properties . . . . . . . . . . . . . . . . .  31
       2.9.1.  GEO . . . . . . . . . . . . . . . . . . . . . . . . .  31
       2.9.2.  TZ  . . . . . . . . . . . . . . . . . . . . . . . . .  31
       2.9.3.  Combining geographical properties . . . . . . . . . .  32
     2.10. Organizational Properties . . . . . . . . . . . . . . . .  32
       2.10.1.  CONTACT-URI  . . . . . . . . . . . . . . . . . . . .  32
       2.10.2.  LOGO . . . . . . . . . . . . . . . . . . . . . . . .  33
       2.10.3.  MEMBER . . . . . . . . . . . . . . . . . . . . . . .  34
       2.10.4.  ORG  . . . . . . . . . . . . . . . . . . . . . . . .  35
       2.10.5.  RELATED  . . . . . . . . . . . . . . . . . . . . . .  36
       2.10.6.  TITLE and ROLE . . . . . . . . . . . . . . . . . . .  37
     2.11. Personal Information Properties . . . . . . . . . . . . .  38
       2.11.1.  EXPERTISE  . . . . . . . . . . . . . . . . . . . . .  38
       2.11.2.  HOBBY  . . . . . . . . . . . . . . . . . . . . . . .  39
       2.11.3.  INTEREST . . . . . . . . . . . . . . . . . . . . . .  40
       2.11.4.  ORG-DIRECTORY  . . . . . . . . . . . . . . . . . . .  41
     2.12. Explanatory Properties  . . . . . . . . . . . . . . . . .  42
       2.12.1.  CATEGORIES . . . . . . . . . . . . . . . . . . . . .  42
       2.12.2.  CLIENTPIDMAP and PID Parameter . . . . . . . . . . .  43
       2.12.3.  CREATED  . . . . . . . . . . . . . . . . . . . . . .  43
       2.12.4.  NOTE . . . . . . . . . . . . . . . . . . . . . . . .  44
       2.12.5.  PRODID . . . . . . . . . . . . . . . . . . . . . . .  44
       2.12.6.  REV  . . . . . . . . . . . . . . . . . . . . . . . .  45
       2.12.7.  SOUND  . . . . . . . . . . . . . . . . . . . . . . .  45
       2.12.8.  UID  . . . . . . . . . . . . . . . . . . . . . . . .  46
       2.12.9.  URL  . . . . . . . . . . . . . . . . . . . . . . . .  47
       2.12.10. VERSION  . . . . . . . . . . . . . . . . . . . . . .  47

Loffredo & Stepanek        Expires 29 May 2023                  [Page 3]
Internet-Draft               jscontact-vcard               November 2022

       2.12.11. X-ABLabel  . . . . . . . . . . . . . . . . . . . . .  47
     2.13. Security Properties . . . . . . . . . . . . . . . . . . .  48
       2.13.1.  KEY  . . . . . . . . . . . . . . . . . . . . . . . .  48
     2.14. Calendar Properties . . . . . . . . . . . . . . . . . . .  49
       2.14.1.  CALADRURI  . . . . . . . . . . . . . . . . . . . . .  49
       2.14.2.  CALURI . . . . . . . . . . . . . . . . . . . . . . .  50
       2.14.3.  FBURL  . . . . . . . . . . . . . . . . . . . . . . .  51
     2.15. Extended Properties and Parameters  . . . . . . . . . . .  52
     2.16. New JSContact properties  . . . . . . . . . . . . . . . .  52
       2.16.1.  Property vCardProps  . . . . . . . . . . . . . . . .  53
       2.16.2.  Property vCardParams . . . . . . . . . . . . . . . .  53
   3.  Converting JSContact to vCard . . . . . . . . . . . . . . . .  54
     3.1.  Conversion Rules  . . . . . . . . . . . . . . . . . . . .  54
     3.2.  New vCard Properties and Parameters . . . . . . . . . . .  66
       3.2.1.  Property JSCONTACT-PROP . . . . . . . . . . . . . . .  66
       3.2.2.  Parameter JSPTR . . . . . . . . . . . . . . . . . . .  69
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .  70
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  70
     5.1.  New vCard Properties  . . . . . . . . . . . . . . . . . .  70
     5.2.  New vCard Parameters  . . . . . . . . . . . . . . . . . .  70
     5.3.  New JSContact Properties  . . . . . . . . . . . . . . . .  70
     5.4.  New JSContact Types . . . . . . . . . . . . . . . . . . .  71
   6.  Implementation Status . . . . . . . . . . . . . . . . . . . .  71
     6.1.  CNR . . . . . . . . . . . . . . . . . . . . . . . . . . .  72
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  72
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  72
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  73
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  73

1.  Introduction

1.1.  Motivation

   The JSContact data model and format [I-D.ietf-calext-jscontact] aims
   to be an alternative to the widely used vCard [RFC6350] standard and
   jCard [RFC7095].

   While applications might prefer JSContact to exchange contact card
   data with other systems, they are likely to interoperate with
   services and clients that only support vCard or jCard.  Similarly,
   existing contact data providers and consumers already using vCard or
   jCard might want to represent their contact data also in JSContact.

   To achieve this, this document defines a standard how to convert
   contact data between JSContact and vCard (and consequently jCard).

Loffredo & Stepanek        Expires 29 May 2023                  [Page 4]
Internet-Draft               jscontact-vcard               November 2022

1.2.  Conventions Used in This Document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

   In the following of this document, the vCard features, namely
   properties and parameters, are written in uppercase while the Card
   features are written in camel case wrapped in double quotes.

2.  Converting vCard to JSContact

   This section contains the conversion rules from vCard to JSContact
   Card.  Its follows the same structure as the vCard v4 RFC document
   [RFC6350].  Properties and parameters of vCard extension RFCs,
   including the vCard JSContact Extension RFC
   [I-D.ietf-calext-vcard-jscontact-extensions] are added to appropriate
   subsections.

2.1.  General rules

2.1.1.  The uid property

   The UID property in vCard is optional, but the uid property in
   JSContact is mandatory.  Implementations that convert a vCard without
   UID property MUST generate a unique identifier as value for the uid
   property.  They SHOULD generate the same identifier when repeatedly
   converting the same vCard, but they MAY generate different values.
   Consequently, a vCard without UID property MAY does not convert to
   one exact instance of a JSContact card or card group.

2.1.2.  Choosing identifiers

   Multi-valued properties in JSContact typically are represented as a
   JSON object where the object keys are of the Id type and the object
   values are the converted vCard property.  In absence of the PROP-ID
   parameter (see Section 2.3.14), implementations are free to choose
   any identifier for such entries.  Whatever identifier generation
   scheme implementations use, they SHOULD generate values of short
   character length.  For example, this could be an incrementing number
   across all Ids or only unique within one JSON object.

2.2.  vCard Value Data Types

2.2.1.  BOOLEAN

   This converts to the JSContact Boolean type.

Loffredo & Stepanek        Expires 29 May 2023                  [Page 5]
Internet-Draft               jscontact-vcard               November 2022

2.2.2.  DATE, TIME, DATE-TIME, DATE-AND-OR-TIME, and TIMESTAMP

   The TIMESTAMP type generally converts to the UTCDateTime.  It
   converts to the Timestamp type for anniversaries.

   The DATE type converts to the PartialDate type, which only is
   relevant for anniversaries.  This does not apply to DATE values that
   only define a month or a day.

   The TIME, DATE-TIME, DATE-AND-OR-TIME types and DATE type values that
   only define a month or day do not convert to any JSContact type.
   vCard properties or parameters having such values MAY convert as
   defined in Section 2.16.

2.2.3.  INTEGER

   This converts to the JSContact Number type.

2.2.4.  FLOAT

   This converts to the JSContact Int and UnsignedInt types.

2.2.5.  LANGUAGE-TAG

   This converts to the JSContact String type.

2.2.6.  TEXT

   This converts to the JSContact String type.

2.2.7.  URI

   This converts to the JSContact String type.

2.2.8.  UTC-OFFSET

   This either converts to a String containing an IANA TimeZone Database
   entry name (see Section 2.9.2), or it does not convert to any
   JSContact type.  For the latter, vCard properties or parameters
   having such values MAY convert to JSContact as defined in
   Section 2.16.

2.3.  vCard Parameters

Loffredo & Stepanek        Expires 29 May 2023                  [Page 6]
Internet-Draft               jscontact-vcard               November 2022

2.3.1.  ALTID

   This 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.7.1.  To preserve the verbatim
   value of the ALTID parameter, set the JSContact extension properties
   props or params defined in Section 2.16.

2.3.2.  AUTHOR

   The AUTHOR parameter value of a vCard NOTE property converts to the
   uri property of the Author object for this note.  To convert this
   parameter for other vCard properties, see Section 2.16.2.

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

2.3.3.  AUTHOR-NAME

   The AUTHOR-NAME parameter value of a vCard NOTE property converts to
   the name property of the Author object for this note.  To convert
   this parameter for other vCard properties, see Section 2.16.2.

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

2.3.4.  CALSCALE

   This parameter set on a BDAY or ANNIVERSARY property converts to the
   calendarScale property of the PartialDate object type.  To convert
   this parameter for other vCard properties, see Section 2.16.2.

2.3.5.  CREATED

   The CREATED parameter value of a vCard NOTE property converts to the
   created property of the Note object.  To convert this parameter for
   other vCard properties, see Section 2.16.2.

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

2.3.6.  DERIVED

   If this parameter is set to true on a vCard property, then
   implementations MAY choose to not convert that property.  Note: This
   parameter is defined in [I-D.ietf-calext-vcard-jscontact-extensions].

Loffredo & Stepanek        Expires 29 May 2023                  [Page 7]
Internet-Draft               jscontact-vcard               November 2022

2.3.7.  GEO

   This parameter set on an ADR property converts to the JSContact
   coordinates property of the Address object that represents the vCard
   ADR.  To convert this parameter for other vCard properties, see
   Section 2.16.2.

2.3.8.  GROUP

   This parameter exclusively is for use in jCard (see Section 7.1 of
   [RFC7095]).  It 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 that still wish to preserve the exact property group
   name of a vCard property MAY set the group parameter in the JSContact
   extension properties props or params defined in Section 2.16.

       BEGIN:VCARD
       VERSION:4.0
       ...
       item1.TEL;VALUE=uri:tel:+1-555-555-5555
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "phones": {
         "p1": {
           "@type": "Phone",
           "number": "tel:+1-555-555-5555",
           "vCardParams" : {
            "group" : "item1"
           }
         }
       }
       ...
       }

    Figure 1: An example how to preserve the group name in params during
                                conversion.

Loffredo & Stepanek        Expires 29 May 2023                  [Page 8]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       item2.X-FOO:bar
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "vCardProps": [
         ["x-foo", {
           "group": "item2"
         }, "unknown", "bar"]
       ]
       ...
       }

        Figure 2: An example how to preserve the group name in props
                             during conversion.

2.3.9.  LANGUAGE

   This converts to an entry in the localizations property for the vCard
   property that this parameter is set on.  The value of the LANGUAGE
   parameter defines the language key in the localizations property.
   The JSON pointer in the PatchObject is the path to the JSContact
   property that the vCard property converts to.  The value of the
   PatchObject is the converted property value.

   A non-localized Card SHOULD NOT provide less information than any of
   its localizations.  For this, the implementation should choose one of
   the vCard properties to also set in the main Card:

   *  If a vCard property occurs one or more times and at least one has
      not the LANGUAGE parameter set, then the implementation should
      choose the non-localized property among them.

   *  If all vCard properties of the same type have the LANGUAGE
      parameter set, then the implementation should choose one of these
      properties to set both as non-localized and localized property.
      This is to preserve the language information of the property
      value.

   The following two examples illustrate these cases.

Loffredo & Stepanek        Expires 29 May 2023                  [Page 9]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       TITLE:Boss
       TITLE;LANGUAGE=fr:Patron
       ...
       END:VCARD

       {
         "@type": "Card",
         "@version" : "rfc0000",
         ...
         "titles": {
           "t1": {
             "@type": "Title",
             "title": "Boss"
           }
         },
         "localizations": {
           "fr": {
             "titles/t1/title": "Patron"
           }
         }
       }

    Figure 3: LANGUAGE conversion example: patch non-localized property

Loffredo & Stepanek        Expires 29 May 2023                 [Page 10]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       TITLE;LANGUAGE=en:Boss
       TITLE;LANGUAGE=fr:Patron
       ...
       END:VCARD

       {
         "@type": "Card",
         "@version" : "rfc0000",
         ...
         "titles": {
           "t1": {
             "@type": "Title",
             "title": "Boss"
           }
         },
         "localizations": {
           "en": {
             "titles/t1/title": "Boss"
           },
           "fr": {
             "titles": {
               "t1": {
                 "@type": "Title",
                 "title": "Patron"
               }
             }
           }
         }
       }

      Figure 4: LANGUAGE conversion example: patch localized property
                          with empty patch object

2.3.10.  LEVEL

   The LEVEL parameter as defined in [RFC6715] is directly converted to
   the level property of the PersonalInformation type apart from when
   LEVEL is used in the EXPERTISE property; in this case, the values
   convert as in the following:

   *  "beginner" converts to "low";
   *  "average" converts to "medium";
   *  "expert" converts to "high".

Loffredo & Stepanek        Expires 29 May 2023                 [Page 11]
Internet-Draft               jscontact-vcard               November 2022

2.3.11.  MEDIATYPE

   This converts to the mediaType property of the Resource object type.

2.3.12.  PID

   This does not convert to an IANA-registered property in JSContact.
   To convert this parameter, see Section 2.16.2.

2.3.13.  PREF

   This converts to the pref property.

2.3.14.  PROP-ID

   The PROP-ID parameter value of a vCard property converts to the Id of
   the JSContact property to which the vCard property converts to.

    BEGIN:VCARD
    VERSION:4.0
    ...
    TEL;PROP-ID=PHONE-A;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555
    TEL;PROP-ID=PHONE-B;VALUE=uri;TYPE=home:tel:+33-01-23-45-67
    ...
    END:VCARD

    {
    "@type": "Card",
    "@version" : "rfc0000",
    ...
    "phones": {
      "PHONE-A": {
        "@type": "Phone",
        "contexts": { "private": true },
        "features": { "voice": true },
        "number": "tel:+1-555-555-5555;ext=5555",
        "pref": 1
      },
      "PHONE-B": {
        "@type": "Phone",
        "contexts": { "private": true },
        "number": "tel:+33-01-23-45-67"
      }
    },
    ...
    }

                 Figure 5: PROP-ID conversion example

Loffredo & Stepanek        Expires 29 May 2023                 [Page 12]
Internet-Draft               jscontact-vcard               November 2022

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

2.3.15.  RANKS

   The values of this parameter convert to the rank property of the
   NameComponent objects inferred from the N property value.  Note: This
   parameter is defined in [I-D.ietf-calext-vcard-jscontact-extensions].

2.3.16.  SERVICE-TYPE

   This converts to the service property of the OnlineService object
   type.  Note: This parameter is defined in
   [I-D.ietf-calext-vcard-jscontact-extensions].

2.3.17.  SORT-AS

   This converts to the sortAs properties defined for the Name,
   Organization and OrgUnit object types.

2.3.18.  TYPE

   This converts to the contexts property as well as property-specific
   type property values defined in later sections.

2.3.19.  TZ

   This parameter set on an ADR property converts to the JSContact
   timeZone property of the Address object that represents the vCard
   ADR.  Also see the conversion of the TZ property in Section 2.9.2.
   To convert this parameter for other vCard properties, see
   Section 2.16.2.

2.4.  VALUE

   This does not convert to an IANA-registered property in JSContact.
   To preserve properties with experimental values, see Section 2.16.2
   and Section 2.16.1.

2.5.  General Properties

2.5.1.  BEGIN and END

   These do not convert to IANA-registered properties in JSContact.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 13]
Internet-Draft               jscontact-vcard               November 2022

2.5.2.  KIND

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

       BEGIN:VCARD
       VERSION:4.0
       ...
       KIND:individual
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "kind": "individual",
       ...
       }

                     Figure 6: KIND conversion example

2.5.3.  SOURCE

   A SOURCE property converts to an entry in the directories property
   (Figure 7).  The entry value is a DirectoryResource object whose type
   property is set to entry and uri property is set to the SOURCE value.

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

Loffredo & Stepanek        Expires 29 May 2023                 [Page 14]
Internet-Draft               jscontact-vcard               November 2022

    BEGIN:VCARD
    VERSION:4.0
    ...
    SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf
    ...
    END:VCARD

    {
    "@type": "Card",
    "@version" : "rfc0000",
    ...
    "directories": {
       ...
       "ENTRY-1": {
         "@type": "DirectoryResource",
         "type": "entry",
         "uri": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf"
       },
       ...
    },
    ...
    }

                 Figure 7: SOURCE conversion example

2.5.4.  XML

   This does not convert to an IANA-registered property in JSContact.

2.6.  Identification Properties

2.6.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 8):

   *  BDAY and BIRTHPLACE convert to date and place where type is set to
      "birth";
   *  DEATHDATE and DEATHPLACE convert to date and place where type is
      set to "death";
   *  ANNIVERSARY converts to date where type is "wedding".

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

Loffredo & Stepanek        Expires 29 May 2023                 [Page 15]
Internet-Draft               jscontact-vcard               November 2022

   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.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 16]
Internet-Draft               jscontact-vcard               November 2022

    BEGIN:VCARD
    VERSION:4.0
    ...
    BDAY:19531015T231000Z
    BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A.
    DEATHDATE:19960415
    DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A.
    ANNIVERSARY:19860201
    ...
    END:VCARD

    {
    "@type": "Card",
    "@version" : "rfc0000",
    ...
    "anniversaries": {
      "ANNIVERSARY-1" : {
        "@type": "Anniversary",
        "type": "birth",
        "date": "1953-10-15T23:10:00Z",
        "place": {
          "@type": "Address",
          "fullAddress": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A."
        }
      },
      "ANNIVERSARY-2" : {
        "@type": "Anniversary",
        "type": "death",
        "date": "1996-04-15",
        "place": {
          "@type": "Address",
          "fullAddress": "4445 Courtright Street\nNew England, ND 58647\nU.S.A."
        }
      },
      "ANNIVERSARY-3" : {
        "@type": "Anniversary",
        "type": "wedding",
        "date": "1986-02-01"
      }
    },
    ...
    }

    Figure 8: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY
                          conversion example

Loffredo & Stepanek        Expires 29 May 2023                 [Page 17]
Internet-Draft               jscontact-vcard               November 2022

2.6.2.  GENDER

   This does not map to an IANA-registered property in JSContact.  To
   convert this property, see Section 2.16.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 GRAMMATICAL-GENDER and PRONOUNS properties of
   [I-D.ietf-calext-vcard-jscontact-extensions].

2.6.3.  GRAMMATICAL-GENDER and PRONOUNS

   The GRAMMATICAL-GENDER property converts to the grammaticalGender
   property of the SpeakToAs object (Figure 9).

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

       BEGIN:VCARD
       VERSION:4.0
       ...
        GRAMMATICAL-GENDER:NEUTER
        PRONOUNS;PREF=2:they/them
        PRONOUNS;PREF=1:xe/xir
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "speakToAs": {
         "grammaticalGender": "neuter",
         "pronouns": {
           "PRONOUNS-1": {
             "@type": "Pronouns",
             "pronouns": "they/them",
             "pref": 2
           },
           "PRONOUNS-2": {
             "@type": "Pronouns",
             "pronouns": "xe/xir",
             "pref": 1
           }
         }
       },
       ...
       }

Loffredo & Stepanek        Expires 29 May 2023                 [Page 18]
Internet-Draft               jscontact-vcard               November 2022

        Figure 9: GRAMMATICAL-GENDER and PRONOUNS conversion example

2.6.4.  FN

   All the FN instances are represented through the fullName property
   (Figure 10).  The presence of multiple instances is implicitly
   associated with the full name translation in various languages
   regardless of the presence of the ALTID parameter.  Each translation
   converts according to the rules as defined in Section 2.3.

2.6.5.  N and NICKNAME

   The N instances convert to equivalent items of the components array
   of the name property (Figure 10): the N components convert into
   related NameComponent objects as presented in Table 1.  Name
   components SHOULD be ordered such that their values joined by
   whitespace produce a valid full name of this entity.

   Each comma-separated item of the SORT-AS parameter value converts to
   an entry of the sortAs property where the key is the "type" value
   related to the sorted N component and the value is the corresponding
   item.  Absence of a key in the sortAs indicates that its related part
   in the SORT-AS parameter value MUST either the empty string followed
   by COMMA, or no further SORT-AS parts are defined.

                   +====================+==============+
                   | N component        | "type" value |
                   +====================+==============+
                   | Honorific Prefixes | prefix       |
                   +--------------------+--------------+
                   | Given Names        | personal     |
                   +--------------------+--------------+
                   | Family Names       | surname      |
                   +--------------------+--------------+
                   | Additional Names   | additional   |
                   +--------------------+--------------+
                   | Honorific Suffixes | suffix       |
                   +--------------------+--------------+

                      Table 1: N components conversion

   A NICKNAME property converts to an entry in the nickNames property
   (Figure 10).  The entry value is a NickName object.  The name
   property is set to the NICKNAME value.

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

Loffredo & Stepanek        Expires 29 May 2023                 [Page 19]
Internet-Draft               jscontact-vcard               November 2022

    BEGIN:VCARD
    VERSION:4.0
    ...
    FN:Mr.  John Q.  Public\, Esq.
    N;SORT-AS="Public,John":Public;John;Quinlan;Mr.;Esq.
    NICKNAME:Johnny
    ...
    END:VCARD

    {
    "@type": "Card",
    "@version" : "rfc0000",
    ...
    "fullName": "Mr.  John Q.  Public, Esq.",
    "name": {
        "@type": "Name",
        "components":[
          { "@type": "NameComponent", "type": "prefix", "value": "Mr."  },
          { "@type": "NameComponent", "type": "personal", "value": "John" },
          { "@type": "NameComponent", "type": "surname", "value": "Public" },
          { "@type": "NameComponent", "type": "additional", "value": "Quinlan" },
          { "@type": "NameComponent", "type": "suffix", "value": "Esq." }
        ],
        "sortAs": {
            "surname": "Public",
            "given": "John"
        }
    },
    "nickNames": {
       "NICK-1": {
          "@type": "NickName",
          "name": "Johnny"
       }
    },
    ...
    }

            Figure 10: FN, N, NICKNAME conversion example

2.6.6.  PHOTO

   A PHOTO property converts to an entry in the media property
   (Figure 11).  The entry value is a MediaResource object whose type
   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.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 20]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       PHOTO:http://www.example.com/pub/photos/jqpublic.gif
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "media": {
          ...
          "PHOTO-1": {
            "@type": "MediaResource",
            "type": "photo",
            "uri": "http://www.example.com/pub/photos/jqpublic.gif"
          },
          ...
       },
       ...
       }

                    Figure 11: PHOTO conversion example

2.7.  Delivery Addressing Properties

2.7.1.  ADR

   An ADR property converts to an entry in the addresses property
   (Figure 12).  The entry value is an Address object.

   The ADR components convert into the Address properties as presented
   in Table 2 and Table 3.

   The "street address" and "extended address" ADR components MAY be
   converted into either a single StreetComponent item or a combination
   of StreetComponent items.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 21]
Internet-Draft               jscontact-vcard               November 2022

                    +===============+================+
                    | ADR component | Address member |
                    +===============+================+
                    | locality      | locality       |
                    +---------------+----------------+
                    | region        | region         |
                    +---------------+----------------+
                    | postal code   | postcode       |
                    +---------------+----------------+
                    | country name  | country        |
                    +---------------+----------------+

                       Table 2: ADR components vs.
                        Address members conversion

     +===============+======================+========================+
     | ADR component | Single               | Combination of         |
     |               | StreetComponent item | StreetComponent items  |
     +===============+======================+========================+
     | post office   | postOfficeBox        |                        |
     | box           |                      |                        |
     +---------------+----------------------+------------------------+
     | extended      | extension            | extension, building,   |
     | address       |                      | floor, room, apartment |
     +---------------+----------------------+------------------------+
     | street        | name                 | name, number,          |
     | address       |                      | direction              |
     +---------------+----------------------+------------------------+

       Table 3: ADR components vs.  StreetComponent items conversion

   The LABEL parameter converts to the fullAddress property.

   The GEO parameter converts to the coordinates property.

   The TZ parameter converts to the timeZone property.

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

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

   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 fullAddress property.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 22]
Internet-Draft               jscontact-vcard               November 2022

    BEGIN:VCARD
    VERSION:4.0
    ...
    ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA
    ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA
    ...
    END:VCARD

    {
    "@type": "Card",
    "@version" : "rfc0000",
    ...
    "addresses": {
      "ADDR-1" : {
        "@type": "Address",
        "contexts": { "work": true },
        "fullAddress": "54321 Oak St\nReston\nVA\n20190\nUSA",
        "street": [
           { "@type": "StreetComponent", "type": "name", "value": "Oak St" },
           { "@type": "StreetComponent", "type": "number", "value": "54321" }
        ],
        "locality": "Reston",
        "region": "VA",
        "country": "USA",
        "postcode": "20190",
        "countryCode": "US"
      },
      "ADDR-2": {
        "@type": "Address",
        "contexts": { "private": true },
        "fullAddress":  "12345 Elm St\nReston\nVA\n20190\nUSA",
        "street": [
           { "@type": "StreetComponent", "type": "name", "value": "Elm St" },
           { "@type": "StreetComponent", "type": "number", "value": "12345" }
        ],
        "locality": "Reston",
        "region": "VA",
        "country": "USA",
        "postcode": "20190",
        "countryCode": "US"
      }
    },
    ...
    }

                  Figure 12: ADR conversion example

Loffredo & Stepanek        Expires 29 May 2023                 [Page 23]
Internet-Draft               jscontact-vcard               November 2022

2.8.  Communications Properties

2.8.1.  CONTACT-CHANNEL-PREF

   A CONTACT-CHANNEL-PREF property converts to an entry in the
   preferredContactChannels property (Figure 13).  The entry key set is
   defined in Table 4, the related entry values are arrays of
   ContactChannelPreference objects.

      +============================+================================+
      | CONTACT-CHANNEL-PREF value | "preferredContactChannels" key |
      +============================+================================+
      | ADR                        | addresses                      |
      +----------------------------+--------------------------------+
      | EMAIL                      | emails                         |
      +----------------------------+--------------------------------+
      | IMPP                       | onlineServices                 |
      +----------------------------+--------------------------------+
      | TEL                        | phones                         |
      +----------------------------+--------------------------------+

              Table 4: CONTACT-CHANNEL-PREF values conversion

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

   If both PREF and TYPE parameters are missing, the array of
   ContactChannelPreference objects MUST be empty.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 24]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       CONTACT-CHANNEL-PREF;PREF=1:EMAIL
       CONTACT-CHANNEL-PREF;PREF=2:TEL
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "preferredContactChannels": {
         "emails":[
           {
             "@type": "ContactChannelPreference",
             "pref": 1
           }
         ],
         "phones":[
           {
             "@type": "ContactChannelPreference",
             "pref": 2
           }
         ]
       },
       ...
       }

                     Figure 13: LANG conversion example

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

2.8.2.  EMAIL

   An EMAIL property converts to an entry in the emails property
   (Figure 14).  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.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 25]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       EMAIL;TYPE=work:jqpublic@xyz.example.com
       EMAIL;PREF=1:jane_doe@example.com
       ...
       END:VCARD

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

                    Figure 14: EMAIL conversion example

2.8.3.  IMPP

   An IMPP property converts to an entry in the onlineServices property
   (Figure 15).  The type of the OnlineService is set to impp.  The
   entry value is a OnlineService object and the user property is set to
   the IMPP value.

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

Loffredo & Stepanek        Expires 29 May 2023                 [Page 26]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       IMPP;PREF=1:xmpp:alice@example.com
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "onlineServices": {
         ...
         "OS-1": {
           "@type": "OnlineService",
           "user": "xmpp:alice@example.com",
           "type": "impp",
           "pref": 1
         },
         ...
       },
       ...
       }

                     Figure 15: IMPP conversion example

2.8.4.  LANG

   A LANG property converts to an entry in the preferredContactLanguages
   property (Figure 16).  The entry keys correspond to the language
   tags, the related entry values are arrays of ContactLanguage objects.

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

   If both PREF and TYPE parameters are missing, the array of
   ContactLanguage objects MUST be empty.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 27]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       LANG;TYPE=work;PREF=1:en
       LANG;TYPE=work;PREF=2:fr
       LANG;TYPE=home:fr
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "preferredLanguages": {
         "en":[
           {
             "@type": "LanguagePreference",
             "contexts": { "work": true },
             "pref": 1
           }
         ],
         "fr":[
           {
             "@type": "LanguagePreference",
             "contexts": { "work": true },
             "pref": 2
           },
           {
             "@type": "ContactLanguage",
             "contexts": { "private": true }
           }
         ]
       },
       ...
       }

                     Figure 16: LANG conversion example

2.8.5.  LOCALE

   The LOCALE property converts to the locale property (Figure 17).

Loffredo & Stepanek        Expires 29 May 2023                 [Page 28]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       LOCALE:de-AT
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "locale": "de-AT",
       ...
       }

                    Figure 17: LOCALE conversion example

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

2.8.6.  SOCIALPROFILE

   A SOCIALPROFILE property converts to an entry in the onlineServices
   property (Figure 18).  If the value type of the SOCIALPROFILE is
   TEXT, then the type of the OnlineService is set to username.
   Otherwise, the type is set to uri.  The entry value is a
   OnlineService object and the user property is set to the property
   value.

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

Loffredo & Stepanek        Expires 29 May 2023                 [Page 29]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       SOCIALPROFILE;SERVICE-TYPE=Twitter:https://twitter.com/ietf
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "onlineServices": {
         ...
         "OS-1": {
           "@type": "OnlineService",
           "service": "Twitter",
           "user": "https://twitter.com/ietf",
           "type": "uri"
         },
         ...
       },
       ...
       }

                     Figure 18: IMPP conversion example

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

2.8.7.  TEL

   A TEL property converts to an entry in the phones property
   (Figure 19).  The entry value is a Phone object.  The TEL-specific
   values of the TYPE parameter convert to the features property keys.
   The number property is set to the TEL value.

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

Loffredo & Stepanek        Expires 29 May 2023                 [Page 30]
Internet-Draft               jscontact-vcard               November 2022

     BEGIN:VCARD
     VERSION:4.0
     ...
     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
     ...
     END:VCARD

     {
     "@type": "Card",
     "@version" : "rfc0000",
     ...
     "phones": {
       "PHONE-1": {
         "@type": "Phone",
         "contexts": { "private": true },
         "features": { "voice": true },
         "number": "tel:+1-555-555-5555;ext=5555",
         "pref": 1
       },
       "PHONE-2": {
         "@type": "Phone",
         "contexts": { "private": true },
         "number": "tel:+33-01-23-45-67"
       }
     ],
     ...
     }

                   Figure 19: TEL conversion example

2.9.  Geographical Properties

2.9.1.  GEO

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

2.9.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:

Loffredo & Stepanek        Expires 29 May 2023                 [Page 31]
Internet-Draft               jscontact-vcard               November 2022

   *  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.9.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.16.1.

2.9.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 SHOULD convert the properties to the _same_ address
   for the following cases:

   *  The ALTID parameter values of the properties match.

   *  The ALTID parameters are not set, but are set on any other ADR,
      GEO and TZ properties.

2.10.  Organizational Properties

2.10.1.  CONTACT-URI

   A CONTACT-URI property as defined in [RFC8605] is represented as an
   entry of the links property (Figure 20).  The entry value is a
   LinkResource object whose type 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.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 32]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       CONTACT-URI;PREF=1:mailto:contact@example.com
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "links": {
         ...
         "CONTACT-1": {
           "@type": "LinkResource",
           "type": "contact",
           "uri": "mailto:contact@example.com",
           "pref": 1
         },
         ...
       },
       ...
       }

                 Figure 20: CONTACT-URI conversion example

2.10.2.  LOGO

   A LOGO property converts to an entry in the media property
   (Figure 21).  The entry value is a MediaResource object whose type
   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.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 33]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       LOGO:http://www.example.com/pub/logos/abccorp.jpg
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "media": {
         ...
         "LOGO-1": {
           "@type": "MediaResource",
           "type": "logo",
           "uri": "http://www.example.com/pub/logos/abccorp.jpg"
         },
         ...
       },
       ...
       }

                     Figure 21: LOGO conversion example

2.10.3.  MEMBER

   The uids of the contact cards composing the group are included in the
   members property (Figure 22).

   In this case, the PREF parameter has not a JSContact counterpart;
   however, the implementers MAY insert the map entries by order of
   preference.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 34]
Internet-Draft               jscontact-vcard               November 2022

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

         {
           "@type": "Card",
           "@version" : "rfc0000",
           "kind": "group",
           "fullName": "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
           }
         }

                          Figure 22: Group example

2.10.4.  ORG

   An ORG property converts to an entry in the organizations property
   (Figure 23).  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 to represent organizational untits 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

Loffredo & Stepanek        Expires 29 May 2023                 [Page 35]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       ORG;SORT-AS="ABC":ABC\, Inc.;North American Division;Marketing
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "organizations": {
         "ORG-1": {
           "@type": "Organization",
           "name": "ABC, Inc.",
           "units":[
             {"@type": "OrgUnit", "name": "North American Division"},
             {"@type": "OrgUnit", "name": "Marketing"}
           ],
           "sortAs": "ABC"
         }
       },
       ...
       }

                     Figure 23: ORG conversion example

2.10.5.  RELATED

   All the RELATED instances convert to the relatedTo property
   (Figure 24): an entry for each entity the entity described by the
   Card is associated with.  The map keys are the uid values of the
   associated cards.

   Each map value is a Relation object including only the relation
   property represented as a set of the RELATED-specific values of the
   TYPE parameter as defined in Section 6.6.6 of [RFC6350].

   If the relation type is unspecified, the relation property MUST be
   empty.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 36]
Internet-Draft               jscontact-vcard               November 2022

    BEGIN:VCARD
    VERSION:4.0
    ...
    RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
    RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf
    RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries.
    ...
    END:VCARD

    {
      "@type" : "Card",
      "@version" : "rfc0000",
      ...
      "relatedTo" : {
        "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6" : {
          "@type" : "Relation",
          "relation" : {
            "friend" : true
          }
        },
        "http://example.com/directory/jdoe.vcf" : {
          "@type" : "Relation",
          "relation" : {
            "contact" : true
          }
        },
        "Please contact my assistant Jane Doe for any inquiries." : {
          "@type" : "Relation",
          "relation" : { }
        }
      },
      ...
    }

                Figure 24: RELATED conversion example

2.10.6.  TITLE and ROLE

   Both TITLE and ROLE properties are represented as entries of the
   titles property (Figure 25).  The entry value is a Title object whose
   type 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.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 37]
Internet-Draft               jscontact-vcard               November 2022

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

       BEGIN:VCARD
       VERSION:4.0
       ...
       TITLE:Research Scientist
       group1.ROLE:Project Leader
       group1.ORG:ABC, Inc.
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "titles": {
         "TITLE-1": {
           "@type": "Title",
           "type": "title",
           "name": "Project Leader"
         },
         "TITLE-2": {
           "@type": "Title",
           "type": "role",
           "name": "Research Scientist",
           "organization": "ORG-1"
         }
       },
       "organizations": {
         "ORG-1": {
           "@type": "Organization",
           "name": "ABC, Inc."
         }
       }
       ...
       }

                Figure 25: TITLE and ROLE conversion example

2.11.  Personal Information Properties

2.11.1.  EXPERTISE

   An EXPERTISE property as defined in [RFC6715] is represented as a
   PersonalInformation object in the personalInfo property (Figure 26).
   The type property is set to "expertise".

Loffredo & Stepanek        Expires 29 May 2023                 [Page 38]
Internet-Draft               jscontact-vcard               November 2022

   The INDEX parameter is represented as the index of the expertise
   among the declared expertises.

       BEGIN:VCARD
       VERSION:4.0
       ...
       EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature
       EXPERTISE;INDEX=1;LEVEL=expert:chemistry
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "personalInfo": {
         ...
         "PERSINFO-1" : {
           "@type": "PersonalInformation",
           "type": "expertise",
           "value": "chemistry",
           "level": "high"
         },
         "PERSINFO-2" : {
           "@type": "PersonalInformation",
           "type": "expertise",
           "value": "chinese literature",
            "level": "low"
         },
         ...
       },
       ...
       }

                  Figure 26: EXPERTISE conversion example

2.11.2.  HOBBY

   A HOBBY property as defined in [RFC6715] is represented as a
   PersonalInformation object in the personalInfo property (Figure 27).
   The type property is set to "hobby".

   The INDEX parameter is represented as the index of the hobby among
   the declared hobbies.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 39]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       HOBBY;INDEX=1;LEVEL=high:reading
       HOBBY;INDEX=2;LEVEL=high:sewing
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "personalInfo": {
         ...
         "PERSINFO-1" : {
           "@type": "PersonalInformation",
           "type": "hobby",
           "value": "reading",
           "level": "high"
         },
         "PERSINFO-2" : {
           "@type": "PersonalInformation",
           "type": "hobby",
           "value": "sewing",
           "level": "high"
         },
         ...
       },
       ...
       }

                    Figure 27: HOBBY conversion example

2.11.3.  INTEREST

   An INTEREST property as defined in [RFC6715] is represented as a
   PersonalInformation object in the personalInfo property (Figure 28).
   The type property is set to "interest".

   The INDEX parameter is represented as the index of the interest among
   the declared interests.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 40]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       INTEREST;INDEX=1;LEVEL=medium:r&b music
       INTEREST;INDEX=2;LEVEL=high:rock ’n’ roll music
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "personalInfo": {
         ...
         "PERSINFO-1" : {
           "@type": "PersonalInformation",
           "type": "interest",
           "value": "r&b music",
           "level": "medium"
         },
         "PERSINFO-2" : {
           "@type": "PersonalInformation",
           "type": "interest",
           "value": "rock ’n’ roll music",
           "level": "high"
         },
         ...
       },
       ...
       }

                   Figure 28: INTEREST conversion example

2.11.4.  ORG-DIRECTORY

   An ORG-DIRECTORY property as defined in [RFC6715] is represented as
   an entry of the directories property (Figure 29).  The entry value is
   a DirectoryResource object whose type property is set to directory
   and uri property is set to the ORG-DIRECTORY value.

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

   The INDEX parameter is represented as the index of the directory
   among the online resources with the directory type.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 41]
Internet-Draft               jscontact-vcard               November 2022

    BEGIN:VCARD
    VERSION:4.0
    ...
    ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com
    ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering
    ...
    END:VCARD

    {
    "@type": "Card",
    "@version" : "rfc0000",
    ...
    "directories": {
      ...
      "DIRECTORY-1": {
        "@type": "DirectoryResource",
        "type": "directory",
        "uri": "http://directory.mycompany.example.com"
      },
      "DIRECTORY-2": {
        "@type": "DirectoryResource",
        "type": "directory",
        "uri": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering",
        "pref": 1
      },
      ...
    },
    ...
    }

             Figure 29: ORG-DIRECTORY conversion example

2.12.  Explanatory Properties

2.12.1.  CATEGORIES

   A CATEGORIES property converts to a set of entries of the keywords
   property (Figure 30).  The keys are the comma-separated text values
   of the CATEGORIES property.

   In this case, the PREF parameter has not a JSContact counterpart;
   however, the implementers MAY insert the map entries by order of
   preference.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 42]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "keywords": {
         "INTERNET": true,
         "IETF": true,
         "INDUSTRY": true,
         "INFORMATION TECHNOLOGY": true
       },
       ...
       }

                  Figure 30: CATEGORIES conversion example

2.12.2.  CLIENTPIDMAP and PID Parameter

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

2.12.3.  CREATED

   The CREATED property converts to the created property (Figure 31).

       BEGIN:VCARD
       VERSION:4.0
       ...
       CREATED:19940930T143510Z
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "created": "1994-09-30T14:35:10Z",
       ...
       }

                   Figure 31: CREATED conversion example

Loffredo & Stepanek        Expires 29 May 2023                 [Page 43]
Internet-Draft               jscontact-vcard               November 2022

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

2.12.4.  NOTE

   A NOTE property converts to a Note object in the notes map
   (Figure 32)

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

    BEGIN:VCARD
    VERSION:4.0
    ...
    NOTE;CREATED=20221123T150132Z;AUTHOR-NAME="John":
      This fax number is operational 0800 to 1715 EST\, Mon-Fri.
    ...
    END:VCARD

    {
    "@type": "Card",
    "@version" : "rfc0000",
    ...
    "notes": {
        "NOTE-1" : {
           "note": "This fax number is operational 0800 to 1715 EST, Mon-Fri.",
           "created": "2022-11-23T15:01:32Z",
           "author": {
             "@type": "Author",
             "name": "John"
           }
        }
    },
    ...
    }

                  Figure 32: NOTE conversion example

2.12.5.  PRODID

   The PRODID property converts to the prodId property (Figure 33).

Loffredo & Stepanek        Expires 29 May 2023                 [Page 44]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN",
       ...
       }

                    Figure 33: PRODID conversion example

2.12.6.  REV

   The REV property converts to the updated property (Figure 34).

       BEGIN:VCARD
       VERSION:4.0
       ...
       REV:19951031T222710Z
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "updated": "1995-10-31T22:27:10Z",
       ...
       }

                     Figure 34: REV conversion example

2.12.7.  SOUND

   A SOUND property converts to an entry in the media property
   (Figure 35).  The entry value is a MediaResource object whose type
   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.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 45]
Internet-Draft               jscontact-vcard               November 2022

    BEGIN:VCARD
    VERSION:4.0
    ...
    SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com
    ...
    END:VCARD

    {
    "@type": "Card",
    "@version" : "rfc0000",
    ...
    "media": {
      ...
      "SOUND-1": {
        "@type": "MediaResource",
        "type": "sound",
        "uri": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com"
      },
      ...
    },
    ...
    }

                 Figure 35: SOUND conversion example

2.12.8.  UID

   The UID property corresponds to the uid property (Figure 36).

       BEGIN:VCARD
       VERSION:4.0
       ...
       UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
       ...
       }

                     Figure 36: UID conversion example

Loffredo & Stepanek        Expires 29 May 2023                 [Page 46]
Internet-Draft               jscontact-vcard               November 2022

2.12.9.  URL

   An URL property converts to an entry in the links property
   (Figure 37).  The entry value is a LinkResource 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.

       BEGIN:VCARD
       VERSION:4.0
       ...
       URL:http://example.org/restaurant.french/~chezchic.html
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "links": {
         ...
         "LINK-1": {
           "@type": "LinkResource",
           "uri": "http://example.org/restaurant.french/~chezchic.html"
         },
         ...
       },
       ...
       }

                     Figure 37: URL conversion example

2.12.10.  VERSION

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

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

Loffredo & Stepanek        Expires 29 May 2023                 [Page 47]
Internet-Draft               jscontact-vcard               November 2022

   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.

       BEGIN:VCARD
       VERSION:4.0
       ...
       item1.TEL;VALUE=uri:tel:+1-555-555-5555
       item1.X-ABLabel:foo
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "phones": {
         "p1": {
           "@type": "Phone",
           "number": "tel:+1-555-555-5555",
           "label": "foo"
         }
       }
       ...
       }

                  Figure 38: X-ABLabel conversion example

2.13.  Security Properties

2.13.1.  KEY

   A KEY property converts to an entry in the cryptoKeys property
   (Figure 39).  The entry value is a CryptoResource 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.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 48]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       KEY:http://www.example.com/keys/jdoe.cer
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "cryptoKeys": {
         ...
         "KEY-1": {
           "@type": "CryptoResource",
           "uri": "http://www.example.com/keys/jdoe.cer"
         },
         ...
       },
       ...
       }

                     Figure 39: KEY conversion example

2.14.  Calendar Properties

2.14.1.  CALADRURI

   A CALADRURI property converts to an entry in the schedulingAddresses
   property (Figure 40).  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.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 49]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       CALADRURI;PREF=1:mailto:janedoe@example.com
       CALADRURI:http://example.com/calendar/jdoe
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "schedulingAddresses": {
         ...
         "SCHEDULING-1": {
           "@type": "SchedulingAddress",
           "uri": "mailto:janedoe@example.com",
           "pref": 1
         },
         "SCHEDULING-2": {
           "@type": "SchedulingAddress",
           "uri": "http://example.com/calendar/jdoe"
         },
         ...
       },
       ...
       }

                  Figure 40: CALADRURI conversion example

2.14.2.  CALURI

   A CALURI property converts to an entry in the calendars property
   (Figure 41).  The entry value is a CalendarResource object whose type
   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.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 50]
Internet-Draft               jscontact-vcard               November 2022

       BEGIN:VCARD
       VERSION:4.0
       ...
       CALURI;PREF=1:http://cal.example.com/calA
       CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics
       ...
       END:VCARD

       {
       "@type": "Card",
       "@version" : "rfc0000",
       ...
       "calendars": {
         ...
         "CAL-1": {
           "@type": "CalendarResource",
           "type": "calendar",
           "uri": "http://cal.example.com/calA",
           "pref": 1
         },
         "CAL-2": {
           "@type": "CalendarResource",
           "type": "calendar",
           "uri": "ftp://ftp.example.com/calA.ics",
           "mediaType": "text/calendar"
         },
         ...
       },
       ...
       }

                    Figure 41: CALURI conversion example

2.14.3.  FBURL

   An FBURL property converts to an entry in the calendars property
   (Figure 42).  The entry value is a CalendarResource object whose type
   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.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 51]
Internet-Draft               jscontact-vcard               November 2022

      BEGIN:VCARD
      VERSION:4.0
      ...
      FBURL;PREF=1:http://www.example.com/busy/janedoe
      FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb
      ...
      END:VCARD

      {
      "@type": "Card",
      "@version" : "rfc0000",
      ...
      "calendars": {
        ...
        "FBURL-1": {
          "@type": "CalendarResource",
          "type": "freeBusy",
          "uri": "http://www.example.com/busy/janedoe",
          "pref": 1
        },
        "FBURL-2": {
          "@type": "CalendarResource",
          "type": "freeBusy",
          "uri": "ftp://example.com/busy/project-a.ifb",
          "mediaType": "text/calendar"
        },
        ...
      },
      ...
      }

                   Figure 42: FBURL conversion example

2.15.  Extended Properties and Parameters

   These convert as specified in Section 2.16.

2.16.  New JSContact properties

   vCards may contain properties or parameters for which no IANA-
   registered JSContact property is defined.  For example, a vCard may
   contain extended properties and parameters of which the semantics or
   purposes are unknown Section 6.10 of [RFC6350].

   This section defines JSContact extension properties by which such
   vCard properties and parameters MAY be represented in JSContact.
   Implementations MAY choose to convert differently if they deem that
   more appropriate.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 52]
Internet-Draft               jscontact-vcard               November 2022

2.16.1.  Property vCardProps

   Name:  vCardProps

   Type:  JCardProp[], where JCardProp denotes a jCard-encoded vCard
      property as defined in Section 3.3 of [RFC7095].

   Definition:  This property is set on a JSContact object that
      represents a vCard.  It contains properties that are set in the
      vCard represented by this JSContact object.  Each entry in this
      list typically represents a vCard property for which no conversion
      to a IANA-registered JSContact property is defined.  It MAY
      contain vCard IANA-registered properties which also got converted
      to an IANA-registered property in the same JSContact object.  In
      case of conflict, the values of the JSContact property MUST be
      used.

   Example:  This illustrates how to convert a vCard extension property:

          BEGIN:VCARD
          VERSION:4.0
          ...
          item1.X-FOO;X-BAR=Hello:World!
          ...
          END:VCARD

          {
          "@type": "Card",
          "@version" : "rfc0000",
          ...
          "vCardProps": [
            ["x-foo", {
              "x-bar": "Hello",
              "group": "item1"
            }, "unknown", "World!"]
          ]
          ...
          }

                      Figure 43: JSContact props example

2.16.2.  Property vCardParams

   Name:  vCardParams

   Type:  String[String|String[]]

   Definition:  This property is set on a JSContact object that

Loffredo & Stepanek        Expires 29 May 2023                 [Page 53]
Internet-Draft               jscontact-vcard               November 2022

      represents a vCard property.  Its value MUST be a JSON object
      containing vCard property parameters, defined as array element 2
      in Section 3.3 of [RFC7095].  Each entry represents a parameter of
      the vCard property that converts to the JSContact object.
      Typically, these are parameters for which no IANA-registered
      property is defined in the JSContact object.  It MAY contain vCard
      IANA-registered parameters which also got converted to an IANA-
      registered property in the same JSContact object.  In case of
      conflict, the values of the JSContact property MUST be used.

   Example:
      EMAIL;X-FOO=Bar:jane_doe@example.com

      converts to

      "emails": {
        "email1": {
          "@type": "EmailAddress",
          "address": "jane_doe@example.com",
          "vCardParams": {
            "x-foo": "Bar"
          }
        }
      }

3.  Converting JSContact to vCard

3.1.  Conversion Rules

   A Card converts to vCard by applying the reserve rules of converting
   vCard to JSContact.  Table 5 lists the relevant document sections for
   each JSContact object type and property.  The following additional
   rules apply:

   *  Multi-valued JSContact properties convert to separate instances of
      their equivalent vCard property, and for each the PROP-ID
      parameter MUST be set to the Id of the converted value (see
      Section 2.3.14).

   *  The fullName property in JSContact is optional, but it is
      mandatory in vCard.  If the fullName is not set but the name
      property is, then implementations MAY derive the value of the FN
      property from it.  In this case, they MUST the DERIVED parameter
      on the FN property.  Otherwise, they MUST set the FN property with
      an empty value.

   *  Vendor-extension and unknown properties convert to vCard as
      outlined in section Section 3.2.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 54]
Internet-Draft               jscontact-vcard               November 2022

   +==========================+==========================+============+
   | JSContact Type           | Property Name            | Relevant   |
   |                          |                          | Section(s) |
   +==========================+==========================+============+
   | Address                  | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | Address                  | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | Address                  | coordinates              | Section    |
   |                          |                          | 2.3.7,     |
   |                          |                          | Section    |
   |                          |                          | 2.9.1      |
   +--------------------------+--------------------------+------------+
   | Address                  | country                  | Section    |
   |                          |                          | 2.7.1      |
   +--------------------------+--------------------------+------------+
   | Address                  | countryCode              | Section    |
   |                          |                          | 2.7.1      |
   +--------------------------+--------------------------+------------+
   | Address                  | fullAddress              | Section    |
   |                          |                          | 2.7.1      |
   +--------------------------+--------------------------+------------+
   | Address                  | locality                 | Section    |
   |                          |                          | 2.7.1      |
   +--------------------------+--------------------------+------------+
   | Address                  | postcode                 | Section    |
   |                          |                          | 2.7.1      |
   +--------------------------+--------------------------+------------+
   | Address                  | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | Address                  | region                   | Section    |
   |                          |                          | 2.7.1      |
   +--------------------------+--------------------------+------------+
   | Address                  | street                   | Section    |
   |                          |                          | 2.7.1      |
   +--------------------------+--------------------------+------------+
   | Address                  | timeZone                 | Section    |
   |                          |                          | 2.3.19,    |
   |                          |                          | Section    |
   |                          |                          | 2.9.2      |
   +--------------------------+--------------------------+------------+
   | Anniversary              | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | Anniversary              | date                     | Section    |

Loffredo & Stepanek        Expires 29 May 2023                 [Page 55]
Internet-Draft               jscontact-vcard               November 2022

   |                          |                          | 2.6.1      |
   +--------------------------+--------------------------+------------+
   | Anniversary              | place                    | Section    |
   |                          |                          | 2.6.1      |
   +--------------------------+--------------------------+------------+
   | Anniversary              | type                     | Section    |
   |                          |                          | 2.6.1      |
   +--------------------------+--------------------------+------------+
   | Author                   | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | Author                   | name                     | Section    |
   |                          |                          | 2.3.3      |
   +--------------------------+--------------------------+------------+
   | Author                   | uri                      | Section    |
   |                          |                          | 2.3.2      |
   +--------------------------+--------------------------+------------+
   | CalendarResource         | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | CalendarResource         | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | CalendarResource         | label                    | Section    |
   |                          |                          | 2.12.11    |
   +--------------------------+--------------------------+------------+
   | CalendarResource         | mediaType                | Section    |
   |                          |                          | 2.3.11     |
   +--------------------------+--------------------------+------------+
   | CalendarResource         | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | CalendarResource         | type                     | Section    |
   |                          |                          | 2.14.1,    |
   |                          |                          | Section    |
   |                          |                          | 2.14.3     |
   +--------------------------+--------------------------+------------+
   | CalendarResource         | uri                      | Section    |
   |                          |                          | 2.14.1,    |
   |                          |                          | Section    |
   |                          |                          | 2.14.3     |
   +--------------------------+--------------------------+------------+
   | Card                     | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | Card                     | @version                 | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+

Loffredo & Stepanek        Expires 29 May 2023                 [Page 56]
Internet-Draft               jscontact-vcard               November 2022

   | Card                     | addresses                | Section    |
   |                          |                          | 2.7.1      |
   +--------------------------+--------------------------+------------+
   | Card                     | anniversaries            | Section    |
   |                          |                          | 2.6.1      |
   +--------------------------+--------------------------+------------+
   | Card                     | calendars                | Section    |
   |                          |                          | 2.14.1,    |
   |                          |                          | Section    |
   |                          |                          | 2.14.3     |
   +--------------------------+--------------------------+------------+
   | Card                     | created                  | Section    |
   |                          |                          | 2.12.3     |
   +--------------------------+--------------------------+------------+
   | Card                     | directories              | Section    |
   |                          |                          | 2.5.3,     |
   |                          |                          | Section    |
   |                          |                          | 2.11.4     |
   +--------------------------+--------------------------+------------+
   | Card                     | emails                   | Section    |
   |                          |                          | 2.8.2      |
   +--------------------------+--------------------------+------------+
   | Card                     | fullName                 | Section    |
   |                          |                          | 2.6.4      |
   +--------------------------+--------------------------+------------+
   | Card                     | keywords                 | Section    |
   |                          |                          | 2.12.1     |
   +--------------------------+--------------------------+------------+
   | Card                     | kind                     | Section    |
   |                          |                          | 2.5.2      |
   +--------------------------+--------------------------+------------+
   | Card                     | links                    | Section    |
   |                          |                          | 2.10.1,    |
   |                          |                          | Section    |
   |                          |                          | 2.12.9     |
   +--------------------------+--------------------------+------------+
   | Card                     | locale                   | Section    |
   |                          |                          | 2.8.5      |
   +--------------------------+--------------------------+------------+
   | Card                     | localizations            | Section    |
   |                          |                          | 2.3.9      |
   +--------------------------+--------------------------+------------+
   | Card                     | media                    | Section    |
   |                          |                          | 2.6.6,     |
   |                          |                          | Section    |
   |                          |                          | 2.10.2,    |
   |                          |                          | Section    |
   |                          |                          | 2.12.7     |

Loffredo & Stepanek        Expires 29 May 2023                 [Page 57]
Internet-Draft               jscontact-vcard               November 2022

   +--------------------------+--------------------------+------------+
   | Card                     | members                  | Section    |
   |                          |                          | 2.10.3     |
   +--------------------------+--------------------------+------------+
   | Card                     | name                     | Section    |
   |                          |                          | 2.6.5      |
   +--------------------------+--------------------------+------------+
   | Card                     | nickNames                | Section    |
   |                          |                          | 2.6.5      |
   +--------------------------+--------------------------+------------+
   | Card                     | notes                    | Section    |
   |                          |                          | 2.12.4     |
   +--------------------------+--------------------------+------------+
   | Card                     | onlineServices           | Section    |
   |                          |                          | 2.8.3      |
   +--------------------------+--------------------------+------------+
   | Card                     | organizations            | Section    |
   |                          |                          | 2.10.4     |
   +--------------------------+--------------------------+------------+
   | Card                     | personalInfo             | Section    |
   |                          |                          | 2.11.1,    |
   |                          |                          | Section    |
   |                          |                          | 2.11.2,    |
   |                          |                          | Section    |
   |                          |                          | 2.11.3     |
   +--------------------------+--------------------------+------------+
   | Card                     | phones                   | Section    |
   |                          |                          | 2.8.7      |
   +--------------------------+--------------------------+------------+
   | Card                     | preferredContactChannels | Section    |
   |                          |                          | 2.8.1      |
   +--------------------------+--------------------------+------------+
   | Card                     | preferredLanguages       | Section    |
   |                          |                          | 2.8.4      |
   +--------------------------+--------------------------+------------+
   | Card                     | prodId                   | Section    |
   |                          |                          | 2.12.5     |
   +--------------------------+--------------------------+------------+
   | Card                     | relatedTo                | Section    |
   |                          |                          | 2.10.5     |
   +--------------------------+--------------------------+------------+
   | Card                     | schedulingAddresses      | Section    |
   |                          |                          | 2.14.1     |
   +--------------------------+--------------------------+------------+
   | Card                     | speakToAs                | Section    |
   |                          |                          | 2.6.3      |
   +--------------------------+--------------------------+------------+
   | Card                     | titles                   | Section    |

Loffredo & Stepanek        Expires 29 May 2023                 [Page 58]
Internet-Draft               jscontact-vcard               November 2022

   |                          |                          | 2.10.6     |
   +--------------------------+--------------------------+------------+
   | Card                     | uid                      | Section    |
   |                          |                          | 2.12.8     |
   +--------------------------+--------------------------+------------+
   | Card                     | updated                  | Section    |
   |                          |                          | 2.12.6     |
   +--------------------------+--------------------------+------------+
   | ContactChannelPreference | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | ContactChannelPreference | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | ContactChannelPreference | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | CryptoResource           | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | CryptoResource           | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | CryptoResource           | label                    | Section    |
   |                          |                          | 2.12.11    |
   +--------------------------+--------------------------+------------+
   | CryptoResource           | mediaType                | Section    |
   |                          |                          | 2.3.11     |
   +--------------------------+--------------------------+------------+
   | CryptoResource           | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | CryptoResource           | type                     | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | CryptoResource           | uri                      | Section    |
   |                          |                          | 2.13.1     |
   +--------------------------+--------------------------+------------+
   | DirectoryResource        | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | DirectoryResource        | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | DirectoryResource        | label                    | Section    |
   |                          |                          | 2.12.11    |
   +--------------------------+--------------------------+------------+
   | DirectoryResource        | mediaType                | Section    |

Loffredo & Stepanek        Expires 29 May 2023                 [Page 59]
Internet-Draft               jscontact-vcard               November 2022

   |                          |                          | 2.3.11     |
   +--------------------------+--------------------------+------------+
   | DirectoryResource        | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | DirectoryResource        | type                     | Section    |
   |                          |                          | 2.5.3,     |
   |                          |                          | Section    |
   |                          |                          | 2.11.4     |
   +--------------------------+--------------------------+------------+
   | DirectoryResource        | uri                      | Section    |
   |                          |                          | 2.5.3,     |
   |                          |                          | Section    |
   |                          |                          | 2.11.4     |
   +--------------------------+--------------------------+------------+
   | EmailAddress             | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | EmailAddress             | address                  | Section    |
   |                          |                          | 2.8.2      |
   +--------------------------+--------------------------+------------+
   | EmailAddress             | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | EmailAddress             | label                    | Section    |
   |                          |                          | 2.12.11    |
   +--------------------------+--------------------------+------------+
   | EmailAddress             | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | LanguagePreference       | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | LanguagePreference       | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | LanguagePreference       | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | LinkResource             | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | LinkResource             | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | LinkResource             | label                    | Section    |
   |                          |                          | 2.12.11    |
   +--------------------------+--------------------------+------------+

Loffredo & Stepanek        Expires 29 May 2023                 [Page 60]
Internet-Draft               jscontact-vcard               November 2022

   | LinkResource             | mediaType                | Section    |
   |                          |                          | 2.3.11     |
   +--------------------------+--------------------------+------------+
   | LinkResource             | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | LinkResource             | type                     | Section    |
   |                          |                          | 2.10.1,    |
   |                          |                          | Section    |
   |                          |                          | 2.12.9     |
   +--------------------------+--------------------------+------------+
   | LinkResource             | uri                      | Section    |
   |                          |                          | 2.10.1,    |
   |                          |                          | Section    |
   |                          |                          | 2.12.9>    |
   +--------------------------+--------------------------+------------+
   | MediaResource            | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | MediaResource            | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | MediaResource            | label                    | Section    |
   |                          |                          | 2.12.11    |
   +--------------------------+--------------------------+------------+
   | MediaResource            | mediaType                | Section    |
   |                          |                          | 2.3.11     |
   +--------------------------+--------------------------+------------+
   | MediaResource            | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | MediaResource            | type                     | Section    |
   |                          |                          | 2.6.6,     |
   |                          |                          | Section    |
   |                          |                          | 2.10.2,    |
   |                          |                          | Section    |
   |                          |                          | 2.12.7     |
   +--------------------------+--------------------------+------------+
   | MediaResource            | uri                      | Section    |
   |                          |                          | 2.6.6,     |
   |                          |                          | Section    |
   |                          |                          | 2.10.2,    |
   |                          |                          | Section    |
   |                          |                          | 2.12.7     |
   +--------------------------+--------------------------+------------+
   | Name                     | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+

Loffredo & Stepanek        Expires 29 May 2023                 [Page 61]
Internet-Draft               jscontact-vcard               November 2022

   | Name                     | components               | Section    |
   |                          |                          | 2.6.5      |
   +--------------------------+--------------------------+------------+
   | Name                     | locale                   | Section    |
   |                          |                          | 2.8.5      |
   +--------------------------+--------------------------+------------+
   | Name                     | sortAs                   | Section    |
   |                          |                          | 2.3.17     |
   +--------------------------+--------------------------+------------+
   | NameComponent            | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | NameComponent            | rank                     | Section    |
   |                          |                          | 2.3.15     |
   +--------------------------+--------------------------+------------+
   | NameComponent            | type                     | Section    |
   |                          |                          | 2.6.5      |
   +--------------------------+--------------------------+------------+
   | NameComponent            | value                    | Section    |
   |                          |                          | 2.6.5      |
   +--------------------------+--------------------------+------------+
   | NickName                 | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | NickName                 | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | NickName                 | name                     | Section    |
   |                          |                          | 2.6.5      |
   +--------------------------+--------------------------+------------+
   | NickName                 | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | Note                     | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | Note                     | author                   | Section    |
   |                          |                          | 2.3.2,     |
   |                          |                          | Section    |
   |                          |                          | 2.3.3      |
   +--------------------------+--------------------------+------------+
   | Note                     | created                  | Section    |
   |                          |                          | 2.3.5      |
   +--------------------------+--------------------------+------------+
   | Note                     | note                     | Section    |
   |                          |                          | 2.12.4     |
   +--------------------------+--------------------------+------------+
   | OnlineService            | @type                    | not        |

Loffredo & Stepanek        Expires 29 May 2023                 [Page 62]
Internet-Draft               jscontact-vcard               November 2022

   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | OnlineService            | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | OnlineService            | label                    | Section    |
   |                          |                          | 2.12.11    |
   +--------------------------+--------------------------+------------+
   | OnlineService            | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | OnlineService            | service                  | Section    |
   |                          |                          | 2.3.16     |
   +--------------------------+--------------------------+------------+
   | OnlineService            | type                     | Section    |
   |                          |                          | 2.8.3,     |
   |                          |                          | Section    |
   |                          |                          | 2.8.6      |
   +--------------------------+--------------------------+------------+
   | OnlineService            | user                     | Section    |
   |                          |                          | 2.8.3,     |
   |                          |                          | Section    |
   |                          |                          | 2.8.6      |
   +--------------------------+--------------------------+------------+
   | OrgUnit                  | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | OrgUnit                  | name                     | Section    |
   |                          |                          | 2.10.4     |
   +--------------------------+--------------------------+------------+
   | OrgUnit                  | sortAs                   | Section    |
   |                          |                          | 2.3.17     |
   +--------------------------+--------------------------+------------+
   | Organization             | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | Organization             | name                     | Section    |
   |                          |                          | 2.10.4     |
   +--------------------------+--------------------------+------------+
   | Organization             | sortAs                   | Section    |
   |                          |                          | 2.3.17     |
   +--------------------------+--------------------------+------------+
   | Organization             | units                    | Section    |
   |                          |                          | 2.10.4     |
   +--------------------------+--------------------------+------------+
   | PartialDate              | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+

Loffredo & Stepanek        Expires 29 May 2023                 [Page 63]
Internet-Draft               jscontact-vcard               November 2022

   | PartialDate              | calendarScale            | Section    |
   |                          |                          | 2.3.4      |
   +--------------------------+--------------------------+------------+
   | PartialDate              | day                      | Section    |
   |                          |                          | 2.2.2      |
   +--------------------------+--------------------------+------------+
   | PartialDate              | month                    | Section    |
   |                          |                          | 2.2.2      |
   +--------------------------+--------------------------+------------+
   | PartialDate              | year                     | Section    |
   |                          |                          | 2.2.2      |
   +--------------------------+--------------------------+------------+
   | PatchObject              | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | PersonalInformation      | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | PersonalInformation      | level                    | Section    |
   |                          |                          | 2.3.10     |
   +--------------------------+--------------------------+------------+
   | PersonalInformation      | type                     | Section    |
   |                          |                          | 2.11.1,    |
   |                          |                          | Section    |
   |                          |                          | 2.11.2,    |
   |                          |                          | Section    |
   |                          |                          | 2.11.3     |
   +--------------------------+--------------------------+------------+
   | PersonalInformation      | value                    | Section    |
   |                          |                          | 2.11.1,    |
   |                          |                          | Section    |
   |                          |                          | 2.11.2,    |
   |                          |                          | Section    |
   |                          |                          | 2.11.3     |
   +--------------------------+--------------------------+------------+
   | Phone                    | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | Phone                    | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | Phone                    | features                 | Section    |
   |                          |                          | 2.8.7      |
   +--------------------------+--------------------------+------------+
   | Phone                    | label                    | Section    |
   |                          |                          | 2.12.11    |
   +--------------------------+--------------------------+------------+
   | Phone                    | number                   | Section    |

Loffredo & Stepanek        Expires 29 May 2023                 [Page 64]
Internet-Draft               jscontact-vcard               November 2022

   |                          |                          | 2.8.7      |
   +--------------------------+--------------------------+------------+
   | Phone                    | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | Pronouns                 | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | Pronouns                 | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | Pronouns                 | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | Pronouns                 | pronouns                 | Section    |
   |                          |                          | 2.6.3      |
   +--------------------------+--------------------------+------------+
   | Relation                 | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | Relation                 | relation                 | Section    |
   |                          |                          | 2.10.5     |
   +--------------------------+--------------------------+------------+
   | Resource                 | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | SchedulingAddress        | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | SchedulingAddress        | contexts                 | Section    |
   |                          |                          | 2.3.18     |
   +--------------------------+--------------------------+------------+
   | SchedulingAddress        | label                    | Section    |
   |                          |                          | 2.12.11    |
   +--------------------------+--------------------------+------------+
   | SchedulingAddress        | pref                     | Section    |
   |                          |                          | 2.3.13     |
   +--------------------------+--------------------------+------------+
   | SchedulingAddress        | uri                      | Section    |
   |                          |                          | 2.14.1     |
   +--------------------------+--------------------------+------------+
   | SpeakToAs                | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | SpeakToAs                | grammaticalGender        | Section    |
   |                          |                          | 2.6.3      |
   +--------------------------+--------------------------+------------+
   | SpeakToAs                | pronouns                 | Section    |

Loffredo & Stepanek        Expires 29 May 2023                 [Page 65]
Internet-Draft               jscontact-vcard               November 2022

   |                          |                          | 2.6.3      |
   +--------------------------+--------------------------+------------+
   | StreetComponent          | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | StreetComponent          | type                     | Section    |
   |                          |                          | 2.7.1      |
   +--------------------------+--------------------------+------------+
   | StreetComponent          | value                    | Section    |
   |                          |                          | 2.7.1      |
   +--------------------------+--------------------------+------------+
   | Timestamp                | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | Timestamp                | utc                      | Section    |
   |                          |                          | 2.2.2      |
   +--------------------------+--------------------------+------------+
   | Title                    | @type                    | not        |
   |                          |                          | applicable |
   +--------------------------+--------------------------+------------+
   | Title                    | name                     | Section    |
   |                          |                          | 2.10.6     |
   +--------------------------+--------------------------+------------+
   | Title                    | organization             | Section    |
   |                          |                          | 2.10.6     |
   +--------------------------+--------------------------+------------+
   | Title                    | type                     | Section    |
   |                          |                          | 2.10.6     |
   +--------------------------+--------------------------+------------+

             Table 5: Conversion rules by JSContact property

3.2.  New vCard Properties and Parameters

   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 section defines new vCard properties and parameters by which
   such JSContact properties MAY be represented in JSContact.
   Implementations MAY choose to convert differently if they deem that
   more appropriate.

3.2.1.  Property JSCONTACT-PROP

Property name:  JSCONTACT-PROP

Loffredo & Stepanek        Expires 29 May 2023                 [Page 66]
Internet-Draft               jscontact-vcard               November 2022

Purpose:  This property represents a JSContact property in vCard.

Value type:  TEXT, also see Format Definition for value restrictions.

Conformance:  The property can be specified multiple times in a
   vCard.

Property parameters:  The JSPTR parameter MUST be set exactly once
   for this property.  The VALUE parameter MAY be set once, in which
   case its value MUST be URI.  Other IANA-registered and
   experimental property parameters can be specified on this
   property.

Description:  This property converts a JSContact property 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 SHOULD be compact, e.g.  without insignificant
   whitespace.

   The value of the JSPTR parameter defines the path to that
   JSContact value within the Card.  The last segment of the JSON
   pointer either defines the property name or array position of the
   JSContact value.  The root of the JSON pointer always is the Card
   object that this vCard converts to, irrespective if the JSON
   pointer starts with the SOLIDUS (U+002F) character.  If any but
   the last segment of the JSON pointer points to a non-existent
   JSContact property or array entry in the Card, then the JSCONTACT-
   PROP property MUST be ignored and SHOULD be discarded from the
   vCard.

Format definition:  This property is defined by the following
   notation:

     jscontact-prop = "JSCONTACT-PROP" jscontact-prop-param ":" TEXT CRLF

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

Loffredo & Stepanek        Expires 29 May 2023                 [Page 67]
Internet-Draft               jscontact-vcard               November 2022

Example(s):  This illustrates how to convert a property at the top-
level in a Card object that is unknown to the implementation.

  {
    "@type": "Card",
    "@version" : "rfc0000",
     ...
     "someUnknownProperty": true
  }

  BEGIN:VCARD
  VERSION:4.0
  ...
  JSCONTACT-PROP;VALUE=TEXT;JSPTR="someUnknownProperty":true
  ...
  END:VCARD

               Figure 44: Unknown property example

This illustrates how to convert a vendor-extension 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.

  {
    "@type": "Card",
    "@version" : "rfc0000",
     ...
     "example.com:foo": {
       "bar": 1234
     }
  }

  BEGIN:VCARD
  VERSION:4.0
  ...
  JSCONTACT-PROP;VALUE=TEXT;JSPTR="example.com:foo":{"bar":1234}
  ...
  END:VCARD

          Figure 45: Vendor-extension conversion example

This illustrates how to convert a vendor-extension 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.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 68]
Internet-Draft               jscontact-vcard               November 2022

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

  BEGIN:VCARD
  VERSION:4.0
  TEL:tel:+33-01-23-45-67
  JSCONTACT-PROP;VALUE=TEXT;JSPTR="phones/phone1/example.com:foo~1bar":"tux hux"
  ...
  END:VCARD

  Figure 46: Nested property example with path relative to Card

3.2.2.  Parameter JSPTR

   Parameter name:  JSPTR

   Purpose:  This parameter contains a JSON pointer [RFC6901] that
      relates its vCard property to some JSON data.  Its exact semantics
      depend on the definition of the property where this parameter is
      set on.

   Description:  This parameter has a single value that MUST be a valid
      JSON pointer as defined in [RFC6901].  Currently, its semantics
      only are defined for the JSCONTACT-PROP property (see
      Section 3.2.1), but it may also be used for other use cases in the
      future.

   Format definition:
      jspath-param  = "JSPTR" "=" DQUOTE *QSAFE-CHAR DQUOTE
                       ; 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.

        JSCONTACT-PROP;VALUE=TEXT;JSPTR="example.com:foo":"bar"

Loffredo & Stepanek        Expires 29 May 2023                 [Page 69]
Internet-Draft               jscontact-vcard               November 2022

4.  Security Considerations

   This specification defines how to convert between the JSContact and
   vCard formats.  The security considerations for parsing and
   formatting such data apply and are outlined in Section 5 of
   [I-D.ietf-calext-jscontact] and Section 9 of [RFC6350].

5.  IANA Considerations

5.1.  New vCard Properties

   IANA is requested to add the following entries to the "vCard
   Properties" registry, defined in Section 10.3.1.  of [RFC6350].

       +===========+================+==============================+
       | Namespace | Property       | Reference                    |
       +===========+================+==============================+
       |           | JSCONTACT-PROP | This document, Section 3.2.1 |
       +-----------+----------------+------------------------------+

                       Table 6: New VCARD Properties

5.2.  New vCard Parameters

   IANA is requested to add the following entries to the "vCard
   Parameters" registry, defined in Section 10.3.2.  of [RFC6350].

         +===========+===========+==============================+
         | Namespace | Parameter | Reference                    |
         +===========+===========+==============================+
         |           | JSPTR     | This document, Section 3.2.2 |
         +-----------+-----------+------------------------------+

                      Table 7: New VCARD Parameters

5.3.  New JSContact Properties

   IANA is requested to add the following entries to the "JSContact
   Properties" registry.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 70]
Internet-Draft               jscontact-vcard               November 2022

   +===========+==============+=========+===========+========+=======+==========+
   |Property   |Property Type |Property |Reference  |Intended|Version|Change    |
   |Name       |              |Context  |or         |Usage   |       |Controller|
   |           |              |         |Description|        |       |          |
   +===========+==============+=========+===========+========+=======+==========+
   |vCardParams|String[String]|Any      |Section    |common  |rfc0000|IETF      |
   |           |              |JSContact|2.16.2     |        |       |          |
   |           |              |object   |           |        |       |          |
   |           |              |type that|           |        |       |          |
   |           |              |contains |           |        |       |          |
   |           |              |the @type|           |        |       |          |
   |           |              |property.|           |        |       |          |
   +-----------+--------------+---------+-----------+--------+-------+----------+
   |vCardProps |JCardProp[]   |Card     |Section    |common  |rfc0000|IETF      |
   |           |              |         |2.16.1     |        |       |          |
   +-----------+--------------+---------+-----------+--------+-------+----------+

      Table 8: Initial Contents of the "JSContact Properties" Registry

5.4.  New JSContact Types

   IANA is requested to add the following entries to the "JSContact
   Types" registry.

   +===========+==============+==========+=========+============+
   | Type Name | Reference or | Intended | Version | Change     |
   |           | Description  | Usage    |         | Controller |
   +===========+==============+==========+=========+============+
   | JCardProp | Section      | common   | rfc0000 | IETF       |
   |           | 2.16.1       |          |         |            |
   +-----------+--------------+----------+---------+------------+

   Table 9: Additional Contents of the "JSContact Types" Registry

6.  Implementation Status

   NOTE: Please remove this section and the reference to RFC 7942 prior
   to publication as an RFC.

   This section records the status of known implementations of the
   protocol as defined in this specification at the time of posting of
   this Internet-Draft, and is based on a proposal described in
   [RFC7942].  The description of implementations in this section is
   intended to assist the IETF in its decision processes in progressing
   drafts to RFCs.  Please note that the listing of any individual
   implementation here does not imply endorsement by the IETF.
   Furthermore, no effort has been spent to verify the information
   presented here that was supplied by IETF contributors.  This is not

Loffredo & Stepanek        Expires 29 May 2023                 [Page 71]
Internet-Draft               jscontact-vcard               November 2022

   intended as, and must not be construed to be, a catalog of available
   implementations or their features.  Readers are advised to note that
   other implementations may exist.

   According to RFC 7942, "this will allow reviewers and working groups
   to assign due consideration to documents that have the benefit of
   running code, which may serve as evidence of valuable experimentation
   and feedback that have made the implemented protocols more mature.
   It is up to the individual working groups to use this information as
   they see fit".

6.1.  CNR

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

7.  References

7.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC6350]  Perreault, S., "vCard Format Specification", RFC 6350,
              DOI 10.17487/RFC6350, August 2011,
              <https://www.rfc-editor.org/info/rfc6350>.

   [RFC6473]  Saint-Andre, P., "vCard KIND:application", RFC 6473,
              DOI 10.17487/RFC6473, December 2011,
              <https://www.rfc-editor.org/info/rfc6473>.

   [RFC6474]  Li, K. and B. Leiba, "vCard Format Extensions: Place of
              Birth, Place and Date of Death", RFC 6474,
              DOI 10.17487/RFC6474, December 2011,
              <https://www.rfc-editor.org/info/rfc6474>.

Loffredo & Stepanek        Expires 29 May 2023                 [Page 72]
Internet-Draft               jscontact-vcard               November 2022

   [RFC6715]  Cauchie, D., Leiba, B., and K. Li, "vCard Format
              Extensions: Representing vCard Extensions Defined by the
              Open Mobile Alliance (OMA) Converged Address Book (CAB)
              Group", RFC 6715, DOI 10.17487/RFC6715, August 2012,
              <https://www.rfc-editor.org/info/rfc6715>.

   [RFC6869]  Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard
              KIND:device", RFC 6869, DOI 10.17487/RFC6869, February
              2013, <https://www.rfc-editor.org/info/rfc6869>.

   [RFC6901]  Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed.,
              "JavaScript Object Notation (JSON) Pointer", RFC 6901,
              DOI 10.17487/RFC6901, April 2013,
              <https://www.rfc-editor.org/info/rfc6901>.

   [RFC7095]  Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095,
              DOI 10.17487/RFC7095, January 2014,
              <https://www.rfc-editor.org/info/rfc7095>.

   [RFC7942]  Sheffer, Y. and A. Farrel, "Improving Awareness of Running
              Code: The Implementation Status Section", BCP 205,
              RFC 7942, DOI 10.17487/RFC7942, July 2016,
              <https://www.rfc-editor.org/info/rfc7942>.

7.2.  Informative References

   [I-D.ietf-calext-jscontact]
              Stepanek, R. and M. Loffredo, "JSContact: A JSON
              representation of contact data", Work in Progress,
              Internet-Draft, draft-ietf-calext-jscontact-04, 24 October
              2022, <https://datatracker.ietf.org/doc/html/draft-ietf-
              calext-jscontact-04>.

   [I-D.ietf-calext-vcard-jscontact-extensions]
              Stepanek, R. and M. Loffredo, "vCard Format Extension for
              JSContact", Work in Progress, Internet-Draft, draft-ietf-
              calext-vcard-jscontact-extensions-01, 24 October 2022,
              <https://datatracker.ietf.org/doc/html/draft-ietf-calext-
              vcard-jscontact-extensions-01>.

   [RFC8605]  Hollenbeck, S. and R. Carney, "vCard Format Extensions:
              ICANN Extensions for the Registration Data Access Protocol
              (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019,
              <https://www.rfc-editor.org/info/rfc8605>.

Authors' Addresses

Loffredo & Stepanek        Expires 29 May 2023                 [Page 73]
Internet-Draft               jscontact-vcard               November 2022

   Mario Loffredo
   IIT-CNR/Registro.it
   Via Moruzzi,1
   56124 Pisa
   Italy
   Email: mario.loffredo@iit.cnr.it
   URI:   http://www.iit.cnr.it

   Robert Stepanek
   Fastmail
   PO Box 234, Collins St West
   Melbourne  VIC 8007
   Australia
   Email: rsto@fastmailteam.com
   URI:   https://www.fastmail.com

Loffredo & Stepanek        Expires 29 May 2023                 [Page 74]