draft-ietf-jcardcal-jcard-05.txt   draft-ietf-jcardcal-jcard-06.txt 
JSON data formats for vCard and iCalendar P. Kewisch JSON data formats for vCard and iCalendar P. Kewisch
Internet-Draft Mozilla Internet-Draft Mozilla
Intended status: Standards Track July 14, 2013 Intended status: Standards Track September 26, 2013
Expires: January 15, 2014 Expires: March 30, 2014
jCard: The JSON format for vCard jCard: The JSON format for vCard
draft-ietf-jcardcal-jcard-05 draft-ietf-jcardcal-jcard-06
Abstract Abstract
This specification defines "jCard", a JSON format for vCard data. This specification defines "jCard", a JSON format for vCard data.
The vCard data format is a text format for representing and
exchanging information about individuals and other entities, for
example telephone numbers, email addresses, structured names and
delivery addresses. JSON is a lightweight, text-based, language-
independent data interchange format commonly used in internet
applications.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 15, 2014. This Internet-Draft will expire on March 30, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in This Document . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 4
3. Converting from vCard to jCard . . . . . . . . . . . . . . . 4 3. Converting from vCard to jCard . . . . . . . . . . . . . . . 4
3.1. Pre-processing . . . . . . . . . . . . . . . . . . . . . 4 3.1. Pre-processing . . . . . . . . . . . . . . . . . . . . . 4
3.2. Properties (RFC6350 section 6) . . . . . . . . . . . . . 5 3.2. jCard Object and Syntactic Entities (RFC6350 section
3.2.1. Special Cases for Properties . . . . . . . . . . . . 6 6.1.1 and 6.1.2) . . . . . . . . . . . . . . . . . . . . 5
3.2.1.1. The VERSION Property . . . . . . . . . . . . . . 6 3.3. Properties (RFC6350 section 6) . . . . . . . . . . . . . 5
3.2.1.2. Multi-valued Properties . . . . . . . . . . . . . 6 3.3.1. Special Cases for Properties . . . . . . . . . . . . 7
3.2.1.3. Grouping of Properties . . . . . . . . . . . . . 6 3.3.1.1. The VERSION Property . . . . . . . . . . . . . . 7
3.2.1.4. Structured Property Values . . . . . . . . . . . 7 3.3.1.2. Grouping of Properties . . . . . . . . . . . . . 7
3.3. Parameters (RFC6350 Section 5) . . . . . . . . . . . . . 9 3.3.1.3. Structured Property Values . . . . . . . . . . . 8
3.3.1. VALUE parameter . . . . . . . . . . . . . . . . . . . 10 3.4. Parameters (RFC6350 Section 5) . . . . . . . . . . . . . 10
3.3.2. Multi-value Parameters . . . . . . . . . . . . . . . 10 3.4.1. VALUE parameter . . . . . . . . . . . . . . . . . . . 11
3.4. Values (RFC6350 Section 4) . . . . . . . . . . . . . . . 10 3.4.2. Multi-value Parameters . . . . . . . . . . . . . . . 11
3.4.1. Text (RFC6350 Section 4.1) . . . . . . . . . . . . . 11 3.5. Values (RFC6350 Section 4) . . . . . . . . . . . . . . . 12
3.4.2. URI (RFC6350 Section 4.2) . . . . . . . . . . . . . . 11 3.5.1. Text (RFC6350 Section 4.1) . . . . . . . . . . . . . 12
3.4.3. Date (RFC6350 Section 4.3.1) . . . . . . . . . . . . 11 3.5.2. URI (RFC6350 Section 4.2) . . . . . . . . . . . . . . 13
3.4.4. Time (RFC6350 Section 4.3.2) . . . . . . . . . . . . 12 3.5.3. Date (RFC6350 Section 4.3.1) . . . . . . . . . . . . 13
3.4.5. Date-Time (RFC6350 Section 4.3.3) . . . . . . . . . . 13 3.5.4. Time (RFC6350 Section 4.3.2) . . . . . . . . . . . . 14
3.4.6. Date and/or Time (RFC6350 Section 4.3.4) . . . . . . 15 3.5.5. Date-Time (RFC6350 Section 4.3.3) . . . . . . . . . . 15
3.4.7. Timestamp (RFC6350 Section 4.3.5) . . . . . . . . . . 15 3.5.6. Date and/or Time (RFC6350 Section 4.3.4) . . . . . . 17
3.4.8. Boolean (RFC6350 Section 4.4) . . . . . . . . . . . . 16 3.5.7. Timestamp (RFC6350 Section 4.3.5) . . . . . . . . . . 17
3.4.9. Integer (RFC6350 Section 4.5) . . . . . . . . . . . . 16 3.5.8. Boolean (RFC6350 Section 4.4) . . . . . . . . . . . . 18
3.4.10. Float (RFC6350 Section 4.6) . . . . . . . . . . . . . 16 3.5.9. Integer (RFC6350 Section 4.5) . . . . . . . . . . . . 18
3.4.11. UTC Offset (RFC6350 Section 4.7) . . . . . . . . . . 16 3.5.10. Float (RFC6350 Section 4.6) . . . . . . . . . . . . . 18
3.4.12. Language Tag (RFC6350 Section 4.8) . . . . . . . . . 17 3.5.11. UTC Offset (RFC6350 Section 4.7) . . . . . . . . . . 19
3.5. Extensions (RFC6350 Section 6.10) . . . . . . . . . . . . 17 3.5.12. Language Tag (RFC6350 Section 4.8) . . . . . . . . . 19
4. Converting from jCard into vCard . . . . . . . . . . . . . . 17 3.6. Extensions (RFC6350 Section 6.10) . . . . . . . . . . . . 19
5. Handling Unrecognized Properties or Parameters . . . . . . . 18 4. Converting from jCard into vCard . . . . . . . . . . . . . . 19
5.1. Converting vCard into jCard . . . . . . . . . . . . . . . 19 5. Handling Unrecognized Properties or Parameters . . . . . . . 20
5.2. Converting jCard into vCard . . . . . . . . . . . . . . . 19 5.1. Converting vCard into jCard . . . . . . . . . . . . . . . 21
5.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 19 5.2. Converting jCard into vCard . . . . . . . . . . . . . . . 21
5.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 21
6. Implementation Status (to be removed prior to publication as 6. Implementation Status (to be removed prior to publication as
an RFC) . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 an RFC) . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7. Security Considerations . . . . . . . . . . . . . . . . . . . 21 7. Security Considerations . . . . . . . . . . . . . . . . . . . 23
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
8.1. GROUP vCard Parameter . . . . . . . . . . . . . . . . . . 22 8.1. GROUP vCard Parameter . . . . . . . . . . . . . . . . . . 25
8.2. UNKNOWN vCard Value Data Type . . . . . . . . . . . . . . 23 8.2. UNKNOWN vCard Value Data Type . . . . . . . . . . . . . . 25
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 26
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 26
10.1. Normative References . . . . . . . . . . . . . . . . . . 23 10.1. Normative References . . . . . . . . . . . . . . . . . . 26
10.2. Informative References . . . . . . . . . . . . . . . . . 24 10.2. Informative References . . . . . . . . . . . . . . . . . 27
Appendix A. ABNF Schema . . . . . . . . . . . . . . . . . . . . 24
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 26
B.1. Example: vCard of the author of RFC6350 . . . . . . . . . 26
B.1.1. vCard Data . . . . . . . . . . . . . . . . . . . . . 26
B.1.2. jCard Data . . . . . . . . . . . . . . . . . . . . . 27
Appendix C. Change History (to be removed prior to publication
as an RFC) . . . . . . . . . . . . . . . . . . . . . 28
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 30 Appendix A. ABNF Schema . . . . . . . . . . . . . . . . . . . . 27
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 29
B.1. Example: vCard of the author of RFC6350 . . . . . . . . . 29
B.1.1. vCard Data . . . . . . . . . . . . . . . . . . . . . 29
B.1.2. jCard Data . . . . . . . . . . . . . . . . . . . . . 29
Appendix C. Change History (to be removed prior to publication
as an RFC) . . . . . . . . . . . . . . . . . . . . . 31
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 32
1. Introduction 1. Introduction
The vCard data format [RFC6350] provides for the capture and exchange The vCard data format [RFC6350] provides for the capture and exchange
of information normally stored within an address book or directory of information normally stored within an address book or directory
application. The vCard format has gone through multiple revisions, application. The vCard format has gone through multiple revisions,
most recently vCard 4. The purpose of this specification is to most recently vCard 4.
define "jCard", a JSON format for vCard data. One main advantage to
using a JSON-based format as defined in [RFC4627] over the classic
vCard format is easier processing for JavaScript based widgets and
libraries, especially in the scope of web-based applications.
As certain similarities exist between vCard and the iCalendar data As certain similarities exist between vCard and the iCalendar data
format [RFC5545], there is also an effort to define a JSON-based data format [RFC5545], there is also an effort to define a JSON-based data
format for calendar information called jCal [I-D.ietf-jcardcal-jcal] format for calendar information called jCal [I-D.ietf-jcardcal-jcal]
that parallels the format defined in this specification. that parallels the format defined in this specification. The term
JSON describes the JavaScript Object Notation defined in [RFC4627].
The purpose of this specification is to define "jCard", a JSON format The purpose of this specification is to define "jCard", a JSON format
for vCard data. One main advantage to using a JSON-based format as for vCard data. One main advantage to using a JSON-based format over
defined in [RFC4627] over the classic vCard format is easier the classic vCard format is easier processing for JavaScript based
processing for JavaScript based widgets and libraries, especially in widgets and libraries, especially in the scope of web-based
the scope of web-based applications. applications.
The key design considerations are essentially the same as those for The key design considerations are essentially the same as those for
[I-D.ietf-jcardcal-jcal] and [RFC6321], that is: [I-D.ietf-jcardcal-jcal] and [RFC6321], that is:
Round-tripping (converting a vCard instance to jCard and back) Round-tripping (converting a vCard instance to jCard and back)
will give the same semantic result as the starting point. For will give the same semantic result as the starting point. For
example, all components, properties and property parameters are example, all components, properties and property parameters are
guaranteed to be preserved. guaranteed to be preserved.
Ordering of elements will not necessarily be preserved. Ordering of elements and case of property and parameter names will
not necessarily be preserved.
Preserve the semantics of the vCard data. While a simple consumer The vCard data semantics are to be preserved, allowing a simple
can easily browse the data in jCard, a full understanding of vCard consumer to easily browse the data in jCard. A full understanding
is still required in order to modify and/or fully comprehend the of vCard is still required in order to modify and/or fully
directory data. comprehend the directory data.
Ability to handle many extensions to the underlying vCard Extensions to the underlying vCard specification must not lead to
specification without requiring an update to this document. requiring an update to jCard.
2. Conventions Used in This Document 2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
The underlying format used for jCard is JSON. Consequently, the The underlying format used for jCard is JSON. Consequently, the
terms "object" and "array" as well as the four primitive types are to terms "object" and "array" as well as the four primitive types
be interpreted as described in Section 1 of [RFC4627]. (strings, numbers, booleans, and null) are to be interpreted as
described in Section 1 of [RFC4627].
Some examples in this document contain "partial" JSON documents used Some examples in this document contain "partial" JSON documents used
for illustrative purposes. In these examples, three periods "..." for illustrative purposes. In these examples, three periods "..."
are used to indicate a portion of the document that has been removed are used to indicate a portion of the document that has been removed
for compactness. for compactness.
3. Converting from vCard to jCard 3. Converting from vCard to jCard
This section describes how vCard objects are converted to jCard using This section describes how vCard objects are converted to jCard using
a simple mapping between the vCard data model and JSON elements. a simple mapping between the vCard data model and JSON elements.
In [RFC6350], vCard objects are comprised of a set of "properties", In [RFC6350], vCard objects are comprised of a set of "properties",
"parameters" and "values". The top level of a vCard object contains "parameters" and "values". The top level of a vCard object contains
"properties". A "property" has a "value" and a set of zero or more "properties". A "property" has a "value" and a set of zero or more
"parameters". Each of these entities have a representation in jCard, "parameters". Each of these entities have a representation in jCard,
defined in the following sections. The representation of a vCard defined in the following sections. The representation of a vCard
object in JSON will be named "jCard component" throughout this object in JSON will be named "jCard object" throughout this document.
document.
3.1. Pre-processing 3.1. Pre-processing
vCard uses a line folding mechanism to limit lines of data to a vCard uses a line folding mechanism to limit lines of data to a
maximum line length (typically 72 characters) to ensure maximum maximum line length (typically 75 octets) to ensure maximum
likelihood of preserving data integrity as it is transported via likelihood of preserving data integrity as it is transported via
various means (e.g., email) - see Section 3.2 of [RFC6350]. Prior to various means (e.g., email) - see Section 3.2 of [RFC6350].
converting vCard data into jCard all folded lines MUST be unfolded.
vCard data uses an "escape" character sequence for text values and vCard data uses an "escape" character sequence for text values and
property parameter values. See Section 3.4 of [RFC6350] as well as property parameter values. See Section 3.4 of [RFC6350] as well as
[RFC6868]. When such text elements are converted into jCard, the [RFC6868].
vCard escaping MUST be removed first. The only escaping that may be
applied is any escaping mandated by JSON. When converting from vCard to jCard, first vCard lines MUST be
unfolded. Afterwards, any vCard escaping MUST be unescaped. Finally
JSON escaping (e.g., for control characters) MUST be applied.
The reverse order applies when converting from jCard to vCard.
First, JSON escaping MUST be unescaped. Afterwards, vCard escaping
MUST be applied. Finally, long lines SHOULD be folded as described
in [RFC6350].
One key difference in the formatting of values used in vCard and One key difference in the formatting of values used in vCard and
jCard is that in jCard the specification uses date/time values jCard is that in jCard the specification uses date/time values
aligned with the extended format of [ISO.8601.2004]. The sections of aligned with the extended format of [ISO.8601.2004], which is more
this document describing the various date and time formats contain commonly used in internet applications that make use of the JSON
more information on the use of the complete representation, reduced format. The sections of this document describing the various date
accuracy or truncated representation. and time formats contain more information on the use of the complete
representation, reduced accuracy or truncated representation.
3.2. Properties (RFC6350 section 6) 3.2. jCard Object and Syntactic Entities (RFC6350 section 6.1.1 and
6.1.2)
In [RFC6350] Section 6.1.1 and 6.1.2, the "BEGIN" and "END"
properties delimit a syntactic vCard entity. In jCard, each
syntactic entity is represented by an array with two elements and is
named "jCard object". The first element is the string "vcard", the
second element is an array of jCard properties as described in
Section 3.3, belonging to the entity.
Although [RFC6350] defines BEGIN and END to be properties, they MUST
NOT appear as properties of the jCard. Instead, the jCard object is
sufficient to define a vCard entity. When converting from jCard to
vCard, the BEGIN and END properties MUST be added to enclose the
properties of the jCard object.
Example:
["vcard", [
/* Add properties in place of this comment */
]
]
Consumers of this format wishing to define content that can contain
multiple syntactic entities within the same JSON document can use a
simple JSON array, each element being a jCard object.
3.3. Properties (RFC6350 section 6)
Each individual vCard property is represented in jCard by an array Each individual vCard property is represented in jCard by an array
with three fixed elements, followed by one or more additional with three fixed elements, followed by one or more additional
elements, depending on if the property is a multi-value property as elements, depending on if the property is a multi-value property as
described in Section 3.3 of [RFC6350]. described in Section 3.3 of [RFC6350].
The array consists of the following fixed elements: The array consists of the following fixed elements:
1. The name of the property as a string, but in lowercase. 1. The name of the property, as a lowercase string. The vCard
format specifies that property names are case-insensitive, and
2. An object containing the parameters as described in Section 3.3. recommends that they be rendered in uppercase. In jCard, they
MUST be in lowercase.
3. The type identifier string of the value, in lowercase. 2. An object containing the parameters as described in Section 3.4.
If the property has no parameters, an empty object is used to
represent that.
The remaining elements of the array are used for the value of the 3. The type identifier string of the value, in lowercase. It is
property. For single-value properties, the array MUST have exactly important that parsers check this to determine the data type of
four elements, for multi-valued properties as described in the value, and that they do not rely on assumptions. For
Section 3.2.1.2 there can be any number of additional elements. example, for structured values the data type will be "array".
The array describing the property can then be inserted into the array The remaining elements of the array are used for one or more values
designated for properties in the jCard component. of the property. For single-value properties, the array has exactly
four elements; for multi-valued properties, each value is another
element, and there can be any number of additional elements.
Example: Single-valued properties example:
["vcard", ["vcard",
[ [
["version", {}, "text", "4.0"], ["version", {}, "text", "4.0"],
["fn", {}, "text", "John Doe"], ["fn", {}, "text", "John Doe"],
["gender", {}, "text", "M"], ["gender", {}, "text", "M"],
... ...
] ]
] ]
The property parameters in the second element of the property array Multi-valued property example:
associate a set of parameter names with their respective value.
Parameters are further described in Section 3.3.
To allow for a cleaner implementation, the parameter object MUST be ["vcard",
present even if there are no parameters. In this case, an empty [
object MUST be used. ["categories", {}, "text", "computers", "cameras"],
...
]
]
As described in Section 3.2.1.4, it is important for a parser check As described in Section 3.3.1.3, a property value may be a structured
the data type of the value even if it is assumed to be a string in property value, in which case it is represented as an array
most cases. The value could turn out to be a structured value, in encapsulated in the array that represents the overall property.
which case the data type is an array.
3.2.1. Special Cases for Properties Strictly speaking, this means that the property value is not
represented in the format indicated by the type identifier, but by an
array instead. However, the values inside the encapsulated array are
of the format identified by the type identifier.
This section describes some properties that have special handling The above also holds for multi-valued properties, where some of the
when converting to jCard. values may be structured property values, and therefore are
represented as an encapsulated array.
3.2.1.1. The VERSION Property A special case is where a value in an encapsulated array consists of
multiple components itself, in which case it is represented as yet
another nested array, with elements matching the value type.
Section 3.3.1.3 describes this in more detail.
The vCard format is versioned. [RFC6350] defines the VERSION The above illustrates the importance for the parser to check the
property to be mandatory, therefore a "version" property MUST also be format of each property value, as it might either directly match the
specified in a jCard component. Similarly, the value of the version value type, or it might be a structured value where nested sub-
property MUST be "4.0". elements match the value type.
3.2.1.2. Multi-valued Properties 3.3.1. Special Cases for Properties
Various vCard properties defined in [RFC6350], for example the This section describes some properties that have special handling
"CATEGORIES" property, are defined as multi-valued properties. In when converting to jCard.
jCal these properties are added as further members of the array
describing the property.
Note that additional multi-valued properties may be added in 3.3.1.1. The VERSION Property
extensions to the iCalendar format.
Example: The vCard format specification [RFC6350] defines the VERSION property
to be mandatory. The "version" property MUST be represented in the
corresponding jCard component, with the same value as in the vCard.
vCards that conform to RFC 6350 will contain the value "4.0".
["vcard", Also in accordance to [RFC6350], the "version" property MUST be the
[ first element of the array containing the properties of a jCard.
["categories", {}, "text", "computers", "cameras"],
...
]
]
3.2.1.3. Grouping of Properties 3.3.1.2. Grouping of Properties
[RFC6350] Section 3.3 defines a grouping construct that is used to In vCard [RFC6350] related properties can be grouped together using a
group related properties together. To eliminate the need for an grouping construct. The grouping is accomplished by adding a prefix
extra group syntax in jCard, thus unifying the general syntax with to the property name, which consists of the group name followed by a
that of jCal, this specification introduces a "group" parameter, that dot.
holds the group name. The parameter MUST NOT be used in vCard as per
[RFC6350], it is merely registered to reserve the parameter, avoiding In jCard the same grouping is achieved through a "group" parameter,
collisions. that holds the group name. In jCard a property name therefore MUST
NOT be prefixed by a group name.
The "GROUP" parameter MUST NOT be used in vCard as per [RFC6350] it
is merely registered to reserve the parameter, avoiding collisions.
Namespace: <empty> Namespace: <empty>
Parameter name: GROUP Parameter name: GROUP
Purpose: To simplify the jCard format. Purpose: To simplify the jCard format.
Description: The GROUP parameter is reserved for the exclusive use Description: The GROUP parameter is reserved for the exclusive use
of the jCard format RFCTODO. It MUST NOT be used in plain vCard of the jCard format described in this document. It MUST NOT be
[RFC6350], nor in xCard [RFC6351]. used in plain vCard [RFC6350], nor in xCard [RFC6351].
Format definition: (Not applicable) Format definition: (Not applicable)
Example: As this registration serves as a reservation of the GROUP Example: As this registration serves as a reservation of the GROUP
parameter so that it is not used in vCard, there is no applicable parameter so that it is not used in vCard, there is no applicable
vCard example. For examples of its usage in jCard, see RFCTODO vCard example. Examples of its usage in jCard can be found in
this document.
3.2.1.3.1. Group Conversion Rules 3.3.1.2.1. Group Conversion Rules
In jCard, the parameter's value is a single opaque string. In jCard, the parameter's value is a single opaque string.
Conversion rules are as follows: Conversion rules are as follows:
o From vCard to jCard, the group construct (see [RFC6350], o From vCard to jCard, the group construct (see [RFC6350],
Section 3.3, Page 7) is removed. In its place, the GROUP Section 3.3, Page 7) is removed. In its place, the "group"
parameter is added (lowercased, as any other parameter). Its parameter is used. Its value is a string corresponding to the
value is a string corresponding to the group name. The name's group name. The name's case MUST be preserved.
case MUST be preserved intact.
o From jCard to vCard, the reverse procedure is performed. The o When converting from jCard to vCard, the value of the "group"
GROUP parameter MUST NOT appear in the resulting vCard. parameter followed by a dot is prefixed to the property name, and
the "group" parameter is discarded. The "GROUP" parameter MUST
NOT appear in the resulting vCard.
Example: Example:
CONTACT.FN:Mr. John Q. Public\, Esq. CONTACT.FN:Mr. John Q. Public\, Esq.
is equivalent to: is equivalent to:
[ "fn", { "group": "CONTACT" }, "text", "Mr. John Q. Public, Esq." ] [ "fn", { "group": "CONTACT" }, "text", "Mr. John Q. Public, Esq." ]
3.2.1.4. Structured Property Values 3.3.1.3. Structured Property Values
The vCard specification defines properties with structured values, The vCard specification defines properties with structured values,
for example GENDER or ADR. A structured value is defined as a value for example GENDER or ADR. In vCard, a structured text value
that contains multiple text components, delimited by the SEMICOLON consists of one or multiple text components, delimited by the
character. In jCard, the property value is an array containing one SEMICOLON character. Its equivalent in jCard is a structured
element for each text component. property value, which is an array containing one element for each
text component, with empty/missing text components represented by
zero-length strings.
vCard Example: vCard Example:
ADR:;;123 Main Street;Any Town;CA;91921-1234;U.S.A. ADR:;;123 Main Street;Any Town;CA;91921-1234;U.S.A.
jCard Example: jCard Example:
["adr", {}, "text", ["adr", {}, "text",
[ [
"", "", "123 Main Street", "", "", "123 Main Street",
skipping to change at page 8, line 39 skipping to change at page 9, line 46
"Hometown", "PA", "18252", "U.S.A." "Hometown", "PA", "18252", "U.S.A."
] ]
] ]
In both cases, the array element values MUST have the primitive type In both cases, the array element values MUST have the primitive type
that matches the jCard type identifier. In [RFC6350], there are only that matches the jCard type identifier. In [RFC6350], there are only
structured text values and thus only JSON strings are used. structured text values and thus only JSON strings are used.
Extensions may for example define structured number or boolean Extensions may for example define structured number or boolean
values, where JSON number or boolean types MUST be used. values, where JSON number or boolean types MUST be used.
If a multi-valued text component is changed to hold only one value, Although it is allowed for a structured property value to hold just
the text component SHOULD be represented as a single primitive value, one component, it is RECOMMENDED to represent it as a single text
dropping the array completely. Nevertheless, a more simple value instead, omitting the array completely. Nevertheless, a simple
implementation might choose to retain the array, with a single implementation MAY choose to retain the array, with a single text
primitive value as its element. value as its element.
Similarly, structured values that consist of two text components with Similarly, structured values that consist of two text components with
one being optional (for example, GENDER) can be represented as a one being optional (for example, GENDER) can be represented as a
single text value. Therefore, parsers of jCard data SHOULD check single text value. Therefore, parsers of jCard data SHOULD check
even known property values for structured information by considering even known property values for structured information by considering
the JSON data type of the value, which can be an array or a primitive the JSON data type of the value, which can be an array or a primitive
value. This is especially important for languages where accessing value. This is especially important for languages where accessing
array members is done by the same construct as accessing characters array members is done by the same construct as accessing characters
of a string. of a string.
skipping to change at page 9, line 31 skipping to change at page 10, line 40
ada":;;;;;; ada":;;;;;;
jCard Example: jCard Example:
["adr", ["adr",
{"label":"123 Maple Ave\nSuite 901\nVancouver BC\nA1B 2C9\nCanada"}, {"label":"123 Maple Ave\nSuite 901\nVancouver BC\nA1B 2C9\nCanada"},
"text", "text",
["", "", "", "", "", "", ""] ["", "", "", "", "", "", ""]
] ]
3.3. Parameters (RFC6350 Section 5) 3.4. Parameters (RFC6350 Section 5)
Property parameters are represented as a JSON object where each key- Property parameters are represented as a JSON object where each key-
value pair represents the vCard parameter name and its value. The value pair represents the vCard parameter name and its value. The
name of the parameter MUST be in lowercase, the original case of the name of the parameter MUST be in lowercase, the original case of the
parameter value MUST be preserved. For example, the "LANG" property parameter value MUST be preserved. For example, the "LANG" property
parameter is represented in jCard by the "lang" key. Any new vCard parameter is represented in jCard by the "lang" key. Any new vCard
parameters added in the future will be converted in the same way. parameters added in the future will be converted in the same way.
Example: Example:
["vcard", ["vcard",
[ [
["role", { "lang": "tr" }, "text", "roca"], ["role", { "lang": "tr" }, "text", "roca"],
... ...
] ]
] ]
3.3.1. VALUE parameter 3.4.1. VALUE parameter
vCard defines a "VALUE" property parameter (Section 5.2 of vCard defines a "VALUE" property parameter (Section 5.2 of
[RFC6350]). This property parameter MUST NOT be added to the [RFC6350]). This property parameter MUST NOT be added to the
parameters object. Instead, the value type is always explicitly parameters object. Instead, the value type is signaled through the
mentioned in the third element of the array describing the property. type identifier in the third element of the array describing the
Thus, when converting from vCard to jCard, any "VALUE" property property. When converting a property from vCard to jCard, the value
parameters are skipped. When converting from jCard into vCard, the type is determined as follows:
appropriate "VALUE" property parameter MUST be included in the vCard
property if the value type is not "unknown" or the default value type
for that property. See Section 5 for information on handling unknown
value types.
3.3.2. Multi-value Parameters 1. If the property has a "VALUE" parameter, that parameter's value
is used as the value type.
2. If the property has no "VALUE" parameter but has a default value
type, the default value type is used.
3. If the property has no "VALUE" parameter and has no default value
type, "unknown" is used.
Converting from jCard into vCard is done as follows:
1. If the property's value type is "unknown", no "VALUE" parameter
is included.
2. If the property's value type is the default type for that
property, no "VALUE" parameter is included.
3. Otherwise, a "VALUE" parameter is included, and the value type is
used as the parameter value.
See Section 5 for information on handling unknown value types.
3.4.2. Multi-value Parameters
In [RFC6350], some parameters allow using a COMMA-separated list of In [RFC6350], some parameters allow using a COMMA-separated list of
values. To ease processing in jCard, the value to such parameters values. To ease processing in jCard, the value to such parameters
MUST be represented in an array containing the separated values. The MUST be represented in an array containing the separated values. The
array elements MUST be string values. Single-value parameters SHOULD array elements MUST be string values. Single-value parameters SHOULD
be represented using a single string value, although a more simple be represented using a single string value, although a more simple
implementation might prefer an array with one string element. An implementation might prefer an array with one string element. An
example for a such parameter is the vCard "SORT-AS" parameter, more example for a such parameter is the vCard "SORT-AS" parameter, more
such parameters may be added in extensions. such parameters may be added in extensions.
DQUOTE characters used to encapsulate the separated values MUST NOT The vCard specification requires encapsulation between DQUOTE
be added to the jCard parameter value. characters if a parameter value contains a colon, a semicolon or a
comma. These extra DQUOTE characters do not belong to the actual
parameter value, and hence are not included when the parameter is
converted to jCard.
Example 1: Example:
["vcard", ["vcard",
[ [
["n", ["n",
{ "sort-as": ["Harten", "Rene"] }, { "sort-as": ["Harten", "Rene"] },
"text", "text",
"van der Harten;Rene,J.;Sir;R.D.O.N." ["van der Harten", "Rene", "J.", "Sir", "R.D.O.N."]
], ],
["fn", {}, "text", "Rene van der Harten"] ["fn", {}, "text", "Rene van der Harten"]
... ...
] ]
] ]
3.4. Values (RFC6350 Section 4) 3.5. Values (RFC6350 Section 4)
The type of a vCard value is explicitly mentioned in the third The following subsections specify how vCard property value data
element of the array describing a jCard property. The actual values types, which are defined in the subsections of [RFC6350] Section 4,
of the property can be found in the fourth and following elements of are represented in jCard.
the array.
3.4.1. Text (RFC6350 Section 4.1) 3.5.1. Text (RFC6350 Section 4.1)
Description: vCard "TEXT" property values are represented by a Description: vCard "TEXT" property values are represented by a
property with the type identifier "text". The value elements are property with the type identifier "text". The value elements are
JSON strings. For details on structured text values, see JSON strings. For details on structured text values, see
Section 3.2.1.4. Section 3.3.1.3.
Example: Example:
["kind", {}, "text", "group"] ["kind", {}, "text", "group"]
3.4.2. URI (RFC6350 Section 4.2) 3.5.2. URI (RFC6350 Section 4.2)
Description: vCard "URI" property values are represented by a Description: vCard "URI" property values are represented by a
property with the type identifier "uri". The value elements are property with the type identifier "uri". The value elements are
JSON strings. JSON strings.
Example: Example:
["source", {}, "uri", "ldap://ldap.example.com/cn=babs%20jensen"] ["source", {}, "uri", "ldap://ldap.example.com/cn=babs%20jensen"]
3.4.3. Date (RFC6350 Section 4.3.1) 3.5.3. Date (RFC6350 Section 4.3.1)
Description: vCard "DATE" property values are represented by a Description: vCard "DATE" property values are represented by a
property with the type identifier "date". The value elements are property with the type identifier "date". The value elements are
JSON strings with the same date value specified by [RFC6350], but JSON strings with the same date value specified by [RFC6350], but
represented using the extended format specified in represented using the extended format specified in
[ISO.8601.2004], Section 4.1.2. If the complete representation is [ISO.8601.2004], Section 4.1.2. If the complete representation is
not used, the same date format restrictions regarding reduced not used, the same date format restrictions regarding reduced
accuracy, truncated representation and expanded representation accuracy, truncated representation and expanded representation
noted in [RFC6350] Section 4.1.2.3 apply. Whenever the extended noted in [RFC6350] Section 4.3.1 apply. Whenever the extended
format is not applicable, the basic format MUST be used. format is not applicable, the basic format MUST be used.
ABNF Schema: ABNF Schema:
date-complete = year "-" month "-" day ;YYYY-MM-DD date-complete = year "-" month "-" day ;YYYY-MM-DD
date-noreduc = date-complete date-noreduc = date-complete
/ "--" month "-" day; --MM-DD / "--" month "-" day; --MM-DD
/ "---" day; ---DDD / "---" day; ---DDD
skipping to change at page 12, line 34 skipping to change at page 14, line 23
| | | | | | | |
| Reduced | 1985 | 1985 | | Reduced | 1985 | 1985 |
| | | | | | | |
| Truncated | --0412 | --04-12 | | Truncated | --0412 | --04-12 |
| | | | | | | |
| Truncated | --04 | --04 | | Truncated | --04 | --04 |
| | | | | | | |
| Truncated | ---12 | ---12 | | Truncated | ---12 | ---12 |
+-----------+----------+------------+ +-----------+----------+------------+
3.4.4. Time (RFC6350 Section 4.3.2) 3.5.4. Time (RFC6350 Section 4.3.2)
Description: vCard "TIME" property values are represented by a Description: vCard "TIME" property values are represented by a
property with the type identifier "time". The value elements are property with the type identifier "time". The value elements are
JSON strings with the same time value specified by [RFC6350], but JSON strings with the same time value specified by [RFC6350], but
represented using the extended format specified in represented using the extended format specified in
[ISO.8601.2004], Section 4.2. If the complete representation is [ISO.8601.2004], Section 4.2. If the complete representation is
not used, the same time format restrictions regarding reduced not used, the same time format restrictions regarding reduced
accuracy, decimal fraction and truncated representation noted in accuracy, decimal fraction and truncated representation noted in
[RFC6350] Section 4.3.2 apply. Whenever the extended format is [RFC6350] Section 4.3.2 apply. Whenever the extended format is
not applicable, the basic format MUST be used. The seconds value not applicable, the basic format MUST be used. The seconds value
of 60 MUST only be used to account for positive "leap" seconds and of 60 MUST only be used to account for positive "leap" seconds and
the midnight hour is always represented by 00, never 24. the midnight hour is always represented by 00, never 24.
Fractions of a second are not supported by this format. Contrary Fractions of a second are not supported by this format. In jCard,
to [I-D.ietf-jcardcal-jcal], UTC offsets are permitted within a UTC offsets are permitted within a time value; note that this
time value. differs from jCal [I-D.ietf-jcardcal-jcal], where they are not
permitted.
ABNF Schema: ABNF Schema:
time-notrunc = hour [":" minute [":" second]] [zone] time-notrunc = hour [":" minute [":" second]] [zone]
time = time-notrunc time = time-notrunc
/ "-" minute ":" second [zone]; -mm:ss / "-" minute ":" second [zone]; -mm:ss
/ "-" minute [zone]; -mm / "-" minute [zone]; -mm
/ "--" second [zone]; --ss / "--" second [zone]; --ss
skipping to change at page 13, line 46 skipping to change at page 15, line 37
| Truncated | -2050 | -20:50 | | Truncated | -2050 | -20:50 |
| | | | | | | |
| Truncated | -20 | -20 | | Truncated | -20 | -20 |
| | | | | | | |
| Truncated | --50 | --50 | | Truncated | --50 | --50 |
+-----------+--------+----------+ +-----------+--------+----------+
Also, all combinations may have any zone designator appended, as in Also, all combinations may have any zone designator appended, as in
the complete representation. the complete representation.
3.4.5. Date-Time (RFC6350 Section 4.3.3) 3.5.5. Date-Time (RFC6350 Section 4.3.3)
Description: vCard "DATE-TIME" property values are represented by a Description: vCard "DATE-TIME" property values are represented by a
property with the type identifier "date-time". The value elements property with the type identifier "date-time". The value elements
are JSON strings with the same date value specified by [RFC6350], are JSON strings with the same date value specified by [RFC6350],
but represented using the extended format specified in but represented using the extended format specified in
[ISO.8601.2004], Section 4.3. If the complete representation is [ISO.8601.2004], Section 4.3. If the complete representation is
not used, the same date and time format restrictions as in not used, the same date and time format restrictions as in
Section 3.4.4 and Section 3.4.3 apply. Just as in [RFC6350], Section 3.5.4 and Section 3.5.3 apply. Just as in [RFC6350],
truncation of the date part is permitted. truncation of the date part is permitted.
Example: Example:
["anniversary", {}, "date-time", "2013-02-14T12:30:00"], ["anniversary", {}, "date-time", "2013-02-14T12:30:00"],
["anniversary", {}, "date-time", "2013-01-10T19:00:00Z"], ["anniversary", {}, "date-time", "2013-01-10T19:00:00Z"],
["anniversary", {}, "date-time", "2013-08-15T09:45:00+01:00"], ["anniversary", {}, "date-time", "2013-08-15T09:45:00+01:00"],
["anniversary", {}, "date-time", "---15T09:45:00+01:00"] ["anniversary", {}, "date-time", "---15T09:45:00+01:00"]
This table contains possible conversions between the vCard DATE-TIME This table contains possible conversions between the vCard DATE-TIME
skipping to change at page 15, line 12 skipping to change at page 17, line 5
| | | | | | | |
| Truncated and | --04T23 | --04T23 | | Truncated and | --04T23 | --04T23 |
| Reduced | | | | Reduced | | |
+----------------+----------------------+---------------------------+ +----------------+----------------------+---------------------------+
As specified in [ISO.8601.2000], the date component shall not be As specified in [ISO.8601.2000], the date component shall not be
represented with reduced accuracy and the time component shall not be represented with reduced accuracy and the time component shall not be
truncated. Also, all combinations may have any zone designator truncated. Also, all combinations may have any zone designator
appended, as in the complete representation. appended, as in the complete representation.
3.4.6. Date and/or Time (RFC6350 Section 4.3.4) 3.5.6. Date and/or Time (RFC6350 Section 4.3.4)
Description: vCard "DATE-AND-OR-TIME" property values are Description: vCard "DATE-AND-OR-TIME" property values are
represented by a property with the type identifier "date-and-or- represented by a property with the type identifier "date-and-or-
time". The value elements are either a date-time (Section 3.4.5), time". The value elements are either a date-time (Section 3.5.5),
a date (Section 3.4.3) or a time (Section 3.4.4) value. Just as a date (Section 3.5.3) or a time (Section 3.5.4) value. Just as
in [RFC6350] Section 4.3.4, a stand-alone time value MUST always in [RFC6350] Section 4.3.4, a stand-alone time value MUST always
be preceded by a "T". be preceded by a "T".
Example: Example:
["bday", {}, "date-and-or-time", "2013-02-14T12:30:00"], ["bday", {}, "date-and-or-time", "2013-02-14T12:30:00"],
["bday", {}, "date-and-or-time", "---22T14:00"] ["bday", {}, "date-and-or-time", "---22T14:00"]
["bday", {}, "date-and-or-time", "1985"], ["bday", {}, "date-and-or-time", "1985"],
["bday", {}, "date-and-or-time", "T12:30"] ["bday", {}, "date-and-or-time", "T12:30"]
3.4.7. Timestamp (RFC6350 Section 4.3.5) 3.5.7. Timestamp (RFC6350 Section 4.3.5)
Description: vCard "TIMESTAMP" property values are represented by a Description: vCard "TIMESTAMP" property values are represented by a
property with the type identifier "timestamp". The value elements property with the type identifier "timestamp". The value elements
are JSON strings with the same timestamp value specified by are JSON strings with the same timestamp value specified by
[RFC6350], but represented using the extended format and complete [RFC6350], but represented using the extended format and complete
representation specified in [ISO.8601.2004], Section 4.3.2. representation specified in [ISO.8601.2004], Section 4.3.2.
Example: Example:
["rev", {}, "timestamp", "2013-02-14T12:30:00"], ["rev", {}, "timestamp", "2013-02-14T12:30:00"],
skipping to change at page 16, line 17 skipping to change at page 18, line 6
+----------------+----------------------+---------------------------+ +----------------+----------------------+---------------------------+
| Complete | 19850412T232050 | 1985-04-12T23:20:50 | | Complete | 19850412T232050 | 1985-04-12T23:20:50 |
| | | | | | | |
| Complete | 19850412T232050Z | 1985-04-12T23:20:50Z | | Complete | 19850412T232050Z | 1985-04-12T23:20:50Z |
| | | | | | | |
| Complete | 19850412T232050+0400 | 1985-04-12T23:20:50+04:00 | | Complete | 19850412T232050+0400 | 1985-04-12T23:20:50+04:00 |
| | | | | | | |
| Complete | 19850412T232050+04 | 1985-04-12T23:20:50+04 | | Complete | 19850412T232050+04 | 1985-04-12T23:20:50+04 |
+----------------+----------------------+---------------------------+ +----------------+----------------------+---------------------------+
3.4.8. Boolean (RFC6350 Section 4.4) 3.5.8. Boolean (RFC6350 Section 4.4)
Description: vCard "BOOLEAN" property values are represented by a Description: vCard "BOOLEAN" property values are represented by a
property with the type identifier "boolean". The value element is property with the type identifier "boolean". The value element is
a JSON boolean value. a JSON boolean value.
Example: Example:
["x-non-smoking", {}, "boolean", true] ["x-non-smoking", {}, "boolean", true]
3.4.9. Integer (RFC6350 Section 4.5) 3.5.9. Integer (RFC6350 Section 4.5)
Description: vCard "INTEGER" property values are represented by a Description: vCard "INTEGER" property values are represented by a
property with the type identifier "integer". The value elements property with the type identifier "integer". The value elements
are JSON primitive number values. are JSON primitive number values.
Examples: Examples:
["x-karma-points", {}, "integer", 42] ["x-karma-points", {}, "integer", 42]
3.4.10. Float (RFC6350 Section 4.6) Neither JSON nor jCard prohibits using a combination of decimals and
exponents to form an integer number. However, since vCard does not
support decimals or exponents in integers, any decimals and exponents
MUST be eliminated when converting an "integer" value type property
from jCard to vCard.
3.5.10. Float (RFC6350 Section 4.6)
Description: vCard "FLOAT" property values are represented by a Description: vCard "FLOAT" property values are represented by a
property with the type identifier "float". The value elements are property with the type identifier "float". The value elements are
JSON primitive number values. JSON primitive number values.
Example: Example:
["x-grade", {}, "float", 1.3] ["x-grade", {}, "float", 1.3]
3.4.11. UTC Offset (RFC6350 Section 4.7) Neither JSON nor jCard prohibits using exponents to form a float
number. However, since vCard does not support exponents in floats,
any exponents MUST be eliminated when converting a "float" value type
property from jCard to vCard.
3.5.11. UTC Offset (RFC6350 Section 4.7)
Description: vCard "UTC-OFFSET" property values are represented by a Description: vCard "UTC-OFFSET" property values are represented by a
property with the type identifier "utc-offset". The value property with the type identifier "utc-offset". The value
elements are JSON strings with the same UTC offset value specified elements are JSON strings with the same UTC offset value specified
by [RFC6350], with the exception that the hour and minute by [RFC6350], with the exception that the hour and minute
components are separated by a ":" character, for consistency with components are separated by a ":" character, for consistency with
the [ISO.8601.2004] timezone offset, extended format. the [ISO.8601.2004] timezone offset, extended format.
Example: Example:
// Note: [RFC6350] mentions use of utc-offset // Note: [RFC6350] mentions use of utc-offset
// for the TZ property as NOT RECOMMENDED // for the TZ property as NOT RECOMMENDED
["tz", {}, "utc-offset", "-05:00"] ["tz", {}, "utc-offset", "-05:00"]
3.4.12. Language Tag (RFC6350 Section 4.8) 3.5.12. Language Tag (RFC6350 Section 4.8)
Description: vCard "LANGUAGE-TAG" property values are represented by Description: vCard "LANGUAGE-TAG" property values are represented by
a property with the type identifier "language-tag". The value a property with the type identifier "language-tag". The value
elements are JSON strings containing a single language-tag, as elements are JSON strings containing a single language-tag, as
defined in [RFC5646]. defined in [RFC5646].
Example: Example:
["lang", {}, "language-tag", "de"] ["lang", {}, "language-tag", "de"]
3.5. Extensions (RFC6350 Section 6.10) 3.6. Extensions (RFC6350 Section 6.10)
vCard extension properties and property parameters (those with an vCard extension properties and property parameters (those with an
"X-" prefix in their name) are handled in the same way as other "X-" prefix in their name) are handled in the same way as other
properties and property parameters: the property is represented by an properties and property parameters: the property is represented by an
array, the property parameter represented by an object. The property array, the property parameter represented by an object. The property
or parameter name uses the same name as for the vCard extension, but or parameter name uses the same name as for the vCard extension, but
in lowercase. For example, the "X-FOO" property in vCard turns into in lowercase. For example, the "X-FOO" property in vCard turns into
the "x-foo" jCard property. See Section 5 for how to deal with the "x-foo" jCard property. See Section 5 for how to deal with
default values for unrecognized extension properties or property default values for unrecognized extension properties or property
parameters. parameters.
skipping to change at page 18, line 41 skipping to change at page 20, line 44
extensions to it. extensions to it.
Value name: UNKNOWN Value name: UNKNOWN
Purpose: To allow preserving property values whose default value Purpose: To allow preserving property values whose default value
type is not known during round-tripping between jCard and vCard. type is not known during round-tripping between jCard and vCard.
Format definition: (Not applicable) Format definition: (Not applicable)
Description: The UNKNOWN value data type is reserved for the Description: The UNKNOWN value data type is reserved for the
exclusive use of the jCard format RFCTODO. It MUST NOT be used in exclusive use of the jCard format. It MUST NOT be used in plain
plain vCard [RFC6350]. vCard [RFC6350].
Example: As this registration serves as a reservation of the UNKNOWN Example: As this registration serves as a reservation of the UNKNOWN
type so that it is not used in vCard, there is no applicable vCard type so that it is not used in vCard, there is no applicable vCard
example. For examples of its usage in jCard, see RFCTODO example. Examples of its usage in jCard can be found in this
document.
5.1. Converting vCard into jCard 5.1. Converting vCard into jCard
Any property that does not include a "VALUE" property parameter and Any property that does not include a "VALUE" property parameter and
whose default value type is not known, MUST be converted to a whose default value type is not known, MUST be converted to a
primitive JSON string. The content of that string is the unprocessed primitive JSON string. The content of that string is the unprocessed
value text. Also, value type MUST be set to "unknown". value text. Also, value type MUST be set to "unknown".
To correctly implement this format, it is critical that if the To correctly implement this format, it is critical that if the
default type is not known that the type "unknown" is used. If this default type is not known that the value type "unknown" is used. If
requirement is ignored and for example "text" is used, additional this requirement is ignored and for example "text" is used,
escaping may occur which breaks round-tripping values. additional escaping may occur which breaks round-tripping values.
Any unrecognized property parameter MUST be converted to a string Any unrecognized property parameter MUST be converted to a string
value, with its content set to the property parameter value text, value, with its content set to the property parameter value text,
treated as if it were a "TEXT" value. treated as if it were a "TEXT" value.
5.2. Converting jCard into vCard 5.2. Converting jCard into vCard
Since jCard always explicitly specifies the value type, it can always In jCard the value type is always explicitly specified. It is
be converted to vCard using the VALUE parameter. converted to vCard using the vCard VALUE parameter, except in the
following two cases:
If the value type specified in jCard matches the default value type o If the value type specified in jCard matches the default value
in vCard, the VALUE parameter MAY be omitted. type in vCard, the VALUE parameter MAY be omitted.
If the value type specified in jCard is set to "unknown", the value o If the value type specified in jCard is set to "unknown", the
MUST be taken over in vCard without processing. In this case, the VALUE parameter MUST NOT be specified. The value MUST be taken
VALUE parameter MUST NOT be specified. over in vCard without processing.
5.3. Examples 5.3. Examples
The following is an example of an unrecognized vCard property (that The following is an example of an unrecognized vCard property (that
uses an "URI" value as its default), and the equivalent jCard uses an "URI" value as its default), and the equivalent jCard
representation of that property. representation of that property.
vCard: vCard:
X-COMPLAINT-URI:mailto:abuse@example.org X-COMPLAINT-URI:mailto:abuse@example.org
skipping to change at page 19, line 46 skipping to change at page 22, line 4
uses an "URI" value as its default), and the equivalent jCard uses an "URI" value as its default), and the equivalent jCard
representation of that property. representation of that property.
vCard: vCard:
X-COMPLAINT-URI:mailto:abuse@example.org X-COMPLAINT-URI:mailto:abuse@example.org
jCard: jCard:
["x-complaint-uri", {}, "unknown", "mailto:abuse@example.org"] ["x-complaint-uri", {}, "unknown", "mailto:abuse@example.org"]
The following is an example of how to cope with jCard data where the The following is an example of how to cope with jCard data where the
parser was unable to identify the type. Note how the "unknown" value parser was unable to identify the value type. Note how the "unknown"
type is not added to the vCard data and escaping, aside from standard value type is not added to the vCard data and escaping, aside from
JSON string escaping, is not processed. standard JSON string escaping, is not processed.
jCard: jCard:
["x-coffee-data", {}, "unknown", "Stenophylla;Guinea\\,Africa"] ["x-coffee-data", {}, "unknown", "Stenophylla;Guinea\\,Africa"]
vCard: vCard:
X-COFFEE-DATA:Stenophylla;Guinea\,Africa X-COFFEE-DATA:Stenophylla;Guinea\,Africa
The following is an example of a jCard property (where the There are no standard properties in [RFC6350] that have a default
corresponding vCard property uses a "INTEGER" value as its default), type of integer. Consequently, this example uses the following
and the equivalent vCard representation of that property. It is extended property which we treat as having a default type known to
assumed that the parser has knowledge of the default data type for the parser, namely integer, in order to illustrate how a property
the "x-karma-points" property. with a known default type would be transformed.
jCard: jCard:
["x-karma-points", {}, "integer", 95] ["x-karma-points", {}, "integer", 95]
vCard: vCard:
X-KARMA-POINTS:95 X-KARMA-POINTS:95
The following is an example of an unrecognized vCard property The following is an example of an unrecognized vCard property
skipping to change at page 21, line 42 skipping to change at page 23, line 48
Coverage All aspects of this draft. Coverage All aspects of this draft.
Licensing: New BSD License Licensing: New BSD License
Additionally, interoperability testing of this draft is an ongoing Additionally, interoperability testing of this draft is an ongoing
effort under members of calconnect, the Calendaring and Scheduling effort under members of calconnect, the Calendaring and Scheduling
Consortium. CalDAV Vendors are looking into supporting this draft. Consortium. CalDAV Vendors are looking into supporting this draft.
7. Security Considerations 7. Security Considerations
For security considerations specific to calendar data, see Section 9 This specification defines how vCard data can be "translated" between
of [RFC6350]. Since this specification is a mapping from vCard, no two different data formats - the original text format and JSON - with
new security concerns are introduced related to calendar data. a one-to-one mapping to ensure all the semantic data in one format
(properties, parameters and values) are preserved in the other. It
does not change the semantic meaning of the underlying data itself,
or impose or remove any security considerations that apply to the
underlying data.
The use of JSON as a format does have security risks. Section 7 of The use of JSON as a format does have its own inherent security risks
[RFC4627] discusses these risks. as discussed in Section 7 of [RFC4627]. Even though JSON is
considered a safe subset of JavaScript, it should be kept in mind
that a flaw in the parser processing JSON could still impose a threat
which doesn't arise with conventional vCard data.
With this in mind, a parser for JSON data should be used for jCard
that is aware of the security implications. For example, the use of
JavaScript's eval() function is only allowed using the regular
expression in Section 6 of [RFC4627]. A native parser with full
awareness of the JSON format should be preferred.
In addition, it is expected that this new format will result in vCard
data being more widely disseminated (e.g., with use in web
applications rather than just dedicated "contact managers").
In all cases, application developers have to conform to the semantics
of the vCard data as defined by [RFC6350] and associated extensions,
and all of the security considerations described in Section 9 of
[RFC6350], or any associated extensions, are applicable.
8. IANA Considerations 8. IANA Considerations
This document defines a MIME media type for use with vCard in JSON This document defines a MIME media type for use with vCard in JSON
data. This media type SHOULD be used for the transfer of calendaring data. This media type SHOULD be used for the transfer of calendaring
data in JSON. data in JSON.
Type name: application Type name: application
Subtype name: vcard+json Subtype name: vcard+json
Required parameters: none Required parameters: none
skipping to change at page 22, line 33 skipping to change at page 25, line 13
alternative format for vCard data based on JSON. alternative format for vCard data based on JSON.
Published specification: This specification. Published specification: This specification.
Applications which use this media type: Applications that currently Applications which use this media type: Applications that currently
make use of the text/vcard media type can use this as an make use of the text/vcard media type can use this as an
alternative. Similarly, Applications that use the application/ alternative. Similarly, Applications that use the application/
json media type to transfer directory data can use this to further json media type to transfer directory data can use this to further
specify the content. specify the content.
Fragment identifier considerations: N/A
Additional information:
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): N/A
Macintosh file type code(s): N/A
Person & email address to contact for further information: Person & email address to contact for further information:
vcarddav@ietf.org vcarddav@ietf.org
Intended usage: COMMON Intended usage: COMMON
Restrictions on usage: There are no restrictions on where this media Restrictions on usage: There are no restrictions on where this media
type can be used. type can be used.
Author: See the "Author's Address" section of this document. Author: See the "Author's Address" section of this document.
Change controller: IETF Change controller: IETF
8.1. GROUP vCard Parameter 8.1. GROUP vCard Parameter
IANA has added the following entry to the vCard Parameters registry, IANA has added the following entry to the vCard Parameters registry,
defined in Section 10.3.2 of [RFC6350]. defined in Section 10.3.2 of [RFC6350].
+-----------+-----------+--------------------------+ +-----------+-----------+--------------------------+
| Namespace | Parameter | Reference | | Namespace | Parameter | Reference |
+-----------+-----------+--------------------------+ +-----------+-----------+--------------------------+
| | GROUP | RFCTODO, Section 3.2.1.3 | | | GROUP | RFCTODO, Section 3.3.1.2 |
+-----------+-----------+--------------------------+ +-----------+-----------+--------------------------+
8.2. UNKNOWN vCard Value Data Type 8.2. UNKNOWN vCard Value Data Type
IANA has added the following entry to the vCard Data Types registry, IANA has added the following entry to the vCard Data Types registry,
defined in Section 10.3.3 of [RFC6350]. defined in Section 10.3.3 of [RFC6350].
+-----------------+--------------------+ +-----------------+--------------------+
| Value Data Type | Reference | | Value Data Type | Reference |
+-----------------+--------------------+ +-----------------+--------------------+
skipping to change at page 23, line 32 skipping to change at page 26, line 24
contributions: Cyrus Daboo, Mike Douglass, William Gill, Erwin Rehme, contributions: Cyrus Daboo, Mike Douglass, William Gill, Erwin Rehme,
and Dave Thewlis. Simon Perreault, Michael Angstadt, Peter Saint- and Dave Thewlis. Simon Perreault, Michael Angstadt, Peter Saint-
Andre, Bert Greevenbosch, Javier Godoy. This specification Andre, Bert Greevenbosch, Javier Godoy. This specification
originated from the work of the XML-JSON technical committee of the originated from the work of the XML-JSON technical committee of the
Calendaring and Scheduling Consortium. Calendaring and Scheduling Consortium.
10. References 10. References
10.1. Normative References 10.1. Normative References
[I-D.ietf-jcardcal-jcal]
Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON
format for iCalendar", draft-ietf-jcardcal-jcal-00 (work
in progress), March 2013.
[ISO.8601.2000] [ISO.8601.2000]
International Organization for Standardization, ""Data International Organization for Standardization, ""Data
elements and interchange formats -- Information elements and interchange formats -- Information
interchange -- Representation of dates and times" ", ISO interchange -- Representation of dates and times" ", ISO
8601, 12 2000. 8601, 12 2000.
[ISO.8601.2004] [ISO.8601.2004]
International Organization for Standardization, ""Data International Organization for Standardization, ""Data
elements and interchange formats -- Information elements and interchange formats -- Information
interchange -- Representation of dates and times" ", ISO interchange -- Representation of dates and times" ", ISO
8601, 12 2004. 8601, 12 2004.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling
Core Object Specification (iCalendar)", RFC 5545,
September 2009.
[RFC5646] Phillips, A. and M. Davis, "Tags for Identifying [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying
Languages", BCP 47, RFC 5646, September 2009. Languages", BCP 47, RFC 5646, September 2009.
[RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML
Format for iCalendar", RFC 6321, August 2011.
[RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
August 2011. August 2011.
[RFC6351] Perreault, S., "xCard: vCard XML Representation", RFC
6351, August 2011.
[RFC6868] Daboo, C., "Parameter Value Encoding in iCalendar and [RFC6868] Daboo, C., "Parameter Value Encoding in iCalendar and
vCard", RFC 6868, February 2013. vCard", RFC 6868, February 2013.
10.2. Informative References 10.2. Informative References
[I-D.ietf-jcardcal-jcal]
Kewisch, P., Daboo, C., and M. Douglass, "jCal: The JSON
format for iCalendar", draft-ietf-jcardcal-jcal-00 (work
in progress), March 2013.
[I-D.sheffer-running-code] [I-D.sheffer-running-code]
Sheffer, Y. and A. Farrel, "Improving Awareness of Running Sheffer, Y. and A. Farrel, "Improving Awareness of Running
Code: the Implementation Status Section", draft-sheffer- Code: the Implementation Status Section", draft-sheffer-
running-code-02 (work in progress), January 2013. running-code-02 (work in progress), January 2013.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC5545] Desruisseaux, B., "Internet Calendaring and Scheduling
JavaScript Object Notation (JSON)", RFC 4627, July 2006. Core Object Specification (iCalendar)", RFC 5545,
September 2009.
[RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML
Format for iCalendar", RFC 6321, August 2011.
[RFC6351] Perreault, S., "xCard: vCard XML Representation", RFC
6351, August 2011.
[calconnect-artifacts] [calconnect-artifacts]
The Calendaring and Scheduling Consortium, "Code Artifacts The Calendaring and Scheduling Consortium, "Code Artifacts
and Schemas", , and Schemas", ,
<http://www.calconnect.org/artifacts.shtml>. <http://www.calconnect.org/artifacts.shtml>.
Appendix A. ABNF Schema Appendix A. ABNF Schema
Below is an ABNF schema as per [RFC5234] for vCard in JSON. ABNF Below is an ABNF schema as per [RFC5234] for vCard in JSON. ABNF
Symbols not described here are taken from [RFC4627]. The schema is Symbols not described here are taken from [RFC4627]. The schema is
skipping to change at page 25, line 11 skipping to change at page 27, line 50
The numeric section numbers given in the comments refer to section in The numeric section numbers given in the comments refer to section in
[RFC6350]. Additional semantic restrictions apply, especially [RFC6350]. Additional semantic restrictions apply, especially
regarding the allowed properties and sub-components per component. regarding the allowed properties and sub-components per component.
Details on these restrictions can be found in this document and Details on these restrictions can be found in this document and
[RFC6350]. [RFC6350].
Additional schemas may be available on the internet at Additional schemas may be available on the internet at
[calconnect-artifacts]. [calconnect-artifacts].
; A jCard component uses the name "vcard" and a properties array. ; A jCard object uses the name "vcard" and a properties array.
; Restrictions to which properties and may be specified are to ; Restrictions to which properties and may be specified are to
; be taken from RFC6350. ; be taken from RFC6350.
jcardobject = begin-array jcardobject = begin-array
DQUOTE component-name DQUOTE value-separator DQUOTE component-name DQUOTE value-separator
properties-array properties-array
end-array end-array
; A jCard property consists of the name string, parameters object, ; A jCard property consists of the name string, parameters object,
; type string and one or more values as specified in this document. ; type string and one or more values as specified in this document.
property = begin-array property = begin-array
DQUOTE property-name DQUOTE value-separator DQUOTE property-name DQUOTE value-separator
params-object value-separator params-object value-separator
skipping to change at page 29, line 14 skipping to change at page 32, line 5
* Added a further sentence on preprocessing and escaping to * Added a further sentence on preprocessing and escaping to
clarify that JSON escaping must be used clarify that JSON escaping must be used
* Described how to handle structured text values and structured * Described how to handle structured text values and structured
text components with multiple values. text components with multiple values.
* Corrections and additions to the ABNF Section, adaptions to * Corrections and additions to the ABNF Section, adaptions to
example example
draft-ietf-jcardcal-jcard-02
* Made more clear that complete representation is not mandatory * Made more clear that complete representation is not mandatory
* Added sheffer-running-code section * Added sheffer-running-code section
* Changed handling of unknown property parameter types * Changed handling of unknown property parameter types
* Minor corrections to sections regarding dates, fixing typos * Minor corrections to sections regarding dates, fixing typos
draft-ietf-jcardcal-jcard-03 draft-ietf-jcardcal-jcard-03
skipping to change at page 30, line 4 skipping to change at page 32, line 41
* Improved GROUP/UNKNOWN registrations by only putting vcard * Improved GROUP/UNKNOWN registrations by only putting vcard
related information into the registration template related information into the registration template
* Removed vcard stream construct. * Removed vcard stream construct.
* Added reference to RFC6868 for both directions * Added reference to RFC6868 for both directions
* Corrected some examples and ABNF * Corrected some examples and ABNF
draft-ietf-jcardcal-jcard-05 draft-ietf-jcardcal-jcard-05
* Updated UNKNOWN registration text to match with jCal text. * Updated UNKNOWN registration text to match with jCal text.
Author's Address draft-ietf-jcardcal-jcard-06
* Various editoral changes based on the IETF reviews. Please see
http://trac.tools.ietf.org/wg/jcardcal/trac/ for details.
Author's Address
Philipp Kewisch Philipp Kewisch
Mozilla Corporation Mozilla Corporation
650 Castro Street, Suite 300 650 Castro Street, Suite 300
Mountain View, CA 94041 Mountain View, CA 94041
USA USA
EMail: mozilla@kewis.ch EMail: mozilla@kewis.ch
URI: http://www.mozilla.org/ URI: http://www.mozilla.org/
 End of changes. 102 change blocks. 
243 lines changed or deleted 371 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/