idnits 2.17.1 draft-ietf-jmap-jscontact-vcard-07.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: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. 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 (20 October 2021) is 917 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 1694, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 8605 Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 jmap M. Loffredo 3 Internet-Draft IIT-CNR/Registro.it 4 Intended status: Standards Track R. Stepanek 5 Expires: 23 April 2022 FastMail 6 20 October 2021 8 JSContact: Converting from and to vCard 9 draft-ietf-jmap-jscontact-vcard-07 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 23 April 2022. 34 Copyright Notice 36 Copyright (c) 2021 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 41 license-info) in effect on the date of publication of this document. 42 Please review these documents carefully, as they describe your rights 43 and restrictions with respect to this document. Code Components 44 extracted from this document must include Simplified BSD License text 45 as described in Section 4.e of the Trust Legal Provisions and are 46 provided without warranty as described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.2. Scope and Caveats . . . . . . . . . . . . . . . . . . . . 4 53 1.2.1. Extensions . . . . . . . . . . . . . . . . . . . . . 4 54 1.3. Conventions Used in This Document . . . . . . . . . . . . 4 55 2. Translating vCard properties to JSContact . . . . . . . . . . 5 56 2.1. Common Parameters . . . . . . . . . . . . . . . . . . . . 5 57 2.2. Unmapped JSContact Information . . . . . . . . . . . . . 5 58 2.3. General Properties . . . . . . . . . . . . . . . . . . . 5 59 2.3.1. BEGIN and END . . . . . . . . . . . . . . . . . . . . 6 60 2.3.2. SOURCE . . . . . . . . . . . . . . . . . . . . . . . 6 61 2.3.3. KIND . . . . . . . . . . . . . . . . . . . . . . . . 6 62 2.3.4. XML . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 2.4. Identification Properties . . . . . . . . . . . . . . . . 7 64 2.4.1. FN . . . . . . . . . . . . . . . . . . . . . . . . . 7 65 2.4.2. N and NICKNAME . . . . . . . . . . . . . . . . . . . 7 66 2.4.3. PHOTO . . . . . . . . . . . . . . . . . . . . . . . . 8 67 2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, 68 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 . . . . . . . . . . . . . . . . . . 39 126 7.2. Informative References . . . . . . . . . . . . . . . . . 40 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 * 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. 159 * 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 Card/ 186 CardGroup 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 Card/ 192 CardGroup. The vCard properties are grouped according to the 193 categories as defined in [RFC6350]. 195 If a vCard represents a group of contacts, those vCard properties 196 which don't have a counterpart in CardGroup are converted into 197 related properties of the "CardGroup.card" object. In this case, the 198 "uid" member of both the resulting CardGroup object and its "card" 199 member MUST have the same value. 201 2.1. Common Parameters 203 The following mapping rules apply to parameters that are common to 204 most of the vCard properties: 206 * The generic values of the TYPE parameter are mapped to the values 207 of the "Context" type as defined in Section 1.5.1 of 208 [draft-ietf-jmap-jscontact]. The "home" value corresponds to the 209 "private" key. The mapping of those specific TYPE values used in 210 the TEL and RELATED properties are defined in Section 2.6.1 and 211 Section 2.8.5. 212 * The PREF parameter is mapped to the "pref" property. 213 * The MEDIATYPE parameter is mapped to the "mediaType" property. As 214 described in Section 5.7 of [RFC6350], the media type of a 215 resource can be identified by its URI. For example, "image/gif" 216 can be derived from the ".gif" extension of a GIF image URI. 217 JSContact producers MAY provide the media type information even 218 when it is not specified in the vCard. 219 * The ALTID and LANGUAGE parameters are used in combination for 220 associating the language-dependent alternatives with a given 221 property. Such alternatives are represented by using the 222 "localizations" map: the "localizations" key is the LANGUAGE 223 value, the key of the related PatchObject map is the JSON pointer 224 of the JSContact member matching the vCard property while the 225 value is the JSContact member itself. 227 2.2. Unmapped JSContact Information 229 The rules to generate a map key of type Id as well as a value for 230 "created", "language" and "preferredContactMethod" properties are out 231 of the scope of this document. 233 2.3. General Properties 234 2.3.1. BEGIN and END 236 The BEGIN and END properties don't have a direct match with a 237 JSContact feature. 239 2.3.2. SOURCE 241 A SOURCE property is represented as an entry of the "online" map 242 (Figure 1). The entry value is a "Resource" object whose "type" 243 member is set to "uri", the "label" member is set to "source" and the 244 "resource" member is the SOURCE value. 246 The PREF and MEDIATYPE parameters are mapped according to the rules 247 as defined in (Section 2.1). 249 BEGIN:VCARD 250 VERSION:4.0 251 ... 252 SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf 253 ... 254 END:VCARD 256 { 257 ... 258 "online":{ 259 ... 260 "a-source":{ 261 "type": "uri", 262 "label": "source", 263 "resource": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf" 264 }, 265 ... 266 }, 267 ... 268 } 270 Figure 1: SOURCE mapping example 272 2.3.3. KIND 274 The KIND property is mapped to the "kind" member (Figure 2). Allowed 275 values are those described in Section 6.1.4 of [RFC6350] and extended 276 with the values declared in [RFC6473] and [RFC6869]. The value 277 "group" is reserved for a CardGroup instance. 279 BEGIN:VCARD 280 VERSION:4.0 281 ... 282 KIND:individual 283 ... 284 END:VCARD 286 { 287 ... 288 "kind": "individual", 289 ... 290 } 292 Figure 2: KIND mapping example 294 2.3.4. XML 296 The XML property doesn't have a direct match with a JSContact 297 feature. 299 2.4. Identification Properties 301 2.4.1. FN 303 All the FN instances are represented through the "fullName" member 304 (Figure 3). The presence of multiple instances is implicitly 305 associated with the full name translations in various languages 306 regardless of the presence of the ALTID parameter. Each translation 307 is mapped according to the rules as defined in (Section 2.1). 309 If the vCard represents a group of contacts, implementers MAY convert 310 the FN property into either "CardGroup.card.fullName" or 311 "CardGroup.name" or both properties. 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 to an item of "nickNames" array. 323 +====================+==============+ 324 | N component | "type" value | 325 +====================+==============+ 326 | Honorific Prefixes | prefix | 327 +--------------------+--------------+ 328 | Given Names | personal | 329 +--------------------+--------------+ 330 | Family Names | surname | 331 +--------------------+--------------+ 332 | Additional Names | additional | 333 +--------------------+--------------+ 334 | Honorific Suffixes | suffix | 335 +--------------------+--------------+ 337 Table 1: N components mapping 339 BEGIN:VCARD 340 VERSION:4.0 341 ... 342 FN:Mr. John Q. Public\, Esq. 343 N:Public;John;Quinlan;Mr.;Esq. 344 NICKNAME:Johnny 345 ... 346 END:VCARD 348 { 349 ... 350 "fullName":{ "value": "Mr. John Q. Public, Esq." }, 351 "name":[ 352 { "value":"Mr.", "type": "prefix" }, 353 { "value":"John", "type": "personal" }, 354 { "value":"Public", "type": "surname" }, 355 { "value":"Quinlan", "type": "additional" }, 356 { "value":"Esq.", "type": "suffix" } 357 ], 358 "nickNames":[ 359 { "value": "Johnny" } 360 ], 361 ... 362 } 364 Figure 3: FN, N, NICKNAME mapping example 366 2.4.3. PHOTO 368 A PHOTO property is represented as an entry of the "photos" map 369 (Figure 4). The entry value is a "File" object whose "href" member 370 is the PHOTO value. 372 The PREF and MEDIATYPE parameters are mapped according to the rules 373 as defined in (Section 2.1). 375 BEGIN:VCARD 376 VERSION:4.0 377 ... 378 PHOTO:http://www.example.com/pub/photos/jqpublic.gif 379 ... 380 END:VCARD 382 { 383 ... 384 "photos":{ 385 ... 386 "a-photo":{ 387 "href": "http://www.example.com/pub/photos/jqpublic.gif" 388 }, 389 ... 390 }, 391 ... 392 } 394 Figure 4: PHOTO mapping example 396 2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 398 The BDAY and ANNIVERSARY properties and the extensions BIRTHPLACE, 399 DEATHDATE, DEATHPLACE described in [RFC6350] are represented as 400 "Anniversary" objects included in the "anniversaries" map (Figure 5): 402 * BDAY and BIRTHPLACE are mapped to "date" and "place" where "type" 403 is set to "birth"; 404 * DEATHDATE and DEATHPLACE are mapped to "date" and "place" where 405 "type" is set to "death"; 406 * ANNIVERSARY is mapped to "date" where "type" is set to "other" and 407 "label" is set to a value describing in detail the kind of 408 anniversary (e.g. "marriage date" for the wedding anniversary). 410 Both birth and death places are represented as instances of the 411 "Address" object. 413 The BIRTHPLACE and DEATHPLACE properties that are represented as geo 414 URIs are converted into "Address" instances including only the 415 "coordinates" member. If the URI value is not a geo URI, the place 416 is ignored. 418 The ALTID and LANGUAGE parameters of both BIRTHPLACE and DEATHPLACE 419 properties are mapped according to the rules as defined in 420 (Section 2.1). 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 "ANNIVERSARY-1" : { 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 "ANNIVERSARY-2" : { 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 "ANNIVERSARY-3" : { 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 and Table 3. 481 The "street address" and "extended address" ADR components MAY be 482 converted into either a single StreetComponent item or a combination 483 of StreetComponent items. 485 +===============+================+ 486 | ADR component | Address member | 487 +===============+================+ 488 | locality | locality | 489 +---------------+----------------+ 490 | region | region | 491 +---------------+----------------+ 492 | postal code | postcode | 493 +---------------+----------------+ 494 | country name | country | 495 +---------------+----------------+ 497 Table 2: ADR components vs. 498 Address members mapping 500 +===============+======================+========================+ 501 | ADR component | Single | Combination of | 502 | | StreetComponent item | StreetComponent items | 503 +===============+======================+========================+ 504 | post office | postOfficeBox | | 505 | box | | | 506 +---------------+----------------------+------------------------+ 507 | extended | extension | extension, building, | 508 | address | | floor, room, apartment | 509 +---------------+----------------------+------------------------+ 510 | street | name | name, number, | 511 | address | | direction | 512 +---------------+----------------------+------------------------+ 514 Table 3: ADR components vs. StreetComponent items mapping 516 The LABEL parameter is converted into the "fullAddress" member. 518 The GEO parameter is converted into the "coordinates" member. 520 The TZ parameter is converted into the "timeZone" member. 522 The CC parameter as defined in [RFC8605] is converted into the 523 "countryCode" member. 525 The PREF and TYPE parameters are mapped according to the rules as 526 defined in (Section 2.1). 528 The ALTID and LANGUAGE parameters are mapped according to the rules 529 as defined in (Section 2.1). Each possible language-dependent 530 alternative is represented as an entry of the PatchObject map where 531 the key references the "fullAddress" member. 533 BEGIN:VCARD 534 VERSION:4.0 535 ... 536 ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA 537 ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA 538 ... 539 END:VCARD 541 { 542 ... 543 "addresses":{ 544 "work-address" :{ 545 "contexts":{ "work": true }, 546 "fullAddress":{ 547 "value": "54321 Oak St\nReston\nVA\n20190\nUSA" 548 }, 549 "street": [ 550 { "name": "Oak St" }, 551 { "number" : "54321" } 552 ], 553 "locality": "Reston", 554 "region": "VA", 555 "country": "USA", 556 "postcode": "20190", 557 "countryCode": "US" 558 }, 559 "private-address":{ 560 "contexts":{ "private": true }, 561 "fullAddress":{ 562 "value": "12345 Elm St\nReston\nVA\n20190\nUSA" 563 }, 564 "street": [ 565 { "name": "Elm St" }, 566 { "number" : "12345" } 567 ], 568 "locality": "Reston", 569 "region": "VA", 570 "country": "USA", 571 "postcode": "20190", 572 "countryCode": "US" 573 } 574 }, 575 ... 576 } 578 Figure 6: ADR mapping example 580 2.6. Communications Properties 582 2.6.1. TEL 584 A TEL property is represented as an entry of the "phones" map 585 (Figure 7). The entry value is a "Phone" object. The TEL-specific 586 values of the TYPE parameter are mapped to the "features" map keys. 587 The values that don't match a key are represented as comma-separated 588 values of the "label" member. If the "features" map is empty and the 589 "label" member is not empty, the "other" feature is added. The 590 "phone" member is set to the TEL value. 592 The PREF and TYPE parameters are mapped according to the rules as 593 defined in (Section 2.1). 595 BEGIN:VCARD 596 VERSION:4.0 597 ... 598 TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555 599 TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67 600 ... 601 END:VCARD 603 { 604 ... 605 "phones":{ 606 "a-phone":{ 607 "contexts":{ "private": true }, 608 "features":{ "voice": true }, 609 "phone": "tel:+1-555-555-5555;ext=5555", 610 "pref": 1 611 }, 612 "another-phone":{ 613 "contexts":{ "private": true }, 614 "phone": "tel:+33-01-23-45-67" 615 } 616 ], 617 ... 618 } 620 Figure 7: TEL mapping example 622 2.6.2. EMAIL 624 An EMAIL property is represented as an entry of the "emails" map 625 (Figure 8). The entry value is an "EmailAddress" object. The 626 "email" member is set to the EMAIL value. 628 The PREF and TYPE parameters are mapped according to the rules as 629 defined in (Section 2.1). 631 BEGIN:VCARD 632 VERSION:4.0 633 ... 634 EMAIL;TYPE=work:jqpublic@xyz.example.com 635 EMAIL;PREF=1:jane_doe@example.com 636 ... 637 END:VCARD 639 { 640 ... 641 "emails":{ 642 "work-email":{ 643 "contexts":{ "work": true }, 644 "email": "jqpublic@xyz.example.com" 645 }, 646 "private-email":{ 647 "contexts":{ "private", true }, 648 "email": "jane_doe@example.com", 649 "pref": 1 650 } 651 }, 652 ... 653 } 655 Figure 8: EMAIL mapping example 657 2.6.3. IMPP 659 An IMPP property is represented as an entry of the "online" map 660 (Figure 9). The entry value is a "Resource" object whose "type" 661 member is set to "username", the "label" member is set to "XMPP" and 662 the "resource" member is the IMPP value. 664 The PREF and TYPE parameters are mapped according to the rules as 665 defined in (Section 2.1). 667 BEGIN:VCARD 668 VERSION:4.0 669 ... 670 IMPP;PREF=1:xmpp:alice@example.com 671 ... 672 END:VCARD 674 { 675 ... 676 "online":{ 677 ... 678 { 679 "type": "username", 680 "label": "XMPP", 681 "value": "alice@example.com" 682 }, 683 ... 684 }, 685 ... 686 } 688 Figure 9: IMPP mapping example 690 2.6.4. LANG 692 A LANG property is represented as an entry of the 693 "preferredContactLanguages" map (Figure 10). The entry keys 694 correspond to the language tags, the corresponding entry values are 695 arrays of "ContactLanguage" objects. 697 The PREF and TYPE parameters are mapped according to the rules as 698 defined in (Section 2.1). 700 If both PREF and TYPE parameters are missing, the array of 701 "ContactLanguage" objects MUST be empty. 703 BEGIN:VCARD 704 VERSION:4.0 705 ... 706 LANG;TYPE=work;PREF=1:en 707 LANG;TYPE=work;PREF=2:fr 708 LANG;TYPE=home:fr 709 ... 710 END:VCARD 712 { 713 ... 714 "preferredContactLanguages":{ 715 "en":[ 716 { 717 "context": "work", 718 "pref": 1 719 } 720 ], 721 "fr":[ 722 { 723 "context": "work", 724 "pref": 2 725 }, 726 { 727 "context": "private" 728 } 729 ] 730 }, 731 ... 732 } 734 Figure 10: LANG mapping example 736 2.7. Geographical Properties 738 The GEO and TZ properties are not directly mapped to topmost Card 739 members because the same information is represented through 740 equivalent "Address" members. 742 The ALTID parameter is used for associating both GEO and TZ 743 properties with the related address information. When the ALTID 744 parameter is missing, the matched members SHOULD be included in the 745 first "Address" object. 747 2.7.1. Time Zone Representation 749 As specified in Section 6.5.1 of [RFC6350], the time zone information 750 can be represented in three ways: as a time zone name, as a UTC 751 offset or as a URI. 753 * If the TZ value is defined in the IANA timezone database, it is 754 directly matched by the "timeZone" member in JSContact. 755 * An UTC offset MUST be converted into the related "Etc/GMT" time 756 zone (e.g. the value "-0500" converts to "Etc/GMT+5"). If the UTC 757 offset value contains minutes information or is not an IANA 758 timezone name, it requires special handling. 759 * Since there is no URI scheme defined for time zones [uri-schemes], 760 any implementation that does use some a custom URI for a time zone 761 is not interoperable anyway. In this case, if the URI corresponds 762 to an IANA time zone [time-zones], this latter SHOULD be used. 763 Otherwise, the URI value is dumped into a string. 765 2.8. Organizational Properties 767 2.8.1. TITLE and ROLE 769 Both TITLE and ROLE properties are represented as entries of the 770 "titles" map (Figure 11). The entry value is a "Title" object whose 771 "title" member includes information about the title or role. The 772 rules to set the "organization" member are out of the scope of this 773 document. 775 The ALTID and LANGUAGE parameters are mapped according to the rules 776 as defined in (Section 2.1). 778 BEGIN:VCARD 779 VERSION:4.0 780 ... 781 TITLE:Research Scientist 782 ROLE:Project Leader 783 ... 784 END:VCARD 786 { 787 ... 788 "titles":{ 789 "a-title":{ 790 "title":{ "value" : "Project Leader" } 791 }, 792 "another-title":{ 793 "title":{ "value" : "Research Scientist" } 794 } 795 }, 796 ... 797 } 799 Figure 11: TITLE and ROLE mapping example 801 2.8.2. LOGO 803 A LOGO property is represented as an entry of the "online" map 804 (Figure 12). The entry value is a "Resource" object whose "type" 805 member is set to "uri", the "label" member is set to "logo" and the 806 "resource" member is the LOGO value. 808 The PREF and TYPE parameters are mapped according to the rules as 809 defined in (Section 2.1). 811 BEGIN:VCARD 812 VERSION:4.0 813 ... 814 LOGO:http://www.example.com/pub/logos/abccorp.jpg 815 ... 816 END:VCARD 818 { 819 ... 820 "online":{ 821 ... 822 "a-logo":{ 823 "type": "uri", 824 "label": "logo", 825 "resource": "http://www.example.com/pub/logos/abccorp.jpg" 826 }, 827 ... 828 }, 829 ... 830 } 832 Figure 12: LOGO mapping example 834 2.8.3. ORG 836 An ORG property is represented as an entry of the "organizations" map 837 (Figure 13). The entry value is an "Organization" object whose 838 "name" member contains the organizational name and the "units" member 839 contains the organizational units. 841 The ALTID and LANGUAGE parameters are mapped according to the rules 842 as defined in (Section 2.1). 844 BEGIN:VCARD 845 VERSION:4.0 846 ... 847 ORG:ABC\, Inc.;North American Division;Marketing 848 ... 849 END:VCARD 851 { 852 ... 853 "organizations":{ 854 "an-organization":{ 855 "name":{ "value": "ABC, Inc." }, 856 "units":[ 857 { "value": "North American Division" }, 858 { "value": "Marketing" } 859 ] 860 } 861 }, 862 ... 863 } 865 Figure 13: ORG mapping example 867 2.8.4. MEMBER 869 According to the JSContact specification, a group of contact cards is 870 represented through a CardGroup (Figure 14). The uids of the contact 871 cards composing the group are included in the "members" map. 873 In this case, the PREF parameter has not a JSContact counterpart; 874 however, the implementers MAY insert the map entries by order of 875 preference. 877 BEGIN:VCARD 878 VERSION:4.0 879 KIND:group 880 FN:The Doe family 881 MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 882 MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 883 END:VCARD 885 { 886 "kind": "group", 887 "fullName":{ "value": "The Doe family" }, 888 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 889 "members":{ 890 "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, 891 "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true 892 } 893 } 895 Figure 14: Group example 897 Only if the GROUP contains properties that don't have a mapping to 898 CardGroup properties, then the CardGroup.card property MAY contain 899 the optional Card object of this group. 901 { 902 "name": "The Doe family", 903 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 904 "members":{ 905 "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, 906 "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true 907 }, 908 "card": { 909 "fullName":{ "value": "The Doe family" }, 910 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 911 "photos":{ 912 "a-photo":{ 913 "href": "http://www.example.com/pub/photos/jqpublic.gif" 914 } 915 } 916 } 917 } 919 Figure 15: card member of CardGroup object 921 2.8.5. RELATED 923 All the RELATED instances are converted into the "relatedTo" map 924 (Figure 16): an entry for each entity the entity described by the 925 Card is associated with. The map keys are the "uid" values of the 926 associated cards. 928 Each map value is a "Relation" object including only the "relation" 929 member represented as a set of the RELATED-specific values of the 930 TYPE parameter as defined in Section 6.6.6 of [RFC6350]. 932 If the relation type is unspecified, the "relation" member MUST be 933 empty. 935 BEGIN:VCARD 936 VERSION:4.0 937 ... 938 RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 939 RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf 940 RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries. 941 ... 942 END:VCARD 944 { 945 ... 946 "relatedTo":{ 947 { 948 "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6":{ 949 "relation":{ "friend": true } 950 } 951 }, 952 { 953 "http://example.com/directory/jdoe.vcf":{ 954 "relation":{ "contact": true } 955 } 956 }, 957 { 958 "Please contact my assistant Jane Doe for any inquiries.":{ 959 "relation":{ } 960 } 961 } 962 }, 963 ... 964 } 966 Figure 16: RELATED mapping example 968 2.8.6. CONTACT-URI 970 A CONTACT-URI property as defined in [RFC8605] is represented as an 971 entry of the "online" map (Figure 17). The entry value is a 972 "Resource" object whose "type" member is set to "uri", the "label" 973 member is set to "contact-uri" and the "resource" member is the 974 CONTACT-URI value. 976 The PREF and TYPE parameters are mapped according to the rules as 977 defined in (Section 2.1). 979 BEGIN:VCARD 980 VERSION:4.0 981 ... 982 CONTACT-URI;PREF=1:mailto:contact@example.com 983 ... 984 END:VCARD 986 { 987 ... 988 "online":{ 989 ... 990 "a-contact-uri":{ 991 "type": "uri", 992 "label": "contact-uri", 993 "resource": "mailto:contact@example.com", 994 "pref": 1 995 }, 996 ... 997 }, 998 ... 999 } 1001 Figure 17: CONTACT-URI mapping example 1003 2.9. Personal Information Properties 1005 The LEVEL parameter as defined in [RFC6715] is directly mapped to the 1006 "level" property of the "PersonalInformation" type apart from when 1007 LEVEL is used in the EXPERTISE property; in this case, the values are 1008 converted as in the following: 1010 * "beginner" is converted into "low"; 1011 * "average" is converted into "medium"; 1012 * "expert" is converted into "high". 1014 2.9.1. EXPERTISE 1016 An EXPERTISE property as defined in [RFC6715] is represented as a 1017 "PersonalInformation" object in the "personalInfo" map (Figure 18). 1018 The "type" member is set to "expertise". 1020 The INDEX parameter is represented as the index of the expertise 1021 among the declared expertises. 1023 BEGIN:VCARD 1024 VERSION:4.0 1025 ... 1026 EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature 1027 EXPERTISE;INDEX=1;LEVEL=expert:chemistry 1028 ... 1029 END:VCARD 1031 { 1032 ... 1033 "personalInfo":{ 1034 ... 1035 "PERSINFO-1" : { 1036 "type": "expertise", 1037 "value": "chemistry", 1038 "level": "high" 1039 }, 1040 "PERSINFO-2" : { 1041 "type": "expertise", 1042 "value": "chinese literature", 1043 "level": "low" 1044 }, 1045 ... 1046 }, 1047 ... 1048 } 1050 Figure 18: EXPERTISE mapping example 1052 2.9.2. HOBBY 1054 A HOBBY property as defined in [RFC6715] is represented as a 1055 "PersonalInformation" object in the "personalInfo" map (Figure 19). 1056 The "type" member is set to "hobby". 1058 The INDEX parameter is represented as the index of the hobby among 1059 the declared hobbies. 1061 BEGIN:VCARD 1062 VERSION:4.0 1063 ... 1064 HOBBY;INDEX=1;LEVEL=high:reading 1065 HOBBY;INDEX=2;LEVEL=high:sewing 1066 ... 1067 END:VCARD 1069 { 1070 ... 1071 "personalInfo":{ 1072 ... 1073 "PERSINFO-1" : { 1074 "type": "hobby", 1075 "value": "reading", 1076 "level": "high" 1077 }, 1078 "PERSINFO-2" : { 1079 "type": "hobby", 1080 "value": "sewing", 1081 "level": "high" 1082 }, 1083 ... 1084 }, 1085 ... 1086 } 1088 Figure 19: HOBBY mapping example 1090 2.9.3. INTEREST 1092 An INTEREST property as defined in [RFC6715] is represented as a 1093 "PersonalInformation" object in the "personalInfo" map (Figure 20). 1094 The "type" member is set to "interest". 1096 The INDEX parameter is represented as the index of the interest among 1097 the declared interests. 1099 BEGIN:VCARD 1100 VERSION:4.0 1101 ... 1102 INTEREST;INDEX=1;LEVEL=medium:r&b music 1103 INTEREST;INDEX=2;LEVEL=high:rock ’n’ roll music 1104 ... 1105 END:VCARD 1107 { 1108 ... 1109 "personalInfo":{ 1110 ... 1111 "PERSINFO-1" : { 1112 "type": "interest", 1113 "value": "r&b music", 1114 "level": "medium" 1115 }, 1116 "PERSINFO-2" : { 1117 "type": "interest", 1118 "value": "rock ’n’ roll music", 1119 "level": "high" 1120 }, 1121 ... 1122 }, 1123 ... 1124 } 1126 Figure 20: INTEREST mapping example 1128 2.9.4. ORG-DIRECTORY 1130 An ORG-DIRECTORY property is represented as an entry of the "online" 1131 map (Figure 21). The entry value is a "Resource" object whose "type" 1132 member is set to "uri", the "label" member is set to "org-directory" 1133 and the "resource" member is the ORG-DIRECTORY value. 1135 The PREF and TYPE parameters are mapped according to the rules as 1136 defined in (Section 2.1). 1138 The INDEX parameter is represented as the index of the directory 1139 among the online resources with the "org-directory" label. 1141 BEGIN:VCARD 1142 VERSION:4.0 1143 ... 1144 ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com 1145 ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering 1146 ... 1147 END:VCARD 1149 { 1150 ... 1151 "online":{ 1152 ... 1153 "an-org-directory":{ 1154 "type": "uri", 1155 "label": "org-directory", 1156 "resource": "http://directory.mycompany.example.com" 1157 }, 1158 "another-org-directory":{ 1159 "type": "uri", 1160 "label": "org-directory", 1161 "resource": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering", 1162 "pref": 1 1163 }, 1164 ... 1165 }, 1166 ... 1167 } 1169 Figure 21: ORG-DIRECTORY mapping example 1171 2.10. Explanatory Properties 1173 2.10.1. CATEGORIES 1175 A CATEGORIES property is converted into a set of entries of the 1176 "categories" map (Figure 22). The keys are the comma-separated text 1177 values of the CATEGORIES property. 1179 In this case, the PREF parameter has not a JSContact counterpart; 1180 however, implementers MAY use a map preserving the order of insertion 1181 and the map entries can be inserted by order of preference. 1183 BEGIN:VCARD 1184 VERSION:4.0 1185 ... 1186 CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY 1187 ... 1188 END:VCARD 1190 { 1191 ... 1192 "categories":{ 1193 "INTERNET": true, 1194 "IETF": true, 1195 "INDUSTRY": true, 1196 "INFORMATION TECHNOLOGY": true 1197 }, 1198 ... 1199 } 1201 Figure 22: CATEGORIES mapping example 1203 2.10.2. NOTE 1205 A NOTE property is mapped to the "notes" property (Figure 23). All 1206 the NOTE instances are condensed into a single note and separated by 1207 newline. 1209 The ALTID and LANGUAGE parameters are mapped according to the rules 1210 as defined in (Section 2.1). 1212 BEGIN:VCARD 1213 VERSION:4.0 1214 ... 1215 NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri. 1216 ... 1217 END:VCARD 1219 { 1220 ... 1221 "notes": { 1222 "value": "This fax number is operational 0800 to 1715 EST, Mon-Fri." 1223 }, 1224 ... 1225 } 1227 Figure 23: NOTE mapping example 1229 2.10.3. PRODID 1231 The PRODID property is converted into the "prodId" member 1232 (Figure 24). 1234 BEGIN:VCARD 1235 VERSION:4.0 1236 ... 1237 PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN 1238 ... 1239 END:VCARD 1241 { 1242 ... 1243 "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN", 1244 ... 1245 } 1247 Figure 24: PRODID mapping example 1249 2.10.4. REV 1251 The REV property is transformed into the "updated" member 1252 (Figure 25). 1254 BEGIN:VCARD 1255 VERSION:4.0 1256 ... 1257 REV:19951031T222710Z 1258 ... 1259 END:VCARD 1261 { 1262 ... 1263 "updated": "1995-10-31T22:27:10Z", 1264 ... 1265 } 1267 Figure 25: REV mapping example 1269 2.10.5. SOUND 1271 A SOUND property is represented as an entry of the "online" map 1272 (Figure 26). The entry value is a "Resource" object whose "type" 1273 member is set to "uri", the "label" member is set to "sound" and the 1274 "resource" member is the SOUND value. 1276 The PREF and TYPE parameters are mapped according to the rules as 1277 defined in (Section 2.1). 1279 BEGIN:VCARD 1280 VERSION:4.0 1281 ... 1282 SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com 1283 ... 1284 END:VCARD 1286 { 1287 ... 1288 "online":{ 1289 ... 1290 "a-sound":{ 1291 "type": "uri", 1292 "label": "sound", 1293 "resource": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com" 1294 }, 1295 ... 1296 }, 1297 ... 1298 } 1300 Figure 26: SOUND mapping example 1302 2.10.6. UID 1304 The UID property corresponds to the "uid" property (Figure 27) in 1305 both Card and CardGroup. 1307 BEGIN:VCARD 1308 VERSION:4.0 1309 ... 1310 UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 1311 ... 1312 END:VCARD 1314 { 1315 ... 1316 "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6", 1317 ... 1318 } 1320 Figure 27: UID mapping example 1322 2.10.7. CLIENTPIDMAP and PID Parameter 1324 The CLIENTPIDMAP property and the PDI parameter don't have a direct 1325 match with a Card feature. 1327 2.10.8. URL 1329 An URL property is represented as an entry of the "online" map 1330 (Figure 28). The entry value is a "Resource" object whose "type" 1331 member is set to "uri", the "label" member is set to "url" and the 1332 "resource" member is the URL value. 1334 The PREF and TYPE parameters are mapped according to the rules as 1335 defined in (Section 2.1). 1337 BEGIN:VCARD 1338 VERSION:4.0 1339 ... 1340 URL:http://example.org/restaurant.french/~chezchic.html 1341 ... 1342 END:VCARD 1344 { 1345 ... 1346 "online":{ 1347 ... 1348 "an-url":{ 1349 "type": "uri", 1350 "label": "url", 1351 "resource": "http://example.org/restaurant.french/~chezchic.html" 1352 }, 1353 ... 1354 }, 1355 ... 1356 } 1358 Figure 28: URL mapping example 1360 2.10.9. VERSION 1362 The VERSION property doesn't have a direct match with a JSContact 1363 feature. 1365 2.11. Security Properties 1366 2.11.1. KEY 1368 A KEY property is represented as an entry of the "online" map 1369 (Figure 29). The entry value is a "Resource" object whose "type" 1370 member is set to "uri", the "label" member is set to "key" and the 1371 "resource" member is the KEY value. 1373 The PREF and TYPE parameters are mapped according to the rules as 1374 defined in (Section 2.1). 1376 BEGIN:VCARD 1377 VERSION:4.0 1378 ... 1379 KEY:http://www.example.com/keys/jdoe.cer 1380 ... 1381 END:VCARD 1383 { 1384 ... 1385 "online":{ 1386 ... 1387 "a-key":{ 1388 "type": "uri", 1389 "label": "key", 1390 "resource": "http://www.example.com/keys/jdoe.cer" 1391 }, 1392 ... 1393 }, 1394 ... 1395 } 1397 Figure 29: KEY mapping example 1399 2.12. Calendar Properties 1401 2.12.1. FBURL 1403 An FBURL property is represented as an entry of the "online" map 1404 (Figure 30). The entry value is a "Resource" object whose "type" 1405 member is set to "uri", the "label" member is set to "fburl" and the 1406 "resource" member is the FBURL value. 1408 The PREF and TYPE parameters are mapped according to the rules as 1409 defined in (Section 2.1). 1411 BEGIN:VCARD 1412 VERSION:4.0 1413 ... 1414 FBURL;PREF=1:http://www.example.com/busy/janedoe 1415 FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb 1416 ... 1417 END:VCARD 1419 { 1420 ... 1421 "online":{ 1422 ... 1423 "an-fburl":{ 1424 "type": "uri", 1425 "label": "fburl", 1426 "resource": "http://www.example.com/busy/janedoe", 1427 "pref": 1 1428 }, 1429 "another-fburl":{ 1430 "type": "uri", 1431 "label": "fburl", 1432 "resource": "ftp://example.com/busy/project-a.ifb", 1433 "mediaType": "text/calendar" 1434 }, 1435 ... 1436 }, 1437 ... 1438 } 1440 Figure 30: FBURL mapping example 1442 2.12.2. CALADRURI 1444 A CALADRURI property is represented as an entry of the "online" map 1445 (Figure 31). The entry value is a "Resource" object whose "type" 1446 member is set to "uri", the "label" member is set to "caladruri" and 1447 the "resource" member is the CALADRURI value. 1449 The PREF and TYPE parameters are mapped according to the rules as 1450 defined in (Section 2.1). 1452 BEGIN:VCARD 1453 VERSION:4.0 1454 ... 1455 CALADRURI;PREF=1:mailto:janedoe@example.com 1456 CALADRURI:http://example.com/calendar/jdoe 1457 ... 1458 END:VCARD 1460 { 1461 ... 1462 "online":{ 1463 ... 1464 "a-caladruri":{ 1465 "type": "uri", 1466 "label": "caladruri", 1467 "resource": "mailto:janedoe@example.com", 1468 "pref": 1 1469 }, 1470 "another-caladruri":{ 1471 "type": "uri", 1472 "label": "caladruri", 1473 "resource": "http://example.com/calendar/jdoe" 1474 }, 1475 ... 1476 }, 1477 ... 1478 } 1480 Figure 31: CALADRURI mapping example 1482 2.12.3. CALURI 1484 A CALURI property is represented as an entry of the "online" map 1485 (Figure 32). The entry value is a "Resource" object whose "type" 1486 member is set to "uri", the "label" member is set to "caluri" and the 1487 "resource" member is the CALURI value. 1489 The PREF and TYPE parameters are mapped according to the rules as 1490 defined in (Section 2.1). 1492 BEGIN:VCARD 1493 VERSION:4.0 1494 ... 1495 CALURI;PREF=1:http://cal.example.com/calA 1496 CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics 1497 ... 1498 END:VCARD 1500 { 1501 ... 1502 "online":{ 1503 ... 1504 "a-caluri":{ 1505 "type": "uri", 1506 "label": "caluri", 1507 "resource": "http://cal.example.com/calA", 1508 "pref": 1 1509 }, 1510 "another-caluri":{ 1511 "type": "uri", 1512 "label": "caluri", 1513 "resource": "ftp://ftp.example.com/calA.ics", 1514 "mediaType": "text/calendar" 1515 }, 1516 ... 1517 }, 1518 ... 1519 } 1521 Figure 32: CALURI mapping example 1523 2.13. vCard Unmatched Properties 1525 The unmatched vCard properties MAY be converted into JSContact 1526 properties whose name contains the prefix "ietf.org/RFC6350/" 1527 followed by property name in uppercase (i.e. ietf.org/RFC6350/ 1528 GENDER"). 1530 2.14. Card Required Properties 1532 While converting a vCard into a Card/CardGroup, only the topmost 1533 "uid" member is mandatory. Implementers are REQUIRED to set it when 1534 it is missing. 1536 3. Translating JSContact properties to vCard 1538 In most of the cases, the rules about the translation from Card/ 1539 CardGroup to vCard can be derived by reversing the rules presented in 1540 Section 2. The remaining cases are treated in the following of this 1541 section. 1543 3.1. Id 1545 Where a map key is of type Id, implementers are free to either ignore 1546 it or preserve it as a vCard information (e.g. a vCard parameter). 1548 3.2. Localizations 1550 Each PatchObject entry value of each "localizations" entry is 1551 converted into a instance of the vCard property matching the 1552 JSContact member referenced by the PatchObject entry key. The 1553 LANGUAGE parameter of such alternative MUST be set to the value of 1554 the given "localizations" entry. The LANGUAGE parameter of a vCard 1555 property presenting, at least, a language-dependent alternative MUST 1556 be set to the value of the JSContact "language" property if it is 1557 valued. Implementers MAY set the ALTID parameter to couple language- 1558 based alternatives of the same value. 1560 Note also that the components of some vCard values and their 1561 language-dependent alternatives are split into different JSContact 1562 values. For example, the "name" and "units" values for a given 1563 language must be grouped to make a single ORG value where components 1564 are separated by ";". 1566 3.3. Date and Time Representations 1568 The JSContact spec defines the "UTCDateTime" type to represent 1569 [RFC3339] "date-time" format with further restrictions. This means 1570 that the matched vCard format for a "UTCDateTime" value MUST be one 1571 of the formats shown in Section 4.3.5 of [RFC6350] (i.e. 1572 "19961022T140000Z"). 1574 In addition to such format, the "date" member of the "Anniversary" 1575 type allows specifying both a date without the time and a partial 1576 date. In this case, the corresponding vCard format is that defined 1577 in Section 4.3.1. 1579 3.4. Time Zone 1581 The time zone name as represented by the "timeZone" property is 1582 mapped to the TZ parameter. 1584 Implementers MAY map an "Etc/GMT" time zone either preserving the 1585 time zone name or converting it into a UTC offset. 1587 3.5. JSContact Types Matching Multiple vCard Properties 1589 3.5.1. Title 1591 The "titles" property contains information about the job, the 1592 position or the role of the entity the card represents. In vCard, 1593 such information is split into the TITLE and ROLE properties. This 1594 specification defines TITLE as the default target property when 1595 converting the "titles" property. 1597 3.5.2. Resource 1599 The "online" property includes resources that are usually represented 1600 through different vCard properties. The matched vCard property of a 1601 "Resource" object can be derived from the value of its "label" 1602 member. 1604 Any resource included in the "online" map that doesn't match a vCard 1605 property MAY be converted into vCard extended properties. 1607 3.6. CardGroup 1609 A CardGroup object is converted into a vCard by merging its 1610 properties with the properties of "CardGroup.card" object. If the 1611 "CardGroup.card.fullName" property exists, it MUST be used to set the 1612 FN value. 1614 3.7. Card Unmatched Properties 1616 Both the "preferredContactMethod" and "created" members don't match 1617 any vCard property. Implementers MAY represent them as vCard 1618 extended properties. 1620 3.8. vCard Required Properties 1622 While converting a Card/CardGroup into a vCard, only the FN property 1623 is required. Since both the "Card.fullName" and "CardGroup.name" 1624 properties are optional, implementers are REQUIRED to generate an FN 1625 value when it is missing. 1627 4. IANA Considerations 1629 This document has no actions for IANA. 1631 5. Implementation Status 1633 NOTE: Please remove this section and the reference to RFC 7942 prior 1634 to publication as an RFC. 1636 This section records the status of known implementations of the 1637 protocol as defined in this specification at the time of posting of 1638 this Internet-Draft, and is based on a proposal described in 1639 [RFC7942]. The description of implementations in this section is 1640 intended to assist the IETF in its decision processes in progressing 1641 drafts to RFCs. Please note that the listing of any individual 1642 implementation here does not imply endorsement by the IETF. 1643 Furthermore, no effort has been spent to verify the information 1644 presented here that was supplied by IETF contributors. This is not 1645 intended as, and must not be construed to be, a catalog of available 1646 implementations or their features. Readers are advised to note that 1647 other implementations may exist. 1649 According to RFC 7942, "this will allow reviewers and working groups 1650 to assign due considerationto documents that have the benefit of 1651 running code, which may serve as evidence of valuable experimentation 1652 and feedback that have made the implemented protocols more mature. 1653 It is up to the individual working groups to use this information as 1654 they see fit". 1656 5.1. CNR 1658 * Responsible Organization: National Research Council (CNR) of Italy 1659 * Location: https://github.com/consiglionazionaledellericerche/ 1660 jscontact-tools 1661 * Description: This implementation includes tools for JSContact 1662 creation, validation, serialization/deserialization, and 1663 conversion from vCard, xCard and jCard. 1664 * Level of Maturity: This is an "alpha" test implementation. 1665 * Coverage: This implementation includes all of the features 1666 described in this specification. 1667 * Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it 1669 6. Security Considerations 1671 This document doesn't present any security consideration. 1673 7. References 1675 7.1. Normative References 1677 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1678 Requirement Levels", BCP 14, RFC 2119, 1679 DOI 10.17487/RFC2119, March 1997, 1680 . 1682 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1683 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1684 . 1686 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 1687 DOI 10.17487/RFC6350, August 2011, 1688 . 1690 [RFC6473] Saint-Andre, P., "vCard KIND:application", RFC 6473, 1691 DOI 10.17487/RFC6473, December 2011, 1692 . 1694 [RFC6474] Li, K. and B. Leiba, "vCard Format Extensions: Place of 1695 Birth, Place and Date of Death", RFC 6474, 1696 DOI 10.17487/RFC6474, December 2011, 1697 . 1699 [RFC6715] Cauchie, D., Leiba, B., and K. Li, "vCard Format 1700 Extensions: Representing vCard Extensions Defined by the 1701 Open Mobile Alliance (OMA) Converged Address Book (CAB) 1702 Group", RFC 6715, DOI 10.17487/RFC6715, August 2012, 1703 . 1705 [RFC6869] Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard 1706 KIND:device", RFC 6869, DOI 10.17487/RFC6869, February 1707 2013, . 1709 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 1710 DOI 10.17487/RFC7095, January 2014, 1711 . 1713 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1714 Code: The Implementation Status Section", BCP 205, 1715 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1716 . 1718 [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: 1719 ICANN Extensions for the Registration Data Access Protocol 1720 (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, 1721 . 1723 7.2. Informative References 1725 [draft-ietf-jmap-jscontact] 1726 "JSContact: A JSON representation of contact data", 1727 . 1730 [time-zones] 1731 "Time Zone Database", . 1733 [uri-schemes] 1734 "Uniform Resource Identifier (URI) Schemes", 1735 . 1738 Authors' Addresses 1740 Mario Loffredo 1741 IIT-CNR/Registro.it 1742 Via Moruzzi,1 1743 56124 Pisa 1744 Italy 1746 Email: mario.loffredo@iit.cnr.it 1747 URI: http://www.iit.cnr.it 1749 Robert Stepanek 1750 FastMail 1751 PO Box 234, Collins St West 1752 Melbourne VIC 8007 1753 Australia 1755 Email: rsto@fastmailteam.com 1756 URI: https://www.fastmail.com