idnits 2.17.1 draft-loffredo-jmap-jscontact-vcard-02.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 (March 28, 2020) is 1488 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC6474' is defined on line 1467, but no explicit reference was found in the text == Unused Reference: 'RFC8259' is defined on line 1486, but no explicit reference was found in the text Summary: 1 error (**), 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: Informational R. Stepanek 5 Expires: September 29, 2020 FastMail 6 March 28, 2020 8 JSContact: Converting from and to vCard 9 draft-loffredo-jmap-jscontact-vcard-02 11 Abstract 13 This document provides an 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 September 29, 2020. 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 . . . . . . . . . . . . . . . . 15 76 2.6.1. TITLE . . . . . . . . . . . . . . . . . . . . . . . . 15 77 2.6.2. ROLE . . . . . . . . . . . . . . . . . . . . . . . . 16 78 2.6.3. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 17 79 2.6.4. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 17 80 2.6.5. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 18 81 2.6.6. RELATED . . . . . . . . . . . . . . . . . . . . . . . 19 82 2.6.7. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 21 83 2.7. Personal Information Properties . . . . . . . . . . . . . 21 84 2.7.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 21 85 2.7.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 22 86 2.7.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 23 87 2.7.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 24 88 2.8. Explanatory Properties . . . . . . . . . . . . . . . . . 25 89 2.8.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 25 90 2.8.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 26 91 2.8.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 27 92 2.8.4. REV . . . . . . . . . . . . . . . . . . . . . . . . . 27 93 2.8.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . . 27 94 2.8.6. UID . . . . . . . . . . . . . . . . . . . . . . . . . 28 95 2.8.7. PID Parameter and CLIENTPIDMAP . . . . . . . . . . . 29 96 2.8.8. URL . . . . . . . . . . . . . . . . . . . . . . . . . 29 97 2.8.9. VERSION . . . . . . . . . . . . . . . . . . . . . . . 29 98 2.9. Security Properties . . . . . . . . . . . . . . . . . . . 29 99 2.9.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . . 30 100 2.10. Calendar Properties . . . . . . . . . . . . . . . . . . . 30 101 2.10.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 30 102 2.10.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 31 103 2.10.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 32 104 2.11. Extended Properties . . . . . . . . . . . . . . . . . . . 33 105 2.12. JSCard Required Properties . . . . . . . . . . . . . . . 33 106 2.13. JSCard Unmatched Properties . . . . . . . . . . . . . . . 34 107 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 108 4. Security Considerations . . . . . . . . . . . . . . . . . . . 34 109 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 110 5.1. Normative References . . . . . . . . . . . . . . . . . . 34 111 5.2. Informative References . . . . . . . . . . . . . . . . . 35 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 114 1. Introduction 116 1.1. Motivation 118 The JSContact specification ([draft-ietf-jmap-jscontact]) has been 119 defined to represent contact card information as a more efficient 120 alternative to vCard ([RFC6350]) and its JSON format named jCard 121 ([RFC7095]). 123 While new applications might adopt JSContact as their main format to 124 exchange contact card data, they are likely to interoperate with 125 services and clients that just support vCard/jCard. Similarly, 126 existing contact data providers and consumers already using vCard/ 127 jCard might want to represent their data also according to the 128 JSContact specification. 130 To facilitate this use cases, this document provides an informational 131 guidance about how to convert the card defined in JSContact, namely 132 JSCard, from and to vCard. 134 1.2. Scope and Caveats 136 JSContact and vCard have a lot of semantics in common, however some 137 differences must be outlined: 139 o The JSContact data model defines some contact information that 140 doesn't have a direct mapping with vCard elements. 142 o The vCard specification includes some features (like parameters) 143 that have been formally removed from JSCard due to a complete 144 refactoring of vCard content. Anyway, the vCard parameters may 145 appear as JSCard properties. 147 o Some vCard elements represented individually have been modeled as 148 members of JSCard elements. 150 o The vCard custom elements, identified by the prefix "x-", don't 151 have a direct counterpart in the JSContact specification. 153 1.3. Conventions Used in This Document 155 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 156 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 157 document are to be interpreted as described in [RFC2119]. 159 2. Mapping 161 This section contains the mapping between vCard and JSCard. The 162 vCard properties are grouped according to the categories defined by 163 [RFC6350]. 165 2.1. General Properties 167 2.1.1. BEGIN and END 169 The vCard BEGIN and END elements don't have a direct match with 170 corresponding JSCard elements. 172 2.1.2. SOURCE 174 The vCard SOURCE element is represented in JSCard as a "Resource" 175 item of the "online" array (Figure 1). In the "Resource" item, the 176 "type" member is set to "uri" as well as a key of the "labels" is set 177 to "source". 179 The PREF and MEDIATYPE parameters can be represented by the 180 "isPreferred" and "mediaType" properties respectively. 182 BEGIN:VCARD 183 VERSION:4.0 184 ... 185 SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf 186 ... 187 END:VCARD 189 { 190 ... 191 "online":[ 192 ... 193 { 194 "type": "uri", 195 "labels": { "source": true }, 196 "value": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf" 197 }, 198 ... 199 ], 200 ... 201 } 203 Figure 1: SOURCE mapping example 205 2.1.3. KIND 207 The vCard KIND element is mapped onto the JSCard "kind" property 208 (Figure 2). Such property can contain one of the values, except 209 "group", described in section 6.1.4 of [RFC6350] and extended with 210 the values declared in [RFC6473] and [RFC6869]. A group of cards is 211 represented by a dedicated object named JSCardGroup. 213 BEGIN:VCARD 214 VERSION:4.0 215 ... 216 KIND:individual 217 ... 218 END:VCARD 220 { 221 ... 222 "kind": "individual", 223 ... 224 } 226 Figure 2: KIND mapping example 228 2.1.4. XML 230 The vCard XML element doesn't have a direct match with a 231 corresponding JSCard element. 233 2.2. Identification Properties 235 2.2.1. FN 237 FN is converted into the "fullName" property. The presence of more 238 than one name is implicitly associated with the translation of the 239 full name in various languages. Each translation corresponds to a 240 different entry of the "localizations" map that is an optional member 241 of the "fullName" object (Figure 3). 243 2.2.2. N and NICKNAME 245 The vCard elements N and NICKNAME are converted into equivalent items 246 of the JSCard "name" array (Figure 3): 248 o the N components are transformed into related JSCard 249 "NameComponent" items as reported in Table 1; an item for each 250 name component. Name components SHOULD be ordered such that their 251 values joined by whitespace produce a valid full name of this 252 entity; 254 o NICKNAME is mapped onto an item whose "type" is "nickname"; an 255 item for each nickname. 257 +--------------------+--------------+ 258 | N component | "type" value | 259 +--------------------+--------------+ 260 | Honorific Prefixes | prefix | 261 | Given Names | personal | 262 | Family Names | surname | 263 | Additional Names | additional | 264 | Honorific Suffixes | suffix | 265 +--------------------+--------------+ 267 Table 1: N components mapping 269 BEGIN:VCARD 270 VERSION:4.0 271 ... 272 FN:Mr. John Q. Public\, Esq. 273 N:Public;John;Quinlan;Mr.;Esq. 274 NICKNAME:Johnny 275 ... 276 END:VCARD 278 { 279 ... 280 "fullName":{ 281 "value": "Mr. John Q. Public, Esq." 282 }, 283 "name":[ 284 { "value":"Mr.", "type": "prefix" }, 285 { "value":"John", "type": "personal" }, 286 { "value":"Public", "type": "surname" }, 287 { "value":"Quinlan", "type": "additional" }, 288 { "value":"Esq.", "type": "suffix" }, 289 { "value":"Johnny", "type": "nickname" } 290 ], 291 ... 292 } 294 Figure 3: FN, N, NICKNAME mapping example 296 2.2.3. PHOTO 298 The vCard PHOTO element is represented in JSCard as a "Resource" item 299 of the "online" array (Figure 4). In the "Resource" item, the "type" 300 member is set to "uri" as well as a key of the "labels" is set to 301 "photo". 303 The PREF and MEDIATYPE parameters can be represented by the 304 "isPreferred" and "mediaType" properties respectively. 306 BEGIN:VCARD 307 VERSION:4.0 308 ... 309 PHOTO:http://www.example.com/pub/photos/jqpublic.gif 310 ... 311 END:VCARD 313 { 314 ... 315 "online":[ 316 ... 317 { 318 "type": "uri", 319 "labels": { "photo": true }, 320 "value": "http://www.example.com/pub/photos/jqpublic.gif" 321 }, 322 ... 323 ], 324 ... 325 } 327 Figure 4: PHOTO mapping example 329 2.2.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 331 The vCard BDAY and ANNIVERSARY elements and the vCard extensions 332 BIRTHPLACE, DEATHDATE, DEATHPLACE described in [RFC6350] are 333 represented in JSCard as "Anniversary" items of the "anniversaries" 334 array (Figure 5): 336 o BDAY and BIRTHPLACE are mapped onto "date" and "place" where 337 "type" is set to "birth" 339 o DEATHDATE and DEATHPLACE are mapped onto "date" and "place" where 340 "type" is set to "death" 342 o ANNIVERSARY is mapped onto "date" where "type" is set to "other" 343 and "label" is set to a value describing in detail the kind of 344 anniversary (e.g. "marriage date" for the wedding anniversary). 346 Both birth and death places are represented as instances of the 347 Address object. The LANGUAGE parameter values of both BIRTHPLACE and 348 DEATHPLACE elements can be expressed as corresponding entries of the 349 "localizations" map included in the "fullAddress" object. 351 BEGIN:VCARD 352 VERSION:4.0 353 ... 354 BDAY:19531015T231000Z 355 BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A. 356 DEATHDATE:19960415 357 DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A. 358 ANNIVERSARY:19860201 359 ... 360 END:VCARD 362 { 363 ... 364 "anniversaries":[ 365 { 366 "type": "birth", 367 "date": "19531015T231000Z", 368 "place": 369 { 370 "fullAddress": 371 { 372 "value": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A." 373 } 374 } 375 }, 376 { 377 "type": "birth", 378 "date": "19531015T231000Z", 379 "place": 380 { 381 "fullAddress": 382 { 383 "value": "4445 Courtright Street\nNew England, ND 58647\nU.S.A." 384 } 385 } 386 }, 387 { 388 "type": "other", 389 "label": "marriage date", 390 "date": "19860201" 391 } 392 ], 393 ... 394 } 396 Figure 5: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 397 mapping example 399 2.2.5. GENDER 401 TBD 403 2.3. Delivery Addressing Properties 405 2.3.1. ADR 407 The vCard ADR element is represented in JSCard as an "Address" item 408 of the "addresses" array (Figure 6). 410 The ADR components are transformed into the "Address" properties as 411 reported in Table 2. 413 +------------------+------------------+ 414 | ADR component | Address property | 415 +------------------+------------------+ 416 | p.o. box | postOfficeBox | 417 | extended address | extension | 418 | street address | street | 419 | locality | locality | 420 | region | region | 421 | postal code | postcode | 422 | country name | country | 423 +------------------+------------------+ 425 Table 2: ADR components mapping 427 The LABEL parameter is converted into the "fullAddress" property. 429 The PREF parameter is converted into the "isPreferred" property. 431 The GEO parameter is converted into the "coordinates" property. 433 The TZ parameter is converted into by the "timeZone" property. 435 The TYPE parameter is converted into the "context" property. The 436 "home" value is replaced by the "private" value. 438 The LANGUAGE parameter values can be represented as different entries 439 of the "localizations" map that is an optional member of the 440 "fullAddress" object. 442 The CC parameter defined by [RFC8605] is converted into the 443 "countryCode" property. 445 BEGIN:VCARD 446 VERSION:4.0 447 ... 448 ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA 449 ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA 450 ... 451 END:VCARD 453 { 454 ... 455 "addresses": [ 456 { 457 "context": "work", 458 "fullAddress": 459 { 460 "value": "54321 Oak St\nReston\nVA\n20190\USA" 461 }, 462 "street": "54321 Oak St", 463 "locality": "Reston", 464 "region": "VA", 465 "country": "USA", 466 "postcode": "20190", 467 "countryCode": "US" 468 }, 469 { 470 "context": "private", 471 "fullAddress": 472 { 473 "value": "12345 Elm St\nReston\nVA\n20190\USA" 474 }, 475 "street": "12345 Elm St", 476 "locality": "Reston", 477 "region": "VA", 478 "country": "USA", 479 "postcode": "20190", 480 "countryCode": "US" 481 } 482 ] 483 ... 484 } 486 Figure 6: ADR mapping example 488 2.4. Communications Properties 489 2.4.1. TEL 491 The vCard TEL element is represented in JSCard as a "Resource" item 492 of the "phones" array (Figure 7). The vCard "type-param-tel" values 493 are represented by the "type" member. Those vCard "type-param-tel" 494 values which don't have a counterpart in the "type" member values are 495 represented as keys of the "labels" map. The "type-param" values are 496 represented by the "context" member. The "home" value is replaced by 497 the "private" value. 499 The PREF parameter can be represented by the "isPreferred" member. 501 BEGIN:VCARD 502 VERSION:4.0 503 ... 504 TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555 505 TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67 506 ... 507 END:VCARD 509 { 510 ... 511 "phones":[ 512 { 513 "context": "private", 514 "type": "voice", 515 "value": "tel:+1-555-555-5555;ext=5555", 516 "isPreferred": true 517 }, 518 { 519 "context": "private", 520 "value": "tel:+33-01-23-45-67" 521 } 522 ], 523 ... 524 } 526 Figure 7: TEL mapping example 528 2.4.2. EMAIL 530 The vCard EMAIL element is represented in JSCard as a "Resource" item 531 of the "emails" array (Figure 8). The vCard "type-param" values are 532 represented by the "context" member. The "home" value is replaced by 533 the "private" value. 535 The PREF parameter can be represented by the "isPreferred" member. 537 BEGIN:VCARD 538 VERSION:4.0 539 ... 540 EMAIL;TYPE=work:jqpublic@xyz.example.com 541 EMAIL;PREF=1:jane_doe@example.com 542 ... 543 END:VCARD 545 { 546 ... 547 "emails":[ 548 { 549 "context": "work", 550 "value": "jqpublic@xyz.example.com", 551 }, 552 { 553 "context": "private", 554 "value": "jane_doe@example.com" 555 "isPreferred": true 556 } 557 ], 558 ... 559 } 561 Figure 8: EMAIL mapping example 563 2.4.3. IMPP 565 The vCard IMPP element is represented in JSCard as a "Resource" item 566 of the "online" array (Figure 9). In the "Resource" item, the "type" 567 member is set to "username" as well as a key of the "labels" is set 568 to "XMPP". 570 The PREF and MEDIATYPE parameters can be represented by the 571 "isPreferred" and "mediaType" properties respectively. 573 BEGIN:VCARD 574 VERSION:4.0 575 ... 576 IMPP;PREF=1:xmpp:alice@example.com 577 ... 578 END:VCARD 580 { 581 ... 582 "online":[ 583 ... 584 { 585 "type": "username", 586 "labels": { "XMPP": true }, 587 "value": "alice@example.com" 588 }, 589 ... 590 ], 591 ... 592 } 594 Figure 9: IMPP mapping example 596 2.4.4. LANG 598 The vCard LANG element is represented through the JSCard 599 "preferredContactLanguages" map (Figure 10): an entry for each 600 language that may be used for contacting the entity associated with 601 the JSCard. The entry keys correspond to the language tags, the 602 corresponding entry values are arrays of ContactLanguage items. 604 The TYPE and PREF parameters can be represented by the 605 ContactLanguage properties "type" and "preference" respectively. 607 If both PREF and TYPE parameters are missing, the array of 608 ContactLanguage items MUST be empty. 610 BEGIN:VCARD 611 VERSION:4.0 612 ... 613 LANG;TYPE=work;PREF=1:en 614 LANG;TYPE=work;PREF=2:fr 615 LANG;TYPE=home:fr 616 ... 617 END:VCARD 619 { 620 ... 621 "preferredContactLanguages" : { 622 "en": [ 623 { 624 "type": "work", 625 "preference": 1 626 } 627 ], 628 "fr": [ 629 { 630 "type": "work", 631 "preference": 2 632 }, 633 { 634 "type": "home", 635 } 636 ] 637 }, 638 ... 639 } 641 Figure 10: LANG mapping example 643 2.5. Geographical Properties 645 The GEO and TZ elements are not directly mapped into equivalent 646 topmost JSCard elements because the same information is represented 647 through equivalent "Address" properties. 649 2.6. Organizational Properties 651 2.6.1. TITLE 653 The vCard TITLE element is mapped onto the JSCard "jobTitle" array; 654 an item for each title (Figure 11). 656 The LANGUAGE parameter values can be expressed as corresponding 657 entries of the "localizations" map included in each "Resource" item. 659 BEGIN:VCARD 660 VERSION:4.0 661 ... 662 TITLE:Research Scientist 663 ... 664 END:VCARD 666 { 667 ... 668 "jobTilte":[ 669 { 670 "value": "Research Scientist" 671 } 672 ], 673 ... 674 } 676 Figure 11: TITLE mapping example 678 2.6.2. ROLE 680 The vCard ROLE element is mapped onto the JSCard "role" array; an 681 item for each role (Figure 12). 683 The LANGUAGE parameter values can be expressed as corresponding 684 entries of the "localizations" map included in each "Resource" item. 686 BEGIN:VCARD 687 VERSION:4.0 688 ... 689 ROLE:Project Leader 690 ... 691 END:VCARD 693 { 694 ... 695 "role":[ 696 { 697 "value": "Project Leader" 698 } 699 ], 700 ... 701 } 703 Figure 12: ROLE mapping example 705 2.6.3. LOGO 707 The vCard LOGO element is represented in JSCard as a "Resource" item 708 of the "online" array (Figure 13). In the "Resource" item, the 709 "type" member is set to "uri" as well as a key of the "labels" is set 710 to "logo". 712 The PREF and MEDIATYPE parameters can be represented by the 713 "isPreferred" and "mediaType" properties respectively. 715 BEGIN:VCARD 716 VERSION:4.0 717 ... 718 LOGO:http://www.example.com/pub/logos/abccorp.jpg 719 ... 720 END:VCARD 722 { 723 ... 724 "online":[ 725 ... 726 { 727 "type": "uri", 728 "labels": { "logo": true }, 729 "value": "http://www.example.com/pub/logos/abccorp.jpg" 730 }, 731 ... 732 ], 733 ... 734 } 736 Figure 13: LOGO mapping example 738 2.6.4. ORG 740 The vCard ORG element is mapped onto the JSCard "organization" array; 741 an item for each organization (Figure 14). The organization name 742 includes the organizational units if any. 744 The LANGUAGE parameter values can be expressed as corresponding 745 entries of the "localizations" map included in each "Resource" item. 747 BEGIN:VCARD 748 VERSION:4.0 749 ... 750 ORG:ABC\, Inc.;North American Division;Marketing 751 ... 752 END:VCARD 754 { 755 ... 756 "organization":[ 757 { 758 "value": "ABC, Inc.;North American Division;Marketing" 759 } 760 ], 761 ... 762 } 764 Figure 14: ORG mapping example 766 2.6.5. MEMBER 768 According to the JSContact specification, a group of contact cards is 769 represented by a dedicated object named JSCardGroup (Figure 15). The 770 contact cards composing the group are included in the "cards" array. 771 Therefore, the vCard MEMBER element doesn't have a direct match with 772 a corresponding JSCard element. 774 BEGIN:VCARD 775 VERSION:4.0 776 KIND:group 777 FN:The Doe family 778 MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 779 MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 780 END:VCARD 781 BEGIN:VCARD 782 VERSION:4.0 783 FN:John Doe 784 UID:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 785 END:VCARD 786 BEGIN:VCARD 787 VERSION:4.0 788 FN:Jane Doe 789 UID:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 790 END:VCARD 792 { 793 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 794 "name": "The Doe family", 795 "cards": [ 796 { 797 "name": { 798 "fullName": { 799 "value": "John Doe" 800 } 801 }, 802 "uid": "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af" 803 }, 804 { 805 "name": { 806 "fullName": { 807 "value": "Jane Doe" 808 } 809 }, 810 "uid": "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519f" 811 } 812 ] 813 } 815 Figure 15: Group example 817 2.6.6. RELATED 819 The vCard RELATED element is converted into the "relatedTo" map 820 (Figure 16): an entry for each entity the entity described by the 821 JSCard is associated with. The map keys are the UUIDs of the 822 associated cards. 824 Each map value is an object including only the "relation" property 825 represented as a set of relation types described in section 6.6.6 of 826 [RFC6350]. 828 If the relation type is unspecified, the "relation" is empty. 830 BEGIN:VCARD 831 VERSION:4.0 832 ... 833 RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 834 RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf 835 RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries. 836 ... 837 END:VCARD 839 { 840 ... 841 "relatedTo":{ 842 { 843 "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6": 844 { 845 "relation": { 846 "friend": true 847 } 848 } 849 }, 850 { 851 "http://example.com/directory/jdoe.vcf": 852 { 853 "relation": { 854 "contact": true 855 } 856 } 857 }, 858 { 859 "Please contact my assistant Jane Doe for any inquiries.": 860 { 861 "relation": { } 862 } 863 } 864 } 865 ... 866 } 868 Figure 16: RELATED mapping example 870 2.6.7. CONTACT-URI 872 The vCard CONTACT-URI element defined by [RFC8605] is represented in 873 JSCard as a "Resource" item of the "online" array (Figure 17). In 874 the "Resource" item, the "type" member is set to "uri" as well as a 875 key of the "labels" is set to "contact-uri". 877 The PREF parameter can be represented by the "isPreferred" property. 879 BEGIN:VCARD 880 VERSION:4.0 881 ... 882 CONTACT-URI;PREF=1:mailto:contact@example.com 883 ... 884 END:VCARD 886 { 887 ... 888 "online":[ 889 ... 890 { 891 "type": "uri", 892 "labels": { "contact-uri": true }, 893 "value": "mailto:contact@example.com", 894 "isPreferred": true 895 }, 896 ... 897 ], 898 ... 899 } 901 Figure 17: CONTACT-URI mapping example 903 2.7. Personal Information Properties 905 2.7.1. EXPERTISE 907 The vCard EXPERTISE element defined by [RFC6715] is represented in 908 JSCard as a "PersonalInformation" item of the "personalInfo" array 909 (Figure 18). The "type" property is set to "expertise". 911 The LEVEL parameter can be represented by the "level" property with 912 following mapping: 914 o "beginner" is converted into "low"; 915 o "average" is converted into "medium"; 916 o "expert" is converted into "high". 918 The INDEX parameter is represented by the position of the expertise 919 among the declared expertises. 921 BEGIN:VCARD 922 VERSION:4.0 923 ... 924 EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature 925 EXPERTISE;INDEX=1;LEVEL=expert:chemistry 926 ... 927 END:VCARD 929 { 930 ... 931 "personalInfo":[ 932 ... 933 { 934 "type": "expertise", 935 "value": "chemistry", 936 "level": "high" 937 }, 938 { 939 "type": "expertise", 940 "value": "chinese literature", 941 "level": "low" 942 } 943 ... 944 ] 945 ... 946 } 948 Figure 18: EXPERTISE mapping example 950 2.7.2. HOBBY 952 The vCard HOBBY element defined by [RFC6715] is represented in JSCard 953 as a "PersonalInformation" item of the "personalInfo" array 954 (Figure 19). The "type" property is set to "hobby". 956 The LEVEL parameter can be represented by the "level" property with a 957 direct mapping. 959 The INDEX parameter is represented by the position of the hobby among 960 the declared hobbies. 962 BEGIN:VCARD 963 VERSION:4.0 964 ... 965 HOBBY;INDEX=1;LEVEL=high:reading 966 HOBBY;INDEX=2;LEVEL=high:sewing 967 ... 968 END:VCARD 970 { 971 ... 972 "personalInfo":[ 973 ... 974 { 975 "type": "hobby", 976 "value": "reading", 977 "level": "high" 978 }, 979 { 980 "type": "hobby", 981 "value": "sewing", 982 "level": "high" 983 } 984 ... 985 ] 986 ... 987 } 989 Figure 19: HOBBY mapping example 991 2.7.3. INTEREST 993 The vCard INTEREST element defined by [RFC6715] is represented in 994 JSCard as a "PersonalInformation" item of the "personalInfo" array 995 (Figure 20). The "type" property is set to "interest". 997 The LEVEL parameter can be represented by the "level" property with a 998 direct mapping. 1000 The INDEX parameter is represented by the position of the interest 1001 among the declared interests. 1003 BEGIN:VCARD 1004 VERSION:4.0 1005 ... 1006 INTEREST;INDEX=1;LEVEL=medium:r&b music 1007 INTEREST;INDEX=2;LEVEL=high:rock 'n' roll music 1008 ... 1009 END:VCARD 1011 { 1012 ... 1013 "personalInfo":[ 1014 ... 1015 { 1016 "type": "interest", 1017 "value": "r&b music", 1018 "level": "medium" 1019 }, 1020 { 1021 "type": "interest", 1022 "value": "rock 'n' roll music", 1023 "level": "high" 1024 } 1025 ... 1026 ] 1027 ... 1028 } 1030 Figure 20: INTEREST mapping example 1032 2.7.4. ORG-DIRECTORY 1034 The vCard ORG-DIRECTORY element is represented in JSCard as a 1035 "Resource" item of the "online" array (Figure 21). In the "Resource" 1036 item, the "type" member is set to "uri" as well as a key of the 1037 "labels" is set to "org-directory". 1039 The PREF parameter can be represented by the "isPreferred" property. 1041 The INDEX parameter is represented by the position of the directory 1042 among the online resources with the "org-directory" key in the 1043 "labels" map. 1045 BEGIN:VCARD 1046 VERSION:4.0 1047 ... 1048 ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com 1049 ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering 1050 ... 1051 END:VCARD 1053 { 1054 ... 1055 "online":[ 1056 ... 1057 { 1058 "type": "uri", 1059 "labels": { "org-directory": true }, 1060 "value": "http://directory.mycompany.example.com" 1061 }, 1062 { 1063 "type": "uri", 1064 "labels": { "org-directory": true }, 1065 "value": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering", 1066 "isPreferred": true 1067 }, 1068 ... 1069 ], 1070 ... 1071 } 1073 Figure 21: ORG-DIRECTORY mapping example 1075 2.8. Explanatory Properties 1077 2.8.1. CATEGORIES 1079 The vCard CATEGORIES element is converted into the JSCard 1080 "categories" array (Figure 22); an item for each category. 1082 BEGIN:VCARD 1083 VERSION:4.0 1084 ... 1085 CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY 1086 ... 1087 END:VCARD 1089 { 1090 ... 1091 "categories":[ 1092 "INTERNET", 1093 "IETF", 1094 "INDUSTRY", 1095 "INFORMATION TECHNOLOGY" 1096 ] 1097 ... 1098 } 1100 Figure 22: CATEGORIES mapping example 1102 2.8.2. NOTE 1104 The vCard NOTE element is mapped onto the JSCard "notes" array 1105 (Figure 23); an item for each note. 1107 The LANGUAGE parameter values can be expressed as corresponding 1108 entries of the "localizations" map included in each "Resource" item. 1110 BEGIN:VCARD 1111 VERSION:4.0 1112 ... 1113 NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri. 1114 ... 1115 END:VCARD 1117 { 1118 ... 1119 "notes":[ 1120 { 1121 "value": "This fax number is operational 0800 to 1715 EST, Mon-Fri." 1122 } 1123 ] 1124 ... 1125 } 1127 Figure 23: NOTE mapping example 1129 2.8.3. PRODID 1131 The vCard PRODID element is converted into the JSCard "prodId" 1132 property (Figure 24). 1134 BEGIN:VCARD 1135 VERSION:4.0 1136 ... 1137 PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN 1138 ... 1139 END:VCARD 1141 { 1142 ... 1143 "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN" 1144 ... 1145 } 1147 Figure 24: PRODID mapping example 1149 2.8.4. REV 1151 The vCard REV element is transformed into the JSCard "updated" 1152 property (Figure 25). 1154 BEGIN:VCARD 1155 VERSION:4.0 1156 ... 1157 REV:19951031T222710Z 1158 ... 1159 END:VCARD 1161 { 1162 ... 1163 "updated": "19951031T222710Z" 1164 ... 1165 } 1167 Figure 25: REV mapping example 1169 2.8.5. SOUND 1171 The vCard SOUND element is represented in JSCard as a "Resource" item 1172 of the "online" array (Figure 26). In the "Resource" item, the 1173 "type" member is set to "uri" as well as a key of the "labels" is set 1174 to "sound". 1176 The PREF and MEDIATYPE parameters can be represented by the 1177 "isPreferred" and "mediaType" properties respectively. 1179 BEGIN:VCARD 1180 VERSION:4.0 1181 ... 1182 SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com 1183 ... 1184 END:VCARD 1186 { 1187 ... 1188 "online":[ 1189 ... 1190 { 1191 "type": "uri", 1192 "labels": { "sound": true }, 1193 "value": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com" 1194 }, 1195 ... 1196 ], 1197 ... 1198 } 1200 Figure 26: SOUND mapping example 1202 2.8.6. UID 1204 The vCard UID element corresponds to the JSCard "uid" property 1205 (Figure 27). 1207 BEGIN:VCARD 1208 VERSION:4.0 1209 ... 1210 UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 1211 ... 1212 END:VCARD 1214 { 1215 ... 1216 "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6" 1217 ... 1218 } 1220 Figure 27: UID mapping example 1222 2.8.7. PID Parameter and CLIENTPIDMAP 1224 TBD 1226 2.8.8. URL 1228 The vCard URL element is represented in JSCard as a "Resource" item 1229 of the "online" array (Figure 28). In the "Resource" item, the 1230 "type" member is set to "uri" as well as a key of the "labels" is set 1231 to "url". 1233 The PREF and MEDIATYPE parameters can be represented by the 1234 "isPreferred" and "mediaType" properties respectively. 1236 BEGIN:VCARD 1237 VERSION:4.0 1238 ... 1239 URL:http://example.org/restaurant.french/~chezchic.html 1240 ... 1241 END:VCARD 1243 { 1244 ... 1245 "online":[ 1246 ... 1247 { 1248 "type": "uri", 1249 "labels": { "url": true }, 1250 "value": "http://example.org/restaurant.french/~chezchic.html" 1251 }, 1252 ... 1253 ], 1254 ... 1255 } 1257 Figure 28: URL mapping example 1259 2.8.9. VERSION 1261 The vCard VERSION element doesn't have a direct match with a 1262 corresponding JSCard element. 1264 2.9. Security Properties 1265 2.9.1. KEY 1267 The vCard KEY element is represented in JSCard as a "Resource" item 1268 of the "online" array (Figure 29). In the "Resource" item, the 1269 "type" member is set to "uri" as well as a key of the "labels" is set 1270 to "key". 1272 The PREF and MEDIATYPE parameters can be represented by the 1273 "isPreferred" and "mediaType" properties respectively. 1275 BEGIN:VCARD 1276 VERSION:4.0 1277 ... 1278 KEY:http://www.example.com/keys/jdoe.cer 1279 ... 1280 END:VCARD 1282 { 1283 ... 1284 "online":[ 1285 ... 1286 { 1287 "type": "uri", 1288 "labels": { "key": true }, 1289 "value": "http://www.example.com/keys/jdoe.cer" 1290 }, 1291 ... 1292 ], 1293 ... 1294 } 1296 Figure 29: KEY mapping example 1298 2.10. Calendar Properties 1300 2.10.1. FBURL 1302 The vCard FBURL element is represented in JSCard as a "Resource" item 1303 of the "online" array (Figure 30). In the "Resource" item, the 1304 "type" member is set to "uri" as well as a key of the "labels" is set 1305 to "fburl". 1307 The PREF and MEDIATYPE parameters can be represented by the 1308 "isPreferred" and "mediaType" properties respectively. 1310 BEGIN:VCARD 1311 VERSION:4.0 1312 ... 1313 FBURL;PREF=1:http://www.example.com/busy/janedoe 1314 FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb 1315 ... 1316 END:VCARD 1318 { 1319 ... 1320 "online":[ 1321 ... 1322 { 1323 "type": "uri", 1324 "labels": { "fburl": true }, 1325 "value": "http://www.example.com/busy/janedoe", 1326 "isPreferred": true 1327 }, 1328 { 1329 "type": "uri", 1330 "labels": { "fburl": true }, 1331 "value": "ftp://example.com/busy/project-a.ifb", 1332 "mediaType": "text/calendar" 1333 }, 1334 ... 1335 ], 1336 ... 1337 } 1339 Figure 30: FBURL mapping example 1341 2.10.2. CALADRURI 1343 The vCard CALADRURI element is represented in JSCard as a "Resource" 1344 item of the "online" array (Figure 31). In the "Resource" item, the 1345 "type" member is set to "uri" as well as a key of the "labels" is set 1346 to "caladruri". 1348 The PREF and MEDIATYPE parameters can be represented by the 1349 "isPreferred" and "mediaType" properties respectively. 1351 BEGIN:VCARD 1352 VERSION:4.0 1353 ... 1354 CALADRURI;PREF=1:mailto:janedoe@example.com 1355 CALADRURI:http://example.com/calendar/jdoe 1356 ... 1357 END:VCARD 1359 { 1360 ... 1361 "online":[ 1362 ... 1363 { 1364 "type": "uri", 1365 "labels": { "caladruri": true }, 1366 "value": "mailto:janedoe@example.com", 1367 "isPreferred": true 1368 }, 1369 { 1370 "type": "uri", 1371 "labels": { "caladruri": true }, 1372 "value": "http://example.com/calendar/jdoe" 1373 }, 1374 ... 1375 ], 1376 ... 1377 } 1379 Figure 31: CALADRURI mapping example 1381 2.10.3. CALURI 1383 The vCard CALURI element is represented in JSCard as a "Resource" 1384 item of the "online" array (Figure 32). In the "Resource" item, the 1385 "type" member is set to "uri" as well as a key of the "labels" is set 1386 to "caluri". 1388 The PREF and MEDIATYPE parameters can be represented by the 1389 "isPreferred" and "mediaType" properties respectively. 1391 BEGIN:VCARD 1392 VERSION:4.0 1393 ... 1394 CALURI;PREF=1:http://cal.example.com/calA 1395 CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics 1396 ... 1397 END:VCARD 1399 { 1400 ... 1401 "online":[ 1402 ... 1403 { 1404 "type": "uri", 1405 "labels": { "caluri": true }, 1406 "value": "http://cal.example.com/calA", 1407 "isPreferred": true 1408 }, 1409 { 1410 "type": "uri", 1411 "labels": { "caluri": true }, 1412 "value": "ftp://ftp.example.com/calA.ics", 1413 "mediaType": "text/calendar" 1414 }, 1415 ... 1416 ], 1417 ... 1418 } 1420 Figure 32: CALURI mapping example 1422 2.11. Extended Properties 1424 If an extended property is a resource, JSCard already allows to 1425 represent it by setting the "type" property to "other" and specifying 1426 a value for the "labels" map. 1428 Any other property supporting a custom feature MAY be added and its 1429 name MUST be prefixed with a specific domain name to avoid conflict, 1430 e.g. "example.com/customprop". 1432 2.12. JSCard Required Properties 1434 While converting a vCard into a JSCard, only the JSCard topmost "uid" 1435 property is required. 1437 2.13. JSCard Unmatched Properties 1439 The "preferredContactMethod" property doesn't match any vCard 1440 element. 1442 3. IANA Considerations 1444 This document has no actions for IANA. 1446 4. Security Considerations 1448 This document doesn't report any security consideration. 1450 5. References 1452 5.1. Normative References 1454 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1455 Requirement Levels", BCP 14, RFC 2119, 1456 DOI 10.17487/RFC2119, March 1997, 1457 . 1459 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 1460 DOI 10.17487/RFC6350, August 2011, 1461 . 1463 [RFC6473] Saint-Andre, P., "vCard KIND:application", RFC 6473, 1464 DOI 10.17487/RFC6473, December 2011, 1465 . 1467 [RFC6474] Li, K. and B. Leiba, "vCard Format Extensions: Place of 1468 Birth, Place and Date of Death", RFC 6474, 1469 DOI 10.17487/RFC6474, December 2011, 1470 . 1472 [RFC6715] Cauchie, D., Leiba, B., and K. Li, "vCard Format 1473 Extensions: Representing vCard Extensions Defined by the 1474 Open Mobile Alliance (OMA) Converged Address Book (CAB) 1475 Group", RFC 6715, DOI 10.17487/RFC6715, August 2012, 1476 . 1478 [RFC6869] Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard 1479 KIND:device", RFC 6869, DOI 10.17487/RFC6869, February 1480 2013, . 1482 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 1483 DOI 10.17487/RFC7095, January 2014, 1484 . 1486 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1487 Interchange Format", STD 90, RFC 8259, 1488 DOI 10.17487/RFC8259, December 2017, 1489 . 1491 [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: 1492 ICANN Extensions for the Registration Data Access Protocol 1493 (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, 1494 . 1496 5.2. Informative References 1498 [draft-ietf-jmap-jscontact] 1499 "JSContact: A JSON representation of contact data", 1500 . 1503 Authors' Addresses 1505 Mario Loffredo 1506 IIT-CNR/Registro.it 1507 Via Moruzzi,1 1508 Pisa 56124 1509 IT 1511 Email: mario.loffredo@iit.cnr.it 1512 URI: http://www.iit.cnr.it 1514 Robert Stepanek 1515 FastMail 1516 PO Box 234, Collins St West 1517 Melbourne VIC 8007 1518 AU 1520 Email: rsto@fastmailteam.com 1521 URI: https://www.fastmail.com