idnits 2.17.1 draft-ietf-jcardcal-jcard-00.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 26, 2013) is 4049 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 (-10) exists of draft-ietf-jcardcal-jcal-00 -- 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 26, 2013 5 Expires: September 27, 2013 7 jCard: The JSON format for vCard 8 draft-ietf-jcardcal-jcard-00 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 27, 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.ietf-jcardcal-jcal]. 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.ietf-jcardcal-jcal] 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 [I-D.ietf-jcardcal-jcal]. 289 Example: 291 ["vcard", 292 [ 293 ["groupname.email", {}, "text", "johndoe@example.org"], 294 ... 295 ], 296 ... 297 ] 299 3.4. Parameters (RFC6350 section 5) 301 Property parameters are represented as a JSON object where each key- 302 value pair represents the vCard parameter name and its value. The 303 name of the parameter MUST be in lowercase, the original case of the 304 parameter value MUST be preserved. For example, the "LANG" property 305 parameter is represented in jCard by the "lang" key. Any new vCard 306 parameters added in the future will be converted in the same way. 308 Example: 310 ["vcard", 311 [ 312 ["role", { "lang": "tr" }, "text", "roca"], 313 ... 314 ], 315 ... 316 ] 318 3.4.1. VALUE parameter 320 vCard defines a "VALUE" property parameter (Section 5.2 of 321 [RFC6350]). This property parameter MUST NOT be added to the 322 parameters object. Instead, the value type is always explicitly 323 mentioned in the third element of the array describing the property. 324 Thus, when converting from vCard to jCard, any "VALUE" property 325 parameters are skipped. When converting from jCard into vCard, the 326 appropriate "VALUE" property parameter MUST be included in the vCard 327 property if the value type is not the default value type for that 328 property. 330 3.4.2. Multi-value Parameters 332 In [RFC6350], some parameters allow using a COMMA-separated list of 333 values. To ease processing in jCard, the value to such parameters 334 MUST be represented in an array containing the separated values. The 335 array elements MUST be string values. Single-value parameters SHOULD 336 be represented using a single string value, but an array with one 337 element MAY also be used. An example for a such parameter is the 338 vCard "SORT-AS" parameter, more such parameters may be added in 339 extensions. 341 DQUOTE characters used to encapsulate the separated values MUST NOT 342 be added to the jCard parameter value. 344 Example 1: 346 ["vcard", 347 [ 348 ["n", 349 { "sort-as": ["Harten", "Rene"] }, 350 "text", 351 "van der Harten;Rene,J.;Sir;R.D.O.N." 352 ], 353 ["fn", {}, "text", "Rene van der Harten"] 354 ... 355 ], 356 ... 357 ] 359 3.5. Values (RFC6350 section 4) 361 The type of a vCard value is explicitly mentioned in the third 362 element of the array describing a jCard property. The actual values 363 of the property can be found in the fourth and following elements of 364 the array. 366 3.5.1. Text (RFC6350 section 4.1) 368 Description: vCard "TEXT" property values are represented by a 369 property with the type identifier "text". The value elements are 370 JSON strings. 372 Example: 374 ... 375 ["kind", {}, "text", "group"], 376 ... 378 3.5.2. URI (RFC6350 section 4.2) 380 Description: vCard "URI" property values are represented by a 381 property with the type identifier "uri". The value elements are 382 JSON strings. 384 Example: 386 ... 387 ["source", {}, "uri", "ldap://ldap.example.com/cn=babs%20jensen"], 388 ... 390 3.5.3. Date (RFC6350 section 4.3.1) 392 Description: vCard "DATE" property values are represented by a 393 property with the type identifier "date". The value elements are 394 JSON strings with the same date value specified by [RFC6350], but 395 formatted using the [ISO.8601.2004] complete representation, 396 extended format. The same date format restrictions regarding 397 reduced accuracy, truncated representation and expanded 398 representation noted in [RFC6350] Section 4.1.2.3 apply. Whenever 399 the extended format is not applicable, the basic format is to be 400 used. 402 ABNF Schema: 404 date-complete = year "-" month "-" day ;YYYY-MM-DD 406 date-noreduc = date-complete 407 / "--" month "-" day; --MM-DD 408 / "---" day; ---DDD 410 date = date-noreduc 411 / year; YYYY 412 / year "-" month ; YYYY-MM 413 / "--" month; --MM 415 Examples: 417 ... 418 ["bday", {}, "date", "1985-04-12"], 419 ["bday", {}, "date", "1985-04"], 420 ["bday", {}, "date", "1985"], 421 ["bday", {}, "date", "--0412"], 422 ["bday", {}, "date", "---12"], 423 ... 425 3.5.4. Time (RFC6350 section 4.3.2) 427 Description: vCard "TIME" property values are represented by a 428 property with the type identifier "time". The value elements are 429 JSON strings with the same time value specified by [RFC6350], but 430 formatted using the [ISO.8601.2004] complete representation, 431 extended format. The same date format restrictions regarding 432 reduced accuracy, decimal fraction and truncated representation 433 noted in [RFC6350] Section 4.3.2 apply. Whenever the extended 434 format is not applicable, the basic format is to be used. The 435 seconds value of 60 MUST only be used to account for positive 436 "leap" seconds and the midnight hour is always represented by 00, 437 never 24. Fractions of a second are not supported by this format. 438 Contrary to [I-D.ietf-jcardcal-jcal], UTC offsets are permitted 439 within a time value. 441 ABNF Schema: 443 time-notrunc = hour [":" minute [":" second]] [zone] 445 time = time-notrunc 446 / "-" minute ":" second [zone]; -mm:ss 447 / "-" minute [zone]; -mm 448 / "--" second [zone]; --ss 450 Examples: 452 ... 453 ["x-time-local", {}, "time", "12:30:00"], 454 ["x-time-utc", {}, "time", "12:30:00Z"], 455 ["x-time-offset", "time", "12:30:00-0800"], 456 ["x-time-reduced", "time", "23"], 457 ["x-time-truncated", "time", "-30"], 458 ... 460 3.5.5. Date-Time (RFC6350 section 4.3.3) 462 Description: vCard "DATE-TIME" property values are represented by a 463 property with the type identifier "date-time". The value elements 464 are JSON strings with the same date value specified by [RFC6350], 465 but formatted using the [ISO.8601.2004] complete representation, 466 extended format. The same restrictions with respect to leap 467 seconds, fractions of a second and UTC offsets as in Section 3.5.4 468 apply. Just as in [RFC6350], truncation of the date part is 469 permitted. 471 Example: 473 ... 474 ["anniversary", {}, "date-time", "2013-02-14T12:30:00"], 475 ["anniversary", {}, "date-time", "2013-01-10T19:00:00Z"], 476 ["anniversary", {}, "date-time", "2013-08-15T09:45:00+0100"], 477 ["anniversary", {}, "date-time", "---15T09:45:00+0100"], 478 ... 480 3.5.6. Date and/or Time (RFC6350 section 4.3.4) 482 Description: jCard has no direct equivalent to vCard's "DATE-AND-OR- 483 TIME" property value data type. Instead, the specified date, 484 date-time or time format MUST be detected and the property MUST be 485 represented by a property with the detected type identifier. See 486 Section 6 for more information on how conversion between jCard and 487 vCard should be handled. 489 3.5.7. Timestamp (RFC6350 section 4.3.5) 491 Description: jCard has no direct equivalent to vCard's "TIMESTAMP" 492 property value data type. Instead, the specified complete date 493 and time of day combination MUST be represented by a property with 494 the "date-time" identifier. See Section 6 for more information on 495 how conversion between jCard and vCard should be handled. 497 3.5.8. Boolean (RFC6350 section 4.4) 499 Description: vCard "BOOLEAN" property values are represented by a 500 property with the type identifier "boolean". The value element is 501 a JSON boolean value. 503 Example: 505 ... 506 ["x-non-smoking", {}, "boolean", true], 507 ... 509 3.5.9. Integer (RFC6350 section 4.5) 511 Description: vCard "INTEGER" property values are represented by a 512 property with the type identifier "integer". The value elements 513 are JSON primitive number values. 515 Examples: 517 ... 518 ["x-karma-points", {}, "integer", 42], 519 ... 521 3.5.10. Float (RFC6350 section 4.6) 523 Description: vCard "FLOAT" property values are represented by a 524 property with the type identifier "float". The value elements are 525 JSON primitive number values. 527 Example: 529 ... 530 ["x-grade", {}, "float", 1.3], 531 ... 533 3.5.11. UTC Offset (RFC6350 section 4.7) 535 Description: vCard "UTC-OFFSET" property values are represented by a 536 property with the type identifier "utc-offset". The value 537 elements are JSON strings with the same UTC offset value specified 538 by [RFC6350], with the exception that the hour and minute 539 components are separated by a ":" character, for consistency with 540 the [ISO.8601.2004] timezone offset, extended format. 542 Example: 544 ... 545 // Note: [RFC6350] mentions use of utc-offset 546 // for the TZ property as NOT RECOMMENDED 547 ["tz", {}, "utc-offset", "-05:00"], 548 .. 550 3.5.12. Language Tag (RFC6350 section 4.8) 552 Description: vCard "LANGUAGE-TAG" property values are represented by 553 a property with the type identifier "language-tag". The value 554 elements are JSON strings containing a single language-tag, as 555 defined in [RFC5646]. 557 Example: 559 ... 560 ["lang", {}, "language-tag", "de"], 561 .. 563 3.6. Extensions (RFC6350 section 6.10) 565 vCard extension properties and property parameters (those with an 566 "X-" prefix in their name) are handled in the same way as other 567 properties and property parameters: the property is represented by an 568 array, the property parameter represented by an object. The property 569 or parameter name uses the same name as for the vCard extension, but 570 in lowercase. For example, the "X-FOO" property in vCard turns into 571 the "x-foo" jCard property. See Section 5 for how to deal with 572 default values for unrecognized extension properties or property 573 parameters. 575 4. Converting from jCard into vCard 577 When converting property and property parameter values, the names 578 SHOULD be converted to uppercase. Although vCard names are case 579 insensitive, common practice is to keep them all uppercase following 580 the actual definitions in [RFC6350]. 582 Backslash escaping and line folding MUST be applied to the resulting 583 vCard data as required by [RFC6350]. 585 When converting to vCard, the VALUE parameter MUST be added to 586 properties whose default value type is unknown. The VALUE parameter 587 SHOULD NOT be added to properties using the default value type. 589 5. Handling Unrecognized Properties or Parameters 591 In vCard, properties have a default value type specified by their 592 definition, e.g. "BDAY"'s value type is "date-and-or-time", but it 593 can also be reset to a single "text" value. When a property uses its 594 default value type, the "VALUE" property parameter does not need to 595 be specified on the property. 597 When new properties are defined or "X-" properties used, a vCard to 598 jCard converter might not recognize them, and not know what the 599 appropriate default value types are, yet they need to be able to 600 preserve the values. A similar issue arises for unrecognized 601 property parameters. As a result, the following rules are applied 602 when dealing with unrecognized properties and property parameters: 604 o When converting vCard into jCard: 606 * Any property that does not include a "VALUE" property parameter 607 and whose default value type is not known, MUST be converted to 608 a string object. The content of that string is the unprocessed 609 value text. 611 * Any unrecognized property parameter MUST be converted to a 612 string value, with its content set to the property parameter 613 value text, treated as if it were a "TEXT" value. 615 o When converting jCard into vCard: 617 * Since jCard always explicitly specifies the value type, it can 618 always be converted to vCard using the VALUE parameter. 620 * If the value type specified in jCard matches the default value 621 type in vCard, the VALUE parameter SHOULD be omitted. 623 Example: The following is an example of an unrecognized vCard 624 property (that uses an "URI" value as its default), and the 625 equivalent jCard representation of that property. 627 vCard: 629 X-COMPLAINT-URI:mailto:abuse@example.org 631 jCard: 633 ... 634 ["x-complaint-uri", {}, "text", "mailto:abuse@example.org"], 635 ... 637 Example: The following is an example of a jCard property (where the 638 corresponding vCard property uses a "INTEGER" value as its default), 639 and the equivalent vCard representation of that property. It is 640 assumed that the parser has knowledge of the default data type for 641 the "x-karma-points" property. 643 jCard: 645 ... 646 ["x-karma-points", {}, "integer", 95], 647 ... 649 vCard: 651 X-KARMA-POINTS:95 653 Example: The following is an example of an unrecognized vCard 654 property parameter (that uses a "FLOAT" value as its default) 655 specified on a recognized vCard property, and the equivalent jCard 656 representation of that property and property parameter. 658 vCard: 660 GENDER;X-PROBABILITY=0.8:M 662 jCard: 664 ... 665 ["gender", { "x-probability": "0.8" }, "text", "M"], 666 ... 668 6. Conversion of Date and Time Related Data Types 670 [RFC6350] defines the data types DATE, DATE-TIME, TIME, DATE-AND-OR- 671 TIME and TIMESTAMP, covering various aspects of dates and times. As 672 jCard is more "strongly typed", some of these types have been 673 consolidated. This section aims to aid conversion between jCard and 674 vCard and vice versa. 676 Regardless of the date/time related property converted, jCard and 677 vCard use different representations of the [ISO.8601.2004] format. 678 The date format MUST be adjusted during conversion. 680 6.1. Conversion from jCard to vCard 682 o If the property type of the jCard property matches the property's 683 default type, the VALUE parameter MUST NOT be added to the vCard 684 property. 686 o For property types "date-and-or-time" or "timestamp", the property 687 value MUST be converted to a permitted date and/or time format as 688 specified in [RFC6350] Section 4.3.4 and 4.3.5 and the VALUE 689 parameter MUST NOT be added to the vCard property. If a permitted 690 conversion cannot be done, the VALUE parameter must be added with 691 the closest available date/time format identifier. 693 o If the default type is unknown or the jCal property type does not 694 match the default type, the VALUE parameter MUST be specified. 696 6.2. Conversion from vCard to jCard 698 o If the parser knows the default type of the property and it is one 699 of "DATE", "DATE-TIME" or "TIME", the properties can be directly 700 converted following the guidelines of the respective format type 701 in this document. 703 o For the property type "date-and-or-time", the parser SHOULD detect 704 if it is handling either a date, a time, or a date-time and use 705 the respective format identifier in jCard. 707 o For the property type "timestamp", the parser MUST use the format 708 type identifier "date-time" in the jCard property. 710 o If the (default) property type is unknown, the property value MUST 711 be treated as opaque text and the "text" format type identifier 712 MUST be used. 714 7. Security Considerations 716 For security considerations specific to calendar data, see Section 9 717 of [RFC6350]. Since this specification is a mapping from vCard, no 718 new security concerns are introduced related to calendar data. 720 The use of JSON as a format does have security risks. Section 7 of 721 [RFC4627] discusses these risks. 723 8. IANA Considerations 725 This document defines a MIME media type for use with vCard in JSON 726 data. This media type SHOULD be used for the transfer of calendaring 727 data in JSON. 729 Type name: application 731 Subtype name: vcard+json 733 Required parameters: none 735 Optional parameters: version as defined for the text/vcard media 736 type in [RFC6350]. 738 Encoding considerations: Same as encoding considerations of 739 application/json as specified in [RFC4627]. 741 Security considerations: See Section 7. 743 Interoperability considerations: This media type provides an 744 alternative format for vCard data based on JSON. 746 Published specification: This specification. 748 Applications which use this media type: Applications that currently 749 make use of the text/vcard media type can use this as an 750 alternative. Similarly, Applications that use the application/ 751 json media type to transfer directory data can use this to further 752 specify the content. 754 Person & email address to contact for further information: 755 vcarddav@ietf.org 757 Intended usage: COMMON 759 Restrictions on usage: There are no restrictions on where this media 760 type can be used. 762 Author: See the "Author's Address" section of this document. 764 Change controller: IETF 766 9. Acknowledgments 768 The author would like to thank the following for their valuable 769 contributions: Cyrus Daboo, Mike Douglass, William Gill, Erwin Rehme, 770 and Dave Thewlis. This specification originated from the work of the 771 XML-JSON technical committee of the Calendaring and Scheduling 772 Consortium. 774 10. References 776 10.1. Normative References 778 [I-D.ietf-jcardcal-jcal] Kewisch, P., Daboo, C., and M. Douglass, 779 "jCal: The JSON format for iCalendar", 780 draft-ietf-jcardcal-jcal-00 (work in 781 progress), March 2013. 783 [ISO.8601.2004] International Organization for 784 Standardization, ""Data elements and 785 interchange formats -- Information 786 interchange -- Representation of dates and 787 times"", ISO 8601, 12 2004. 789 [RFC2119] Bradner, S., "Key words for use in RFCs to 790 Indicate Requirement Levels", BCP 14, 791 RFC 2119, March 1997. 793 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF 794 for Syntax Specifications: ABNF", STD 68, 795 RFC 5234, January 2008. 797 [RFC5545] Desruisseaux, B., "Internet Calendaring and 798 Scheduling Core Object Specification 799 (iCalendar)", RFC 5545, September 2009. 801 [RFC5646] Phillips, A. and M. Davis, "Tags for 802 Identifying Languages", BCP 47, RFC 5646, 803 September 2009. 805 [RFC6321] Daboo, C., Douglass, M., and S. Lees, 806 "xCal: The XML Format for iCalendar", 807 RFC 6321, August 2011. 809 [RFC6350] Perreault, S., "vCard Format 810 Specification", RFC 6350, August 2011. 812 10.2. Informative References 814 [RFC4627] Crockford, D., "The application/json Media 815 Type for JavaScript Object Notation 816 (JSON)", RFC 4627, July 2006. 818 [calconnect-artifacts] The Calendaring and Scheduling Consortium, 819 "Code Artifacts and Schemas", 820 . 823 Appendix A. ABNF Schema 825 Below is an ABNF schema as per [RFC5234] for vCard in JSON. ABNF 826 Symbols not described here are taken from [RFC4627]. The schema is 827 non-normative and given for reference only. 829 The numeric section numbers given in the comments refer to section in 830 [RFC6350]. Additional semantic restrictions apply, especially 831 regarding the allowed properties and sub-components per component. 832 Details on these restrictions can be found in this document and 833 [RFC6350]. 835 Additional schemas may be available on the internet at 836 [calconnect-artifacts]. 838 ; A vCard Stream is an array with the first element being the 839 ; string "vcardstream". All remaining elements are jcardobjects. 840 jcardstream = begin-array 841 DQUOTE "vcardstream" DQUOTE 842 *(value-separator jcardobject) 843 end-array 845 jcardobject = component 847 ; A jCard object consists of the name string "vcard" and a properties 848 ; array. Restrictions to which properties and may be specified are to 849 ; be taken from RFC6350. 851 jcardobject = begin-array 852 DQUOTE component-name DQUOTE value-separator 853 properties-array 854 end-array 856 ; A jCard property consists of the name string, parameters object, 857 ; type string and one or more values as specified in this document. 858 property = begin-array 859 DQUOTE property-name DQUOTE value-separator 860 params-object value-separator 861 DQUOTE type-name DQUOTE 862 propery-value *(value-separator property-value) 863 end-array 864 properties-array = begin-array 865 [ property *(value-separator property) ] 866 end-array 868 ; Property values depend on the type-name. Aside from the value types 869 ; mentioned here, extensions may make use of other JSON value types. 870 property-value = string / number / boolean 872 ; The jCard params-object is a JSON object which follows the semantic 873 ; guidelines described in this document. 874 params-object = begin-object 875 [ params-member *(value-separator params-member) ] 876 end-object 877 params-member = DQUOTE param-name DQUOTE name-separator param-value 878 param-value = string 880 ; The type MUST be a valid type as described by this document. New 881 ; value types can be added by extensions. 882 type-name = "text" / "uri" / "date" / "time" / "date-time" / 883 "boolean" / "integer" / "float" / "utc-offset" / 884 "language-tag" / x-type 886 ; Property, parameter and type names MUST be lowercase. Additional 887 ; semantic restrictions apply as described by this document and 888 ; RFC6350. 889 component-name = lowercase-name 890 property-name = lowercase-name 891 param-name = lowercase-name 892 x-type = lowercase-name 893 lowercase-name = 1*(%x61-7A / DIGIT / "-") 895 Appendix B. Examples 897 This section contains an example of a vCard object with its jCard 898 representation. 900 B.1. Example: vCard of the author of RFC6350 902 B.1.1. vCard Data 904 BEGIN:VCARD 905 VERSION:4.0 906 FN:Simon Perreault 907 N:Perreault;Simon;;;ing. jr,M.Sc. 908 BDAY:--0203 909 ANNIVERSARY:20090808T1430-0500 910 GENDER:M 911 LANG;PREF=1:fr 912 LANG;PREF=2:en 913 ORG;TYPE=work:Viagenie 914 ADR;TYPE=work:;Suite D2-630;2875 Laurier; 915 Quebec;QC;G1V 2M2;Canada 916 TEL;VALUE=uri;TYPE="work,voice";PREF=1:tel:+1-418-656-9254;ext=102 917 TEL;VALUE=uri;TYPE="work,cell,voice,video,text":tel:+1-418-262-6501 918 EMAIL;TYPE=work:simon.perreault@viagenie.ca 919 GEO;TYPE=work:geo:46.772673,-71.282945 920 KEY;TYPE=work;VALUE=uri: 921 http://www.viagenie.ca/simon.perreault/simon.asc 922 TZ:-0500 923 URL;TYPE=home:http://nomis80.org 924 END:VCARD 926 B.1.2. jCard Data 928 ["vcard", 929 [ 930 ["version", {}, "text", "4.0"], 931 ["fn", {}, "text", "Simon Perreault"], 932 ["n", {}, "text", "Perreault;Simon;;;ing. jr,M.Sc."], 933 ["bday", {}, "date", "--02-03"], 934 ["anniversary", {}, "date-time", "2009-08-08T14:30:00-0500"], 935 ["gender", {}, "text", "M"], 936 ["lang", { "pref": "1" }, "language-tag", "fr"], 937 ["lang", { "pref": "2" }, "language-tag", "en"], 938 ["org", { "type": "work" }, "text", "Viagenie"], 939 ["adr", 940 { "type": "work" }, 941 "text", 942 ";Suite D2-630;2875 Laurier;Quebec;QC;G1V 2M2;Canada" 943 ], 944 ["tel", 945 { "type": ["work", "voice"], "pref": "1" }, 946 "uri", 947 "tel:+1-418-656-9254;ext=102" 948 ], 949 ["tel", 950 { "type": ["work", "cell", "voice", "video", "text"] }, 951 "uri", 952 "tel:+1-418-262-6501" 953 ], 954 ["email", 955 { "type": "work" }, 956 "text", 957 "simon.perreault@viagenie.ca" 958 ], 959 ["geo", { "type": "work" }, "uri", "geo:46.772673,-71.282945"], 960 ["key", 961 { "type": "work" }, 962 "uri", 963 "http://www.viagenie.ca/simon.perreault/simon.asc" 964 ], 965 ["tz", {}, "utc-offset", "-05:00"], 966 ["url", { "type": "home" }, "uri", "http://nomis80.org"] 967 ] 968 ] 970 Appendix C. Open Issues (to be removed prior to publication as an RFC) 972 o [RFC6350] doesn't define any kind of stream for multiple vcard 973 elements. For similarity with the jCal draft, I have added a 974 "vcardstream". Is this wanted and does the name fit? (Maybe 975 rather "jcardstream" ?) 977 o During conversion to jCard, I have dropped "date-and-or-time" and 978 "timestamp" formats, since they can equally be represented by the 979 formats "date", "time" and "date-time". I have added guidelines 980 to Section 6, but there may be some situations I am unaware of 981 that make dropping these formats impossible. 983 o This document defines in Section 3.3.1.2, that grouped properties 984 are not to be handled differently than normal properties. This 985 was done for compatibility with the jCal draft to make it easier 986 for a parser to support both jCal and jCard. Another option would 987 be to add a pseudo-property with the special type "group", the 988 property name being the group name and the property value being an 989 array of properties. Downside is that there is room for an extra 990 set of parameters in the group container that does not serialize 991 back to vCard. 993 o There is some open discussion on the vcarddav and calsify lists 994 about structured property and parameter values. The origin of 995 this format comes from jCal, where structured values are very rare 996 and processing the remaining ones requires a processing library 997 anyway. Therefore neither structured property values nor 998 parameter values were added. For jCard on the other hand, 999 structured values appear quite often. I have come up with three 1000 possible options for structured property values: 1002 1. Use an array as the value, possibly with a null value for any 1003 empty structured property: foo;;bar becomes ["foo", null, 1004 "bar"] 1006 2. Use an object for key-value combinations. Downside is that 1007 the key may not always be known, and needs to be defined at 1008 least for standard properties. (i.e for N: "surnames", 1009 "given", "additional", "honor-prefix", "honor-suffix"). 1010 Object values themselves could also be array values, i.e 1011 multiple honorific prefixes. Upside is that it makes it very 1012 easy to access the values even without using a dedicated 1013 client library. 1015 3. Keep the property value as an opaque text and leave any 1016 splitting to client libraries. This makes it very simple to 1017 parse both iCalendar and vCard data into a similar format, but 1018 puts the burden of parsing the structured value on the client 1019 or client library. 1021 Also, there should be a mention of how multi-values inside a 1022 structured value should be handled. With the second approach, 1023 these could themselves be an array, similar to how this document 1024 currently defines multi-value parameters. 1026 Appendix D. Change History (to be removed prior to publication as an 1027 RFC) 1029 draft-kewisch-vcard-in-json-01 1031 * Added ABNF and improved references in date/time related 1032 sections 1034 * Changes to wording in "vCard Stream" section 1036 * Changes to wording about VALUE parameter when converting to 1037 vCard 1039 * Corrected missing "type" parameter and separator in example 1041 * Minor wording corrections 1043 draft-ietf-jcardcal-jcard-00 1045 * Pubication as a WG draft 1047 Author's Address 1049 Philipp Kewisch 1050 Mozilla Corporation 1051 650 Castro Street, Suite 300 1052 Mountain View, CA 94041 1053 USA 1055 EMail: mozilla@kewis.ch 1056 URI: http://www.mozilla.org/