idnits 2.17.1 draft-ietf-jmap-jscontact-vcard-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 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 (April 14, 2021) is 1109 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 1652, 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: October 16, 2021 FastMail 6 April 14, 2021 8 JSContact: Converting from and to vCard 9 draft-ietf-jmap-jscontact-vcard-03 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 October 16, 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 . . . . . . . . . . . . . . . . 12 73 2.6.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 12 74 2.6.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 13 75 2.6.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 14 76 2.6.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 15 77 2.7. Geographical Properties . . . . . . . . . . . . . . . . . 16 78 2.7.1. Time Zone Representation . . . . . . . . . . . . . . 17 79 2.8. Organizational Properties . . . . . . . . . . . . . . . . 17 80 2.8.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 17 81 2.8.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 18 82 2.8.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 19 83 2.8.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 20 84 2.8.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 21 85 2.8.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 22 86 2.9. Personal Information Properties . . . . . . . . . . . . . 23 87 2.9.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 23 88 2.9.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 24 89 2.9.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 25 90 2.9.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 26 91 2.10. Explanatory Properties . . . . . . . . . . . . . . . . . 27 92 2.10.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 27 93 2.10.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 28 94 2.10.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 29 95 2.10.4. REV . . . . . . . . . . . . . . . . . . . . . . . . 29 96 2.10.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . 29 97 2.10.6. UID . . . . . . . . . . . . . . . . . . . . . . . . 30 98 2.10.7. CLIENTPIDMAP and PID Parameter . . . . . . . . . . . 31 99 2.10.8. URL . . . . . . . . . . . . . . . . . . . . . . . . 31 100 2.10.9. VERSION . . . . . . . . . . . . . . . . . . . . . . 31 101 2.11. Security Properties . . . . . . . . . . . . . . . . . . . 31 102 2.11.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . 32 103 2.12. Calendar Properties . . . . . . . . . . . . . . . . . . . 32 104 2.12.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 32 105 2.12.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 33 106 2.12.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 34 107 2.13. vCard Unmatched Properties . . . . . . . . . . . . . . . 35 108 2.14. JSCard Required Properties . . . . . . . . . . . . . . . 35 109 3. Translating JSContact properties to vCard . . . . . . . . . . 36 110 3.1. Id . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 111 3.2. Localizations . . . . . . . . . . . . . . . . . . . . . . 36 112 3.3. Date and Time Representations . . . . . . . . . . . . . . 36 113 3.4. Time Zone . . . . . . . . . . . . . . . . . . . . . . . . 36 114 3.5. JSContact Types Matching Multiple vCard Properties . . . 37 115 3.5.1. Title . . . . . . . . . . . . . . . . . . . . . . . . 37 116 3.5.2. Resource . . . . . . . . . . . . . . . . . . . . . . 37 117 3.6. JSCard Unmatched Properties . . . . . . . . . . . . . . . 37 118 3.7. vCard Required Properties . . . . . . . . . . . . . . . . 37 119 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 120 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 37 121 5.1. CNR . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 122 6. Security Considerations . . . . . . . . . . . . . . . . . . . 38 123 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 124 7.1. Normative References . . . . . . . . . . . . . . . . . . 38 125 7.2. Informative References . . . . . . . . . . . . . . . . . 39 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 128 1. Introduction 130 1.1. Motivation 132 The JSContact specification [draft-ietf-jmap-jscontact] has been 133 defined to represent contact card information as a more efficient 134 alternative to vCard [RFC6350] and its JSON-based version named jCard 135 [RFC7095]. 137 While new applications might adopt JSContact as their main format to 138 exchange contact card data, they are likely to interoperate with 139 services and clients that just support vCard/jCard. Similarly, 140 existing contact data providers and consumers already using vCard/ 141 jCard might want to represent their data also according to the 142 JSContact specification. 144 To facilitate this, this document defines how to convert contact 145 information as defined in the JSContact [draft-ietf-jmap-jscontact] 146 specification from and to vCard. 148 1.2. Scope and Caveats 150 JSContact and vCard have a lot of semantics in common, however some 151 differences must be outlined: 153 o The JSContact data model defines some contact information that 154 doesn't have a direct mapping with vCard properties. In 155 particular, unlike vCard, JSContact distinguishes between a single 156 contact card, named JSCard, and a group of contact cards, named 157 JSCardGroup. 159 o The properties that can be present multiple times in a vCard are 160 represented through different collections in JSContact; mainly as 161 maps, sometimes as lists, in some cases condensed in a single 162 value. 164 1.2.1. Extensions 166 While translating vCard properties to JSContact, any vCard property 167 that doesn't have a direct counterpart in JSContact MUST be converted 168 into a property whose name is prefixed by "ietf.org//". 171 Any custom extension MAY be added and its name MUST be prefixed with 172 a specific domain name to avoid conflict, e.g. "example.com/ 173 customprop". 175 Similarly, the reversed rules are applied while translating JSContact 176 properties to vCard. 178 1.3. Conventions Used in This Document 180 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 181 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 182 document are to be interpreted as described in [RFC2119]. 184 In the following of this document, the vCard features, namely 185 properties and parameters, are written in uppercase while the JSCard/ 186 JSCardGroup features are written in camel case wrapped in double 187 quotes. 189 2. Translating vCard properties to JSContact 191 This section contains the translation rules from vCard to JSCard/ 192 JSCardGroup. The vCard properties are grouped according to the 193 categories as defined in [RFC6350]. 195 2.1. Common Parameters 197 The following mapping rules apply to parameters that are common to 198 most of the vCard properties: 200 o The generic values of the TYPE parameter are mapped onto the 201 values of the "Context" type as defined in Section 1.5.1 of 202 [draft-ietf-jmap-jscontact]. The "home" value corresponds to the 203 "private" key. The mapping of those specific TYPE values used in 204 the TEL and RELATED properties are defined in the following of the 205 document. 207 o The PREF parameter is mapped onto the "pref" property. 209 o The MEDIATYPE parameter is mapped onto the "mediaType" property. 210 As described in Section 5.7 of [RFC6350], the media type of a 211 resource can be identified by its URI. For example, "image/gif" 212 can be derived from the ".gif" extension of a GIF image URI. 213 JSContact producers MAY provide the media type information even 214 when it is not specified in the vCard. 216 o The ALTID and LANGUAGE parameters are used in combination for 217 associating the language-dependent alternatives with a given 218 property. Such alternatives are represented by using the 219 "localizations" map of a "LocalizedString" member inside the 220 matching JSContact object. 222 o The LEVEL parameter as defined in [RFC6715] is directly mapped 223 onto the "level" property of the "PersonalInformation" type apart 224 from when LEVEL is used in the EXPERTISE property; in this case, 225 the values are converted as in the following: 227 * "beginner" is converted into "low"; 228 * "average" is converted into "medium"; 229 * "expert" is converted into "high". 231 2.2. JSContact Id 233 The rules to generate a map key of type Id are out of the scope of 234 this document. 236 2.3. General Properties 238 2.3.1. BEGIN and END 240 The BEGIN and END properties don't have a direct match with a 241 JSContact feature. 243 2.3.2. SOURCE 245 A SOURCE property is represented as an entry of the "online" map 246 (Figure 1). The entry value is a "Resource" object whose "type" 247 member is set to "uri", the "label" member is set to "source" and the 248 "resource" member is the SOURCE value. 250 The PREF and MEDIATYPE parameters are mapped according to the rules 251 as defined in (Section 2.1). 253 BEGIN:VCARD 254 VERSION:4.0 255 ... 256 SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf 257 ... 258 END:VCARD 260 { 261 ... 262 "online":{ 263 ... 264 "a-source":{ 265 "type": "uri", 266 "label": "source", 267 "resource": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf" 268 }, 269 ... 270 }, 271 ... 272 } 274 Figure 1: SOURCE mapping example 276 2.3.3. KIND 278 The KIND property is mapped onto the "kind" member (Figure 2). 279 Allowed values are those described in Section 6.1.4 of [RFC6350] and 280 extended with the values declared in [RFC6473] and [RFC6869]. The 281 value "group" is reserved for a JSCardGroup instance. 283 BEGIN:VCARD 284 VERSION:4.0 285 ... 286 KIND:individual 287 ... 288 END:VCARD 290 { 291 ... 292 "kind": "individual", 293 ... 294 } 296 Figure 2: KIND mapping example 298 2.3.4. XML 300 The XML property doesn't have a direct match with a JSContact 301 feature. 303 2.4. Identification Properties 305 2.4.1. FN 307 All the FN instances are globally represented through the "fullName" 308 member. The presence of multiple instances is implicitly associated 309 with the full name translations in various languages regardless of 310 the presence of the ALTID parameter. Each translation corresponds to 311 a different entry of the "localizations" map (Figure 3). 313 2.4.2. N and NICKNAME 315 The N instances are converted into equivalent items of the "name" 316 array (Figure 3): the N components are transformed into related 317 "NameComponent" objects as presented in Table 1. Name components 318 SHOULD be ordered such that their values joined by whitespace produce 319 a valid full name of this entity. 321 Each NICKNAME instance is mapped onto an item of "nickNames" array. 323 +--------------------+--------------+ 324 | N component | "type" value | 325 +--------------------+--------------+ 326 | Honorific Prefixes | prefix | 327 | Given Names | personal | 328 | Family Names | surname | 329 | Additional Names | additional | 330 | Honorific Suffixes | suffix | 331 +--------------------+--------------+ 333 Table 1: N components mapping 335 BEGIN:VCARD 336 VERSION:4.0 337 ... 338 FN:Mr. John Q. Public\, Esq. 339 N:Public;John;Quinlan;Mr.;Esq. 340 NICKNAME:Johnny 341 ... 342 END:VCARD 344 { 345 ... 346 "fullName":{ "value": "Mr. John Q. Public, Esq." }, 347 "name":[ 348 { "value":"Mr.", "type": "prefix" }, 349 { "value":"John", "type": "personal" }, 350 { "value":"Public", "type": "surname" }, 351 { "value":"Quinlan", "type": "additional" }, 352 { "value":"Esq.", "type": "suffix" } 353 ], 354 "nickNames":[ 355 { "value": "Johnny" } 356 ], 357 ... 358 } 360 Figure 3: FN, N, NICKNAME mapping example 362 2.4.3. PHOTO 364 A PHOTO property is represented as an entry of the "photos" map 365 (Figure 4). The entry value is a "File" object whose "href" member 366 is the PHOTO value. 368 The PREF and MEDIATYPE parameters are mapped according to the rules 369 as defined in (Section 2.1). 371 BEGIN:VCARD 372 VERSION:4.0 373 ... 374 PHOTO:http://www.example.com/pub/photos/jqpublic.gif 375 ... 376 END:VCARD 378 { 379 ... 380 "photos":{ 381 ... 382 "a-photo":{ 383 "href": "http://www.example.com/pub/photos/jqpublic.gif" 384 }, 385 ... 386 }, 387 ... 388 } 390 Figure 4: PHOTO mapping example 392 2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 394 The BDAY and ANNIVERSARY properties and the extensions BIRTHPLACE, 395 DEATHDATE, DEATHPLACE described in [RFC6350] are represented as 396 "Anniversary" objects included in the "anniversaries" array 397 (Figure 5): 399 o BDAY and BIRTHPLACE are mapped onto "date" and "place" where 400 "type" is set to "birth"; 402 o DEATHDATE and DEATHPLACE are mapped onto "date" and "place" where 403 "type" is set to "death"; 405 o ANNIVERSARY is mapped onto "date" where "type" is set to "other" 406 and "label" is set to a value describing in detail the kind of 407 anniversary (e.g. "marriage date" for the wedding anniversary). 409 Both birth and death places are represented as instances of the 410 "Address" object. 412 The BIRTHPLACE and DEATHPLACE properties that are represented as geo 413 URIs are converted into "Address" instances including only the 414 "coordinates" member. If the URI value is not a geo URI, the place 415 is ignored. 417 The ALTID and LANGUAGE parameters of both BIRTHPLACE and DEATHPLACE 418 properties are mapped according to the rules as defined in 419 (Section 2.1). The "fullAddress.localizations" includes possible 420 language-dependent alternatives. 422 BEGIN:VCARD 423 VERSION:4.0 424 ... 425 BDAY:19531015T231000Z 426 BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A. 427 DEATHDATE:19960415 428 DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A. 429 ANNIVERSARY:19860201 430 ... 431 END:VCARD 433 { 434 ... 435 "anniversaries":[ 436 { 437 "type": "birth", 438 "date": "1953-10-15T23:10:00Z", 439 "place":{ 440 "fullAddress":{ 441 "value": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A." 442 } 443 } 444 }, 445 { 446 "type": "birth", 447 "date": "1953-10-15T23:10:00Z", 448 "place":{ 449 "fullAddress":{ 450 "value": "4445 Courtright Street\nNew England, ND 58647\nU.S.A." 451 } 452 } 453 }, 454 { 455 "type": "other", 456 "label": "marriage date", 457 "date": "1986-02-01" 458 } 459 ], 460 ... 461 } 463 Figure 5: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 464 mapping example 466 2.4.5. GENDER 468 The GENDER property doesn't have a direct match with a JSContact 469 feature. 471 2.5. Delivery Addressing Properties 473 2.5.1. ADR 475 An ADR property is represented as an entry of the "addresses" map 476 (Figure 6). The entry value is an "Address" object. 478 The ADR components are transformed into the "Address" members as 479 presented in Table 2. 481 +------------------+----------------+ 482 | ADR component | Address member | 483 +------------------+----------------+ 484 | p.o. box | postOfficeBox | 485 | extended address | extension | 486 | street address | street | 487 | locality | locality | 488 | region | region | 489 | postal code | postcode | 490 | country name | country | 491 +------------------+----------------+ 493 Table 2: ADR components mapping 495 The LABEL parameter is converted into the "fullAddress" member. 497 The GEO parameter is converted into the "coordinates" member. 499 The TZ parameter is converted into the "timeZone" member. 501 The CC parameter as defined in [RFC8605] is converted into the 502 "countryCode" member. 504 The PREF and TYPE parameters are mapped according to the rules as 505 defined in (Section 2.1). 507 The ALTID and LANGUAGE parameters are mapped according to the rules 508 as defined in (Section 2.1). The "fullAddress.localizations" 509 includes possible language-dependent alternatives. 511 BEGIN:VCARD 512 VERSION:4.0 513 ... 514 ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA 515 ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA 516 ... 517 END:VCARD 519 { 520 ... 521 "addresses":{ 522 "work-address" :{ 523 "contexts":{ "work": true }, 524 "fullAddress":{ 525 "value": "54321 Oak St\nReston\nVA\n20190\nUSA" 526 }, 527 "street": "54321 Oak St", 528 "locality": "Reston", 529 "region": "VA", 530 "country": "USA", 531 "postcode": "20190", 532 "countryCode": "US" 533 }, 534 "private-address":{ 535 "contexts":{ "private": true }, 536 "fullAddress":{ 537 "value": "12345 Elm St\nReston\nVA\n20190\nUSA" 538 }, 539 "street": "12345 Elm St", 540 "locality": "Reston", 541 "region": "VA", 542 "country": "USA", 543 "postcode": "20190", 544 "countryCode": "US" 545 } 546 }, 547 ... 548 } 550 Figure 6: ADR mapping example 552 2.6. Communications Properties 554 2.6.1. TEL 556 A TEL property is represented as an entry of the "phones" map 557 (Figure 7). The entry value is a "Phone" object. The TEL-specific 558 values of the TYPE parameter are mapped onto the "features" map keys. 560 The values that don't match a key are represented as comma-separated 561 values of the "label" member. If the "features" map is empty and the 562 "label" member is not empty, the "other" feature is added. The 563 "phone" member is set to the TEL value. 565 The PREF and TYPE parameters are mapped according to the rules as 566 defined in (Section 2.1). 568 BEGIN:VCARD 569 VERSION:4.0 570 ... 571 TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555 572 TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67 573 ... 574 END:VCARD 576 { 577 ... 578 "phones":{ 579 "a-phone":{ 580 "contexts":{ "private": true }, 581 "features":{ "voice": true }, 582 "phone": "tel:+1-555-555-5555;ext=5555", 583 "pref": 1 584 }, 585 "another-phone":{ 586 "contexts":{ "private": true }, 587 "phone": "tel:+33-01-23-45-67" 588 } 589 ], 590 ... 591 } 593 Figure 7: TEL mapping example 595 2.6.2. EMAIL 597 An EMAIL property is represented as an entry of the "emails" map 598 (Figure 8). The entry value is an "EmailAddress" object. The 599 "email" member is set to the EMAIL value. 601 The PREF and TYPE parameters are mapped according to the rules as 602 defined in (Section 2.1). 604 BEGIN:VCARD 605 VERSION:4.0 606 ... 607 EMAIL;TYPE=work:jqpublic@xyz.example.com 608 EMAIL;PREF=1:jane_doe@example.com 609 ... 610 END:VCARD 612 { 613 ... 614 "emails":{ 615 "work-email":{ 616 "contexts":{ "work": true }, 617 "email": "jqpublic@xyz.example.com" 618 }, 619 "private-email":{ 620 "contexts":{ "private", true }, 621 "email": "jane_doe@example.com", 622 "pref": 1 623 } 624 }, 625 ... 626 } 628 Figure 8: EMAIL mapping example 630 2.6.3. IMPP 632 An IMPP property is represented as an entry of the "online" map 633 (Figure 9). The entry value is a "Resource" object whose "type" 634 member is set to "username", the "label" member is set to "XMPP" and 635 the "resource" member is the IMPP value. 637 The PREF and TYPE parameters are mapped according to the rules as 638 defined in (Section 2.1). 640 BEGIN:VCARD 641 VERSION:4.0 642 ... 643 IMPP;PREF=1:xmpp:alice@example.com 644 ... 645 END:VCARD 647 { 648 ... 649 "online":{ 650 ... 651 { 652 "type": "username", 653 "label": "XMPP", 654 "value": "alice@example.com" 655 }, 656 ... 657 }, 658 ... 659 } 661 Figure 9: IMPP mapping example 663 2.6.4. LANG 665 A LANG property is represented as an entry of the 666 "preferredContactLanguages" map (Figure 10). The entry keys 667 correspond to the language tags, the corresponding entry values are 668 arrays of "ContactLanguage" objects. 670 The PREF and TYPE parameters are mapped according to the rules as 671 defined in (Section 2.1). 673 If both PREF and TYPE parameters are missing, the array of 674 "ContactLanguage" objects MUST be empty. 676 BEGIN:VCARD 677 VERSION:4.0 678 ... 679 LANG;TYPE=work;PREF=1:en 680 LANG;TYPE=work;PREF=2:fr 681 LANG;TYPE=home:fr 682 ... 683 END:VCARD 685 { 686 ... 687 "preferredContactLanguages":{ 688 "en":[ 689 { 690 "context": "work", 691 "pref": 1 692 } 693 ], 694 "fr":[ 695 { 696 "context": "work", 697 "pref": 2 698 }, 699 { 700 "context": "private" 701 } 702 ] 703 }, 704 ... 705 } 707 Figure 10: LANG mapping example 709 2.7. Geographical Properties 711 The GEO and TZ properties are not directly mapped onto topmost 712 JSCard/JSCardGroup members because the same information is 713 represented through equivalent "Address" members. 715 The ALTID parameter is used for associating both GEO and TZ 716 properties with the related address information. When the ALTID 717 parameter is missing, the matched members SHOULD be included in the 718 first "Address" object. 720 2.7.1. Time Zone Representation 722 As specified in Section 6.5.1 of [RFC6350], the time zone information 723 can be represented in three ways: as a time zone name, as a UTC 724 offset or as a URI. 726 o The time zone name is directly matched by the "timeZone" member in 727 JSContact. 729 o An UTC offset MUST be converted into the related "Etc/GMT" time 730 zone (e.g. the value "-0500" converts to "Etc/GMT+5"). If the UTC 731 offset value contains minutes information, it MUST be mapped to 732 the zone "Etc/GMT:". 734 o Since there is no URI scheme defined for time zones [uri-schemes], 735 any implementation that does use some a custom URI for a time zone 736 is not interoperable anyway. In this case, if the URI corresponds 737 to an IANA time zone [time-zones], this latter SHOULD be used. 738 Otherwise, the URI value is dumped into a string. 740 2.8. Organizational Properties 742 2.8.1. TITLE and ROLE 744 Both TITLE and ROLE properties are represented as entries of the 745 "titles" map (Figure 11). The entry value is a "Title" object whose 746 "title" member includes information about the language. 748 The ALTID and LANGUAGE parameters are mapped according to the rules 749 as defined in (Section 2.1). The "title.localizations" includes 750 possible language-dependent alternatives. 752 BEGIN:VCARD 753 VERSION:4.0 754 ... 755 TITLE:Research Scientist 756 ROLE:Project Leader 757 ... 758 END:VCARD 760 { 761 ... 762 "titles":{ 763 "a-title":{ 764 "title":{ "value" : "Project Leader" } 765 }, 766 "another-title":{ 767 "title":{ "value" : "Research Scientist" } 768 } 769 }, 770 ... 771 } 773 Figure 11: TITLE and ROLE mapping example 775 2.8.2. LOGO 777 A LOGO property is represented as an entry of the "online" map 778 (Figure 12). The entry value is a "Resource" object whose "type" 779 member is set to "uri", the "label" member is set to "logo" and the 780 "resource" member is the LOGO value. 782 The PREF and TYPE parameters are mapped according to the rules as 783 defined in (Section 2.1). 785 BEGIN:VCARD 786 VERSION:4.0 787 ... 788 LOGO:http://www.example.com/pub/logos/abccorp.jpg 789 ... 790 END:VCARD 792 { 793 ... 794 "online":{ 795 ... 796 "a-logo":{ 797 "type": "uri", 798 "label": "logo", 799 "resource": "http://www.example.com/pub/logos/abccorp.jpg" 800 }, 801 ... 802 }, 803 ... 804 } 806 Figure 12: LOGO mapping example 808 2.8.3. ORG 810 An ORG property is represented as an entry of the "organizations" map 811 (Figure 13). The entry value is an "Organization" object whose 812 "name" member contains the organizational name and the "units" member 813 contains the organizational units. 815 The ALTID and LANGUAGE parameters are mapped according to the rules 816 as defined in (Section 2.1). The "localizations" maps for both 817 "name" and "units" include possible language-dependent alternatives. 819 BEGIN:VCARD 820 VERSION:4.0 821 ... 822 ORG:ABC\, Inc.;North American Division;Marketing 823 ... 824 END:VCARD 826 { 827 ... 828 "organizations":{ 829 "an-organization":{ 830 "name":{ "value": "ABC, Inc." }, 831 "units":[ 832 { "value": "North American Division" }, 833 { "value": "Marketing" } 834 ] 835 } 836 }, 837 ... 838 } 840 Figure 13: ORG mapping example 842 2.8.4. MEMBER 844 According to the JSContact specification, a group of contact cards is 845 represented through a JSCardGroup (Figure 14). The uids of the 846 contact cards composing the group are included in the "members" map. 848 In this case, the PREF parameter has not a JSContact counterpart; 849 however, the implementers MAY insert the map entries by order of 850 preference. 852 BEGIN:VCARD 853 VERSION:4.0 854 KIND:group 855 FN:The Doe family 856 MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 857 MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 858 END:VCARD 859 BEGIN:VCARD 860 VERSION:4.0 861 FN:John Doe 862 UID:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 863 END:VCARD 864 BEGIN:VCARD 865 VERSION:4.0 866 FN:Jane Doe 867 UID:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 868 END:VCARD 870 [ 871 { 872 "kind": "group", 873 "fullName":{ "value": "The Doe family" }, 874 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 875 "members":{ 876 "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, 877 "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true 878 } 879 }, 880 { 881 "fullName":{ "value": "John Doe" }, 882 "uid": "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af" 883 }, 884 { 885 "fullName":{ "value": "Jane Doe" }, 886 "uid": "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519" 887 } 888 ] 890 Figure 14: Group example 892 2.8.5. RELATED 894 All the RELATED instances are globally converted into the "relatedTo" 895 map (Figure 15): an entry for each entity the entity described by the 896 JSCard is associated with. The map keys are the "uid" values of the 897 associated cards. 899 Each map value is a "Relation" object including only the "relation" 900 member represented as a set of the RELATED-specific values of the 901 TYPE parameter as defined in Section 6.6.6 of [RFC6350]. 903 If the relation type is unspecified, the "relation" member MUST be 904 empty. 906 BEGIN:VCARD 907 VERSION:4.0 908 ... 909 RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 910 RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf 911 RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries. 912 ... 913 END:VCARD 915 { 916 ... 917 "relatedTo":{ 918 { 919 "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6":{ 920 "relation":{ "friend": true } 921 } 922 }, 923 { 924 "http://example.com/directory/jdoe.vcf":{ 925 "relation":{ "contact": true } 926 } 927 }, 928 { 929 "Please contact my assistant Jane Doe for any inquiries.":{ 930 "relation":{ } 931 } 932 } 933 }, 934 ... 935 } 937 Figure 15: RELATED mapping example 939 2.8.6. CONTACT-URI 941 A CONTACT-URI property as defined in [RFC8605] is represented as an 942 entry of the "online" map (Figure 16). The entry value is a 943 "Resource" object whose "type" member is set to "uri", the "label" 944 member is set to "contact-uri" and the "resource" member is the 945 CONTACT-URI value. 947 The PREF and TYPE parameters are mapped according to the rules as 948 defined in (Section 2.1). 950 BEGIN:VCARD 951 VERSION:4.0 952 ... 953 CONTACT-URI;PREF=1:mailto:contact@example.com 954 ... 955 END:VCARD 957 { 958 ... 959 "online":{ 960 ... 961 "a-contact-uri":{ 962 "type": "uri", 963 "label": "contact-uri", 964 "resource": "mailto:contact@example.com", 965 "pref": 1 966 }, 967 ... 968 }, 969 ... 970 } 972 Figure 16: CONTACT-URI mapping example 974 2.9. Personal Information Properties 976 2.9.1. EXPERTISE 978 An EXPERTISE property as defined in [RFC6715] is represented as a 979 "PersonalInformation" object in the "personalInfo" array (Figure 17). 980 The "type" member is set to "expertise". 982 The INDEX parameter is represented as the index of the expertise 983 among the declared expertises. 985 The LEVEL parameter is mapped according to the rules as defined in 986 (Section 2.1). 988 BEGIN:VCARD 989 VERSION:4.0 990 ... 991 EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature 992 EXPERTISE;INDEX=1;LEVEL=expert:chemistry 993 ... 994 END:VCARD 996 { 997 ... 998 "personalInfo":[ 999 ... 1000 { 1001 "type": "expertise", 1002 "value": "chemistry", 1003 "level": "high" 1004 }, 1005 { 1006 "type": "expertise", 1007 "value": "chinese literature", 1008 "level": "low" 1009 }, 1010 ... 1011 ], 1012 ... 1013 } 1015 Figure 17: EXPERTISE mapping example 1017 2.9.2. HOBBY 1019 A HOBBY property as defined in [RFC6715] is represented as a 1020 "PersonalInformation" object in the "personalInfo" array (Figure 18). 1021 The "type" member is set to "hobby". 1023 The INDEX parameter is represented as the index of the hobby among 1024 the declared hobbies. 1026 The LEVEL parameter is mapped according to the rules as defined in 1027 (Section 2.1). 1029 BEGIN:VCARD 1030 VERSION:4.0 1031 ... 1032 HOBBY;INDEX=1;LEVEL=high:reading 1033 HOBBY;INDEX=2;LEVEL=high:sewing 1034 ... 1035 END:VCARD 1037 { 1038 ... 1039 "personalInfo":[ 1040 ... 1041 { 1042 "type": "hobby", 1043 "value": "reading", 1044 "level": "high" 1045 }, 1046 { 1047 "type": "hobby", 1048 "value": "sewing", 1049 "level": "high" 1050 }, 1051 ... 1052 ], 1053 ... 1054 } 1056 Figure 18: HOBBY mapping example 1058 2.9.3. INTEREST 1060 An INTEREST property as defined in [RFC6715] is represented as a 1061 "PersonalInformation" object in the "personalInfo" array (Figure 19). 1062 The "type" member is set to "interest". 1064 The INDEX parameter is represented as the index of the interest among 1065 the declared interests. 1067 The LEVEL parameter is mapped according to the rules as defined in 1068 (Section 2.1). 1070 BEGIN:VCARD 1071 VERSION:4.0 1072 ... 1073 INTEREST;INDEX=1;LEVEL=medium:r&b music 1074 INTEREST;INDEX=2;LEVEL=high:rock 'n' roll music 1075 ... 1076 END:VCARD 1078 { 1079 ... 1080 "personalInfo":[ 1081 ... 1082 { 1083 "type": "interest", 1084 "value": "r&b music", 1085 "level": "medium" 1086 }, 1087 { 1088 "type": "interest", 1089 "value": "rock 'n' roll music", 1090 "level": "high" 1091 }, 1092 ... 1093 ], 1094 ... 1095 } 1097 Figure 19: INTEREST mapping example 1099 2.9.4. ORG-DIRECTORY 1101 An ORG-DIRECTORY property is represented as an entry of the "online" 1102 map (Figure 20). The entry value is a "Resource" object whose "type" 1103 member is set to "uri", the "label" member is set to "org-directory" 1104 and the "resource" member is the ORG-DIRECTORY value. 1106 The PREF and TYPE parameters are mapped according to the rules as 1107 defined in (Section 2.1). 1109 The INDEX parameter is represented as the index of the directory 1110 among the online resources with the "org-directory" label. 1112 BEGIN:VCARD 1113 VERSION:4.0 1114 ... 1115 ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com 1116 ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering 1117 ... 1118 END:VCARD 1120 { 1121 ... 1122 "online":{ 1123 ... 1124 "an-org-directory":{ 1125 "type": "uri", 1126 "label": "org-directory", 1127 "resource": "http://directory.mycompany.example.com" 1128 }, 1129 "another-org-directory":{ 1130 "type": "uri", 1131 "label": "org-directory", 1132 "resource": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering", 1133 "pref": 1 1134 }, 1135 ... 1136 }, 1137 ... 1138 } 1140 Figure 20: ORG-DIRECTORY mapping example 1142 2.10. Explanatory Properties 1144 2.10.1. CATEGORIES 1146 A CATEGORIES property is converted into a set of entries of the 1147 "categories" map (Figure 21). The keys are the comma-separated text 1148 values of the CATEGORIES property. 1150 In this case, the PREF parameter has not a JSContact counterpart; 1151 however, implementers MAY use a map preserving the order of insertion 1152 and the map entries can be inserted by order of preference. 1154 BEGIN:VCARD 1155 VERSION:4.0 1156 ... 1157 CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY 1158 ... 1159 END:VCARD 1161 { 1162 ... 1163 "categories":{ 1164 "INTERNET": true, 1165 "IETF": true, 1166 "INDUSTRY": true, 1167 "INFORMATION TECHNOLOGY": true 1168 }, 1169 ... 1170 } 1172 Figure 21: CATEGORIES mapping example 1174 2.10.2. NOTE 1176 A NOTE property is mapped onto the "notes" property (Figure 22). All 1177 the NOTE instances are condensed in a single note and separated by 1178 newline. 1180 The ALTID and LANGUAGE parameters are mapped according to the rules 1181 as defined in (Section 2.1). The "localizations" map includes 1182 possible language-dependent alternatives. 1184 BEGIN:VCARD 1185 VERSION:4.0 1186 ... 1187 NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri. 1188 ... 1189 END:VCARD 1191 { 1192 ... 1193 "notes": { 1194 "value": "This fax number is operational 0800 to 1715 EST, Mon-Fri." 1195 }, 1196 ... 1197 } 1199 Figure 22: NOTE mapping example 1201 2.10.3. PRODID 1203 The PRODID property is converted into the "prodId" member 1204 (Figure 23). 1206 BEGIN:VCARD 1207 VERSION:4.0 1208 ... 1209 PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN 1210 ... 1211 END:VCARD 1213 { 1214 ... 1215 "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN", 1216 ... 1217 } 1219 Figure 23: PRODID mapping example 1221 2.10.4. REV 1223 The REV property is transformed into the "updated" member 1224 (Figure 24). 1226 BEGIN:VCARD 1227 VERSION:4.0 1228 ... 1229 REV:19951031T222710Z 1230 ... 1231 END:VCARD 1233 { 1234 ... 1235 "updated": "1995-10-31T22:27:10Z", 1236 ... 1237 } 1239 Figure 24: REV mapping example 1241 2.10.5. SOUND 1243 A SOUND property is represented as an entry of the "online" map 1244 (Figure 25). The entry value is a "Resource" object whose "type" 1245 member is set to "uri", the "label" member is set to "sound" and the 1246 "resource" member is the SOUND value. 1248 The PREF and TYPE parameters are mapped according to the rules as 1249 defined in (Section 2.1). 1251 BEGIN:VCARD 1252 VERSION:4.0 1253 ... 1254 SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com 1255 ... 1256 END:VCARD 1258 { 1259 ... 1260 "online":{ 1261 ... 1262 "a-sound":{ 1263 "type": "uri", 1264 "label": "sound", 1265 "resource": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com" 1266 }, 1267 ... 1268 }, 1269 ... 1270 } 1272 Figure 25: SOUND mapping example 1274 2.10.6. UID 1276 The UID property corresponds to the "uid" property (Figure 26). 1278 BEGIN:VCARD 1279 VERSION:4.0 1280 ... 1281 UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 1282 ... 1283 END:VCARD 1285 { 1286 ... 1287 "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6", 1288 ... 1289 } 1291 Figure 26: UID mapping example 1293 2.10.7. CLIENTPIDMAP and PID Parameter 1295 The CLIENTPIDMAP property and the PDI parameter don't have a direct 1296 match with a JSCard feature. 1298 2.10.8. URL 1300 An URL property is represented as an entry of the "online" map 1301 (Figure 27). The entry value is a "Resource" object whose "type" 1302 member is set to "uri", the "label" member is set to "url" and the 1303 "resource" member is the URL value. 1305 The PREF and TYPE parameters are mapped according to the rules as 1306 defined in (Section 2.1). 1308 BEGIN:VCARD 1309 VERSION:4.0 1310 ... 1311 URL:http://example.org/restaurant.french/~chezchic.html 1312 ... 1313 END:VCARD 1315 { 1316 ... 1317 "online":{ 1318 ... 1319 "an-url":{ 1320 "type": "uri", 1321 "label": "url", 1322 "resource": "http://example.org/restaurant.french/~chezchic.html" 1323 }, 1324 ... 1325 }, 1326 ... 1327 } 1329 Figure 27: URL mapping example 1331 2.10.9. VERSION 1333 The VERSION property doesn't have a direct match with a JSContact 1334 feature. 1336 2.11. Security Properties 1337 2.11.1. KEY 1339 A KEY property is represented as an entry of the "online" map 1340 (Figure 28). The entry value is a "Resource" object whose "type" 1341 member is set to "uri", the "label" member is set to "key" and the 1342 "resource" member is the KEY value. 1344 The PREF and TYPE parameters are mapped according to the rules as 1345 defined in (Section 2.1). 1347 BEGIN:VCARD 1348 VERSION:4.0 1349 ... 1350 KEY:http://www.example.com/keys/jdoe.cer 1351 ... 1352 END:VCARD 1354 { 1355 ... 1356 "online":{ 1357 ... 1358 "a-key":{ 1359 "type": "uri", 1360 "label": "key", 1361 "resource": "http://www.example.com/keys/jdoe.cer" 1362 }, 1363 ... 1364 }, 1365 ... 1366 } 1368 Figure 28: KEY mapping example 1370 2.12. Calendar Properties 1372 2.12.1. FBURL 1374 An FBURL property is represented as an entry of the "online" map 1375 (Figure 29). The entry value is a "Resource" object whose "type" 1376 member is set to "uri", the "label" member is set to "fburl" and the 1377 "resource" member is the FBURL value. 1379 The PREF and TYPE parameters are mapped according to the rules as 1380 defined in (Section 2.1). 1382 BEGIN:VCARD 1383 VERSION:4.0 1384 ... 1385 FBURL;PREF=1:http://www.example.com/busy/janedoe 1386 FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb 1387 ... 1388 END:VCARD 1390 { 1391 ... 1392 "online":{ 1393 ... 1394 "an-fburl":{ 1395 "type": "uri", 1396 "label": "fburl", 1397 "resource": "http://www.example.com/busy/janedoe", 1398 "pref": 1 1399 }, 1400 "another-fburl":{ 1401 "type": "uri", 1402 "label": "fburl", 1403 "resource": "ftp://example.com/busy/project-a.ifb", 1404 "mediaType": "text/calendar" 1405 }, 1406 ... 1407 }, 1408 ... 1409 } 1411 Figure 29: FBURL mapping example 1413 2.12.2. CALADRURI 1415 A CALADRURI property is represented as an entry of the "online" map 1416 (Figure 30). The entry value is a "Resource" object whose "type" 1417 member is set to "uri", the "label" member is set to "caladruri" and 1418 the "resource" member is the CALADRURI value. 1420 The PREF and TYPE parameters are mapped according to the rules as 1421 defined in (Section 2.1). 1423 BEGIN:VCARD 1424 VERSION:4.0 1425 ... 1426 CALADRURI;PREF=1:mailto:janedoe@example.com 1427 CALADRURI:http://example.com/calendar/jdoe 1428 ... 1429 END:VCARD 1431 { 1432 ... 1433 "online":{ 1434 ... 1435 "a-caladruri":{ 1436 "type": "uri", 1437 "label": "caladruri", 1438 "resource": "mailto:janedoe@example.com", 1439 "pref": 1 1440 }, 1441 "another-caladruri":{ 1442 "type": "uri", 1443 "label": "caladruri", 1444 "resource": "http://example.com/calendar/jdoe" 1445 }, 1446 ... 1447 }, 1448 ... 1449 } 1451 Figure 30: CALADRURI mapping example 1453 2.12.3. CALURI 1455 A CALURI property is represented as an entry of the "online" map 1456 (Figure 31). The entry value is a "Resource" object whose "type" 1457 member is set to "uri", the "label" member is set to "caluri" and the 1458 "resource" member is the CALURI value. 1460 The PREF and TYPE parameters are mapped according to the rules as 1461 defined in (Section 2.1). 1463 BEGIN:VCARD 1464 VERSION:4.0 1465 ... 1466 CALURI;PREF=1:http://cal.example.com/calA 1467 CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics 1468 ... 1469 END:VCARD 1471 { 1472 ... 1473 "online":{ 1474 ... 1475 "a-caluri":{ 1476 "type": "uri", 1477 "label": "caluri", 1478 "resource": "http://cal.example.com/calA", 1479 "pref": 1 1480 }, 1481 "another-caluri":{ 1482 "type": "uri", 1483 "label": "caluri", 1484 "resource": "ftp://ftp.example.com/calA.ics", 1485 "mediaType": "text/calendar" 1486 }, 1487 ... 1488 }, 1489 ... 1490 } 1492 Figure 31: CALURI mapping example 1494 2.13. vCard Unmatched Properties 1496 The unmatched vCard properties MAY be converted into JSContact 1497 properties whose name contains the prefix "ietf.org/RFC6350/" 1498 followed by property name in uppercase (i.e. ietf.org/RFC6350/ 1499 GENDER"). 1501 2.14. JSCard Required Properties 1503 While converting a vCard into a JSCard/JSCardGroup, only the topmost 1504 "uid" member is mandatory. Implementers are REQUIRED to set it when 1505 it is missing. 1507 3. Translating JSContact properties to vCard 1509 In most of the cases, the rules about the translation from JSCard/ 1510 JSCardGroup to vCard can be derived by reversing the rules presented 1511 in Section 2. The remaining cases are treated in the following of 1512 this section. 1514 3.1. Id 1516 Where a map key is of type Id, implementers are free to either ignore 1517 it or preserve it as a vCard information (e.g. a vCard parameter). 1519 3.2. Localizations 1521 A LocalizedString object is converted in multiple instances of the 1522 same vCard property having different values of the LANGUAGE 1523 parameter. Implementers MAY set the ALTID parameter to couple 1524 language-based alternatives of the same value. 1526 Note also that the components of some vCard values and their related 1527 alternatives are split into different JSContact values. For example, 1528 the "name" and "units" values for a given language must be grouped to 1529 make a single ORG value where components are separated by ";". 1531 3.3. Date and Time Representations 1533 The JSContact spec defines the "UTCDateTime" type to represent 1534 [RFC3339] "date-time" format with further restrictions. This means 1535 that the matched vCard format for a "UTCDateTime" value MUST be one 1536 of the formats shown in Section 4.3.5 of [RFC6350] (i.e. 1537 "19961022T140000Z"). 1539 In addition to such format, the "date" member of the "Anniversary" 1540 type allows specifying both a date without the time and a partial 1541 date. In this case, the corresponding vCard format is that defined 1542 in Section 4.3.1. 1544 3.4. Time Zone 1546 The time zone name as represented by the "timeZone" property is 1547 mapped onto the TZ parameter. 1549 Implementers MAY map an "Etc/GMT" time zone either preserving the 1550 time zone name or converting it into a UTC offset. 1552 3.5. JSContact Types Matching Multiple vCard Properties 1554 3.5.1. Title 1556 The "titles" property contains information about the job, the 1557 position or the role of the entity the card represents. In vCard, 1558 such information is split into the TITLE and ROLE properties. This 1559 specification defines TITLE as the default target property when 1560 converting the "titles" property. 1562 3.5.2. Resource 1564 The "online" property includes resources that are usually represented 1565 through different vCard properties. The matched vCard property of a 1566 "Resource" object can be derived from the value of its "label" 1567 member. 1569 Any resource included in the "online" map that doesn't match a vCard 1570 property MAY be converted into vCard extended properties. 1572 3.6. JSCard Unmatched Properties 1574 Both the "preferredContactMethod" and "created" members don't match 1575 any vCard property. Implementers MAY represent them as vCard 1576 extended properties. 1578 3.7. vCard Required Properties 1580 While converting a JSCard/JSCardGroup into a vCard, only the FN 1581 property is required. Since the "fullName" property is optional, 1582 implementers are REQUIRED to generate an FN value when it is missing. 1584 4. IANA Considerations 1586 This document has no actions for IANA. 1588 5. Implementation Status 1590 NOTE: Please remove this section and the reference to RFC 7942 prior 1591 to publication as an RFC. 1593 This section records the status of known implementations of the 1594 protocol as defined in this specification at the time of posting of 1595 this Internet-Draft, and is based on a proposal described in 1596 [RFC7942]. The description of implementations in this section is 1597 intended to assist the IETF in its decision processes in progressing 1598 drafts to RFCs. Please note that the listing of any individual 1599 implementation here does not imply endorsement by the IETF. 1601 Furthermore, no effort has been spent to verify the information 1602 presented here that was supplied by IETF contributors. This is not 1603 intended as, and must not be construed to be, a catalog of available 1604 implementations or their features. Readers are advised to note that 1605 other implementations may exist. 1607 According to RFC 7942, "this will allow reviewers and working groups 1608 to assign due considerationto documents that have the benefit of 1609 running code, which may serve as evidence of valuable experimentation 1610 and feedback that have made the implemented protocols more mature. 1611 It is up to the individual working groups to use this information as 1612 they see fit". 1614 5.1. CNR 1616 Responsible Organization: National Research Council (CNR) of Italy 1617 Location: https://github.com/consiglionazionaledellericerche/ 1618 jscontact-tools 1619 Description: This implementation includes tools for JSContact 1620 creation, validation, serialization/deserialization, and 1621 conversion from vCard, xCard and jCard. 1622 Level of Maturity: This is an "alpha" test implementation. 1623 Coverage: This implementation includes all of the features 1624 described in this specification. 1625 Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it 1627 6. Security Considerations 1629 This document doesn't present any security consideration. 1631 7. References 1633 7.1. Normative References 1635 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1636 Requirement Levels", BCP 14, RFC 2119, 1637 DOI 10.17487/RFC2119, March 1997, 1638 . 1640 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1641 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1642 . 1644 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 1645 DOI 10.17487/RFC6350, August 2011, 1646 . 1648 [RFC6473] Saint-Andre, P., "vCard KIND:application", RFC 6473, 1649 DOI 10.17487/RFC6473, December 2011, 1650 . 1652 [RFC6474] Li, K. and B. Leiba, "vCard Format Extensions: Place of 1653 Birth, Place and Date of Death", RFC 6474, 1654 DOI 10.17487/RFC6474, December 2011, 1655 . 1657 [RFC6715] Cauchie, D., Leiba, B., and K. Li, "vCard Format 1658 Extensions: Representing vCard Extensions Defined by the 1659 Open Mobile Alliance (OMA) Converged Address Book (CAB) 1660 Group", RFC 6715, DOI 10.17487/RFC6715, August 2012, 1661 . 1663 [RFC6869] Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard 1664 KIND:device", RFC 6869, DOI 10.17487/RFC6869, February 1665 2013, . 1667 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 1668 DOI 10.17487/RFC7095, January 2014, 1669 . 1671 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1672 Code: The Implementation Status Section", BCP 205, 1673 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1674 . 1676 [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: 1677 ICANN Extensions for the Registration Data Access Protocol 1678 (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, 1679 . 1681 7.2. Informative References 1683 [draft-ietf-jmap-jscontact] 1684 "JSContact: A JSON representation of contact data", 1685 . 1688 [time-zones] 1689 "Time Zone Database", . 1691 [uri-schemes] 1692 "Uniform Resource Identifier (URI) Schemes", 1693 . 1696 Authors' Addresses 1698 Mario Loffredo 1699 IIT-CNR/Registro.it 1700 Via Moruzzi,1 1701 Pisa 56124 1702 IT 1704 Email: mario.loffredo@iit.cnr.it 1705 URI: http://www.iit.cnr.it 1707 Robert Stepanek 1708 FastMail 1709 PO Box 234, Collins St West 1710 Melbourne VIC 8007 1711 AU 1713 Email: rsto@fastmailteam.com 1714 URI: https://www.fastmail.com