idnits 2.17.1 draft-kewisch-vcard-in-json-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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (March 18, 2013) is 4029 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-02) exists of draft-kewisch-et-al-icalendar-in-json-01 -- Obsolete informational reference (is this intentional?): RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Kewisch 3 Internet-Draft Mozilla 4 Intended status: Standards Track March 18, 2013 5 Expires: September 19, 2013 7 jCard: The JSON format for vCard 8 draft-kewisch-vcard-in-json-01 10 Abstract 12 This specification defines "jCard", a JSON format for vCard data. 14 Status of This Memo 16 This Internet-Draft is submitted in full conformance with the 17 provisions of BCP 78 and BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF). Note that other groups may also distribute 21 working documents as Internet-Drafts. The list of current Internet- 22 Drafts is at http://datatracker.ietf.org/drafts/current/. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 This Internet-Draft will expire on September 19, 2013. 31 Copyright Notice 33 Copyright (c) 2013 IETF Trust and the persons identified as the 34 document authors. All rights reserved. 36 This document is subject to BCP 78 and the IETF Trust's Legal 37 Provisions Relating to IETF Documents 38 (http://trustee.ietf.org/license-info) in effect on the date of 39 publication of this document. Please review these documents 40 carefully, as they describe your rights and restrictions with respect 41 to this document. Code Components extracted from this document must 42 include Simplified BSD License text as described in Section 4.e of 43 the Trust Legal Provisions and are provided without warranty as 44 described in the Simplified BSD License. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 49 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 50 3. Converting from vCard to jCard . . . . . . . . . . . . . . . . 4 51 3.1. Pre-processing . . . . . . . . . . . . . . . . . . . . . . 4 52 3.2. vCard Stream . . . . . . . . . . . . . . . . . . . . . . . 4 53 3.3. Properties (RFC6350 section 6) . . . . . . . . . . . . . . 5 54 3.3.1. Special Cases for Properties . . . . . . . . . . . . . 6 55 3.3.1.1. Multi-valued Properties . . . . . . . . . . . . . 6 56 3.3.1.2. Grouping of Properties . . . . . . . . . . . . . . 7 57 3.4. Parameters (RFC6350 section 5) . . . . . . . . . . . . . . 7 58 3.4.1. VALUE parameter . . . . . . . . . . . . . . . . . . . 7 59 3.4.2. Multi-value Parameters . . . . . . . . . . . . . . . . 8 60 3.5. Values (RFC6350 section 4) . . . . . . . . . . . . . . . . 8 61 3.5.1. Text (RFC6350 section 4.1) . . . . . . . . . . . . . . 8 62 3.5.2. URI (RFC6350 section 4.2) . . . . . . . . . . . . . . 9 63 3.5.3. Date (RFC6350 section 4.3.1) . . . . . . . . . . . . . 9 64 3.5.4. Time (RFC6350 section 4.3.2) . . . . . . . . . . . . . 10 65 3.5.5. Date-Time (RFC6350 section 4.3.3) . . . . . . . . . . 10 66 3.5.6. Date and/or Time (RFC6350 section 4.3.4) . . . . . . . 11 67 3.5.7. Timestamp (RFC6350 section 4.3.5) . . . . . . . . . . 11 68 3.5.8. Boolean (RFC6350 section 4.4) . . . . . . . . . . . . 11 69 3.5.9. Integer (RFC6350 section 4.5) . . . . . . . . . . . . 11 70 3.5.10. Float (RFC6350 section 4.6) . . . . . . . . . . . . . 12 71 3.5.11. UTC Offset (RFC6350 section 4.7) . . . . . . . . . . . 12 72 3.5.12. Language Tag (RFC6350 section 4.8) . . . . . . . . . . 12 73 3.6. Extensions (RFC6350 section 6.10) . . . . . . . . . . . . 13 74 4. Converting from jCard into vCard . . . . . . . . . . . . . . . 13 75 5. Handling Unrecognized Properties or Parameters . . . . . . . . 13 76 6. Conversion of Date and Time Related Data Types . . . . . . . . 15 77 6.1. Conversion from jCard to vCard . . . . . . . . . . . . . . 15 78 6.2. Conversion from vCard to jCard . . . . . . . . . . . . . . 15 79 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 80 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 81 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 82 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 83 10.1. Normative References . . . . . . . . . . . . . . . . . . . 17 84 10.2. Informative References . . . . . . . . . . . . . . . . . . 18 85 Appendix A. ABNF Schema . . . . . . . . . . . . . . . . . . . . . 18 86 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 20 87 B.1. Example: vCard of the author of RFC6350 . . . . . . . . . 20 88 B.1.1. vCard Data . . . . . . . . . . . . . . . . . . . . . . 20 89 B.1.2. jCard Data . . . . . . . . . . . . . . . . . . . . . . 21 90 Appendix C. Open Issues (to be removed prior to publication 91 as an RFC) . . . . . . . . . . . . . . . . . . . . . 22 92 Appendix D. Change History (to be removed prior to 93 publication as an RFC) . . . . . . . . . . . . . . . 23 95 1. Introduction 97 The vCard data format [RFC6350] has gone through multiple revisions, 98 most recently vCard 4. The goal followed by this format is the 99 capture and exchange of information normally stored within an address 100 book or directory application. As certain similarities to the 101 iCalendar data format [RFC5545] exist it makes sense to define a 102 JSON-based data format for vCards that is similar to the jCal format 103 defined in [I-D.kewisch-et-al-icalendar-in-json]. 105 The purpose of this specification is to define "jCard", a JSON format 106 for vCard data. One main advantage to using a JSON-based format as 107 defined in [RFC4627] over the classic vCard format is easier 108 processing for JavaScript based widgets and libraries, especially in 109 the scope of web-based applications. 111 The key design considerations are essentially the same as those for 112 [I-D.kewisch-et-al-icalendar-in-json] and [RFC6321], that is: 114 Round-tripping (converting a vCard instance to jCard and back) 115 will give the same semantic result as the starting point. For 116 example, all components, properties and property parameters are 117 guaranteed to be preserved, with the exception of those which have 118 default values. 120 Ordering of elements will not necessarily be preserved. 122 Preserve the semantics of the vCard data. While a simple consumer 123 can easily browse the data in jCard, a full understanding of vCard 124 is still required in order to modify and/or fully comprehend the 125 directory data. 127 Ability to handle many extensions to the underlying vCard 128 specification without requiring an update to this document. 130 2. Conventions Used in This Document 132 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 133 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 134 document are to be interpreted as described in [RFC2119]. 136 The underlying format used for jCard is JSON. Consequently, the 137 terms "object" and "array" as well as the four primitive types are to 138 be interpreted as described in Section 1 of [RFC4627]. 140 Some examples in this document contain "partial" JSON documents used 141 for illustrative purposes. In these examples, three periods "..." 142 are used to indicate a portion of the document that has been removed 143 for compactness. 145 3. Converting from vCard to jCard 147 This section describes how vCard data is converted to jCard using a 148 simple mapping between the vCard data model and JSON elements. 150 3.1. Pre-processing 152 vCard uses a line folding mechanism to limit lines of data to a 153 maximum line length (typically 72 characters) to ensure maximum 154 likelihood of preserving data integrity as it is transported via 155 various means (e.g., email) - see Section 3.2 of [RFC6350]. Prior to 156 converting vCard data into jCard all folded lines MUST be unfolded. 158 vCard data uses an "escape" character sequence for text values and 159 property parameter values. When such text elements are converted 160 into jCard the escaping MUST be removed. See Section 3.4 of 161 [RFC6350]. 163 One key difference in the formatting of values used in vCard and 164 jCard is that in jCard the specification uses date/time values 165 aligned with the complete representation, extended format of 166 [ISO.8601.2004]. 168 3.2. vCard Stream 170 In certain cases it makes sense to group a sequence of vcard objects 171 into a stream of objects. While the vCard 4 standard doesn't define 172 a stream of vcard objects, having one makes it easier to identify 173 multiple jCard objects and also ensures compatibility to jCal. A 174 jCard stream is identified by an array, where the first element is 175 the string "vcardstream". Subsequent elements are vCard objects 176 represented as described in this document. 178 In the typical case where there is only one vCard object, 179 encapsulation inside a "vcardstream" array MAY be omitted. 181 A vCard stream can contain one or more vCard objects. Each vCard 182 object, delimited by "BEGIN:VCARD" and "END:VCARD", is represented in 183 JSON as a fixed length array with two elements: 185 1. The string "vcard" 187 2. An array of jCard properties 189 The representation of a vCard object in JSON will be named "vcard 190 component" throughout this document. 192 Example: 194 ["vcardstream", 195 ["vcard", 196 [ /* properties */ ] 197 ], 198 ["vcard", 199 [ /* properties */ ] 200 ], 201 ... 202 ] 204 vCard objects are comprised of a set of "properties", "parameters" 205 and "values". The top level of a vCard object contains "properties". 206 A "property" has a "value" and a set of zero or more "parameters". 207 vCard objects are delimited by the general properties "BEGIN" and 208 "END" with the fixed value "VCARD" as defined in Section 6.1.1 and 209 6.1.2 of [RFC6350]. In addition, the vCard format is versioned, 210 therefore the "version" property is mandatory. To comply with 211 Section 6.7.9 of [RFC6350], the value of the version property MUST be 212 "4.0". 214 3.3. Properties (RFC6350 section 6) 216 Each individual vCard property is represented in jCard by an array 217 with three fixed elements, followed by one or more additional 218 elements, depending on if the property is a multi-value property as 219 described in Section 3.3 of [RFC6350]. 221 The array consists of the following fixed elements: 223 1. The name of the property as a string, but in lowercase. 225 2. An object containing the parameters as described in Section 3.4. 227 3. The type identifier string of the value, in lowercase. 229 The remaining elements of the array are used for the value of the 230 property. For single-value properties, the array MUST have exactly 231 four elements, for multi-valued properties as described in 232 Section 3.3.1.1 there can be any number of additional elements. 234 The array describing the property can then be inserted into the array 235 designated for properties in the "vcard" component. 237 Example: 239 ["vcard", 240 [ 241 ["version", {}, "text", "4.0"], 242 ["fn", {}, "text", "John Doe"], 243 ["gender", {}, "text", "M"], 244 ... 245 ], 246 ] 248 The property parameters in the second element of the property array 249 associate a set of parameter names with their respective value. 250 Parameters are further described in Section 3.4. 252 To allow for a cleaner implementation, the parameter object MUST be 253 present even if there are no parameters. In this case, an empty 254 object MUST be used. 256 3.3.1. Special Cases for Properties 258 This section describes some properties that have special handling 259 when converting to jCard. 261 3.3.1.1. Multi-valued Properties 263 Various vCard properties defined in [RFC6350], for example the 264 "CATEGORIES" property, are defined as multi-valued properties. In 265 jCal these properties are added as further members of the array 266 describing the property. 268 Note that additional multi-valued properties may be added in 269 extensions to the iCalendar format. 271 Example: 273 ["vcard", 274 [ 275 ["categories", {}, "text", "computers", "cameras"], 276 ... 277 ], 278 ... 279 ] 281 3.3.1.2. Grouping of Properties 283 [RFC6350] Section 3.3 defines a grouping construct that is used to 284 group related properties together. In jCard, each grouped property 285 appears as a separate property containing the group name and property 286 name, separated by a "." character. This was done to maintain 287 compatibilty of array elements with 288 [I-D.kewisch-et-al-icalendar-in-json]. 290 Example: 292 ["vcard", 293 [ 294 ["groupname.email", {}, "text", "johndoe@example.org"], 295 ... 296 ], 297 ... 298 ] 300 3.4. Parameters (RFC6350 section 5) 302 Property parameters are represented as a JSON object where each key- 303 value pair represents the vCard parameter name and its value. The 304 name of the parameter MUST be in lowercase, the original case of the 305 parameter value MUST be preserved. For example, the "LANG" property 306 parameter is represented in jCard by the "lang" key. Any new vCard 307 parameters added in the future will be converted in the same way. 309 Example: 311 ["vcard", 312 [ 313 ["role", { "lang": "tr" }, "text", "roca"], 314 ... 315 ], 316 ... 317 ] 319 3.4.1. VALUE parameter 321 vCard defines a "VALUE" property parameter (Section 5.2 of 322 [RFC6350]). This property parameter MUST NOT be added to the 323 parameters object. Instead, the value type is always explicitly 324 mentioned in the third element of the array describing the property. 325 Thus, when converting from vCard to jCard, any "VALUE" property 326 parameters are skipped. When converting from jCard into vCard, the 327 appropriate "VALUE" property parameter MUST be included in the vCard 328 property if the value type is not the default value type for that 329 property. 331 3.4.2. Multi-value Parameters 333 In [RFC6350], some parameters allow using a COMMA-separated list of 334 values. To ease processing in jCard, the value to such parameters 335 MUST be represented in an array containing the separated values. The 336 array elements MUST be string values. Single-value parameters SHOULD 337 be represented using a single string value, but an array with one 338 element MAY also be used. An example for a such parameter is the 339 vCard "SORT-AS" parameter, more such parameters may be added in 340 extensions. 342 DQUOTE characters used to encapsulate the separated values MUST NOT 343 be added to the jCard parameter value. 345 Example 1: 347 ["vcard", 348 [ 349 ["n", 350 { "sort-as": ["Harten", "Rene"] }, 351 "text", 352 "van der Harten;Rene,J.;Sir;R.D.O.N." 353 ], 354 ["fn", {}, "text", "Rene van der Harten"] 355 ... 356 ], 357 ... 358 ] 360 3.5. Values (RFC6350 section 4) 362 The type of a vCard value is explicitly mentioned in the third 363 element of the array describing a jCard property. The actual values 364 of the property can be found in the fourth and following elements of 365 the array. 367 3.5.1. Text (RFC6350 section 4.1) 369 Description: vCard "TEXT" property values are represented by a 370 property with the type identifier "text". The value elements are 371 JSON strings. 373 Example: 375 ... 376 ["kind", {}, "text", "group"], 377 ... 379 3.5.2. URI (RFC6350 section 4.2) 381 Description: vCard "URI" property values are represented by a 382 property with the type identifier "uri". The value elements are 383 JSON strings. 385 Example: 387 ... 388 ["source", {}, "uri", "ldap://ldap.example.com/cn=babs%20jensen"], 389 ... 391 3.5.3. Date (RFC6350 section 4.3.1) 393 Description: vCard "DATE" property values are represented by a 394 property with the type identifier "date". The value elements are 395 JSON strings with the same date value specified by [RFC6350], but 396 formatted using the [ISO.8601.2004] complete representation, 397 extended format. The same date format restrictions regarding 398 reduced accuracy, truncated representation and expanded 399 representation noted in [RFC6350] Section 4.1.2.3 apply. Whenever 400 the extended format is not applicable, the basic format is to be 401 used. 403 ABNF Schema: 405 date-complete = year "-" month "-" day ;YYYY-MM-DD 407 date-noreduc = date-complete 408 / "--" month "-" day; --MM-DD 409 / "---" day; ---DDD 411 date = date-noreduc 412 / year; YYYY 413 / year "-" month ; YYYY-MM 414 / "--" month; --MM 416 Examples: 418 ... 419 ["bday", {}, "date", "1985-04-12"], 420 ["bday", {}, "date", "1985-04"], 421 ["bday", {}, "date", "1985"], 422 ["bday", {}, "date", "--0412"], 423 ["bday", {}, "date", "---12"], 424 ... 426 3.5.4. Time (RFC6350 section 4.3.2) 428 Description: vCard "TIME" property values are represented by a 429 property with the type identifier "time". The value elements are 430 JSON strings with the same time value specified by [RFC6350], but 431 formatted using the [ISO.8601.2004] complete representation, 432 extended format. The same date format restrictions regarding 433 reduced accuracy, decimal fraction and truncated representation 434 noted in [RFC6350] Section 4.3.2 apply. Whenever the extended 435 format is not applicable, the basic format is to be used. The 436 seconds value of 60 MUST only be used to account for positive 437 "leap" seconds and the midnight hour is always represented by 00, 438 never 24. Fractions of a second are not supported by this format. 439 Contrary to [I-D.kewisch-et-al-icalendar-in-json], UTC offsets are 440 permitted within a time value. 442 ABNF Schema: 444 time-notrunc = hour [":" minute [":" second]] [zone] 446 time = time-notrunc 447 / "-" minute ":" second [zone]; -mm:ss 448 / "-" minute [zone]; -mm 449 / "--" second [zone]; --ss 451 Examples: 453 ... 454 ["x-time-local", {}, "time", "12:30:00"], 455 ["x-time-utc", {}, "time", "12:30:00Z"], 456 ["x-time-offset", "time", "12:30:00-0800"], 457 ["x-time-reduced", "time", "23"], 458 ["x-time-truncated", "time", "-30"], 459 ... 461 3.5.5. Date-Time (RFC6350 section 4.3.3) 463 Description: vCard "DATE-TIME" property values are represented by a 464 property with the type identifier "date-time". The value elements 465 are JSON strings with the same date value specified by [RFC6350], 466 but formatted using the [ISO.8601.2004] complete representation, 467 extended format. The same restrictions with respect to leap 468 seconds, fractions of a second and UTC offsets as in Section 3.5.4 469 apply. Just as in [RFC6350], truncation of the date part is 470 permitted. 472 Example: 474 ... 475 ["anniversary", {}, "date-time", "2013-02-14T12:30:00"], 476 ["anniversary", {}, "date-time", "2013-01-10T19:00:00Z"], 477 ["anniversary", {}, "date-time", "2013-08-15T09:45:00+0100"], 478 ["anniversary", {}, "date-time", "---15T09:45:00+0100"], 479 ... 481 3.5.6. Date and/or Time (RFC6350 section 4.3.4) 483 Description: jCard has no direct equivalent to vCard's "DATE-AND-OR- 484 TIME" property value data type. Instead, the specified date, 485 date-time or time format MUST be detected and the property MUST be 486 represented by a property with the detected type identifier. See 487 Section 6 for more information on how conversion between jCard and 488 vCard should be handled. 490 3.5.7. Timestamp (RFC6350 section 4.3.5) 492 Description: jCard has no direct equivalent to vCard's "TIMESTAMP" 493 property value data type. Instead, the specified complete date 494 and time of day combination MUST be represented by a property with 495 the "date-time" identifier. See Section 6 for more information on 496 how conversion between jCard and vCard should be handled. 498 3.5.8. Boolean (RFC6350 section 4.4) 500 Description: vCard "BOOLEAN" property values are represented by a 501 property with the type identifier "boolean". The value element is 502 a JSON boolean value. 504 Example: 506 ... 507 ["x-non-smoking", {}, "boolean", true], 508 ... 510 3.5.9. Integer (RFC6350 section 4.5) 512 Description: vCard "INTEGER" property values are represented by a 513 property with the type identifier "integer". The value elements 514 are JSON primitive number values. 516 Examples: 518 ... 519 ["x-karma-points", {}, "integer", 42], 520 ... 522 3.5.10. Float (RFC6350 section 4.6) 524 Description: vCard "FLOAT" property values are represented by a 525 property with the type identifier "float". The value elements are 526 JSON primitive number values. 528 Example: 530 ... 531 ["x-grade", {}, "float", 1.3], 532 ... 534 3.5.11. UTC Offset (RFC6350 section 4.7) 536 Description: vCard "UTC-OFFSET" property values are represented by a 537 property with the type identifier "utc-offset". The value 538 elements are JSON strings with the same UTC offset value specified 539 by [RFC6350], with the exception that the hour and minute 540 components are separated by a ":" character, for consistency with 541 the [ISO.8601.2004] timezone offset, extended format. 543 Example: 545 ... 546 // Note: [RFC6350] mentions use of utc-offset 547 // for the TZ property as NOT RECOMMENDED 548 ["tz", {}, "utc-offset", "-05:00"], 549 .. 551 3.5.12. Language Tag (RFC6350 section 4.8) 553 Description: vCard "LANGUAGE-TAG" property values are represented by 554 a property with the type identifier "language-tag". The value 555 elements are JSON strings containing a single language-tag, as 556 defined in [RFC5646]. 558 Example: 560 ... 561 ["lang", {}, "language-tag", "de"], 562 .. 564 3.6. Extensions (RFC6350 section 6.10) 566 vCard extension properties and property parameters (those with an 567 "X-" prefix in their name) are handled in the same way as other 568 properties and property parameters: the property is represented by an 569 array, the property parameter represented by an object. The property 570 or parameter name uses the same name as for the vCard extension, but 571 in lowercase. For example, the "X-FOO" property in vCard turns into 572 the "x-foo" jCard property. See Section 5 for how to deal with 573 default values for unrecognized extension properties or property 574 parameters. 576 4. Converting from jCard into vCard 578 When converting property and property parameter values, the names 579 SHOULD be converted to uppercase. Although vCard names are case 580 insensitive, common practice is to keep them all uppercase following 581 the actual definitions in [RFC6350]. 583 Backslash escaping and line folding MUST be applied to the resulting 584 vCard data as required by [RFC6350]. 586 When converting to vCard, the VALUE parameter MUST be added to 587 properties whose default value type is unknown. The VALUE parameter 588 SHOULD NOT be added to properties using the default value type. 590 5. Handling Unrecognized Properties or Parameters 592 In vCard, properties have a default value type specified by their 593 definition, e.g. "BDAY"'s value type is "date-and-or-time", but it 594 can also be reset to a single "text" value. When a property uses its 595 default value type, the "VALUE" property parameter does not need to 596 be specified on the property. 598 When new properties are defined or "X-" properties used, a vCard to 599 jCard converter might not recognize them, and not know what the 600 appropriate default value types are, yet they need to be able to 601 preserve the values. A similar issue arises for unrecognized 602 property parameters. As a result, the following rules are applied 603 when dealing with unrecognized properties and property parameters: 605 o When converting vCard into jCard: 607 * Any property that does not include a "VALUE" property parameter 608 and whose default value type is not known, MUST be converted to 609 a string object. The content of that string is the unprocessed 610 value text. 612 * Any unrecognized property parameter MUST be converted to a 613 string value, with its content set to the property parameter 614 value text, treated as if it were a "TEXT" value. 616 o When converting jCard into vCard: 618 * Since jCard always explicitly specifies the value type, it can 619 always be converted to vCard using the VALUE parameter. 621 * If the value type specified in jCard matches the default value 622 type in vCard, the VALUE parameter SHOULD be omitted. 624 Example: The following is an example of an unrecognized vCard 625 property (that uses an "URI" value as its default), and the 626 equivalent jCard representation of that property. 628 vCard: 630 X-COMPLAINT-URI:mailto:abuse@example.org 632 jCard: 634 ... 635 ["x-complaint-uri", {}, "text", "mailto:abuse@example.org"], 636 ... 638 Example: The following is an example of a jCard property (where the 639 corresponding vCard property uses a "INTEGER" value as its default), 640 and the equivalent vCard representation of that property. It is 641 assumed that the parser has knowledge of the default data type for 642 the "x-karma-points" property. 644 jCard: 646 ... 647 ["x-karma-points", {}, "integer", 95], 648 ... 650 vCard: 652 X-KARMA-POINTS:95 654 Example: The following is an example of an unrecognized vCard 655 property parameter (that uses a "FLOAT" value as its default) 656 specified on a recognized vCard property, and the equivalent jCard 657 representation of that property and property parameter. 659 vCard: 661 GENDER;X-PROBABILITY=0.8:M 663 jCard: 665 ... 666 ["gender", { "x-probability": "0.8" }, "text", "M"], 667 ... 669 6. Conversion of Date and Time Related Data Types 671 [RFC6350] defines the data types DATE, DATE-TIME, TIME, DATE-AND-OR- 672 TIME and TIMESTAMP, covering various aspects of dates and times. As 673 jCard is more "strongly typed", some of these types have been 674 consolidated. This section aims to aid conversion between jCard and 675 vCard and vice versa. 677 Regardless of the date/time related property converted, jCard and 678 vCard use different representations of the [ISO.8601.2004] format. 679 The date format MUST be adjusted during conversion. 681 6.1. Conversion from jCard to vCard 683 o If the property type of the jCard property matches the property's 684 default type, the VALUE parameter MUST NOT be added to the vCard 685 property. 687 o For property types "date-and-or-time" or "timestamp", the property 688 value MUST be converted to a permitted date and/or time format as 689 specified in [RFC6350] Section 4.3.4 and 4.3.5 and the VALUE 690 parameter MUST NOT be added to the vCard property. If a permitted 691 conversion cannot be done, the VALUE parameter must be added with 692 the closest available date/time format identifier. 694 o If the default type is unknown or the jCal property type does not 695 match the default type, the VALUE parameter MUST be specified. 697 6.2. Conversion from vCard to jCard 699 o If the parser knows the default type of the property and it is one 700 of "DATE", "DATE-TIME" or "TIME", the properties can be directly 701 converted following the guidelines of the respective format type 702 in this document. 704 o For the property type "date-and-or-time", the parser SHOULD detect 705 if it is handling either a date, a time, or a date-time and use 706 the respective format identifier in jCard. 708 o For the property type "timestamp", the parser MUST use the format 709 type identifier "date-time" in the jCard property. 711 o If the (default) property type is unknown, the property value MUST 712 be treated as opaque text and the "text" format type identifier 713 MUST be used. 715 7. Security Considerations 717 For security considerations specific to calendar data, see Section 9 718 of [RFC6350]. Since this specification is a mapping from vCard, no 719 new security concerns are introduced related to calendar data. 721 The use of JSON as a format does have security risks. Section 7 of 722 [RFC4627] discusses these risks. 724 8. IANA Considerations 726 This document defines a MIME media type for use with vCard in JSON 727 data. This media type SHOULD be used for the transfer of calendaring 728 data in JSON. 730 Type name: application 732 Subtype name: vcard+json 734 Required parameters: none 736 Optional parameters: version as defined for the text/vcard media 737 type in [RFC6350]. 739 Encoding considerations: Same as encoding considerations of 740 application/json as specified in [RFC4627]. 742 Security considerations: See Section 7. 744 Interoperability considerations: This media type provides an 745 alternative format for vCard data based on JSON. 747 Published specification: This specification. 749 Applications which use this media type: Applications that currently 750 make use of the text/vcard media type can use this as an 751 alternative. Similarly, Applications that use the application/ 752 json media type to transfer directory data can use this to further 753 specify the content. 755 Person & email address to contact for further information: 756 vcarddav@ietf.org 758 Intended usage: COMMON 760 Restrictions on usage: There are no restrictions on where this media 761 type can be used. 763 Author: See the "Author's Address" section of this document. 765 Change controller: IETF 767 9. Acknowledgments 769 The author would like to thank the following for their valuable 770 contributions: Cyrus Daboo, Mike Douglass, William Gill, Erwin Rehme, 771 and Dave Thewlis. This specification originated from the work of the 772 XML-JSON technical committee of the Calendaring and Scheduling 773 Consortium. 775 10. References 777 10.1. Normative References 779 [I-D.kewisch-et-al-icalendar-in-json] Kewisch, P., Daboo, C., and M. 780 Douglass, "jCal: The JSON 781 format for iCalendar", draft- 782 kewisch-et-al-icalendar-in- 783 json-01 (work in progress), 784 January 2013. 786 [ISO.8601.2004] International Organization for 787 Standardization, ""Data 788 elements and interchange 789 formats -- Information 790 interchange -- Representation 791 of dates and times"", 792 ISO 8601, 12 2004. 794 [RFC2119] Bradner, S., "Key words for 795 use in RFCs to Indicate 796 Requirement Levels", BCP 14, 797 RFC 2119, March 1997. 799 [RFC5234] Crocker, D. and P. Overell, 800 "Augmented BNF for Syntax 801 Specifications: ABNF", STD 68, 802 RFC 5234, January 2008. 804 [RFC5545] Desruisseaux, B., "Internet 805 Calendaring and Scheduling 806 Core Object Specification 807 (iCalendar)", RFC 5545, 808 September 2009. 810 [RFC5646] Phillips, A. and M. Davis, 811 "Tags for Identifying 812 Languages", BCP 47, RFC 5646, 813 September 2009. 815 [RFC6321] Daboo, C., Douglass, M., and 816 S. Lees, "xCal: The XML Format 817 for iCalendar", RFC 6321, 818 August 2011. 820 [RFC6350] Perreault, S., "vCard Format 821 Specification", RFC 6350, 822 August 2011. 824 10.2. Informative References 826 [RFC4627] Crockford, D., "The 827 application/json Media Type 828 for JavaScript Object Notation 829 (JSON)", RFC 4627, July 2006. 831 [calconnect-artifacts] The Calendaring and Scheduling 832 Consortium, "Code Artifacts 833 and Schemas", . 837 Appendix A. ABNF Schema 839 Below is an ABNF schema as per [RFC5234] for vCard in JSON. ABNF 840 Symbols not described here are taken from [RFC4627]. The schema is 841 non-normative and given for reference only. 843 The numeric section numbers given in the comments refer to section in 844 [RFC6350]. Additional semantic restrictions apply, especially 845 regarding the allowed properties and sub-components per component. 846 Details on these restrictions can be found in this document and 847 [RFC6350]. 849 Additional schemas may be available on the internet at 850 [calconnect-artifacts]. 852 ; A vCard Stream is an array with the first element being the 853 ; string "vcardstream". All remaining elements are jcardobjects. 854 jcardstream = begin-array 855 DQUOTE "vcardstream" DQUOTE 856 *(value-separator jcardobject) 857 end-array 859 jcardobject = component 861 ; A jCard object consists of the name string "vcard" and a properties 862 ; array. Restrictions to which properties and may be specified are to 863 ; be taken from RFC6350. 864 jcardobject = begin-array 865 DQUOTE component-name DQUOTE value-separator 866 properties-array 867 end-array 869 ; A jCard property consists of the name string, parameters object, 870 ; type string and one or more values as specified in this document. 871 property = begin-array 872 DQUOTE property-name DQUOTE value-separator 873 params-object value-separator 874 DQUOTE type-name DQUOTE 875 propery-value *(value-separator property-value) 876 end-array 877 properties-array = begin-array 878 [ property *(value-separator property) ] 879 end-array 881 ; Property values depend on the type-name. Aside from the value types 882 ; mentioned here, extensions may make use of other JSON value types. 883 property-value = string / number / boolean 885 ; The jCard params-object is a JSON object which follows the semantic 886 ; guidelines described in this document. 887 params-object = begin-object 888 [ params-member *(value-separator params-member) ] 889 end-object 890 params-member = DQUOTE param-name DQUOTE name-separator param-value 891 param-value = string 893 ; The type MUST be a valid type as described by this document. New 894 ; value types can be added by extensions. 895 type-name = "text" / "uri" / "date" / "time" / "date-time" / 896 "boolean" / "integer" / "float" / "utc-offset" / 897 "language-tag" / x-type 899 ; Property, parameter and type names MUST be lowercase. Additional 900 ; semantic restrictions apply as described by this document and 901 ; RFC6350. 902 component-name = lowercase-name 903 property-name = lowercase-name 904 param-name = lowercase-name 905 x-type = lowercase-name 906 lowercase-name = 1*(%x61-7A / DIGIT / "-") 908 Appendix B. Examples 910 This section contains an example of a vCard object with its jCard 911 representation. 913 B.1. Example: vCard of the author of RFC6350 915 B.1.1. vCard Data 917 BEGIN:VCARD 918 VERSION:4.0 919 FN:Simon Perreault 920 N:Perreault;Simon;;;ing. jr,M.Sc. 921 BDAY:--0203 922 ANNIVERSARY:20090808T1430-0500 923 GENDER:M 924 LANG;PREF=1:fr 925 LANG;PREF=2:en 926 ORG;TYPE=work:Viagenie 927 ADR;TYPE=work:;Suite D2-630;2875 Laurier; 928 Quebec;QC;G1V 2M2;Canada 929 TEL;VALUE=uri;TYPE="work,voice";PREF=1:tel:+1-418-656-9254;ext=102 930 TEL;VALUE=uri;TYPE="work,cell,voice,video,text":tel:+1-418-262-6501 931 EMAIL;TYPE=work:simon.perreault@viagenie.ca 932 GEO;TYPE=work:geo:46.772673,-71.282945 933 KEY;TYPE=work;VALUE=uri: 934 http://www.viagenie.ca/simon.perreault/simon.asc 935 TZ:-0500 936 URL;TYPE=home:http://nomis80.org 937 END:VCARD 939 B.1.2. jCard Data 941 ["vcard", 942 [ 943 ["version", {}, "text", "4.0"], 944 ["fn", {}, "text", "Simon Perreault"], 945 ["n", {}, "text", "Perreault;Simon;;;ing. jr,M.Sc."], 946 ["bday", {}, "date", "--02-03"], 947 ["anniversary", {}, "date-time", "2009-08-08T14:30:00-0500"], 948 ["gender", {}, "text", "M"], 949 ["lang", { "pref": "1" }, "language-tag", "fr"], 950 ["lang", { "pref": "2" }, "language-tag", "en"], 951 ["org", { "type": "work" }, "text", "Viagenie"], 952 ["adr", 953 { "type": "work" }, 954 "text", 955 ";Suite D2-630;2875 Laurier;Quebec;QC;G1V 2M2;Canada" 956 ], 957 ["tel", 958 { "type": ["work", "voice"], "pref": "1" }, 959 "uri", 960 "tel:+1-418-656-9254;ext=102" 961 ], 962 ["tel", 963 { "type": ["work", "cell", "voice", "video", "text"] }, 964 "uri", 965 "tel:+1-418-262-6501" 966 ], 967 ["email", 968 { "type": "work" }, 969 "text", 970 "simon.perreault@viagenie.ca" 971 ], 972 ["geo", { "type": "work" }, "uri", "geo:46.772673,-71.282945"], 973 ["key", 974 { "type": "work" }, 975 "uri", 976 "http://www.viagenie.ca/simon.perreault/simon.asc" 977 ], 978 ["tz", {}, "utc-offset", "-05:00"], 979 ["url", { "type": "home" }, "uri", "http://nomis80.org"] 980 ] 981 ] 983 Appendix C. Open Issues (to be removed prior to publication as an RFC) 985 o [RFC6350] doesn't define any kind of stream for multiple vcard 986 elements. For similarity with the jCal draft, I have added a 987 "vcardstream". Is this wanted and does the name fit? (Maybe 988 rather "jcardstream" ?) 990 o During conversion to jCard, I have dropped "date-and-or-time" and 991 "timestamp" formats, since they can equally be represented by the 992 formats "date", "time" and "date-time". I have added guidelines 993 to Section 6, but there may be some situations I am unaware of 994 that make dropping these formats impossible. 996 o This document defines in Section 3.3.1.2, that grouped properties 997 are not to be handled differently than normal properties. This 998 was done for compatibility with the jCal draft to make it easier 999 for a parser to support both jCal and jCard. Another option would 1000 be to add a pseudo-property with the special type "group", the 1001 property name being the group name and the property value being an 1002 array of properties. Downside is that there is room for an extra 1003 set of parameters in the group container that does not serialize 1004 back to vCard. 1006 o There is some open discussion on the vcarddav and calsify lists 1007 about structured property and parameter values. The origin of 1008 this format comes from jCal, where structured values are very rare 1009 and processing the remaining ones requires a processing library 1010 anyway. Therefore neither structured property values nor 1011 parameter values were added. For jCard on the other hand, 1012 structured values appear quite often. I have come up with three 1013 possible options for structured property values: 1015 1. Use an array as the value, possibly with a null value for any 1016 empty structured property: foo;;bar becomes ["foo", null, 1017 "bar"] 1019 2. Use an object for key-value combinations. Downside is that 1020 the key may not always be known, and needs to be defined at 1021 least for standard properties. (i.e for N: "surnames", 1022 "given", "additional", "honor-prefix", "honor-suffix"). 1023 Object values themselves could also be array values, i.e 1024 multiple honorific prefixes. Upside is that it makes it very 1025 easy to access the values even without using a dedicated 1026 client library. 1028 3. Keep the property value as an opaque text and leave any 1029 splitting to client libraries. This makes it very simple to 1030 parse both iCalendar and vCard data into a similar format, but 1031 puts the burden of parsing the structured value on the client 1032 or client library. 1034 Also, there should be a mention of how multi-values inside a 1035 structured value should be handled. With the second approach, 1036 these could themselves be an array, similar to how this document 1037 currently defines multi-value parameters. 1039 Appendix D. Change History (to be removed prior to publication as an 1040 RFC) 1042 draft-kewisch-vcard-in-json-01 1044 * Added ABNF and improved references in date/time related 1045 sections 1047 * Changes to wording in "vCard Stream" section 1049 * Changes to wording about VALUE parameter when converting to 1050 vCard 1052 * Corrected missing "type" parameter and separator in example 1054 * Minor wording corrections 1056 Author's Address 1058 Philipp Kewisch 1059 Mozilla Corporation 1060 650 Castro Street, Suite 300 1061 Mountain View, CA 94041 1062 USA 1064 EMail: mozilla@kewis.ch 1065 URI: http://www.mozilla.org/