idnits 2.17.1 draft-ietf-jmap-jscontact-vcard-06.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 11 instances of too long lines in the document, the longest one being 18 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 12, 2021) is 990 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC6474' is defined on line 1720, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 8605 Summary: 2 errors (**), 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: Standards Track R. Stepanek 5 Expires: January 13, 2022 FastMail 6 July 12, 2021 8 JSContact: Converting from and to vCard 9 draft-ietf-jmap-jscontact-vcard-06 11 Abstract 13 This document defines how to convert contact information as defined 14 in the JSContact [draft-ietf-jmap-jscontact] specification from and 15 to vCard. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on January 13, 2022. 34 Copyright Notice 36 Copyright (c) 2021 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 . . . . . . . . . . . . . . . . . . . . 4 54 1.2.1. Extensions . . . . . . . . . . . . . . . . . . . . . 4 55 1.3. Conventions Used in This Document . . . . . . . . . . . . 4 56 2. Translating vCard properties to JSContact . . . . . . . . . . 5 57 2.1. Common Parameters . . . . . . . . . . . . . . . . . . . . 5 58 2.2. JSContact Id . . . . . . . . . . . . . . . . . . . . . . 5 59 2.3. General Properties . . . . . . . . . . . . . . . . . . . 6 60 2.3.1. BEGIN and END . . . . . . . . . . . . . . . . . . . . 6 61 2.3.2. SOURCE . . . . . . . . . . . . . . . . . . . . . . . 6 62 2.3.3. KIND . . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.3.4. XML . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 2.4. Identification Properties . . . . . . . . . . . . . . . . 7 65 2.4.1. FN . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 2.4.2. N and NICKNAME . . . . . . . . . . . . . . . . . . . 7 67 2.4.3. PHOTO . . . . . . . . . . . . . . . . . . . . . . . . 8 68 2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 9 69 2.4.5. GENDER . . . . . . . . . . . . . . . . . . . . . . . 11 70 2.5. Delivery Addressing Properties . . . . . . . . . . . . . 11 71 2.5.1. ADR . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 2.6. Communications Properties . . . . . . . . . . . . . . . . 14 73 2.6.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 14 74 2.6.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 14 75 2.6.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 15 76 2.6.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 16 77 2.7. Geographical Properties . . . . . . . . . . . . . . . . . 17 78 2.7.1. Time Zone Representation . . . . . . . . . . . . . . 18 79 2.8. Organizational Properties . . . . . . . . . . . . . . . . 19 80 2.8.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 19 81 2.8.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 20 82 2.8.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 21 83 2.8.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 22 84 2.8.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 24 85 2.8.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 25 86 2.9. Personal Information Properties . . . . . . . . . . . . . 25 87 2.9.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 26 88 2.9.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 26 89 2.9.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 27 90 2.9.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 28 91 2.10. Explanatory Properties . . . . . . . . . . . . . . . . . 29 92 2.10.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 29 93 2.10.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 30 94 2.10.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 31 95 2.10.4. REV . . . . . . . . . . . . . . . . . . . . . . . . 31 96 2.10.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . 31 97 2.10.6. UID . . . . . . . . . . . . . . . . . . . . . . . . 32 98 2.10.7. CLIENTPIDMAP and PID Parameter . . . . . . . . . . . 33 99 2.10.8. URL . . . . . . . . . . . . . . . . . . . . . . . . 33 100 2.10.9. VERSION . . . . . . . . . . . . . . . . . . . . . . 33 101 2.11. Security Properties . . . . . . . . . . . . . . . . . . . 33 102 2.11.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . 34 103 2.12. Calendar Properties . . . . . . . . . . . . . . . . . . . 34 104 2.12.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 34 105 2.12.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 35 106 2.12.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 36 107 2.13. vCard Unmatched Properties . . . . . . . . . . . . . . . 37 108 2.14. Card Required Properties . . . . . . . . . . . . . . . . 37 109 3. Translating JSContact properties to vCard . . . . . . . . . . 38 110 3.1. Id . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 111 3.2. Localizations . . . . . . . . . . . . . . . . . . . . . . 38 112 3.3. Date and Time Representations . . . . . . . . . . . . . . 38 113 3.4. Time Zone . . . . . . . . . . . . . . . . . . . . . . . . 38 114 3.5. JSContact Types Matching Multiple vCard Properties . . . 39 115 3.5.1. Title . . . . . . . . . . . . . . . . . . . . . . . . 39 116 3.5.2. Resource . . . . . . . . . . . . . . . . . . . . . . 39 117 3.6. CardGroup . . . . . . . . . . . . . . . . . . . . . . . . 39 118 3.7. Card Unmatched Properties . . . . . . . . . . . . . . . . 39 119 3.8. vCard Required Properties . . . . . . . . . . . . . . . . 39 120 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 121 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 40 122 5.1. CNR . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 123 6. Security Considerations . . . . . . . . . . . . . . . . . . . 40 124 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 125 7.1. Normative References . . . . . . . . . . . . . . . . . . 41 126 7.2. Informative References . . . . . . . . . . . . . . . . . 42 127 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 129 1. Introduction 131 1.1. Motivation 133 The JSContact specification [draft-ietf-jmap-jscontact] has been 134 defined to represent contact card information as a more efficient 135 alternative to vCard [RFC6350] and its JSON-based version named jCard 136 [RFC7095]. 138 While new applications might adopt JSContact as their main format to 139 exchange contact card data, they are likely to interoperate with 140 services and clients that just support vCard/jCard. Similarly, 141 existing contact data providers and consumers already using vCard/ 142 jCard might want to represent their data also according to the 143 JSContact specification. 145 To facilitate this, this document defines how to convert contact 146 information as defined in the JSContact [draft-ietf-jmap-jscontact] 147 specification from and to vCard. 149 1.2. Scope and Caveats 151 JSContact and vCard have a lot of semantics in common, however some 152 differences must be outlined: 154 o The JSContact data model defines some contact information that 155 doesn't have a direct mapping with vCard properties. In 156 particular, unlike vCard, JSContact distinguishes between a single 157 contact card, named Card, and a group of contact cards, named 158 CardGroup. 160 o The properties that can be present multiple times in a vCard are 161 represented through different collections in JSContact; mainly as 162 maps, sometimes as lists, in some cases condensed in a single 163 value. 165 1.2.1. Extensions 167 While translating vCard properties to JSContact, any vCard property 168 that doesn't have a direct counterpart in JSContact MUST be converted 169 into a property whose name is prefixed by "ietf.org//". 172 Any custom extension MAY be added and its name MUST be prefixed with 173 a specific domain name to avoid conflict, e.g. "example.com/ 174 customprop". 176 Similarly, the reversed rules are applied while translating JSContact 177 properties to vCard. 179 1.3. Conventions Used in This Document 181 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 182 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 183 document are to be interpreted as described in [RFC2119]. 185 In the following of this document, the vCard features, namely 186 properties and parameters, are written in uppercase while the Card/ 187 CardGroup features are written in camel case wrapped in double 188 quotes. 190 2. Translating vCard properties to JSContact 192 This section contains the translation rules from vCard to Card/ 193 CardGroup. The vCard properties are grouped according to the 194 categories as defined in [RFC6350]. 196 If a vCard represents a group of contacts, those vCard properties 197 which don't have a counterpart in CardGroup are converted into 198 related properties of the "CardGroup.card" object. In this case, the 199 "uid" member of both the resulting CardGroup object and its "card" 200 member MUST have the same value. 202 2.1. Common Parameters 204 The following mapping rules apply to parameters that are common to 205 most of the vCard properties: 207 o The generic values of the TYPE parameter are mapped to the values 208 of the "Context" type as defined in Section 1.5.1 of 209 [draft-ietf-jmap-jscontact]. The "home" value corresponds to the 210 "private" key. The mapping of those specific TYPE values used in 211 the TEL and RELATED properties are defined in Section 2.6.1 and 212 Section 2.8.5. 214 o The PREF parameter is mapped to the "pref" property. 216 o The MEDIATYPE parameter is mapped to the "mediaType" property. As 217 described in Section 5.7 of [RFC6350], the media type of a 218 resource can be identified by its URI. For example, "image/gif" 219 can be derived from the ".gif" extension of a GIF image URI. 220 JSContact producers MAY provide the media type information even 221 when it is not specified in the vCard. 223 o The ALTID and LANGUAGE parameters are used in combination for 224 associating the language-dependent alternatives with a given 225 property. Such alternatives are represented by using the 226 "localizations" map of a "LocalizedString" member inside the 227 matching JSContact object. 229 2.2. JSContact Id 231 The rules to generate a map key of type Id are out of the scope of 232 this document. 234 2.3. General Properties 236 2.3.1. BEGIN and END 238 The BEGIN and END properties don't have a direct match with a 239 JSContact feature. 241 2.3.2. SOURCE 243 A SOURCE property is represented as an entry of the "online" map 244 (Figure 1). The entry value is a "Resource" object whose "type" 245 member is set to "uri", the "label" member is set to "source" and the 246 "resource" member is the SOURCE value. 248 The PREF and MEDIATYPE parameters are mapped according to the rules 249 as defined in (Section 2.1). 251 BEGIN:VCARD 252 VERSION:4.0 253 ... 254 SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf 255 ... 256 END:VCARD 258 { 259 ... 260 "online":{ 261 ... 262 "a-source":{ 263 "type": "uri", 264 "label": "source", 265 "resource": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf" 266 }, 267 ... 268 }, 269 ... 270 } 272 Figure 1: SOURCE mapping example 274 2.3.3. KIND 276 The KIND property is mapped to the "kind" member (Figure 2). Allowed 277 values are those described in Section 6.1.4 of [RFC6350] and extended 278 with the values declared in [RFC6473] and [RFC6869]. The value 279 "group" is reserved for a CardGroup instance. 281 BEGIN:VCARD 282 VERSION:4.0 283 ... 284 KIND:individual 285 ... 286 END:VCARD 288 { 289 ... 290 "kind": "individual", 291 ... 292 } 294 Figure 2: KIND mapping example 296 2.3.4. XML 298 The XML property doesn't have a direct match with a JSContact 299 feature. 301 2.4. Identification Properties 303 2.4.1. FN 305 All the FN instances are represented through the "fullName" member. 306 The presence of multiple instances is implicitly associated with the 307 full name translations in various languages regardless of the 308 presence of the ALTID parameter. Each translation corresponds to a 309 different entry of the "localizations" map (Figure 3). 311 If the vCard represents a group of contacts, implementers MAY convert 312 the FN property into either "CardGroup.card.fullName" or 313 "CardGroup.name" or both properties. 315 2.4.2. N and NICKNAME 317 The N instances are converted into equivalent items of the "name" 318 array (Figure 3): the N components are transformed into related 319 "NameComponent" objects as presented in Table 1. Name components 320 SHOULD be ordered such that their values joined by whitespace produce 321 a valid full name of this entity. 323 Each NICKNAME instance is mapped to an item of "nickNames" array. 325 +--------------------+--------------+ 326 | N component | "type" value | 327 +--------------------+--------------+ 328 | Honorific Prefixes | prefix | 329 | Given Names | personal | 330 | Family Names | surname | 331 | Additional Names | additional | 332 | Honorific Suffixes | suffix | 333 +--------------------+--------------+ 335 Table 1: N components mapping 337 BEGIN:VCARD 338 VERSION:4.0 339 ... 340 FN:Mr. John Q. Public\, Esq. 341 N:Public;John;Quinlan;Mr.;Esq. 342 NICKNAME:Johnny 343 ... 344 END:VCARD 346 { 347 ... 348 "fullName":{ "value": "Mr. John Q. Public, Esq." }, 349 "name":[ 350 { "value":"Mr.", "type": "prefix" }, 351 { "value":"John", "type": "personal" }, 352 { "value":"Public", "type": "surname" }, 353 { "value":"Quinlan", "type": "additional" }, 354 { "value":"Esq.", "type": "suffix" } 355 ], 356 "nickNames":[ 357 { "value": "Johnny" } 358 ], 359 ... 360 } 362 Figure 3: FN, N, NICKNAME mapping example 364 2.4.3. PHOTO 366 A PHOTO property is represented as an entry of the "photos" map 367 (Figure 4). The entry value is a "File" object whose "href" member 368 is the PHOTO value. 370 The PREF and MEDIATYPE parameters are mapped according to the rules 371 as defined in (Section 2.1). 373 BEGIN:VCARD 374 VERSION:4.0 375 ... 376 PHOTO:http://www.example.com/pub/photos/jqpublic.gif 377 ... 378 END:VCARD 380 { 381 ... 382 "photos":{ 383 ... 384 "a-photo":{ 385 "href": "http://www.example.com/pub/photos/jqpublic.gif" 386 }, 387 ... 388 }, 389 ... 390 } 392 Figure 4: PHOTO mapping example 394 2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 396 The BDAY and ANNIVERSARY properties and the extensions BIRTHPLACE, 397 DEATHDATE, DEATHPLACE described in [RFC6350] are represented as 398 "Anniversary" objects included in the "anniversaries" map (Figure 5): 400 o BDAY and BIRTHPLACE are mapped to "date" and "place" where "type" 401 is set to "birth"; 403 o DEATHDATE and DEATHPLACE are mapped to "date" and "place" where 404 "type" is set to "death"; 406 o ANNIVERSARY is mapped to "date" where "type" is set to "other" and 407 "label" is set to a value describing in detail the kind of 408 anniversary (e.g. "marriage date" for the wedding anniversary). 410 Both birth and death places are represented as instances of the 411 "Address" object. 413 The BIRTHPLACE and DEATHPLACE properties that are represented as geo 414 URIs are converted into "Address" instances including only the 415 "coordinates" member. If the URI value is not a geo URI, the place 416 is ignored. 418 The ALTID and LANGUAGE parameters of both BIRTHPLACE and DEATHPLACE 419 properties are mapped according to the rules as defined in 420 (Section 2.1). The "fullAddress.localizations" includes possible 421 language-dependent alternatives. 423 BEGIN:VCARD 424 VERSION:4.0 425 ... 426 BDAY:19531015T231000Z 427 BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A. 428 DEATHDATE:19960415 429 DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A. 430 ANNIVERSARY:19860201 431 ... 432 END:VCARD 434 { 435 ... 436 "anniversaries": { 437 "ANNIVERSARY-1" : { 438 "type": "birth", 439 "date": "1953-10-15T23:10:00Z", 440 "place":{ 441 "fullAddress":{ 442 "value": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A." 443 } 444 } 445 }, 446 "ANNIVERSARY-2" : { 447 "type": "birth", 448 "date": "1953-10-15T23:10:00Z", 449 "place":{ 450 "fullAddress":{ 451 "value": "4445 Courtright Street\nNew England, ND 58647\nU.S.A." 452 } 453 } 454 }, 455 "ANNIVERSARY-3" : { 456 "type": "other", 457 "label": "marriage date", 458 "date": "1986-02-01" 459 } 460 }, 461 ... 462 } 464 Figure 5: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 465 mapping example 467 2.4.5. GENDER 469 The GENDER property doesn't have a direct match with a JSContact 470 feature. 472 2.5. Delivery Addressing Properties 474 2.5.1. ADR 476 An ADR property is represented as an entry of the "addresses" map 477 (Figure 6). The entry value is an "Address" object. 479 The ADR components are transformed into the "Address" members as 480 presented in Table 2 and Table 3. 482 The "street address" and "extended address" ADR components MAY be 483 converted into either a single StreetComponent item or a combination 484 of StreetComponent items. 486 +---------------+----------------+ 487 | ADR component | Address member | 488 +---------------+----------------+ 489 | locality | locality | 490 | region | region | 491 | postal code | postcode | 492 | country name | country | 493 +---------------+----------------+ 495 Table 2: ADR components vs. Address members mapping 497 +-------------+---------------------+-------------------------------+ 498 | ADR | Single | Combination of | 499 | component | StreetComponent | StreetComponent items | 500 | | item | | 501 +-------------+---------------------+-------------------------------+ 502 | post office | postOfficeBox | | 503 | box | | | 504 | extended | extension | extension, building, floor, | 505 | address | | room, apartment | 506 | street | name | name, number, direction | 507 | address | | | 508 +-------------+---------------------+-------------------------------+ 510 Table 3: ADR components vs. StreetComponent items mapping 512 The LABEL parameter is converted into the "fullAddress" member. 514 The GEO parameter is converted into the "coordinates" member. 516 The TZ parameter is converted into the "timeZone" member. 518 The CC parameter as defined in [RFC8605] is converted into the 519 "countryCode" member. 521 The PREF and TYPE parameters are mapped according to the rules as 522 defined in (Section 2.1). 524 The ALTID and LANGUAGE parameters are mapped according to the rules 525 as defined in (Section 2.1). The "fullAddress.localizations" 526 includes possible language-dependent alternatives. 528 BEGIN:VCARD 529 VERSION:4.0 530 ... 531 ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA 532 ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA 533 ... 534 END:VCARD 536 { 537 ... 538 "addresses":{ 539 "work-address" :{ 540 "contexts":{ "work": true }, 541 "fullAddress":{ 542 "value": "54321 Oak St\nReston\nVA\n20190\nUSA" 543 }, 544 "street": [ 545 { "name": "Oak St" }, 546 { "number" : "54321" } 547 ], 548 "locality": "Reston", 549 "region": "VA", 550 "country": "USA", 551 "postcode": "20190", 552 "countryCode": "US" 553 }, 554 "private-address":{ 555 "contexts":{ "private": true }, 556 "fullAddress":{ 557 "value": "12345 Elm St\nReston\nVA\n20190\nUSA" 558 }, 559 "street": [ 560 { "name": "Elm St" }, 561 { "number" : "12345" } 562 ], 563 "locality": "Reston", 564 "region": "VA", 565 "country": "USA", 566 "postcode": "20190", 567 "countryCode": "US" 568 } 569 }, 570 ... 571 } 573 Figure 6: ADR mapping example 575 2.6. Communications Properties 577 2.6.1. TEL 579 A TEL property is represented as an entry of the "phones" map 580 (Figure 7). The entry value is a "Phone" object. The TEL-specific 581 values of the TYPE parameter are mapped to the "features" map keys. 582 The values that don't match a key are represented as comma-separated 583 values of the "label" member. If the "features" map is empty and the 584 "label" member is not empty, the "other" feature is added. The 585 "phone" member is set to the TEL value. 587 The PREF and TYPE parameters are mapped according to the rules as 588 defined in (Section 2.1). 590 BEGIN:VCARD 591 VERSION:4.0 592 ... 593 TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555 594 TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67 595 ... 596 END:VCARD 598 { 599 ... 600 "phones":{ 601 "a-phone":{ 602 "contexts":{ "private": true }, 603 "features":{ "voice": true }, 604 "phone": "tel:+1-555-555-5555;ext=5555", 605 "pref": 1 606 }, 607 "another-phone":{ 608 "contexts":{ "private": true }, 609 "phone": "tel:+33-01-23-45-67" 610 } 611 ], 612 ... 613 } 615 Figure 7: TEL mapping example 617 2.6.2. EMAIL 619 An EMAIL property is represented as an entry of the "emails" map 620 (Figure 8). The entry value is an "EmailAddress" object. The 621 "email" member is set to the EMAIL value. 623 The PREF and TYPE parameters are mapped according to the rules as 624 defined in (Section 2.1). 626 BEGIN:VCARD 627 VERSION:4.0 628 ... 629 EMAIL;TYPE=work:jqpublic@xyz.example.com 630 EMAIL;PREF=1:jane_doe@example.com 631 ... 632 END:VCARD 634 { 635 ... 636 "emails":{ 637 "work-email":{ 638 "contexts":{ "work": true }, 639 "email": "jqpublic@xyz.example.com" 640 }, 641 "private-email":{ 642 "contexts":{ "private", true }, 643 "email": "jane_doe@example.com", 644 "pref": 1 645 } 646 }, 647 ... 648 } 650 Figure 8: EMAIL mapping example 652 2.6.3. IMPP 654 An IMPP property is represented as an entry of the "online" map 655 (Figure 9). The entry value is a "Resource" object whose "type" 656 member is set to "username", the "label" member is set to "XMPP" and 657 the "resource" member is the IMPP value. 659 The PREF and TYPE parameters are mapped according to the rules as 660 defined in (Section 2.1). 662 BEGIN:VCARD 663 VERSION:4.0 664 ... 665 IMPP;PREF=1:xmpp:alice@example.com 666 ... 667 END:VCARD 669 { 670 ... 671 "online":{ 672 ... 673 { 674 "type": "username", 675 "label": "XMPP", 676 "value": "alice@example.com" 677 }, 678 ... 679 }, 680 ... 681 } 683 Figure 9: IMPP mapping example 685 2.6.4. LANG 687 A LANG property is represented as an entry of the 688 "preferredContactLanguages" map (Figure 10). The entry keys 689 correspond to the language tags, the corresponding entry values are 690 arrays of "ContactLanguage" objects. 692 The PREF and TYPE parameters are mapped according to the rules as 693 defined in (Section 2.1). 695 If both PREF and TYPE parameters are missing, the array of 696 "ContactLanguage" objects MUST be empty. 698 BEGIN:VCARD 699 VERSION:4.0 700 ... 701 LANG;TYPE=work;PREF=1:en 702 LANG;TYPE=work;PREF=2:fr 703 LANG;TYPE=home:fr 704 ... 705 END:VCARD 707 { 708 ... 709 "preferredContactLanguages":{ 710 "en":[ 711 { 712 "context": "work", 713 "pref": 1 714 } 715 ], 716 "fr":[ 717 { 718 "context": "work", 719 "pref": 2 720 }, 721 { 722 "context": "private" 723 } 724 ] 725 }, 726 ... 727 } 729 Figure 10: LANG mapping example 731 2.7. Geographical Properties 733 The GEO and TZ properties are not directly mapped to topmost Card 734 members because the same information is represented through 735 equivalent "Address" members. 737 The ALTID parameter is used for associating both GEO and TZ 738 properties with the related address information. When the ALTID 739 parameter is missing, the matched members SHOULD be included in the 740 first "Address" object. 742 2.7.1. Time Zone Representation 744 As specified in Section 6.5.1 of [RFC6350], the time zone information 745 can be represented in three ways: as a time zone name, as a UTC 746 offset or as a URI. 748 o If the TZ value is defined in the IANA timezone database, it is 749 directly matched by the "timeZone" member in JSContact. 751 o An UTC offset with zero minutes MUST be converted into one its 752 equivalent IANA "Etc/GMT" time zone to set in the "timeZone" 753 property. For example, the value "-0500" converts to "Etc/GMT+5". 754 Implementations MUST make sure that such IANA timezone exists. 756 o An UTC offset with non-zero minutes MAY be converted to a custom 757 "TimeZone" object in the JSContact "timeZones" property (see 758 example below). 760 o A non-IANA timezone name or URI MAY be converted to a custom 761 "TimeZone" object in the JSContact "timeZones" property. It is up 762 to the implementation to determine the time zone definition. 764 BEGIN:VCARD 765 VERSION:4.0 766 ... 767 ADR;TZ=-0530:;;123 Main Street;Any Town;CA;91921-1234;U.S.A. 768 ... 769 END:VCARD 771 { 772 ... 773 "addresses": { 774 "addr1" : { 775 "timeZone": "/tz1" 776 ... 777 } 778 }, 779 "timeZones": { 780 "/tz1": { 781 "@type": "TimeZone", 782 "tzId": "TZ-0530", 783 "updated": "2021-06-07T14:24:45Z", 784 "standard": [{ 785 "@type": "TimeZoneRule", 786 "offsetFrom": "-0530", 787 "offsetTo": "-0530", 788 "start": "1601-01-01T00:00:00" 789 }] 790 } 791 } 792 ... 793 } 795 Figure 11: Mapping a TZ UTC offset value with non-zero minutes 797 2.8. Organizational Properties 799 2.8.1. TITLE and ROLE 801 Both TITLE and ROLE properties are represented as entries of the 802 "titles" map (Figure 12). The entry value is a "Title" object whose 803 "title" member includes information about the language. 805 The ALTID and LANGUAGE parameters are mapped according to the rules 806 as defined in (Section 2.1). The "title.localizations" includes 807 possible language-dependent alternatives. 809 BEGIN:VCARD 810 VERSION:4.0 811 ... 812 TITLE:Research Scientist 813 ROLE:Project Leader 814 ... 815 END:VCARD 817 { 818 ... 819 "titles":{ 820 "a-title":{ 821 "title":{ "value" : "Project Leader" } 822 }, 823 "another-title":{ 824 "title":{ "value" : "Research Scientist" } 825 } 826 }, 827 ... 828 } 830 Figure 12: TITLE and ROLE mapping example 832 2.8.2. LOGO 834 A LOGO property is represented as an entry of the "online" map 835 (Figure 13). The entry value is a "Resource" object whose "type" 836 member is set to "uri", the "label" member is set to "logo" and the 837 "resource" member is the LOGO value. 839 The PREF and TYPE parameters are mapped according to the rules as 840 defined in (Section 2.1). 842 BEGIN:VCARD 843 VERSION:4.0 844 ... 845 LOGO:http://www.example.com/pub/logos/abccorp.jpg 846 ... 847 END:VCARD 849 { 850 ... 851 "online":{ 852 ... 853 "a-logo":{ 854 "type": "uri", 855 "label": "logo", 856 "resource": "http://www.example.com/pub/logos/abccorp.jpg" 857 }, 858 ... 859 }, 860 ... 861 } 863 Figure 13: LOGO mapping example 865 2.8.3. ORG 867 An ORG property is represented as an entry of the "organizations" map 868 (Figure 14). The entry value is an "Organization" object whose 869 "name" member contains the organizational name and the "units" member 870 contains the organizational units. 872 The ALTID and LANGUAGE parameters are mapped according to the rules 873 as defined in (Section 2.1). The "localizations" maps for both 874 "name" and "units" include possible language-dependent alternatives. 876 BEGIN:VCARD 877 VERSION:4.0 878 ... 879 ORG:ABC\, Inc.;North American Division;Marketing 880 ... 881 END:VCARD 883 { 884 ... 885 "organizations":{ 886 "an-organization":{ 887 "name":{ "value": "ABC, Inc." }, 888 "units":[ 889 { "value": "North American Division" }, 890 { "value": "Marketing" } 891 ] 892 } 893 }, 894 ... 895 } 897 Figure 14: ORG mapping example 899 2.8.4. MEMBER 901 According to the JSContact specification, a group of contact cards is 902 represented through a CardGroup (Figure 15). The uids of the contact 903 cards composing the group are included in the "members" map. 905 In this case, the PREF parameter has not a JSContact counterpart; 906 however, the implementers MAY insert the map entries by order of 907 preference. 909 BEGIN:VCARD 910 VERSION:4.0 911 KIND:group 912 FN:The Doe family 913 MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 914 MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 915 END:VCARD 917 { 918 "kind": "group", 919 "fullName":{ "value": "The Doe family" }, 920 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 921 "members":{ 922 "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, 923 "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true 924 } 925 } 927 Figure 15: Group example 929 Only if the GROUP contains properties that don't have a mapping to 930 CardGroup properties, then the CardGroup.card property MAY contain 931 the optional Card object of this group. 933 { 934 "name": "The Doe family", 935 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 936 "members":{ 937 "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, 938 "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true 939 }, 940 "card": { 941 "fullName":{ "value": "The Doe family" }, 942 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 943 "photos":{ 944 "a-photo":{ 945 "href": "http://www.example.com/pub/photos/jqpublic.gif" 946 } 947 } 948 } 949 } 951 Figure 16: card member of CardGroup object 953 2.8.5. RELATED 955 All the RELATED instances are converted into the "relatedTo" map 956 (Figure 17): an entry for each entity the entity described by the 957 Card is associated with. The map keys are the "uid" values of the 958 associated cards. 960 Each map value is a "Relation" object including only the "relation" 961 member represented as a set of the RELATED-specific values of the 962 TYPE parameter as defined in Section 6.6.6 of [RFC6350]. 964 If the relation type is unspecified, the "relation" member MUST be 965 empty. 967 BEGIN:VCARD 968 VERSION:4.0 969 ... 970 RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 971 RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf 972 RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries. 973 ... 974 END:VCARD 976 { 977 ... 978 "relatedTo":{ 979 { 980 "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6":{ 981 "relation":{ "friend": true } 982 } 983 }, 984 { 985 "http://example.com/directory/jdoe.vcf":{ 986 "relation":{ "contact": true } 987 } 988 }, 989 { 990 "Please contact my assistant Jane Doe for any inquiries.":{ 991 "relation":{ } 992 } 993 } 994 }, 995 ... 996 } 998 Figure 17: RELATED mapping example 1000 2.8.6. CONTACT-URI 1002 A CONTACT-URI property as defined in [RFC8605] is represented as an 1003 entry of the "online" map (Figure 18). The entry value is a 1004 "Resource" object whose "type" member is set to "uri", the "label" 1005 member is set to "contact-uri" and the "resource" member is the 1006 CONTACT-URI value. 1008 The PREF and TYPE parameters are mapped according to the rules as 1009 defined in (Section 2.1). 1011 BEGIN:VCARD 1012 VERSION:4.0 1013 ... 1014 CONTACT-URI;PREF=1:mailto:contact@example.com 1015 ... 1016 END:VCARD 1018 { 1019 ... 1020 "online":{ 1021 ... 1022 "a-contact-uri":{ 1023 "type": "uri", 1024 "label": "contact-uri", 1025 "resource": "mailto:contact@example.com", 1026 "pref": 1 1027 }, 1028 ... 1029 }, 1030 ... 1031 } 1033 Figure 18: CONTACT-URI mapping example 1035 2.9. Personal Information Properties 1037 The LEVEL parameter as defined in [RFC6715] is directly mapped to the 1038 "level" property of the "PersonalInformation" type apart from when 1039 LEVEL is used in the EXPERTISE property; in this case, the values are 1040 converted as in the following: 1042 o "beginner" is converted into "low"; 1043 o "average" is converted into "medium"; 1044 o "expert" is converted into "high". 1046 2.9.1. EXPERTISE 1048 An EXPERTISE property as defined in [RFC6715] is represented as a 1049 "PersonalInformation" object in the "personalInfo" map (Figure 19). 1050 The "type" member is set to "expertise". 1052 The INDEX parameter is represented as the index of the expertise 1053 among the declared expertises. 1055 BEGIN:VCARD 1056 VERSION:4.0 1057 ... 1058 EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature 1059 EXPERTISE;INDEX=1;LEVEL=expert:chemistry 1060 ... 1061 END:VCARD 1063 { 1064 ... 1065 "personalInfo":{ 1066 ... 1067 "PERSINFO-1" : { 1068 "type": "expertise", 1069 "value": "chemistry", 1070 "level": "high" 1071 }, 1072 "PERSINFO-2" : { 1073 "type": "expertise", 1074 "value": "chinese literature", 1075 "level": "low" 1076 }, 1077 ... 1078 }, 1079 ... 1080 } 1082 Figure 19: EXPERTISE mapping example 1084 2.9.2. HOBBY 1086 A HOBBY property as defined in [RFC6715] is represented as a 1087 "PersonalInformation" object in the "personalInfo" map (Figure 20). 1088 The "type" member is set to "hobby". 1090 The INDEX parameter is represented as the index of the hobby among 1091 the declared hobbies. 1093 BEGIN:VCARD 1094 VERSION:4.0 1095 ... 1096 HOBBY;INDEX=1;LEVEL=high:reading 1097 HOBBY;INDEX=2;LEVEL=high:sewing 1098 ... 1099 END:VCARD 1101 { 1102 ... 1103 "personalInfo":{ 1104 ... 1105 "PERSINFO-1" : { 1106 "type": "hobby", 1107 "value": "reading", 1108 "level": "high" 1109 }, 1110 "PERSINFO-2" : { 1111 "type": "hobby", 1112 "value": "sewing", 1113 "level": "high" 1114 }, 1115 ... 1116 }, 1117 ... 1118 } 1120 Figure 20: HOBBY mapping example 1122 2.9.3. INTEREST 1124 An INTEREST property as defined in [RFC6715] is represented as a 1125 "PersonalInformation" object in the "personalInfo" map (Figure 21). 1126 The "type" member is set to "interest". 1128 The INDEX parameter is represented as the index of the interest among 1129 the declared interests. 1131 BEGIN:VCARD 1132 VERSION:4.0 1133 ... 1134 INTEREST;INDEX=1;LEVEL=medium:r&b music 1135 INTEREST;INDEX=2;LEVEL=high:rock 'n' roll music 1136 ... 1137 END:VCARD 1139 { 1140 ... 1141 "personalInfo":{ 1142 ... 1143 "PERSINFO-1" : { 1144 "type": "interest", 1145 "value": "r&b music", 1146 "level": "medium" 1147 }, 1148 "PERSINFO-2" : { 1149 "type": "interest", 1150 "value": "rock 'n' roll music", 1151 "level": "high" 1152 }, 1153 ... 1154 }, 1155 ... 1156 } 1158 Figure 21: INTEREST mapping example 1160 2.9.4. ORG-DIRECTORY 1162 An ORG-DIRECTORY property is represented as an entry of the "online" 1163 map (Figure 22). The entry value is a "Resource" object whose "type" 1164 member is set to "uri", the "label" member is set to "org-directory" 1165 and the "resource" member is the ORG-DIRECTORY value. 1167 The PREF and TYPE parameters are mapped according to the rules as 1168 defined in (Section 2.1). 1170 The INDEX parameter is represented as the index of the directory 1171 among the online resources with the "org-directory" label. 1173 BEGIN:VCARD 1174 VERSION:4.0 1175 ... 1176 ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com 1177 ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering 1178 ... 1179 END:VCARD 1181 { 1182 ... 1183 "online":{ 1184 ... 1185 "an-org-directory":{ 1186 "type": "uri", 1187 "label": "org-directory", 1188 "resource": "http://directory.mycompany.example.com" 1189 }, 1190 "another-org-directory":{ 1191 "type": "uri", 1192 "label": "org-directory", 1193 "resource": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering", 1194 "pref": 1 1195 }, 1196 ... 1197 }, 1198 ... 1199 } 1201 Figure 22: ORG-DIRECTORY mapping example 1203 2.10. Explanatory Properties 1205 2.10.1. CATEGORIES 1207 A CATEGORIES property is converted into a set of entries of the 1208 "categories" map (Figure 23). The keys are the comma-separated text 1209 values of the CATEGORIES property. 1211 In this case, the PREF parameter has not a JSContact counterpart; 1212 however, implementers MAY use a map preserving the order of insertion 1213 and the map entries can be inserted by order of preference. 1215 BEGIN:VCARD 1216 VERSION:4.0 1217 ... 1218 CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY 1219 ... 1220 END:VCARD 1222 { 1223 ... 1224 "categories":{ 1225 "INTERNET": true, 1226 "IETF": true, 1227 "INDUSTRY": true, 1228 "INFORMATION TECHNOLOGY": true 1229 }, 1230 ... 1231 } 1233 Figure 23: CATEGORIES mapping example 1235 2.10.2. NOTE 1237 A NOTE property is mapped to the "notes" property (Figure 24). All 1238 the NOTE instances are condensed into a single note and separated by 1239 newline. 1241 The ALTID and LANGUAGE parameters are mapped according to the rules 1242 as defined in (Section 2.1). The "localizations" map includes 1243 possible language-dependent alternatives. 1245 BEGIN:VCARD 1246 VERSION:4.0 1247 ... 1248 NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri. 1249 ... 1250 END:VCARD 1252 { 1253 ... 1254 "notes": { 1255 "value": "This fax number is operational 0800 to 1715 EST, Mon-Fri." 1256 }, 1257 ... 1258 } 1260 Figure 24: NOTE mapping example 1262 2.10.3. PRODID 1264 The PRODID property is converted into the "prodId" member 1265 (Figure 25). 1267 BEGIN:VCARD 1268 VERSION:4.0 1269 ... 1270 PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN 1271 ... 1272 END:VCARD 1274 { 1275 ... 1276 "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN", 1277 ... 1278 } 1280 Figure 25: PRODID mapping example 1282 2.10.4. REV 1284 The REV property is transformed into the "updated" member 1285 (Figure 26). 1287 BEGIN:VCARD 1288 VERSION:4.0 1289 ... 1290 REV:19951031T222710Z 1291 ... 1292 END:VCARD 1294 { 1295 ... 1296 "updated": "1995-10-31T22:27:10Z", 1297 ... 1298 } 1300 Figure 26: REV mapping example 1302 2.10.5. SOUND 1304 A SOUND property is represented as an entry of the "online" map 1305 (Figure 27). The entry value is a "Resource" object whose "type" 1306 member is set to "uri", the "label" member is set to "sound" and the 1307 "resource" member is the SOUND value. 1309 The PREF and TYPE parameters are mapped according to the rules as 1310 defined in (Section 2.1). 1312 BEGIN:VCARD 1313 VERSION:4.0 1314 ... 1315 SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com 1316 ... 1317 END:VCARD 1319 { 1320 ... 1321 "online":{ 1322 ... 1323 "a-sound":{ 1324 "type": "uri", 1325 "label": "sound", 1326 "resource": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com" 1327 }, 1328 ... 1329 }, 1330 ... 1331 } 1333 Figure 27: SOUND mapping example 1335 2.10.6. UID 1337 The UID property corresponds to the "uid" property (Figure 28) in 1338 both Card and CardGroup. 1340 BEGIN:VCARD 1341 VERSION:4.0 1342 ... 1343 UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 1344 ... 1345 END:VCARD 1347 { 1348 ... 1349 "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6", 1350 ... 1351 } 1353 Figure 28: UID mapping example 1355 2.10.7. CLIENTPIDMAP and PID Parameter 1357 The CLIENTPIDMAP property and the PDI parameter don't have a direct 1358 match with a Card feature. 1360 2.10.8. URL 1362 An URL property is represented as an entry of the "online" map 1363 (Figure 29). The entry value is a "Resource" object whose "type" 1364 member is set to "uri", the "label" member is set to "url" and the 1365 "resource" member is the URL value. 1367 The PREF and TYPE parameters are mapped according to the rules as 1368 defined in (Section 2.1). 1370 BEGIN:VCARD 1371 VERSION:4.0 1372 ... 1373 URL:http://example.org/restaurant.french/~chezchic.html 1374 ... 1375 END:VCARD 1377 { 1378 ... 1379 "online":{ 1380 ... 1381 "an-url":{ 1382 "type": "uri", 1383 "label": "url", 1384 "resource": "http://example.org/restaurant.french/~chezchic.html" 1385 }, 1386 ... 1387 }, 1388 ... 1389 } 1391 Figure 29: URL mapping example 1393 2.10.9. VERSION 1395 The VERSION property doesn't have a direct match with a JSContact 1396 feature. 1398 2.11. Security Properties 1399 2.11.1. KEY 1401 A KEY property is represented as an entry of the "online" map 1402 (Figure 30). The entry value is a "Resource" object whose "type" 1403 member is set to "uri", the "label" member is set to "key" and the 1404 "resource" member is the KEY value. 1406 The PREF and TYPE parameters are mapped according to the rules as 1407 defined in (Section 2.1). 1409 BEGIN:VCARD 1410 VERSION:4.0 1411 ... 1412 KEY:http://www.example.com/keys/jdoe.cer 1413 ... 1414 END:VCARD 1416 { 1417 ... 1418 "online":{ 1419 ... 1420 "a-key":{ 1421 "type": "uri", 1422 "label": "key", 1423 "resource": "http://www.example.com/keys/jdoe.cer" 1424 }, 1425 ... 1426 }, 1427 ... 1428 } 1430 Figure 30: KEY mapping example 1432 2.12. Calendar Properties 1434 2.12.1. FBURL 1436 An FBURL property is represented as an entry of the "online" map 1437 (Figure 31). The entry value is a "Resource" object whose "type" 1438 member is set to "uri", the "label" member is set to "fburl" and the 1439 "resource" member is the FBURL value. 1441 The PREF and TYPE parameters are mapped according to the rules as 1442 defined in (Section 2.1). 1444 BEGIN:VCARD 1445 VERSION:4.0 1446 ... 1447 FBURL;PREF=1:http://www.example.com/busy/janedoe 1448 FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb 1449 ... 1450 END:VCARD 1452 { 1453 ... 1454 "online":{ 1455 ... 1456 "an-fburl":{ 1457 "type": "uri", 1458 "label": "fburl", 1459 "resource": "http://www.example.com/busy/janedoe", 1460 "pref": 1 1461 }, 1462 "another-fburl":{ 1463 "type": "uri", 1464 "label": "fburl", 1465 "resource": "ftp://example.com/busy/project-a.ifb", 1466 "mediaType": "text/calendar" 1467 }, 1468 ... 1469 }, 1470 ... 1471 } 1473 Figure 31: FBURL mapping example 1475 2.12.2. CALADRURI 1477 A CALADRURI property is represented as an entry of the "online" map 1478 (Figure 32). The entry value is a "Resource" object whose "type" 1479 member is set to "uri", the "label" member is set to "caladruri" and 1480 the "resource" member is the CALADRURI value. 1482 The PREF and TYPE parameters are mapped according to the rules as 1483 defined in (Section 2.1). 1485 BEGIN:VCARD 1486 VERSION:4.0 1487 ... 1488 CALADRURI;PREF=1:mailto:janedoe@example.com 1489 CALADRURI:http://example.com/calendar/jdoe 1490 ... 1491 END:VCARD 1493 { 1494 ... 1495 "online":{ 1496 ... 1497 "a-caladruri":{ 1498 "type": "uri", 1499 "label": "caladruri", 1500 "resource": "mailto:janedoe@example.com", 1501 "pref": 1 1502 }, 1503 "another-caladruri":{ 1504 "type": "uri", 1505 "label": "caladruri", 1506 "resource": "http://example.com/calendar/jdoe" 1507 }, 1508 ... 1509 }, 1510 ... 1511 } 1513 Figure 32: CALADRURI mapping example 1515 2.12.3. CALURI 1517 A CALURI property is represented as an entry of the "online" map 1518 (Figure 33). The entry value is a "Resource" object whose "type" 1519 member is set to "uri", the "label" member is set to "caluri" and the 1520 "resource" member is the CALURI value. 1522 The PREF and TYPE parameters are mapped according to the rules as 1523 defined in (Section 2.1). 1525 BEGIN:VCARD 1526 VERSION:4.0 1527 ... 1528 CALURI;PREF=1:http://cal.example.com/calA 1529 CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics 1530 ... 1531 END:VCARD 1533 { 1534 ... 1535 "online":{ 1536 ... 1537 "a-caluri":{ 1538 "type": "uri", 1539 "label": "caluri", 1540 "resource": "http://cal.example.com/calA", 1541 "pref": 1 1542 }, 1543 "another-caluri":{ 1544 "type": "uri", 1545 "label": "caluri", 1546 "resource": "ftp://ftp.example.com/calA.ics", 1547 "mediaType": "text/calendar" 1548 }, 1549 ... 1550 }, 1551 ... 1552 } 1554 Figure 33: CALURI mapping example 1556 2.13. vCard Unmatched Properties 1558 The unmatched vCard properties MAY be converted into JSContact 1559 properties whose name contains the prefix "ietf.org/RFC6350/" 1560 followed by property name in uppercase (i.e. ietf.org/RFC6350/ 1561 GENDER"). 1563 2.14. Card Required Properties 1565 While converting a vCard into a Card/CardGroup, only the topmost 1566 "uid" member is mandatory. Implementers are REQUIRED to set it when 1567 it is missing. 1569 3. Translating JSContact properties to vCard 1571 In most of the cases, the rules about the translation from Card/ 1572 CardGroup to vCard can be derived by reversing the rules presented in 1573 Section 2. The remaining cases are treated in the following of this 1574 section. 1576 3.1. Id 1578 Where a map key is of type Id, implementers are free to either ignore 1579 it or preserve it as a vCard information (e.g. a vCard parameter). 1581 3.2. Localizations 1583 A LocalizedString object is converted in multiple instances of the 1584 same vCard property having different values of the LANGUAGE 1585 parameter. Implementers MAY set the ALTID parameter to couple 1586 language-based alternatives of the same value. 1588 Note also that the components of some vCard values and their related 1589 alternatives are split into different JSContact values. For example, 1590 the "name" and "units" values for a given language must be grouped to 1591 make a single ORG value where components are separated by ";". 1593 3.3. Date and Time Representations 1595 The JSContact spec defines the "UTCDateTime" type to represent 1596 [RFC3339] "date-time" format with further restrictions. This means 1597 that the matched vCard format for a "UTCDateTime" value MUST be one 1598 of the formats shown in Section 4.3.5 of [RFC6350] (i.e. 1599 "19961022T140000Z"). 1601 In addition to such format, the "date" member of the "Anniversary" 1602 type allows specifying both a date without the time and a partial 1603 date. In this case, the corresponding vCard format is that defined 1604 in Section 4.3.1. 1606 3.4. Time Zone 1608 The time zone name as represented by the "timeZone" property is 1609 mapped to the TZ parameter. 1611 Implementers MAY map an "Etc/GMT" time zone either preserving the 1612 time zone name or converting it into a UTC offset. 1614 3.5. JSContact Types Matching Multiple vCard Properties 1616 3.5.1. Title 1618 The "titles" property contains information about the job, the 1619 position or the role of the entity the card represents. In vCard, 1620 such information is split into the TITLE and ROLE properties. This 1621 specification defines TITLE as the default target property when 1622 converting the "titles" property. 1624 3.5.2. Resource 1626 The "online" property includes resources that are usually represented 1627 through different vCard properties. The matched vCard property of a 1628 "Resource" object can be derived from the value of its "label" 1629 member. 1631 Any resource included in the "online" map that doesn't match a vCard 1632 property MAY be converted into vCard extended properties. 1634 3.6. CardGroup 1636 A CardGroup object is converted into a vCard by merging its 1637 properties with the properties of "CardGroup.card" object. If the 1638 "CardGroup.card.fullName" property exists, it MUST be used to set the 1639 FN value. 1641 3.7. Card Unmatched Properties 1643 Both the "preferredContactMethod" and "created" members don't match 1644 any vCard property. Implementers MAY represent them as vCard 1645 extended properties. 1647 3.8. vCard Required Properties 1649 While converting a Card/CardGroup into a vCard, only the FN property 1650 is required. Since both the "Card.fullName" and "CardGroup.name" 1651 properties are optional, implementers are REQUIRED to generate an FN 1652 value when it is missing. 1654 4. IANA Considerations 1656 This document has no actions for IANA. 1658 5. Implementation Status 1660 NOTE: Please remove this section and the reference to RFC 7942 prior 1661 to publication as an RFC. 1663 This section records the status of known implementations of the 1664 protocol as defined in this specification at the time of posting of 1665 this Internet-Draft, and is based on a proposal described in 1666 [RFC7942]. The description of implementations in this section is 1667 intended to assist the IETF in its decision processes in progressing 1668 drafts to RFCs. Please note that the listing of any individual 1669 implementation here does not imply endorsement by the IETF. 1670 Furthermore, no effort has been spent to verify the information 1671 presented here that was supplied by IETF contributors. This is not 1672 intended as, and must not be construed to be, a catalog of available 1673 implementations or their features. Readers are advised to note that 1674 other implementations may exist. 1676 According to RFC 7942, "this will allow reviewers and working groups 1677 to assign due considerationto documents that have the benefit of 1678 running code, which may serve as evidence of valuable experimentation 1679 and feedback that have made the implemented protocols more mature. 1680 It is up to the individual working groups to use this information as 1681 they see fit". 1683 5.1. CNR 1685 Responsible Organization: National Research Council (CNR) of Italy 1686 Location: https://github.com/consiglionazionaledellericerche/ 1687 jscontact-tools 1688 Description: This implementation includes tools for JSContact 1689 creation, validation, serialization/deserialization, and 1690 conversion from vCard, xCard and jCard. 1691 Level of Maturity: This is an "alpha" test implementation. 1692 Coverage: This implementation includes all of the features 1693 described in this specification. 1694 Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it 1696 6. Security Considerations 1698 This document doesn't present any security consideration. 1700 7. References 1701 7.1. Normative References 1703 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1704 Requirement Levels", BCP 14, RFC 2119, 1705 DOI 10.17487/RFC2119, March 1997, 1706 . 1708 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1709 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1710 . 1712 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 1713 DOI 10.17487/RFC6350, August 2011, 1714 . 1716 [RFC6473] Saint-Andre, P., "vCard KIND:application", RFC 6473, 1717 DOI 10.17487/RFC6473, December 2011, 1718 . 1720 [RFC6474] Li, K. and B. Leiba, "vCard Format Extensions: Place of 1721 Birth, Place and Date of Death", RFC 6474, 1722 DOI 10.17487/RFC6474, December 2011, 1723 . 1725 [RFC6715] Cauchie, D., Leiba, B., and K. Li, "vCard Format 1726 Extensions: Representing vCard Extensions Defined by the 1727 Open Mobile Alliance (OMA) Converged Address Book (CAB) 1728 Group", RFC 6715, DOI 10.17487/RFC6715, August 2012, 1729 . 1731 [RFC6869] Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard 1732 KIND:device", RFC 6869, DOI 10.17487/RFC6869, February 1733 2013, . 1735 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 1736 DOI 10.17487/RFC7095, January 2014, 1737 . 1739 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1740 Code: The Implementation Status Section", BCP 205, 1741 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1742 . 1744 [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: 1745 ICANN Extensions for the Registration Data Access Protocol 1746 (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, 1747 . 1749 7.2. Informative References 1751 [draft-ietf-jmap-jscontact] 1752 "JSContact: A JSON representation of contact data", 1753 . 1756 [time-zones] 1757 "Time Zone Database", . 1759 [uri-schemes] 1760 "Uniform Resource Identifier (URI) Schemes", 1761 . 1764 Authors' Addresses 1766 Mario Loffredo 1767 IIT-CNR/Registro.it 1768 Via Moruzzi,1 1769 Pisa 56124 1770 IT 1772 Email: mario.loffredo@iit.cnr.it 1773 URI: http://www.iit.cnr.it 1775 Robert Stepanek 1776 FastMail 1777 PO Box 234, Collins St West 1778 Melbourne VIC 8007 1779 AU 1781 Email: rsto@fastmailteam.com 1782 URI: https://www.fastmail.com