idnits 2.17.1 draft-ietf-jmap-jscontact-vcard-04.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 (May 28, 2021) is 1054 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 1686, 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: November 29, 2021 FastMail 6 May 28, 2021 8 JSContact: Converting from and to vCard 9 draft-ietf-jmap-jscontact-vcard-04 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 November 29, 2021. 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 . . . . . . . . . . . . . . . . 18 80 2.8.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 18 81 2.8.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 19 82 2.8.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 20 83 2.8.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 21 84 2.8.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 23 85 2.8.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 24 86 2.9. Personal Information Properties . . . . . . . . . . . . . 24 87 2.9.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 25 88 2.9.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 25 89 2.9.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 26 90 2.9.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 27 91 2.10. Explanatory Properties . . . . . . . . . . . . . . . . . 28 92 2.10.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 28 93 2.10.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 29 94 2.10.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 30 95 2.10.4. REV . . . . . . . . . . . . . . . . . . . . . . . . 30 96 2.10.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . 30 97 2.10.6. UID . . . . . . . . . . . . . . . . . . . . . . . . 31 98 2.10.7. CLIENTPIDMAP and PID Parameter . . . . . . . . . . . 32 99 2.10.8. URL . . . . . . . . . . . . . . . . . . . . . . . . 32 100 2.10.9. VERSION . . . . . . . . . . . . . . . . . . . . . . 32 101 2.11. Security Properties . . . . . . . . . . . . . . . . . . . 32 102 2.11.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . 33 103 2.12. Calendar Properties . . . . . . . . . . . . . . . . . . . 33 104 2.12.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 33 105 2.12.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 34 106 2.12.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 35 107 2.13. vCard Unmatched Properties . . . . . . . . . . . . . . . 36 108 2.14. Card Required Properties . . . . . . . . . . . . . . . . 36 109 3. Translating JSContact properties to vCard . . . . . . . . . . 37 110 3.1. Id . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 111 3.2. Localizations . . . . . . . . . . . . . . . . . . . . . . 37 112 3.3. Date and Time Representations . . . . . . . . . . . . . . 37 113 3.4. Time Zone . . . . . . . . . . . . . . . . . . . . . . . . 37 114 3.5. JSContact Types Matching Multiple vCard Properties . . . 38 115 3.5.1. Title . . . . . . . . . . . . . . . . . . . . . . . . 38 116 3.5.2. Resource . . . . . . . . . . . . . . . . . . . . . . 38 117 3.6. CardGroup . . . . . . . . . . . . . . . . . . . . . . . . 38 118 3.7. Card Unmatched Properties . . . . . . . . . . . . . . . . 38 119 3.8. vCard Required Properties . . . . . . . . . . . . . . . . 38 120 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 121 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 39 122 5.1. CNR . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 123 6. Security Considerations . . . . . . . . . . . . . . . . . . . 39 124 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 125 7.1. Normative References . . . . . . . . . . . . . . . . . . 40 126 7.2. Informative References . . . . . . . . . . . . . . . . . 41 127 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 41 129 1. Introduction 131 1.1. Motivation 133 The JSContact specification [draft-ietf-jmap-jscontact] has been 134 defined to represent contact card information as a more efficient 135 alternative to vCard [RFC6350] and its JSON-based version named jCard 136 [RFC7095]. 138 While new applications might adopt JSContact as their main format to 139 exchange contact card data, they are likely to interoperate with 140 services and clients that just support vCard/jCard. Similarly, 141 existing contact data providers and consumers already using vCard/ 142 jCard might want to represent their data also according to the 143 JSContact specification. 145 To facilitate this, this document defines how to convert contact 146 information as defined in the JSContact [draft-ietf-jmap-jscontact] 147 specification from and to vCard. 149 1.2. Scope and Caveats 151 JSContact and vCard have a lot of semantics in common, however some 152 differences must be outlined: 154 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" array 399 (Figure 5): 401 o BDAY and BIRTHPLACE are mapped to "date" and "place" where "type" 402 is set to "birth"; 404 o DEATHDATE and DEATHPLACE are mapped to "date" and "place" where 405 "type" is set to "death"; 407 o ANNIVERSARY is mapped to "date" where "type" is set to "other" and 408 "label" is set to a value describing in detail the kind of 409 anniversary (e.g. "marriage date" for the wedding anniversary). 411 Both birth and death places are represented as instances of the 412 "Address" object. 414 The BIRTHPLACE and DEATHPLACE properties that are represented as geo 415 URIs are converted into "Address" instances including only the 416 "coordinates" member. If the URI value is not a geo URI, the place 417 is ignored. 419 The ALTID and LANGUAGE parameters of both BIRTHPLACE and DEATHPLACE 420 properties are mapped according to the rules as defined in 421 (Section 2.1). The "fullAddress.localizations" includes possible 422 language-dependent alternatives. 424 BEGIN:VCARD 425 VERSION:4.0 426 ... 427 BDAY:19531015T231000Z 428 BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A. 429 DEATHDATE:19960415 430 DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A. 431 ANNIVERSARY:19860201 432 ... 433 END:VCARD 435 { 436 ... 437 "anniversaries":[ 438 { 439 "type": "birth", 440 "date": "1953-10-15T23:10:00Z", 441 "place":{ 442 "fullAddress":{ 443 "value": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A." 444 } 445 } 446 }, 447 { 448 "type": "birth", 449 "date": "1953-10-15T23:10:00Z", 450 "place":{ 451 "fullAddress":{ 452 "value": "4445 Courtright Street\nNew England, ND 58647\nU.S.A." 453 } 454 } 455 }, 456 { 457 "type": "other", 458 "label": "marriage date", 459 "date": "1986-02-01" 460 } 461 ], 462 ... 463 } 465 Figure 5: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 466 mapping example 468 2.4.5. GENDER 470 The GENDER property doesn't have a direct match with a JSContact 471 feature. 473 2.5. Delivery Addressing Properties 475 2.5.1. ADR 477 An ADR property is represented as an entry of the "addresses" map 478 (Figure 6). The entry value is an "Address" object. 480 The ADR components are transformed into the "Address" members as 481 presented in Table 2 and Table 3. 483 The "street address" and "extended address" ADR components MAY be 484 converted into either a single StreetComponent item or a combination 485 of StreetComponent items. 487 +---------------+----------------+ 488 | ADR component | Address member | 489 +---------------+----------------+ 490 | locality | locality | 491 | region | region | 492 | postal code | postcode | 493 | country name | country | 494 +---------------+----------------+ 496 Table 2: ADR components vs. Address members mapping 498 +-------------+---------------------+-------------------------------+ 499 | ADR | Single | Combination of | 500 | component | StreetComponent | StreetComponent items | 501 | | item | | 502 +-------------+---------------------+-------------------------------+ 503 | post office | postOfficeBox | | 504 | box | | | 505 | extended | extension | extension, building, floor, | 506 | address | | room, apartment | 507 | street | name | name, number, direction | 508 | address | | | 509 +-------------+---------------------+-------------------------------+ 511 Table 3: ADR components vs. StreetComponent items mapping 513 The LABEL parameter is converted into the "fullAddress" member. 515 The GEO parameter is converted into the "coordinates" member. 517 The TZ parameter is converted into the "timeZone" member. 519 The CC parameter as defined in [RFC8605] is converted into the 520 "countryCode" member. 522 The PREF and TYPE parameters are mapped according to the rules as 523 defined in (Section 2.1). 525 The ALTID and LANGUAGE parameters are mapped according to the rules 526 as defined in (Section 2.1). The "fullAddress.localizations" 527 includes possible language-dependent alternatives. 529 BEGIN:VCARD 530 VERSION:4.0 531 ... 532 ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA 533 ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA 534 ... 535 END:VCARD 537 { 538 ... 539 "addresses":{ 540 "work-address" :{ 541 "contexts":{ "work": true }, 542 "fullAddress":{ 543 "value": "54321 Oak St\nReston\nVA\n20190\nUSA" 544 }, 545 "street": [ 546 { "name": "Oak St" }, 547 { "number" : "54321" } 548 ], 549 "locality": "Reston", 550 "region": "VA", 551 "country": "USA", 552 "postcode": "20190", 553 "countryCode": "US" 554 }, 555 "private-address":{ 556 "contexts":{ "private": true }, 557 "fullAddress":{ 558 "value": "12345 Elm St\nReston\nVA\n20190\nUSA" 559 }, 560 "street": [ 561 { "name": "Elm St" }, 562 { "number" : "12345" } 563 ], 564 "locality": "Reston", 565 "region": "VA", 566 "country": "USA", 567 "postcode": "20190", 568 "countryCode": "US" 569 } 570 }, 571 ... 572 } 574 Figure 6: ADR mapping example 576 2.6. Communications Properties 578 2.6.1. TEL 580 A TEL property is represented as an entry of the "phones" map 581 (Figure 7). The entry value is a "Phone" object. The TEL-specific 582 values of the TYPE parameter are mapped to the "features" map keys. 583 The values that don't match a key are represented as comma-separated 584 values of the "label" member. If the "features" map is empty and the 585 "label" member is not empty, the "other" feature is added. The 586 "phone" member is set to the TEL value. 588 The PREF and TYPE parameters are mapped according to the rules as 589 defined in (Section 2.1). 591 BEGIN:VCARD 592 VERSION:4.0 593 ... 594 TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555 595 TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67 596 ... 597 END:VCARD 599 { 600 ... 601 "phones":{ 602 "a-phone":{ 603 "contexts":{ "private": true }, 604 "features":{ "voice": true }, 605 "phone": "tel:+1-555-555-5555;ext=5555", 606 "pref": 1 607 }, 608 "another-phone":{ 609 "contexts":{ "private": true }, 610 "phone": "tel:+33-01-23-45-67" 611 } 612 ], 613 ... 614 } 616 Figure 7: TEL mapping example 618 2.6.2. EMAIL 620 An EMAIL property is represented as an entry of the "emails" map 621 (Figure 8). The entry value is an "EmailAddress" object. The 622 "email" member is set to the EMAIL value. 624 The PREF and TYPE parameters are mapped according to the rules as 625 defined in (Section 2.1). 627 BEGIN:VCARD 628 VERSION:4.0 629 ... 630 EMAIL;TYPE=work:jqpublic@xyz.example.com 631 EMAIL;PREF=1:jane_doe@example.com 632 ... 633 END:VCARD 635 { 636 ... 637 "emails":{ 638 "work-email":{ 639 "contexts":{ "work": true }, 640 "email": "jqpublic@xyz.example.com" 641 }, 642 "private-email":{ 643 "contexts":{ "private", true }, 644 "email": "jane_doe@example.com", 645 "pref": 1 646 } 647 }, 648 ... 649 } 651 Figure 8: EMAIL mapping example 653 2.6.3. IMPP 655 An IMPP property is represented as an entry of the "online" map 656 (Figure 9). The entry value is a "Resource" object whose "type" 657 member is set to "username", the "label" member is set to "XMPP" and 658 the "resource" member is the IMPP value. 660 The PREF and TYPE parameters are mapped according to the rules as 661 defined in (Section 2.1). 663 BEGIN:VCARD 664 VERSION:4.0 665 ... 666 IMPP;PREF=1:xmpp:alice@example.com 667 ... 668 END:VCARD 670 { 671 ... 672 "online":{ 673 ... 674 { 675 "type": "username", 676 "label": "XMPP", 677 "value": "alice@example.com" 678 }, 679 ... 680 }, 681 ... 682 } 684 Figure 9: IMPP mapping example 686 2.6.4. LANG 688 A LANG property is represented as an entry of the 689 "preferredContactLanguages" map (Figure 10). The entry keys 690 correspond to the language tags, the corresponding entry values are 691 arrays of "ContactLanguage" objects. 693 The PREF and TYPE parameters are mapped according to the rules as 694 defined in (Section 2.1). 696 If both PREF and TYPE parameters are missing, the array of 697 "ContactLanguage" objects MUST be empty. 699 BEGIN:VCARD 700 VERSION:4.0 701 ... 702 LANG;TYPE=work;PREF=1:en 703 LANG;TYPE=work;PREF=2:fr 704 LANG;TYPE=home:fr 705 ... 706 END:VCARD 708 { 709 ... 710 "preferredContactLanguages":{ 711 "en":[ 712 { 713 "context": "work", 714 "pref": 1 715 } 716 ], 717 "fr":[ 718 { 719 "context": "work", 720 "pref": 2 721 }, 722 { 723 "context": "private" 724 } 725 ] 726 }, 727 ... 728 } 730 Figure 10: LANG mapping example 732 2.7. Geographical Properties 734 The GEO and TZ properties are not directly mapped to topmost Card 735 members because the same information is represented through 736 equivalent "Address" members. 738 The ALTID parameter is used for associating both GEO and TZ 739 properties with the related address information. When the ALTID 740 parameter is missing, the matched members SHOULD be included in the 741 first "Address" object. 743 2.7.1. Time Zone Representation 745 As specified in Section 6.5.1 of [RFC6350], the time zone information 746 can be represented in three ways: as a time zone name, as a UTC 747 offset or as a URI. 749 o If the TZ value is defined in the IANA timezone database, it is 750 directly matched by the "timeZone" member in JSContact. 752 o An UTC offset MUST be converted into the related "Etc/GMT" time 753 zone (e.g. the value "-0500" converts to "Etc/GMT+5"). If the UTC 754 offset value contains minutes information or is not an IANA 755 timezone name, it requires special handling. 757 o Since there is no URI scheme defined for time zones [uri-schemes], 758 any implementation that does use some a custom URI for a time zone 759 is not interoperable anyway. In this case, if the URI corresponds 760 to an IANA time zone [time-zones], this latter SHOULD be used. 761 Otherwise, the URI value is dumped into a string. 763 2.8. Organizational Properties 765 2.8.1. TITLE and ROLE 767 Both TITLE and ROLE properties are represented as entries of the 768 "titles" map (Figure 11). The entry value is a "Title" object whose 769 "title" member includes information about the language. 771 The ALTID and LANGUAGE parameters are mapped according to the rules 772 as defined in (Section 2.1). The "title.localizations" includes 773 possible language-dependent alternatives. 775 BEGIN:VCARD 776 VERSION:4.0 777 ... 778 TITLE:Research Scientist 779 ROLE:Project Leader 780 ... 781 END:VCARD 783 { 784 ... 785 "titles":{ 786 "a-title":{ 787 "title":{ "value" : "Project Leader" } 788 }, 789 "another-title":{ 790 "title":{ "value" : "Research Scientist" } 791 } 792 }, 793 ... 794 } 796 Figure 11: TITLE and ROLE mapping example 798 2.8.2. LOGO 800 A LOGO property is represented as an entry of the "online" map 801 (Figure 12). The entry value is a "Resource" object whose "type" 802 member is set to "uri", the "label" member is set to "logo" and the 803 "resource" member is the LOGO value. 805 The PREF and TYPE parameters are mapped according to the rules as 806 defined in (Section 2.1). 808 BEGIN:VCARD 809 VERSION:4.0 810 ... 811 LOGO:http://www.example.com/pub/logos/abccorp.jpg 812 ... 813 END:VCARD 815 { 816 ... 817 "online":{ 818 ... 819 "a-logo":{ 820 "type": "uri", 821 "label": "logo", 822 "resource": "http://www.example.com/pub/logos/abccorp.jpg" 823 }, 824 ... 825 }, 826 ... 827 } 829 Figure 12: LOGO mapping example 831 2.8.3. ORG 833 An ORG property is represented as an entry of the "organizations" map 834 (Figure 13). The entry value is an "Organization" object whose 835 "name" member contains the organizational name and the "units" member 836 contains the organizational units. 838 The ALTID and LANGUAGE parameters are mapped according to the rules 839 as defined in (Section 2.1). The "localizations" maps for both 840 "name" and "units" include possible language-dependent alternatives. 842 BEGIN:VCARD 843 VERSION:4.0 844 ... 845 ORG:ABC\, Inc.;North American Division;Marketing 846 ... 847 END:VCARD 849 { 850 ... 851 "organizations":{ 852 "an-organization":{ 853 "name":{ "value": "ABC, Inc." }, 854 "units":[ 855 { "value": "North American Division" }, 856 { "value": "Marketing" } 857 ] 858 } 859 }, 860 ... 861 } 863 Figure 13: ORG mapping example 865 2.8.4. MEMBER 867 According to the JSContact specification, a group of contact cards is 868 represented through a CardGroup (Figure 14). The uids of the contact 869 cards composing the group are included in the "members" map. 871 In this case, the PREF parameter has not a JSContact counterpart; 872 however, the implementers MAY insert the map entries by order of 873 preference. 875 BEGIN:VCARD 876 VERSION:4.0 877 KIND:group 878 FN:The Doe family 879 MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 880 MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 881 END:VCARD 883 { 884 "kind": "group", 885 "fullName":{ "value": "The Doe family" }, 886 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 887 "members":{ 888 "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, 889 "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true 890 } 891 } 893 Figure 14: Group example 895 Only if the GROUP contains properties that don't have a mapping to 896 CardGroup properties, then the CardGroup.card property MAY contain 897 the optional Card object of this group. 899 { 900 "name": "The Doe family", 901 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 902 "members":{ 903 "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, 904 "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true 905 }, 906 "card": { 907 "fullName":{ "value": "The Doe family" }, 908 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 909 "photos":{ 910 "a-photo":{ 911 "href": "http://www.example.com/pub/photos/jqpublic.gif" 912 } 913 } 914 } 915 } 917 Figure 15: card member of CardGroup object 919 2.8.5. RELATED 921 All the RELATED instances are converted into the "relatedTo" map 922 (Figure 16): an entry for each entity the entity described by the 923 Card is associated with. The map keys are the "uid" values of the 924 associated cards. 926 Each map value is a "Relation" object including only the "relation" 927 member represented as a set of the RELATED-specific values of the 928 TYPE parameter as defined in Section 6.6.6 of [RFC6350]. 930 If the relation type is unspecified, the "relation" member MUST be 931 empty. 933 BEGIN:VCARD 934 VERSION:4.0 935 ... 936 RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 937 RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf 938 RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries. 939 ... 940 END:VCARD 942 { 943 ... 944 "relatedTo":{ 945 { 946 "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6":{ 947 "relation":{ "friend": true } 948 } 949 }, 950 { 951 "http://example.com/directory/jdoe.vcf":{ 952 "relation":{ "contact": true } 953 } 954 }, 955 { 956 "Please contact my assistant Jane Doe for any inquiries.":{ 957 "relation":{ } 958 } 959 } 960 }, 961 ... 962 } 964 Figure 16: RELATED mapping example 966 2.8.6. CONTACT-URI 968 A CONTACT-URI property as defined in [RFC8605] is represented as an 969 entry of the "online" map (Figure 17). The entry value is a 970 "Resource" object whose "type" member is set to "uri", the "label" 971 member is set to "contact-uri" and the "resource" member is the 972 CONTACT-URI value. 974 The PREF and TYPE parameters are mapped according to the rules as 975 defined in (Section 2.1). 977 BEGIN:VCARD 978 VERSION:4.0 979 ... 980 CONTACT-URI;PREF=1:mailto:contact@example.com 981 ... 982 END:VCARD 984 { 985 ... 986 "online":{ 987 ... 988 "a-contact-uri":{ 989 "type": "uri", 990 "label": "contact-uri", 991 "resource": "mailto:contact@example.com", 992 "pref": 1 993 }, 994 ... 995 }, 996 ... 997 } 999 Figure 17: CONTACT-URI mapping example 1001 2.9. Personal Information Properties 1003 The LEVEL parameter as defined in [RFC6715] is directly mapped to the 1004 "level" property of the "PersonalInformation" type apart from when 1005 LEVEL is used in the EXPERTISE property; in this case, the values are 1006 converted as in the following: 1008 o "beginner" is converted into "low"; 1009 o "average" is converted into "medium"; 1010 o "expert" is converted into "high". 1012 2.9.1. EXPERTISE 1014 An EXPERTISE property as defined in [RFC6715] is represented as a 1015 "PersonalInformation" object in the "personalInfo" array (Figure 18). 1016 The "type" member is set to "expertise". 1018 The INDEX parameter is represented as the index of the expertise 1019 among the declared expertises. 1021 BEGIN:VCARD 1022 VERSION:4.0 1023 ... 1024 EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature 1025 EXPERTISE;INDEX=1;LEVEL=expert:chemistry 1026 ... 1027 END:VCARD 1029 { 1030 ... 1031 "personalInfo":[ 1032 ... 1033 { 1034 "type": "expertise", 1035 "value": "chemistry", 1036 "level": "high" 1037 }, 1038 { 1039 "type": "expertise", 1040 "value": "chinese literature", 1041 "level": "low" 1042 }, 1043 ... 1044 ], 1045 ... 1046 } 1048 Figure 18: EXPERTISE mapping example 1050 2.9.2. HOBBY 1052 A HOBBY property as defined in [RFC6715] is represented as a 1053 "PersonalInformation" object in the "personalInfo" array (Figure 19). 1054 The "type" member is set to "hobby". 1056 The INDEX parameter is represented as the index of the hobby among 1057 the declared hobbies. 1059 BEGIN:VCARD 1060 VERSION:4.0 1061 ... 1062 HOBBY;INDEX=1;LEVEL=high:reading 1063 HOBBY;INDEX=2;LEVEL=high:sewing 1064 ... 1065 END:VCARD 1067 { 1068 ... 1069 "personalInfo":[ 1070 ... 1071 { 1072 "type": "hobby", 1073 "value": "reading", 1074 "level": "high" 1075 }, 1076 { 1077 "type": "hobby", 1078 "value": "sewing", 1079 "level": "high" 1080 }, 1081 ... 1082 ], 1083 ... 1084 } 1086 Figure 19: HOBBY mapping example 1088 2.9.3. INTEREST 1090 An INTEREST property as defined in [RFC6715] is represented as a 1091 "PersonalInformation" object in the "personalInfo" array (Figure 20). 1092 The "type" member is set to "interest". 1094 The INDEX parameter is represented as the index of the interest among 1095 the declared interests. 1097 BEGIN:VCARD 1098 VERSION:4.0 1099 ... 1100 INTEREST;INDEX=1;LEVEL=medium:r&b music 1101 INTEREST;INDEX=2;LEVEL=high:rock 'n' roll music 1102 ... 1103 END:VCARD 1105 { 1106 ... 1107 "personalInfo":[ 1108 ... 1109 { 1110 "type": "interest", 1111 "value": "r&b music", 1112 "level": "medium" 1113 }, 1114 { 1115 "type": "interest", 1116 "value": "rock 'n' roll music", 1117 "level": "high" 1118 }, 1119 ... 1120 ], 1121 ... 1122 } 1124 Figure 20: INTEREST mapping example 1126 2.9.4. ORG-DIRECTORY 1128 An ORG-DIRECTORY property is represented as an entry of the "online" 1129 map (Figure 21). The entry value is a "Resource" object whose "type" 1130 member is set to "uri", the "label" member is set to "org-directory" 1131 and the "resource" member is the ORG-DIRECTORY value. 1133 The PREF and TYPE parameters are mapped according to the rules as 1134 defined in (Section 2.1). 1136 The INDEX parameter is represented as the index of the directory 1137 among the online resources with the "org-directory" label. 1139 BEGIN:VCARD 1140 VERSION:4.0 1141 ... 1142 ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com 1143 ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering 1144 ... 1145 END:VCARD 1147 { 1148 ... 1149 "online":{ 1150 ... 1151 "an-org-directory":{ 1152 "type": "uri", 1153 "label": "org-directory", 1154 "resource": "http://directory.mycompany.example.com" 1155 }, 1156 "another-org-directory":{ 1157 "type": "uri", 1158 "label": "org-directory", 1159 "resource": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering", 1160 "pref": 1 1161 }, 1162 ... 1163 }, 1164 ... 1165 } 1167 Figure 21: ORG-DIRECTORY mapping example 1169 2.10. Explanatory Properties 1171 2.10.1. CATEGORIES 1173 A CATEGORIES property is converted into a set of entries of the 1174 "categories" map (Figure 22). The keys are the comma-separated text 1175 values of the CATEGORIES property. 1177 In this case, the PREF parameter has not a JSContact counterpart; 1178 however, implementers MAY use a map preserving the order of insertion 1179 and the map entries can be inserted by order of preference. 1181 BEGIN:VCARD 1182 VERSION:4.0 1183 ... 1184 CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY 1185 ... 1186 END:VCARD 1188 { 1189 ... 1190 "categories":{ 1191 "INTERNET": true, 1192 "IETF": true, 1193 "INDUSTRY": true, 1194 "INFORMATION TECHNOLOGY": true 1195 }, 1196 ... 1197 } 1199 Figure 22: CATEGORIES mapping example 1201 2.10.2. NOTE 1203 A NOTE property is mapped to the "notes" property (Figure 23). All 1204 the NOTE instances are condensed into a single note and separated by 1205 newline. 1207 The ALTID and LANGUAGE parameters are mapped according to the rules 1208 as defined in (Section 2.1). The "localizations" map includes 1209 possible language-dependent alternatives. 1211 BEGIN:VCARD 1212 VERSION:4.0 1213 ... 1214 NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri. 1215 ... 1216 END:VCARD 1218 { 1219 ... 1220 "notes": { 1221 "value": "This fax number is operational 0800 to 1715 EST, Mon-Fri." 1222 }, 1223 ... 1224 } 1226 Figure 23: NOTE mapping example 1228 2.10.3. PRODID 1230 The PRODID property is converted into the "prodId" member 1231 (Figure 24). 1233 BEGIN:VCARD 1234 VERSION:4.0 1235 ... 1236 PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN 1237 ... 1238 END:VCARD 1240 { 1241 ... 1242 "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN", 1243 ... 1244 } 1246 Figure 24: PRODID mapping example 1248 2.10.4. REV 1250 The REV property is transformed into the "updated" member 1251 (Figure 25). 1253 BEGIN:VCARD 1254 VERSION:4.0 1255 ... 1256 REV:19951031T222710Z 1257 ... 1258 END:VCARD 1260 { 1261 ... 1262 "updated": "1995-10-31T22:27:10Z", 1263 ... 1264 } 1266 Figure 25: REV mapping example 1268 2.10.5. SOUND 1270 A SOUND property is represented as an entry of the "online" map 1271 (Figure 26). The entry value is a "Resource" object whose "type" 1272 member is set to "uri", the "label" member is set to "sound" and the 1273 "resource" member is the SOUND value. 1275 The PREF and TYPE parameters are mapped according to the rules as 1276 defined in (Section 2.1). 1278 BEGIN:VCARD 1279 VERSION:4.0 1280 ... 1281 SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com 1282 ... 1283 END:VCARD 1285 { 1286 ... 1287 "online":{ 1288 ... 1289 "a-sound":{ 1290 "type": "uri", 1291 "label": "sound", 1292 "resource": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com" 1293 }, 1294 ... 1295 }, 1296 ... 1297 } 1299 Figure 26: SOUND mapping example 1301 2.10.6. UID 1303 The UID property corresponds to the "uid" property (Figure 27) in 1304 both Card and CardGroup. 1306 BEGIN:VCARD 1307 VERSION:4.0 1308 ... 1309 UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 1310 ... 1311 END:VCARD 1313 { 1314 ... 1315 "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6", 1316 ... 1317 } 1319 Figure 27: UID mapping example 1321 2.10.7. CLIENTPIDMAP and PID Parameter 1323 The CLIENTPIDMAP property and the PDI parameter don't have a direct 1324 match with a Card feature. 1326 2.10.8. URL 1328 An URL property is represented as an entry of the "online" map 1329 (Figure 28). The entry value is a "Resource" object whose "type" 1330 member is set to "uri", the "label" member is set to "url" and the 1331 "resource" member is the URL value. 1333 The PREF and TYPE parameters are mapped according to the rules as 1334 defined in (Section 2.1). 1336 BEGIN:VCARD 1337 VERSION:4.0 1338 ... 1339 URL:http://example.org/restaurant.french/~chezchic.html 1340 ... 1341 END:VCARD 1343 { 1344 ... 1345 "online":{ 1346 ... 1347 "an-url":{ 1348 "type": "uri", 1349 "label": "url", 1350 "resource": "http://example.org/restaurant.french/~chezchic.html" 1351 }, 1352 ... 1353 }, 1354 ... 1355 } 1357 Figure 28: URL mapping example 1359 2.10.9. VERSION 1361 The VERSION property doesn't have a direct match with a JSContact 1362 feature. 1364 2.11. Security Properties 1365 2.11.1. KEY 1367 A KEY property is represented as an entry of the "online" map 1368 (Figure 29). The entry value is a "Resource" object whose "type" 1369 member is set to "uri", the "label" member is set to "key" and the 1370 "resource" member is the KEY value. 1372 The PREF and TYPE parameters are mapped according to the rules as 1373 defined in (Section 2.1). 1375 BEGIN:VCARD 1376 VERSION:4.0 1377 ... 1378 KEY:http://www.example.com/keys/jdoe.cer 1379 ... 1380 END:VCARD 1382 { 1383 ... 1384 "online":{ 1385 ... 1386 "a-key":{ 1387 "type": "uri", 1388 "label": "key", 1389 "resource": "http://www.example.com/keys/jdoe.cer" 1390 }, 1391 ... 1392 }, 1393 ... 1394 } 1396 Figure 29: KEY mapping example 1398 2.12. Calendar Properties 1400 2.12.1. FBURL 1402 An FBURL property is represented as an entry of the "online" map 1403 (Figure 30). The entry value is a "Resource" object whose "type" 1404 member is set to "uri", the "label" member is set to "fburl" and the 1405 "resource" member is the FBURL value. 1407 The PREF and TYPE parameters are mapped according to the rules as 1408 defined in (Section 2.1). 1410 BEGIN:VCARD 1411 VERSION:4.0 1412 ... 1413 FBURL;PREF=1:http://www.example.com/busy/janedoe 1414 FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb 1415 ... 1416 END:VCARD 1418 { 1419 ... 1420 "online":{ 1421 ... 1422 "an-fburl":{ 1423 "type": "uri", 1424 "label": "fburl", 1425 "resource": "http://www.example.com/busy/janedoe", 1426 "pref": 1 1427 }, 1428 "another-fburl":{ 1429 "type": "uri", 1430 "label": "fburl", 1431 "resource": "ftp://example.com/busy/project-a.ifb", 1432 "mediaType": "text/calendar" 1433 }, 1434 ... 1435 }, 1436 ... 1437 } 1439 Figure 30: FBURL mapping example 1441 2.12.2. CALADRURI 1443 A CALADRURI property is represented as an entry of the "online" map 1444 (Figure 31). The entry value is a "Resource" object whose "type" 1445 member is set to "uri", the "label" member is set to "caladruri" and 1446 the "resource" member is the CALADRURI value. 1448 The PREF and TYPE parameters are mapped according to the rules as 1449 defined in (Section 2.1). 1451 BEGIN:VCARD 1452 VERSION:4.0 1453 ... 1454 CALADRURI;PREF=1:mailto:janedoe@example.com 1455 CALADRURI:http://example.com/calendar/jdoe 1456 ... 1457 END:VCARD 1459 { 1460 ... 1461 "online":{ 1462 ... 1463 "a-caladruri":{ 1464 "type": "uri", 1465 "label": "caladruri", 1466 "resource": "mailto:janedoe@example.com", 1467 "pref": 1 1468 }, 1469 "another-caladruri":{ 1470 "type": "uri", 1471 "label": "caladruri", 1472 "resource": "http://example.com/calendar/jdoe" 1473 }, 1474 ... 1475 }, 1476 ... 1477 } 1479 Figure 31: CALADRURI mapping example 1481 2.12.3. CALURI 1483 A CALURI property is represented as an entry of the "online" map 1484 (Figure 32). The entry value is a "Resource" object whose "type" 1485 member is set to "uri", the "label" member is set to "caluri" and the 1486 "resource" member is the CALURI value. 1488 The PREF and TYPE parameters are mapped according to the rules as 1489 defined in (Section 2.1). 1491 BEGIN:VCARD 1492 VERSION:4.0 1493 ... 1494 CALURI;PREF=1:http://cal.example.com/calA 1495 CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics 1496 ... 1497 END:VCARD 1499 { 1500 ... 1501 "online":{ 1502 ... 1503 "a-caluri":{ 1504 "type": "uri", 1505 "label": "caluri", 1506 "resource": "http://cal.example.com/calA", 1507 "pref": 1 1508 }, 1509 "another-caluri":{ 1510 "type": "uri", 1511 "label": "caluri", 1512 "resource": "ftp://ftp.example.com/calA.ics", 1513 "mediaType": "text/calendar" 1514 }, 1515 ... 1516 }, 1517 ... 1518 } 1520 Figure 32: CALURI mapping example 1522 2.13. vCard Unmatched Properties 1524 The unmatched vCard properties MAY be converted into JSContact 1525 properties whose name contains the prefix "ietf.org/RFC6350/" 1526 followed by property name in uppercase (i.e. ietf.org/RFC6350/ 1527 GENDER"). 1529 2.14. Card Required Properties 1531 While converting a vCard into a Card/CardGroup, only the topmost 1532 "uid" member is mandatory. Implementers are REQUIRED to set it when 1533 it is missing. 1535 3. Translating JSContact properties to vCard 1537 In most of the cases, the rules about the translation from Card/ 1538 CardGroup to vCard can be derived by reversing the rules presented in 1539 Section 2. The remaining cases are treated in the following of this 1540 section. 1542 3.1. Id 1544 Where a map key is of type Id, implementers are free to either ignore 1545 it or preserve it as a vCard information (e.g. a vCard parameter). 1547 3.2. Localizations 1549 A LocalizedString object is converted in multiple instances of the 1550 same vCard property having different values of the LANGUAGE 1551 parameter. Implementers MAY set the ALTID parameter to couple 1552 language-based alternatives of the same value. 1554 Note also that the components of some vCard values and their related 1555 alternatives are split into different JSContact values. For example, 1556 the "name" and "units" values for a given language must be grouped to 1557 make a single ORG value where components are separated by ";". 1559 3.3. Date and Time Representations 1561 The JSContact spec defines the "UTCDateTime" type to represent 1562 [RFC3339] "date-time" format with further restrictions. This means 1563 that the matched vCard format for a "UTCDateTime" value MUST be one 1564 of the formats shown in Section 4.3.5 of [RFC6350] (i.e. 1565 "19961022T140000Z"). 1567 In addition to such format, the "date" member of the "Anniversary" 1568 type allows specifying both a date without the time and a partial 1569 date. In this case, the corresponding vCard format is that defined 1570 in Section 4.3.1. 1572 3.4. Time Zone 1574 The time zone name as represented by the "timeZone" property is 1575 mapped to the TZ parameter. 1577 Implementers MAY map an "Etc/GMT" time zone either preserving the 1578 time zone name or converting it into a UTC offset. 1580 3.5. JSContact Types Matching Multiple vCard Properties 1582 3.5.1. Title 1584 The "titles" property contains information about the job, the 1585 position or the role of the entity the card represents. In vCard, 1586 such information is split into the TITLE and ROLE properties. This 1587 specification defines TITLE as the default target property when 1588 converting the "titles" property. 1590 3.5.2. Resource 1592 The "online" property includes resources that are usually represented 1593 through different vCard properties. The matched vCard property of a 1594 "Resource" object can be derived from the value of its "label" 1595 member. 1597 Any resource included in the "online" map that doesn't match a vCard 1598 property MAY be converted into vCard extended properties. 1600 3.6. CardGroup 1602 A CardGroup object is converted into a vCard by merging its 1603 properties with the properties of "CardGroup.card" object. If the 1604 "CardGroup.card.fullName" property exists, it MUST be used to set the 1605 FN value. 1607 3.7. Card Unmatched Properties 1609 Both the "preferredContactMethod" and "created" members don't match 1610 any vCard property. Implementers MAY represent them as vCard 1611 extended properties. 1613 3.8. vCard Required Properties 1615 While converting a Card/CardGroup into a vCard, only the FN property 1616 is required. Since both the "Card.fullName" and "CardGroup.name" 1617 properties are optional, implementers are REQUIRED to generate an FN 1618 value when it is missing. 1620 4. IANA Considerations 1622 This document has no actions for IANA. 1624 5. Implementation Status 1626 NOTE: Please remove this section and the reference to RFC 7942 prior 1627 to publication as an RFC. 1629 This section records the status of known implementations of the 1630 protocol as defined in this specification at the time of posting of 1631 this Internet-Draft, and is based on a proposal described in 1632 [RFC7942]. The description of implementations in this section is 1633 intended to assist the IETF in its decision processes in progressing 1634 drafts to RFCs. Please note that the listing of any individual 1635 implementation here does not imply endorsement by the IETF. 1636 Furthermore, no effort has been spent to verify the information 1637 presented here that was supplied by IETF contributors. This is not 1638 intended as, and must not be construed to be, a catalog of available 1639 implementations or their features. Readers are advised to note that 1640 other implementations may exist. 1642 According to RFC 7942, "this will allow reviewers and working groups 1643 to assign due considerationto documents that have the benefit of 1644 running code, which may serve as evidence of valuable experimentation 1645 and feedback that have made the implemented protocols more mature. 1646 It is up to the individual working groups to use this information as 1647 they see fit". 1649 5.1. CNR 1651 Responsible Organization: National Research Council (CNR) of Italy 1652 Location: https://github.com/consiglionazionaledellericerche/ 1653 jscontact-tools 1654 Description: This implementation includes tools for JSContact 1655 creation, validation, serialization/deserialization, and 1656 conversion from vCard, xCard and jCard. 1657 Level of Maturity: This is an "alpha" test implementation. 1658 Coverage: This implementation includes all of the features 1659 described in this specification. 1660 Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it 1662 6. Security Considerations 1664 This document doesn't present any security consideration. 1666 7. References 1667 7.1. Normative References 1669 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1670 Requirement Levels", BCP 14, RFC 2119, 1671 DOI 10.17487/RFC2119, March 1997, 1672 . 1674 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1675 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1676 . 1678 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 1679 DOI 10.17487/RFC6350, August 2011, 1680 . 1682 [RFC6473] Saint-Andre, P., "vCard KIND:application", RFC 6473, 1683 DOI 10.17487/RFC6473, December 2011, 1684 . 1686 [RFC6474] Li, K. and B. Leiba, "vCard Format Extensions: Place of 1687 Birth, Place and Date of Death", RFC 6474, 1688 DOI 10.17487/RFC6474, December 2011, 1689 . 1691 [RFC6715] Cauchie, D., Leiba, B., and K. Li, "vCard Format 1692 Extensions: Representing vCard Extensions Defined by the 1693 Open Mobile Alliance (OMA) Converged Address Book (CAB) 1694 Group", RFC 6715, DOI 10.17487/RFC6715, August 2012, 1695 . 1697 [RFC6869] Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard 1698 KIND:device", RFC 6869, DOI 10.17487/RFC6869, February 1699 2013, . 1701 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 1702 DOI 10.17487/RFC7095, January 2014, 1703 . 1705 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1706 Code: The Implementation Status Section", BCP 205, 1707 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1708 . 1710 [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: 1711 ICANN Extensions for the Registration Data Access Protocol 1712 (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, 1713 . 1715 7.2. Informative References 1717 [draft-ietf-jmap-jscontact] 1718 "JSContact: A JSON representation of contact data", 1719 . 1722 [time-zones] 1723 "Time Zone Database", . 1725 [uri-schemes] 1726 "Uniform Resource Identifier (URI) Schemes", 1727 . 1730 Authors' Addresses 1732 Mario Loffredo 1733 IIT-CNR/Registro.it 1734 Via Moruzzi,1 1735 Pisa 56124 1736 IT 1738 Email: mario.loffredo@iit.cnr.it 1739 URI: http://www.iit.cnr.it 1741 Robert Stepanek 1742 FastMail 1743 PO Box 234, Collins St West 1744 Melbourne VIC 8007 1745 AU 1747 Email: rsto@fastmailteam.com 1748 URI: https://www.fastmail.com