idnits 2.17.1 draft-ietf-jmap-jscontact-vcard-00.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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 12 instances of too long lines in the document, the longest one being 41 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 (July 13, 2020) is 1376 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC6474' is defined on line 1531, but no explicit reference was found in the text Summary: 1 error (**), 0 flaws (~~), 2 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: Informational R. Stepanek 5 Expires: January 14, 2021 FastMail 6 July 13, 2020 8 JSContact: Converting from and to vCard 9 draft-ietf-jmap-jscontact-vcard-00 11 Abstract 13 This document provides informational guidance for converting the 14 contact card defined by JSContact specification, namely JSCard, from 15 and 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 January 14, 2021. 34 Copyright Notice 36 Copyright (c) 2020 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 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.2. Scope and Caveats . . . . . . . . . . . . . . . . . . . . 3 54 1.3. Conventions Used in This Document . . . . . . . . . . . . 4 55 2. Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2.1. General Properties . . . . . . . . . . . . . . . . . . . 4 57 2.1.1. BEGIN and END . . . . . . . . . . . . . . . . . . . . 4 58 2.1.2. SOURCE . . . . . . . . . . . . . . . . . . . . . . . 4 59 2.1.3. KIND . . . . . . . . . . . . . . . . . . . . . . . . 5 60 2.1.4. XML . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 2.2. Identification Properties . . . . . . . . . . . . . . . . 6 62 2.2.1. FN . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.2.2. N and NICKNAME . . . . . . . . . . . . . . . . . . . 6 64 2.2.3. PHOTO . . . . . . . . . . . . . . . . . . . . . . . . 7 65 2.2.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 8 66 2.2.5. GENDER . . . . . . . . . . . . . . . . . . . . . . . 10 67 2.3. Delivery Addressing Properties . . . . . . . . . . . . . 10 68 2.3.1. ADR . . . . . . . . . . . . . . . . . . . . . . . . . 10 69 2.4. Communications Properties . . . . . . . . . . . . . . . . 11 70 2.4.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 12 71 2.4.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 12 72 2.4.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 13 73 2.4.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 14 74 2.5. Geographical Properties . . . . . . . . . . . . . . . . . 15 75 2.6. Organizational Properties . . . . . . . . . . . . . . . . 16 76 2.6.1. TITLE . . . . . . . . . . . . . . . . . . . . . . . . 16 77 2.6.2. ROLE . . . . . . . . . . . . . . . . . . . . . . . . 16 78 2.6.3. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 17 79 2.6.4. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 18 80 2.6.5. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 19 81 2.6.6. RELATED . . . . . . . . . . . . . . . . . . . . . . . 20 82 2.6.7. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 22 83 2.7. Personal Information Properties . . . . . . . . . . . . . 22 84 2.7.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 22 85 2.7.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 23 86 2.7.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 24 87 2.7.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 25 88 2.8. Explanatory Properties . . . . . . . . . . . . . . . . . 26 89 2.8.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 26 90 2.8.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 27 91 2.8.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 28 92 2.8.4. REV . . . . . . . . . . . . . . . . . . . . . . . . . 28 93 2.8.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . . 29 94 2.8.6. UID . . . . . . . . . . . . . . . . . . . . . . . . . 30 95 2.8.7. CLIENTPIDMAP and PID Parameter . . . . . . . . . . . 30 96 2.8.8. URL . . . . . . . . . . . . . . . . . . . . . . . . . 30 97 2.8.9. VERSION . . . . . . . . . . . . . . . . . . . . . . . 31 98 2.9. Security Properties . . . . . . . . . . . . . . . . . . . 31 99 2.9.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . . 31 100 2.10. Calendar Properties . . . . . . . . . . . . . . . . . . . 32 101 2.10.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 32 102 2.10.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 33 103 2.10.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 34 104 2.11. Additional Clarifications about Mapping . . . . . . . . . 35 105 2.11.1. Media type . . . . . . . . . . . . . . . . . . . . . 35 106 2.11.2. Timezone . . . . . . . . . . . . . . . . . . . . . . 35 107 2.12. Extended Properties . . . . . . . . . . . . . . . . . . . 36 108 2.13. vCard Unmatched Properties . . . . . . . . . . . . . . . 36 109 2.14. JSCard Required Properties . . . . . . . . . . . . . . . 36 110 2.15. JSCard Unmatched Properties . . . . . . . . . . . . . . . 36 111 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 112 4. Security Considerations . . . . . . . . . . . . . . . . . . . 37 113 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 114 5.1. Normative References . . . . . . . . . . . . . . . . . . 37 115 5.2. Informative References . . . . . . . . . . . . . . . . . 38 116 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 38 118 1. Introduction 120 1.1. Motivation 122 The JSContact specification [draft-ietf-jmap-jscontact] has been 123 defined to represent contact card information as a more efficient 124 alternative to vCard [RFC6350] and its JSON-based version named jCard 125 [RFC7095]. 127 While new applications might adopt JSContact as their main format to 128 exchange contact card data, they are likely to interoperate with 129 services and clients that just support vCard/jCard. Similarly, 130 existing contact data providers and consumers already using vCard/ 131 jCard might want to represent their data also according to the 132 JSContact specification. 134 To facilitate this use cases, this document provides informational 135 guidance about how to convert the card defined in JSContact, namely 136 JSCard, from and to vCard. 138 1.2. Scope and Caveats 140 JSContact and vCard have a lot of semantics in common, however some 141 differences must be outlined: 143 o The JSContact data model defines some contact information that 144 doesn't have a direct mapping with vCard elements. In particular, 145 unlike vCard, JSContact distinguishes between a single contact 146 card, named JSCard, and a group of contact cards, named 147 JSCardGroup. 149 o The vCard specification includes some features (like parameters) 150 that have been formally removed from JSCard due to a complete 151 refactoring of vCard content. Anyway, the vCard parameters may 152 appear as JSCard features. 154 o Some vCard elements represented individually have been mapped onto 155 members of JSCard objects. 157 o The vCard custom elements, identified by the prefix "x-", don't 158 have a direct counterpart in the JSContact specification. 160 1.3. Conventions Used in This Document 162 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 163 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 164 document are to be interpreted as described in [RFC2119]. 166 2. Mapping 168 This section contains the mapping between vCard and JSCard. The 169 vCard properties are grouped according to the categories defined by 170 [RFC6350]. 172 Where it is needed, the JCardGroup is taken into account. 174 In the following of this document, the vCard features, namely 175 properties and parameters, are written in uppercase while the JSCard 176 features are written in camel case. 178 2.1. General Properties 180 2.1.1. BEGIN and END 182 The BEGIN and END properties don't have a direct match with a JSCard 183 feature. 185 2.1.2. SOURCE 187 A SOURCE element is represented as a "Resource" object in the 188 "online" array (Figure 1) whose "type" member is set to "uri" and 189 "labels" map contains the entry <"source",true>. 191 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 192 and "mediaType" members respectively. 194 BEGIN:VCARD 195 VERSION:4.0 196 ... 197 SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf 198 ... 199 END:VCARD 201 { 202 ... 203 "online":[ 204 ... 205 { 206 "type": "uri", 207 "labels": { "source": true }, 208 "value": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf" 209 }, 210 ... 211 ], 212 ... 213 } 215 Figure 1: SOURCE mapping example 217 2.1.3. KIND 219 The KIND element is mapped onto the "kind" member (Figure 2). 220 Allowed values are those, except "group", described in section 6.1.4 221 of [RFC6350] and extended with the values declared in [RFC6473] and 222 [RFC6869]. A group of cards is represented through a JSCardGroup. 224 BEGIN:VCARD 225 VERSION:4.0 226 ... 227 KIND:individual 228 ... 229 END:VCARD 231 { 232 ... 233 "kind": "individual", 234 ... 235 } 237 Figure 2: KIND mapping example 239 2.1.4. XML 241 The XML property doesn't have a direct match with a JSCard feature. 243 2.2. Identification Properties 245 2.2.1. FN 247 All the FN elements are globally represented through the "fullName" 248 member. The presence of more than one name is implicitly associated 249 with the full name translations in various languages regardless of 250 the presence of the ALTID parameter. Each translation corresponds to 251 a different entry of the "localizations" map (Figure 3). 253 2.2.2. N and NICKNAME 255 Both the N and NICKNAME elements are converted into equivalent items 256 of the "name" array (Figure 3): 258 o the N components are transformed into related "NameComponent" 259 objects as reported in Table 1. Name components SHOULD be ordered 260 such that their values joined by whitespace produce a valid full 261 name of this entity; 263 o Each NICKNAME element is mapped onto an object whose "type" member 264 is set to "nickname" 266 +--------------------+--------------+ 267 | N component | "type" value | 268 +--------------------+--------------+ 269 | Honorific Prefixes | prefix | 270 | Given Names | personal | 271 | Family Names | surname | 272 | Additional Names | additional | 273 | Honorific Suffixes | suffix | 274 +--------------------+--------------+ 276 Table 1: N components mapping 278 BEGIN:VCARD 279 VERSION:4.0 280 ... 281 FN:Mr. John Q. Public\, Esq. 282 N:Public;John;Quinlan;Mr.;Esq. 283 NICKNAME:Johnny 284 ... 285 END:VCARD 287 { 288 ... 289 "fullName":{ 290 "value": "Mr. John Q. Public, Esq." 291 }, 292 "name":[ 293 { "value":"Mr.", "type": "prefix" }, 294 { "value":"John", "type": "personal" }, 295 { "value":"Public", "type": "surname" }, 296 { "value":"Quinlan", "type": "additional" }, 297 { "value":"Esq.", "type": "suffix" }, 298 { "value":"Johnny", "type": "nickname" } 299 ], 300 ... 301 } 303 Figure 3: FN, N, NICKNAME mapping example 305 2.2.3. PHOTO 307 A PHOTO element is represented as a "Resource" object in the "online" 308 array (Figure 4) whose "type" member is set to "uri" and "labels" map 309 contains the entry <"photo",true>. 311 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 312 and "mediaType" members respectively. 314 BEGIN:VCARD 315 VERSION:4.0 316 ... 317 PHOTO:http://www.example.com/pub/photos/jqpublic.gif 318 ... 319 END:VCARD 321 { 322 ... 323 "online":[ 324 ... 325 { 326 "type": "uri", 327 "labels": { "photo": true }, 328 "value": "http://www.example.com/pub/photos/jqpublic.gif" 329 }, 330 ... 331 ], 332 ... 333 } 335 Figure 4: PHOTO mapping example 337 2.2.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 339 The BDAY and ANNIVERSARY elements and the extensions BIRTHPLACE, 340 DEATHDATE, DEATHPLACE described in [RFC6350] are represented as 341 "Anniversary" objects included in the "anniversaries" array 342 (Figure 5): 344 o BDAY and BIRTHPLACE are mapped onto "date" and "place" where 345 "type" is set to "birth"; 347 o DEATHDATE and DEATHPLACE are mapped onto "date" and "place" where 348 "type" is set to "death"; 350 o ANNIVERSARY is mapped onto "date" where "type" is set to "other" 351 and "label" is set to a value describing in detail the kind of 352 anniversary (e.g. "marriage date" for the wedding anniversary). 354 Both birth and death places are represented as instances of the 355 "Address" object. BIRTHPLACE and DEATHPLACE that are represented as 356 geo URIs are converted into "Address" instances including only the 357 "coordinates" member. If the URI value is not a geo URI, the place 358 is ignored. The LANGUAGE parameter values of both BIRTHPLACE and 359 DEATHPLACE elements are represented as corresponding entries of the 360 "fullAddress.localizations" map. 362 BEGIN:VCARD 363 VERSION:4.0 364 ... 365 BDAY:19531015T231000Z 366 BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A. 367 DEATHDATE:19960415 368 DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A. 369 ANNIVERSARY:19860201 370 ... 371 END:VCARD 373 { 374 ... 375 "anniversaries":[ 376 { 377 "type": "birth", 378 "date": "19531015T231000Z", 379 "place": 380 { 381 "fullAddress": 382 { 383 "value": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A." 384 } 385 } 386 }, 387 { 388 "type": "birth", 389 "date": "19531015T231000Z", 390 "place": 391 { 392 "fullAddress": 393 { 394 "value": "4445 Courtright Street\nNew England, ND 58647\nU.S.A." 395 } 396 } 397 }, 398 { 399 "type": "other", 400 "label": "marriage date", 401 "date": "19860201" 402 } 403 ], 404 ... 405 } 407 Figure 5: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 408 mapping example 410 2.2.5. GENDER 412 TBD 414 2.3. Delivery Addressing Properties 416 2.3.1. ADR 418 An ADR element is represented as an "Address" object in the 419 "addresses" array (Figure 6). 421 The ADR components are transformed into the "Address" members as 422 reported in Table 2. 424 +------------------+----------------+ 425 | ADR component | Address member | 426 +------------------+----------------+ 427 | p.o. box | postOfficeBox | 428 | extended address | extension | 429 | street address | street | 430 | locality | locality | 431 | region | region | 432 | postal code | postcode | 433 | country name | country | 434 +------------------+----------------+ 436 Table 2: ADR components mapping 438 The LABEL parameter is converted into the "fullAddress" member. 440 The PREF parameter is converted into the "isPreferred" member. 442 The GEO parameter is converted into the "coordinates" member. 444 The TZ parameter is converted into by the "timeZone" member. 446 The TYPE parameter is converted into the "context" member. The 447 "home" value is replaced with the "private" value. 449 The LANGUAGE parameter values are represented as different entries of 450 the "fullAddress.localizations" map. 452 The CC parameter defined by [RFC8605] is converted into the 453 "countryCode" member. 455 BEGIN:VCARD 456 VERSION:4.0 457 ... 458 ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA 459 ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA 460 ... 461 END:VCARD 463 { 464 ... 465 "addresses": [ 466 { 467 "context": "work", 468 "fullAddress": 469 { 470 "value": "54321 Oak St\nReston\nVA\n20190\nUSA" 471 }, 472 "street": "54321 Oak St", 473 "locality": "Reston", 474 "region": "VA", 475 "country": "USA", 476 "postcode": "20190", 477 "countryCode": "US" 478 }, 479 { 480 "context": "private", 481 "fullAddress": 482 { 483 "value": "12345 Elm St\nReston\nVA\n20190\nUSA" 484 }, 485 "street": "12345 Elm St", 486 "locality": "Reston", 487 "region": "VA", 488 "country": "USA", 489 "postcode": "20190", 490 "countryCode": "US" 491 } 492 ] 493 ... 494 } 496 Figure 6: ADR mapping example 498 2.4. Communications Properties 499 2.4.1. TEL 501 A TEL element is represented as a "Resource" object in the "phones" 502 array (Figure 7). The vCard "type-param-tel" values are mapped onto 503 the "type" member values. Those vCard "type-param-tel" values that 504 don't have a counterpart among the "type" member values are 505 represented as entry keys of the "labels" map with the corresponding 506 entry value set to true. The "type-param" values are are mapped onto 507 the "context" member values. The "home" value is replaced with the 508 "private" value. 510 The PREF parameter is mapped onto the "isPreferred" member. 512 BEGIN:VCARD 513 VERSION:4.0 514 ... 515 TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555 516 TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67 517 ... 518 END:VCARD 520 { 521 ... 522 "phones":[ 523 { 524 "context": "private", 525 "type": "voice", 526 "value": "tel:+1-555-555-5555;ext=5555", 527 "isPreferred": true 528 }, 529 { 530 "context": "private", 531 "value": "tel:+33-01-23-45-67" 532 } 533 ], 534 ... 535 } 537 Figure 7: TEL mapping example 539 2.4.2. EMAIL 541 An EMAIL element is represented as a "Resource" object in the 542 "emails" array (Figure 8). The vCard "type-param" values are mapped 543 onto the "context" member values. The "home" value is replaced with 544 the "private" value. 546 The PREF parameter is mapped onto the "isPreferred" member. 548 BEGIN:VCARD 549 VERSION:4.0 550 ... 551 EMAIL;TYPE=work:jqpublic@xyz.example.com 552 EMAIL;PREF=1:jane_doe@example.com 553 ... 554 END:VCARD 556 { 557 ... 558 "emails":[ 559 { 560 "context": "work", 561 "value": "jqpublic@xyz.example.com", 562 }, 563 { 564 "context": "private", 565 "value": "jane_doe@example.com" 566 "isPreferred": true 567 } 568 ], 569 ... 570 } 572 Figure 8: EMAIL mapping example 574 2.4.3. IMPP 576 An IMPP element is represented as a "Resource" object in the "online" 577 array (Figure 9) whose "type" member is set to "username" and 578 "labels" map contains the entry <"XMPP",true>. 580 In case of a contact card related to an acconunt on another online 581 service, the entry key SHOULD be the canonical service name, 582 including capitalisation (e.g. "Twitter", "Facebook", "Skype", 583 "GitHub") 585 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 586 and "mediaType" members respectively. 588 BEGIN:VCARD 589 VERSION:4.0 590 ... 591 IMPP;PREF=1:xmpp:alice@example.com 592 ... 593 END:VCARD 595 { 596 ... 597 "online":[ 598 ... 599 { 600 "type": "username", 601 "labels": { "XMPP": true }, 602 "value": "alice@example.com" 603 }, 604 ... 605 ], 606 ... 607 } 609 Figure 9: IMPP mapping example 611 2.4.4. LANG 613 A LANG element is represented through the "preferredContactLanguages" 614 map (Figure 10): an entry for each language that may be used for 615 contacting the entity associated with the JSCard. The entry keys 616 correspond to the language tags, the corresponding entry values are 617 arrays of "ContactLanguage" objects. 619 The TYPE and PREF parameters are mapped onto the "ContactLanguage" 620 members "type" and "preference" respectively. 622 If both PREF and TYPE parameters are missing, the array of 623 "ContactLanguage" objects MUST be empty. 625 BEGIN:VCARD 626 VERSION:4.0 627 ... 628 LANG;TYPE=work;PREF=1:en 629 LANG;TYPE=work;PREF=2:fr 630 LANG;TYPE=home:fr 631 ... 632 END:VCARD 634 { 635 ... 636 "preferredContactLanguages" : { 637 "en": [ 638 { 639 "type": "work", 640 "preference": 1 641 } 642 ], 643 "fr": [ 644 { 645 "type": "work", 646 "preference": 2 647 }, 648 { 649 "type": "home", 650 } 651 ] 652 }, 653 ... 654 } 656 Figure 10: LANG mapping example 658 2.5. Geographical Properties 660 The GEO and TZ elements are not directly mapped into equivalent 661 topmost JSCard members because the same information is represented 662 through equivalent "Address" members. 664 The ALTID parameter is used for associating both GEO and TZ elements 665 with the related address information. When the ALTID parameter is 666 missing, the element should be associated with the first contact 667 address. 669 2.6. Organizational Properties 671 2.6.1. TITLE 673 A TITLE element is mapped onto a "LocalizedString" object included in 674 the "jobTitle" array (Figure 11). 676 The ALTID parameter is used for for associating the language- 677 dependent alternatives with a given element. 679 The LANGUAGE parameter values are represented as corresponding 680 entries of the "localizations" map. 682 BEGIN:VCARD 683 VERSION:4.0 684 ... 685 TITLE:Research Scientist 686 ... 687 END:VCARD 689 { 690 ... 691 "jobTitle":[ 692 { 693 "value": "Research Scientist" 694 } 695 ], 696 ... 697 } 699 Figure 11: TITLE mapping example 701 2.6.2. ROLE 703 A ROLE element is mapped onto a "LocalizedString" object included in 704 the "role" array (Figure 12). 706 The ALTID parameter is used for for associating the language- 707 dependent alternatives with a given element. 709 The LANGUAGE parameter values are represented as corresponding 710 entries of the "localizations" map. 712 BEGIN:VCARD 713 VERSION:4.0 714 ... 715 ROLE:Project Leader 716 ... 717 END:VCARD 719 { 720 ... 721 "role":[ 722 { 723 "value": "Project Leader" 724 } 725 ], 726 ... 727 } 729 Figure 12: ROLE mapping example 731 2.6.3. LOGO 733 A LOGO element is represented as a "Resource" object in the "online" 734 array (Figure 13) whose "type" member is set to "uri" and "labels" 735 map contains the entry <"logo",true>. 737 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 738 and "mediaType" members respectively. 740 BEGIN:VCARD 741 VERSION:4.0 742 ... 743 LOGO:http://www.example.com/pub/logos/abccorp.jpg 744 ... 745 END:VCARD 747 { 748 ... 749 "online":[ 750 ... 751 { 752 "type": "uri", 753 "labels": { "logo": true }, 754 "value": "http://www.example.com/pub/logos/abccorp.jpg" 755 }, 756 ... 757 ], 758 ... 759 } 761 Figure 13: LOGO mapping example 763 2.6.4. ORG 765 An ORG element is mapped onto a "LocalizedString" object included in 766 the "organization" array (Figure 14). The organization name includes 767 the organizational units if any. 769 The ALTID parameter is used for for associating the language- 770 dependent alternatives with a given element. 772 The LANGUAGE parameter values are represented as corresponding 773 entries of the "localizations" map. 775 BEGIN:VCARD 776 VERSION:4.0 777 ... 778 ORG:ABC\, Inc.;North American Division;Marketing 779 ... 780 END:VCARD 782 { 783 ... 784 "organization":[ 785 { 786 "value": "ABC, Inc.;North American Division;Marketing" 787 } 788 ], 789 ... 790 } 792 Figure 14: ORG mapping example 794 2.6.5. MEMBER 796 According to the JSContact specification, a group of contact cards is 797 represented through a JSCardGroup (Figure 15). The contact cards 798 composing the group are included in the "cards" array. Therefore, 799 the MEMBER element doesn't have a direct match with a JSCard feature. 801 BEGIN:VCARD 802 VERSION:4.0 803 KIND:group 804 FN:The Doe family 805 MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 806 MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 807 END:VCARD 808 BEGIN:VCARD 809 VERSION:4.0 810 FN:John Doe 811 UID:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 812 END:VCARD 813 BEGIN:VCARD 814 VERSION:4.0 815 FN:Jane Doe 816 UID:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 817 END:VCARD 819 { 820 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 821 "name": "The Doe family", 822 "cards": [ 823 { 824 "name": { 825 "fullName": { 826 "value": "John Doe" 827 } 828 }, 829 "uid": "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af" 830 }, 831 { 832 "name": { 833 "fullName": { 834 "value": "Jane Doe" 835 } 836 }, 837 "uid": "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519f" 838 } 839 ] 840 } 842 Figure 15: Group example 844 2.6.6. RELATED 846 All the RELATED elements are globally converted into the "relatedTo" 847 map (Figure 16): an entry for each entity the entity described by the 848 JSCard is associated with. The map keys are the "uid" values of the 849 associated cards. 851 Each map value is a "Relation" object including only the "relation" 852 member represented as a set of relation types described in section 853 6.6.6 of [RFC6350]. 855 If the relation type is unspecified, the "relation" is empty. 857 BEGIN:VCARD 858 VERSION:4.0 859 ... 860 RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 861 RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf 862 RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries. 863 ... 864 END:VCARD 866 { 867 ... 868 "relatedTo":{ 869 { 870 "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6": 871 { 872 "relation": { 873 "friend": true 874 } 875 } 876 }, 877 { 878 "http://example.com/directory/jdoe.vcf": 879 { 880 "relation": { 881 "contact": true 882 } 883 } 884 }, 885 { 886 "Please contact my assistant Jane Doe for any inquiries.": 887 { 888 "relation": { } 889 } 890 } 891 } 892 ... 893 } 895 Figure 16: RELATED mapping example 897 2.6.7. CONTACT-URI 899 A CONTACT-URI element defined by [RFC8605] is represented as a 900 "Resource" object of the "online" array (Figure 17) whose "type" 901 member is set to "uri" and "labels" map contains the entry <"contact- 902 uri",true>. 904 The PREF parameter is mapped onto the "isPreferred" member. 906 BEGIN:VCARD 907 VERSION:4.0 908 ... 909 CONTACT-URI;PREF=1:mailto:contact@example.com 910 ... 911 END:VCARD 913 { 914 ... 915 "online":[ 916 ... 917 { 918 "type": "uri", 919 "labels": { "contact-uri": true }, 920 "value": "mailto:contact@example.com", 921 "isPreferred": true 922 }, 923 ... 924 ], 925 ... 926 } 928 Figure 17: CONTACT-URI mapping example 930 2.7. Personal Information Properties 932 2.7.1. EXPERTISE 934 An EXPERTISE element defined by [RFC6715] is represented as a 935 "PersonalInformation" object in the "personalInfo" array (Figure 18). 936 The "type" member is set to "expertise". 938 The LEVEL parameter is mapped onto the "level" member with following 939 mapping: 941 o "beginner" is converted into "low"; 942 o "average" is converted into "medium"; 943 o "expert" is converted into "high". 945 The INDEX parameter is represented as the index of the expertise 946 among the declared expertises. 948 BEGIN:VCARD 949 VERSION:4.0 950 ... 951 EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature 952 EXPERTISE;INDEX=1;LEVEL=expert:chemistry 953 ... 954 END:VCARD 956 { 957 ... 958 "personalInfo":[ 959 ... 960 { 961 "type": "expertise", 962 "value": "chemistry", 963 "level": "high" 964 }, 965 { 966 "type": "expertise", 967 "value": "chinese literature", 968 "level": "low" 969 } 970 ... 971 ] 972 ... 973 } 975 Figure 18: EXPERTISE mapping example 977 2.7.2. HOBBY 979 An HOBBY element defined by [RFC6715] is represented as a 980 "PersonalInformation" object in the "personalInfo" array (Figure 19). 981 The "type" member is set to "hobby". 983 The LEVEL parameter is mapped onto the "level" member with a direct 984 mapping. 986 The INDEX parameter is represented as the index of the hobby among 987 the declared hobbies. 989 BEGIN:VCARD 990 VERSION:4.0 991 ... 992 HOBBY;INDEX=1;LEVEL=high:reading 993 HOBBY;INDEX=2;LEVEL=high:sewing 994 ... 995 END:VCARD 997 { 998 ... 999 "personalInfo":[ 1000 ... 1001 { 1002 "type": "hobby", 1003 "value": "reading", 1004 "level": "high" 1005 }, 1006 { 1007 "type": "hobby", 1008 "value": "sewing", 1009 "level": "high" 1010 } 1011 ... 1012 ] 1013 ... 1014 } 1016 Figure 19: HOBBY mapping example 1018 2.7.3. INTEREST 1020 An INTEREST element defined by [RFC6715] is represented as a 1021 "PersonalInformation" object in the "personalInfo" array (Figure 20). 1022 The "type" member is set to "interest". 1024 The LEVEL parameter is mapped onto the "level" member with a direct 1025 mapping. 1027 The INDEX parameter is represented as the index of the interest among 1028 the declared interests. 1030 BEGIN:VCARD 1031 VERSION:4.0 1032 ... 1033 INTEREST;INDEX=1;LEVEL=medium:r&b music 1034 INTEREST;INDEX=2;LEVEL=high:rock 'n' roll music 1035 ... 1036 END:VCARD 1038 { 1039 ... 1040 "personalInfo":[ 1041 ... 1042 { 1043 "type": "interest", 1044 "value": "r&b music", 1045 "level": "medium" 1046 }, 1047 { 1048 "type": "interest", 1049 "value": "rock 'n' roll music", 1050 "level": "high" 1051 } 1052 ... 1053 ] 1054 ... 1055 } 1057 Figure 20: INTEREST mapping example 1059 2.7.4. ORG-DIRECTORY 1061 An ORG-DIRECTORY element is represented as a "Resource" object in the 1062 "online" array (Figure 21) whose "type" member is set to "uri" and 1063 "labels" map contains the entry <"org-directory",true>. 1065 The PREF parameter is mapped onto the "isPreferred" member. 1067 The INDEX parameter is represented as the index of the directory 1068 among the online resources with the "org-directory" key in the 1069 "labels" map. 1071 BEGIN:VCARD 1072 VERSION:4.0 1073 ... 1074 ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com 1075 ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering 1076 ... 1077 END:VCARD 1079 { 1080 ... 1081 "online":[ 1082 ... 1083 { 1084 "type": "uri", 1085 "labels": { "org-directory": true }, 1086 "value": "http://directory.mycompany.example.com" 1087 }, 1088 { 1089 "type": "uri", 1090 "labels": { "org-directory": true }, 1091 "value": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering", 1092 "isPreferred": true 1093 }, 1094 ... 1095 ], 1096 ... 1097 } 1099 Figure 21: ORG-DIRECTORY mapping example 1101 2.8. Explanatory Properties 1103 2.8.1. CATEGORIES 1105 A CATEGORIES element is converted into an object in the "categories" 1106 array (Figure 22). 1108 BEGIN:VCARD 1109 VERSION:4.0 1110 ... 1111 CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY 1112 ... 1113 END:VCARD 1115 { 1116 ... 1117 "categories":[ 1118 "INTERNET", 1119 "IETF", 1120 "INDUSTRY", 1121 "INFORMATION TECHNOLOGY" 1122 ] 1123 ... 1124 } 1126 Figure 22: CATEGORIES mapping example 1128 2.8.2. NOTE 1130 A NOTE element is mapped onto a "LocalizedString" object included in 1131 the "notes" array (Figure 23). 1133 The ALTID parameter is used for associating the language-dependent 1134 alternatives with a given element. 1136 The LANGUAGE parameter values are represented as corresponding 1137 entries of the "localizations" map. 1139 BEGIN:VCARD 1140 VERSION:4.0 1141 ... 1142 NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri. 1143 ... 1144 END:VCARD 1146 { 1147 ... 1148 "notes":[ 1149 { 1150 "value": "This fax number is operational 0800 to 1715 EST, Mon-Fri." 1151 } 1152 ] 1153 ... 1154 } 1156 Figure 23: NOTE mapping example 1158 2.8.3. PRODID 1160 The PRODID element is converted into the "prodId" member (Figure 24). 1162 BEGIN:VCARD 1163 VERSION:4.0 1164 ... 1165 PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN 1166 ... 1167 END:VCARD 1169 { 1170 ... 1171 "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN" 1172 ... 1173 } 1175 Figure 24: PRODID mapping example 1177 2.8.4. REV 1179 The REV element is transformed into the "updated" member (Figure 25). 1181 BEGIN:VCARD 1182 VERSION:4.0 1183 ... 1184 REV:19951031T222710Z 1185 ... 1186 END:VCARD 1188 { 1189 ... 1190 "updated": "19951031T222710Z" 1191 ... 1192 } 1194 Figure 25: REV mapping example 1196 2.8.5. SOUND 1198 A SOUND element is represented as a "Resource" object in the "online" 1199 array (Figure 26) whose "type" member is set to "uri" and "labels" 1200 map contains the entry <"sound",true>. 1202 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 1203 and "mediaType" members respectively. 1205 BEGIN:VCARD 1206 VERSION:4.0 1207 ... 1208 SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com 1209 ... 1210 END:VCARD 1212 { 1213 ... 1214 "online":[ 1215 ... 1216 { 1217 "type": "uri", 1218 "labels": { "sound": true }, 1219 "value": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com" 1220 }, 1221 ... 1222 ], 1223 ... 1224 } 1226 Figure 26: SOUND mapping example 1228 2.8.6. UID 1230 The UID element corresponds to the "uid" member (Figure 27). 1232 BEGIN:VCARD 1233 VERSION:4.0 1234 ... 1235 UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 1236 ... 1237 END:VCARD 1239 { 1240 ... 1241 "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6" 1242 ... 1243 } 1245 Figure 27: UID mapping example 1247 2.8.7. CLIENTPIDMAP and PID Parameter 1249 TBD 1251 2.8.8. URL 1253 An URL element is represented as a "Resource" object in the "online" 1254 array (Figure 28) whose "type" member is set to "uri" and "labels" 1255 map contains the entry <"url",true>. 1257 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 1258 and "mediaType" members respectively. 1260 BEGIN:VCARD 1261 VERSION:4.0 1262 ... 1263 URL:http://example.org/restaurant.french/~chezchic.html 1264 ... 1265 END:VCARD 1267 { 1268 ... 1269 "online":[ 1270 ... 1271 { 1272 "type": "uri", 1273 "labels": { "url": true }, 1274 "value": "http://example.org/restaurant.french/~chezchic.html" 1275 }, 1276 ... 1277 ], 1278 ... 1279 } 1281 Figure 28: URL mapping example 1283 2.8.9. VERSION 1285 The VERSION property doesn't have a direct match with a JSCard 1286 feature. 1288 2.9. Security Properties 1290 2.9.1. KEY 1292 A KEY element is represented as a "Resource" object in the "online" 1293 array (Figure 29) whose "type" member is set to "uri" and "labels" 1294 map contains the entry <"key",true>. 1296 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 1297 and "mediaType" members respectively. 1299 BEGIN:VCARD 1300 VERSION:4.0 1301 ... 1302 KEY:http://www.example.com/keys/jdoe.cer 1303 ... 1304 END:VCARD 1306 { 1307 ... 1308 "online":[ 1309 ... 1310 { 1311 "type": "uri", 1312 "labels": { "key": true }, 1313 "value": "http://www.example.com/keys/jdoe.cer" 1314 }, 1315 ... 1316 ], 1317 ... 1318 } 1320 Figure 29: KEY mapping example 1322 2.10. Calendar Properties 1324 2.10.1. FBURL 1326 A FBURL element is represented as a "Resource" object of the "online" 1327 array (Figure 30) whose "type" member is set to "uri" and "labels" 1328 map contains the entry <"fburl",true>. 1330 The PREF and MEDIATYPE parameters are mapped ontoy the "isPreferred" 1331 and "mediaType" members respectively. 1333 BEGIN:VCARD 1334 VERSION:4.0 1335 ... 1336 FBURL;PREF=1:http://www.example.com/busy/janedoe 1337 FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb 1338 ... 1339 END:VCARD 1341 { 1342 ... 1343 "online":[ 1344 ... 1345 { 1346 "type": "uri", 1347 "labels": { "fburl": true }, 1348 "value": "http://www.example.com/busy/janedoe", 1349 "isPreferred": true 1350 }, 1351 { 1352 "type": "uri", 1353 "labels": { "fburl": true }, 1354 "value": "ftp://example.com/busy/project-a.ifb", 1355 "mediaType": "text/calendar" 1356 }, 1357 ... 1358 ], 1359 ... 1360 } 1362 Figure 30: FBURL mapping example 1364 2.10.2. CALADRURI 1366 A CALADRURI element is represented as a "Resource" object of the 1367 "online" array (Figure 31) whose "type" member is set to "uri" and 1368 "labels" map contains the entry <"caladruri",true>. 1370 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 1371 and "mediaType" members respectively. 1373 BEGIN:VCARD 1374 VERSION:4.0 1375 ... 1376 CALADRURI;PREF=1:mailto:janedoe@example.com 1377 CALADRURI:http://example.com/calendar/jdoe 1378 ... 1379 END:VCARD 1381 { 1382 ... 1383 "online":[ 1384 ... 1385 { 1386 "type": "uri", 1387 "labels": { "caladruri": true }, 1388 "value": "mailto:janedoe@example.com", 1389 "isPreferred": true 1390 }, 1391 { 1392 "type": "uri", 1393 "labels": { "caladruri": true }, 1394 "value": "http://example.com/calendar/jdoe" 1395 }, 1396 ... 1397 ], 1398 ... 1399 } 1401 Figure 31: CALADRURI mapping example 1403 2.10.3. CALURI 1405 A CALURI element is represented as a "Resource" object of the 1406 "online" array (Figure 32) whose "type" member is set to "uri" and 1407 "labels" map contains the entry <"caluri",true>. 1409 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 1410 and "mediaType" members respectively. 1412 BEGIN:VCARD 1413 VERSION:4.0 1414 ... 1415 CALURI;PREF=1:http://cal.example.com/calA 1416 CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics 1417 ... 1418 END:VCARD 1420 { 1421 ... 1422 "online":[ 1423 ... 1424 { 1425 "type": "uri", 1426 "labels": { "caluri": true }, 1427 "value": "http://cal.example.com/calA", 1428 "isPreferred": true 1429 }, 1430 { 1431 "type": "uri", 1432 "labels": { "caluri": true }, 1433 "value": "ftp://ftp.example.com/calA.ics", 1434 "mediaType": "text/calendar" 1435 }, 1436 ... 1437 ], 1438 ... 1439 } 1441 Figure 32: CALURI mapping example 1443 2.11. Additional Clarifications about Mapping 1445 2.11.1. Media type 1447 As described in section 5.7 of [RFC6350], the media type of a 1448 resource can be identified by its URI. For example, "image/gif" can 1449 be derived from the ".gif" extension of a GIF image URI. JSContact 1450 producers MAY provide the media type information even when it is not 1451 specified in the vCard. 1453 2.11.2. Timezone 1455 As specified in section 6.5.1 of [RFC6350], the time zone information 1456 can be represented in three ways: as a time zone name, as an UTC 1457 offset or as an URI. 1459 o The time zone name is directly matched by the "timeZone" member in 1460 JSContact. 1462 o An UTC offset MUST be converted into the related "Etc/GMT" time 1463 zone (e.g. the value "-0500" converts to "Etc/GMT+5"). If the UTC 1464 offset value contains minutes information, it MUST be mapped to 1465 map it to the zone "Etc/GMT:". 1467 o Since there is no URI scheme defined for time zones [uri-schemes], 1468 any implementation that does use some a custom URI for a time zone 1469 is not interoperable anyway. In this case, if the URI corresponds 1470 to an a IANA time zone [time-zones], this latter SHOULD be used. 1471 Otherwise, the URI value is dumped into a string. 1473 2.12. Extended Properties 1475 If an extended property is a resource, JSCard already allows to 1476 represent it by setting the "type" member to "other" and specifying a 1477 value for the "labels" map. 1479 Any other property supporting a custom feature MAY be added and its 1480 name MUST be prefixed with a specific domain name to avoid conflict, 1481 e.g. "example.com/customprop". 1483 2.13. vCard Unmatched Properties 1485 Any vCard property or parameter that doesn't have a direct 1486 counterpart in JSContact is treated as an extended property. The 1487 following mapping rules MUST be applied: 1489 o an unmatched property is converted into an extended property whose 1490 name is prefixed by "ietf.org/rfc6350/" 1492 o an unmatched parameter is converted into an extended property 1493 whose name is prefixed by "ietf.org/rfc6350//" 1495 In both cases, the resulting names MUST be in lowercase. 1497 2.14. JSCard Required Properties 1499 While converting a vCard into a JSCard, only the topmost "uid" member 1500 is required. 1502 2.15. JSCard Unmatched Properties 1504 The "preferredContactMethod" member doesn't match any vCard element. 1506 3. IANA Considerations 1508 This document has no actions for IANA. 1510 4. Security Considerations 1512 This document doesn't report any security consideration. 1514 5. References 1516 5.1. Normative References 1518 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1519 Requirement Levels", BCP 14, RFC 2119, 1520 DOI 10.17487/RFC2119, March 1997, 1521 . 1523 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 1524 DOI 10.17487/RFC6350, August 2011, 1525 . 1527 [RFC6473] Saint-Andre, P., "vCard KIND:application", RFC 6473, 1528 DOI 10.17487/RFC6473, December 2011, 1529 . 1531 [RFC6474] Li, K. and B. Leiba, "vCard Format Extensions: Place of 1532 Birth, Place and Date of Death", RFC 6474, 1533 DOI 10.17487/RFC6474, December 2011, 1534 . 1536 [RFC6715] Cauchie, D., Leiba, B., and K. Li, "vCard Format 1537 Extensions: Representing vCard Extensions Defined by the 1538 Open Mobile Alliance (OMA) Converged Address Book (CAB) 1539 Group", RFC 6715, DOI 10.17487/RFC6715, August 2012, 1540 . 1542 [RFC6869] Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard 1543 KIND:device", RFC 6869, DOI 10.17487/RFC6869, February 1544 2013, . 1546 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 1547 DOI 10.17487/RFC7095, January 2014, 1548 . 1550 [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: 1551 ICANN Extensions for the Registration Data Access Protocol 1552 (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, 1553 . 1555 5.2. Informative References 1557 [draft-ietf-jmap-jscontact] 1558 "JSContact: A JSON representation of contact data", 1559 . 1562 [time-zones] 1563 "Time Zone Database", . 1565 [uri-schemes] 1566 "Uniform Resource Identifier (URI) Schemes", 1567 . 1570 Authors' Addresses 1572 Mario Loffredo 1573 IIT-CNR/Registro.it 1574 Via Moruzzi,1 1575 Pisa 56124 1576 IT 1578 Email: mario.loffredo@iit.cnr.it 1579 URI: http://www.iit.cnr.it 1581 Robert Stepanek 1582 FastMail 1583 PO Box 234, Collins St West 1584 Melbourne VIC 8007 1585 AU 1587 Email: rsto@fastmailteam.com 1588 URI: https://www.fastmail.com