idnits 2.17.1 draft-ietf-calext-jscontact-vcard-01.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 19 instances of too long lines in the document, the longest one being 22 characters in excess of 72. ** The abstract seems to contain references ([I-D.ietf-calext-jscontact]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (11 April 2022) is 745 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 1788, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 8605 == Outdated reference: A later version (-17) exists of draft-ietf-calext-jscontact-00 Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 calext M. Loffredo 3 Internet-Draft IIT-CNR/Registro.it 4 Intended status: Standards Track R. Stepanek 5 Expires: 13 October 2022 FastMail 6 11 April 2022 8 JSContact: Converting from and to vCard 9 draft-ietf-calext-jscontact-vcard-01 11 Abstract 13 This document defines how to convert contact information as defined 14 in the JSContact [I-D.ietf-calext-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 13 October 2022. 34 Copyright Notice 36 Copyright (c) 2022 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 Revised BSD License text as 45 described in Section 4.e of the Trust Legal Provisions and are 46 provided without warranty as described in the Revised BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.2. Scope and Caveats . . . . . . . . . . . . . . . . . . . . 4 53 1.3. Conventions Used in This Document . . . . . . . . . . . . 4 54 1.4. Extensions . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . 9 67 2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, 68 ANNIVERSARY . . . . . . . . . . . . . . . . . . . . . 9 69 2.4.5. GENDER . . . . . . . . . . . . . . . . . . . . . . . 12 70 2.5. Delivery Addressing Properties . . . . . . . . . . . . . 13 71 2.5.1. ADR . . . . . . . . . . . . . . . . . . . . . . . . . 13 72 2.6. Communications Properties . . . . . . . . . . . . . . . . 15 73 2.6.1. TEL . . . . . . . . . . . . . . . . . . . . . . . . . 16 74 2.6.2. EMAIL . . . . . . . . . . . . . . . . . . . . . . . . 16 75 2.6.3. IMPP . . . . . . . . . . . . . . . . . . . . . . . . 17 76 2.6.4. LANG . . . . . . . . . . . . . . . . . . . . . . . . 18 77 2.7. Geographical Properties . . . . . . . . . . . . . . . . . 19 78 2.7.1. Time Zone Representation . . . . . . . . . . . . . . 20 79 2.8. Organizational Properties . . . . . . . . . . . . . . . . 20 80 2.8.1. TITLE and ROLE . . . . . . . . . . . . . . . . . . . 20 81 2.8.2. LOGO . . . . . . . . . . . . . . . . . . . . . . . . 21 82 2.8.3. ORG . . . . . . . . . . . . . . . . . . . . . . . . . 22 83 2.8.4. MEMBER . . . . . . . . . . . . . . . . . . . . . . . 23 84 2.8.5. RELATED . . . . . . . . . . . . . . . . . . . . . . . 25 85 2.8.6. CONTACT-URI . . . . . . . . . . . . . . . . . . . . . 26 86 2.9. Personal Information Properties . . . . . . . . . . . . . 26 87 2.9.1. EXPERTISE . . . . . . . . . . . . . . . . . . . . . . 27 88 2.9.2. HOBBY . . . . . . . . . . . . . . . . . . . . . . . . 27 89 2.9.3. INTEREST . . . . . . . . . . . . . . . . . . . . . . 28 90 2.9.4. ORG-DIRECTORY . . . . . . . . . . . . . . . . . . . . 29 91 2.10. Explanatory Properties . . . . . . . . . . . . . . . . . 30 92 2.10.1. CATEGORIES . . . . . . . . . . . . . . . . . . . . . 30 93 2.10.2. NOTE . . . . . . . . . . . . . . . . . . . . . . . . 31 94 2.10.3. PRODID . . . . . . . . . . . . . . . . . . . . . . . 32 95 2.10.4. REV . . . . . . . . . . . . . . . . . . . . . . . . 32 96 2.10.5. SOUND . . . . . . . . . . . . . . . . . . . . . . . 32 97 2.10.6. UID . . . . . . . . . . . . . . . . . . . . . . . . 33 98 2.10.7. CLIENTPIDMAP and PID Parameter . . . . . . . . . . . 34 99 2.10.8. URL . . . . . . . . . . . . . . . . . . . . . . . . 34 100 2.10.9. VERSION . . . . . . . . . . . . . . . . . . . . . . 34 101 2.11. Security Properties . . . . . . . . . . . . . . . . . . . 34 102 2.11.1. KEY . . . . . . . . . . . . . . . . . . . . . . . . 35 103 2.12. Calendar Properties . . . . . . . . . . . . . . . . . . . 35 104 2.12.1. FBURL . . . . . . . . . . . . . . . . . . . . . . . 35 105 2.12.2. CALADRURI . . . . . . . . . . . . . . . . . . . . . 36 106 2.12.3. CALURI . . . . . . . . . . . . . . . . . . . . . . . 37 107 2.13. vCard Unmatched Properties . . . . . . . . . . . . . . . 38 108 2.14. Card Required Properties . . . . . . . . . . . . . . . . 38 109 3. Translating JSContact properties to vCard . . . . . . . . . . 39 110 3.1. Id . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 111 3.2. Localizations . . . . . . . . . . . . . . . . . . . . . . 39 112 3.3. Date and Time Representations . . . . . . . . . . . . . . 39 113 3.4. Time Zone . . . . . . . . . . . . . . . . . . . . . . . . 39 114 3.5. JSContact Types Matching Multiple vCard Properties . . . 40 115 3.5.1. Title . . . . . . . . . . . . . . . . . . . . . . . . 40 116 3.5.2. Resource . . . . . . . . . . . . . . . . . . . . . . 40 117 3.6. CardGroup . . . . . . . . . . . . . . . . . . . . . . . . 40 118 3.7. Card Unmatched Properties . . . . . . . . . . . . . . . . 40 119 3.8. vCard Required Properties . . . . . . . . . . . . . . . . 40 120 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 121 5. Implementation Status . . . . . . . . . . . . . . . . . . . . 41 122 5.1. CNR . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 123 6. Security Considerations . . . . . . . . . . . . . . . . . . . 41 124 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 41 125 7.1. Normative References . . . . . . . . . . . . . . . . . . 41 126 7.2. Informative References . . . . . . . . . . . . . . . . . 42 127 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 43 129 1. Introduction 131 1.1. Motivation 133 The JSContact specification [I-D.ietf-calext-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 [I-D.ietf-calext-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.3. Conventions Used in This Document 166 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 167 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 168 document are to be interpreted as described in [RFC2119]. 170 In the following of this document, the vCard features, namely 171 properties and parameters, are written in uppercase while the Card/ 172 CardGroup features are written in camel case wrapped in double 173 quotes. 175 1.4. Extensions 177 While translating vCard to JSContact, any vCard property that doesn't 178 have a direct counterpart in JSContact MUST be converted into a 179 property whose name is prefixed by "ietf.org::" (e.g. "ietf.org:rfc6350:"). 182 Any custom extension MAY be added and its name MUST be prefixed with 183 a specific domain name to avoid conflict, e.g. 184 "example.com:customprop". 186 Likewise, while translating JSContact to vCard, a JSContact property 187 that doesn't have a direct counterpart in vCard MUST be converted 188 into a property whose name is prefixed with "X-" as specified in 189 Section 6.10 of [RFC6350]. 191 2. Translating vCard properties to JSContact 193 This section contains the translation rules from vCard to Card/ 194 CardGroup. The vCard properties are grouped according to the 195 categories as defined in [RFC6350]. 197 If a vCard represents a group of contacts, those vCard properties 198 which don't have a counterpart in CardGroup are converted into 199 related properties of the "CardGroup.card" object. In this case, the 200 "uid" member of both the resulting CardGroup object and its "card" 201 member MUST have the same value. 203 2.1. Common Parameters 205 The following mapping rules apply to parameters that are common to 206 most of the vCard properties: 208 * The generic values of the TYPE parameter are mapped to the values 209 of the "Context" type as defined in Section 1.5.1 of 210 [I-D.ietf-calext-jscontact]. The "home" value corresponds to the 211 "private" key. The mapping of those specific TYPE values used in 212 the TEL and RELATED properties are defined in Section 2.6.1 and 213 Section 2.8.5. 214 * The PREF parameter is mapped to the "pref" property. 215 * The MEDIATYPE parameter is mapped to the "mediaType" property. As 216 described in Section 5.7 of [RFC6350], the media type of a 217 resource can be identified by its URI. For example, "image/gif" 218 can be derived from the ".gif" extension of a GIF image URI. 219 JSContact producers MAY provide the media type information even 220 when it is not specified in the vCard. 221 * The ALTID and LANGUAGE parameters are used in combination for 222 associating the language-dependent alternatives with a given 223 property. Such alternatives are represented by using the 224 "localizations" map: the "localizations" key is the LANGUAGE 225 value, the key of the related PatchObject map is the JSON pointer 226 of the JSContact member matching the vCard property while the 227 value is the JSContact member itself. 229 2.2. Unmapped JSContact Information 231 The rules to generate a map key of type Id as well as a value for 232 "created", "language" and "preferredContactMethod" properties are out 233 of the scope of this document. 235 2.3. General Properties 236 2.3.1. BEGIN and END 238 The BEGIN and END properties don't have a direct match with a 239 JSContact feature. 241 2.3.2. SOURCE 243 A SOURCE property is represented as an entry of the "online" map 244 (Figure 1). The entry value is a "Resource" object whose "type" 245 member is set to "directorySource" and the "resource" member is the 246 SOURCE value. 248 The PREF and MEDIATYPE parameters are mapped according to the rules 249 as defined in Section 2.1. 251 BEGIN:VCARD 252 VERSION:4.0 253 ... 254 SOURCE:http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf 255 ... 256 END:VCARD 258 { 259 "@type": "Card", 260 ... 261 "online":{ 262 ... 263 "a-source":{ 264 "@type": "Resource", 265 "type": "directorySource", 266 "resource": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf" 267 }, 268 ... 269 }, 270 ... 271 } 273 Figure 1: SOURCE mapping example 275 2.3.3. KIND 277 The KIND property is mapped to the "kind" member (Figure 2). Allowed 278 values are those described in Section 6.1.4 of [RFC6350] and extended 279 with the values declared in [RFC6473] and [RFC6869]. The value 280 "group" is reserved for a CardGroup instance. 282 BEGIN:VCARD 283 VERSION:4.0 284 ... 285 KIND:individual 286 ... 287 END:VCARD 289 { 290 "@type": "Card", 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 represented through the "fullName" member 308 (Figure 3). The presence of multiple instances is implicitly 309 associated with the full name translations in various languages 310 regardless of the presence of the ALTID parameter. Each translation 311 is mapped according to the rules as defined in Section 2.1. 313 If the vCard represents a group of contacts, implementers MAY convert 314 the FN property into either "CardGroup.card.fullName" or 315 "CardGroup.name" or both properties. 317 2.4.2. N and NICKNAME 319 The N instances are converted into equivalent items of the 320 "components" array of the "name" property (Figure 3): the N 321 components are transformed into related "NameComponent" objects as 322 presented in Table 1. Name components SHOULD be ordered such that 323 their values joined by whitespace produce a valid full name of this 324 entity. 326 Each NICKNAME instance is mapped to an item of "nickNames" array. 328 +====================+==============+ 329 | N component | "type" value | 330 +====================+==============+ 331 | Honorific Prefixes | prefix | 332 +--------------------+--------------+ 333 | Given Names | personal | 334 +--------------------+--------------+ 335 | Family Names | surname | 336 +--------------------+--------------+ 337 | Additional Names | additional | 338 +--------------------+--------------+ 339 | Honorific Suffixes | suffix | 340 +--------------------+--------------+ 342 Table 1: N components mapping 344 BEGIN:VCARD 345 VERSION:4.0 346 ... 347 FN:Mr. John Q. Public\, Esq. 348 N:Public;John;Quinlan;Mr.;Esq. 349 NICKNAME:Johnny 350 ... 351 END:VCARD 353 { 354 "@type": "Card", 355 ... 356 "fullName": "Mr. John Q. Public, Esq.", 357 "name":{ 358 "@type": "Name", 359 "components":[ 360 { "@type": "NameComponent", "type": "prefix", "value":"Mr." }, 361 { "@type": "NameComponent", "type": "personal", "value":"John" }, 362 { "@type": "NameComponent", "type": "surname", "value":"Public" }, 363 { "@type": "NameComponent", "type": "additional", "value":"Quinlan" }, 364 { "@type": "NameComponent", "type": "suffix", "value":"Esq." } 365 ] 366 }, 367 "nickNames":[ 368 "Johnny" 369 ], 370 ... 371 } 373 Figure 3: FN, N, NICKNAME mapping example 375 2.4.3. PHOTO 377 A PHOTO property is represented as an entry of the "photos" map 378 (Figure 4). The entry value is a "File" object whose "href" member 379 is the PHOTO value. 381 The PREF and MEDIATYPE parameters are mapped according to the rules 382 as defined in Section 2.1. 384 BEGIN:VCARD 385 VERSION:4.0 386 ... 387 PHOTO:http://www.example.com/pub/photos/jqpublic.gif 388 ... 389 END:VCARD 391 { 392 "@type": "Card", 393 ... 394 "photos":{ 395 ... 396 "a-photo":{ 397 "@type": "File", 398 "href": "http://www.example.com/pub/photos/jqpublic.gif" 399 }, 400 ... 401 }, 402 ... 403 } 405 Figure 4: PHOTO mapping example 407 2.4.4. BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 409 The BDAY and ANNIVERSARY properties and the extensions BIRTHPLACE, 410 DEATHDATE, DEATHPLACE described in [RFC6350] are represented as 411 "Anniversary" objects included in the "anniversaries" map (Figure 5): 413 * BDAY and BIRTHPLACE are mapped to "date" and "place" where "type" 414 is set to "birth"; 415 * DEATHDATE and DEATHPLACE are mapped to "date" and "place" where 416 "type" is set to "death"; 417 * ANNIVERSARY is mapped to "date" where "type" is empty and "label" 418 is set to a value describing in detail the kind of anniversary 419 (e.g. "marriage date" for the wedding anniversary). 421 Both birth and death places are represented as instances of the 422 "Address" object. 424 The BIRTHPLACE and DEATHPLACE properties that are represented as geo 425 URIs are converted into "Address" instances including only the 426 "coordinates" member. If the URI value is not a geo URI, the place 427 is ignored. 429 The ALTID and LANGUAGE parameters of both BIRTHPLACE and DEATHPLACE 430 properties are mapped according to the rules as defined in 431 Section 2.1. 433 BEGIN:VCARD 434 VERSION:4.0 435 ... 436 BDAY:19531015T231000Z 437 BIRTHPLACE:Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A. 438 DEATHDATE:19960415 439 DEATHPLACE:4445 Courtright Street\nNew England, ND 58647\nU.S.A. 440 ANNIVERSARY:19860201 441 ... 442 END:VCARD 444 { 445 "@type": "Card", 446 ... 447 "anniversaries": { 448 "ANNIVERSARY-1" : { 449 "@type": "Anniversary", 450 "type": "birth", 451 "date": "1953-10-15T23:10:00Z", 452 "place":{ 453 "@type": "Address", 454 "fullAddress": "Mail Drop: TNE QB\n123 Main Street\nAny Town, CA 91921-1234\nU.S.A." 455 } 456 }, 457 "ANNIVERSARY-2" : { 458 "@type": "Anniversary", 459 "type": "death", 460 "date": "1996-04-15", 461 "place":{ 462 "@type": "Address", 463 "fullAddress": "4445 Courtright Street\nNew England, ND 58647\nU.S.A." 464 } 465 }, 466 "ANNIVERSARY-3" : { 467 "@type": "Anniversary", 468 "label": "marriage date", 469 "date": "1986-02-01" 470 } 471 }, 472 ... 473 } 475 Figure 5: BDAY, BIRTHPLACE, DEATHDATE, DEATHPLACE, ANNIVERSARY 476 mapping example 478 2.4.5. GENDER 480 The GENDER property is a single structured value with two optional 481 components: the biological sex and the gender information. The 482 former is represented as an enumerated value, while the latter as a 483 free-form text. As opposed to such a representation, the JSContact 484 specification includes the "SpeakToAs" object just to represent how 485 to address, speak to or refer to the contact. In particular, some 486 pre-defined values are allowed for the "grammaticalGender" member. 488 For the reasons stated above, the GENDER property doesn't have a 489 direct match with the "SpeakToAs" object. However, on the assumption 490 that the GENDER property doesn't store the actual biological sex of 491 the contact, implementations MAY use the conversion rules shown in 492 Table 2 and Table 3. 494 +==============+=====================================+ 495 | GENDER value | "SpeakToAs.grammaticalGender" value | 496 +==============+=====================================+ 497 | M | male | 498 +--------------+-------------------------------------+ 499 | F | female | 500 +--------------+-------------------------------------+ 501 | N | neuter | 502 +--------------+-------------------------------------+ 503 | O | animate | 504 +--------------+-------------------------------------+ 505 | U | SpeakToAs = null | 506 +--------------+-------------------------------------+ 508 Table 2: GENDER to SpeakToAs conversion 510 +=====================================+==============+ 511 | "SpeakToAs.grammaticalGender" value | GENDER value | 512 +=====================================+==============+ 513 | male | M | 514 +-------------------------------------+--------------+ 515 | female | F | 516 +-------------------------------------+--------------+ 517 | neuter | N | 518 +-------------------------------------+--------------+ 519 | animate | O | 520 +-------------------------------------+--------------+ 521 | inanimate | N;inanimate | 522 +-------------------------------------+--------------+ 524 Table 3: SpeakToAs to GENDER conversion 526 2.5. Delivery Addressing Properties 528 2.5.1. ADR 530 An ADR property is represented as an entry of the "addresses" map 531 (Figure 6). The entry value is an "Address" object. 533 The ADR components are transformed into the "Address" members as 534 presented in Table 4 and Table 5. 536 The "street address" and "extended address" ADR components MAY be 537 converted into either a single StreetComponent item or a combination 538 of StreetComponent items. 540 +===============+================+ 541 | ADR component | Address member | 542 +===============+================+ 543 | locality | locality | 544 +---------------+----------------+ 545 | region | region | 546 +---------------+----------------+ 547 | postal code | postcode | 548 +---------------+----------------+ 549 | country name | country | 550 +---------------+----------------+ 552 Table 4: ADR components vs. 553 Address members mapping 555 +===============+======================+========================+ 556 | ADR component | Single | Combination of | 557 | | StreetComponent item | StreetComponent items | 558 +===============+======================+========================+ 559 | post office | postOfficeBox | | 560 | box | | | 561 +---------------+----------------------+------------------------+ 562 | extended | extension | extension, building, | 563 | address | | floor, room, apartment | 564 +---------------+----------------------+------------------------+ 565 | street | name | name, number, | 566 | address | | direction | 567 +---------------+----------------------+------------------------+ 569 Table 5: ADR components vs. StreetComponent items mapping 571 The LABEL parameter is converted into the "fullAddress" member. 573 The GEO parameter is converted into the "coordinates" member. 575 The TZ parameter is converted into the "timeZone" member. 577 The CC parameter as defined in [RFC8605] is converted into the 578 "countryCode" member. 580 The PREF and TYPE parameters are mapped according to the rules as 581 defined in Section 2.1. 583 The ALTID and LANGUAGE parameters are mapped according to the rules 584 as defined in Section 2.1. Each possible language-dependent 585 alternative is represented as an entry of the PatchObject map where 586 the key references the "fullAddress" member. 588 BEGIN:VCARD 589 VERSION:4.0 590 ... 591 ADR;TYPE=work;CC=US:;;54321 Oak St;Reston;VA;20190;USA 592 ADR;TYPE=home;CC=US:;;12345 Elm St;Reston;VA;20190;USA 593 ... 594 END:VCARD 596 { 597 "@type": "Card", 598 ... 599 "addresses":{ 600 "work-address" :{ 601 "@type": "Address", 602 "contexts":{ "work": true }, 603 "fullAddress": "54321 Oak St\nReston\nVA\n20190\nUSA", 604 "street": [ 605 { "@type": "StreetComponent", "type": "name", "value": "Oak St" }, 606 { "@type": "StreetComponent", "type": "number", "value": "54321" } 607 ], 608 "locality": "Reston", 609 "region": "VA", 610 "country": "USA", 611 "postcode": "20190", 612 "countryCode": "US" 613 }, 614 "private-address":{ 615 "@type": "Address", 616 "contexts":{ "private": true }, 617 "fullAddress": "12345 Elm St\nReston\nVA\n20190\nUSA", 618 "street": [ 619 { "@type": "StreetComponent", "type": "name", "value": "Elm St" }, 620 { "@type": "StreetComponent", "type": "number", "value": "12345" } 621 ], 622 "locality": "Reston", 623 "region": "VA", 624 "country": "USA", 625 "postcode": "20190", 626 "countryCode": "US" 627 } 628 }, 629 ... 630 } 632 Figure 6: ADR mapping example 634 2.6. Communications Properties 635 2.6.1. TEL 637 A TEL property is represented as an entry of the "phones" map 638 (Figure 7). The entry value is a "Phone" object. The TEL-specific 639 values of the TYPE parameter are mapped to the "features" map keys. 640 The values that don't match a key are represented as comma-separated 641 values of the "label" member. The "phone" member is set to the TEL 642 value. 644 The PREF and TYPE parameters are mapped according to the rules as 645 defined in Section 2.1. 647 BEGIN:VCARD 648 VERSION:4.0 649 ... 650 TEL;VALUE=uri;PREF=1;TYPE="voice,home":tel:+1-555-555-5555;ext=5555 651 TEL;VALUE=uri;TYPE=home:tel:+33-01-23-45-67 652 ... 653 END:VCARD 655 { 656 "@type": "Card", 657 ... 658 "phones":{ 659 "a-phone":{ 660 "@type": "Phone", 661 "contexts":{ "private": true }, 662 "features":{ "voice": true }, 663 "phone": "tel:+1-555-555-5555;ext=5555", 664 "pref": 1 665 }, 666 "another-phone":{ 667 "@type": "Phone", 668 "contexts":{ "private": true }, 669 "phone": "tel:+33-01-23-45-67" 670 } 671 ], 672 ... 673 } 675 Figure 7: TEL mapping example 677 2.6.2. EMAIL 679 An EMAIL property is represented as an entry of the "emails" map 680 (Figure 8). The entry value is an "EmailAddress" object. The 681 "email" member is set to the EMAIL value. 683 The PREF and TYPE parameters are mapped according to the rules as 684 defined in Section 2.1. 686 BEGIN:VCARD 687 VERSION:4.0 688 ... 689 EMAIL;TYPE=work:jqpublic@xyz.example.com 690 EMAIL;PREF=1:jane_doe@example.com 691 ... 692 END:VCARD 694 { 695 "@type": "Card", 696 ... 697 "emails":{ 698 "work-email":{ 699 "@type": "EmailAddress", 700 "contexts":{ "work": true }, 701 "email": "jqpublic@xyz.example.com" 702 }, 703 "private-email":{ 704 "@type": "EmailAddress", 705 "email": "jane_doe@example.com", 706 "pref": 1 707 } 708 }, 709 ... 710 } 712 Figure 8: EMAIL mapping example 714 2.6.3. IMPP 716 An IMPP property is represented as an entry of the "online" map 717 (Figure 9). The entry value is a "Resource" object whose "type" 718 member is set to "username", the "label" member is set to "XMPP" and 719 the "resource" member is the IMPP value. 721 The PREF and TYPE parameters are mapped according to the rules as 722 defined in Section 2.1. 724 BEGIN:VCARD 725 VERSION:4.0 726 ... 727 IMPP;PREF=1:xmpp:alice@example.com 728 ... 729 END:VCARD 731 { 732 "@type": "Card", 733 ... 734 "online":{ 735 ... 736 { 737 "@type": "Resource", 738 "type": "username", 739 "label": "XMPP", 740 "value": "alice@example.com", 741 "pref": 1 742 }, 743 ... 744 }, 745 ... 746 } 748 Figure 9: IMPP mapping example 750 2.6.4. LANG 752 A LANG property is represented as an entry of the 753 "preferredContactLanguages" map (Figure 10). The entry keys 754 correspond to the language tags, the corresponding entry values are 755 arrays of "ContactLanguage" objects. 757 The PREF and TYPE parameters are mapped according to the rules as 758 defined in Section 2.1. 760 If both PREF and TYPE parameters are missing, the array of 761 "ContactLanguage" objects MUST be empty. 763 BEGIN:VCARD 764 VERSION:4.0 765 ... 766 LANG;TYPE=work;PREF=1:en 767 LANG;TYPE=work;PREF=2:fr 768 LANG;TYPE=home:fr 769 ... 770 END:VCARD 772 { 773 "@type": "Card", 774 ... 775 "preferredContactLanguages":{ 776 "en":[ 777 { 778 "@type": "ContactLanguage", 779 "context": "work", 780 "pref": 1 781 } 782 ], 783 "fr":[ 784 { 785 "@type": "ContactLanguage", 786 "context": "work", 787 "pref": 2 788 }, 789 { 790 "@type": "ContactLanguage", 791 "context": "private" 792 } 793 ] 794 }, 795 ... 796 } 798 Figure 10: LANG mapping example 800 2.7. Geographical Properties 802 The GEO and TZ properties are not directly mapped to topmost Card 803 members because the same information is represented through 804 equivalent "Address" members. 806 The ALTID parameter is used for associating both GEO and TZ 807 properties with the related address information. When the ALTID 808 parameter is missing, the matched members SHOULD be included in the 809 first "Address" object. 811 2.7.1. Time Zone Representation 813 As specified in Section 6.5.1 of [RFC6350], the time zone information 814 can be represented as a time zone name, as a UTC offset or as a URI. 816 * If the TZ value is defined in the IANA timezone database, it is 817 directly matched by the "timeZone" member in JSContact. 818 * An UTC offset MUST be converted into the related "Etc/GMT" time 819 zone (e.g. the value "-0500" converts to "Etc/GMT+5"). If the UTC 820 offset value contains minutes information or is not an IANA 821 timezone name, it requires special handling. 822 * Since there is no URI scheme defined for time zones [uri-schemes], 823 any implementation that does use some a custom URI for a time zone 824 is not interoperable anyway. In this case, if the URI corresponds 825 to an IANA time zone [time-zones], this latter SHOULD be used. 826 Otherwise, the URI value is dumped into a string. 828 2.8. Organizational Properties 830 2.8.1. TITLE and ROLE 832 Both TITLE and ROLE properties are represented as entries of the 833 "titles" map (Figure 11). The entry value is a "Title" object whose 834 "title" member includes information about the title or role. The 835 rules to set the "organization" member are out of the scope of this 836 document. 838 The ALTID and LANGUAGE parameters are mapped according to the rules 839 as defined in Section 2.1. 841 BEGIN:VCARD 842 VERSION:4.0 843 ... 844 TITLE:Research Scientist 845 ROLE:Project Leader 846 ... 847 END:VCARD 849 { 850 "@type": "Card", 851 ... 852 "titles":{ 853 "a-title":{ 854 "@type": "Title", 855 "title": "Project Leader" 856 }, 857 "another-title":{ 858 "@type": "Title", 859 "title": "Research Scientist" 860 } 861 }, 862 ... 863 } 865 Figure 11: TITLE and ROLE mapping example 867 2.8.2. LOGO 869 A LOGO property is represented as an entry of the "online" map 870 (Figure 12). The entry value is a "Resource" object whose "type" 871 member is set to "logo" and the "resource" member is the LOGO value. 873 The PREF and TYPE parameters are mapped according to the rules as 874 defined in Section 2.1. 876 BEGIN:VCARD 877 VERSION:4.0 878 ... 879 LOGO:http://www.example.com/pub/logos/abccorp.jpg 880 ... 881 END:VCARD 883 { 884 "@type": "Card", 885 ... 886 "online":{ 887 ... 888 "a-logo":{ 889 "@type": "Resource", 890 "type": "logo", 891 "resource": "http://www.example.com/pub/logos/abccorp.jpg" 892 }, 893 ... 894 }, 895 ... 896 } 898 Figure 12: LOGO mapping example 900 2.8.3. ORG 902 An ORG property is represented as an entry of the "organizations" map 903 (Figure 13). The entry value is an "Organization" object whose 904 "name" member contains the organizational name and the "units" member 905 contains the organizational units. 907 The ALTID and LANGUAGE parameters are mapped according to the rules 908 as defined in Section 2.1. 910 BEGIN:VCARD 911 VERSION:4.0 912 ... 913 ORG:ABC\, Inc.;North American Division;Marketing 914 ... 915 END:VCARD 917 { 918 "@type": "Card", 919 ... 920 "organizations":{ 921 "an-organization":{ 922 "@type": "Organization", 923 "name": "ABC, Inc.", 924 "units":[ 925 "North American Division", 926 "Marketing" 927 ] 928 } 929 }, 930 ... 931 } 933 Figure 13: ORG mapping example 935 2.8.4. MEMBER 937 According to the JSContact specification, a group of contact cards is 938 represented through a CardGroup (Figure 14). The uids of the contact 939 cards composing the group are included in the "members" map. 941 In this case, the PREF parameter has not a JSContact counterpart; 942 however, the implementers MAY insert the map entries by order of 943 preference. 945 BEGIN:VCARD 946 VERSION:4.0 947 KIND:group 948 FN:The Doe family 949 MEMBER:urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af 950 MEMBER:urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519 951 END:VCARD 953 { 954 "@type": "CardGroup", 955 "kind": "group", 956 "fullName": "The Doe family", 957 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 958 "members":{ 959 "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, 960 "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true 961 } 962 } 964 Figure 14: Group example 966 Only if the GROUP contains properties that don't have a mapping to 967 CardGroup properties, then the CardGroup.card property MAY contain 968 the optional Card object of this group. 970 { 971 "@type": "CardGroup", 972 "name": "The Doe family", 973 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 974 "members":{ 975 "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, 976 "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true 977 }, 978 "card": { 979 "@type": "Card", 980 "fullName": "The Doe family", 981 "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", 982 "photos":{ 983 "a-photo":{ 984 "@type": "File", 985 "href": "http://www.example.com/pub/photos/jqpublic.gif" 986 } 987 } 988 } 989 } 991 Figure 15: card member of CardGroup object 993 2.8.5. RELATED 995 All the RELATED instances are converted into the "relatedTo" map 996 (Figure 16): an entry for each entity the entity described by the 997 Card is associated with. The map keys are the "uid" values of the 998 associated cards. 1000 Each map value is a "Relation" object including only the "relation" 1001 member represented as a set of the RELATED-specific values of the 1002 TYPE parameter as defined in Section 6.6.6 of [RFC6350]. 1004 If the relation type is unspecified, the "relation" member MUST be 1005 empty. 1007 BEGIN:VCARD 1008 VERSION:4.0 1009 ... 1010 RELATED;TYPE=friend:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 1011 RELATED;TYPE=contact:http://example.com/directory/jdoe.vcf 1012 RELATED;VALUE=text:Please contact my assistant Jane Doe for any inquiries. 1013 ... 1014 END:VCARD 1016 { 1017 "@type": "Card", 1018 ... 1019 "relatedTo":{ 1020 { 1021 "@type": "Relation", 1022 "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6":{ 1023 "relation":{ "friend": true } 1024 } 1025 }, 1026 { 1027 "@type": "Relation", 1028 "http://example.com/directory/jdoe.vcf":{ 1029 "relation":{ "contact": true } 1030 } 1031 }, 1032 { 1033 "@type": "Relation", 1034 "Please contact my assistant Jane Doe for any inquiries.":{ 1035 "relation":{ } 1036 } 1037 } 1038 }, 1039 ... 1040 } 1041 Figure 16: RELATED mapping example 1043 2.8.6. CONTACT-URI 1045 A CONTACT-URI property as defined in [RFC8605] is represented as an 1046 entry of the "online" map (Figure 17). The entry value is a 1047 "Resource" object whose "type" member is set to "contact" and the 1048 "resource" member is the CONTACT-URI value. 1050 The PREF and TYPE parameters are mapped according to the rules as 1051 defined in Section 2.1. 1053 BEGIN:VCARD 1054 VERSION:4.0 1055 ... 1056 CONTACT-URI;PREF=1:mailto:contact@example.com 1057 ... 1058 END:VCARD 1060 { 1061 "@type": "Card", 1062 ... 1063 "online":{ 1064 ... 1065 "a-contact-uri":{ 1066 "@type": "Resource", 1067 "type": "contact", 1068 "resource": "mailto:contact@example.com", 1069 "pref": 1 1070 }, 1071 ... 1072 }, 1073 ... 1074 } 1076 Figure 17: CONTACT-URI mapping example 1078 2.9. Personal Information Properties 1080 The LEVEL parameter as defined in [RFC6715] is directly mapped to the 1081 "level" property of the "PersonalInformation" type apart from when 1082 LEVEL is used in the EXPERTISE property; in this case, the values are 1083 converted as in the following: 1085 * "beginner" is converted into "low"; 1086 * "average" is converted into "medium"; 1087 * "expert" is converted into "high". 1089 2.9.1. EXPERTISE 1091 An EXPERTISE property as defined in [RFC6715] is represented as a 1092 "PersonalInformation" object in the "personalInfo" map (Figure 18). 1093 The "type" member is set to "expertise". 1095 The INDEX parameter is represented as the index of the expertise 1096 among the declared expertises. 1098 BEGIN:VCARD 1099 VERSION:4.0 1100 ... 1101 EXPERTISE;LEVEL=beginner;INDEX=2:chinese literature 1102 EXPERTISE;INDEX=1;LEVEL=expert:chemistry 1103 ... 1104 END:VCARD 1106 { 1107 "@type": "Card", 1108 ... 1109 "personalInfo":{ 1110 ... 1111 "PERSINFO-1" : { 1112 "@type": "PersonalInformation", 1113 "type": "expertise", 1114 "value": "chemistry", 1115 "level": "high" 1116 }, 1117 "PERSINFO-2" : { 1118 "@type": "PersonalInformation", 1119 "type": "expertise", 1120 "value": "chinese literature", 1121 "level": "low" 1122 }, 1123 ... 1124 }, 1125 ... 1126 } 1128 Figure 18: EXPERTISE mapping example 1130 2.9.2. HOBBY 1132 A HOBBY property as defined in [RFC6715] is represented as a 1133 "PersonalInformation" object in the "personalInfo" map (Figure 19). 1134 The "type" member is set to "hobby". 1136 The INDEX parameter is represented as the index of the hobby among 1137 the declared hobbies. 1139 BEGIN:VCARD 1140 VERSION:4.0 1141 ... 1142 HOBBY;INDEX=1;LEVEL=high:reading 1143 HOBBY;INDEX=2;LEVEL=high:sewing 1144 ... 1145 END:VCARD 1147 { 1148 "@type": "Card", 1149 ... 1150 "personalInfo":{ 1151 ... 1152 "PERSINFO-1" : { 1153 "@type": "PersonalInformation", 1154 "type": "hobby", 1155 "value": "reading", 1156 "level": "high" 1157 }, 1158 "PERSINFO-2" : { 1159 "@type": "PersonalInformation", 1160 "type": "hobby", 1161 "value": "sewing", 1162 "level": "high" 1163 }, 1164 ... 1165 }, 1166 ... 1167 } 1169 Figure 19: HOBBY mapping example 1171 2.9.3. INTEREST 1173 An INTEREST property as defined in [RFC6715] is represented as a 1174 "PersonalInformation" object in the "personalInfo" map (Figure 20). 1175 The "type" member is set to "interest". 1177 The INDEX parameter is represented as the index of the interest among 1178 the declared interests. 1180 BEGIN:VCARD 1181 VERSION:4.0 1182 ... 1183 INTEREST;INDEX=1;LEVEL=medium:r&b music 1184 INTEREST;INDEX=2;LEVEL=high:rock ’n’ roll music 1185 ... 1186 END:VCARD 1188 { 1189 "@type": "Card", 1190 ... 1191 "personalInfo":{ 1192 ... 1193 "PERSINFO-1" : { 1194 "@type": "PersonalInformation", 1195 "type": "interest", 1196 "value": "r&b music", 1197 "level": "medium" 1198 }, 1199 "PERSINFO-2" : { 1200 "@type": "PersonalInformation", 1201 "type": "interest", 1202 "value": "rock ’n’ roll music", 1203 "level": "high" 1204 }, 1205 ... 1206 }, 1207 ... 1208 } 1210 Figure 20: INTEREST mapping example 1212 2.9.4. ORG-DIRECTORY 1214 An ORG-DIRECTORY property as defined in [RFC6715] is represented as 1215 an entry of the "online" map (Figure 21). The entry value is a 1216 "Resource" object whose "type" member is set to "directory" and the 1217 "resource" member is the ORG-DIRECTORY value. 1219 The PREF and TYPE parameters are mapped according to the rules as 1220 defined in Section 2.1. 1222 The INDEX parameter is represented as the index of the directory 1223 among the online resources with the "directory" type. 1225 BEGIN:VCARD 1226 VERSION:4.0 1227 ... 1228 ORG-DIRECTORY;INDEX=1:http://directory.mycompany.example.com 1229 ORG-DIRECTORY;PREF=1:ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering 1230 ... 1231 END:VCARD 1233 { 1234 ... 1235 "online":{ 1236 "@type": "Card", 1237 ... 1238 "an-org-directory":{ 1239 "@type": "Resource", 1240 "type": "directory", 1241 "resource": "http://directory.mycompany.example.com" 1242 }, 1243 "another-org-directory":{ 1244 "@type": "Resource", 1245 "type": "directory", 1246 "resource": "ldap://ldap.tech.example/o=Example%20Tech,ou=Engineering", 1247 "pref": 1 1248 }, 1249 ... 1250 }, 1251 ... 1252 } 1254 Figure 21: ORG-DIRECTORY mapping example 1256 2.10. Explanatory Properties 1258 2.10.1. CATEGORIES 1260 A CATEGORIES property is converted into a set of entries of the 1261 "categories" map (Figure 22). The keys are the comma-separated text 1262 values of the CATEGORIES property. 1264 In this case, the PREF parameter has not a JSContact counterpart; 1265 however, implementers MAY use a map preserving the order of insertion 1266 and the map entries can be inserted by order of preference. 1268 BEGIN:VCARD 1269 VERSION:4.0 1270 ... 1271 CATEGORIES:INTERNET,IETF,INDUSTRY,INFORMATION TECHNOLOGY 1272 ... 1273 END:VCARD 1275 { 1276 "@type": "Card", 1277 ... 1278 "categories":{ 1279 "INTERNET": true, 1280 "IETF": true, 1281 "INDUSTRY": true, 1282 "INFORMATION TECHNOLOGY": true 1283 }, 1284 ... 1285 } 1287 Figure 22: CATEGORIES mapping example 1289 2.10.2. NOTE 1291 A NOTE property is mapped to the "notes" property (Figure 23). All 1292 the NOTE instances are condensed into a single note and separated by 1293 newline. 1295 The ALTID and LANGUAGE parameters are mapped according to the rules 1296 as defined in Section 2.1. 1298 BEGIN:VCARD 1299 VERSION:4.0 1300 ... 1301 NOTE:This fax number is operational 0800 to 1715 EST\, Mon-Fri. 1302 ... 1303 END:VCARD 1305 { 1306 "@type": "Card", 1307 ... 1308 "notes": "This fax number is operational 0800 to 1715 EST, Mon-Fri.", 1309 ... 1310 } 1312 Figure 23: NOTE mapping example 1314 2.10.3. PRODID 1316 The PRODID property is converted into the "prodId" member 1317 (Figure 24). 1319 BEGIN:VCARD 1320 VERSION:4.0 1321 ... 1322 PRODID:-//ONLINE DIRECTORY//NONSGML Version 1//EN 1323 ... 1324 END:VCARD 1326 { 1327 "@type": "Card", 1328 ... 1329 "prodId": "-//ONLINE DIRECTORY//NONSGML Version 1//EN", 1330 ... 1331 } 1333 Figure 24: PRODID mapping example 1335 2.10.4. REV 1337 The REV property is transformed into the "updated" member 1338 (Figure 25). 1340 BEGIN:VCARD 1341 VERSION:4.0 1342 ... 1343 REV:19951031T222710Z 1344 ... 1345 END:VCARD 1347 { 1348 "@type": "Card", 1349 ... 1350 "updated": "1995-10-31T22:27:10Z", 1351 ... 1352 } 1354 Figure 25: REV mapping example 1356 2.10.5. SOUND 1358 A SOUND property is represented as an entry of the "online" map 1359 (Figure 26). The entry value is a "Resource" object whose "type" 1360 member is set to "audio" and the "resource" member is the SOUND 1361 value. 1363 The PREF and TYPE parameters are mapped according to the rules as 1364 defined in Section 2.1. 1366 BEGIN:VCARD 1367 VERSION:4.0 1368 ... 1369 SOUND:CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com 1370 ... 1371 END:VCARD 1373 { 1374 "@type": "Card", 1375 ... 1376 "online":{ 1377 ... 1378 "a-sound":{ 1379 "@type": "Resource", 1380 "type": "audio", 1381 "resource": "CID:JOHNQPUBLIC.part8.19960229T080000.xyzMail@example.com" 1382 }, 1383 ... 1384 }, 1385 ... 1386 } 1388 Figure 26: SOUND mapping example 1390 2.10.6. UID 1392 The UID property corresponds to the "uid" property (Figure 27) in 1393 both Card and CardGroup. 1395 BEGIN:VCARD 1396 VERSION:4.0 1397 ... 1398 UID:urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6 1399 ... 1400 END:VCARD 1402 { 1403 "@type": "Card", 1404 ... 1405 "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6", 1406 ... 1407 } 1409 Figure 27: UID mapping example 1411 2.10.7. CLIENTPIDMAP and PID Parameter 1413 The CLIENTPIDMAP property and the PDI parameter don't have a direct 1414 match with a Card feature. 1416 2.10.8. URL 1418 An URL property is represented as an entry of the "online" map 1419 (Figure 28). The entry value is a "Resource" object whose "type" 1420 member is set to "uri" and the "resource" member is the URL value. 1422 The PREF and TYPE parameters are mapped according to the rules as 1423 defined in Section 2.1. 1425 BEGIN:VCARD 1426 VERSION:4.0 1427 ... 1428 URL:http://example.org/restaurant.french/~chezchic.html 1429 ... 1430 END:VCARD 1432 { 1433 "@type": "Card", 1434 ... 1435 "online":{ 1436 ... 1437 "an-url":{ 1438 "@type": "Resource", 1439 "type": "uri", 1440 "resource": "http://example.org/restaurant.french/~chezchic.html" 1441 }, 1442 ... 1443 }, 1444 ... 1445 } 1447 Figure 28: URL mapping example 1449 2.10.9. VERSION 1451 The VERSION property doesn't have a direct match with a JSContact 1452 feature. 1454 2.11. Security Properties 1455 2.11.1. KEY 1457 A KEY property is represented as an entry of the "online" map 1458 (Figure 29). The entry value is a "Resource" object whose "type" 1459 member is set to "publicKey" and the "resource" member is the KEY 1460 value. 1462 The PREF and TYPE parameters are mapped according to the rules as 1463 defined in Section 2.1. 1465 BEGIN:VCARD 1466 VERSION:4.0 1467 ... 1468 KEY:http://www.example.com/keys/jdoe.cer 1469 ... 1470 END:VCARD 1472 { 1473 "@type": "Card", 1474 ... 1475 "online":{ 1476 ... 1477 "a-key":{ 1478 "@type": "Resource", 1479 "type": "publicKey", 1480 "resource": "http://www.example.com/keys/jdoe.cer" 1481 }, 1482 ... 1483 }, 1484 ... 1485 } 1487 Figure 29: KEY mapping example 1489 2.12. Calendar Properties 1491 2.12.1. FBURL 1493 An FBURL property is represented as an entry of the "online" map 1494 (Figure 30). The entry value is a "Resource" object whose "type" 1495 member is set to "freeBusy" and the "resource" member is the FBURL 1496 value. 1498 The PREF and TYPE parameters are mapped according to the rules as 1499 defined in Section 2.1. 1501 BEGIN:VCARD 1502 VERSION:4.0 1503 ... 1504 FBURL;PREF=1:http://www.example.com/busy/janedoe 1505 FBURL;MEDIATYPE=text/calendar:ftp://example.com/busy/project-a.ifb 1506 ... 1507 END:VCARD 1509 { 1510 "@type": "Card", 1511 ... 1512 "online":{ 1513 ... 1514 "an-fburl":{ 1515 "@type": "Resource", 1516 "type": "freeBusy", 1517 "resource": "http://www.example.com/busy/janedoe", 1518 "pref": 1 1519 }, 1520 "another-fburl":{ 1521 "@type": "Resource", 1522 "type": "freeBusy", 1523 "resource": "ftp://example.com/busy/project-a.ifb", 1524 "mediaType": "text/calendar" 1525 }, 1526 ... 1527 }, 1528 ... 1529 } 1531 Figure 30: FBURL mapping example 1533 2.12.2. CALADRURI 1535 A CALADRURI property is represented as an entry of the "scheduling" 1536 map (Figure 31). The entry value is a "Scheduling" object whose 1537 "sendTo" map includes an entry whose key is set to "imip" and value 1538 is set to the CALADRURI value. 1540 The PREF parameter is mapped according to the rules as defined in 1541 Section 2.1. 1543 BEGIN:VCARD 1544 VERSION:4.0 1545 ... 1546 CALADRURI;PREF=1:mailto:janedoe@example.com 1547 CALADRURI:http://example.com/calendar/jdoe 1548 ... 1549 END:VCARD 1551 { 1552 "@type": "Card", 1553 ... 1554 "scheduling":{ 1555 ... 1556 "a-caladruri":{ 1557 "@type": "Scheduling", 1558 "sendTo": { 1559 "imip": "mailto:janedoe@example.com" 1560 }, 1561 "pref": 1 1562 }, 1563 "another-caladruri":{ 1564 "@type": "Scheduling", 1565 "sendTo": { 1566 "imip": "http://example.com/calendar/jdoe" 1567 } 1568 }, 1569 ... 1570 }, 1571 ... 1572 } 1574 Figure 31: CALADRURI mapping example 1576 2.12.3. CALURI 1578 A CALURI property is represented as an entry of the "online" map 1579 (Figure 32). The entry value is a "Resource" object whose "type" 1580 member is set to "calendar" and the "resource" member is the CALURI 1581 value. 1583 The PREF and TYPE parameters are mapped according to the rules as 1584 defined in Section 2.1. 1586 BEGIN:VCARD 1587 VERSION:4.0 1588 ... 1589 CALURI;PREF=1:http://cal.example.com/calA 1590 CALURI;MEDIATYPE=text/calendar:ftp://ftp.example.com/calA.ics 1591 ... 1592 END:VCARD 1594 { 1595 "@type": "Card", 1596 ... 1597 "online":{ 1598 ... 1599 "a-caluri":{ 1600 "@type": "Resource", 1601 "type": "calendar", 1602 "resource": "http://cal.example.com/calA", 1603 "pref": 1 1604 }, 1605 "another-caluri":{ 1606 "@type": "Resource", 1607 "type": "calendar", 1608 "resource": "ftp://ftp.example.com/calA.ics", 1609 "mediaType": "text/calendar" 1610 }, 1611 ... 1612 }, 1613 ... 1614 } 1616 Figure 32: CALURI mapping example 1618 2.13. vCard Unmatched Properties 1620 The unmatched vCard properties MAY be converted into JSContact 1621 properties whose name contains the prefix "ietf.org:rfc6350:" 1622 followed by property name in uppercase (i.e. 1623 ietf.org:rfc6350:CLIENTPIDMAP"). 1625 2.14. Card Required Properties 1627 While converting a vCard into a Card/CardGroup, only the topmost 1628 "uid" member is mandatory. Implementers are REQUIRED to set it when 1629 it is missing. 1631 3. Translating JSContact properties to vCard 1633 In most of the cases, the rules about the translation from Card/ 1634 CardGroup to vCard can be derived by reversing the rules presented in 1635 Section 2. The remaining cases are treated in the following of this 1636 section. 1638 3.1. Id 1640 Where a map key is of type Id, implementers are free to either ignore 1641 it or preserve it as a vCard information (e.g. a vCard parameter). 1643 3.2. Localizations 1645 Each PatchObject entry value of each "localizations" entry is 1646 converted into a instance of the vCard property matching the 1647 JSContact member referenced by the PatchObject entry key. The 1648 LANGUAGE parameter of such alternative MUST be set to the value of 1649 the given "localizations" entry. The LANGUAGE parameter of a vCard 1650 property presenting, at least, a language-dependent alternative MUST 1651 be set to the value of the JSContact "language" property if it is 1652 valued. Implementers MAY set the ALTID parameter to group language- 1653 based alternatives of the same value. 1655 Note also that the components of some vCard values and their 1656 language-dependent alternatives are split into different JSContact 1657 values. For example, the "name" and "units" values for a given 1658 language must be grouped to make a single ORG value where components 1659 are separated by ";". 1661 3.3. Date and Time Representations 1663 The JSContact spec defines the "UTCDateTime" type to represent 1664 [RFC3339] "date-time" format with further restrictions. This means 1665 that the matched vCard format for a "UTCDateTime" value MUST be one 1666 of the formats shown in Section 4.3.5 of [RFC6350] (i.e. 1667 "19961022T140000Z"). 1669 In addition to such format, the "date" member of the "Anniversary" 1670 type allows to specify both dates without the time and partial dates. 1671 In such cases, the corresponding vCard format is that defined in 1672 Section 4.3.1. 1674 3.4. Time Zone 1676 The time zone name as represented by the "timeZone" property is 1677 mapped to the TZ parameter. 1679 Implementers MAY map an "Etc/GMT" time zone either preserving the 1680 time zone name or converting it into a UTC offset. 1682 3.5. JSContact Types Matching Multiple vCard Properties 1684 3.5.1. Title 1686 The "titles" property contains information about the job, the 1687 position or the role of the entity the card represents. In vCard, 1688 such information is split into the TITLE and the ROLE properties. 1689 This specification defines TITLE as the default target property when 1690 converting the "titles" property. 1692 3.5.2. Resource 1694 The "online" property includes resources that are usually represented 1695 through different vCard properties. The matched vCard property of a 1696 "Resource" object can be derived from the value of its "type" member. 1698 Any resource included in the "online" map that doesn't match a vCard 1699 property MAY be converted into a vCard extended property. 1701 3.6. CardGroup 1703 A CardGroup object is converted into a vCard by merging its 1704 properties with the properties of "CardGroup.card" object. If the 1705 "CardGroup.card.fullName" property exists, it MUST be used to set the 1706 FN value. 1708 3.7. Card Unmatched Properties 1710 Both the "preferredContactMethod" and "created" members don't match 1711 any vCard property. Implementers MAY represent them as vCard 1712 extended properties. 1714 3.8. vCard Required Properties 1716 While converting a Card/CardGroup into a vCard, only the FN property 1717 is required. Since both the "Card.fullName" and "CardGroup.name" 1718 properties are optional, implementers are REQUIRED to generate an FN 1719 value when it is missing. 1721 4. IANA Considerations 1723 This document has no actions for IANA. 1725 5. Implementation Status 1727 NOTE: Please remove this section and the reference to RFC 7942 prior 1728 to publication as an RFC. 1730 This section records the status of known implementations of the 1731 protocol as defined in this specification at the time of posting of 1732 this Internet-Draft, and is based on a proposal described in 1733 [RFC7942]. The description of implementations in this section is 1734 intended to assist the IETF in its decision processes in progressing 1735 drafts to RFCs. Please note that the listing of any individual 1736 implementation here does not imply endorsement by the IETF. 1737 Furthermore, no effort has been spent to verify the information 1738 presented here that was supplied by IETF contributors. This is not 1739 intended as, and must not be construed to be, a catalog of available 1740 implementations or their features. Readers are advised to note that 1741 other implementations may exist. 1743 According to RFC 7942, "this will allow reviewers and working groups 1744 to assign due considerationto documents that have the benefit of 1745 running code, which may serve as evidence of valuable experimentation 1746 and feedback that have made the implemented protocols more mature. 1747 It is up to the individual working groups to use this information as 1748 they see fit". 1750 5.1. CNR 1752 * Responsible Organization: National Research Council (CNR) of Italy 1753 * Location: https://github.com/consiglionazionaledellericerche/ 1754 jscontact-tools 1755 * Description: This implementation includes tools for JSContact 1756 creation, validation, serialization/deserialization, and 1757 conversion from vCard, xCard and jCard. 1758 * Level of Maturity: This is an "alpha" test implementation. 1759 * Coverage: This implementation includes all of the features 1760 described in this specification. 1761 * Contact Information: Mario Loffredo, mario.loffredo@iit.cnr.it 1763 6. Security Considerations 1765 This document doesn't present any security consideration. 1767 7. References 1769 7.1. Normative References 1771 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1772 Requirement Levels", BCP 14, RFC 2119, 1773 DOI 10.17487/RFC2119, March 1997, 1774 . 1776 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1777 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1778 . 1780 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 1781 DOI 10.17487/RFC6350, August 2011, 1782 . 1784 [RFC6473] Saint-Andre, P., "vCard KIND:application", RFC 6473, 1785 DOI 10.17487/RFC6473, December 2011, 1786 . 1788 [RFC6474] Li, K. and B. Leiba, "vCard Format Extensions: Place of 1789 Birth, Place and Date of Death", RFC 6474, 1790 DOI 10.17487/RFC6474, December 2011, 1791 . 1793 [RFC6715] Cauchie, D., Leiba, B., and K. Li, "vCard Format 1794 Extensions: Representing vCard Extensions Defined by the 1795 Open Mobile Alliance (OMA) Converged Address Book (CAB) 1796 Group", RFC 6715, DOI 10.17487/RFC6715, August 2012, 1797 . 1799 [RFC6869] Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard 1800 KIND:device", RFC 6869, DOI 10.17487/RFC6869, February 1801 2013, . 1803 [RFC7095] Kewisch, P., "jCard: The JSON Format for vCard", RFC 7095, 1804 DOI 10.17487/RFC7095, January 2014, 1805 . 1807 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1808 Code: The Implementation Status Section", BCP 205, 1809 RFC 7942, DOI 10.17487/RFC7942, July 2016, 1810 . 1812 [RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions: 1813 ICANN Extensions for the Registration Data Access Protocol 1814 (RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019, 1815 . 1817 7.2. Informative References 1819 [I-D.ietf-calext-jscontact] 1820 Stepanek, R. and M. Loffredo, "JSContact: A JSON 1821 representation of contact data", Work in Progress, 1822 Internet-Draft, draft-ietf-calext-jscontact-00, 17 January 1823 2020, . 1826 [time-zones] 1827 "Time Zone Database", . 1829 [uri-schemes] 1830 "Uniform Resource Identifier (URI) Schemes", 1831 . 1834 Authors' Addresses 1836 Mario Loffredo 1837 IIT-CNR/Registro.it 1838 Via Moruzzi,1 1839 56124 Pisa 1840 Italy 1841 Email: mario.loffredo@iit.cnr.it 1842 URI: http://www.iit.cnr.it 1844 Robert Stepanek 1845 FastMail 1846 PO Box 234, Collins St West 1847 Melbourne VIC 8007 1848 Australia 1849 Email: rsto@fastmailteam.com 1850 URI: https://www.fastmail.com