idnits 2.17.1 draft-loffredo-jmap-jscontact-vcard-03.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 (June 22, 2020) is 1404 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC6474' is defined on line 1480, 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: December 24, 2020 FastMail 6 June 22, 2020 8 JSContact: Converting from and to vCard 9 draft-loffredo-jmap-jscontact-vcard-03 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 December 24, 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 . . . . . . . . . . . . . . . . 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. Extended Properties . . . . . . . . . . . . . . . . . . . 35 105 2.12. JSCard Required Properties . . . . . . . . . . . . . . . 35 106 2.13. JSCard Unmatched Properties . . . . . . . . . . . . . . . 36 107 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 108 4. Security Considerations . . . . . . . . . . . . . . . . . . . 36 109 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 110 5.1. Normative References . . . . . . . . . . . . . . . . . . 36 111 5.2. Informative References . . . . . . . . . . . . . . . . . 37 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 37 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-based version 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 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. In particular, 141 unlike vCard, JSContact distinguishes between a single contact 142 card, named JSCard, and a group of contact cards, named 143 JSCardGroup. 145 o The vCard specification includes some features (like parameters) 146 that have been formally removed from JSCard due to a complete 147 refactoring of vCard content. Anyway, the vCard parameters may 148 appear as JSCard features. 150 o Some vCard elements represented individually have been mapped onto 151 members of JSCard objects. 153 o The vCard custom elements, identified by the prefix "x-", don't 154 have a direct counterpart among the JSContact specification. 156 1.3. Conventions Used in This Document 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 160 document are to be interpreted as described in [RFC2119]. 162 2. Mapping 164 This section contains the mapping between vCard and JSCard. The 165 vCard properties are grouped according to the categories defined by 166 [RFC6350]. 168 Where it is needed, the JCardGroup is taken into account. 170 In the following of this document, the vCard features, namely 171 properties and parameters, are written in uppercase while the JSCard 172 features are written in camel case. 174 2.1. General Properties 176 2.1.1. BEGIN and END 178 The BEGIN and END properties don't have a direct match with a JSCard 179 feature. 181 2.1.2. SOURCE 183 A SOURCE element is represented as a "Resource" object in the 184 "online" array (Figure 1) whose "type" member is set to "uri" and 185 "labels" map contains the entry <"source",true>. 187 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 188 and "mediaType" members respectively. 190 BEGIN:VCARD 191 VERSION:4.0 192 ... 193 SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf 194 ... 195 END:VCARD 197 { 198 ... 199 "online":[ 200 ... 201 { 202 "type": "uri", 203 "labels": { "source": true }, 204 "value": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf" 205 }, 206 ... 207 ], 208 ... 209 } 211 Figure 1: SOURCE mapping example 213 2.1.3. KIND 215 The KIND element is mapped onto the "kind" member (Figure 2). 216 Allowed values are those, except "group", described in section 6.1.4 217 of [RFC6350] and extended with the values declared in [RFC6473] and 218 [RFC6869]. A group of cards is represented through a JSCardGroup. 220 BEGIN:VCARD 221 VERSION:4.0 222 ... 223 KIND:individual 224 ... 225 END:VCARD 227 { 228 ... 229 "kind": "individual", 230 ... 231 } 233 Figure 2: KIND mapping example 235 2.1.4. XML 237 The XML property doesn't have a direct match with a JSCard feature. 239 2.2. Identification Properties 241 2.2.1. FN 243 All the FN elements are globally represented through the "fullName" 244 member. The presence of more than one name is implicitly associated 245 with the full name translations in various languages regardless of 246 the presence of the ALTID parameter. Each translation corresponds to 247 a different entry of the "localizations" map (Figure 3). 249 2.2.2. N and NICKNAME 251 Both the N and NICKNAME elements are converted into equivalent items 252 of the "name" array (Figure 3): 254 o the N components are transformed into related "NameComponent" 255 objects as reported in Table 1. Name components SHOULD be ordered 256 such that their values joined by whitespace produce a valid full 257 name of this entity; 259 o Each NICKNAME element is mapped onto an object whose "type" member 260 is set to "nickname" 262 +--------------------+--------------+ 263 | N component | "type" value | 264 +--------------------+--------------+ 265 | Honorific Prefixes | prefix | 266 | Given Names | personal | 267 | Family Names | surname | 268 | Additional Names | additional | 269 | Honorific Suffixes | suffix | 270 +--------------------+--------------+ 272 Table 1: N components mapping 274 BEGIN:VCARD 275 VERSION:4.0 276 ... 277 FN:Mr. John Q. Public\, Esq. 278 N:Public;John;Quinlan;Mr.;Esq. 279 NICKNAME:Johnny 280 ... 281 END:VCARD 283 { 284 ... 285 "fullName":{ 286 "value": "Mr. John Q. Public, Esq." 287 }, 288 "name":[ 289 { "value":"Mr.", "type": "prefix" }, 290 { "value":"John", "type": "personal" }, 291 { "value":"Public", "type": "surname" }, 292 { "value":"Quinlan", "type": "additional" }, 293 { "value":"Esq.", "type": "suffix" }, 294 { "value":"Johnny", "type": "nickname" } 295 ], 296 ... 297 } 299 Figure 3: FN, N, NICKNAME mapping example 301 2.2.3. PHOTO 303 A PHOTO element is represented as a "Resource" object in the "online" 304 array (Figure 4) whose "type" member is set to "uri" and "labels" map 305 contains the entry <"photo",true>. 307 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 308 and "mediaType" members respectively. 310 BEGIN:VCARD 311 VERSION:4.0 312 ... 313 PHOTO:http://www.example.com/pub/photos/jqpublic.gif 314 ... 315 END:VCARD 317 { 318 ... 319 "online":[ 320 ... 321 { 322 "type": "uri", 323 "labels": { "photo": true }, 324 "value": "http://www.example.com/pub/photos/jqpublic.gif" 325 }, 326 ... 327 ], 328 ... 329 } 331 Figure 4: PHOTO mapping example 333 2.2.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 335 The BDAY and ANNIVERSARY elements and the extensions BIRTHPLACE, 336 DEATHDATE, DEATHPLACE described in [RFC6350] are represented as 337 "Anniversary" objects included in the "anniversaries" array 338 (Figure 5): 340 o BDAY and BIRTHPLACE are mapped onto "date" and "place" where 341 "type" is set to "birth" 343 o DEATHDATE and DEATHPLACE are mapped onto "date" and "place" where 344 "type" is set to "death" 346 o ANNIVERSARY is mapped onto "date" where "type" is set to "other" 347 and "label" is set to a value describing in detail the kind of 348 anniversary (e.g. "marriage date" for the wedding anniversary). 350 Both birth and death places are represented as instances of the 351 "Address" object. The LANGUAGE parameter values of both BIRTHPLACE 352 and DEATHPLACE elements are represented as corresponding entries of 353 the "fullAddress.localizations" map. 355 BEGIN:VCARD 356 VERSION:4.0 357 ... 358 BDAY:19531015T231000Z 359 BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A. 360 DEATHDATE:19960415 361 DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A. 362 ANNIVERSARY:19860201 363 ... 364 END:VCARD 366 { 367 ... 368 "anniversaries":[ 369 { 370 "type": "birth", 371 "date": "19531015T231000Z", 372 "place": 373 { 374 "fullAddress": 375 { 376 "value": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A." 377 } 378 } 379 }, 380 { 381 "type": "birth", 382 "date": "19531015T231000Z", 383 "place": 384 { 385 "fullAddress": 386 { 387 "value": "4445 Courtright Street\nNew England, ND 58647\nU.S.A." 388 } 389 } 390 }, 391 { 392 "type": "other", 393 "label": "marriage date", 394 "date": "19860201" 395 } 396 ], 397 ... 398 } 400 Figure 5: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 401 mapping example 403 2.2.5. GENDER 405 TBD 407 2.3. Delivery Addressing Properties 409 2.3.1. ADR 411 An ADR element is represented as an "Address" object in the 412 "addresses" array (Figure 6). 414 The ADR components are transformed into the "Address" members as 415 reported in Table 2. 417 +------------------+----------------+ 418 | ADR component | Address member | 419 +------------------+----------------+ 420 | p.o. box | postOfficeBox | 421 | extended address | extension | 422 | street address | street | 423 | locality | locality | 424 | region | region | 425 | postal code | postcode | 426 | country name | country | 427 +------------------+----------------+ 429 Table 2: ADR components mapping 431 The LABEL parameter is converted into the "fullAddress" member. 433 The PREF parameter is converted into the "isPreferred" member. 435 The GEO parameter is converted into the "coordinates" member. 437 The TZ parameter is converted into by the "timeZone" member. 439 The TYPE parameter is converted into the "context" member. The 440 "home" value is replaced with the "private" value. 442 The LANGUAGE parameter values are represented as different entries of 443 the "fullAddress.localizations" map. 445 The CC parameter defined by [RFC8605] is converted into the 446 "countryCode" member. 448 BEGIN:VCARD 449 VERSION:4.0 450 ... 451 ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA 452 ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA 453 ... 454 END:VCARD 456 { 457 ... 458 "addresses": [ 459 { 460 "context": "work", 461 "fullAddress": 462 { 463 "value": "54321 Oak St\nReston\nVA\n20190\nUSA" 464 }, 465 "street": "54321 Oak St", 466 "locality": "Reston", 467 "region": "VA", 468 "country": "USA", 469 "postcode": "20190", 470 "countryCode": "US" 471 }, 472 { 473 "context": "private", 474 "fullAddress": 475 { 476 "value": "12345 Elm St\nReston\nVA\n20190\nUSA" 477 }, 478 "street": "12345 Elm St", 479 "locality": "Reston", 480 "region": "VA", 481 "country": "USA", 482 "postcode": "20190", 483 "countryCode": "US" 484 } 485 ] 486 ... 487 } 489 Figure 6: ADR mapping example 491 2.4. Communications Properties 492 2.4.1. TEL 494 A TEL element is represented as a "Resource" object in the "phones" 495 array (Figure 7). The vCard "type-param-tel" values are mapped onto 496 the "type" member values. Those vCard "type-param-tel" values that 497 don't have a counterpart among the "type" member values are 498 represented as entry keys of the "labels" map with the corresponding 499 entry value set to true. The "type-param" values are are mapped onto 500 the "context" member values. The "home" value is replaced with the 501 "private" value. 503 The PREF parameter is mapped onto the "isPreferred" member. 505 BEGIN:VCARD 506 VERSION:4.0 507 ... 508 TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555 509 TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67 510 ... 511 END:VCARD 513 { 514 ... 515 "phones":[ 516 { 517 "context": "private", 518 "type": "voice", 519 "value": "tel:+1-555-555-5555;ext=5555", 520 "isPreferred": true 521 }, 522 { 523 "context": "private", 524 "value": "tel:+33-01-23-45-67" 525 } 526 ], 527 ... 528 } 530 Figure 7: TEL mapping example 532 2.4.2. EMAIL 534 An EMAIL element is represented as a "Resource" object in the 535 "emails" array (Figure 8). The vCard "type-param" values are mapped 536 onto the "context" member values. The "home" value is replaced with 537 the "private" value. 539 The PREF parameter is mapped onto the "isPreferred" member. 541 BEGIN:VCARD 542 VERSION:4.0 543 ... 544 EMAIL;TYPE=work:jqpublic@xyz.example.com 545 EMAIL;PREF=1:jane_doe@example.com 546 ... 547 END:VCARD 549 { 550 ... 551 "emails":[ 552 { 553 "context": "work", 554 "value": "jqpublic@xyz.example.com", 555 }, 556 { 557 "context": "private", 558 "value": "jane_doe@example.com" 559 "isPreferred": true 560 } 561 ], 562 ... 563 } 565 Figure 8: EMAIL mapping example 567 2.4.3. IMPP 569 An IMPP element is represented as a "Resource" object in the "online" 570 array (Figure 9) whose "type" member is set to "username" and 571 "labels" map contains the entry <"XMPP",true>. 573 In case of a contact card related to an acconunt on another online 574 service, the entry key SHOULD be the canonical service name, 575 including capitalisation (e.g. "Twitter", "Facebook", "Skype", 576 "GitHub") 578 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 579 and "mediaType" members respectively. 581 BEGIN:VCARD 582 VERSION:4.0 583 ... 584 IMPP;PREF=1:xmpp:alice@example.com 585 ... 586 END:VCARD 588 { 589 ... 590 "online":[ 591 ... 592 { 593 "type": "username", 594 "labels": { "XMPP": true }, 595 "value": "alice@example.com" 596 }, 597 ... 598 ], 599 ... 600 } 602 Figure 9: IMPP mapping example 604 2.4.4. LANG 606 A LANG element is represented through the "preferredContactLanguages" 607 map (Figure 10): an entry for each language that may be used for 608 contacting the entity associated with the JSCard. The entry keys 609 correspond to the language tags, the corresponding entry values are 610 arrays of "ContactLanguage" objects. 612 The TYPE and PREF parameters are mapped onto the "ContactLanguage" 613 members "type" and "preference" respectively. 615 If both PREF and TYPE parameters are missing, the array of 616 "ContactLanguage" objects MUST be empty. 618 BEGIN:VCARD 619 VERSION:4.0 620 ... 621 LANG;TYPE=work;PREF=1:en 622 LANG;TYPE=work;PREF=2:fr 623 LANG;TYPE=home:fr 624 ... 625 END:VCARD 627 { 628 ... 629 "preferredContactLanguages" : { 630 "en": [ 631 { 632 "type": "work", 633 "preference": 1 634 } 635 ], 636 "fr": [ 637 { 638 "type": "work", 639 "preference": 2 640 }, 641 { 642 "type": "home", 643 } 644 ] 645 }, 646 ... 647 } 649 Figure 10: LANG mapping example 651 2.5. Geographical Properties 653 The GEO and TZ elements are not directly mapped into equivalent 654 topmost JSCard members because the same information is represented 655 through equivalent "Address" members. 657 The ALTID parameter is used for associating both GEO and TZ elements 658 with the related address information. When the ALTID parameter is 659 missing, the element should be associated with the first contact 660 address. 662 2.6. Organizational Properties 664 2.6.1. TITLE 666 A TITLE element is mapped onto a "LocalizedString" object included in 667 the "jobTitle" array (Figure 11). 669 The ALTID parameter is used for for associating the language- 670 dependent alternatives with a given element. 672 The LANGUAGE parameter values are represented as corresponding 673 entries of the "localizations" map. 675 BEGIN:VCARD 676 VERSION:4.0 677 ... 678 TITLE:Research Scientist 679 ... 680 END:VCARD 682 { 683 ... 684 "jobTitle":[ 685 { 686 "value": "Research Scientist" 687 } 688 ], 689 ... 690 } 692 Figure 11: TITLE mapping example 694 2.6.2. ROLE 696 A ROLE element is mapped onto a "LocalizedString" object included in 697 the "role" array (Figure 12). 699 The ALTID parameter is used for for associating the language- 700 dependent alternatives with a given element. 702 The LANGUAGE parameter values are represented as corresponding 703 entries of the "localizations" map. 705 BEGIN:VCARD 706 VERSION:4.0 707 ... 708 ROLE:Project Leader 709 ... 710 END:VCARD 712 { 713 ... 714 "role":[ 715 { 716 "value": "Project Leader" 717 } 718 ], 719 ... 720 } 722 Figure 12: ROLE mapping example 724 2.6.3. LOGO 726 A LOGO element is represented as a "Resource" object in the "online" 727 array (Figure 13) whose "type" member is set to "uri" and "labels" 728 map contains the entry <"logo",true>. 730 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 731 and "mediaType" members respectively. 733 BEGIN:VCARD 734 VERSION:4.0 735 ... 736 LOGO:http://www.example.com/pub/logos/abccorp.jpg 737 ... 738 END:VCARD 740 { 741 ... 742 "online":[ 743 ... 744 { 745 "type": "uri", 746 "labels": { "logo": true }, 747 "value": "http://www.example.com/pub/logos/abccorp.jpg" 748 }, 749 ... 750 ], 751 ... 752 } 754 Figure 13: LOGO mapping example 756 2.6.4. ORG 758 An ORG element is mapped onto a "LocalizedString" object included in 759 the "organization" array (Figure 14). The organization name includes 760 the organizational units if any. 762 The ALTID parameter is used for for associating the language- 763 dependent alternatives with a given element. 765 The LANGUAGE parameter values are represented as corresponding 766 entries of the "localizations" map. 768 BEGIN:VCARD 769 VERSION:4.0 770 ... 771 ORG:ABC\, Inc.;North American Division;Marketing 772 ... 773 END:VCARD 775 { 776 ... 777 "organization":[ 778 { 779 "value": "ABC, Inc.;North American Division;Marketing" 780 } 781 ], 782 ... 783 } 785 Figure 14: ORG mapping example 787 2.6.5. MEMBER 789 According to the JSContact specification, a group of contact cards is 790 represented through a JSCardGroup (Figure 15). The contact cards 791 composing the group are included in the "cards" array. Therefore, 792 the MEMBER element doesn't have a direct match with a JSCard feature. 794 BEGIN:VCARD 795 VERSION:4.0 796 KIND:group 797 FN:The Doe family 798 MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 799 MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 800 END:VCARD 801 BEGIN:VCARD 802 VERSION:4.0 803 FN:John Doe 804 UID:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 805 END:VCARD 806 BEGIN:VCARD 807 VERSION:4.0 808 FN:Jane Doe 809 UID:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 810 END:VCARD 812 { 813 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 814 "name": "The Doe family", 815 "cards": [ 816 { 817 "name": { 818 "fullName": { 819 "value": "John Doe" 820 } 821 }, 822 "uid": "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af" 823 }, 824 { 825 "name": { 826 "fullName": { 827 "value": "Jane Doe" 828 } 829 }, 830 "uid": "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519f" 831 } 832 ] 833 } 835 Figure 15: Group example 837 2.6.6. RELATED 839 All the RELATED elements are globally converted into the "relatedTo" 840 map (Figure 16): an entry for each entity the entity described by the 841 JSCard is associated with. The map keys are the "uid" values of the 842 associated cards. 844 Each map value is a "Relation" object including only the "relation" 845 member represented as a set of relation types described in section 846 6.6.6 of [RFC6350]. 848 If the relation type is unspecified, the "relation" is empty. 850 BEGIN:VCARD 851 VERSION:4.0 852 ... 853 RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 854 RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf 855 RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries. 856 ... 857 END:VCARD 859 { 860 ... 861 "relatedTo":{ 862 { 863 "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6": 864 { 865 "relation": { 866 "friend": true 867 } 868 } 869 }, 870 { 871 "http://example.com/directory/jdoe.vcf": 872 { 873 "relation": { 874 "contact": true 875 } 876 } 877 }, 878 { 879 "Please contact my assistant Jane Doe for any inquiries.": 880 { 881 "relation": { } 882 } 883 } 884 } 885 ... 886 } 888 Figure 16: RELATED mapping example 890 2.6.7. CONTACT-URI 892 A CONTACT-URI element defined by [RFC8605] is represented as a 893 "Resource" object of the "online" array (Figure 17) whose "type" 894 member is set to "uri" and "labels" map contains the entry <"contact- 895 uri",true>. 897 The PREF parameter is mapped onto the "isPreferred" member. 899 BEGIN:VCARD 900 VERSION:4.0 901 ... 902 CONTACT-URI;PREF=1:mailto:contact@example.com 903 ... 904 END:VCARD 906 { 907 ... 908 "online":[ 909 ... 910 { 911 "type": "uri", 912 "labels": { "contact-uri": true }, 913 "value": "mailto:contact@example.com", 914 "isPreferred": true 915 }, 916 ... 917 ], 918 ... 919 } 921 Figure 17: CONTACT-URI mapping example 923 2.7. Personal Information Properties 925 2.7.1. EXPERTISE 927 An EXPERTISE element defined by [RFC6715] is represented as a 928 "PersonalInformation" object in the "personalInfo" array (Figure 18). 929 The "type" member is set to "expertise". 931 The LEVEL parameter is mapped onto the "level" member with following 932 mapping: 934 o "beginner" is converted into "low"; 935 o "average" is converted into "medium"; 936 o "expert" is converted into "high". 938 The INDEX parameter is represented as the index of the expertise 939 among the declared expertises. 941 BEGIN:VCARD 942 VERSION:4.0 943 ... 944 EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature 945 EXPERTISE;INDEX=1;LEVEL=expert:chemistry 946 ... 947 END:VCARD 949 { 950 ... 951 "personalInfo":[ 952 ... 953 { 954 "type": "expertise", 955 "value": "chemistry", 956 "level": "high" 957 }, 958 { 959 "type": "expertise", 960 "value": "chinese literature", 961 "level": "low" 962 } 963 ... 964 ] 965 ... 966 } 968 Figure 18: EXPERTISE mapping example 970 2.7.2. HOBBY 972 An HOBBY element defined by [RFC6715] is represented as a 973 "PersonalInformation" object in the "personalInfo" array (Figure 19). 974 The "type" member is set to "hobby". 976 The LEVEL parameter is mapped onto the "level" member with a direct 977 mapping. 979 The INDEX parameter is represented as the index of the hobby among 980 the declared hobbies. 982 BEGIN:VCARD 983 VERSION:4.0 984 ... 985 HOBBY;INDEX=1;LEVEL=high:reading 986 HOBBY;INDEX=2;LEVEL=high:sewing 987 ... 988 END:VCARD 990 { 991 ... 992 "personalInfo":[ 993 ... 994 { 995 "type": "hobby", 996 "value": "reading", 997 "level": "high" 998 }, 999 { 1000 "type": "hobby", 1001 "value": "sewing", 1002 "level": "high" 1003 } 1004 ... 1005 ] 1006 ... 1007 } 1009 Figure 19: HOBBY mapping example 1011 2.7.3. INTEREST 1013 An INTEREST element defined by [RFC6715] is represented as a 1014 "PersonalInformation" object in the "personalInfo" array (Figure 20). 1015 The "type" member is set to "interest". 1017 The LEVEL parameter is mapped onto the "level" member with a direct 1018 mapping. 1020 The INDEX parameter is represented as the index of the interest among 1021 the declared interests. 1023 BEGIN:VCARD 1024 VERSION:4.0 1025 ... 1026 INTEREST;INDEX=1;LEVEL=medium:r&b music 1027 INTEREST;INDEX=2;LEVEL=high:rock 'n' roll music 1028 ... 1029 END:VCARD 1031 { 1032 ... 1033 "personalInfo":[ 1034 ... 1035 { 1036 "type": "interest", 1037 "value": "r&b music", 1038 "level": "medium" 1039 }, 1040 { 1041 "type": "interest", 1042 "value": "rock 'n' roll music", 1043 "level": "high" 1044 } 1045 ... 1046 ] 1047 ... 1048 } 1050 Figure 20: INTEREST mapping example 1052 2.7.4. ORG-DIRECTORY 1054 An ORG-DIRECTORY element is represented as a "Resource" object in the 1055 "online" array (Figure 21) whose "type" member is set to "uri" and 1056 "labels" map contains the entry <"org-directory",true>. 1058 The PREF parameter is mapped onto the "isPreferred" member. 1060 The INDEX parameter is represented as the index of the directory 1061 among the online resources with the "org-directory" key in the 1062 "labels" map. 1064 BEGIN:VCARD 1065 VERSION:4.0 1066 ... 1067 ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com 1068 ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering 1069 ... 1070 END:VCARD 1072 { 1073 ... 1074 "online":[ 1075 ... 1076 { 1077 "type": "uri", 1078 "labels": { "org-directory": true }, 1079 "value": "http://directory.mycompany.example.com" 1080 }, 1081 { 1082 "type": "uri", 1083 "labels": { "org-directory": true }, 1084 "value": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering", 1085 "isPreferred": true 1086 }, 1087 ... 1088 ], 1089 ... 1090 } 1092 Figure 21: ORG-DIRECTORY mapping example 1094 2.8. Explanatory Properties 1096 2.8.1. CATEGORIES 1098 A CATEGORIES element is converted into an object in the "categories" 1099 array (Figure 22). 1101 BEGIN:VCARD 1102 VERSION:4.0 1103 ... 1104 CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY 1105 ... 1106 END:VCARD 1108 { 1109 ... 1110 "categories":[ 1111 "INTERNET", 1112 "IETF", 1113 "INDUSTRY", 1114 "INFORMATION TECHNOLOGY" 1115 ] 1116 ... 1117 } 1119 Figure 22: CATEGORIES mapping example 1121 2.8.2. NOTE 1123 A NOTE element is mapped onto a "LocalizedString" object included in 1124 the "notes" array (Figure 23). 1126 The ALTID parameter is used for associating the language-dependent 1127 alternatives with a given element. 1129 The LANGUAGE parameter values are represented as corresponding 1130 entries of the "localizations" map. 1132 BEGIN:VCARD 1133 VERSION:4.0 1134 ... 1135 NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri. 1136 ... 1137 END:VCARD 1139 { 1140 ... 1141 "notes":[ 1142 { 1143 "value": "This fax number is operational 0800 to 1715 EST, Mon-Fri." 1144 } 1145 ] 1146 ... 1147 } 1149 Figure 23: NOTE mapping example 1151 2.8.3. PRODID 1153 The PRODID element is converted into the "prodId" member (Figure 24). 1155 BEGIN:VCARD 1156 VERSION:4.0 1157 ... 1158 PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN 1159 ... 1160 END:VCARD 1162 { 1163 ... 1164 "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN" 1165 ... 1166 } 1168 Figure 24: PRODID mapping example 1170 2.8.4. REV 1172 The REV element is transformed into the "updated" member (Figure 25). 1174 BEGIN:VCARD 1175 VERSION:4.0 1176 ... 1177 REV:19951031T222710Z 1178 ... 1179 END:VCARD 1181 { 1182 ... 1183 "updated": "19951031T222710Z" 1184 ... 1185 } 1187 Figure 25: REV mapping example 1189 2.8.5. SOUND 1191 A SOUND element is represented as a "Resource" object in the "online" 1192 array (Figure 26) whose "type" member is set to "uri" and "labels" 1193 map contains the entry <"sound",true>. 1195 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 1196 and "mediaType" members respectively. 1198 BEGIN:VCARD 1199 VERSION:4.0 1200 ... 1201 SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com 1202 ... 1203 END:VCARD 1205 { 1206 ... 1207 "online":[ 1208 ... 1209 { 1210 "type": "uri", 1211 "labels": { "sound": true }, 1212 "value": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com" 1213 }, 1214 ... 1215 ], 1216 ... 1217 } 1219 Figure 26: SOUND mapping example 1221 2.8.6. UID 1223 The UID element corresponds to the "uid" member (Figure 27). 1225 BEGIN:VCARD 1226 VERSION:4.0 1227 ... 1228 UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 1229 ... 1230 END:VCARD 1232 { 1233 ... 1234 "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6" 1235 ... 1236 } 1238 Figure 27: UID mapping example 1240 2.8.7. CLIENTPIDMAP and PID Parameter 1242 TBD 1244 2.8.8. URL 1246 An URL element is represented as a "Resource" object in the "online" 1247 array (Figure 28) whose "type" member is set to "uri" and "labels" 1248 map contains the entry <"url",true>. 1250 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 1251 and "mediaType" members respectively. 1253 BEGIN:VCARD 1254 VERSION:4.0 1255 ... 1256 URL:http://example.org/restaurant.french/~chezchic.html 1257 ... 1258 END:VCARD 1260 { 1261 ... 1262 "online":[ 1263 ... 1264 { 1265 "type": "uri", 1266 "labels": { "url": true }, 1267 "value": "http://example.org/restaurant.french/~chezchic.html" 1268 }, 1269 ... 1270 ], 1271 ... 1272 } 1274 Figure 28: URL mapping example 1276 2.8.9. VERSION 1278 The VERSION property doesn't have a direct match with a JSCard 1279 feature. 1281 2.9. Security Properties 1283 2.9.1. KEY 1285 A KEY element is represented as a "Resource" object in the "online" 1286 array (Figure 29) whose "type" member is set to "uri" and "labels" 1287 map contains the entry <"key",true>. 1289 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 1290 and "mediaType" members respectively. 1292 BEGIN:VCARD 1293 VERSION:4.0 1294 ... 1295 KEY:http://www.example.com/keys/jdoe.cer 1296 ... 1297 END:VCARD 1299 { 1300 ... 1301 "online":[ 1302 ... 1303 { 1304 "type": "uri", 1305 "labels": { "key": true }, 1306 "value": "http://www.example.com/keys/jdoe.cer" 1307 }, 1308 ... 1309 ], 1310 ... 1311 } 1313 Figure 29: KEY mapping example 1315 2.10. Calendar Properties 1317 2.10.1. FBURL 1319 A FBURL element is represented as a "Resource" object of the "online" 1320 array (Figure 30) whose "type" member is set to "uri" and "labels" 1321 map contains the entry <"fburl",true>. 1323 The PREF and MEDIATYPE parameters are mapped ontoy the "isPreferred" 1324 and "mediaType" members respectively. 1326 BEGIN:VCARD 1327 VERSION:4.0 1328 ... 1329 FBURL;PREF=1:http://www.example.com/busy/janedoe 1330 FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb 1331 ... 1332 END:VCARD 1334 { 1335 ... 1336 "online":[ 1337 ... 1338 { 1339 "type": "uri", 1340 "labels": { "fburl": true }, 1341 "value": "http://www.example.com/busy/janedoe", 1342 "isPreferred": true 1343 }, 1344 { 1345 "type": "uri", 1346 "labels": { "fburl": true }, 1347 "value": "ftp://example.com/busy/project-a.ifb", 1348 "mediaType": "text/calendar" 1349 }, 1350 ... 1351 ], 1352 ... 1353 } 1355 Figure 30: FBURL mapping example 1357 2.10.2. CALADRURI 1359 A CALADRURI element is represented as a "Resource" object of the 1360 "online" array (Figure 31) whose "type" member is set to "uri" and 1361 "labels" map contains the entry <"caladruri",true>. 1363 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 1364 and "mediaType" members respectively. 1366 BEGIN:VCARD 1367 VERSION:4.0 1368 ... 1369 CALADRURI;PREF=1:mailto:janedoe@example.com 1370 CALADRURI:http://example.com/calendar/jdoe 1371 ... 1372 END:VCARD 1374 { 1375 ... 1376 "online":[ 1377 ... 1378 { 1379 "type": "uri", 1380 "labels": { "caladruri": true }, 1381 "value": "mailto:janedoe@example.com", 1382 "isPreferred": true 1383 }, 1384 { 1385 "type": "uri", 1386 "labels": { "caladruri": true }, 1387 "value": "http://example.com/calendar/jdoe" 1388 }, 1389 ... 1390 ], 1391 ... 1392 } 1394 Figure 31: CALADRURI mapping example 1396 2.10.3. CALURI 1398 A CALURI element is represented as a "Resource" object of the 1399 "online" array (Figure 32) whose "type" member is set to "uri" and 1400 "labels" map contains the entry <"caluri",true>. 1402 The PREF and MEDIATYPE parameters are mapped onto the "isPreferred" 1403 and "mediaType" members respectively. 1405 BEGIN:VCARD 1406 VERSION:4.0 1407 ... 1408 CALURI;PREF=1:http://cal.example.com/calA 1409 CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics 1410 ... 1411 END:VCARD 1413 { 1414 ... 1415 "online":[ 1416 ... 1417 { 1418 "type": "uri", 1419 "labels": { "caluri": true }, 1420 "value": "http://cal.example.com/calA", 1421 "isPreferred": true 1422 }, 1423 { 1424 "type": "uri", 1425 "labels": { "caluri": true }, 1426 "value": "ftp://ftp.example.com/calA.ics", 1427 "mediaType": "text/calendar" 1428 }, 1429 ... 1430 ], 1431 ... 1432 } 1434 Figure 32: CALURI mapping example 1436 2.11. Extended Properties 1438 If an extended property is a resource, JSCard already allows to 1439 represent it by setting the "type" member to "other" and specifying a 1440 value for the "labels" map. 1442 Any other property supporting a custom feature MAY be added and its 1443 name MUST be prefixed with a specific domain name to avoid conflict, 1444 e.g. "example.com/customprop". 1446 2.12. JSCard Required Properties 1448 While converting a vCard into a JSCard, only the topmost "uid" member 1449 is required. 1451 2.13. JSCard Unmatched Properties 1453 The "preferredContactMethod" member doesn't match any vCard element. 1455 3. IANA Considerations 1457 This document has no actions for IANA. 1459 4. Security Considerations 1461 This document doesn't report any security consideration. 1463 5. References 1465 5.1. Normative References 1467 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1468 Requirement Levels", BCP 14, RFC 2119, 1469 DOI 10.17487/RFC2119, March 1997, 1470 . 1472 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 1473 DOI 10.17487/RFC6350, August 2011, 1474 . 1476 [RFC6473] Saint-Andre, P., "vCard KIND:application", RFC 6473, 1477 DOI 10.17487/RFC6473, December 2011, 1478 . 1480 [RFC6474] Li, K. and B. Leiba, "vCard Format Extensions: Place of 1481 Birth, Place and Date of Death", RFC 6474, 1482 DOI 10.17487/RFC6474, December 2011, 1483 . 1485 [RFC6715] Cauchie, D., Leiba, B., and K. Li, "vCard Format 1486 Extensions: Representing vCard Extensions Defined by the 1487 Open Mobile Alliance (OMA) Converged Address Book (CAB) 1488 Group", RFC 6715, DOI 10.17487/RFC6715, August 2012, 1489 . 1491 [RFC6869] Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard 1492 KIND:device", RFC 6869, DOI 10.17487/RFC6869, February 1493 2013, . 1495 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 1496 DOI 10.17487/RFC7095, January 2014, 1497 . 1499 [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: 1500 ICANN Extensions for the Registration Data Access Protocol 1501 (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, 1502 . 1504 5.2. Informative References 1506 [draft-ietf-jmap-jscontact] 1507 "JSContact: A JSON representation of contact data", 1508 . 1511 Authors' Addresses 1513 Mario Loffredo 1514 IIT-CNR/Registro.it 1515 Via Moruzzi,1 1516 Pisa 56124 1517 IT 1519 Email: mario.loffredo@iit.cnr.it 1520 URI: http://www.iit.cnr.it 1522 Robert Stepanek 1523 FastMail 1524 PO Box 234, Collins St West 1525 Melbourne VIC 8007 1526 AU 1528 Email: rsto@fastmailteam.com 1529 URI: https://www.fastmail.com