One document matched: draft-ietf-jcardcal-jcard-02.xml
<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'
[
<!ENTITY rfc2119 PUBLIC '' 'bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc4627 PUBLIC '' 'bibxml/reference.RFC.4627.xml'>
<!ENTITY rfc5234 PUBLIC '' 'bibxml/reference.RFC.5234.xml'>
<!ENTITY rfc5545 PUBLIC '' 'bibxml/reference.RFC.5545.xml'>
<!ENTITY rfc5646 PUBLIC '' 'bibxml/reference.RFC.5646.xml'>
<!ENTITY rfc6321 PUBLIC '' 'bibxml/reference.RFC.6321.xml'>
<!ENTITY rfc6350 PUBLIC '' 'bibxml/reference.RFC.6350.xml'>
<!ENTITY rfc6351 PUBLIC '' 'bibxml/reference.RFC.6351.xml'>
<!ENTITY I-D.sheffer-running-code PUBLIC '' 'bibxml3/reference.I-D.sheffer-running-code.xml'>
<!ENTITY I-D.ietf-jcardcal-jcal PUBLIC '' 'bibxml3/reference.I-D.ietf-jcardcal-jcal.xml'>
]>
<?rfc rfcedstyle="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<!-- default = 3 -->
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="no"?>
<?rfc subcompact="no"?>
<?rfc strict="yes"?>
<!-- <?rfc comments="yes"?> -->
<!--<?rfc inline="yes"?> -->
<rfc category='std' ipr='trust200902' docName='draft-ietf-jcardcal-jcard-02'>
<front>
<title abbrev="jCard">jCard: The JSON format for vCard</title>
<author initials="P." surname="Kewisch" fullname="Philipp Kewisch">
<organization abbrev="Mozilla">Mozilla Corporation</organization>
<address>
<postal>
<street>650 Castro Street, Suite 300</street>
<city>Mountain View</city>
<region>CA</region>
<code>94041</code>
<country>USA</country>
</postal>
<email>mozilla@kewis.ch</email>
<uri>http://www.mozilla.org/</uri>
</address>
</author>
<date />
<area>Applications</area>
<workgroup>JSON data formats for vCard and iCalendar</workgroup>
<abstract>
<t>This specification defines "jCard", a JSON format for vCard data.</t>
</abstract>
</front>
<middle>
<section title='Introduction'>
<t>
The vCard data format <xref target='RFC6350'/> has gone through
multiple revisions, most recently vCard 4. The goal followed by this
format is the capture and exchange of information normally stored
within an address book or directory application. As certain similarities
to the iCalendar data format <xref target='RFC5545'/> exist it makes
sense to define a JSON-based data format for vCards that is similar to
the jCal format defined in <xref target='I-D.ietf-jcardcal-jcal'/>.
</t>
<t>
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
defined in <xref target='RFC4627'/> over the classic vCard format is
easier processing for JavaScript based widgets and libraries, especially
in the scope of web-based applications.
</t>
<t>
The key design considerations are essentially the same as those for
<xref target='I-D.ietf-jcardcal-jcal'/> and
<xref target='RFC6321'/>, that is:
<list>
<t>
Round-tripping (converting a vCard instance to jCard and back) will
give the same semantic result as the starting point. For example,
all components, properties and property parameters are guaranteed to
be preserved.
</t>
<t>
Ordering of elements will not necessarily be preserved.
</t>
<t>
Preserve the semantics of the vCard data. While a simple consumer
can easily browse the data in jCard, a full understanding
of vCard is still required in order to modify and/or fully
comprehend the directory data.
</t>
<t>
Ability to handle many extensions to the underlying vCard
specification without requiring an update to this document.
</t>
</list>
</t>
</section>
<section title='Conventions Used in This Document'>
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
<xref target='RFC2119' />.
</t>
<t>
The underlying format used for jCard is JSON. Consequently, the terms
"object" and "array" as well as the four primitive types are to be
interpreted as described in Section 1 of <xref target="RFC4627"/>.
</t>
<t>
Some examples in this document contain "partial" JSON documents used
for illustrative purposes. In these examples, three periods "..." are
used to indicate a portion of the document that has been removed for
compactness.
</t>
</section>
<section title='Converting from vCard to jCard'>
<t>
This section describes how vCard data is converted to jCard using a
simple mapping between the vCard data model and JSON elements.
</t>
<section title="Pre-processing">
<t>
vCard uses a line folding mechanism to limit lines of data to a
maximum line length (typically 72 characters) to ensure maximum
likelihood of preserving data integrity as it is transported via
various means (e.g., email) - see Section 3.2 of <xref target='RFC6350'/>.
Prior to converting vCard data into jCard all folded lines MUST be
unfolded.
</t>
<t>
vCard data uses an "escape" character sequence for text values and
property parameter values. When such text elements are converted into
jCard the escaping MUST be removed. See Section 3.4 of
<xref target='RFC6350'/>. The only escaping that may be applied is
any escaping mandated by JSON.
</t>
<t>
One key difference in the formatting of values used in vCard and
jCard is that in jCard the specification uses date/time
values aligned with the extended format of
<xref target="ISO.8601.2004"/>. The sections of this document
describing the various date and time formats contain more information
on the use of the complete representation, reduced accuracy or
truncated representation.
</t>
</section>
<section title="vCard Stream">
<t>
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.
</t>
<t>
In the typical case where there is only one vCard object,
encapsulation inside a "vcardstream" array MAY be omitted.
</t>
<t>
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:
<list style="numbers">
<t>The string "vcard"</t>
<t>An array of jCard properties</t>
</list>
</t>
<t>
The representation of a vCard object in JSON will be named
"vcard component" throughout this document.
</t>
<t>
<figure>
<preamble>Example:</preamble>
<artwork><![CDATA[
["vcardstream",
["vcard",
[ /* properties */ ]
],
["vcard",
[ /* properties */ ]
],
...
]
]]></artwork></figure>
</t>
<t>
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 <xref target='RFC6350'/>. In addition, the vCard format is
versioned, therefore the "version" property is mandatory. To comply
with Section 6.7.9 of <xref target='RFC6350'/>, the value of the
version property MUST be "4.0".
</t>
</section>
<section anchor="properties" title="Properties (RFC6350 section 6)">
<t>
Each individual vCard property is represented in jCard by an array
with three fixed elements, followed by one or more additional
elements, depending on if the property is a multi-value property as
described in Section 3.3 of <xref target="RFC6350"/>.
</t>
<t>
The array consists of the following fixed elements:
<list style="numbers">
<t>
The name of the property as a string, but in lowercase.
</t>
<t>
An object containing the parameters as described in
<xref target="parameters"/>.
</t>
<t>
The type identifier string of the value, in lowercase.
</t>
</list>
The remaining elements of the array are used for the value of the
property. For single-value properties, the array MUST have exactly
four elements, for multi-valued properties as described in
<xref target="multivalue"/> there can be any number of additional
elements.
</t>
<t>
The array describing the property can then be inserted into the array
designated for properties in the "vcard" component.
</t>
<t>
<figure>
<preamble>Example:</preamble>
<artwork><![CDATA[
["vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "John Doe"],
["gender", {}, "text", "M"],
...
],
]
]]></artwork></figure>
</t>
<t>
The property parameters in the second element of the property array
associate a set of parameter names with their respective value.
Parameters are further described in <xref target="parameters"/>.
</t>
<t>
To allow for a cleaner implementation, the parameter object MUST be
present even if there are no parameters. In this case, an empty
object MUST be used.
</t>
<t>
As described in <xref target="structured-props"/>, it is important to
check the data type of the value even if it is assumed to be a string
in most cases. The value could turn out to be a structured value, in
which case the type is an array.
</t>
<section title="Special Cases for Properties">
<t>
This section describes some properties that have special handling
when converting to jCard.
</t>
<section anchor="multivalue" title="Multi-valued Properties">
<t>
Various vCard properties defined in <xref target="RFC6350"/>,
for example the "CATEGORIES" property, are defined as
multi-valued properties. In jCal these properties are added as
further members of the array describing the property.
</t>
<t>
Note that additional multi-valued properties may be added in
extensions to the iCalendar format.
</t>
<t>
<figure>
<preamble>Example:</preamble>
<artwork><![CDATA[
["vcard",
[
["categories", {}, "text", "computers", "cameras"],
...
],
...
]
]]></artwork>
</figure>
</t>
</section>
<section anchor="grouping" title="Grouping of Properties">
<t>
<xref target='RFC6350'/>
Section 3.3 defines a grouping construct that is used to group
related properties together. In jCard, a new GROUP parameter is
introduced. Its purpose is to eliminate the need for group syntax
in jCard, thus unifying the general syntax with that of jCal.
<list style="hanging">
<t hangText="Namespace:"><empty></t>
<t hangText="Parameter name:">GROUP</t>
<t hangText="Purpose:">To simplify the jCard format.</t>
<t hangText="Description:">
The GROUP parameter is reserved for the exclusive use of
the jCard format [RFCTODO]
<cref>Replace RFCTODO with the target RFC number for this document</cref>.
It MUST NOT be used in plain
vCard <xref target="RFC6350"/>, nor in xCard
<xref target="RFC6351"/>. In jCard, the parameter's value
is a single opaque string. Conversion rules are as follows:
<list style="symbols">
<t>
From vCard to jCard, the group construct (see
<xref target="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.
</t>
<t>
From jCard to vCard, the reverse procedure is
performed. The GROUP parameter MUST NOT appear in the
resulting vCard.
</t>
</list>
</t>
<t hangText="Format definition:">(Not applicable)</t>
<t hangText="Example:">
<figure><artwork><![CDATA[
CONTACT.FN:Mr. John Q. Public\, Esq.
]]></artwork></figure>
is equivalent to:
<figure><artwork><![CDATA[
[ "fn", { "group": "CONTACT" }, "text", "Mr. John Q. Public, Esq." ]
]]></artwork></figure>
</t>
</list>
</t>
</section>
<section anchor="structured-props" title="Structured Property Values">
<t>
The vCard specification defines properties with structured
values, for example GENDER or ADR. A structured value is defined
as a value that contains multiple text components, delimited by
the SEMICOLON character. In jCard, the property value is an
array containing one element for each text component.
<figure>
<preamble>vCard Example:</preamble>
<artwork><![CDATA[
ADR:;;Main Street 123;Any Town;CA;91921-1234;U.S.A.
]]></artwork></figure>
<figure>
<preamble>jCard Example:</preamble>
<artwork><![CDATA[
["adr", {}, "text",
[
"", "", "Main Street 123",
"Any Town", "CA", "91921-1234", "U.S.A."
]
]
]]></artwork></figure>
</t>
<t>
Some vCard properties, for example ADR, also allow a structured
value element that itself has multiple values. In this case, the
element of the array describing the structured value is itself an
array with one element for each of the component's multiple
values.
<figure>
<preamble>vCard Example:</preamble>
<artwork><![CDATA[
ADR:;;My Street,Left Side,Second Shack;Hometown;PA;18252;U.S.A.
]]></artwork></figure>
<figure>
<preamble>jCard Example:</preamble>
<artwork><![CDATA[
["adr", {}, "text",
[
"",
"",
["My Street", "Left Side", "Second Shack"],
"Hometown",
"PA",
"18252",
"U.S.A."
]
]
]]></artwork></figure>
</t>
<t>
In both cases, the array element values MUST have the primative
type that matches the jCard type identifier. In
<xref target="RFC6350"/>, there are only structured text values
and thus only JSON strings are used. Extensions may for example
define structured number or boolean values, where JSON number or
boolean types MUST be used.
</t>
<t>
If a multi-valued text component is changed to hold only one
value, the text component SHOULD be represented as a single
primative value, but MAY be represented as an array with a single
primative value.
</t>
<t>
Similarly, structured values that consist of two text components
with one being optional (for example, GENDER) MAY be represented
as a single text value. Therefore, implementors SHOULD check even
known property values for structured information. This is
especially important for languages where accessing array members
is done by the same construct as accessing characters of a
string.
<figure>
<preamble>Examples:</preamble>
<artwork><![CDATA[
["gender", {}, "text", ["F", "grrrl"] ],
["gender", {}, "text", "M" ],
]]></artwork></figure>
</t>
</section>
</section>
</section>
<section anchor="parameters" title="Parameters (RFC6350 Section 5)">
<t>
Property parameters are represented as a JSON object where each
key-value pair represents the vCard parameter name and its value.
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 is represented in jCard by the "lang" key. Any
new vCard parameters added in the future will be converted in the
same way.
</t>
<t>
<figure>
<preamble>Example:</preamble>
<artwork><![CDATA[
["vcard",
[
["role", { "lang": "tr" }, "text", "roca"],
...
],
...
]
]]></artwork></figure>
</t>
<section title="VALUE parameter">
<t>
vCard defines a "VALUE" property parameter (Section 5.2 of
<xref target='RFC6350'/>). This property parameter MUST NOT be
added to the parameters object. Instead, the value type is always
explicitly mentioned in the third element of the array describing
the property. Thus, when converting from vCard to jCard, any "VALUE"
property parameters are skipped. When converting from jCard into
vCard, the 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 <xref target="unrecognized"/>
for information on handling unknown value types.
</t>
</section>
<section title="Multi-value Parameters">
<t>
In <xref target='RFC6350'/>, some parameters allow using a
COMMA-separated list of values. To ease processing in jCard, the
value to such parameters MUST be represented in an array containing
the separated values. The array elements MUST be string values.
Single-value parameters SHOULD be represented using a single string
value, but an array with one element MAY also be used. An example
for a such parameter is the vCard "SORT-AS" parameter, more such
parameters may be added in extensions.
</t>
<t>
DQUOTE characters used to encapsulate the separated values MUST NOT
be added to the jCard parameter value.
</t>
<t>
<figure>
<preamble>Example 1:</preamble>
<artwork><![CDATA[
["vcard",
[
["n",
{ "sort-as": ["Harten", "Rene"] },
"text",
"van der Harten;Rene,J.;Sir;R.D.O.N."
],
["fn", {}, "text", "Rene van der Harten"]
...
],
...
]
]]></artwork></figure>
</t>
</section>
</section>
<section anchor="values" title="Values (RFC6350 Section 4)">
<t>
The type of a vCard value is explicitly mentioned in the third
element of the array describing a jCard property. The actual values of
the property can be found in the fourth and following elements of the
array.
</t>
<section title="Text (RFC6350 Section 4.1)">
<t><list style="hanging">
<t hangText="Description:">
vCard "TEXT" property values are represented by a
property with the type identifier "text". The value elements
are JSON strings. For details on structured text values, see
<xref target="structured-props"/>.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["kind", {}, "text", "group"],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="URI (RFC6350 Section 4.2)">
<t><list style="hanging">
<t hangText="Description:">
vCard "URI" property values are represented by a property
with the type identifier "uri". The value elements
are JSON strings.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["source", {}, "uri", "ldap://ldap.example.com/cn=babs%20jensen"],
...
]]></artwork></figure></t>
</list></t>
</section>
<section anchor="proptype-date" title="Date (RFC6350 Section 4.3.1)">
<t><list style="hanging">
<t hangText="Description:">
vCard "DATE" property values are represented by a property with
the type identifier "date". The value elements are JSON strings
with the same date value specified by <xref target="RFC6350"/>,
but represented using the extended format specified in
<xref target="ISO.8601.2004"/>, Section 4.1.2. If the complete
representation is not used, the same date format restrictions
regarding reduced accuracy, truncated representation and expanded
representation noted in <xref target="RFC6350"/> Section 4.1.2.3
apply. Whenever the extended format is not applicable, the basic
format MUST be used.
</t>
<t hangText="ABNF Schema:"><figure><artwork><![CDATA[
date-complete = year "-" month "-" day ;YYYY-MM-DD
date-noreduc = date-complete
/ "--" month "-" day; --MM-DD
/ "---" day; ---DDD
date = date-noreduc
/ year; YYYY
/ year "-" month ; YYYY-MM
/ "--" month; --MM
]]></artwork></figure></t>
<t hangText="Examples:"><figure><artwork><![CDATA[
...
["bday", {}, "date", "1985-04-12"],
["bday", {}, "date", "1985-04"],
["bday", {}, "date", "1985"],
["bday", {}, "date", "--04-12"],
["bday", {}, "date", "---12"],
...
]]></artwork></figure></t>
</list></t>
<t>
This table contains possible converisions between the vCard
DATE format its jCard date. This information is to be seen as
an informative reference, the normative reference is
<xref target="ISO.8601.2000"/> and
<xref target="ISO.8601.2004"/>:
</t>
<texttable>
<ttcol></ttcol>
<ttcol>vCard</ttcol>
<ttcol>jCard</ttcol>
<c>Complete</c>
<c>19850412</c>
<c>1985-04-12</c>
<c>Reduced</c>
<c>1985-04</c>
<c>1985-04</c>
<c>Reduced</c>
<c>1985</c>
<c>1985</c>
<c>Truncated</c>
<c>--0412</c>
<c>--04-12</c>
<c>Truncated</c>
<c>--04</c>
<c>--04</c>
<c>Truncated</c>
<c>---12</c>
<c>---12</c>
</texttable>
</section>
<section anchor="proptype-time" title="Time (RFC6350 Section 4.3.2)">
<t><list style="hanging">
<t hangText="Description:">
vCard "TIME" property values are represented by a property with
the type identifier "time". The value elements are JSON strings
with the same time value specified by <xref target="RFC6350"/>,
but represented using the extended format specified in
<xref target="ISO.8601.2004"/>, Section 4.2. If the complete
representation is not used, the same time format restrictions
regarding reduced accuracy, decimal fraction and
truncated representation noted in <xref target="RFC6350"/>
Section 4.3.2 apply. Whenever the extended format is not
applicable, the basic format MUST be used. The seconds value of
60 MUST only be used to account for positive "leap" seconds and
the midnight hour is always represented by 00, never 24.
Fractions of a second are not supported by this format. Contrary
to <xref target='I-D.ietf-jcardcal-jcal'/>, UTC
offsets are permitted within a time value.
</t>
<t hangText="ABNF Schema:"><figure><artwork><![CDATA[
time-notrunc = hour [":" minute [":" second]] [zone]
time = time-notrunc
/ "-" minute ":" second [zone]; -mm:ss
/ "-" minute [zone]; -mm
/ "--" second [zone]; --ss
]]></artwork></figure></t>
<t hangText="Examples:"><figure><artwork><![CDATA[
...
["x-time-local", {}, "time", "12:30:00"],
["x-time-utc", {}, "time", "12:30:00Z"],
["x-time-offset", "time", "12:30:00-08:00"],
["x-time-reduced", "time", "23"],
["x-time-truncated", "time", "-30"],
...
]]></artwork></figure></t>
</list></t>
<t>
This table contains possible converisions between the vCard TIME
format its jCard time.This information is to be seen as an
informative reference, the normative reference is
<xref target="ISO.8601.2000"/> and
<xref target="ISO.8601.2004"/>:
</t>
<texttable>
<ttcol></ttcol>
<ttcol>vCard</ttcol>
<ttcol>jCard</ttcol>
<c>Complete</c>
<c>232050</c>
<c>23:20:50</c>
<c>Reduced</c>
<c>2320</c>
<c>23:20</c>
<c>Reduced</c>
<c>23</c>
<c>23</c>
<c>Truncated</c>
<c>-2050</c>
<c>-20:50</c>
<c>Truncated</c>
<c>-20</c>
<c>-20</c>
<c>Truncated</c>
<c>--50</c>
<c>--50</c>
</texttable>
<t>
Also, all combinations may have any zone designator appended, as in
the complete representation.
</t>
</section>
<section anchor="proptype-date-time" title="Date-Time (RFC6350 Section 4.3.3)">
<t><list style="hanging">
<t hangText="Description:">
vCard "DATE-TIME" property values are represented by a property
with the type identifier "date-time". The value elements are JSON
strings with the same date value specified by
<xref target="RFC6350"/>,
but represented using the extended format specified in
<xref target="ISO.8601.2004"/>, Section 4.3. If the complete
representation is not used, the same date and time format
restrictions as in <xref target="proptype-time"/> and
<xref target="proptype-date"/> apply. Just
as in <xref target="RFC6350"/>, truncation of the date part is
permitted.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["anniversary", {}, "date-time", "2013-02-14T12:30:00"],
["anniversary", {}, "date-time", "2013-01-10T19:00:00Z"],
["anniversary", {}, "date-time", "2013-08-15T09:45:00+01:00"],
["anniversary", {}, "date-time", "---15T09:45:00+01:00"],
...
]]></artwork></figure></t>
</list></t>
<t>
This table contains possible converisions between the vCard
DATE-TIME format its jCard date-time. This information is to be
seen as an informative reference, the normative reference is
<xref target="ISO.8601.2000"/> and
<xref target="ISO.8601.2004"/>:
</t>
<texttable>
<ttcol>Representation</ttcol>
<ttcol>vCard</ttcol>
<ttcol>jCard</ttcol>
<c>Complete</c>
<c>19850412T232050</c>
<c>1985-04-12T23:20:50</c>
<c>Complete</c>
<c>19850412T232050Z</c>
<c>1985-04-12T23:20:50Z</c>
<c>Complete</c>
<c>19850412T232050+0400</c>
<c>1985-04-12T23:20:50+04:00</c>
<c>Complete</c>
<c>19850412T232050+04</c>
<c>1985-04-12T23:20:50+04</c>
<c>Reduced</c>
<c>19850412T2320</c>
<c>1985-04-12T23:20</c>
<c>Reduced</c>
<c>19850412T23</c>
<c>1985-04-12T23</c>
<c>Truncated and Reduced</c>
<c>--0412T2320</c>
<c>--04-12T23:20</c>
<c>Truncated and Reduced</c>
<c>--04T2320</c>
<c>--04T23:20</c>
<c>Truncated and Reduced</c>
<c>---12T2320</c>
<c>---12T23:20</c>
<c>Truncated and Reduced</c>
<c>--0412T2320</c>
<c>--04-12T23:20</c>
<c>Truncated and Reduced</c>
<c>--04T23</c>
<c>--04T23</c>
</texttable>
<t>
As specified in <xref target="ISO.8601.2000"/>, the date component
shall not be represented with reduced accuracy and the time
component shall not be truncated. Also, all combinations may have
any zone designator appended, as in the complete representation.
</t>
</section>
<section title="Date and/or Time (RFC6350 Section 4.3.4)">
<t><list style="hanging">
<t hangText="Description:">
vCard "DATE-AND-OR-TIME" property values are represented by a
property with the type identifier "date-and-or-time". The value
elements are either a date-time
(<xref target="proptype-date-time"/>), a date
(<xref target="proptype-date"/>) or a time
(<xref target="proptype-time"/>) value.
Just as in <xref target="RFC6350"/> Section 4.3.4, a stand-alone
time value MUST always be preceded by a "T".
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["bday", {}, "date-and-or-time", "2013-02-14T12:30:00"],
["bday", {}, "date-and-or-time", "---22T14:00"]
["bday", {}, "date-and-or-time", "1985"],
["bday", {}, "date-and-or-time", "T12:30"],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Timestamp (RFC6350 Section 4.3.5)">
<t><list style="hanging">
<t hangText="Description:">
vCard "TIMESTAMP" property values are represented by a
property with the type identifier "timestamp". The value
elements are JSON strings with the same timestamp value specified
by <xref target="RFC6350"/>, but represented using the extended
format and complete representation specified in <xref
target="ISO.8601.2004"/>, Section 4.3.2.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["rev", {}, "timestamp", "2013-02-14T12:30:00"],
["rev", {}, "timestamp", "2013-02-14T12:30:00Z"],
["rev", {}, "timestamp", "2013-02-14T12:30:00-05"],
["rev", {}, "timestamp", "2013-02-14T12:30:00-05:00"],
...
]]></artwork></figure></t>
</list></t>
<t>
This table contains possible converisions between the vCard
TIMESTAMP format its jCard timestamp. This information is to be
seen as an informative reference, the normative reference is
<xref target="ISO.8601.2000"/> and
<xref target="ISO.8601.2004"/>:
</t>
<texttable>
<ttcol>Representation</ttcol>
<ttcol>vCard</ttcol>
<ttcol>jCard</ttcol>
<c>Complete</c>
<c>19850412T232050</c>
<c>1985-04-12T23:20:50</c>
<c>Complete</c>
<c>19850412T232050Z</c>
<c>1985-04-12T23:20:50Z</c>
<c>Complete</c>
<c>19850412T232050+0400</c>
<c>1985-04-12T23:20:50+04:00</c>
<c>Complete</c>
<c>19850412T232050+04</c>
<c>1985-04-12T23:20:50+04</c>
</texttable>
</section>
<section title="Boolean (RFC6350 Section 4.4)">
<t><list style="hanging">
<t hangText="Description:">
vCard "BOOLEAN" property values are represented by a property
with the type identifier "boolean". The value element is a JSON boolean
value.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["x-non-smoking", {}, "boolean", true],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Integer (RFC6350 Section 4.5)">
<t><list style="hanging">
<t hangText="Description:">
vCard "INTEGER" property values are represented by a property
with the type identifier "integer". The value elements are JSON primitive number values.
</t>
<t hangText="Examples:"><figure><artwork><![CDATA[
...
["x-karma-points", {}, "integer", 42],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Float (RFC6350 Section 4.6)">
<t><list style="hanging">
<t hangText="Description:">
vCard "FLOAT" property values are represented by a property
with the type identifier "float". The value elements are JSON primitive number values.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["x-grade", {}, "float", 1.3],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="UTC Offset (RFC6350 Section 4.7)">
<t><list style="hanging">
<t hangText="Description:">
vCard "UTC-OFFSET" property values are represented by a
property with the type identifier "utc-offset". The value elements are JSON
strings with the same UTC offset value specified by
<xref target="RFC6350"/>, with the exception that the hour and
minute components are separated by a ":" character, for
consistency with the <xref target="ISO.8601.2004"/> timezone offset,
extended format.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
// Note: [RFC6350] mentions use of utc-offset
// for the TZ property as NOT RECOMMENDED
["tz", {}, "utc-offset", "-05:00"],
..
]]></artwork></figure></t>
</list></t>
</section>
<section title="Language Tag (RFC6350 Section 4.8)">
<t><list style="hanging">
<t hangText="Description:">
vCard "LANGUAGE-TAG" property values are represented by a
property with the type identifier "language-tag". The value elements are JSON
strings containing a single language-tag, as defined in
<xref target="RFC5646"/>.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["lang", {}, "language-tag", "de"],
..
]]></artwork></figure></t>
</list></t>
</section>
</section>
<section title="Extensions (RFC6350 Section 6.10)">
<t>
vCard extension properties and property parameters (those with an
"X-" prefix in their name) are handled in the same way as other
properties and property parameters: the property is represented by an
array, the property parameter represented by an object. The property
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 the "x-foo" jCard property. See <xref target="unrecognized"/>
for how to deal with default values for unrecognized extension
properties or property parameters.
</t>
</section>
</section>
<section title="Converting from jCard into vCard">
<t>
When converting property and property parameter values, the
names SHOULD be converted to uppercase. Although vCard names are
case insensitive, common practice is to keep them all uppercase
following the actual definitions in <xref target="RFC6350"/>.
</t>
<t>
Backslash escaping and line folding MUST be applied to the resulting
vCard data as required by <xref target="RFC6350"/>.
</t>
<t>
When converting to vCard, the VALUE parameter MUST be added to
properties whose default value type is unknown. The VALUE parameter
SHOULD NOT be added to properties using the default value type.
</t>
</section>
<section title="Handling Unrecognized Properties or Parameters" anchor="unrecognized">
<t>
In vCard, properties have a default value type specified by their
definition, e.g. "BDAY"'s value type is "date-and-or-time", but it can
also be reset to a single "text" value. When a property uses its
default value type, the "VALUE" property parameter does not need to be
specified on the property.
</t>
<t>
When new properties are defined or "X-" properties used, a vCard
to jCard converter might not recognize them, and not know what the
appropriate default value types are, yet they need to be able to
preserve the values. A similar issue arises for unrecognized property
parameters.
</t>
<t>
In jCard, a new UNKNOWN property value type is introduced. Its purpose
is to allow preserving unknown property types when roundtripping between
jCard and vCard.
<list style="hanging">
<t hangText="Value Data Type name:">UNKNOWN</t>
<t hangText="Purpose:">
To allow preserving unknown property types during roundtripping
</t>
<t hangText="Description:">
The UNKNOWN value data type is reserved for the exclusive use of
the jCard format [RFCTODO]
<cref>Replace RFCTODO with the target RFC number for this document</cref>.
It MUST NOT be used in plain vCard <xref target="RFC6350"/>.
Conversion rules are as follows:
<list style="symbols">
<t>When converting vCard into jCard:
<list style="symbols">
<t>
Any property that does not include a "VALUE" property
parameter and whose default value type is not known, MUST
be converted to a primative JSON string. The content of
that string is the unprocessed value text. Also, value type
MUST be set to "unknown".
</t>
<t>
To correctly implement this format, it is critical that if
the default type is not known that the type "unknown" is
used. If this requirement is ignored and for example "text"
is used, additional escaping may occur which breaks
roundtripping values.
</t>
<t>
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.
</t>
</list>
</t>
<t>When converting jCard into vCard:
<list style="symbols">
<t>
Since jCard always explicitly specifies the value type, it
can always be converted to vCard using the VALUE parameter.
</t>
<t>
If the value type specified in jCard matches the default
value type in vCard, the VALUE parameter SHOULD be omitted.
</t>
<t>
If the valye type specified in jCard is set to "unknown",
the value MUST be taken over in vCard without proessing. In
this case, the VALUE parameter MUST NOT be specified.
</t>
</list>
</t>
</list>
</t>
<t hangText="Format definition:">(Not applicable)</t>
</list>
</t>
<t>
Example: 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.
</t>
<figure><preamble>vCard:</preamble><artwork><![CDATA[
X-COMPLAINT-URI:mailto:abuse@example.org
]]></artwork></figure>
<figure><preamble>jCard:</preamble><artwork><![CDATA[
...
["x-complaint-uri", {}, "unknown", "mailto:abuse@example.org"],
...
]]></artwork></figure>
<t>
Example: 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 type is not added to the vCard data and escaping, aside
from standard JSON string escaping, is not processed.
</t>
<figure><preamble>jCard:</preamble><artwork><![CDATA[
...
["x-coffee-data", {}, "unknown", "Stenophylla;Guinea\\,Africa"],
...
]]></artwork></figure>
<figure><preamble>vCard:</preamble><artwork><![CDATA[
X-COFFEE-DATA:Stenophylla;Guinea\,Africa
]]></artwork></figure>
<t>
Example: The following is an example of a jCard property (where the
corresponding vCard property uses a "INTEGER" value as its default), and
the equivalent vCard representation of that property. It is assumed that
the parser has knowledge of the default data type for the
"x-karma-points" property.
</t>
<figure><preamble>jCard:</preamble><artwork><![CDATA[
...
["x-karma-points", {}, "integer", 95],
...
]]></artwork></figure>
<figure><preamble>vCard:</preamble><artwork><![CDATA[
X-KARMA-POINTS:95
]]></artwork></figure>
<t>
Example: The following is an example of an unrecognized vCard
property parameter (that uses a "FLOAT" value as its default) specified
on a recognized vCard property, and the equivalent jCard
representation of that property and property parameter.
</t>
<figure><preamble>vCard:</preamble><artwork><![CDATA[
GENDER;X-PROBABILITY=0.8:M
]]></artwork></figure>
<figure><preamble>jCard:</preamble><artwork><![CDATA[
...
["gender", { "x-probability": "0.8" }, "text", "M"],
...
]]></artwork></figure>
</section>
<section title="Implementation Status (to be removed prior to publication as an RFC)">
<t>
This section describes libraries known to implement this draft as per
<xref target='I-D.sheffer-running-code'/>.
<list style="numbers">
<t>
ICAL.js - Philipp Kewisch, James Lal. A JavaScript parser for iCalendar (rfc5545)
<list style="hanging">
<t hangText="Source:">https://github.com/mozilla-comm/ical.js/</t>
<t hangText="Maturity:">alpha (for jCard)</t>
<t hangText="Coverage:">Currently geared towards jCal, therefore not all formats are supported. Includes an online validator. (as of rev 847c67c501, 2013-02-14)</t>
<t hangText="Licensing:">MPL, Mozilla Public License 2.0</t>
</list>
</t>
<t>
Py Calendar - Cyrus Daboo. iCalendar/vCard Library
<list style="hanging">
<t hangText="Source:">https://svn.calendarserver.org/repository/calendarserver/PyCalendar/branches/json/</t>
<t hangText="Maturity:">production</t>
<t hangText="Coverage:">All aspects of this draft, up to version 01.</t>
<t hangText="Licensing:">Apache License, Version 2.0</t>
</list>
</t>
<t>
ez-vcard - Michael Angstadt. A vCard parser library written in Java
<list style="hanging">
<t hangText="Source:">https://code.google.com/p/ez-vcard/</t>
<t hangText="Maturity:">production</t>
<t hangText="Coverage">All aspects of this draft.</t>
<t hangText="Licensing:">New BSD License</t>
</list>
</t>
</list>
</t>
<t>
Additionally, interoperability testing of this draft is an ongoing
effort under members of calconnect, the Calendaring and Scheduling
Consortium. CalDAV Vendors are looking into supporting this draft.
</t>
</section>
<section title="Security Considerations" anchor="security">
<t>
For security considerations specific to calendar data, see Section 9 of
<xref target="RFC6350"/>. Since this specification is a mapping from
vCard, no new security concerns are introduced related to calendar
data.
</t>
<t>
The use of JSON as a format does have security risks. Section 7 of
<xref target="RFC4627"/> discusses these risks.
</t>
</section>
<section title="IANA Considerations">
<t>
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 in JSON.
<list style="hanging">
<t hangText="Type name:">application</t>
<t hangText="Subtype name:">vcard+json</t>
<t hangText="Required parameters:">none</t>
<t hangText="Optional parameters:">
version as defined for the text/vcard
media type in <xref target="RFC6350"/>.
</t>
<t hangText="Encoding considerations:">
Same as encoding considerations of application/json as specified in
<xref target="RFC4627"/>.
</t>
<t hangText="Security considerations:">See <xref target="security"/>.</t>
<t hangText="Interoperability considerations:">
This media type provides an alternative format for vCard data
based on JSON.
</t>
<t hangText="Published specification:">This specification.</t>
<t hangText="Applications which use this media type:">
Applications that currently make use of the text/vcard media
type can use this as an alternative. Similarly, Applications that
use the application/json media type to transfer directory data
can use this to further specify the content.
</t>
<t hangText="Person & email address to contact for further information:">vcarddav@ietf.org</t>
<t hangText="Intended usage:">COMMON</t>
<t hangText="Restrictions on usage:">
There are no restrictions on where this media type can be used.
</t>
<t hangText="Author:">
See the "Author's Address" section of this document.
</t>
<t hangText="Change controller:">IETF</t>
</list>
</t>
<section title="GROUP vCard Parameter">
<t>
IANA has added the following entry to the vCard Parameters registry,
defined in Section 10.3.2 of <xref target="RFC6350"/>.
</t>
<texttable>
<ttcol>Namespace</ttcol>
<ttcol>Parameter</ttcol>
<ttcol>Reference</ttcol>
<c></c>
<c>GROUP</c>
<c>
RFCTODO, <xref target="grouping"/><cref>Replace RFCTODO with the target RFC number for this document</cref>.
</c>
</texttable>
</section>
<section title="UNKNOWN vCard Value Data Type">
<t>
IANA has added the following entry to the vCard Data Types registry,
defined in Section 10.3.3 of <xref target="RFC6350"/>.
</t>
<texttable>
<ttcol>Value Data Type</ttcol>
<ttcol>Reference</ttcol>
<c>UNKNOWN</c>
<c>
RFCTODO, <xref target="unrecognized"/><cref>Replace RFCTODO with the target RFC number for this document</cref>.
</c>
</texttable>
</section>
</section>
<section title="Acknowledgments">
<t>
The author would like to thank the following for their valuable
contributions: Cyrus Daboo, Mike Douglass, William Gill, Erwin Rehme,
and Dave Thewlis. This specification originated from the work of the
XML-JSON technical committee of the Calendaring and Scheduling
Consortium.
</t>
</section>
</middle>
<back>
<references title="Normative References">
&rfc2119;
&rfc5234;
&rfc5545;
&rfc5646;
&rfc6321;
&rfc6350;
&rfc6351;
&I-D.ietf-jcardcal-jcal;
<reference anchor="ISO.8601.2000">
<front>
<title>
"Data elements and interchange formats -- Information interchange
-- Representation of dates and times"
</title>
<author>
<organization>International Organization for Standardization</organization>
</author>
<date year="2000" month="12"/>
</front>
<seriesInfo name="ISO" value="8601"/>
</reference>
<reference anchor="ISO.8601.2004">
<front>
<title>
"Data elements and interchange formats -- Information interchange
-- Representation of dates and times"
</title>
<author>
<organization>International Organization for Standardization</organization>
</author>
<date year="2004" month="12"/>
</front>
<seriesInfo name="ISO" value="8601"/>
</reference>
</references>
<references title="Informative References">
&rfc4627;
&I-D.sheffer-running-code;
<reference anchor="calconnect-artifacts"
target="http://www.calconnect.org/artifacts.shtml">
<front>
<title>Code Artifacts and Schemas</title>
<author>
<organization>The Calendaring and Scheduling Consortium</organization>
</author>
<date/>
</front>
</reference>
</references>
<section anchor="schema" title="ABNF Schema">
<t>
Below is an ABNF schema as per <xref target="RFC5234"/> for vCard
in JSON. ABNF Symbols not described here are taken from
<xref target="RFC4627"/>. The schema is non-normative and given for
reference only.
</t>
<t>
The numeric section numbers given in the comments refer to section in
<xref target="RFC6350"/>. Additional semantic restrictions apply,
especially regarding the allowed properties and sub-components per
component. Details on these restrictions can be found in this document
and <xref target="RFC6350"/>.
</t>
<t>
Additional schemas may be available on the internet at
<xref target="calconnect-artifacts"/>.
</t>
<figure><artwork><![CDATA[
; A vCard Stream is an array with the first element being the
; string "vcardstream". All remaining elements are jcardobjects.
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.
jcardobject = begin-array
DQUOTE component-name DQUOTE value-separator
properties-array
end-array
; A jCard property consists of the name string, parameters object,
; type string and one or more values as specified in this document.
property = begin-array
DQUOTE property-name DQUOTE value-separator
params-object value-separator
DQUOTE type-name DQUOTE
propery-value *(value-separator property-value)
end-array
properties-array = begin-array
[ property *(value-separator property) ]
end-array
; Property values depend on the type-name. Aside from the value types
; mentioned here, extensions may make use of other JSON value types.
property-value = simple-prop-value / structured-prop-value
simple-prop-value = string / number / boolean
structured-prop-value =
begin-array
[ structured-element *(value-separator structured-element) ]
end-array
; Each structured element may have multiple values if
; semantically allowed
structured-element = simple-prop-value / structured-multi-prop
structured-multi-prop =
begin-array
[ simple-prop-value *(value-separator simple-prop-value) ]
end-array
; The jCard params-object is a JSON object which follows the semantic
; guidelines described in this document.
params-object = begin-object
[ params-member *(value-separator params-member) ]
end-object
params-member = DQUOTE param-name DQUOTE name-separator param-value
param-value = string / param-multi
param-multi = begin-array
[ string *(value-separtor string) ]
end-array
; The type MUST be a valid type as described by this document. New
; value types can be added by extensions.
type-name = "text" / "uri" / "date" / "time" / "date-time" /
"boolean" / "integer" / "float" / "utc-offset" /
"language-tag" / x-type
; Property, parameter and type names MUST be lowercase. Additional
; semantic restrictions apply as described by this document and
; RFC6350.
component-name = lowercase-name
property-name = lowercase-name
param-name = lowercase-name
x-type = lowercase-name
lowercase-name = 1*(%x61-7A / DIGIT / "-")
]]></artwork></figure>
</section>
<section title="Examples">
<t>
This section contains an example of a vCard object with its jCard
representation.
</t>
<section title="Example: vCard of the author of RFC6350">
<section title="vCard Data">
<figure><artwork><![CDATA[
BEGIN:VCARD
VERSION:4.0
FN:Simon Perreault
N:Perreault;Simon;;;ing. jr,M.Sc.
BDAY:--0203
ANNIVERSARY:20090808T1430-0500
GENDER:M
LANG;PREF=1:fr
LANG;PREF=2:en
ORG;TYPE=work:Viagenie
ADR;TYPE=work:;Suite D2-630;2875 Laurier;
Quebec;QC;G1V 2M2;Canada
TEL;VALUE=uri;TYPE="work,voice";PREF=1:tel:+1-418-656-9254;ext=102
TEL;VALUE=uri;TYPE="work,cell,voice,video,text":tel:+1-418-262-6501
EMAIL;TYPE=work:simon.perreault@viagenie.ca
GEO;TYPE=work:geo:46.772673,-71.282945
KEY;TYPE=work;VALUE=uri:
http://www.viagenie.ca/simon.perreault/simon.asc
TZ:-0500
URL;TYPE=home:http://nomis80.org
END:VCARD
]]></artwork></figure>
</section>
<section title="jCard Data">
<figure><artwork><![CDATA[
["vcard",
[
["version", {}, "text", "4.0"],
["fn", {}, "text", "Simon Perreault"],
["n",
{},
"text",
["Perreault", "Simon", "", "", ["ing. jr", "M.Sc."]]
],
["bday", {}, "date-and-or-time", "--02-03"],
["anniversary",
{},
"date-and-or-time",
"2009-08-08T14:30:00-05:00"
],
["gender", {}, "text", "M"],
["lang", { "pref": "1" }, "language-tag", "fr"],
["lang", { "pref": "2" }, "language-tag", "en"],
["org", { "type": "work" }, "text", "Viagenie"],
["adr",
{ "type": "work" },
"text",
[
"",
"Suite D2-630",
"2875 Laurier",
"Quebec",
"QC",
"G1V 2M2",
"Canada"
]
],
["tel",
{ "type": ["work", "voice"], "pref": "1" },
"uri",
"tel:+1-418-656-9254;ext=102"
],
["tel",
{ "type": ["work", "cell", "voice", "video", "text"] },
"uri",
"tel:+1-418-262-6501"
],
["email",
{ "type": "work" },
"text",
"simon.perreault@viagenie.ca"
],
["geo", { "type": "work" }, "uri", "geo:46.772673,-71.282945"],
["key",
{ "type": "work" },
"uri",
"http://www.viagenie.ca/simon.perreault/simon.asc"
],
["tz", {}, "utc-offset", "-05:00"],
["url", { "type": "home" }, "uri", "http://nomis80.org"]
]
]
]]></artwork></figure>
</section>
</section>
</section>
<section title='Change History (to be removed prior to publication as an RFC)'>
<t>
<cref>Remove this section prior to publishing</cref>
<list style="hanging">
<t hangText="draft-kewisch-vcard-in-json-01">
<list style="symbols">
<t>Added ABNF and improved references in date/time related sections</t>
<t>Changes to wording in "vCard Stream" section</t>
<t>Changes to wording about VALUE parameter when converting to vCard</t>
<t>Corrected missing "type" parameter and separator in example</t>
<t>Minor wording corrections</t>
</list>
</t>
<t hangText="draft-ietf-jcardcal-jcard-00">
<list style="symbols">
<t>
Pubication as a WG draft
</t>
</list>
</t>
<t hangText="draft-ietf-jcardcal-jcard-01">
<list style="symbols">
<t>
Changed grouping syntax to use new GROUP parameter and added respective IANA section
</t>
<t>
Added timestamp and date-and-or-time types instead of converting them from date/time/date-time
</t>
<t>
Added a further sentence on preprocessing and escaping to clarify that JSON escaping must be used.
</t>
<t>
Described how to handle structured text values and structured text components with multiple values.
</t>
<t>
Corrections and additions to the ABNF Section, adaptions to example
</t>
</list>
</t>
<t hangText="draft-ietf-jcardcal-jcard-02">
<list style="symbols">
<t>
Made more clear that complete representation is not mandatory
</t>
<t>
Added sheffer-running-code section
</t>
<t>
Changed handling of unknown property parameter types.
</t>
<t>
Minor corrections to sections regarding dates, fixing typos
</t>
</list>
</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 02:48:14 |