7Internet Engineering Task Force (IETF) P. Kewisch
8Request for Comments: 7095 Mozilla
9Category: Standards Track January 2014
13 jCard: The JSON Format for vCard
17 This specification defines "jCard", a JSON format for vCard data.
18 The vCard data format is a text format for representing and
19 exchanging information about individuals and other entities, for
20 example, telephone numbers, email addresses, structured names, and
21 delivery addresses. JSON is a lightweight, text-based, language-
22 independent data interchange format commonly used in Internet
27 This is an Internet Standards Track document.
29 This document is a product of the Internet Engineering Task Force
30 (IETF). It represents the consensus of the IETF community. It has
31 received public review and has been approved for publication by the
32 Internet Engineering Steering Group (IESG). Further information on
33 Internet Standards is available in Section 2 of RFC 5741.
35 Information about the current status of this document, any errata,
36 and how to provide feedback on it may be obtained at
37 http://www.rfc-editor.org/info/rfc7095.
41 Copyright (c) 2014 IETF Trust and the persons identified as the
42 document authors. All rights reserved.
44 This document is subject to BCP 78 and the IETF Trust's Legal
45 Provisions Relating to IETF Documents
46 (http://trustee.ietf.org/license-info) in effect on the date of
47 publication of this document. Please review these documents
48 carefully, as they describe your rights and restrictions with respect
49 to this document. Code Components extracted from this document must
50 include Simplified BSD License text as described in Section 4.e of
51 the Trust Legal Provisions and are provided without warranty as
52 described in the Simplified BSD License.
58Kewisch Standards Track [Page 1]
60RFC 7095 jCard January 2014
65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
66 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
67 3. Converting from vCard to jCard . . . . . . . . . . . . . . . 4
68 3.1. Pre-processing . . . . . . . . . . . . . . . . . . . . . 4
69 3.2. jCard Object and Syntactic Entities (RFC 6350, Sections
70 6.1.1 and 6.1.2) . . . . . . . . . . . . . . . . . . . . 5
71 3.3. Properties (RFC 6350, Section 6) . . . . . . . . . . . . 5
72 3.3.1. Special Cases for Properties . . . . . . . . . . . . 7
73 3.3.1.1. The VERSION Property . . . . . . . . . . . . . . 7
74 3.3.1.2. Grouping of Properties . . . . . . . . . . . . . 7
75 3.3.1.3. Structured Property Values . . . . . . . . . . . 8
76 3.4. Parameters (RFC 6350, Section 5) . . . . . . . . . . . . 10
77 3.4.1. VALUE Parameter . . . . . . . . . . . . . . . . . . . 10
78 3.4.2. Multi-Valued Parameters . . . . . . . . . . . . . . . 11
79 3.5. Values (RFC 6350, Section 4) . . . . . . . . . . . . . . 11
80 3.5.1. Text (RFC 6350, Section 4.1) . . . . . . . . . . . . 12
81 3.5.2. URI (RFC 6350, Section 4.2) . . . . . . . . . . . . . 12
82 3.5.3. Date (RFC 6350, Section 4.3.1) . . . . . . . . . . . 12
83 3.5.4. Time (RFC 6350, Section 4.3.2) . . . . . . . . . . . 13
84 3.5.5. Date-Time (RFC 6350, Section 4.3.3) . . . . . . . . . 14
85 3.5.6. Date and/or Time (RFC 6350, Section 4.3.4) . . . . . 16
86 3.5.7. Timestamp (RFC 6350, Section 4.3.5) . . . . . . . . . 16
87 3.5.8. Boolean (RFC 6350, Section 4.4) . . . . . . . . . . . 17
88 3.5.9. Integer (RFC 6350, Section 4.5) . . . . . . . . . . . 17
89 3.5.10. Float (RFC 6350, Section 4.6) . . . . . . . . . . . . 17
90 3.5.11. UTC Offset (RFC 6350, Section 4.7) . . . . . . . . . 18
91 3.5.12. Language Tag (RFC 6350, Section 4.8) . . . . . . . . 18
92 3.6. Extensions (RFC 6350, Section 6.10) . . . . . . . . . . . 18
93 4. Converting from jCard into vCard . . . . . . . . . . . . . . 19
94 5. Handling Unrecognized Properties or Parameters . . . . . . . 19
95 5.1. Converting vCard into jCard . . . . . . . . . . . . . . . 19
96 5.2. Converting jCard into vCard . . . . . . . . . . . . . . . 20
97 5.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 20
98 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21
99 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
100 7.1. GROUP vCard Parameter . . . . . . . . . . . . . . . . . . 23
101 7.2. UNKNOWN vCard Value Data Type . . . . . . . . . . . . . . 24
102 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24
103 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 24
104 9.1. Normative References . . . . . . . . . . . . . . . . . . 24
105 9.2. Informative References . . . . . . . . . . . . . . . . . 25
106 Appendix A. ABNF Syntax . . . . . . . . . . . . . . . . . . . . 26
107 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 27
108 B.1. Example: vCard of the Author of RFC 6350 . . . . . . . . 27
109 B.1.1. vCard Data . . . . . . . . . . . . . . . . . . . . . 27
110 B.1.2. jCard Data . . . . . . . . . . . . . . . . . . . . . 28
114Kewisch Standards Track [Page 2]
116RFC 7095 jCard January 2014
121 The vCard data format [RFC6350] provides for the capture and exchange
122 of information normally stored within an address book or directory
123 application. The vCard format has gone through multiple revisions,
124 most recently vCard 4.
126 As certain similarities exist between vCard and the iCalendar data
127 format [RFC5545], there is also an effort to define a JSON-based data
128 format for calendar information called jCal [JCAL] that parallels the
129 format defined in this specification. The term "JSON" describes the
130 JavaScript Object Notation defined in [RFC4627].
132 The purpose of this specification is to define "jCard", a JSON format
133 for vCard data. One main advantage to using a JSON-based format over
134 the classic vCard format is easier processing for JavaScript-based
135 widgets and libraries, especially in the scope of web-based
138 The key design considerations are essentially the same as those for
139 [JCAL] and [RFC6321], that is:
141 Round-tripping (converting a vCard instance to jCard and back)
142 will give the same semantic result as the starting point. For
143 example, all components, properties, and property parameters are
144 guaranteed to be preserved.
146 The Ordering of elements and the case of property and parameter
147 names will not necessarily be preserved.
149 The vCard data semantics are to be preserved, allowing a simple
150 consumer to easily browse the data in jCard. A full understanding
151 of vCard is still required in order to modify and/or fully
152 comprehend the directory data.
154 Extensions to the underlying vCard specification must not lead to
155 requiring an update to jCard.
1572. Conventions Used in This Document
159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
160 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
161 document are to be interpreted as described in [RFC2119].
163 The underlying format used for jCard is JSON. Consequently, the
164 terms "object" and "array" as well as the four primitive types
165 (strings, numbers, booleans, and null) are to be interpreted as
166 described in Section 1 of [RFC4627].
170Kewisch Standards Track [Page 3]
172RFC 7095 jCard January 2014
175 Some examples in this document contain "partial" JSON documents used
176 for illustrative purposes. In these examples, three periods "..."
177 are used to indicate a portion of the document that has been removed
1803. Converting from vCard to jCard
182 This section describes how vCard objects are converted to jCard using
183 a simple mapping between the vCard data model and JSON elements.
185 In [RFC6350], vCard objects are comprised of a set of "properties",
186 "parameters", and "values". The top level of a vCard object contains
187 "properties". A "property" has a "value" and a set of zero or more
188 "parameters". Each of these entities has a representation in jCard,
189 defined in the following sections. The representation of a vCard
190 object in JSON will be named "jCard object" throughout this document.
194 vCard uses a line-folding mechanism to limit lines of data to a
195 maximum line length (typically 75 octets) to ensure maximum
196 likelihood of preserving data integrity as it is transported via
197 various means (e.g., email) -- see Section 3.2 of [RFC6350].
199 vCard data uses an "escape" character sequence for text values and
200 property parameter values. See Section 3.4 of [RFC6350] as well as
203 When converting from vCard to jCard, first vCard lines MUST be
204 unfolded. Afterwards, any vCard escaping MUST be unescaped.
205 Finally, JSON escaping (e.g., for control characters) MUST be
208 The reverse order applies when converting from jCard to vCard.
209 First, JSON escaping MUST be unescaped. Afterwards, vCard escaping
210 MUST be applied. Finally, long lines SHOULD be folded as described
213 One key difference in the formatting of values used in vCard and
214 jCard is that in jCard the specification uses date/time values
215 aligned with the extended format of [ISO.8601.2004], which is more
216 commonly used in Internet applications that make use of the JSON
217 format. The sections of this document describing the various date
218 and time formats contain more information on the use of the complete
219 representation, reduced accuracy, or truncated representation.
226Kewisch Standards Track [Page 4]
228RFC 7095 jCard January 2014
2313.2. jCard Object and Syntactic Entities (RFC 6350, Sections 6.1.1 and
234 In Sections 6.1.1 and 6.1.2 of [RFC6350], the BEGIN and END
235 properties delimit a syntactic vCard entity. In jCard, each
236 syntactic entity is represented by an array with two elements and is
237 named "jCard object". The first element is the string "vcard", and
238 the second element is an array of jCard properties as described in
239 Section 3.3, belonging to the entity.
241 Although [RFC6350] defines BEGIN and END to be properties, they MUST
242 NOT appear as properties of the jCard. Instead, the jCard object is
243 sufficient to define a vCard entity. When converting from jCard to
244 vCard, the BEGIN and END properties MUST be added to enclose the
245 properties of the jCard object.
250 /* Add properties in place of this comment */
254 Consumers of this format wishing to define content that can represent
255 multiple jCard objects within the same JSON document can use a simple
256 JSON array, each element being a single jCard object.
2583.3. Properties (RFC 6350, Section 6)
260 Each individual vCard property is represented in jCard by an array
261 with three fixed elements, followed by one or more additional
262 elements, depending on if the property is a multi-valued property as
263 described in Section 3.3 of [RFC6350].
265 The array consists of the following fixed elements:
267 1. The name of the property, as a lowercase string. The vCard
268 format specifies that property names are case insensitive and
269 recommends that they be rendered in uppercase. In jCard, they
270 MUST be in lowercase.
272 2. An object containing the parameters as described in Section 3.4.
273 If the property has no parameters, an empty object is used to
282Kewisch Standards Track [Page 5]
284RFC 7095 jCard January 2014
287 3. The type identifier string of the value, in lowercase. It is
288 important that parsers check this to determine the data type of
289 the value and that they do not rely on assumptions. For example,
290 for structured values, the data type will be "array".
292 The remaining elements of the array are used for one or more values
293 of the property. For single-value properties, the array has exactly
294 four elements; for multi-valued properties, each value is another
295 element, and there can be any number of additional elements.
297 In the following example, the "categories" property is multi-valued
298 and has two values, while all other properties are single-valued:
302 ["version", {}, "text", "4.0"],
303 ["fn", {}, "text", "John Doe"],
304 ["gender", {}, "text", "M"],
305 ["categories", {}, "text", "computers", "cameras"],
310 As described in Section 3.3.1.3, a property value may be a structured
311 property value, in which case it is represented as an array
312 encapsulated in the array that represents the overall property.
314 Strictly speaking, this means that the property value is not
315 represented in the format indicated by the type identifier but by an
316 array instead. However, the values inside the encapsulated array are
317 of the format identified by the type identifier.
319 The above also holds for multi-valued properties, where some of the
320 values may be structured property values and therefore are
321 represented as an encapsulated array.
323 A special case is where a value in an encapsulated array consists of
324 multiple components itself, in which case it is represented as yet
325 another nested array, with elements matching the value type.
326 Section 3.3.1.3 describes this in more detail.
328 The above illustrates that it's important for the parser to check the
329 format of each property value, as it might either directly match the
330 value type, or it might be a structured value where nested
331 subelements match the value type.
338Kewisch Standards Track [Page 6]
340RFC 7095 jCard January 2014
3433.3.1. Special Cases for Properties
345 This section describes some properties that have special handling
346 when converting to jCard.
3483.3.1.1. The VERSION Property
350 The vCard format specification [RFC6350] defines the "VERSION"
351 property to be mandatory. The jCard "version" property MUST be
352 represented in the corresponding jCard component, with the same value
353 as in the vCard. vCards that conform to RFC 6350 will contain the
356 Also in accordance to [RFC6350], the "version" property MUST be the
357 first element of the array containing the properties of a jCard.
3593.3.1.2. Grouping of Properties
361 In vCard [RFC6350], related properties can be grouped together using
362 a grouping construct. The grouping is accomplished by adding a
363 prefix (which consists of the group name followed by a dot) to the
366 In jCard, the same grouping is achieved through a "group" parameter
367 that holds the group name. In jCard, a property name therefore MUST
368 NOT be prefixed by a group name.
370 The "GROUP" parameter MUST NOT be used in vCard; as per [RFC6350], it
371 is merely registered to reserve the parameter, avoiding collisions.
372 Formal registration of the "GROUP" parameter is described in
3753.3.1.2.1. Group Conversion Rules
377 In jCard, the parameter's value is a single opaque string.
378 Conversion rules are as follows:
380 o From vCard to jCard, the group construct (see [RFC6350],
381 Section 3.3) is removed. In its place, the "group" parameter is
382 used. Its value is a string corresponding to the group name,
383 which is case insensitive both in vCard and jCard. The name's
384 case SHOULD be converted into lowercase.
386 o When converting from jCard to vCard, the value of the "group"
387 parameter followed by a dot is prefixed to the property name, and
388 the "group" parameter is discarded. The "GROUP" parameter MUST
389 NOT appear in the resulting vCard. Following the recommendations
390 in [RFC6350], the name's case SHOULD be converted into uppercase.
394Kewisch Standards Track [Page 7]
396RFC 7095 jCard January 2014
401 CONTACT.FN:Mr. John Q. Public\, Esq.
405 [ "fn", { "group": "CONTACT" }, "text", "Mr. John Q. Public, Esq." ]
4073.3.1.3. Structured Property Values
409 The vCard specification defines properties with structured values,
410 for example, "GENDER" or "ADR". In vCard, a structured text value
411 consists of one or multiple text components, delimited by the
412 SEMICOLON character. Its equivalent in jCard is a structured
413 property value, which is an array containing one element for each
414 text component, with empty/missing text components represented by
419 ADR:;;123 Main Street;Any Town;CA;91921-1234;U.S.A.
425 "", "", "123 Main Street",
426 "Any Town", "CA", "91921-1234", "U.S.A."
430 Some vCard properties, for example, ADR, also allow a structured
431 value element that itself has multiple values. In this case, the
432 element of the array describing the structured value is itself an
433 array with one element for each of the component's multiple values.
437 ADR:;;My Street,Left Side,Second Shack;Hometown;PA;18252;U.S.A.
450Kewisch Standards Track [Page 8]
452RFC 7095 jCard January 2014
460 ["My Street", "Left Side", "Second Shack"],
461 "Hometown", "PA", "18252", "U.S.A."
465 In both cases, the array element values MUST have the primitive type
466 that matches the jCard type identifier. In [RFC6350], there are only
467 structured text values and thus only JSON strings are used. For
468 example, extensions may define structured number or boolean values,
469 where JSON number or boolean types MUST be used.
471 Although it is allowed for a structured property value to hold just
472 one component, it is RECOMMENDED to represent it as a single text
473 value instead, omitting the array completely. Nevertheless, a simple
474 implementation MAY choose to retain the array, with a single text
475 value as its element.
477 Similarly, structured values that consist of two text components with
478 one being optional (for example, "GENDER") can be represented as a
479 single text value. Therefore, parsers of jCard data SHOULD check
480 even known property values for structured information by considering
481 the JSON data type of the value, which can be an array or a primitive
482 value. This is especially important for languages where accessing
483 array members is done by the same construct as accessing characters
488 ["gender", {}, "text", ["F", "grrrl"] ],
489 ["gender", {}, "text", "M" ]
491 Per Section 6.3.1 of [RFC6350], the component separator MUST be
492 specified even if the component value is missing. Similarly, the
493 jCard array containing the structured data MUST contain all required
494 elements, even if they are empty.
498 ADR;LABEL="123 Maple Ave\nSuite 901\nVancouver BC\nA1B 2C9\nCan
506Kewisch Standards Track [Page 9]
508RFC 7095 jCard January 2014
514 {"label":"123 Maple Ave\nSuite 901\nVancouver BC\nA1B 2C9\nCanada"},
516 ["", "", "", "", "", "", ""]
5193.4. Parameters (RFC 6350, Section 5)
521 Property parameters are represented as a JSON object where each key-
522 value pair represents the vCard parameter name and its value. The
523 name of the parameter MUST be in lowercase; the original case of the
524 parameter value MUST be preserved. For example, the "LANGUAGE"
525 property parameter is represented in jCard by the "language" key.
526 Any new vCard parameters added in the future will be converted in the
531 ["role", { "language": "tr" }, "text", "roca"],
5333.4.1. VALUE Parameter
535 vCard defines a "VALUE" property parameter (Section 5.2 of
536 [RFC6350]). This property parameter MUST NOT be added to the
537 parameters object. Instead, the value type is signaled through the
538 type identifier in the third element of the array describing the
539 property. When converting a property from vCard to jCard, the value
540 type is determined as follows:
542 1. If the property has a "VALUE" parameter, that parameter's value
543 is used as the value type.
545 2. If the property has no "VALUE" parameter but has a default value
546 type, the default value type is used.
548 3. If the property has no "VALUE" parameter and has no default value
549 type, "unknown" is used.
551 Converting from jCard into vCard is done as follows:
553 1. If the property's value type is "unknown", no "VALUE" parameter
556 2. If the property's value type is the default type for that
557 property, no "VALUE" parameter is included.
562Kewisch Standards Track [Page 10]
564RFC 7095 jCard January 2014
567 3. Otherwise, a "VALUE" parameter is included, and the value type is
568 used as the parameter value.
570 See Section 5 for information on handling unknown value types.
5723.4.2. Multi-Valued Parameters
574 In [RFC6350], some parameters allow using a comma-separated list of
575 values. To ease processing in jCard, the value for such parameters
576 MUST be represented in an array containing the separated values. The
577 array elements MUST be string values. Single-value parameters SHOULD
578 be represented using a single string value, although a more simple
579 implementation might prefer an array with one string element. An
580 example of such a parameter is the vCard "SORT-AS" parameter; more
581 such parameters may be added in extensions.
583 The vCard specification requires encapsulation between DQUOTE
584 characters if a parameter value contains a colon, a semicolon, or a
585 comma. These extra DQUOTE characters do not belong to the actual
586 parameter value and hence are not included when the parameter is
593 ["version", {}, "text", "4.0"],
595 { "sort-as": ["Harten", "Rene"] },
597 ["van der Harten", "Rene", "J.", "Sir", "R.D.O.N."]
599 ["fn", {}, "text", "Rene van der Harten"]
6043.5. Values (RFC 6350, Section 4)
606 The following subsections specify how vCard property value data types
607 (which are defined in Section 4 of [RFC6350]) are represented in
618Kewisch Standards Track [Page 11]
620RFC 7095 jCard January 2014
6233.5.1. Text (RFC 6350, Section 4.1)
625 Description: vCard "TEXT" property values are represented by a
626 property with the type identifier "text". The value elements are
627 JSON strings. For details on structured text values, see
632 ["kind", {}, "text", "group"]
6343.5.2. URI (RFC 6350, Section 4.2)
636 Description: vCard "URI" property values are represented by a
637 property with the type identifier "uri". The value elements are
642 ["source", {}, "uri", "ldap://ldap.example.com/cn=babs%20jensen"]
6443.5.3. Date (RFC 6350, Section 4.3.1)
646 Description: vCard "DATE" property values are represented by a
647 property with the type identifier "date". The value elements are
648 JSON strings with the same date value specified by [RFC6350], but
649 represented using the extended format specified in
650 [ISO.8601.2004], Section 4.1.2. If the complete representation is
651 not used, the same date format restrictions regarding reduced
652 accuracy, truncated representation, and expanded representation
653 noted in [RFC6350], Section 4.3.1 apply. Whenever the extended
654 format is not applicable, the basic format MUST be used.
658 date-complete = year "-" month "-" day ;YYYY-MM-DD
660 date-noreduc = date-complete
661 / "--" month "-" day ; --MM-DD
666 / year "-" month ; YYYY-MM
674Kewisch Standards Track [Page 12]
676RFC 7095 jCard January 2014
681 ["bday", {}, "date", "1985-04-12"],
682 ["bday", {}, "date", "1985-04"],
683 ["bday", {}, "date", "1985"],
684 ["bday", {}, "date", "--04-12"],
685 ["bday", {}, "date", "---12"]
687 This table contains possible conversions between the vCard DATE
688 format and jCard date. This information is just an example and not a
689 formal specification of the syntax. The specification can be found
690 in [ISO.8601.2000] and [ISO.8601.2004].
692 +-----------+----------+------------+
694 +-----------+----------+------------+
695 | Complete | 19850412 | 1985-04-12 |
697 | Reduced | 1985-04 | 1985-04 |
699 | Reduced | 1985 | 1985 |
701 | Truncated | --0412 | --04-12 |
703 | Truncated | --04 | --04 |
705 | Truncated | ---12 | ---12 |
706 +-----------+----------+------------+
7083.5.4. Time (RFC 6350, Section 4.3.2)
710 Description: vCard "TIME" property values are represented by a
711 property with the type identifier "time". The value elements are
712 JSON strings with the same time value specified by [RFC6350], but
713 represented using the extended format specified in
714 [ISO.8601.2004], Section 4.2. If the complete representation is
715 not used, the same time format restrictions regarding reduced
716 accuracy, decimal fraction, and truncated representation noted in
717 [RFC6350], Section 4.3.2 apply. Whenever the extended format is
718 not applicable, the basic format MUST be used. The seconds value
719 of 60 MUST only be used to account for positive "leap" seconds,
720 and the midnight hour is always represented by 00, never 24.
721 Fractions of a second are not supported by this format. In jCard,
722 UTC offsets are permitted within a time value; note that this
723 differs from jCal [JCAL], where they are not permitted.
730Kewisch Standards Track [Page 13]
732RFC 7095 jCard January 2014
737 time-notrunc = hour [":" minute [":" second]] [zone]
740 / "-" minute ":" second [zone]; -mm:ss
741 / "-" minute [zone]; -mm
742 / "--" second [zone]; --ss
746 ["x-time-local", {}, "time", "12:30:00"],
747 ["x-time-utc", {}, "time", "12:30:00Z"],
748 ["x-time-offset", {}, "time", "12:30:00-08:00"],
749 ["x-time-reduced", {}, "time", "23"],
750 ["x-time-truncated", {}, "time", "-30"]
752 This table contains possible conversions between the vCard TIME
753 format and jCard time. This information is just an example and not a
754 formal specification of the syntax. The specification can be found
755 in [ISO.8601.2000] and [ISO.8601.2004].
757 +-----------+--------+----------+
759 +-----------+--------+----------+
760 | Complete | 232050 | 23:20:50 |
762 | Reduced | 2320 | 23:20 |
764 | Reduced | 23 | 23 |
766 | Truncated | -2050 | -20:50 |
768 | Truncated | -20 | -20 |
770 | Truncated | --50 | --50 |
771 +-----------+--------+----------+
773 Also, all combinations may have any zone designator appended, as in
774 the complete representation.
7763.5.5. Date-Time (RFC 6350, Section 4.3.3)
778 Description: vCard "DATE-TIME" property values are represented by a
779 property with the type identifier "date-time". The value elements
780 are JSON strings with the same date value specified by [RFC6350],
781 but represented using the extended format specified in
782 [ISO.8601.2004], Section 4.3. If the complete representation is
786Kewisch Standards Track [Page 14]
788RFC 7095 jCard January 2014
791 not used, the same date and time format restrictions noted in
792 Sections 3.5.3 and 3.5.4 apply. Just as described in [RFC6350],
793 truncation of the date part is permitted.
797 ["anniversary", {}, "date-time", "2013-02-14T12:30:00"],
798 ["anniversary", {}, "date-time", "2013-01-10T19:00:00Z"],
799 ["anniversary", {}, "date-time", "2013-08-15T09:45:00+01:00"],
800 ["anniversary", {}, "date-time", "---15T09:45:00+01:00"]
802 This table contains possible conversions between the vCard DATE-TIME
803 format and jCard date-time. This information is just an example and
804 not a formal specification of the syntax. The specification can be
805 found in [ISO.8601.2000] and [ISO.8601.2004].
807 +----------------+----------------------+---------------------------+
808 | Representation | vCard | jCard |
809 +----------------+----------------------+---------------------------+
810 | Complete | 19850412T232050 | 1985-04-12T23:20:50 |
812 | Complete | 19850412T232050Z | 1985-04-12T23:20:50Z |
814 | Complete | 19850412T232050+0400 | 1985-04-12T23:20:50+04:00 |
816 | Complete | 19850412T232050+04 | 1985-04-12T23:20:50+04 |
818 | Reduced | 19850412T2320 | 1985-04-12T23:20 |
820 | Reduced | 19850412T23 | 1985-04-12T23 |
822 | Truncated and | --0412T2320 | --04-12T23:20 |
825 | Truncated and | --04T2320 | --04T23:20 |
828 | Truncated and | ---12T2320 | ---12T23:20 |
831 | Truncated and | --0412T2320 | --04-12T23:20 |
834 | Truncated and | --04T23 | --04T23 |
836 +----------------+----------------------+---------------------------+
842Kewisch Standards Track [Page 15]
844RFC 7095 jCard January 2014
847 As specified in [ISO.8601.2000], the lower-order components may not
848 be omitted in the date part (reduced accuracy) and the higher-order
849 components may not be omitted in the time part (truncation). Also,
850 all combinations may have any zone designator appended, as in the
851 complete representation.
8533.5.6. Date and/or Time (RFC 6350, Section 4.3.4)
855 Description: vCard "DATE-AND-OR-TIME" property values are
856 represented by a property with the type identifier "date-and-or-
857 time". The value elements are either a date-time (Section 3.5.5),
858 a date (Section 3.5.3), or a time (Section 3.5.4) value. Just as
859 described in Section 4.3.4 of [RFC6350], a stand-alone time value
860 MUST always be preceded by a "T".
864 ["bday", {}, "date-and-or-time", "2013-02-14T12:30:00"],
865 ["bday", {}, "date-and-or-time", "---22T14:00"]
866 ["bday", {}, "date-and-or-time", "1985"],
867 ["bday", {}, "date-and-or-time", "T12:30"]
8693.5.7. Timestamp (RFC 6350, Section 4.3.5)
871 Description: vCard "TIMESTAMP" property values are represented by a
872 property with the type identifier "timestamp". The value elements
873 are JSON strings with the same timestamp value specified by
874 [RFC6350], but represented using the extended format and complete
875 representation specified in [ISO.8601.2004], Section 4.3.2.
879 ["rev", {}, "timestamp", "2013-02-14T12:30:00"],
880 ["rev", {}, "timestamp", "2013-02-14T12:30:00Z"],
881 ["rev", {}, "timestamp", "2013-02-14T12:30:00-05"],
882 ["rev", {}, "timestamp", "2013-02-14T12:30:00-05:00"]
884 This table contains possible conversions between the vCard TIMESTAMP
885 format and jCard timestamp. This information is just an example and
886 not a formal specification of the syntax. The specification can be
887 found in [ISO.8601.2000] and [ISO.8601.2004].
898Kewisch Standards Track [Page 16]
900RFC 7095 jCard January 2014
903 +----------------+----------------------+---------------------------+
904 | Representation | vCard | jCard |
905 +----------------+----------------------+---------------------------+
906 | Complete | 19850412T232050 | 1985-04-12T23:20:50 |
908 | Complete | 19850412T232050Z | 1985-04-12T23:20:50Z |
910 | Complete | 19850412T232050+0400 | 1985-04-12T23:20:50+04:00 |
912 | Complete | 19850412T232050+04 | 1985-04-12T23:20:50+04 |
913 +----------------+----------------------+---------------------------+
9153.5.8. Boolean (RFC 6350, Section 4.4)
917 Description: vCard "BOOLEAN" property values are represented by a
918 property with the type identifier "boolean". The value element is
919 a JSON boolean value.
923 ["x-non-smoking", {}, "boolean", true]
9253.5.9. Integer (RFC 6350, Section 4.5)
927 Description: vCard "INTEGER" property values are represented by a
928 property with the type identifier "integer". The value elements
929 are JSON primitive number values.
933 ["x-karma-points", {}, "integer", 42]
935 JSON allows decimals (e.g., 3.14) and exponents (e.g., 2e10) to be
936 used in numeric values. jCard does not prohibit this for "integer"
937 property values. However, since vCard does not support decimals or
938 exponents in integers, any decimals and exponents MUST be eliminated
939 when converting an "integer" value type property from jCard to vCard.
9413.5.10. Float (RFC 6350, Section 4.6)
943 Description: vCard "FLOAT" property values are represented by a
944 property with the type identifier "float". The value elements are
945 JSON primitive number values.
949 ["x-grade", {}, "float", 1.3]
954Kewisch Standards Track [Page 17]
956RFC 7095 jCard January 2014
959 JSON allows exponents (e.g., 2e10) to be used in numeric values.
960 jCard does not prohibit this for "float" property values. However,
961 since vCard does not support exponents in floats, any exponents MUST
962 be eliminated when converting a "float" value type property from
9653.5.11. UTC Offset (RFC 6350, Section 4.7)
967 Description: vCard "UTC-OFFSET" property values are represented by a
968 property with the type identifier "utc-offset". The value
969 elements are JSON strings with the same UTC offset value specified
970 by [RFC6350], with the exception that the hour and minute
971 components are separated by a ":" character, for consistency with
972 the [ISO.8601.2004] timezone offset, extended format.
976 // Note: [RFC6350] mentions use of utc-offset
977 // for the TZ property as NOT RECOMMENDED
978 ["tz", {}, "utc-offset", "-05:00"]
9803.5.12. Language Tag (RFC 6350, Section 4.8)
982 Description: vCard "LANGUAGE-TAG" property values are represented by
983 a property with the type identifier "language-tag". The value
984 elements are JSON strings containing a single language-tag, as
985 defined in [RFC5646].
989 ["lang", {}, "language-tag", "de"]
9913.6. Extensions (RFC 6350, Section 6.10)
993 vCard extension properties and property parameters (those with an
994 "X-" prefix in their name) are handled in the same way as other
995 properties and property parameters: the property is represented by an
996 array, the property parameter represented by an object. The property
997 or parameter name uses the same name as for the vCard extension, but
998 in lowercase. For example, the "X-FOO" property in vCard turns into
999 the "x-foo" jCard property. See Section 5 for how to deal with
1000 default values for unrecognized extension properties or property
1010Kewisch Standards Track [Page 18]
1012RFC 7095 jCard January 2014
10154. Converting from jCard into vCard
1017 When converting property and property parameter values, the names
1018 SHOULD be converted to uppercase. Although vCard names are case
1019 insensitive, common practice is to keep them all uppercase following
1020 the actual definitions in [RFC6350].
1022 Character escaping and line folding MUST be applied to the resulting
1023 vCard data as required by [RFC6350] and [RFC6868].
1025 When converting to vCard, the "VALUE" parameter MUST be added to
1026 properties whose default value type is unknown but do not have a
1027 jCard type identifier "unknown". The "VALUE" parameter MAY be
1028 omitted for properties using the default value type. The "VALUE"
1029 parameter MUST be omitted for properties that have the jCard type
1030 identifier "unknown".
10325. Handling Unrecognized Properties or Parameters
1034 In vCard, properties can have one or more value types as specified by
1035 their definition, with one of those values being defined as the
1036 default. When a property uses its default value type, the "VALUE"
1037 property parameter does not need to be specified on the property.
1038 For example, "BDAY"'s default value type is "date-and-or-time", so
1039 "VALUE=date-and-or-time" need not be set as a property parameter.
1040 However, "BDAY" also allows a "text" value to be specified, and if
1041 that is used, "VALUE=text" has to be set as a property parameter.
1043 When new properties are defined or "X-" properties used, a vCard-to-
1044 jCard converter might not recognize them, and not know what the
1045 appropriate default value types are, yet it needs to be able to
1046 preserve the values. A similar issue arises for unrecognized
1047 property parameters.
1049 In jCard, a new "unknown" property value type is introduced. Its
1050 purpose is to allow preserving unknown property values when round-
1051 tripping between jCard and vCard. To avoid collisions, this
1052 specification reserves the "UNKNOWN" property value type in vCard.
1053 It MUST NOT be used in any vCard as specified by [RFC6350], nor any
1054 extensions to it. The type is hence registered to the "vCard Value
1055 Data Types" registry; see Section 7.2.
10575.1. Converting vCard into jCard
1059 Any property that does not include a "VALUE" property parameter and
1060 whose default value type is not known MUST be converted to a
1061 primitive JSON string. The content of that string is the unprocessed
1062 value text. Also, value type MUST be set to "unknown".
1066Kewisch Standards Track [Page 19]
1068RFC 7095 jCard January 2014
1071 To correctly implement this format, it's critical to use the value
1072 type "unknown" when the default value type is not known. If this
1073 requirement is ignored and, for example, "text" is used, additional
1074 escaping may occur that breaks round-tripping values.
1076 Any unrecognized property parameter MUST be converted to a string
1077 value, with its content set to the property parameter value text,
1078 treated as if it were a "TEXT" value.
10805.2. Converting jCard into vCard
1082 In jCard, the value type is always explicitly specified. It is
1083 converted to vCard using the vCard "VALUE" parameter, except in the
1084 following two cases:
1086 o If the value type specified in jCard matches the default value
1087 type in vCard, the "VALUE" parameter MAY be omitted.
1089 o If the value type specified in jCard is set to "unknown", the
1090 "VALUE" parameter MUST NOT be specified. The value MUST be taken
1091 over in vCard without processing.
1095 The following is an example of an unrecognized vCard property (that
1096 uses a "URI" value as its default), and the equivalent jCard
1097 representation of that property.
1101 X-COMPLAINT-URI:mailto:abuse@example.org
1105 ["x-complaint-uri", {}, "unknown", "mailto:abuse@example.org"]
1107 The following is an example of how to cope with jCard data where the
1108 parser was unable to identify the value type. Note how the "unknown"
1109 value type is not added to the vCard data, and escaping, aside from
1110 standard JSON string escaping, is not processed.
1114 ["x-coffee-data", {}, "unknown", "Stenophylla;Guinea\\,Africa"]
1118 X-COFFEE-DATA:Stenophylla;Guinea\,Africa
1122Kewisch Standards Track [Page 20]
1124RFC 7095 jCard January 2014
1127 There are no standard properties in [RFC6350] that have a default
1128 type of integer. Consequently, this example uses the following
1129 extended property that we treat as having a default type (namely,
1130 integer) known to the parser in order to illustrate how a property
1131 with a known default type would be transformed.
1135 ["x-karma-points", {}, "integer", 95]
1141 The following is an example of an unrecognized vCard property
1142 parameter (that uses a "FLOAT" value as its default) specified on a
1143 recognized vCard property, and the equivalent jCard representation of
1144 that property and property parameter.
1148 GENDER;X-PROBABILITY=0.8:M
1152 ["gender", { "x-probability": "0.8" }, "text", "M"]
11546. Security Considerations
1156 This specification defines how vCard data can be "translated" between
1157 two different data formats -- the original text format and JSON --
1158 with a one-to-one mapping to ensure all the semantic data in one
1159 format (properties, parameters, and values) are preserved in the
1160 other. It does not change the semantic meaning of the underlying
1161 data itself, or impose or remove any security considerations that
1162 apply to the underlying data.
1164 The use of JSON as a format does have its own inherent security risks
1165 as discussed in Section 7 of [RFC4627]. Even though JSON is
1166 considered a safe subset of JavaScript, it should be kept in mind
1167 that a flaw in the parser for JSON data could still impose a threat
1168 that doesn't arise with conventional vCard data.
1170 With this in mind when using jCard, the parser for JSON data should
1171 be aware of the security implications. For example, the use of
1172 JavaScript's eval() function is only allowed using the regular
1173 expression in Section 6 of [RFC4627]. A native parser with full
1174 awareness of the JSON format should be preferred.
1178Kewisch Standards Track [Page 21]
1180RFC 7095 jCard January 2014
1183 In addition, it is expected that this new format will result in vCard
1184 data being more widely disseminated (e.g., with use in web
1185 applications rather than just dedicated "contact managers").
1187 In all cases, application developers have to conform to the semantics
1188 of the vCard data as defined by [RFC6350] and associated extensions,
1189 and all of the security considerations described in Section 9 of
1190 [RFC6350], or any associated extensions, are applicable.
11927. IANA Considerations
1194 This document defines a MIME media type for use with vCard in JSON
1195 data. This media type SHOULD be used for the transfer of calendaring
1198 Type name: application
1200 Subtype name: vcard+json
1202 Required parameters: none
1204 Optional parameters: "version", as defined for the text/vcard media
1205 type in [RFC6350], Section 10.1.
1207 Encoding considerations: Same as encoding considerations of
1208 application/json as specified in [RFC4627], Section 6.
1210 Security considerations: See Section 6.
1212 Interoperability considerations: This media type provides an
1213 alternative format for vCard data based on JSON.
1215 Published specification: This specification.
1217 Applications which use this media type: Applications that currently
1218 make use of the text/vcard media type can use this as an
1219 alternative. Similarly, applications that use the application/
1220 json media type to transfer directory data can use this to further
1221 specify the content.
1223 Fragment identifier considerations: N/A
1234Kewisch Standards Track [Page 22]
1236RFC 7095 jCard January 2014
1239 Additional information:
1241 Deprecated alias names for this type: N/A
1243 Magic number(s): N/A
1245 File extension(s): N/A
1247 Macintosh file type code(s): N/A
1249 Person & email address to contact for further information:
1252 Intended usage: COMMON
1254 Restrictions on usage: There are no restrictions on where this media
1257 Author: See the "Author's Address" section of this document.
1259 Change controller: IETF
12617.1. GROUP vCard Parameter
1263 IANA has added the "GROUP" parameter to the "vCard Parameters"
1264 registry, initialized in Section 10.3.2 of [RFC6350]. Usage of the
1265 "GROUP" parameter is further described in Section 3.3.1.2 of this
1270 Parameter name: GROUP
1272 Purpose: To simplify the jCard format.
1274 Description: The "GROUP" parameter is reserved for the exclusive use
1275 of the jCard format described in this document. It MUST NOT be
1276 used in plain vCard [RFC6350], nor in xCard [RFC6351].
1278 Format definition: When converting from jCard to vCard, the value of
1279 the "GROUP" parameter is used as part of the property name.
1280 Therefore, the value is restricted to characters allowed in
1281 property names, namely ALPHA, DIGIT, and "-" characters. When
1282 used, the "GROUP" parameter MUST NOT be empty.
1290Kewisch Standards Track [Page 23]
1292RFC 7095 jCard January 2014
1295 Example: As this registration serves as a reservation of the "GROUP"
1296 parameter so that it is not used in vCard, there is no applicable
1297 vCard example. Examples of its usage in jCard can be found in
13007.2. UNKNOWN vCard Value Data Type
1302 IANA has added the "UNKNOWN" value data type to the "vCard Value Data
1303 Types" registry, initialized in Section 10.3.3 of [RFC6350]. Usage
1304 of the "UNKNOWN" type is further described in Section 5 of this
1309 Purpose: To allow preserving property values whose default value
1310 type is not known during round-tripping between jCard and vCard.
1312 Format definition: (Not applicable)
1314 Description: The "UNKNOWN" value data type is reserved for the
1315 exclusive use of the jCard format. It MUST NOT be used in plain
1318 Example: As this registration serves as a reservation of the
1319 "UNKNOWN" type so that it is not used in vCard, there is no
1320 applicable vCard example. Examples of its usage in jCard can be
1321 found in this document.
1325 The author would like to thank the following for their valuable
1326 contributions: Cyrus Daboo, Mike Douglass, William Gill, Erwin Rehme,
1327 Dave Thewlis, Simon Perreault, Michael Angstadt, Peter Saint-Andre,
1328 Bert Greevenbosch, and Javier Godoy. This specification originated
1329 from the work of the XML-JSON technical committee of the Calendaring
1330 and Scheduling Consortium.
13349.1. Normative References
1337 International Organization for Standardization, "Data
1338 elements and interchange formats -- Information
1339 interchange -- Representation of dates and times", ISO
1340 8601, December 2000.
1346Kewisch Standards Track [Page 24]
1348RFC 7095 jCard January 2014
1352 International Organization for Standardization, "Data
1353 elements and interchange formats -- Information
1354 interchange -- Representation of dates and times", ISO
1355 8601, December 2004.
1357 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1358 Requirement Levels", BCP 14, RFC 2119, March 1997.
1360 [RFC4627] Crockford, D., "The application/json Media Type for
1361 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
1363 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
1364 Specifications: ABNF", STD 68, RFC 5234, January 2008.
1366 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying
1367 Languages", BCP 47, RFC 5646, September 2009.
1369 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
1372 [RFC6868] Daboo, C., "Parameter Value Encoding in iCalendar and
1373 vCard", RFC 6868, February 2013.
13759.2. Informative References
1377 [JCAL] Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON
1378 format for iCalendar", Work in Progress, December 2013.
1380 [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling
1381 Core Object Specification (iCalendar)", RFC 5545,
1384 [RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML
1385 Format for iCalendar", RFC 6321, August 2011.
1387 [RFC6351] Perreault, S., "xCard: vCard XML Representation", RFC
1390 [calconnect-artifacts]
1391 The Calendaring and Scheduling Consortium, "Code Artifacts
1392 and Schemas", <http://www.calconnect.org/artifacts.shtml>.
1402Kewisch Standards Track [Page 25]
1404RFC 7095 jCard January 2014
1407Appendix A. ABNF Syntax
1409 Below is the ABNF syntax as per [RFC5234] for vCard in JSON. ABNF
1410 symbols not described here are taken from [RFC4627]. The syntax is
1411 non-normative and given for reference only.
1413 The numeric section numbers given in the comments refer to sections
1414 in [RFC6350]. Additional semantic restrictions apply, especially
1415 regarding the allowed properties and subcomponents per component.
1416 Details on these restrictions can be found in this document and
1419 Additional ABNF syntax may be available on the Internet at
1420 [calconnect-artifacts].
1422 ; A jCard object uses the name "vcard" and a properties array.
1423 ; Restrictions to which properties may be specified are to
1424 ; be taken from RFC 6350.
1425 jcardobject = begin-array
1426 DQUOTE component-name DQUOTE value-separator
1430 ; A jCard property consists of the name string, parameters object,
1431 ; type string, and one or more values as specified in this document.
1432 property = begin-array
1433 DQUOTE property-name DQUOTE value-separator
1434 params-object value-separator
1435 DQUOTE type-name DQUOTE
1436 property-value *(value-separator property-value)
1438 properties-array = begin-array
1439 [ property *(value-separator property) ]
1442 ; Property values depend on the type-name. Aside from the value types
1443 ; mentioned here, extensions may make use of other JSON value types.
1444 property-value = simple-prop-value / structured-prop-value
1445 simple-prop-value = string / number / true / false
1446 structured-prop-value =
1448 [ structured-element *(value-separator structured-element) ]
1451 ; Each structured element may have multiple values if
1452 ; semantically allowed.
1453 structured-element = simple-prop-value / structured-multi-prop
1458Kewisch Standards Track [Page 26]
1460RFC 7095 jCard January 2014
1463 structured-multi-prop =
1465 [ simple-prop-value *(value-separator simple-prop-value) ]
1468 ; The jCard params-object is a JSON object that follows the semantic
1469 ; guidelines described in this document.
1470 params-object = begin-object
1471 [ params-member *(value-separator params-member) ]
1473 params-member = DQUOTE param-name DQUOTE name-separator param-value
1474 param-value = string / param-multi
1475 param-multi = begin-array
1476 [ string *(value-separator string) ]
1479 ; The type MUST be a valid type as described by this document. New
1480 ; value types can be added by extensions.
1481 type-name = "text" / "uri" / "date" / "time" / "date-time" /
1482 "boolean" / "integer" / "float" / "utc-offset" /
1483 "language-tag" / x-type
1485 ; Property, parameter, and type names MUST be lowercase. Additional
1486 ; semantic restrictions apply as described by this document and
1488 component-name = lowercase-name
1489 property-name = lowercase-name
1490 param-name = lowercase-name
1491 x-type = lowercase-name
1492 lowercase-name = 1*(%x61-7A / DIGIT / "-")
1496 This section contains an example of a vCard object with its jCard
1499B.1. Example: vCard of the Author of RFC 6350
1506 N:Perreault;Simon;;;ing. jr,M.Sc.
1508 ANNIVERSARY:20090808T1430-0500
1514Kewisch Standards Track [Page 27]
1516RFC 7095 jCard January 2014
1520 ORG;TYPE=work:Viagenie
1521 ADR;TYPE=work:;Suite D2-630;2875 Laurier;
1522 Quebec;QC;G1V 2M2;Canada
1523 TEL;VALUE=uri;TYPE="work,voice";PREF=1:tel:+1-418-656-9254;ext=102
1524 TEL;VALUE=uri;TYPE="work,cell,voice,video,text":tel:+1-418-262-6501
1525 EMAIL;TYPE=work:simon.perreault@viagenie.ca
1526 GEO;TYPE=work:geo:46.772673,-71.282945
1527 KEY;TYPE=work;VALUE=uri:
1528 http://www.viagenie.ca/simon.perreault/simon.asc
1530 URL;TYPE=home:http://nomis80.org
1537 ["version", {}, "text", "4.0"],
1538 ["fn", {}, "text", "Simon Perreault"],
1542 ["Perreault", "Simon", "", "", ["ing. jr", "M.Sc."]]
1544 ["bday", {}, "date-and-or-time", "--02-03"],
1548 "2009-08-08T14:30:00-05:00"
1550 ["gender", {}, "text", "M"],
1551 ["lang", { "pref": "1" }, "language-tag", "fr"],
1552 ["lang", { "pref": "2" }, "language-tag", "en"],
1553 ["org", { "type": "work" }, "text", "Viagenie"],
1570Kewisch Standards Track [Page 28]
1572RFC 7095 jCard January 2014
1576 { "type": ["work", "voice"], "pref": "1" },
1578 "tel:+1-418-656-9254;ext=102"
1581 { "type": ["work", "cell", "voice", "video", "text"] },
1583 "tel:+1-418-262-6501"
1588 "simon.perreault@viagenie.ca"
1590 ["geo", { "type": "work" }, "uri", "geo:46.772673,-71.282945"],
1594 "http://www.viagenie.ca/simon.perreault/simon.asc"
1596 ["tz", {}, "utc-offset", "-05:00"],
1597 ["url", { "type": "home" }, "uri", "http://nomis80.org"]
1605 650 Castro Street, Suite 300
1606 Mountain View, CA 94041
1609 EMail: mozilla@kewis.ch
1610 URI: http://www.mozilla.org/
1626Kewisch Standards Track [Page 29]