draft-ietf-jcardcal-jcard-03.txt   draft-ietf-jcardcal-jcard-04.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 May 18, 2013 Intended status: Standards Track July 03, 2013
Expires: November 19, 2013 Expires: January 04, 2014
jCard: The JSON format for vCard jCard: The JSON format for vCard
draft-ietf-jcardcal-jcard-03 draft-ietf-jcardcal-jcard-04
Abstract Abstract
This specification defines "jCard", a JSON format for vCard data. This specification defines "jCard", a JSON format for vCard data.
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 November 19, 2013. This Internet-Draft will expire on January 04, 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
skipping to change at page 2, line 7 skipping to change at page 2, line 7
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 . . . . . . . . . . . . . . 3
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. vCard Stream . . . . . . . . . . . . . . . . . . . . . . 4 3.2. Properties (RFC6350 section 6) . . . . . . . . . . . . . 5
3.3. Properties (RFC6350 section 6) . . . . . . . . . . . . . 5 3.2.1. Special Cases for Properties . . . . . . . . . . . . 6
3.3.1. Special Cases for Properties . . . . . . . . . . . . 6 3.2.1.1. The VERSION Property . . . . . . . . . . . . . . 6
3.3.1.1. Multi-valued Properties . . . . . . . . . . . . . 6 3.2.1.2. Multi-valued Properties . . . . . . . . . . . . . 6
3.3.1.2. Grouping of Properties . . . . . . . . . . . . . 7 3.2.1.3. Grouping of Properties . . . . . . . . . . . . . 6
3.3.1.3. Structured Property Values . . . . . . . . . . . 8 3.2.1.4. Structured Property Values . . . . . . . . . . . 7
3.4. Parameters (RFC6350 Section 5) . . . . . . . . . . . . . 9 3.3. Parameters (RFC6350 Section 5) . . . . . . . . . . . . . 9
3.4.1. VALUE parameter . . . . . . . . . . . . . . . . . . . 10 3.3.1. VALUE parameter . . . . . . . . . . . . . . . . . . . 10
3.4.2. Multi-value Parameters . . . . . . . . . . . . . . . 10 3.3.2. Multi-value Parameters . . . . . . . . . . . . . . . 10
3.5. Values (RFC6350 Section 4) . . . . . . . . . . . . . . . 11 3.4. Values (RFC6350 Section 4) . . . . . . . . . . . . . . . 10
3.5.1. Text (RFC6350 Section 4.1) . . . . . . . . . . . . . 11 3.4.1. Text (RFC6350 Section 4.1) . . . . . . . . . . . . . 11
3.5.2. URI (RFC6350 Section 4.2) . . . . . . . . . . . . . . 11 3.4.2. URI (RFC6350 Section 4.2) . . . . . . . . . . . . . . 11
3.5.3. Date (RFC6350 Section 4.3.1) . . . . . . . . . . . . 12 3.4.3. Date (RFC6350 Section 4.3.1) . . . . . . . . . . . . 11
3.5.4. Time (RFC6350 Section 4.3.2) . . . . . . . . . . . . 13 3.4.4. Time (RFC6350 Section 4.3.2) . . . . . . . . . . . . 12
3.5.5. Date-Time (RFC6350 Section 4.3.3) . . . . . . . . . . 14 3.4.5. Date-Time (RFC6350 Section 4.3.3) . . . . . . . . . . 13
3.5.6. Date and/or Time (RFC6350 Section 4.3.4) . . . . . . 15 3.4.6. Date and/or Time (RFC6350 Section 4.3.4) . . . . . . 15
3.5.7. Timestamp (RFC6350 Section 4.3.5) . . . . . . . . . . 16 3.4.7. Timestamp (RFC6350 Section 4.3.5) . . . . . . . . . . 15
3.5.8. Boolean (RFC6350 Section 4.4) . . . . . . . . . . . . 16 3.4.8. Boolean (RFC6350 Section 4.4) . . . . . . . . . . . . 16
3.5.9. Integer (RFC6350 Section 4.5) . . . . . . . . . . . . 17 3.4.9. Integer (RFC6350 Section 4.5) . . . . . . . . . . . . 16
3.5.10. Float (RFC6350 Section 4.6) . . . . . . . . . . . . . 17 3.4.10. Float (RFC6350 Section 4.6) . . . . . . . . . . . . . 16
3.5.11. UTC Offset (RFC6350 Section 4.7) . . . . . . . . . . 17 3.4.11. UTC Offset (RFC6350 Section 4.7) . . . . . . . . . . 16
3.5.12. Language Tag (RFC6350 Section 4.8) . . . . . . . . . 18 3.4.12. Language Tag (RFC6350 Section 4.8) . . . . . . . . . 17
3.6. Extensions (RFC6350 Section 6.10) . . . . . . . . . . . . 18 3.5. Extensions (RFC6350 Section 6.10) . . . . . . . . . . . . 17
4. Converting from jCard into vCard . . . . . . . . . . . . . . 18 4. Converting from jCard into vCard . . . . . . . . . . . . . . 17
5. Handling Unrecognized Properties or Parameters . . . . . . . 19 5. Handling Unrecognized Properties or Parameters . . . . . . . 18
5.1. Converting vCard into jCard . . . . . . . . . . . . . . . 19
5.2. Converting jCard into vCard . . . . . . . . . . . . . . . 19
5.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . 19
6. Implementation Status (to be removed prior to publication as 6. Implementation Status (to be removed prior to publication as
an RFC) . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 an RFC) . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
7. Security Considerations . . . . . . . . . . . . . . . . . . . 22 7. Security Considerations . . . . . . . . . . . . . . . . . . . 21
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
8.1. GROUP vCard Parameter . . . . . . . . . . . . . . . . . . 23 8.1. GROUP vCard Parameter . . . . . . . . . . . . . . . . . . 22
8.2. UNKNOWN vCard Value Data Type . . . . . . . . . . . . . . 23 8.2. UNKNOWN vCard Value Data Type . . . . . . . . . . . . . . 23
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 23
10.1. Normative References . . . . . . . . . . . . . . . . . . 24 10.1. Normative References . . . . . . . . . . . . . . . . . . 23
10.2. Informative References . . . . . . . . . . . . . . . . . 25 10.2. Informative References . . . . . . . . . . . . . . . . . 24
Appendix A. ABNF Schema . . . . . . . . . . . . . . . . . . . . 25 Appendix A. ABNF Schema . . . . . . . . . . . . . . . . . . . . 24
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 27 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 26
B.1. Example: vCard of the author of RFC6350 . . . . . . . . . 27 B.1. Example: vCard of the author of RFC6350 . . . . . . . . . 26
B.1.1. vCard Data . . . . . . . . . . . . . . . . . . . . . 27 B.1.1. vCard Data . . . . . . . . . . . . . . . . . . . . . 26
B.1.2. jCard Data . . . . . . . . . . . . . . . . . . . . . 28 B.1.2. jCard Data . . . . . . . . . . . . . . . . . . . . . 27
Appendix C. Change History (to be removed prior to publication Appendix C. Change History (to be removed prior to publication
as an RFC) . . . . . . . . . . . . . . . . . . . . . 29 as an RFC) . . . . . . . . . . . . . . . . . . . . . 28
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 30
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 29
1. Introduction 1. Introduction
The vCard data format [RFC6350] has gone through multiple revisions, The vCard data format [RFC6350] provides for the capture and exchange
most recently vCard 4. The goal followed by this format is the of information normally stored within an address book or directory
capture and exchange of information normally stored within an address application. The vCard format has gone through multiple revisions,
book or directory application. As certain similarities to the most recently vCard 4. The purpose of this specification is to
iCalendar data format [RFC5545] exist it makes sense to define a define "jCard", a JSON format for vCard data. One main advantage to
JSON-based data format for vCards that is similar to the jCal format using a JSON-based format as defined in [RFC4627] over the classic
defined in [I-D.ietf-jcardcal-jcal]. 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
format [RFC5545], there is also an effort to define a JSON-based data
format for calendar information called jCal [I-D.ietf-jcardcal-jcal]
that parallels the format defined in this specification.
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 as
defined in [RFC4627] over the classic vCard format is easier defined in [RFC4627] over the classic vCard format is easier
processing for JavaScript based widgets and libraries, especially in processing for JavaScript based widgets and libraries, especially in
the scope of web-based applications. the scope of web-based 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:
skipping to change at page 4, line 7 skipping to change at page 4, line 16
terms "object" and "array" as well as the four primitive types are to terms "object" and "array" as well as the four primitive types are to
be interpreted as described in Section 1 of [RFC4627]. 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 data is converted to jCard using a This section describes how vCard objects are converted to jCard using
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",
"parameters" and "values". The top level of a vCard object contains
"properties". A "property" has a "value" and a set of zero or more
"parameters". Each of these entities have a representation in jCard,
defined in the following sections. The representation of a vCard
object in JSON will be named "jCard component" throughout this
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 72 characters) 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]. Prior to
converting vCard data into jCard all folded lines MUST be unfolded. 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. When such text elements are converted property parameter values. See Section 3.4 of [RFC6350] as well as
into jCard the escaping MUST be removed. See Section 3.4 of [RFC6868]. When such text elements are converted into jCard, the
[RFC6350]. The only escaping that may be applied is any escaping vCard escaping MUST be removed first. The only escaping that may be
mandated by JSON. applied is any escaping mandated by JSON.
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]. The sections of
this document describing the various date and time formats contain this document describing the various date and time formats contain
more information on the use of the complete representation, reduced more information on the use of the complete representation, reduced
accuracy or truncated representation. accuracy or truncated representation.
3.2. vCard Stream 3.2. Properties (RFC6350 section 6)
In certain cases it makes sense to group a sequence of vcard objects
into a stream of objects. While the vCard 4 standard doesn't define
a stream of vcard objects, having one makes it easier to identify
multiple jCard objects and also ensures compatibility to jCal. A
jCard stream is identified by an array, where the first element is
the string "vcardstream". Subsequent elements are vCard objects
represented as described in this document.
In the typical case where there is only one vCard object,
encapsulation inside a "vcardstream" array MAY be omitted.
A vCard stream can contain one or more vCard objects. Each vCard
object, delimited by "BEGIN:VCARD" and "END:VCARD", is represented in
JSON as a fixed length array with two elements:
1. The string "vcard"
2. An array of jCard properties
The representation of a vCard object in JSON will be named "vcard
component" throughout this document.
Example:
["vcardstream",
["vcard",
[ /* properties */ ]
],
["vcard",
[ /* properties */ ]
],
...
]
vCard objects are comprised of a set of "properties", "parameters"
and "values". The top level of a vCard object contains "properties".
A "property" has a "value" and a set of zero or more "parameters".
vCard objects are delimited by the general properties "BEGIN" and
"END" with the fixed value "VCARD" as defined in Section 6.1.1 and
6.1.2 of [RFC6350]. In addition, the vCard format is versioned,
therefore the "version" property is mandatory. To comply with
Section 6.7.9 of [RFC6350], the value of the version property MUST be
"4.0".
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 string, but in lowercase.
2. An object containing the parameters as described in Section 3.4. 2. An object containing the parameters as described in Section 3.3.
3. The type identifier string of the value, in lowercase. 3. The type identifier string of the value, in lowercase.
The remaining elements of the array are used for the value of the The remaining elements of the array are used for the value of the
property. For single-value properties, the array MUST have exactly property. For single-value properties, the array MUST have exactly
four elements, for multi-valued properties as described in four elements, for multi-valued properties as described in
Section 3.3.1.1 there can be any number of additional elements. Section 3.2.1.2 there can be any number of additional elements.
The array describing the property can then be inserted into the array The array describing the property can then be inserted into the array
designated for properties in the "vcard" component. designated for properties in the jCard component.
Example: 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 The property parameters in the second element of the property array
associate a set of parameter names with their respective value. associate a set of parameter names with their respective value.
Parameters are further described in Section 3.4. Parameters are further described in Section 3.3.
To allow for a cleaner implementation, the parameter object MUST be To allow for a cleaner implementation, the parameter object MUST be
present even if there are no parameters. In this case, an empty present even if there are no parameters. In this case, an empty
object MUST be used. object MUST be used.
As described in Section 3.3.1.3, it is important to check the data As described in Section 3.2.1.4, it is important for a parser check
type of the value even if it is assumed to be a string in most cases. the data type of the value even if it is assumed to be a string in
The value could turn out to be a structured value, in which case the most cases. The value could turn out to be a structured value, in
type is an array. which case the data type is an array.
3.3.1. Special Cases for Properties 3.2.1. Special Cases for Properties
This section describes some properties that have special handling This section describes some properties that have special handling
when converting to jCard. when converting to jCard.
3.3.1.1. Multi-valued Properties 3.2.1.1. The VERSION Property
The vCard format is versioned. [RFC6350] defines the VERSION
property to be mandatory, therefore a "version" property MUST also be
specified in a jCard component. Similarly, the value of the version
property MUST be "4.0".
3.2.1.2. Multi-valued Properties
Various vCard properties defined in [RFC6350], for example the Various vCard properties defined in [RFC6350], for example the
"CATEGORIES" property, are defined as multi-valued properties. In "CATEGORIES" property, are defined as multi-valued properties. In
jCal these properties are added as further members of the array jCal these properties are added as further members of the array
describing the property. describing the property.
Note that additional multi-valued properties may be added in Note that additional multi-valued properties may be added in
extensions to the iCalendar format. extensions to the iCalendar format.
Example: Example:
["vcard", ["vcard",
[ [
["categories", {}, "text", "computers", "cameras"], ["categories", {}, "text", "computers", "cameras"],
... ...
], ]
...
] ]
3.3.1.2. Grouping of Properties 3.2.1.3. Grouping of Properties
[RFC6350] Section 3.3 defines a grouping construct that is used to [RFC6350] Section 3.3 defines a grouping construct that is used to
group related properties together. In jCard, a new GROUP parameter group related properties together. To eliminate the need for an
is introduced. Its purpose is to eliminate the need for group syntax extra group syntax in jCard, thus unifying the general syntax with
in jCard, thus unifying the general syntax with that of jCal. that of jCal, this specification introduces a "group" parameter, that
holds the group name. The 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 RFCTODO. It MUST NOT be used in plain vCard
[RFC6350], nor in xCard [RFC6351]. In jCard, the parameter's [RFC6350], nor in xCard [RFC6351].
value is a single opaque string. Conversion rules are as follows:
* From vCard to jCard, the group construct (see [RFC6350], Format definition: (Not applicable)
Section 3.3, Page 7) is removed. In its place, the GROUP
parameter is added (lowercased, as any other parameter). Its
value is a string corresponding to the group name. The name's
case MUST be preserved intact.
* From jCard to vCard, the reverse procedure is performed. The Example: As this registration serves as a reservation of the GROUP
GROUP parameter MUST NOT appear in the resulting vCard. parameter so that it is not used in vCard, there is no applicable
vCard example. For examples of its usage in jCard, see RFCTODO
Format definition: (Not applicable) 3.2.1.3.1. Group Conversion Rules
In jCard, the parameter's value is a single opaque string.
Conversion rules are as follows:
o From vCard to jCard, the group construct (see [RFC6350],
Section 3.3, Page 7) is removed. In its place, the GROUP
parameter is added (lowercased, as any other parameter). Its
value is a string corresponding to the group name. The name's
case MUST be preserved intact.
o From jCard to vCard, the reverse procedure is performed. 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.3.1.3. Structured Property Values 3.2.1.4. 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. A structured value is defined as a value
that contains multiple text components, delimited by the SEMICOLON that contains multiple text components, delimited by the SEMICOLON
character. In jCard, the property value is an array containing one character. In jCard, the property value is an array containing one
element for each text component. element for each text component.
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",
"Any Town", "CA", "91921-1234", "U.S.A." "Any Town", "CA", "91921-1234", "U.S.A."
] ]
] ]
Some vCard properties, for example ADR, also allow a structured value Some vCard properties, for example ADR, also allow a structured value
element that itself has multiple values. In this case, the element element that itself has multiple values. In this case, the element
of the array describing the structured value is itself an array with of the array describing the structured value is itself an array with
one element for each of the component's multiple values. one element for each of the component's multiple values.
vCard Example: vCard Example:
ADR:;;My Street,Left Side,Second Shack;Hometown;PA;18252;U.S.A. ADR:;;My Street,Left Side,Second Shack;Hometown;PA;18252;U.S.A.
jCard Example: jCard Example:
["adr", {}, "text", ["adr", {}, "text",
[ [
"", "", "", "",
["My Street", "Left Side", "Second Shack"], ["My Street", "Left Side", "Second Shack"],
"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, If a multi-valued text component is changed to hold only one value,
the text component SHOULD be represented as a single primitive value, the text component SHOULD be represented as a single primitive value,
but MAY be represented as an array with a single primitive value. dropping the array completely. Nevertheless, a more simple
implementation might choose to retain the array, with a single
primitive 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) MAY be represented as a one being optional (for example, GENDER) can be represented as a
single text value. Therefore, implementors SHOULD check even known single text value. Therefore, parsers of jCard data SHOULD check
property values for structured information. This is especially even known property values for structured information by considering
important for languages where accessing array members is done by the the JSON data type of the value, which can be an array or a primitive
same construct as accessing characters of a string. value. This is especially important for languages where accessing
array members is done by the same construct as accessing characters
of a string.
Examples: Examples:
["gender", {}, "text", ["F", "grrrl"] ], ["gender", {}, "text", ["F", "grrrl"] ],
["gender", {}, "text", "M" ], ["gender", {}, "text", "M" ]
Per [RFC6350] Section 6.3.1, the component separator MUST be Per [RFC6350] Section 6.3.1, the component separator MUST be
specified even if the component value is missing. Similarly, the specified even if the component value is missing. Similarly, the
jCard array containing the structured data MUST contain all required jCard array containing the structured data MUST contain all required
elements, even if they are empty. elements, even if they are empty.
vCard Example: vCard Example:
ADR;LABEL="123 Maple Ave\nSuite 901\nVancouver BC\nA1B 2C9\nCan ADR;LABEL="123 Maple Ave\nSuite 901\nVancouver BC\nA1B 2C9\nCan
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.4. Parameters (RFC6350 Section 5) 3.3. 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.4.1. VALUE parameter 3.3.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 always explicitly
mentioned in the third element of the array describing the property. mentioned in the third element of the array describing the property.
Thus, when converting from vCard to jCard, any "VALUE" property Thus, when converting from vCard to jCard, any "VALUE" property
parameters are skipped. When converting from jCard into vCard, the parameters are skipped. When converting from jCard into vCard, the
appropriate "VALUE" property parameter MUST be included in the vCard appropriate "VALUE" property parameter MUST be included in the vCard
property if the value type is not "unknown" or the default value type property if the value type is not "unknown" or the default value type
for that property. See Section 5 for information on handling unknown for that property. See Section 5 for information on handling unknown
value types. value types.
3.4.2. Multi-value Parameters 3.3.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, but an array with one be represented using a single string value, although a more simple
element MAY also be used. An example for a such parameter is the implementation might prefer an array with one string element. An
vCard "SORT-AS" parameter, more such parameters may be added in example for a such parameter is the vCard "SORT-AS" parameter, more
extensions. such parameters may be added in extensions.
DQUOTE characters used to encapsulate the separated values MUST NOT DQUOTE characters used to encapsulate the separated values MUST NOT
be added to the jCard parameter value. be added to the jCard parameter value.
Example 1: Example 1:
["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.5. Values (RFC6350 Section 4) 3.4. Values (RFC6350 Section 4)
The type of a vCard value is explicitly mentioned in the third The type of a vCard value is explicitly mentioned in the third
element of the array describing a jCard property. The actual values element of the array describing a jCard property. The actual values
of the property can be found in the fourth and following elements of of the property can be found in the fourth and following elements of
the array. the array.
3.5.1. Text (RFC6350 Section 4.1) 3.4.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.3.1.3. Section 3.2.1.4.
Example: Example:
... ["kind", {}, "text", "group"]
["kind", {}, "text", "group"],
...
3.5.2. URI (RFC6350 Section 4.2) 3.4.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.5.3. Date (RFC6350 Section 4.3.1) 3.4.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.1.2.3 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
date = date-noreduc date = date-noreduc
/ year; YYYY / year; YYYY
/ year "-" month ; YYYY-MM / year "-" month ; YYYY-MM
/ "--" month; --MM / "--" month; --MM
Examples: Examples:
...
["bday", {}, "date", "1985-04-12"], ["bday", {}, "date", "1985-04-12"],
["bday", {}, "date", "1985-04"], ["bday", {}, "date", "1985-04"],
["bday", {}, "date", "1985"], ["bday", {}, "date", "1985"],
["bday", {}, "date", "--04-12"], ["bday", {}, "date", "--04-12"],
["bday", {}, "date", "---12"], ["bday", {}, "date", "---12"]
...
This table contains possible conversions between the vCard DATE This table contains possible conversions between the vCard DATE
format its jCard date. This information is to be seen as an format its jCard date. This information is just an example and not a
informative reference, the normative reference is [ISO.8601.2000] and formal specification of the syntax. The specification can be found
[ISO.8601.2004]: in [ISO.8601.2000] and [ISO.8601.2004]:
+-----------+----------+------------+ +-----------+----------+------------+
| | vCard | jCard | | | vCard | jCard |
+-----------+----------+------------+ +-----------+----------+------------+
| Complete | 19850412 | 1985-04-12 | | Complete | 19850412 | 1985-04-12 |
| | | | | | | |
| Reduced | 1985-04 | 1985-04 | | Reduced | 1985-04 | 1985-04 |
| | | | | | | |
| 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.5.4. Time (RFC6350 Section 4.3.2) 3.4.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
skipping to change at page 13, line 36 skipping to change at page 13, line 10
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. Contrary
to [I-D.ietf-jcardcal-jcal], UTC offsets are permitted within a to [I-D.ietf-jcardcal-jcal], UTC offsets are permitted within a
time value. time value.
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
Examples: Examples:
...
["x-time-local", {}, "time", "12:30:00"], ["x-time-local", {}, "time", "12:30:00"],
["x-time-utc", {}, "time", "12:30:00Z"], ["x-time-utc", {}, "time", "12:30:00Z"],
["x-time-offset", "time", "12:30:00-08:00"], ["x-time-offset", {}, "time", "12:30:00-08:00"],
["x-time-reduced", "time", "23"], ["x-time-reduced", {}, "time", "23"],
["x-time-truncated", "time", "-30"], ["x-time-truncated", {}, "time", "-30"]
...
This table contains possible conversions between the vCard TIME This table contains possible conversions between the vCard TIME
format its jCard time.This information is to be seen as an format its jCard time. This information is just an example and not a
informative reference, the normative reference is [ISO.8601.2000] and formal specification of the syntax. The specification can be found
[ISO.8601.2004]: in [ISO.8601.2000] and [ISO.8601.2004]:
+-----------+--------+----------+ +-----------+--------+----------+
| | vCard | jCard | | | vCard | jCard |
+-----------+--------+----------+ +-----------+--------+----------+
| Complete | 232050 | 23:20:50 | | Complete | 232050 | 23:20:50 |
| | | | | | | |
| Reduced | 2320 | 23:20 | | Reduced | 2320 | 23:20 |
| | | | | | | |
| Reduced | 23 | 23 | | Reduced | 23 | 23 |
| | | | | | | |
| 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.5.5. Date-Time (RFC6350 Section 4.3.3) 3.4.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.5.4 and Section 3.5.3 apply. Just as in [RFC6350], Section 3.4.4 and Section 3.4.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
format its jCard date-time. This information is to be seen as an format its jCard date-time. This information is just an example and
informative reference, the normative reference is [ISO.8601.2000] and not a formal specification of the syntax. The specification can be
[ISO.8601.2004]: found in [ISO.8601.2000] and [ISO.8601.2004]:
+----------------+----------------------+---------------------------+ +----------------+----------------------+---------------------------+
| Representation | vCard | jCard | | Representation | vCard | jCard |
+----------------+----------------------+---------------------------+ +----------------+----------------------+---------------------------+
| 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 |
| | | | | | | |
skipping to change at page 15, line 43 skipping to change at page 15, line 12
| | | | | | | |
| 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.5.6. Date and/or Time (RFC6350 Section 4.3.4) 3.4.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.5.5), time". The value elements are either a date-time (Section 3.4.5),
a date (Section 3.5.3) or a time (Section 3.5.4) value. Just as a date (Section 3.4.3) or a time (Section 3.4.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.5.7. Timestamp (RFC6350 Section 4.3.5) 3.4.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"],
["rev", {}, "timestamp", "2013-02-14T12:30:00Z"], ["rev", {}, "timestamp", "2013-02-14T12:30:00Z"],
["rev", {}, "timestamp", "2013-02-14T12:30:00-05"], ["rev", {}, "timestamp", "2013-02-14T12:30:00-05"],
["rev", {}, "timestamp", "2013-02-14T12:30:00-05:00"], ["rev", {}, "timestamp", "2013-02-14T12:30:00-05:00"]
...
This table contains possible conversions between the vCard TIMESTAMP This table contains possible conversions between the vCard TIMESTAMP
format its jCard timestamp. This information is to be seen as an format its jCard timestamp. This information is just an example and
informative reference, the normative reference is [ISO.8601.2000] and not a formal specification of the syntax. The specification can be
[ISO.8601.2004]: found in [ISO.8601.2000] and [ISO.8601.2004]:
+----------------+----------------------+---------------------------+ +----------------+----------------------+---------------------------+
| Representation | vCard | jCard | | Representation | vCard | jCard |
+----------------+----------------------+---------------------------+ +----------------+----------------------+---------------------------+
| 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.5.8. Boolean (RFC6350 Section 4.4) 3.4.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.5.9. Integer (RFC6350 Section 4.5) 3.4.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.5.10. Float (RFC6350 Section 4.6) 3.4.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.5.11. UTC Offset (RFC6350 Section 4.7)
3.4.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.5.12. Language Tag (RFC6350 Section 4.8) 3.4.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.6. Extensions (RFC6350 Section 6.10) 3.5. 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.
4. Converting from jCard into vCard 4. Converting from jCard into vCard
When converting property and property parameter values, the names When converting property and property parameter values, the names
SHOULD be converted to uppercase. Although vCard names are case SHOULD be converted to uppercase. Although vCard names are case
insensitive, common practice is to keep them all uppercase following insensitive, common practice is to keep them all uppercase following
the actual definitions in [RFC6350]. the actual definitions in [RFC6350].
Backslash escaping and line folding MUST be applied to the resulting Character escaping and line folding MUST be applied to the resulting
vCard data as required by [RFC6350]. vCard data as required by [RFC6350] and [RFC6868].
When converting to vCard, the VALUE parameter MUST be added to When converting to vCard, the VALUE parameter MUST be added to
properties whose default value type is unknown. The VALUE parameter properties whose default value type is unknown. The VALUE parameter
SHOULD NOT be added to properties using the default value type. MAY be omitted for properties using the default value type.
5. Handling Unrecognized Properties or Parameters 5. Handling Unrecognized Properties or Parameters
In vCard, properties have a default value type specified by their In vCard, properties can have one or more value types as specified by
definition, e.g. "BDAY"'s value type is "date-and-or-time", but it their definition, with one of those values being defined as the
can also be reset to a single "text" value. When a property uses its default. When a property uses its default value type, the "VALUE"
default value type, the "VALUE" property parameter does not need to property parameter does not need to be specified on the property.
be specified on the property. For example, "BDAY"'s default value type is "date-and-or-time", so
"VALUE=date-and-or-time" need not be set as a property parameter.
However, "BDAY" also allows a "text" value to be specified, and if
that is used, "VALUE=text" has to be set as a property parameter.
When new properties are defined or "X-" properties used, a vCard to When new properties are defined or "X-" properties used, a vCard to
jCard converter might not recognize them, and not know what the jCard converter might not recognize them, and not know what the
appropriate default value types are, yet they need to be able to appropriate default value types are, yet they need to be able to
preserve the values. A similar issue arises for unrecognized preserve the values. A similar issue arises for unrecognized
property parameters. property parameters.
In jCard, a new UNKNOWN property value type is introduced. Its In jCard, a new "unknown" property value type is introduced. Its
purpose is to allow preserving unknown property values when round- purpose is to allow preserving unknown property values when round-
tripping between jCard and vCard. tripping between jCard and vCard. To avoid collisions, this
specification reserves the UNKNOWN property value type in vCard. It
MUST NOT be used in any vCard as specified by [RFC6350], nor any
extensions to it.
Value name: UNKNOWN Value name: UNKNOWN
Purpose: To allow preserving unknown property values during round- Purpose: To allow preserving unknown property values during round-
tripping 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 RFCTODO. It MUST NOT be used in
plain vCard [RFC6350]. Conversion rules are as follows: plain vCard [RFC6350].
* When converting vCard into jCard: 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
example. For examples of its usage in jCard, see RFCTODO
+ Any property that does not include a "VALUE" property 5.1. Converting vCard into jCard
parameter and whose default value type is not known, MUST be
converted to a primitive JSON string. The content of that
string is the unprocessed value text. Also, value type MUST
be set to "unknown".
+ To correctly implement this format, it is critical that if Any property that does not include a "VALUE" property parameter and
the default type is not known that the type "unknown" is whose default value type is not known, MUST be converted to a
used. If this requirement is ignored and for example "text" primitive JSON string. The content of that string is the unprocessed
is used, additional escaping may occur which breaks round- value text. Also, value type MUST be set to "unknown".
tripping values.
+ Any unrecognized property parameter MUST be converted to a To correctly implement this format, it is critical that if the
string value, with its content set to the property parameter default type is not known that the type "unknown" is used. If this
value text, treated as if it were a "TEXT" value. requirement is ignored and for example "text" is used, additional
escaping may occur which breaks round-tripping values.
* When converting jCard into vCard: Any unrecognized property parameter MUST be converted to a string
value, with its content set to the property parameter value text,
treated as if it were a "TEXT" value.
+ Since jCard always explicitly specifies the value type, it 5.2. Converting jCard into vCard
can always be converted to vCard using the VALUE parameter.
+ If the value type specified in jCard matches the default Since jCard always explicitly specifies the value type, it can always
value type in vCard, the VALUE parameter SHOULD be omitted. be converted to vCard using the VALUE parameter.
+ If the value type specified in jCard is set to "unknown", If the value type specified in jCard matches the default value type
the value MUST be taken over in vCard without processing. in vCard, the VALUE parameter MAY be omitted.
In this case, the VALUE parameter MUST NOT be specified.
Example: The following is an example of an unrecognized vCard If the value type specified in jCard is set to "unknown", the value
property (that uses an "URI" value as its default), and the MUST be taken over in vCard without processing. In this case, the
equivalent jCard representation of that property. VALUE parameter MUST NOT be specified.
5.3. Examples
The following is an example of an unrecognized vCard property (that
uses an "URI" value as its default), and the equivalent jCard
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"],
...
Example: The following is an example of how to cope with jCard data The following is an example of how to cope with jCard data where the
where the parser was unable to identify the type. Note how the parser was unable to identify the type. Note how the "unknown" value
"unknown" value type is not added to the vCard data and escaping, type is not added to the vCard data and escaping, aside from standard
aside from standard JSON string escaping, is not processed. 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
Example: The following is an example of a jCard property (where the The following is an example of a jCard property (where the
corresponding vCard property uses a "INTEGER" value as its default), corresponding vCard property uses a "INTEGER" value as its default),
and the equivalent vCard representation of that property. It is and the equivalent vCard representation of that property. It is
assumed that the parser has knowledge of the default data type for assumed that the parser has knowledge of the default data type for
the "x-karma-points" property. the "x-karma-points" property.
jCard: jCard:
... ["x-karma-points", {}, "integer", 95]
["x-karma-points", {}, "integer", 95],
...
vCard: vCard:
X-KARMA-POINTS:95 X-KARMA-POINTS:95
Example: The following is an example of an unrecognized vCard The following is an example of an unrecognized vCard property
property parameter (that uses a "FLOAT" value as its default) parameter (that uses a "FLOAT" value as its default) specified on a
specified on a recognized vCard property, and the equivalent jCard recognized vCard property, and the equivalent jCard representation of
representation of that property and property parameter. that property and property parameter.
vCard: vCard:
GENDER;X-PROBABILITY=0.8:M GENDER;X-PROBABILITY=0.8:M
jCard: jCard:
... ["gender", { "x-probability": "0.8" }, "text", "M"]
["gender", { "x-probability": "0.8" }, "text", "M"],
...
6. Implementation Status (to be removed prior to publication as an RFC) 6. Implementation Status (to be removed prior to publication as an RFC)
This section describes libraries known to implement this draft as per This section describes libraries known to implement this draft as per
[I-D.sheffer-running-code]. [I-D.sheffer-running-code].
1. ICAL.js - Philipp Kewisch, James Lal. A JavaScript parser for 1. ICAL.js - Philipp Kewisch, James Lal. A JavaScript parser for
iCalendar (rfc5545) iCalendar (rfc5545)
Source: https://github.com/mozilla-comm/ical.js/ Source: https://github.com/mozilla-comm/ical.js/
Maturity: alpha (for jCard) Maturity: alpha (for jCard)
Coverage: Currently geared towards jCal, therefore not all Coverage: Currently geared towards jCal, therefore not all
formats are supported. Includes an online validator. (as formats are supported. Includes an online validator. (as
of rev 847c67c501, 2013-02-14) of rev 847c67c501, 2013-02-14)
Licensing: MPL, Mozilla Public License 2.0 Licensing: MPL, Mozilla Public License 2.0
skipping to change at page 23, line 41 skipping to change at page 23, line 5
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.3.1.2 | | | GROUP | RFCTODO, Section 3.2.1.3 |
+-----------+-----------+--------------------------+ +-----------+-----------+--------------------------+
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 25, line 14 skipping to change at page 24, line 27
[RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML [RFC6321] Daboo, C., Douglass, M., and S. Lees, "xCal: The XML
Format for iCalendar", RFC 6321, August 2011. 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 [RFC6351] Perreault, S., "xCard: vCard XML Representation", RFC
6351, August 2011. 6351, August 2011.
[RFC6868] Daboo, C., "Parameter Value Encoding in iCalendar and
vCard", RFC 6868, February 2013.
10.2. Informative References 10.2. Informative References
[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 [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
skipping to change at page 25, line 44 skipping to change at page 25, line 11
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 vCard Stream is an array with the first element being the ; A jCard component uses the name "vcard" and a properties array.
; string "vcardstream". All remaining elements are jcardobjects. ; Restrictions to which properties and may be specified are to
jcardstream = begin-array
DQUOTE "vcardstream" DQUOTE
*(value-separator jcardobject)
end-array
jcardobject = component
; A jCard object consists of the name string "vcard" and a properties
; array. 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
skipping to change at page 26, line 27 skipping to change at page 25, line 34
DQUOTE type-name DQUOTE DQUOTE type-name DQUOTE
propery-value *(value-separator property-value) propery-value *(value-separator property-value)
end-array end-array
properties-array = begin-array properties-array = begin-array
[ property *(value-separator property) ] [ property *(value-separator property) ]
end-array end-array
; Property values depend on the type-name. Aside from the value types ; Property values depend on the type-name. Aside from the value types
; mentioned here, extensions may make use of other JSON value types. ; mentioned here, extensions may make use of other JSON value types.
property-value = simple-prop-value / structured-prop-value property-value = simple-prop-value / structured-prop-value
simple-prop-value = string / number / boolean simple-prop-value = string / number / true / false
structured-prop-value = structured-prop-value =
begin-array begin-array
[ structured-element *(value-separator structured-element) ] [ structured-element *(value-separator structured-element) ]
end-array end-array
; Each structured element may have multiple values if ; Each structured element may have multiple values if
; semantically allowed ; semantically allowed
structured-element = simple-prop-value / structured-multi-prop structured-element = simple-prop-value / structured-multi-prop
structured-multi-prop = structured-multi-prop =
begin-array begin-array
skipping to change at page 30, line 26 skipping to change at page 29, line 32
* 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
* Add LABEL property example and description * Add LABEL property example and description
* Added acknowledgements * Added acknowledgements
* More typos fixed * More typos fixed
Author's Address draft-ietf-jcardcal-jcard-04
* Added reference to rfc6868
* Various editorial changes per jcardcal issue tracker
* Resolved a few MAY/SHOULD conflicts
* Put the VERSION property into its own section
* Improved GROUP/UNKNOWN registrations by only putting vcard
related information into the registration template
* Removed vcard stream construct.
* Added reference to RFC6868 for both directions
* Corrected some examples and ABNF
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. 114 change blocks. 
304 lines changed or deleted 285 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/