idnits 2.17.1 draft-ietf-jmap-jscontact-vcard-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 11 instances of too long lines in the document, the longest one being 18 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (16 January 2022) is 832 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC6474' is defined on line 1738, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 8605 Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 jmap M. Loffredo 3 Internet-Draft IIT-CNR/Registro.it 4 Intended status: Standards Track R. Stepanek 5 Expires: 20 July 2022 FastMail 6 16 January 2022 8 JSContact: Converting from and to vCard 9 draft-ietf-jmap-jscontact-vcard-09 11 Abstract 13 This document defines how to convert contact information as defined 14 in the JSContact [draft-ietf-jmap-jscontact] specification from and 15 to vCard. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on 20 July 2022. 34 Copyright Notice 36 Copyright (c) 2022 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 41 license-info) in effect on the date of publication of this document. 42 Please review these documents carefully, as they describe your rights 43 and restrictions with respect to this document. Code Components 44 extracted from this document must include Revised BSD License text as 45 described in Section 4.e of the Trust Legal Provisions and are 46 provided without warranty as described in the Revised BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.2. Scope and Caveats . . . . . . . . . . . . . . . . . . . . 4 53 1.3. Conventions Used in This Document . . . . . . . . . . . . 4 54 1.4. Extensions . . . . . . . . . . . . . . . . . . . . . . . 4 55 2. Translating vCard properties to JSContact . . . . . . . . . . 5 56 2.1. Common Parameters . . . . . . . . . . . . . . . . . . . . 5 57 2.2. Unmapped JSContact Information . . . . . . . . . . . . . 5 58 2.3. General Properties . . . . . . . . . . . . . . . . . . . 5 59 2.3.1. BEGIN and END . . . . . . . . . . . . . . . . . . . . 6 60 2.3.2. SOURCE . . . . . . . . . . . . . . . . . . . . . . . 6 61 2.3.3. KIND . . . . . . . . . . . . . . . . . . . . . . . . 6 62 2.3.4. XML . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 2.4. Identification Properties . . . . . . . . . . . . . . . . 7 64 2.4.1. FN . . . . . . . . . . . . . . . . . . . . . . . . . 7 65 2.4.2. N and NICKNAME . . . . . . . . . . . . . . . . . . . 7 66 2.4.3. PHOTO . . . . . . . . . . . . . . . . . . . . . . . . 9 67 2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, 68 ANNIVERSARY . . . . . . . . . . . . . . . . . . . . . 9 69 2.4.5. GENDER . . . . . . . . . . . . . . . . . . . . . . . 11 70 2.5. Delivery Addressing Properties . . . . . . . . . . . . . 12 71 2.5.1. ADR . . . . . . . . . . . . . . . . . . . . . . . . . 12 72 2.6. Communications Properties . . . . . . . . . . . . . . . . 15 73 2.6.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 15 74 2.6.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 15 75 2.6.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 16 76 2.6.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 17 77 2.7. Geographical Properties . . . . . . . . . . . . . . . . . 18 78 2.7.1. Time Zone Representation . . . . . . . . . . . . . . 18 79 2.8. Organizational Properties . . . . . . . . . . . . . . . . 19 80 2.8.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 19 81 2.8.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 20 82 2.8.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 20 83 2.8.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 21 84 2.8.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 23 85 2.8.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 24 86 2.9. Personal Information Properties . . . . . . . . . . . . . 24 87 2.9.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 25 88 2.9.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 25 89 2.9.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 26 90 2.9.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 27 91 2.10. Explanatory Properties . . . . . . . . . . . . . . . . . 28 92 2.10.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 28 93 2.10.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 29 94 2.10.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 30 95 2.10.4. REV . . . . . . . . . . . . . . . . . . . . . . . . 30 96 2.10.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . 30 97 2.10.6. UID . . . . . . . . . . . . . . . . . . . . . . . . 31 98 2.10.7. CLIENTPIDMAP and PID Parameter . . . . . . . . . . . 32 99 2.10.8. URL . . . . . . . . . . . . . . . . . . . . . . . . 32 100 2.10.9. VERSION . . . . . . . . . . . . . . . . . . . . . . 32 101 2.11. Security Properties . . . . . . . . . . . . . . . . . . . 32 102 2.11.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . 33 103 2.12. Calendar Properties . . . . . . . . . . . . . . . . . . . 33 104 2.12.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 33 105 2.12.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 34 106 2.12.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 35 107 2.13. vCard Unmatched Properties . . . . . . . . . . . . . . . 36 108 2.14. Card Required Properties . . . . . . . . . . . . . . . . 36 109 3. Translating JSContact properties to vCard . . . . . . . . . . 37 110 3.1. Id . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 111 3.2. Localizations . . . . . . . . . . . . . . . . . . . . . . 37 112 3.3. Date and Time Representations . . . . . . . . . . . . . . 37 113 3.4. Time Zone . . . . . . . . . . . . . . . . . . . . . . . . 37 114 3.5. JSContact Types Matching Multiple vCard Properties . . . 38 115 3.5.1. Title . . . . . . . . . . . . . . . . . . . . . . . . 38 116 3.5.2. Resource . . . . . . . . . . . . . . . . . . . . . . 38 117 3.6. CardGroup . . . . . . . . . . . . . . . . . . . . . . . . 38 118 3.7. Card Unmatched Properties . . . . . . . . . . . . . . . . 38 119 3.8. vCard Required Properties . . . . . . . . . . . . . . . . 38 120 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 121 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 39 122 5.1. CNR . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 123 6. Security Considerations . . . . . . . . . . . . . . . . . . . 39 124 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 125 7.1. Normative References . . . . . . . . . . . . . . . . . . 39 126 7.2. Informative References . . . . . . . . . . . . . . . . . 40 127 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 129 1. Introduction 131 1.1. Motivation 133 The JSContact specification [draft-ietf-jmap-jscontact] has been 134 defined to represent contact card information as a more efficient 135 alternative to vCard [RFC6350] and its JSON-based version named jCard 136 [RFC7095]. 138 While new applications might adopt JSContact as their main format to 139 exchange contact card data, they are likely to interoperate with 140 services and clients that just support vCard/jCard. Similarly, 141 existing contact data providers and consumers already using vCard/ 142 jCard might want to represent their data also according to the 143 JSContact specification. 145 To facilitate this, this document defines how to convert contact 146 information as defined in the JSContact [draft-ietf-jmap-jscontact] 147 specification from and to vCard. 149 1.2. Scope and Caveats 151 JSContact and vCard have a lot of semantics in common, however some 152 differences must be outlined: 154 * The JSContact data model defines some contact information that 155 doesn't have a direct mapping with vCard properties. In 156 particular, unlike vCard, JSContact distinguishes between a single 157 contact card, named Card, and a group of contact cards, named 158 CardGroup. 159 * The properties that can be present multiple times in a vCard are 160 represented through different collections in JSContact; mainly as 161 maps, sometimes as lists, in some cases condensed in a single 162 value. 164 1.3. Conventions Used in This Document 166 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 167 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 168 document are to be interpreted as described in [RFC2119]. 170 In the following of this document, the vCard features, namely 171 properties and parameters, are written in uppercase while the Card/ 172 CardGroup features are written in camel case wrapped in double 173 quotes. 175 1.4. Extensions 177 While translating vCard to JSContact, any vCard property that doesn't 178 have a direct counterpart in JSContact MUST be converted into a 179 property whose name is prefixed by "ietf.org::" (e.g. "ietf.org:rfc6350:"). 182 Any custom extension MAY be added and its name MUST be prefixed with 183 a specific domain name to avoid conflict, e.g. 184 "example.com:customprop". 186 Likewise, while translating JSContact to vCard, a JSContact property 187 that doesn't have a direct counterpart in vCard MUST be converted 188 into a property whose name is prefixed with "X-" as specified in 189 Section 6.10 of [RFC6350]. 191 2. Translating vCard properties to JSContact 193 This section contains the translation rules from vCard to Card/ 194 CardGroup. The vCard properties are grouped according to the 195 categories as defined in [RFC6350]. 197 If a vCard represents a group of contacts, those vCard properties 198 which don't have a counterpart in CardGroup are converted into 199 related properties of the "CardGroup.card" object. In this case, the 200 "uid" member of both the resulting CardGroup object and its "card" 201 member MUST have the same value. 203 2.1. Common Parameters 205 The following mapping rules apply to parameters that are common to 206 most of the vCard properties: 208 * The generic values of the TYPE parameter are mapped to the values 209 of the "Context" type as defined in Section 1.5.1 of 210 [draft-ietf-jmap-jscontact]. The "home" value corresponds to the 211 "private" key. The mapping of those specific TYPE values used in 212 the TEL and RELATED properties are defined in Section 2.6.1 and 213 Section 2.8.5. 214 * The PREF parameter is mapped to the "pref" property. 215 * The MEDIATYPE parameter is mapped to the "mediaType" property. As 216 described in Section 5.7 of [RFC6350], the media type of a 217 resource can be identified by its URI. For example, "image/gif" 218 can be derived from the ".gif" extension of a GIF image URI. 219 JSContact producers MAY provide the media type information even 220 when it is not specified in the vCard. 221 * The ALTID and LANGUAGE parameters are used in combination for 222 associating the language-dependent alternatives with a given 223 property. Such alternatives are represented by using the 224 "localizations" map: the "localizations" key is the LANGUAGE 225 value, the key of the related PatchObject map is the JSON pointer 226 of the JSContact member matching the vCard property while the 227 value is the JSContact member itself. 229 2.2. Unmapped JSContact Information 231 The rules to generate a map key of type Id as well as a value for 232 "created", "language" and "preferredContactMethod" properties are out 233 of the scope of this document. 235 2.3. General Properties 236 2.3.1. BEGIN and END 238 The BEGIN and END properties don't have a direct match with a 239 JSContact feature. 241 2.3.2. SOURCE 243 A SOURCE property is represented as an entry of the "online" map 244 (Figure 1). The entry value is a "Resource" object whose "type" 245 member is set to "uri", the "label" member is set to "source" and the 246 "resource" member is the SOURCE value. 248 The PREF and MEDIATYPE parameters are mapped according to the rules 249 as defined in Section 2.1. 251 BEGIN:VCARD 252 VERSION:4.0 253 ... 254 SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf 255 ... 256 END:VCARD 258 { 259 ... 260 "online":{ 261 ... 262 "a-source":{ 263 "type": "uri", 264 "label": "source", 265 "resource": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf" 266 }, 267 ... 268 }, 269 ... 270 } 272 Figure 1: SOURCE mapping example 274 2.3.3. KIND 276 The KIND property is mapped to the "kind" member (Figure 2). Allowed 277 values are those described in Section 6.1.4 of [RFC6350] and extended 278 with the values declared in [RFC6473] and [RFC6869]. The value 279 "group" is reserved for a CardGroup instance. 281 BEGIN:VCARD 282 VERSION:4.0 283 ... 284 KIND:individual 285 ... 286 END:VCARD 288 { 289 ... 290 "kind": "individual", 291 ... 292 } 294 Figure 2: KIND mapping example 296 2.3.4. XML 298 The XML property doesn't have a direct match with a JSContact 299 feature. 301 2.4. Identification Properties 303 2.4.1. FN 305 All the FN instances are represented through the "fullName" member 306 (Figure 3). The presence of multiple instances is implicitly 307 associated with the full name translations in various languages 308 regardless of the presence of the ALTID parameter. Each translation 309 is mapped according to the rules as defined in Section 2.1. 311 If the vCard represents a group of contacts, implementers MAY convert 312 the FN property into either "CardGroup.card.fullName" or 313 "CardGroup.name" or both properties. 315 2.4.2. N and NICKNAME 317 The N instances are converted into equivalent items of the 318 "components" array of the "name" property (Figure 3): the N 319 components are transformed into related "NameComponent" objects as 320 presented in Table 1. Name components SHOULD be ordered such that 321 their values joined by whitespace produce a valid full name of this 322 entity. 324 Each NICKNAME instance is mapped to an item of "nickNames" array. 326 +====================+==============+ 327 | N component | "type" value | 328 +====================+==============+ 329 | Honorific Prefixes | prefix | 330 +--------------------+--------------+ 331 | Given Names | personal | 332 +--------------------+--------------+ 333 | Family Names | surname | 334 +--------------------+--------------+ 335 | Additional Names | additional | 336 +--------------------+--------------+ 337 | Honorific Suffixes | suffix | 338 +--------------------+--------------+ 340 Table 1: N components mapping 342 BEGIN:VCARD 343 VERSION:4.0 344 ... 345 FN:Mr. John Q. Public\, Esq. 346 N:Public;John;Quinlan;Mr.;Esq. 347 NICKNAME:Johnny 348 ... 349 END:VCARD 351 { 352 ... 353 "fullName":{ "value": "Mr. John Q. Public, Esq." }, 354 "name":{ 355 "components":[ 356 { "value":"Mr.", "type": "prefix" }, 357 { "value":"John", "type": "personal" }, 358 { "value":"Public", "type": "surname" }, 359 { "value":"Quinlan", "type": "additional" }, 360 { "value":"Esq.", "type": "suffix" } 361 ] 362 }, 363 "nickNames":[ 364 { "value": "Johnny" } 365 ], 366 ... 367 } 369 Figure 3: FN, N, NICKNAME mapping example 371 2.4.3. PHOTO 373 A PHOTO property is represented as an entry of the "photos" map 374 (Figure 4). The entry value is a "File" object whose "href" member 375 is the PHOTO value. 377 The PREF and MEDIATYPE parameters are mapped according to the rules 378 as defined in Section 2.1. 380 BEGIN:VCARD 381 VERSION:4.0 382 ... 383 PHOTO:http://www.example.com/pub/photos/jqpublic.gif 384 ... 385 END:VCARD 387 { 388 ... 389 "photos":{ 390 ... 391 "a-photo":{ 392 "href": "http://www.example.com/pub/photos/jqpublic.gif" 393 }, 394 ... 395 }, 396 ... 397 } 399 Figure 4: PHOTO mapping example 401 2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 403 The BDAY and ANNIVERSARY properties and the extensions BIRTHPLACE, 404 DEATHDATE, DEATHPLACE described in [RFC6350] are represented as 405 "Anniversary" objects included in the "anniversaries" map (Figure 5): 407 * BDAY and BIRTHPLACE are mapped to "date" and "place" where "type" 408 is set to "birth"; 409 * DEATHDATE and DEATHPLACE are mapped to "date" and "place" where 410 "type" is set to "death"; 411 * ANNIVERSARY is mapped to "date" where "type" is empty and "label" 412 is set to a value describing in detail the kind of anniversary 413 (e.g. "marriage date" for the wedding anniversary). 415 Both birth and death places are represented as instances of the 416 "Address" object. 418 The BIRTHPLACE and DEATHPLACE properties that are represented as geo 419 URIs are converted into "Address" instances including only the 420 "coordinates" member. If the URI value is not a geo URI, the place 421 is ignored. 423 The ALTID and LANGUAGE parameters of both BIRTHPLACE and DEATHPLACE 424 properties are mapped according to the rules as defined in 425 Section 2.1. 427 BEGIN:VCARD 428 VERSION:4.0 429 ... 430 BDAY:19531015T231000Z 431 BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A. 432 DEATHDATE:19960415 433 DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A. 434 ANNIVERSARY:19860201 435 ... 436 END:VCARD 438 { 439 ... 440 "anniversaries": { 441 "ANNIVERSARY-1" : { 442 "type": "birth", 443 "date": "1953-10-15T23:10:00Z", 444 "place":{ 445 "fullAddress":{ 446 "value": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A." 447 } 448 } 449 }, 450 "ANNIVERSARY-2" : { 451 "type": "birth", 452 "date": "1953-10-15T23:10:00Z", 453 "place":{ 454 "fullAddress":{ 455 "value": "4445 Courtright Street\nNew England, ND 58647\nU.S.A." 456 } 457 } 458 }, 459 "ANNIVERSARY-3" : { 460 "label": "marriage date", 461 "date": "1986-02-01" 462 } 463 }, 464 ... 465 } 466 Figure 5: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 467 mapping example 469 2.4.5. GENDER 471 The GENDER property is a single structured value with two optional 472 components: the biological sex and the gender information. The 473 former is represented as an enumerated value, while the latter as a 474 free-form text. As opposed to such a representation, the JSContact 475 specification includes the "SpeakToAs" object just to represent how 476 to address, speak to or refer to the contact. In particular, some 477 pre-defined values are allowed for the "grammaticalGender" member. 479 For the reasons stated above, the GENDER property doesn't have a 480 direct match with the "SpeakToAs" object. However, on the assumption 481 that the GENDER property doesn't store the actual biological sex of 482 the contact, implementations MAY use the conversion rules shown in 483 Table 2 and Table 3. 485 +==============+=====================================+ 486 | GENDER value | "SpeakToAs.grammaticalGender" value | 487 +==============+=====================================+ 488 | M | male | 489 +--------------+-------------------------------------+ 490 | F | female | 491 +--------------+-------------------------------------+ 492 | N | neuter | 493 +--------------+-------------------------------------+ 494 | O | animate | 495 +--------------+-------------------------------------+ 496 | U | SpeakToAs = null | 497 +--------------+-------------------------------------+ 499 Table 2: GENDER to SpeakToAs conversion 501 +=====================================+==============+ 502 | "SpeakToAs.grammaticalGender" value | GENDER value | 503 +=====================================+==============+ 504 | male | M | 505 +-------------------------------------+--------------+ 506 | female | F | 507 +-------------------------------------+--------------+ 508 | neuter | N | 509 +-------------------------------------+--------------+ 510 | animate | O | 511 +-------------------------------------+--------------+ 512 | inanimate | N;inanimate | 513 +-------------------------------------+--------------+ 515 Table 3: SpeakToAs to GENDER conversion 517 2.5. Delivery Addressing Properties 519 2.5.1. ADR 521 An ADR property is represented as an entry of the "addresses" map 522 (Figure 6). The entry value is an "Address" object. 524 The ADR components are transformed into the "Address" members as 525 presented in Table 4 and Table 5. 527 The "street address" and "extended address" ADR components MAY be 528 converted into either a single StreetComponent item or a combination 529 of StreetComponent items. 531 +===============+================+ 532 | ADR component | Address member | 533 +===============+================+ 534 | locality | locality | 535 +---------------+----------------+ 536 | region | region | 537 +---------------+----------------+ 538 | postal code | postcode | 539 +---------------+----------------+ 540 | country name | country | 541 +---------------+----------------+ 543 Table 4: ADR components vs. 544 Address members mapping 546 +===============+======================+========================+ 547 | ADR component | Single | Combination of | 548 | | StreetComponent item | StreetComponent items | 549 +===============+======================+========================+ 550 | post office | postOfficeBox | | 551 | box | | | 552 +---------------+----------------------+------------------------+ 553 | extended | extension | extension, building, | 554 | address | | floor, room, apartment | 555 +---------------+----------------------+------------------------+ 556 | street | name | name, number, | 557 | address | | direction | 558 +---------------+----------------------+------------------------+ 560 Table 5: ADR components vs. StreetComponent items mapping 562 The LABEL parameter is converted into the "fullAddress" member. 564 The GEO parameter is converted into the "coordinates" member. 566 The TZ parameter is converted into the "timeZone" member. 568 The CC parameter as defined in [RFC8605] is converted into the 569 "countryCode" member. 571 The PREF and TYPE parameters are mapped according to the rules as 572 defined in Section 2.1. 574 The ALTID and LANGUAGE parameters are mapped according to the rules 575 as defined in Section 2.1. Each possible language-dependent 576 alternative is represented as an entry of the PatchObject map where 577 the key references the "fullAddress" member. 579 BEGIN:VCARD 580 VERSION:4.0 581 ... 582 ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA 583 ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA 584 ... 585 END:VCARD 587 { 588 ... 589 "addresses":{ 590 "work-address" :{ 591 "contexts":{ "work": true }, 592 "fullAddress":{ 593 "value": "54321 Oak St\nReston\nVA\n20190\nUSA" 594 }, 595 "street": [ 596 { "name": "Oak St" }, 597 { "number" : "54321" } 598 ], 599 "locality": "Reston", 600 "region": "VA", 601 "country": "USA", 602 "postcode": "20190", 603 "countryCode": "US" 604 }, 605 "private-address":{ 606 "contexts":{ "private": true }, 607 "fullAddress":{ 608 "value": "12345 Elm St\nReston\nVA\n20190\nUSA" 609 }, 610 "street": [ 611 { "name": "Elm St" }, 612 { "number" : "12345" } 613 ], 614 "locality": "Reston", 615 "region": "VA", 616 "country": "USA", 617 "postcode": "20190", 618 "countryCode": "US" 619 } 620 }, 621 ... 622 } 624 Figure 6: ADR mapping example 626 2.6. Communications Properties 628 2.6.1. TEL 630 A TEL property is represented as an entry of the "phones" map 631 (Figure 7). The entry value is a "Phone" object. The TEL-specific 632 values of the TYPE parameter are mapped to the "features" map keys. 633 The values that don't match a key are represented as comma-separated 634 values of the "label" member. The "phone" member is set to the TEL 635 value. 637 The PREF and TYPE parameters are mapped according to the rules as 638 defined in Section 2.1. 640 BEGIN:VCARD 641 VERSION:4.0 642 ... 643 TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555 644 TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67 645 ... 646 END:VCARD 648 { 649 ... 650 "phones":{ 651 "a-phone":{ 652 "contexts":{ "private": true }, 653 "features":{ "voice": true }, 654 "phone": "tel:+1-555-555-5555;ext=5555", 655 "pref": 1 656 }, 657 "another-phone":{ 658 "contexts":{ "private": true }, 659 "phone": "tel:+33-01-23-45-67" 660 } 661 ], 662 ... 663 } 665 Figure 7: TEL mapping example 667 2.6.2. EMAIL 669 An EMAIL property is represented as an entry of the "emails" map 670 (Figure 8). The entry value is an "EmailAddress" object. The 671 "email" member is set to the EMAIL value. 673 The PREF and TYPE parameters are mapped according to the rules as 674 defined in Section 2.1. 676 BEGIN:VCARD 677 VERSION:4.0 678 ... 679 EMAIL;TYPE=work:jqpublic@xyz.example.com 680 EMAIL;PREF=1:jane_doe@example.com 681 ... 682 END:VCARD 684 { 685 ... 686 "emails":{ 687 "work-email":{ 688 "contexts":{ "work": true }, 689 "email": "jqpublic@xyz.example.com" 690 }, 691 "private-email":{ 692 "contexts":{ "private", true }, 693 "email": "jane_doe@example.com", 694 "pref": 1 695 } 696 }, 697 ... 698 } 700 Figure 8: EMAIL mapping example 702 2.6.3. IMPP 704 An IMPP property is represented as an entry of the "online" map 705 (Figure 9). The entry value is a "Resource" object whose "type" 706 member is set to "username", the "label" member is set to "XMPP" and 707 the "resource" member is the IMPP value. 709 The PREF and TYPE parameters are mapped according to the rules as 710 defined in Section 2.1. 712 BEGIN:VCARD 713 VERSION:4.0 714 ... 715 IMPP;PREF=1:xmpp:alice@example.com 716 ... 717 END:VCARD 719 { 720 ... 721 "online":{ 722 ... 723 { 724 "type": "username", 725 "label": "XMPP", 726 "value": "alice@example.com" 727 }, 728 ... 729 }, 730 ... 731 } 733 Figure 9: IMPP mapping example 735 2.6.4. LANG 737 A LANG property is represented as an entry of the 738 "preferredContactLanguages" map (Figure 10). The entry keys 739 correspond to the language tags, the corresponding entry values are 740 arrays of "ContactLanguage" objects. 742 The PREF and TYPE parameters are mapped according to the rules as 743 defined in Section 2.1. 745 If both PREF and TYPE parameters are missing, the array of 746 "ContactLanguage" objects MUST be empty. 748 BEGIN:VCARD 749 VERSION:4.0 750 ... 751 LANG;TYPE=work;PREF=1:en 752 LANG;TYPE=work;PREF=2:fr 753 LANG;TYPE=home:fr 754 ... 755 END:VCARD 757 { 758 ... 759 "preferredContactLanguages":{ 760 "en":[ 761 { 762 "context": "work", 763 "pref": 1 764 } 765 ], 766 "fr":[ 767 { 768 "context": "work", 769 "pref": 2 770 }, 771 { 772 "context": "private" 773 } 774 ] 775 }, 776 ... 777 } 779 Figure 10: LANG mapping example 781 2.7. Geographical Properties 783 The GEO and TZ properties are not directly mapped to topmost Card 784 members because the same information is represented through 785 equivalent "Address" members. 787 The ALTID parameter is used for associating both GEO and TZ 788 properties with the related address information. When the ALTID 789 parameter is missing, the matched members SHOULD be included in the 790 first "Address" object. 792 2.7.1. Time Zone Representation 794 As specified in Section 6.5.1 of [RFC6350], the time zone information 795 can be represented as a time zone name, as a UTC offset or as a URI. 797 * If the TZ value is defined in the IANA timezone database, it is 798 directly matched by the "timeZone" member in JSContact. 799 * An UTC offset MUST be converted into the related "Etc/GMT" time 800 zone (e.g. the value "-0500" converts to "Etc/GMT+5"). If the UTC 801 offset value contains minutes information or is not an IANA 802 timezone name, it requires special handling. 803 * Since there is no URI scheme defined for time zones [uri-schemes], 804 any implementation that does use some a custom URI for a time zone 805 is not interoperable anyway. In this case, if the URI corresponds 806 to an IANA time zone [time-zones], this latter SHOULD be used. 807 Otherwise, the URI value is dumped into a string. 809 2.8. Organizational Properties 811 2.8.1. TITLE and ROLE 813 Both TITLE and ROLE properties are represented as entries of the 814 "titles" map (Figure 11). The entry value is a "Title" object whose 815 "title" member includes information about the title or role. The 816 rules to set the "organization" member are out of the scope of this 817 document. 819 The ALTID and LANGUAGE parameters are mapped according to the rules 820 as defined in Section 2.1. 822 BEGIN:VCARD 823 VERSION:4.0 824 ... 825 TITLE:Research Scientist 826 ROLE:Project Leader 827 ... 828 END:VCARD 830 { 831 ... 832 "titles":{ 833 "a-title":{ 834 "title":{ "value" : "Project Leader" } 835 }, 836 "another-title":{ 837 "title":{ "value" : "Research Scientist" } 838 } 839 }, 840 ... 841 } 843 Figure 11: TITLE and ROLE mapping example 845 2.8.2. LOGO 847 A LOGO property is represented as an entry of the "online" map 848 (Figure 12). The entry value is a "Resource" object whose "type" 849 member is set to "uri", the "label" member is set to "logo" and the 850 "resource" member is the LOGO value. 852 The PREF and TYPE parameters are mapped according to the rules as 853 defined in Section 2.1. 855 BEGIN:VCARD 856 VERSION:4.0 857 ... 858 LOGO:http://www.example.com/pub/logos/abccorp.jpg 859 ... 860 END:VCARD 862 { 863 ... 864 "online":{ 865 ... 866 "a-logo":{ 867 "type": "uri", 868 "label": "logo", 869 "resource": "http://www.example.com/pub/logos/abccorp.jpg" 870 }, 871 ... 872 }, 873 ... 874 } 876 Figure 12: LOGO mapping example 878 2.8.3. ORG 880 An ORG property is represented as an entry of the "organizations" map 881 (Figure 13). The entry value is an "Organization" object whose 882 "name" member contains the organizational name and the "units" member 883 contains the organizational units. 885 The ALTID and LANGUAGE parameters are mapped according to the rules 886 as defined in Section 2.1. 888 BEGIN:VCARD 889 VERSION:4.0 890 ... 891 ORG:ABC\, Inc.;North American Division;Marketing 892 ... 893 END:VCARD 895 { 896 ... 897 "organizations":{ 898 "an-organization":{ 899 "name":{ "value": "ABC, Inc." }, 900 "units":[ 901 { "value": "North American Division" }, 902 { "value": "Marketing" } 903 ] 904 } 905 }, 906 ... 907 } 909 Figure 13: ORG mapping example 911 2.8.4. MEMBER 913 According to the JSContact specification, a group of contact cards is 914 represented through a CardGroup (Figure 14). The uids of the contact 915 cards composing the group are included in the "members" map. 917 In this case, the PREF parameter has not a JSContact counterpart; 918 however, the implementers MAY insert the map entries by order of 919 preference. 921 BEGIN:VCARD 922 VERSION:4.0 923 KIND:group 924 FN:The Doe family 925 MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 926 MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 927 END:VCARD 929 { 930 "kind": "group", 931 "fullName":{ "value": "The Doe family" }, 932 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 933 "members":{ 934 "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, 935 "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true 936 } 937 } 939 Figure 14: Group example 941 Only if the GROUP contains properties that don't have a mapping to 942 CardGroup properties, then the CardGroup.card property MAY contain 943 the optional Card object of this group. 945 { 946 "name": "The Doe family", 947 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 948 "members":{ 949 "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, 950 "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true 951 }, 952 "card": { 953 "fullName":{ "value": "The Doe family" }, 954 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 955 "photos":{ 956 "a-photo":{ 957 "href": "http://www.example.com/pub/photos/jqpublic.gif" 958 } 959 } 960 } 961 } 963 Figure 15: card member of CardGroup object 965 2.8.5. RELATED 967 All the RELATED instances are converted into the "relatedTo" map 968 (Figure 16): an entry for each entity the entity described by the 969 Card is associated with. The map keys are the "uid" values of the 970 associated cards. 972 Each map value is a "Relation" object including only the "relation" 973 member represented as a set of the RELATED-specific values of the 974 TYPE parameter as defined in Section 6.6.6 of [RFC6350]. 976 If the relation type is unspecified, the "relation" member MUST be 977 empty. 979 BEGIN:VCARD 980 VERSION:4.0 981 ... 982 RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 983 RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf 984 RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries. 985 ... 986 END:VCARD 988 { 989 ... 990 "relatedTo":{ 991 { 992 "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6":{ 993 "relation":{ "friend": true } 994 } 995 }, 996 { 997 "http://example.com/directory/jdoe.vcf":{ 998 "relation":{ "contact": true } 999 } 1000 }, 1001 { 1002 "Please contact my assistant Jane Doe for any inquiries.":{ 1003 "relation":{ } 1004 } 1005 } 1006 }, 1007 ... 1008 } 1010 Figure 16: RELATED mapping example 1012 2.8.6. CONTACT-URI 1014 A CONTACT-URI property as defined in [RFC8605] is represented as an 1015 entry of the "online" map (Figure 17). The entry value is a 1016 "Resource" object whose "type" member is set to "uri", the "label" 1017 member is set to "contact-uri" and the "resource" member is the 1018 CONTACT-URI value. 1020 The PREF and TYPE parameters are mapped according to the rules as 1021 defined in Section 2.1. 1023 BEGIN:VCARD 1024 VERSION:4.0 1025 ... 1026 CONTACT-URI;PREF=1:mailto:contact@example.com 1027 ... 1028 END:VCARD 1030 { 1031 ... 1032 "online":{ 1033 ... 1034 "a-contact-uri":{ 1035 "type": "uri", 1036 "label": "contact-uri", 1037 "resource": "mailto:contact@example.com", 1038 "pref": 1 1039 }, 1040 ... 1041 }, 1042 ... 1043 } 1045 Figure 17: CONTACT-URI mapping example 1047 2.9. Personal Information Properties 1049 The LEVEL parameter as defined in [RFC6715] is directly mapped to the 1050 "level" property of the "PersonalInformation" type apart from when 1051 LEVEL is used in the EXPERTISE property; in this case, the values are 1052 converted as in the following: 1054 * "beginner" is converted into "low"; 1055 * "average" is converted into "medium"; 1056 * "expert" is converted into "high". 1058 2.9.1. EXPERTISE 1060 An EXPERTISE property as defined in [RFC6715] is represented as a 1061 "PersonalInformation" object in the "personalInfo" map (Figure 18). 1062 The "type" member is set to "expertise". 1064 The INDEX parameter is represented as the index of the expertise 1065 among the declared expertises. 1067 BEGIN:VCARD 1068 VERSION:4.0 1069 ... 1070 EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature 1071 EXPERTISE;INDEX=1;LEVEL=expert:chemistry 1072 ... 1073 END:VCARD 1075 { 1076 ... 1077 "personalInfo":{ 1078 ... 1079 "PERSINFO-1" : { 1080 "type": "expertise", 1081 "value": "chemistry", 1082 "level": "high" 1083 }, 1084 "PERSINFO-2" : { 1085 "type": "expertise", 1086 "value": "chinese literature", 1087 "level": "low" 1088 }, 1089 ... 1090 }, 1091 ... 1092 } 1094 Figure 18: EXPERTISE mapping example 1096 2.9.2. HOBBY 1098 A HOBBY property as defined in [RFC6715] is represented as a 1099 "PersonalInformation" object in the "personalInfo" map (Figure 19). 1100 The "type" member is set to "hobby". 1102 The INDEX parameter is represented as the index of the hobby among 1103 the declared hobbies. 1105 BEGIN:VCARD 1106 VERSION:4.0 1107 ... 1108 HOBBY;INDEX=1;LEVEL=high:reading 1109 HOBBY;INDEX=2;LEVEL=high:sewing 1110 ... 1111 END:VCARD 1113 { 1114 ... 1115 "personalInfo":{ 1116 ... 1117 "PERSINFO-1" : { 1118 "type": "hobby", 1119 "value": "reading", 1120 "level": "high" 1121 }, 1122 "PERSINFO-2" : { 1123 "type": "hobby", 1124 "value": "sewing", 1125 "level": "high" 1126 }, 1127 ... 1128 }, 1129 ... 1130 } 1132 Figure 19: HOBBY mapping example 1134 2.9.3. INTEREST 1136 An INTEREST property as defined in [RFC6715] is represented as a 1137 "PersonalInformation" object in the "personalInfo" map (Figure 20). 1138 The "type" member is set to "interest". 1140 The INDEX parameter is represented as the index of the interest among 1141 the declared interests. 1143 BEGIN:VCARD 1144 VERSION:4.0 1145 ... 1146 INTEREST;INDEX=1;LEVEL=medium:r&b music 1147 INTEREST;INDEX=2;LEVEL=high:rock ’n’ roll music 1148 ... 1149 END:VCARD 1151 { 1152 ... 1153 "personalInfo":{ 1154 ... 1155 "PERSINFO-1" : { 1156 "type": "interest", 1157 "value": "r&b music", 1158 "level": "medium" 1159 }, 1160 "PERSINFO-2" : { 1161 "type": "interest", 1162 "value": "rock ’n’ roll music", 1163 "level": "high" 1164 }, 1165 ... 1166 }, 1167 ... 1168 } 1170 Figure 20: INTEREST mapping example 1172 2.9.4. ORG-DIRECTORY 1174 An ORG-DIRECTORY property is represented as an entry of the "online" 1175 map (Figure 21). The entry value is a "Resource" object whose "type" 1176 member is set to "uri", the "label" member is set to "org-directory" 1177 and the "resource" member is the ORG-DIRECTORY value. 1179 The PREF and TYPE parameters are mapped according to the rules as 1180 defined in Section 2.1. 1182 The INDEX parameter is represented as the index of the directory 1183 among the online resources with the "org-directory" label. 1185 BEGIN:VCARD 1186 VERSION:4.0 1187 ... 1188 ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com 1189 ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering 1190 ... 1191 END:VCARD 1193 { 1194 ... 1195 "online":{ 1196 ... 1197 "an-org-directory":{ 1198 "type": "uri", 1199 "label": "org-directory", 1200 "resource": "http://directory.mycompany.example.com" 1201 }, 1202 "another-org-directory":{ 1203 "type": "uri", 1204 "label": "org-directory", 1205 "resource": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering", 1206 "pref": 1 1207 }, 1208 ... 1209 }, 1210 ... 1211 } 1213 Figure 21: ORG-DIRECTORY mapping example 1215 2.10. Explanatory Properties 1217 2.10.1. CATEGORIES 1219 A CATEGORIES property is converted into a set of entries of the 1220 "categories" map (Figure 22). The keys are the comma-separated text 1221 values of the CATEGORIES property. 1223 In this case, the PREF parameter has not a JSContact counterpart; 1224 however, implementers MAY use a map preserving the order of insertion 1225 and the map entries can be inserted by order of preference. 1227 BEGIN:VCARD 1228 VERSION:4.0 1229 ... 1230 CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY 1231 ... 1232 END:VCARD 1234 { 1235 ... 1236 "categories":{ 1237 "INTERNET": true, 1238 "IETF": true, 1239 "INDUSTRY": true, 1240 "INFORMATION TECHNOLOGY": true 1241 }, 1242 ... 1243 } 1245 Figure 22: CATEGORIES mapping example 1247 2.10.2. NOTE 1249 A NOTE property is mapped to the "notes" property (Figure 23). All 1250 the NOTE instances are condensed into a single note and separated by 1251 newline. 1253 The ALTID and LANGUAGE parameters are mapped according to the rules 1254 as defined in Section 2.1. 1256 BEGIN:VCARD 1257 VERSION:4.0 1258 ... 1259 NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri. 1260 ... 1261 END:VCARD 1263 { 1264 ... 1265 "notes": { 1266 "value": "This fax number is operational 0800 to 1715 EST, Mon-Fri." 1267 }, 1268 ... 1269 } 1271 Figure 23: NOTE mapping example 1273 2.10.3. PRODID 1275 The PRODID property is converted into the "prodId" member 1276 (Figure 24). 1278 BEGIN:VCARD 1279 VERSION:4.0 1280 ... 1281 PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN 1282 ... 1283 END:VCARD 1285 { 1286 ... 1287 "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN", 1288 ... 1289 } 1291 Figure 24: PRODID mapping example 1293 2.10.4. REV 1295 The REV property is transformed into the "updated" member 1296 (Figure 25). 1298 BEGIN:VCARD 1299 VERSION:4.0 1300 ... 1301 REV:19951031T222710Z 1302 ... 1303 END:VCARD 1305 { 1306 ... 1307 "updated": "1995-10-31T22:27:10Z", 1308 ... 1309 } 1311 Figure 25: REV mapping example 1313 2.10.5. SOUND 1315 A SOUND property is represented as an entry of the "online" map 1316 (Figure 26). The entry value is a "Resource" object whose "type" 1317 member is set to "uri", the "label" member is set to "sound" and the 1318 "resource" member is the SOUND value. 1320 The PREF and TYPE parameters are mapped according to the rules as 1321 defined in Section 2.1. 1323 BEGIN:VCARD 1324 VERSION:4.0 1325 ... 1326 SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com 1327 ... 1328 END:VCARD 1330 { 1331 ... 1332 "online":{ 1333 ... 1334 "a-sound":{ 1335 "type": "uri", 1336 "label": "sound", 1337 "resource": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com" 1338 }, 1339 ... 1340 }, 1341 ... 1342 } 1344 Figure 26: SOUND mapping example 1346 2.10.6. UID 1348 The UID property corresponds to the "uid" property (Figure 27) in 1349 both Card and CardGroup. 1351 BEGIN:VCARD 1352 VERSION:4.0 1353 ... 1354 UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 1355 ... 1356 END:VCARD 1358 { 1359 ... 1360 "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6", 1361 ... 1362 } 1364 Figure 27: UID mapping example 1366 2.10.7. CLIENTPIDMAP and PID Parameter 1368 The CLIENTPIDMAP property and the PDI parameter don't have a direct 1369 match with a Card feature. 1371 2.10.8. URL 1373 An URL property is represented as an entry of the "online" map 1374 (Figure 28). The entry value is a "Resource" object whose "type" 1375 member is set to "uri", the "label" member is set to "url" and the 1376 "resource" member is the URL value. 1378 The PREF and TYPE parameters are mapped according to the rules as 1379 defined in Section 2.1. 1381 BEGIN:VCARD 1382 VERSION:4.0 1383 ... 1384 URL:http://example.org/restaurant.french/~chezchic.html 1385 ... 1386 END:VCARD 1388 { 1389 ... 1390 "online":{ 1391 ... 1392 "an-url":{ 1393 "type": "uri", 1394 "label": "url", 1395 "resource": "http://example.org/restaurant.french/~chezchic.html" 1396 }, 1397 ... 1398 }, 1399 ... 1400 } 1402 Figure 28: URL mapping example 1404 2.10.9. VERSION 1406 The VERSION property doesn't have a direct match with a JSContact 1407 feature. 1409 2.11. Security Properties 1410 2.11.1. KEY 1412 A KEY property is represented as an entry of the "online" map 1413 (Figure 29). The entry value is a "Resource" object whose "type" 1414 member is set to "uri", the "label" member is set to "key" and the 1415 "resource" member is the KEY value. 1417 The PREF and TYPE parameters are mapped according to the rules as 1418 defined in Section 2.1. 1420 BEGIN:VCARD 1421 VERSION:4.0 1422 ... 1423 KEY:http://www.example.com/keys/jdoe.cer 1424 ... 1425 END:VCARD 1427 { 1428 ... 1429 "online":{ 1430 ... 1431 "a-key":{ 1432 "type": "uri", 1433 "label": "key", 1434 "resource": "http://www.example.com/keys/jdoe.cer" 1435 }, 1436 ... 1437 }, 1438 ... 1439 } 1441 Figure 29: KEY mapping example 1443 2.12. Calendar Properties 1445 2.12.1. FBURL 1447 An FBURL property is represented as an entry of the "online" map 1448 (Figure 30). The entry value is a "Resource" object whose "type" 1449 member is set to "uri", the "label" member is set to "fburl" and the 1450 "resource" member is the FBURL value. 1452 The PREF and TYPE parameters are mapped according to the rules as 1453 defined in Section 2.1. 1455 BEGIN:VCARD 1456 VERSION:4.0 1457 ... 1458 FBURL;PREF=1:http://www.example.com/busy/janedoe 1459 FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb 1460 ... 1461 END:VCARD 1463 { 1464 ... 1465 "online":{ 1466 ... 1467 "an-fburl":{ 1468 "type": "uri", 1469 "label": "fburl", 1470 "resource": "http://www.example.com/busy/janedoe", 1471 "pref": 1 1472 }, 1473 "another-fburl":{ 1474 "type": "uri", 1475 "label": "fburl", 1476 "resource": "ftp://example.com/busy/project-a.ifb", 1477 "mediaType": "text/calendar" 1478 }, 1479 ... 1480 }, 1481 ... 1482 } 1484 Figure 30: FBURL mapping example 1486 2.12.2. CALADRURI 1488 A CALADRURI property is represented as an entry of the "online" map 1489 (Figure 31). The entry value is a "Resource" object whose "type" 1490 member is set to "uri", the "label" member is set to "caladruri" and 1491 the "resource" member is the CALADRURI value. 1493 The PREF and TYPE parameters are mapped according to the rules as 1494 defined in Section 2.1. 1496 BEGIN:VCARD 1497 VERSION:4.0 1498 ... 1499 CALADRURI;PREF=1:mailto:janedoe@example.com 1500 CALADRURI:http://example.com/calendar/jdoe 1501 ... 1502 END:VCARD 1504 { 1505 ... 1506 "online":{ 1507 ... 1508 "a-caladruri":{ 1509 "type": "uri", 1510 "label": "caladruri", 1511 "resource": "mailto:janedoe@example.com", 1512 "pref": 1 1513 }, 1514 "another-caladruri":{ 1515 "type": "uri", 1516 "label": "caladruri", 1517 "resource": "http://example.com/calendar/jdoe" 1518 }, 1519 ... 1520 }, 1521 ... 1522 } 1524 Figure 31: CALADRURI mapping example 1526 2.12.3. CALURI 1528 A CALURI property is represented as an entry of the "online" map 1529 (Figure 32). The entry value is a "Resource" object whose "type" 1530 member is set to "uri", the "label" member is set to "caluri" and the 1531 "resource" member is the CALURI value. 1533 The PREF and TYPE parameters are mapped according to the rules as 1534 defined in Section 2.1. 1536 BEGIN:VCARD 1537 VERSION:4.0 1538 ... 1539 CALURI;PREF=1:http://cal.example.com/calA 1540 CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics 1541 ... 1542 END:VCARD 1544 { 1545 ... 1546 "online":{ 1547 ... 1548 "a-caluri":{ 1549 "type": "uri", 1550 "label": "caluri", 1551 "resource": "http://cal.example.com/calA", 1552 "pref": 1 1553 }, 1554 "another-caluri":{ 1555 "type": "uri", 1556 "label": "caluri", 1557 "resource": "ftp://ftp.example.com/calA.ics", 1558 "mediaType": "text/calendar" 1559 }, 1560 ... 1561 }, 1562 ... 1563 } 1565 Figure 32: CALURI mapping example 1567 2.13. vCard Unmatched Properties 1569 The unmatched vCard properties MAY be converted into JSContact 1570 properties whose name contains the prefix "ietf.org:rfc6350:" 1571 followed by property name in uppercase (i.e. 1572 ietf.org:rfc6350:CLIENTPIDMAP"). 1574 2.14. Card Required Properties 1576 While converting a vCard into a Card/CardGroup, only the topmost 1577 "uid" member is mandatory. Implementers are REQUIRED to set it when 1578 it is missing. 1580 3. Translating JSContact properties to vCard 1582 In most of the cases, the rules about the translation from Card/ 1583 CardGroup to vCard can be derived by reversing the rules presented in 1584 Section 2. The remaining cases are treated in the following of this 1585 section. 1587 3.1. Id 1589 Where a map key is of type Id, implementers are free to either ignore 1590 it or preserve it as a vCard information (e.g. a vCard parameter). 1592 3.2. Localizations 1594 Each PatchObject entry value of each "localizations" entry is 1595 converted into a instance of the vCard property matching the 1596 JSContact member referenced by the PatchObject entry key. The 1597 LANGUAGE parameter of such alternative MUST be set to the value of 1598 the given "localizations" entry. The LANGUAGE parameter of a vCard 1599 property presenting, at least, a language-dependent alternative MUST 1600 be set to the value of the JSContact "language" property if it is 1601 valued. Implementers MAY set the ALTID parameter to group language- 1602 based alternatives of the same value. 1604 Note also that the components of some vCard values and their 1605 language-dependent alternatives are split into different JSContact 1606 values. For example, the "name" and "units" values for a given 1607 language must be grouped to make a single ORG value where components 1608 are separated by ";". 1610 3.3. Date and Time Representations 1612 The JSContact spec defines the "UTCDateTime" type to represent 1613 [RFC3339] "date-time" format with further restrictions. This means 1614 that the matched vCard format for a "UTCDateTime" value MUST be one 1615 of the formats shown in Section 4.3.5 of [RFC6350] (i.e. 1616 "19961022T140000Z"). 1618 In addition to such format, the "date" member of the "Anniversary" 1619 type allows to specify both dates without the time and partial dates. 1620 In such cases, the corresponding vCard format is that defined in 1621 Section 4.3.1. 1623 3.4. Time Zone 1625 The time zone name as represented by the "timeZone" property is 1626 mapped to the TZ parameter. 1628 Implementers MAY map an "Etc/GMT" time zone either preserving the 1629 time zone name or converting it into a UTC offset. 1631 3.5. JSContact Types Matching Multiple vCard Properties 1633 3.5.1. Title 1635 The "titles" property contains information about the job, the 1636 position or the role of the entity the card represents. In vCard, 1637 such information is split into the TITLE and the ROLE properties. 1638 This specification defines TITLE as the default target property when 1639 converting the "titles" property. 1641 3.5.2. Resource 1643 The "online" property includes resources that are usually represented 1644 through different vCard properties. The matched vCard property of a 1645 "Resource" object can be derived from the value of its "label" 1646 member. 1648 Any resource included in the "online" map that doesn't match a vCard 1649 property MAY be converted into a vCard extended property. 1651 3.6. CardGroup 1653 A CardGroup object is converted into a vCard by merging its 1654 properties with the properties of "CardGroup.card" object. If the 1655 "CardGroup.card.fullName" property exists, it MUST be used to set the 1656 FN value. 1658 3.7. Card Unmatched Properties 1660 Both the "preferredContactMethod" and "created" members don't match 1661 any vCard property. Implementers MAY represent them as vCard 1662 extended properties. 1664 3.8. vCard Required Properties 1666 While converting a Card/CardGroup into a vCard, only the FN property 1667 is required. Since both the "Card.fullName" and "CardGroup.name" 1668 properties are optional, implementers are REQUIRED to generate an FN 1669 value when it is missing. 1671 4. IANA Considerations 1673 This document has no actions for IANA. 1675 5. Implementation Status 1677 NOTE: Please remove this section and the reference to RFC 7942 prior 1678 to publication as an RFC. 1680 This section records the status of known implementations of the 1681 protocol as defined in this specification at the time of posting of 1682 this Internet-Draft, and is based on a proposal described in 1683 [RFC7942]. The description of implementations in this section is 1684 intended to assist the IETF in its decision processes in progressing 1685 drafts to RFCs. Please note that the listing of any individual 1686 implementation here does not imply endorsement by the IETF. 1687 Furthermore, no effort has been spent to verify the information 1688 presented here that was supplied by IETF contributors. This is not 1689 intended as, and must not be construed to be, a catalog of available 1690 implementations or their features. Readers are advised to note that 1691 other implementations may exist. 1693 According to RFC 7942, "this will allow reviewers and working groups 1694 to assign due considerationto documents that have the benefit of 1695 running code, which may serve as evidence of valuable experimentation 1696 and feedback that have made the implemented protocols more mature. 1697 It is up to the individual working groups to use this information as 1698 they see fit". 1700 5.1. CNR 1702 * Responsible Organization: National Research Council (CNR) of Italy 1703 * Location: https://github.com/consiglionazionaledellericerche/ 1704 jscontact-tools 1705 * Description: This implementation includes tools for JSContact 1706 creation, validation, serialization/deserialization, and 1707 conversion from vCard, xCard and jCard. 1708 * Level of Maturity: This is an "alpha" test implementation. 1709 * Coverage: This implementation includes all of the features 1710 described in this specification. 1711 * Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it 1713 6. Security Considerations 1715 This document doesn't present any security consideration. 1717 7. References 1719 7.1. Normative References 1721 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1722 Requirement Levels", BCP 14, RFC 2119, 1723 DOI 10.17487/RFC2119, March 1997, 1724 . 1726 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1727 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1728 . 1730 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 1731 DOI 10.17487/RFC6350, August 2011, 1732 . 1734 [RFC6473] Saint-Andre, P., "vCard KIND:application", RFC 6473, 1735 DOI 10.17487/RFC6473, December 2011, 1736 . 1738 [RFC6474] Li, K. and B. Leiba, "vCard Format Extensions: Place of 1739 Birth, Place and Date of Death", RFC 6474, 1740 DOI 10.17487/RFC6474, December 2011, 1741 . 1743 [RFC6715] Cauchie, D., Leiba, B., and K. Li, "vCard Format 1744 Extensions: Representing vCard Extensions Defined by the 1745 Open Mobile Alliance (OMA) Converged Address Book (CAB) 1746 Group", RFC 6715, DOI 10.17487/RFC6715, August 2012, 1747 . 1749 [RFC6869] Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard 1750 KIND:device", RFC 6869, DOI 10.17487/RFC6869, February 1751 2013, . 1753 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 1754 DOI 10.17487/RFC7095, January 2014, 1755 . 1757 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1758 Code: The Implementation Status Section", BCP 205, 1759 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1760 . 1762 [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: 1763 ICANN Extensions for the Registration Data Access Protocol 1764 (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, 1765 . 1767 7.2. Informative References 1769 [draft-ietf-jmap-jscontact] 1770 "JSContact: A JSON representation of contact data", 1771 . 1774 [time-zones] 1775 "Time Zone Database", . 1777 [uri-schemes] 1778 "Uniform Resource Identifier (URI) Schemes", 1779 . 1782 Authors' Addresses 1784 Mario Loffredo 1785 IIT-CNR/Registro.it 1786 Via Moruzzi,1 1787 56124 Pisa 1788 Italy 1790 Email: mario.loffredo@iit.cnr.it 1791 URI: http://www.iit.cnr.it 1793 Robert Stepanek 1794 FastMail 1795 PO Box 234, Collins St West 1796 Melbourne VIC 8007 1797 Australia 1799 Email: rsto@fastmailteam.com 1800 URI: https://www.fastmail.com