idnits 2.17.1 draft-ietf-jcardcal-jcard-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- 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 (October 15, 2013) is 3838 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) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) == Outdated reference: A later version (-10) exists of draft-ietf-jcardcal-jcal-00 == Outdated reference: A later version (-06) exists of draft-sheffer-running-code-02 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 JSON data formats for vCard and iCalendar P. Kewisch 3 Internet-Draft Mozilla 4 Intended status: Standards Track October 15, 2013 5 Expires: April 18, 2014 7 jCard: The JSON format for vCard 8 draft-ietf-jcardcal-jcard-07 10 Abstract 12 This specification defines "jCard", a JSON format for vCard data. 13 The vCard data format is a text format for representing and 14 exchanging information about individuals and other entities, for 15 example telephone numbers, email addresses, structured names and 16 delivery addresses. JSON is a lightweight, text-based, language- 17 independent data interchange format commonly used in internet 18 applications. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on April 18, 2014. 37 Copyright Notice 39 Copyright (c) 2013 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 56 3. Converting from vCard to jCard . . . . . . . . . . . . . . . 4 57 3.1. Pre-processing . . . . . . . . . . . . . . . . . . . . . 4 58 3.2. jCard Object and Syntactic Entities (RFC6350 section 59 6.1.1 and 6.1.2) . . . . . . . . . . . . . . . . . . . . 5 60 3.3. Properties (RFC6350 section 6) . . . . . . . . . . . . . 5 61 3.3.1. Special Cases for Properties . . . . . . . . . . . . 7 62 3.3.1.1. The VERSION Property . . . . . . . . . . . . . . 7 63 3.3.1.2. Grouping of Properties . . . . . . . . . . . . . 7 64 3.3.1.3. Structured Property Values . . . . . . . . . . . 8 65 3.4. Parameters (RFC6350 Section 5) . . . . . . . . . . . . . 10 66 3.4.1. VALUE parameter . . . . . . . . . . . . . . . . . . . 10 67 3.4.2. Multi-value Parameters . . . . . . . . . . . . . . . 11 68 3.5. Values (RFC6350 Section 4) . . . . . . . . . . . . . . . 11 69 3.5.1. Text (RFC6350 Section 4.1) . . . . . . . . . . . . . 12 70 3.5.2. URI (RFC6350 Section 4.2) . . . . . . . . . . . . . . 12 71 3.5.3. Date (RFC6350 Section 4.3.1) . . . . . . . . . . . . 12 72 3.5.4. Time (RFC6350 Section 4.3.2) . . . . . . . . . . . . 13 73 3.5.5. Date-Time (RFC6350 Section 4.3.3) . . . . . . . . . . 15 74 3.5.6. Date and/or Time (RFC6350 Section 4.3.4) . . . . . . 16 75 3.5.7. Timestamp (RFC6350 Section 4.3.5) . . . . . . . . . . 16 76 3.5.8. Boolean (RFC6350 Section 4.4) . . . . . . . . . . . . 17 77 3.5.9. Integer (RFC6350 Section 4.5) . . . . . . . . . . . . 17 78 3.5.10. Float (RFC6350 Section 4.6) . . . . . . . . . . . . . 18 79 3.5.11. UTC Offset (RFC6350 Section 4.7) . . . . . . . . . . 18 80 3.5.12. Language Tag (RFC6350 Section 4.8) . . . . . . . . . 18 81 3.6. Extensions (RFC6350 Section 6.10) . . . . . . . . . . . . 19 82 4. Converting from jCard into vCard . . . . . . . . . . . . . . 19 83 5. Handling Unrecognized Properties or Parameters . . . . . . . 19 84 5.1. Converting vCard into jCard . . . . . . . . . . . . . . . 20 85 5.2. Converting jCard into vCard . . . . . . . . . . . . . . . 20 86 5.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 20 87 6. Implementation Status (to be removed prior to publication as 88 an RFC) . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 89 7. Security Considerations . . . . . . . . . . . . . . . . . . . 22 90 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 91 8.1. GROUP vCard Parameter . . . . . . . . . . . . . . . . . . 24 92 8.2. UNKNOWN vCard Value Data Type . . . . . . . . . . . . . . 25 93 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25 94 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 95 10.1. Normative References . . . . . . . . . . . . . . . . . . 26 96 10.2. Informative References . . . . . . . . . . . . . . . . . 26 98 Appendix A. ABNF Schema . . . . . . . . . . . . . . . . . . . . 27 99 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 28 100 B.1. Example: vCard of the author of RFC6350 . . . . . . . . . 29 101 B.1.1. vCard Data . . . . . . . . . . . . . . . . . . . . . 29 102 B.1.2. jCard Data . . . . . . . . . . . . . . . . . . . . . 29 103 Appendix C. Change History (to be removed prior to publication 104 as an RFC) . . . . . . . . . . . . . . . . . . . . . 30 105 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 32 107 1. Introduction 109 The vCard data format [RFC6350] provides for the capture and exchange 110 of information normally stored within an address book or directory 111 application. The vCard format has gone through multiple revisions, 112 most recently vCard 4. 114 As certain similarities exist between vCard and the iCalendar data 115 format [RFC5545], there is also an effort to define a JSON-based data 116 format for calendar information called jCal [I-D.ietf-jcardcal-jcal] 117 that parallels the format defined in this specification. The term 118 JSON describes the JavaScript Object Notation defined in [RFC4627]. 120 The purpose of this specification is to define "jCard", a JSON format 121 for vCard data. One main advantage to using a JSON-based format over 122 the classic vCard format is easier processing for JavaScript based 123 widgets and libraries, especially in the scope of web-based 124 applications. 126 The key design considerations are essentially the same as those for 127 [I-D.ietf-jcardcal-jcal] and [RFC6321], that is: 129 Round-tripping (converting a vCard instance to jCard and back) 130 will give the same semantic result as the starting point. For 131 example, all components, properties and property parameters are 132 guaranteed to be preserved. 134 Ordering of elements and case of property and parameter names will 135 not necessarily be preserved. 137 The vCard data semantics are to be preserved, allowing a simple 138 consumer to easily browse the data in jCard. A full understanding 139 of vCard is still required in order to modify and/or fully 140 comprehend the directory data. 142 Extensions to the underlying vCard specification must not lead to 143 requiring an update to jCard. 145 2. Conventions Used in This Document 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 149 document are to be interpreted as described in [RFC2119]. 151 The underlying format used for jCard is JSON. Consequently, the 152 terms "object" and "array" as well as the four primitive types 153 (strings, numbers, booleans, and null) are to be interpreted as 154 described in Section 1 of [RFC4627]. 156 Some examples in this document contain "partial" JSON documents used 157 for illustrative purposes. In these examples, three periods "..." 158 are used to indicate a portion of the document that has been removed 159 for compactness. 161 3. Converting from vCard to jCard 163 This section describes how vCard objects are converted to jCard using 164 a simple mapping between the vCard data model and JSON elements. 166 In [RFC6350], vCard objects are comprised of a set of "properties", 167 "parameters" and "values". The top level of a vCard object contains 168 "properties". A "property" has a "value" and a set of zero or more 169 "parameters". Each of these entities have a representation in jCard, 170 defined in the following sections. The representation of a vCard 171 object in JSON will be named "jCard object" throughout this document. 173 3.1. Pre-processing 175 vCard uses a line folding mechanism to limit lines of data to a 176 maximum line length (typically 75 octets) to ensure maximum 177 likelihood of preserving data integrity as it is transported via 178 various means (e.g., email) - see Section 3.2 of [RFC6350]. 180 vCard data uses an "escape" character sequence for text values and 181 property parameter values. See Section 3.4 of [RFC6350] as well as 182 [RFC6868]. 184 When converting from vCard to jCard, first vCard lines MUST be 185 unfolded. Afterwards, any vCard escaping MUST be unescaped. Finally 186 JSON escaping (e.g., for control characters) MUST be applied. 188 The reverse order applies when converting from jCard to vCard. 189 First, JSON escaping MUST be unescaped. Afterwards, vCard escaping 190 MUST be applied. Finally, long lines SHOULD be folded as described 191 in [RFC6350]. 193 One key difference in the formatting of values used in vCard and 194 jCard is that in jCard the specification uses date/time values 195 aligned with the extended format of [ISO.8601.2004], which is more 196 commonly used in internet applications that make use of the JSON 197 format. The sections of this document describing the various date 198 and time formats contain more information on the use of the complete 199 representation, reduced accuracy or truncated representation. 201 3.2. jCard Object and Syntactic Entities (RFC6350 section 6.1.1 and 202 6.1.2) 204 In [RFC6350] Section 6.1.1 and 6.1.2, the "BEGIN" and "END" 205 properties delimit a syntactic vCard entity. In jCard, each 206 syntactic entity is represented by an array with two elements and is 207 named "jCard object". The first element is the string "vcard", the 208 second element is an array of jCard properties as described in 209 Section 3.3, belonging to the entity. 211 Although [RFC6350] defines BEGIN and END to be properties, they MUST 212 NOT appear as properties of the jCard. Instead, the jCard object is 213 sufficient to define a vCard entity. When converting from jCard to 214 vCard, the BEGIN and END properties MUST be added to enclose the 215 properties of the jCard object. 217 Example: 219 ["vcard", [ 220 /* Add properties in place of this comment */ 221 ] 222 ] 224 Consumers of this format wishing to define content that can represent 225 multiple jCard objects within the same JSON document can use a simple 226 JSON array, each element being a single jCard object. 228 3.3. Properties (RFC6350 section 6) 230 Each individual vCard property is represented in jCard by an array 231 with three fixed elements, followed by one or more additional 232 elements, depending on if the property is a multi-value property as 233 described in Section 3.3 of [RFC6350]. 235 The array consists of the following fixed elements: 237 1. The name of the property, as a lowercase string. The vCard 238 format specifies that property names are case-insensitive, and 239 recommends that they be rendered in uppercase. In jCard, they 240 MUST be in lowercase. 242 2. An object containing the parameters as described in Section 3.4. 243 If the property has no parameters, an empty object is used to 244 represent that. 246 3. The type identifier string of the value, in lowercase. It is 247 important that parsers check this to determine the data type of 248 the value, and that they do not rely on assumptions. For 249 example, for structured values the data type will be "array". 251 The remaining elements of the array are used for one or more values 252 of the property. For single-value properties, the array has exactly 253 four elements; for multi-valued properties, each value is another 254 element, and there can be any number of additional elements. 256 In the following example, the "categories" property is multi-valued 257 and has two values, while all other properties are single-valued: 259 ["vcard", 260 [ 261 ["version", {}, "text", "4.0"], 262 ["fn", {}, "text", "John Doe"], 263 ["gender", {}, "text", "M"], 264 ["categories", {}, "text", "computers", "cameras"], 265 ... 266 ] 267 ] 269 As described in Section 3.3.1.3, a property value may be a structured 270 property value, in which case it is represented as an array 271 encapsulated in the array that represents the overall property. 273 Strictly speaking, this means that the property value is not 274 represented in the format indicated by the type identifier, but by an 275 array instead. However, the values inside the encapsulated array are 276 of the format identified by the type identifier. 278 The above also holds for multi-valued properties, where some of the 279 values may be structured property values, and therefore are 280 represented as an encapsulated array. 282 A special case is where a value in an encapsulated array consists of 283 multiple components itself, in which case it is represented as yet 284 another nested array, with elements matching the value type. 285 Section 3.3.1.3 describes this in more detail. 287 The above illustrates the importance for the parser to check the 288 format of each property value, as it might either directly match the 289 value type, or it might be a structured value where nested sub- 290 elements match the value type. 292 3.3.1. Special Cases for Properties 294 This section describes some properties that have special handling 295 when converting to jCard. 297 3.3.1.1. The VERSION Property 299 The vCard format specification [RFC6350] defines the VERSION property 300 to be mandatory. The "version" property MUST be represented in the 301 corresponding jCard component, with the same value as in the vCard. 302 vCards that conform to RFC 6350 will contain the value "4.0". 304 Also in accordance to [RFC6350], the "version" property MUST be the 305 first element of the array containing the properties of a jCard. 307 3.3.1.2. Grouping of Properties 309 In vCard [RFC6350] related properties can be grouped together using a 310 grouping construct. The grouping is accomplished by adding a prefix 311 to the property name, which consists of the group name followed by a 312 dot. 314 In jCard the same grouping is achieved through a "group" parameter, 315 that holds the group name. In jCard a property name therefore MUST 316 NOT be prefixed by a group name. 318 The "GROUP" parameter MUST NOT be used in vCard as per [RFC6350] it 319 is merely registered to reserve the parameter, avoiding collisions. 320 Formal registration occurs in Section 8.1. 322 3.3.1.2.1. Group Conversion Rules 324 In jCard, the parameter's value is a single opaque string. 325 Conversion rules are as follows: 327 o From vCard to jCard, the group construct (see [RFC6350], 328 Section 3.3, Page 7) is removed. In its place, the "group" 329 parameter is used. Its value is a string corresponding to the 330 group name, which is case-insensitive both in vCard and jCard. 331 The name's case SHOULD be converted into lowercase. 333 o When converting from jCard to vCard, the value of the "group" 334 parameter followed by a dot is prefixed to the property name, and 335 the "group" parameter is discarded. The "GROUP" parameter MUST 336 NOT appear in the resulting vCard. Following recommendations in 337 [RFC6350], the name's case SHOULD be converted into uppercase. 339 Example: 341 CONTACT.FN:Mr. John Q. Public\, Esq. 343 is equivalent to: 345 [ "fn", { "group": "CONTACT" }, "text", "Mr. John Q. Public, Esq." ] 347 3.3.1.3. Structured Property Values 349 The vCard specification defines properties with structured values, 350 for example GENDER or ADR. In vCard, a structured text value 351 consists of one or multiple text components, delimited by the 352 SEMICOLON character. Its equivalent in jCard is a structured 353 property value, which is an array containing one element for each 354 text component, with empty/missing text components represented by 355 zero-length strings. 357 vCard Example: 359 ADR:;;123 Main Street;Any Town;CA;91921-1234;U.S.A. 361 jCard Example: 363 ["adr", {}, "text", 364 [ 365 "", "", "123 Main Street", 366 "Any Town", "CA", "91921-1234", "U.S.A." 367 ] 368 ] 370 Some vCard properties, for example ADR, also allow a structured value 371 element that itself has multiple values. In this case, the element 372 of the array describing the structured value is itself an array with 373 one element for each of the component's multiple values. 375 vCard Example: 377 ADR:;;My Street,Left Side,Second Shack;Hometown;PA;18252;U.S.A. 379 jCard Example: 381 ["adr", {}, "text", 382 [ 383 "", "", 384 ["My Street", "Left Side", "Second Shack"], 385 "Hometown", "PA", "18252", "U.S.A." 386 ] 387 ] 389 In both cases, the array element values MUST have the primitive type 390 that matches the jCard type identifier. In [RFC6350], there are only 391 structured text values and thus only JSON strings are used. 392 Extensions may for example define structured number or boolean 393 values, where JSON number or boolean types MUST be used. 395 Although it is allowed for a structured property value to hold just 396 one component, it is RECOMMENDED to represent it as a single text 397 value instead, omitting the array completely. Nevertheless, a simple 398 implementation MAY choose to retain the array, with a single text 399 value as its element. 401 Similarly, structured values that consist of two text components with 402 one being optional (for example, GENDER) can be represented as a 403 single text value. Therefore, parsers of jCard data SHOULD check 404 even known property values for structured information by considering 405 the JSON data type of the value, which can be an array or a primitive 406 value. This is especially important for languages where accessing 407 array members is done by the same construct as accessing characters 408 of a string. 410 Examples: 412 ["gender", {}, "text", ["F", "grrrl"] ], 413 ["gender", {}, "text", "M" ] 415 Per [RFC6350] Section 6.3.1, the component separator MUST be 416 specified even if the component value is missing. Similarly, the 417 jCard array containing the structured data MUST contain all required 418 elements, even if they are empty. 420 vCard Example: 422 ADR;LABEL="123 Maple Ave\nSuite 901\nVancouver BC\nA1B 2C9\nCan 423 ada":;;;;;; 425 jCard Example: 427 ["adr", 428 {"label":"123 Maple Ave\nSuite 901\nVancouver BC\nA1B 2C9\nCanada"}, 429 "text", 430 ["", "", "", "", "", "", ""] 431 ] 433 3.4. Parameters (RFC6350 Section 5) 435 Property parameters are represented as a JSON object where each key- 436 value pair represents the vCard parameter name and its value. The 437 name of the parameter MUST be in lowercase, the original case of the 438 parameter value MUST be preserved. For example, the "LANGUAGE" 439 property parameter is represented in jCard by the "language" key. 440 Any new vCard parameters added in the future will be converted in the 441 same way. 443 Example: 445 ["role", { "language": "tr" }, "text", "roca"], 447 3.4.1. VALUE parameter 449 vCard defines a "VALUE" property parameter (Section 5.2 of 450 [RFC6350]). This property parameter MUST NOT be added to the 451 parameters object. Instead, the value type is signaled through the 452 type identifier in the third element of the array describing the 453 property. When converting a property from vCard to jCard, the value 454 type is determined as follows: 456 1. If the property has a "VALUE" parameter, that parameter's value 457 is used as the value type. 459 2. If the property has no "VALUE" parameter but has a default value 460 type, the default value type is used. 462 3. If the property has no "VALUE" parameter and has no default value 463 type, "unknown" is used. 465 Converting from jCard into vCard is done as follows: 467 1. If the property's value type is "unknown", no "VALUE" parameter 468 is included. 470 2. If the property's value type is the default type for that 471 property, no "VALUE" parameter is included. 473 3. Otherwise, a "VALUE" parameter is included, and the value type is 474 used as the parameter value. 476 See Section 5 for information on handling unknown value types. 478 3.4.2. Multi-value Parameters 480 In [RFC6350], some parameters allow using a COMMA-separated list of 481 values. To ease processing in jCard, the value to such parameters 482 MUST be represented in an array containing the separated values. The 483 array elements MUST be string values. Single-value parameters SHOULD 484 be represented using a single string value, although a more simple 485 implementation might prefer an array with one string element. An 486 example for a such parameter is the vCard "SORT-AS" parameter, more 487 such parameters may be added in extensions. 489 The vCard specification requires encapsulation between DQUOTE 490 characters if a parameter value contains a colon, a semicolon or a 491 comma. These extra DQUOTE characters do not belong to the actual 492 parameter value, and hence are not included when the parameter is 493 converted to jCard. 495 Example: 497 ["vcard", 498 [ 499 ["version", {}, "text", "4.0"], 500 ["n", 501 { "sort-as": ["Harten", "Rene"] }, 502 "text", 503 ["van der Harten", "Rene", "J.", "Sir", "R.D.O.N."] 504 ], 505 ["fn", {}, "text", "Rene van der Harten"] 506 ... 507 ] 508 ] 510 3.5. Values (RFC6350 Section 4) 511 The following subsections specify how vCard property value data 512 types, which are defined in the subsections of [RFC6350] Section 4, 513 are represented in jCard. 515 3.5.1. Text (RFC6350 Section 4.1) 517 Description: vCard "TEXT" property values are represented by a 518 property with the type identifier "text". The value elements are 519 JSON strings. For details on structured text values, see 520 Section 3.3.1.3. 522 Example: 524 ["kind", {}, "text", "group"] 526 3.5.2. URI (RFC6350 Section 4.2) 528 Description: vCard "URI" property values are represented by a 529 property with the type identifier "uri". The value elements are 530 JSON strings. 532 Example: 534 ["source", {}, "uri", "ldap://ldap.example.com/cn=babs%20jensen"] 536 3.5.3. Date (RFC6350 Section 4.3.1) 538 Description: vCard "DATE" property values are represented by a 539 property with the type identifier "date". The value elements are 540 JSON strings with the same date value specified by [RFC6350], but 541 represented using the extended format specified in 542 [ISO.8601.2004], Section 4.1.2. If the complete representation is 543 not used, the same date format restrictions regarding reduced 544 accuracy, truncated representation and expanded representation 545 noted in [RFC6350] Section 4.3.1 apply. Whenever the extended 546 format is not applicable, the basic format MUST be used. 548 ABNF Schema: 550 date-complete = year "-" month "-" day ;YYYY-MM-DD 552 date-noreduc = date-complete 553 / "--" month "-" day; --MM-DD 554 / "---" day; ---DDD 556 date = date-noreduc 557 / year; YYYY 558 / year "-" month ; YYYY-MM 559 / "--" month; --MM 561 Examples: 563 ["bday", {}, "date", "1985-04-12"], 564 ["bday", {}, "date", "1985-04"], 565 ["bday", {}, "date", "1985"], 566 ["bday", {}, "date", "--04-12"], 567 ["bday", {}, "date", "---12"] 569 This table contains possible conversions between the vCard DATE 570 format its jCard date. This information is just an example and not a 571 formal specification of the syntax. The specification can be found 572 in [ISO.8601.2000] and [ISO.8601.2004]: 574 +-----------+----------+------------+ 575 | | vCard | jCard | 576 +-----------+----------+------------+ 577 | Complete | 19850412 | 1985-04-12 | 578 | | | | 579 | Reduced | 1985-04 | 1985-04 | 580 | | | | 581 | Reduced | 1985 | 1985 | 582 | | | | 583 | Truncated | --0412 | --04-12 | 584 | | | | 585 | Truncated | --04 | --04 | 586 | | | | 587 | Truncated | ---12 | ---12 | 588 +-----------+----------+------------+ 590 3.5.4. Time (RFC6350 Section 4.3.2) 592 Description: vCard "TIME" property values are represented by a 593 property with the type identifier "time". The value elements are 594 JSON strings with the same time value specified by [RFC6350], but 595 represented using the extended format specified in 596 [ISO.8601.2004], Section 4.2. If the complete representation is 597 not used, the same time format restrictions regarding reduced 598 accuracy, decimal fraction and truncated representation noted in 599 [RFC6350] Section 4.3.2 apply. Whenever the extended format is 600 not applicable, the basic format MUST be used. The seconds value 601 of 60 MUST only be used to account for positive "leap" seconds and 602 the midnight hour is always represented by 00, never 24. 603 Fractions of a second are not supported by this format. In jCard, 604 UTC offsets are permitted within a time value; note that this 605 differs from jCal [I-D.ietf-jcardcal-jcal], where they are not 606 permitted. 608 ABNF Schema: 610 time-notrunc = hour [":" minute [":" second]] [zone] 612 time = time-notrunc 613 / "-" minute ":" second [zone]; -mm:ss 614 / "-" minute [zone]; -mm 615 / "--" second [zone]; --ss 617 Examples: 619 ["x-time-local", {}, "time", "12:30:00"], 620 ["x-time-utc", {}, "time", "12:30:00Z"], 621 ["x-time-offset", {}, "time", "12:30:00-08:00"], 622 ["x-time-reduced", {}, "time", "23"], 623 ["x-time-truncated", {}, "time", "-30"] 625 This table contains possible conversions between the vCard TIME 626 format its jCard time. This information is just an example and not a 627 formal specification of the syntax. The specification can be found 628 in [ISO.8601.2000] and [ISO.8601.2004]: 630 +-----------+--------+----------+ 631 | | vCard | jCard | 632 +-----------+--------+----------+ 633 | Complete | 232050 | 23:20:50 | 634 | | | | 635 | Reduced | 2320 | 23:20 | 636 | | | | 637 | Reduced | 23 | 23 | 638 | | | | 639 | Truncated | -2050 | -20:50 | 640 | | | | 641 | Truncated | -20 | -20 | 642 | | | | 643 | Truncated | --50 | --50 | 644 +-----------+--------+----------+ 646 Also, all combinations may have any zone designator appended, as in 647 the complete representation. 649 3.5.5. Date-Time (RFC6350 Section 4.3.3) 651 Description: vCard "DATE-TIME" property values are represented by a 652 property with the type identifier "date-time". The value elements 653 are JSON strings with the same date value specified by [RFC6350], 654 but represented using the extended format specified in 655 [ISO.8601.2004], Section 4.3. If the complete representation is 656 not used, the same date and time format restrictions as in 657 Section 3.5.4 and Section 3.5.3 apply. Just as in [RFC6350], 658 truncation of the date part is permitted. 660 Example: 662 ["anniversary", {}, "date-time", "2013-02-14T12:30:00"], 663 ["anniversary", {}, "date-time", "2013-01-10T19:00:00Z"], 664 ["anniversary", {}, "date-time", "2013-08-15T09:45:00+01:00"], 665 ["anniversary", {}, "date-time", "---15T09:45:00+01:00"] 667 This table contains possible conversions between the vCard DATE-TIME 668 format its jCard date-time. This information is just an example and 669 not a formal specification of the syntax. The specification can be 670 found in [ISO.8601.2000] and [ISO.8601.2004]: 672 +----------------+----------------------+---------------------------+ 673 | Representation | vCard | jCard | 674 +----------------+----------------------+---------------------------+ 675 | Complete | 19850412T232050 | 1985-04-12T23:20:50 | 676 | | | | 677 | Complete | 19850412T232050Z | 1985-04-12T23:20:50Z | 678 | | | | 679 | Complete | 19850412T232050+0400 | 1985-04-12T23:20:50+04:00 | 680 | | | | 681 | Complete | 19850412T232050+04 | 1985-04-12T23:20:50+04 | 682 | | | | 683 | Reduced | 19850412T2320 | 1985-04-12T23:20 | 684 | | | | 685 | Reduced | 19850412T23 | 1985-04-12T23 | 686 | | | | 687 | Truncated and | --0412T2320 | --04-12T23:20 | 688 | Reduced | | | 689 | | | | 690 | Truncated and | --04T2320 | --04T23:20 | 691 | Reduced | | | 692 | | | | 693 | Truncated and | ---12T2320 | ---12T23:20 | 694 | Reduced | | | 695 | | | | 696 | Truncated and | --0412T2320 | --04-12T23:20 | 697 | Reduced | | | 698 | | | | 699 | Truncated and | --04T23 | --04T23 | 700 | Reduced | | | 701 +----------------+----------------------+---------------------------+ 703 As specified in [ISO.8601.2000], the lower order components may not 704 be omitted in the date part (reduced accuracy) and the higher order 705 components may not be omitted in the time part (truncation). Also, 706 all combinations may have any zone designator appended, as in the 707 complete representation. 709 3.5.6. Date and/or Time (RFC6350 Section 4.3.4) 711 Description: vCard "DATE-AND-OR-TIME" property values are 712 represented by a property with the type identifier "date-and-or- 713 time". The value elements are either a date-time (Section 3.5.5), 714 a date (Section 3.5.3) or a time (Section 3.5.4) value. Just as 715 in [RFC6350] Section 4.3.4, a stand-alone time value MUST always 716 be preceded by a "T". 718 Example: 720 ["bday", {}, "date-and-or-time", "2013-02-14T12:30:00"], 721 ["bday", {}, "date-and-or-time", "---22T14:00"] 722 ["bday", {}, "date-and-or-time", "1985"], 723 ["bday", {}, "date-and-or-time", "T12:30"] 725 3.5.7. Timestamp (RFC6350 Section 4.3.5) 727 Description: vCard "TIMESTAMP" property values are represented by a 728 property with the type identifier "timestamp". The value elements 729 are JSON strings with the same timestamp value specified by 730 [RFC6350], but represented using the extended format and complete 731 representation specified in [ISO.8601.2004], Section 4.3.2. 733 Example: 735 ["rev", {}, "timestamp", "2013-02-14T12:30:00"], 736 ["rev", {}, "timestamp", "2013-02-14T12:30:00Z"], 737 ["rev", {}, "timestamp", "2013-02-14T12:30:00-05"], 738 ["rev", {}, "timestamp", "2013-02-14T12:30:00-05:00"] 740 This table contains possible conversions between the vCard TIMESTAMP 741 format its jCard timestamp. This information is just an example and 742 not a formal specification of the syntax. The specification can be 743 found in [ISO.8601.2000] and [ISO.8601.2004]: 745 +----------------+----------------------+---------------------------+ 746 | Representation | vCard | jCard | 747 +----------------+----------------------+---------------------------+ 748 | Complete | 19850412T232050 | 1985-04-12T23:20:50 | 749 | | | | 750 | Complete | 19850412T232050Z | 1985-04-12T23:20:50Z | 751 | | | | 752 | Complete | 19850412T232050+0400 | 1985-04-12T23:20:50+04:00 | 753 | | | | 754 | Complete | 19850412T232050+04 | 1985-04-12T23:20:50+04 | 755 +----------------+----------------------+---------------------------+ 757 3.5.8. Boolean (RFC6350 Section 4.4) 759 Description: vCard "BOOLEAN" property values are represented by a 760 property with the type identifier "boolean". The value element is 761 a JSON boolean value. 763 Example: 765 ["x-non-smoking", {}, "boolean", true] 767 3.5.9. Integer (RFC6350 Section 4.5) 769 Description: vCard "INTEGER" property values are represented by a 770 property with the type identifier "integer". The value elements 771 are JSON primitive number values. 773 Examples: 775 ["x-karma-points", {}, "integer", 42] 777 JSON allows decimals (e.g. 3.14) and exponents (e.g. 2e10) to be 778 used in numeric values. jCard does not prohibit this for "integer" 779 property values. However, since vCard does not support decimals or 780 exponents in integers, any decimals and exponents MUST be eliminated 781 when converting an "integer" value type property from jCard to vCard. 783 3.5.10. Float (RFC6350 Section 4.6) 785 Description: vCard "FLOAT" property values are represented by a 786 property with the type identifier "float". The value elements are 787 JSON primitive number values. 789 Example: 791 ["x-grade", {}, "float", 1.3] 793 JSON allows exponents (e.g. 2e10) to be used in numeric values. 794 jCard does not prohibit this for "float" property values. However, 795 since vCard does not support exponents in floats, any exponents MUST 796 be eliminated when converting a "float" value type property from 797 jCard to vCard. 799 3.5.11. UTC Offset (RFC6350 Section 4.7) 801 Description: vCard "UTC-OFFSET" property values are represented by a 802 property with the type identifier "utc-offset". The value 803 elements are JSON strings with the same UTC offset value specified 804 by [RFC6350], with the exception that the hour and minute 805 components are separated by a ":" character, for consistency with 806 the [ISO.8601.2004] timezone offset, extended format. 808 Example: 810 // Note: [RFC6350] mentions use of utc-offset 811 // for the TZ property as NOT RECOMMENDED 812 ["tz", {}, "utc-offset", "-05:00"] 814 3.5.12. Language Tag (RFC6350 Section 4.8) 816 Description: vCard "LANGUAGE-TAG" property values are represented by 817 a property with the type identifier "language-tag". The value 818 elements are JSON strings containing a single language-tag, as 819 defined in [RFC5646]. 821 Example: 823 ["lang", {}, "language-tag", "de"] 825 3.6. Extensions (RFC6350 Section 6.10) 827 vCard extension properties and property parameters (those with an 828 "X-" prefix in their name) are handled in the same way as other 829 properties and property parameters: the property is represented by an 830 array, the property parameter represented by an object. The property 831 or parameter name uses the same name as for the vCard extension, but 832 in lowercase. For example, the "X-FOO" property in vCard turns into 833 the "x-foo" jCard property. See Section 5 for how to deal with 834 default values for unrecognized extension properties or property 835 parameters. 837 4. Converting from jCard into vCard 839 When converting property and property parameter values, the names 840 SHOULD be converted to uppercase. Although vCard names are case 841 insensitive, common practice is to keep them all uppercase following 842 the actual definitions in [RFC6350]. 844 Character escaping and line folding MUST be applied to the resulting 845 vCard data as required by [RFC6350] and [RFC6868]. 847 When converting to vCard, the VALUE parameter MUST be added to 848 properties whose default value type is unknown, but do not have a 849 jCard type identifier "unknown". The VALUE parameter MAY be omitted 850 for properties using the default value type. The VALUE parameter 851 MUST be omitted for properties which have the jCard type identifier 852 "unknown". 854 5. Handling Unrecognized Properties or Parameters 856 In vCard, properties can have one or more value types as specified by 857 their definition, with one of those values being defined as the 858 default. When a property uses its default value type, the "VALUE" 859 property parameter does not need to be specified on the property. 860 For example, "BDAY"'s default value type is "date-and-or-time", so 861 "VALUE=date-and-or-time" need not be set as a property parameter. 862 However, "BDAY" also allows a "text" value to be specified, and if 863 that is used, "VALUE=text" has to be set as a property parameter. 865 When new properties are defined or "X-" properties used, a vCard to 866 jCard converter might not recognize them, and not know what the 867 appropriate default value types are, yet they need to be able to 868 preserve the values. A similar issue arises for unrecognized 869 property parameters. 871 In jCard, a new "unknown" property value type is introduced. Its 872 purpose is to allow preserving unknown property values when round- 873 tripping between jCard and vCard. To avoid collisions, this 874 specification reserves the UNKNOWN property value type in vCard. It 875 MUST NOT be used in any vCard as specified by [RFC6350], nor any 876 extensions to it. The type is hence registered to the vCard Value 877 Data Types registroy in Section 8.2. 879 5.1. Converting vCard into jCard 881 Any property that does not include a "VALUE" property parameter and 882 whose default value type is not known, MUST be converted to a 883 primitive JSON string. The content of that string is the unprocessed 884 value text. Also, value type MUST be set to "unknown". 886 To correctly implement this format, it is critical that if the 887 default type is not known that the value type "unknown" is used. If 888 this requirement is ignored and for example "text" is used, 889 additional escaping may occur which breaks round-tripping values. 891 Any unrecognized property parameter MUST be converted to a string 892 value, with its content set to the property parameter value text, 893 treated as if it were a "TEXT" value. 895 5.2. Converting jCard into vCard 897 In jCard the value type is always explicitly specified. It is 898 converted to vCard using the vCard VALUE parameter, except in the 899 following two cases: 901 o If the value type specified in jCard matches the default value 902 type in vCard, the VALUE parameter MAY be omitted. 904 o If the value type specified in jCard is set to "unknown", the 905 VALUE parameter MUST NOT be specified. The value MUST be taken 906 over in vCard without processing. 908 5.3. Examples 910 The following is an example of an unrecognized vCard property (that 911 uses an "URI" value as its default), and the equivalent jCard 912 representation of that property. 914 vCard: 916 X-COMPLAINT-URI:mailto:abuse@example.org 918 jCard: 920 ["x-complaint-uri", {}, "unknown", "mailto:abuse@example.org"] 922 The following is an example of how to cope with jCard data where the 923 parser was unable to identify the value type. Note how the "unknown" 924 value type is not added to the vCard data and escaping, aside from 925 standard JSON string escaping, is not processed. 927 jCard: 929 ["x-coffee-data", {}, "unknown", "Stenophylla;Guinea\\,Africa"] 931 vCard: 933 X-COFFEE-DATA:Stenophylla;Guinea\,Africa 935 There are no standard properties in [RFC6350] that have a default 936 type of integer. Consequently, this example uses the following 937 extended property which we treat as having a default type known to 938 the parser, namely integer, in order to illustrate how a property 939 with a known default type would be transformed. 941 jCard: 943 ["x-karma-points", {}, "integer", 95] 945 vCard: 947 X-KARMA-POINTS:95 949 The following is an example of an unrecognized vCard property 950 parameter (that uses a "FLOAT" value as its default) specified on a 951 recognized vCard property, and the equivalent jCard representation of 952 that property and property parameter. 954 vCard: 956 GENDER;X-PROBABILITY=0.8:M 958 jCard: 960 ["gender", { "x-probability": "0.8" }, "text", "M"] 962 6. Implementation Status (to be removed prior to publication as an RFC) 964 This section describes libraries known to implement this draft as per 965 [I-D.sheffer-running-code]. 967 1. ICAL.js - Philipp Kewisch, James Lal. A JavaScript parser for 968 iCalendar (rfc5545) 970 Source: https://github.com/mozilla-comm/ical.js/ 972 Maturity: alpha (for jCard) 974 Coverage: Currently geared towards jCal, therefore not all 975 formats are supported. Includes an online validator. (as 976 of rev 847c67c501, 2013-02-14) 978 Licensing: MPL, Mozilla Public License 2.0 980 2. Py Calendar - Cyrus Daboo. iCalendar/vCard Library 982 Source: https://svn.calendarserver.org/repository/calendarserver 983 /PyCalendar/branches/json/ 985 Maturity: production 987 Coverage: All aspects of this draft, up to version 01. 989 Licensing: Apache License, Version 2.0 991 3. ez-vcard - Michael Angstadt. A vCard parser library written in 992 Java 994 Source: https://code.google.com/p/ez-vcard/ 996 Maturity: production 998 Coverage All aspects of this draft. 1000 Licensing: New BSD License 1002 Additionally, interoperability testing of this draft is an ongoing 1003 effort under members of calconnect, the Calendaring and Scheduling 1004 Consortium. CalDAV Vendors are looking into supporting this draft. 1006 7. Security Considerations 1008 This specification defines how vCard data can be "translated" between 1009 two different data formats - the original text format and JSON - with 1010 a one-to-one mapping to ensure all the semantic data in one format 1011 (properties, parameters and values) are preserved in the other. It 1012 does not change the semantic meaning of the underlying data itself, 1013 or impose or remove any security considerations that apply to the 1014 underlying data. 1016 The use of JSON as a format does have its own inherent security risks 1017 as discussed in Section 7 of [RFC4627]. Even though JSON is 1018 considered a safe subset of JavaScript, it should be kept in mind 1019 that a flaw in the parser processing JSON could still impose a threat 1020 which doesn't arise with conventional vCard data. 1022 With this in mind, a parser for JSON data should be used for jCard 1023 that is aware of the security implications. For example, the use of 1024 JavaScript's eval() function is only allowed using the regular 1025 expression in Section 6 of [RFC4627]. A native parser with full 1026 awareness of the JSON format should be preferred. 1028 In addition, it is expected that this new format will result in vCard 1029 data being more widely disseminated (e.g., with use in web 1030 applications rather than just dedicated "contact managers"). 1032 In all cases, application developers have to conform to the semantics 1033 of the vCard data as defined by [RFC6350] and associated extensions, 1034 and all of the security considerations described in Section 9 of 1035 [RFC6350], or any associated extensions, are applicable. 1037 8. IANA Considerations 1039 This document defines a MIME media type for use with vCard in JSON 1040 data. This media type SHOULD be used for the transfer of calendaring 1041 data in JSON. 1043 Type name: application 1045 Subtype name: vcard+json 1047 Required parameters: none 1049 Optional parameters: "version", as defined for the text/vcard media 1050 media type in [RFC6350], Section 10.1. 1052 Encoding considerations: Same as encoding considerations of 1053 application/json as specified in [RFC4627], Section 6. 1055 Security considerations: See Section 7. 1057 Interoperability considerations: This media type provides an 1058 alternative format for vCard data based on JSON. 1060 Published specification: This specification. 1062 Applications which use this media type: Applications that currently 1063 make use of the text/vcard media type can use this as an 1064 alternative. Similarly, Applications that use the application/ 1065 json media type to transfer directory data can use this to further 1066 specify the content. 1068 Fragment identifier considerations: N/A 1070 Additional information: 1072 Deprecated alias names for this type: N/A 1074 Magic number(s): N/A 1076 File extension(s): N/A 1078 Macintosh file type code(s): N/A 1080 Person & email address to contact for further information: 1081 vcarddav@ietf.org 1083 Intended usage: COMMON 1085 Restrictions on usage: There are no restrictions on where this media 1086 type can be used. 1088 Author: See the "Author's Address" section of this document. 1090 Change controller: IETF 1092 8.1. GROUP vCard Parameter 1094 IANA has added the GROUP parameter to the vCard Parameters registry, 1095 initialied in Section 10.3.2 of [RFC6350]. Usage of the GROUP 1096 parameter is further described in Section 3.3.1.2 of this document. 1098 Namespace: 1100 Parameter name: GROUP 1102 Purpose: To simplify the jCard format. 1104 Description: The GROUP parameter is reserved for the exclusive use 1105 of the jCard format described in this document. It MUST NOT be 1106 used in plain vCard [RFC6350], nor in xCard [RFC6351]. 1108 Format definition: When converting from jCard to vCard, the value of 1109 the GROUP parameter is used as part of the property name. 1110 Therefore the value is restricted to characters allowed in 1111 property names, namely ALPHA, DIGIT and "-" characters. When 1112 used, the GROUP parameter MUST NOT be empty. 1114 Example: As this registration serves as a reservation of the GROUP 1115 parameter so that it is not used in vCard, there is no applicable 1116 vCard example. Examples of its usage in jCard can be found in 1117 this document. 1119 8.2. UNKNOWN vCard Value Data Type 1121 IANA has added the UNKNOWN value data type to the vCard Value Data 1122 Types registry, initialized in Section 10.3.3 of [RFC6350]. Usage of 1123 the UNKNOWN type is further described in Section 5 of this document. 1125 Value name: UNKNOWN 1127 Purpose: To allow preserving property values whose default value 1128 type is not known during round-tripping between jCard and vCard. 1130 Format definition: (Not applicable) 1132 Description: The UNKNOWN value data type is reserved for the 1133 exclusive use of the jCard format. It MUST NOT be used in plain 1134 vCard [RFC6350]. 1136 Example: As this registration serves as a reservation of the UNKNOWN 1137 type so that it is not used in vCard, there is no applicable vCard 1138 example. Examples of its usage in jCard can be found in this 1139 document. 1141 9. Acknowledgments 1143 The author would like to thank the following for their valuable 1144 contributions: Cyrus Daboo, Mike Douglass, William Gill, Erwin Rehme, 1145 and Dave Thewlis. Simon Perreault, Michael Angstadt, Peter Saint- 1146 Andre, Bert Greevenbosch, Javier Godoy. This specification 1147 originated from the work of the XML-JSON technical committee of the 1148 Calendaring and Scheduling Consortium. 1150 10. References 1151 10.1. Normative References 1153 [ISO.8601.2000] 1154 International Organization for Standardization, ""Data 1155 elements and interchange formats -- Information 1156 interchange -- Representation of dates and times" ", ISO 1157 8601, 12 2000. 1159 [ISO.8601.2004] 1160 International Organization for Standardization, ""Data 1161 elements and interchange formats -- Information 1162 interchange -- Representation of dates and times" ", ISO 1163 8601, 12 2004. 1165 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1166 Requirement Levels", BCP 14, RFC 2119, March 1997. 1168 [RFC4627] Crockford, D., "The application/json Media Type for 1169 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1171 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1172 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1174 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1175 Languages", BCP 47, RFC 5646, September 2009. 1177 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 1178 August 2011. 1180 [RFC6868] Daboo, C., "Parameter Value Encoding in iCalendar and 1181 vCard", RFC 6868, February 2013. 1183 10.2. Informative References 1185 [I-D.ietf-jcardcal-jcal] 1186 Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON 1187 format for iCalendar", draft-ietf-jcardcal-jcal-00 (work 1188 in progress), March 2013. 1190 [I-D.sheffer-running-code] 1191 Sheffer, Y. and A. Farrel, "Improving Awareness of Running 1192 Code: the Implementation Status Section", draft-sheffer- 1193 running-code-02 (work in progress), January 2013. 1195 [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling 1196 Core Object Specification (iCalendar)", RFC 5545, 1197 September 2009. 1199 [RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML 1200 Format for iCalendar", RFC 6321, August 2011. 1202 [RFC6351] Perreault, S., "xCard: vCard XML Representation", RFC 1203 6351, August 2011. 1205 [calconnect-artifacts] 1206 The Calendaring and Scheduling Consortium, "Code Artifacts 1207 and Schemas", , 1208 . 1210 Appendix A. ABNF Schema 1212 Below is an ABNF schema as per [RFC5234] for vCard in JSON. ABNF 1213 Symbols not described here are taken from [RFC4627]. The schema is 1214 non-normative and given for reference only. 1216 The numeric section numbers given in the comments refer to section in 1217 [RFC6350]. Additional semantic restrictions apply, especially 1218 regarding the allowed properties and sub-components per component. 1219 Details on these restrictions can be found in this document and 1220 [RFC6350]. 1222 Additional schemas may be available on the internet at 1223 [calconnect-artifacts]. 1225 ; A jCard object uses the name "vcard" and a properties array. 1226 ; Restrictions to which properties and may be specified are to 1227 ; be taken from RFC6350. 1228 jcardobject = begin-array 1229 DQUOTE component-name DQUOTE value-separator 1230 properties-array 1231 end-array 1233 ; A jCard property consists of the name string, parameters object, 1234 ; type string and one or more values as specified in this document. 1235 property = begin-array 1236 DQUOTE property-name DQUOTE value-separator 1237 params-object value-separator 1238 DQUOTE type-name DQUOTE 1239 propery-value *(value-separator property-value) 1240 end-array 1241 properties-array = begin-array 1242 [ property *(value-separator property) ] 1243 end-array 1245 ; Property values depend on the type-name. Aside from the value types 1246 ; mentioned here, extensions may make use of other JSON value types. 1248 property-value = simple-prop-value / structured-prop-value 1249 simple-prop-value = string / number / true / false 1250 structured-prop-value = 1251 begin-array 1252 [ structured-element *(value-separator structured-element) ] 1253 end-array 1255 ; Each structured element may have multiple values if 1256 ; semantically allowed 1257 structured-element = simple-prop-value / structured-multi-prop 1258 structured-multi-prop = 1259 begin-array 1260 [ simple-prop-value *(value-separator simple-prop-value) ] 1261 end-array 1263 ; The jCard params-object is a JSON object which follows the semantic 1264 ; guidelines described in this document. 1265 params-object = begin-object 1266 [ params-member *(value-separator params-member) ] 1267 end-object 1268 params-member = DQUOTE param-name DQUOTE name-separator param-value 1269 param-value = string / param-multi 1270 param-multi = begin-array 1271 [ string *(value-separtor string) ] 1272 end-array 1274 ; The type MUST be a valid type as described by this document. New 1275 ; value types can be added by extensions. 1276 type-name = "text" / "uri" / "date" / "time" / "date-time" / 1277 "boolean" / "integer" / "float" / "utc-offset" / 1278 "language-tag" / x-type 1280 ; Property, parameter and type names MUST be lowercase. Additional 1281 ; semantic restrictions apply as described by this document and 1282 ; RFC6350. 1283 component-name = lowercase-name 1284 property-name = lowercase-name 1285 param-name = lowercase-name 1286 x-type = lowercase-name 1287 lowercase-name = 1*(%x61-7A / DIGIT / "-") 1289 Appendix B. Examples 1291 This section contains an example of a vCard object with its jCard 1292 representation. 1294 B.1. Example: vCard of the author of RFC6350 1296 B.1.1. vCard Data 1298 BEGIN:VCARD 1299 VERSION:4.0 1300 FN:Simon Perreault 1301 N:Perreault;Simon;;;ing. jr,M.Sc. 1302 BDAY:--0203 1303 ANNIVERSARY:20090808T1430-0500 1304 GENDER:M 1305 LANG;PREF=1:fr 1306 LANG;PREF=2:en 1307 ORG;TYPE=work:Viagenie 1308 ADR;TYPE=work:;Suite D2-630;2875 Laurier; 1309 Quebec;QC;G1V 2M2;Canada 1310 TEL;VALUE=uri;TYPE="work,voice";PREF=1:tel:+1-418-656-9254;ext=102 1311 TEL;VALUE=uri;TYPE="work,cell,voice,video,text":tel:+1-418-262-6501 1312 EMAIL;TYPE=work:simon.perreault@viagenie.ca 1313 GEO;TYPE=work:geo:46.772673,-71.282945 1314 KEY;TYPE=work;VALUE=uri: 1315 http://www.viagenie.ca/simon.perreault/simon.asc 1316 TZ:-0500 1317 URL;TYPE=home:http://nomis80.org 1318 END:VCARD 1320 B.1.2. jCard Data 1322 ["vcard", 1323 [ 1324 ["version", {}, "text", "4.0"], 1325 ["fn", {}, "text", "Simon Perreault"], 1326 ["n", 1327 {}, 1328 "text", 1329 ["Perreault", "Simon", "", "", ["ing. jr", "M.Sc."]] 1330 ], 1331 ["bday", {}, "date-and-or-time", "--02-03"], 1332 ["anniversary", 1333 {}, 1334 "date-and-or-time", 1335 "2009-08-08T14:30:00-05:00" 1336 ], 1337 ["gender", {}, "text", "M"], 1338 ["lang", { "pref": "1" }, "language-tag", "fr"], 1339 ["lang", { "pref": "2" }, "language-tag", "en"], 1340 ["org", { "type": "work" }, "text", "Viagenie"], 1342 ["adr", 1343 { "type": "work" }, 1344 "text", 1345 [ 1346 "", 1347 "Suite D2-630", 1348 "2875 Laurier", 1349 "Quebec", 1350 "QC", 1351 "G1V 2M2", 1352 "Canada" 1353 ] 1354 ], 1355 ["tel", 1356 { "type": ["work", "voice"], "pref": "1" }, 1357 "uri", 1358 "tel:+1-418-656-9254;ext=102" 1359 ], 1360 ["tel", 1361 { "type": ["work", "cell", "voice", "video", "text"] }, 1362 "uri", 1363 "tel:+1-418-262-6501" 1364 ], 1365 ["email", 1366 { "type": "work" }, 1367 "text", 1368 "simon.perreault@viagenie.ca" 1369 ], 1370 ["geo", { "type": "work" }, "uri", "geo:46.772673,-71.282945"], 1371 ["key", 1372 { "type": "work" }, 1373 "uri", 1374 "http://www.viagenie.ca/simon.perreault/simon.asc" 1375 ], 1376 ["tz", {}, "utc-offset", "-05:00"], 1377 ["url", { "type": "home" }, "uri", "http://nomis80.org"] 1378 ] 1379 ] 1381 Appendix C. Change History (to be removed prior to publication as an 1382 RFC) 1384 draft-kewisch-vcard-in-json-01 1386 * Added ABNF and improved references in date/time related 1387 sections 1389 * Changes to wording in "vCard Stream" section 1391 * Changes to wording about VALUE parameter when converting to 1392 vCard 1394 * Corrected missing "type" parameter and separator in example 1396 * Minor wording corrections 1398 draft-ietf-jcardcal-jcard-00 1400 * Pubication as a WG draft 1402 draft-ietf-jcardcal-jcard-01 1404 * Changed grouping syntax to use new GROUP parameter and added 1405 respective IANA section 1407 * Added timestamp and date-and-or-time types instead of 1408 converting them from date/time/date-time 1410 * Added a further sentence on preprocessing and escaping to 1411 clarify that JSON escaping must be used 1413 * Described how to handle structured text values and structured 1414 text components with multiple values. 1416 * Corrections and additions to the ABNF Section, adaptions to 1417 example 1419 draft-ietf-jcardcal-jcard-02 1421 * Made more clear that complete representation is not mandatory 1423 * Added sheffer-running-code section 1425 * Changed handling of unknown property parameter types 1427 * Minor corrections to sections regarding dates, fixing typos 1429 draft-ietf-jcardcal-jcard-03 1431 * Add LABEL property example and description 1433 * Added acknowledgements 1435 * More typos fixed 1436 * Added reference to rfc6868 1438 * Various editorial changes per jcardcal issue tracker 1440 * Resolved a few MAY/SHOULD conflicts 1442 * Put the VERSION property into its own section 1444 * Improved GROUP/UNKNOWN registrations by only putting vcard 1445 related information into the registration template 1447 * Removed vcard stream construct. 1449 * Added reference to RFC6868 for both directions 1451 * Corrected some examples and ABNF 1453 draft-ietf-jcardcal-jcard-05 1455 * Updated UNKNOWN registration text to match with jCal text. 1457 draft-ietf-jcardcal-jcard-06 1459 * Various editoral changes based on the IETF reviews. Please see 1460 http://trac.tools.ietf.org/wg/jcardcal/trac/ for details. 1462 draft-ietf-jcardcal-jcard-07 1464 * More editoral changes based on the IETF reviews. Please see 1465 http://trac.tools.ietf.org/wg/jcardcal/trac/ for details. 1467 * Merged examples for single/multi-valued properties 1469 * Move IANA registrations for GROUP and UNKNOWN to the end of the 1470 document 1472 * Corrected a few examples, e.g. use of "lang" vs "language" or 1473 missing version property. 1475 Author's Address 1476 Philipp Kewisch 1477 Mozilla Corporation 1478 650 Castro Street, Suite 300 1479 Mountain View, CA 94041 1480 USA 1482 EMail: mozilla@kewis.ch 1483 URI: http://www.mozilla.org/