One document matched: draft-kewisch-vcard-in-json-00.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'>
]>
<?rfc rfcedstyle="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<!-- default = 3 -->
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc strict="yes"?>
<!--<?rfc comments="yes"?> -->
<!--<?rfc inline="yes"?> -->
<rfc category='std' ipr='trust200902' docName='draft-kewisch-vcard-in-json-00'>
<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>
<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='draft-kewisch-et-al-icalendar-in-json'/>.
</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='draft-kewisch-et-al-icalendar-in-json'/> 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, with the exception of those which have default values.
</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'/>.
</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 complete representation, extended format of
<xref target="ISO.8601.2004"/>.
</t>
</section>
<section title="vCard Stream">
<t>
The vCard 4 standard doesn't define a stream of vcard elements. To
easier identify multiple jCard objects and provide compatibility to
jCal, multiple jCard objects MAY be streamed using 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 values of the
property. Properties have at least one value, so the array will have a minimum of
four elements, but there can be any number of additional
elements for multi-valued properties as described in
<xref target="multivalue"/>.
</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 an example, the table below shows vCard to jCard mappings for
current vCard properties. Any new vCard properties added in
the future will be converted in the same way.
</t>
<texttable>
<ttcol>Property</ttcol>
<ttcol>jCard Name</ttcol>
<ttcol>RFC6350 Section</ttcol>
<c>BEGIN</c>
<c>not mapped</c>
<c><xref target="RFC6350"/> # 6.1.1</c>
<c>END</c>
<c>not mapped</c>
<c><xref target="RFC6350"/> # 6.1.2</c>
<c>SOURCE</c>
<c>source</c>
<c><xref target="RFC6350"/> # 6.1.3</c>
<c>KIND</c>
<c>kind</c>
<c><xref target="RFC6350"/> # 6.1.4</c>
<c>XML</c>
<c>xml</c>
<c><xref target="RFC6350"/> # 6.1.5</c>
<c>FN</c>
<c>fn</c>
<c><xref target="RFC6350"/> # 6.2.1</c>
<c>N</c>
<c>n</c>
<c><xref target="RFC6350"/> # 6.2.2</c>
<c>NICKNAME</c>
<c>nickname</c>
<c><xref target="RFC6350"/> # 6.2.3</c>
<c>PHOTO</c>
<c>photo</c>
<c><xref target="RFC6350"/> # 6.2.4</c>
<c>BDAY</c>
<c>bday</c>
<c><xref target="RFC6350"/> # 6.2.5</c>
<c>ANNIVERSARY</c>
<c>anniversary</c>
<c><xref target="RFC6350"/> # 6.2.6</c>
<c>GENDER</c>
<c>gender</c>
<c><xref target="RFC6350"/> # 6.2.7</c>
<c>ADR</c>
<c>adr</c>
<c><xref target="RFC6350"/> # 6.3.1</c>
<c>TEL</c>
<c>tel</c>
<c><xref target="RFC6350"/> # 6.4.1</c>
<c>EMAIL</c>
<c>email</c>
<c><xref target="RFC6350"/> # 6.4.2</c>
<c>IMPP</c>
<c>impp</c>
<c><xref target="RFC6350"/> # 6.4.3</c>
<c>LANG</c>
<c>lang</c>
<c><xref target="RFC6350"/> # 6.4.4</c>
<c>TZ</c>
<c>tz</c>
<c><xref target="RFC6350"/> # 6.5.1</c>
<c>GEO</c>
<c>geo</c>
<c><xref target="RFC6350"/> # 6.5.2</c>
<c>TITLE</c>
<c>title</c>
<c><xref target="RFC6350"/> # 6.6.1</c>
<c>ROLE</c>
<c>role</c>
<c><xref target="RFC6350"/> # 6.6.2</c>
<c>LOGO</c>
<c>logo</c>
<c><xref target="RFC6350"/> # 6.6.3</c>
<c>ORG</c>
<c>org</c>
<c><xref target="RFC6350"/> # 6.6.4</c>
<c>MEMBER</c>
<c>member</c>
<c><xref target="RFC6350"/> # 6.6.5</c>
<c>RELATED</c>
<c>related</c>
<c><xref target="RFC6350"/> # 6.6.6</c>
<c>CATEGORIES</c>
<c>categories</c>
<c><xref target="RFC6350"/> # 6.7.1</c>
<c>NOTE</c>
<c>note</c>
<c><xref target="RFC6350"/> # 6.7.2</c>
<c>PRODID</c>
<c>prodid</c>
<c><xref target="RFC6350"/> # 6.7.3</c>
<c>REV</c>
<c>rev</c>
<c><xref target="RFC6350"/> # 6.7.4</c>
<c>SOUND</c>
<c>sound</c>
<c><xref target="RFC6350"/> # 6.7.5</c>
<c>UID</c>
<c>uid</c>
<c><xref target="RFC6350"/> # 6.7.6</c>
<c>CLIENTPIDMAP</c>
<c>clientpidmap</c>
<c><xref target="RFC6350"/> # 6.7.7</c>
<c>URL</c>
<c>url</c>
<c><xref target="RFC6350"/> # 6.7.8</c>
<c>VERSION</c>
<c>version</c>
<c><xref target="RFC6350"/> # 6.7.9</c>
<c>KEY</c>
<c>key</c>
<c><xref target="RFC6350"/> # 6.8.1</c>
<c>FBURL</c>
<c>fburl</c>
<c><xref target="RFC6350"/> # 6.9.1</c>
<c>CALADRURI</c>
<c>caladruri</c>
<c><xref target="RFC6350"/> # 6.9.2</c>
<c>CALURI</c>
<c>caluri</c>
<c><xref target="RFC6350"/> # 6.9.3</c>
</texttable>
<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>
The following vCard properties can have values that consist
of a list of "standard" vCard values separated by a specific
delimiter. In jCard these properties are added as further members
of the array describing the property.
</t>
<texttable>
<ttcol>Property</ttcol>
<ttcol>jCard Name</ttcol>
<ttcol>RFC6350 Section</ttcol>
<c>NICKNAME</c>
<c>nickname</c>
<c><xref target="RFC6350"/> # 6.2.3</c>
<c>CATEGORIES</c>
<c>categories</c>
<c><xref target="RFC6350"/> # 6.7.1</c>
</texttable>
<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, each
grouped property appears as a separate property containing the group
name and property name, separated by a "." character. This was done
to maintain compatibilty of array elements with
<xref target='draft-kewisch-et-al-icalendar-in-json'/>.
</t>
<t>
<figure>
<preamble>Example:</preamble>
<artwork><![CDATA[
["vcard",
[
["groupname.email", {}, "text", "johndoe@example.org"],
...
],
...
]
]]></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.
</t>
<t>
<figure>
<preamble>Example:</preamble>
<artwork><![CDATA[
["vcard",
[
["role", { "lang": "tr" }, "text", "roca"],
...
],
...
]
]]></artwork></figure>
</t>
<t>
As an example, the table below shows vCard to jCard mappings for
current vCard parameters. Any new vCard parameters added in
the future will be converted in the same way.
</t>
<texttable>
<ttcol>Parameter</ttcol>
<ttcol>jCard Name</ttcol>
<ttcol>RFC6350 Section</ttcol>
<c>LANGUAGE</c>
<c>language</c>
<c><xref target="RFC6350"/> # 5.1</c>
<c>VALUE</c>
<c>not mapped</c>
<c><xref target="RFC6350"/> # 5.2</c>
<c>PREF</c>
<c>pref</c>
<c><xref target="RFC6350"/> # 5.3</c>
<c>ALTID</c>
<c>altid</c>
<c><xref target="RFC6350"/> # 5.4</c>
<c>PID</c>
<c>pid</c>
<c><xref target="RFC6350"/> # 5.5</c>
<c>TYPE</c>
<c>type</c>
<c><xref target="RFC6350"/> # 5.6</c>
<c>MEDIATYPE</c>
<c>mediatype</c>
<c><xref target="RFC6350"/> # 5.7</c>
<c>CALSCALE</c>
<c>calscale</c>
<c><xref target="RFC6350"/> # 5.8</c>
<c>SORT-AS</c>
<c>sort-as</c>
<c><xref target="RFC6350"/> # 5.9</c>
<c>GEO</c>
<c>geo</c>
<c><xref target="RFC6350"/> # 5.10</c>
<c>TZ</c>
<c>tz</c>
<c><xref target="RFC6350"/> # 5.11</c>
</texttable>
<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 the default value
type for that property.
</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.
</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>
<t>
As an example, the table below shows a list of vCard parameters
where COMMA-separated values are used. Any new vCard parameters
added in the future will be handled in the same way.
</t>
<texttable>
<ttcol>Parameter</ttcol>
<ttcol>RFC6350 Section</ttcol>
<c>PID</c>
<c><xref target="RFC6350"/> # 5.5</c>
<c>TYPE</c>
<c><xref target="RFC6350"/> # 5.6</c>
<c>SORT-AS</c>
<c><xref target="RFC6350"/> # 5.9</c>
</texttable>
</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.
</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 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 formatted using the
<xref target="ISO.8601.2004"/> complete representation, extended
format. The textual format specifies a four-digit year, two-digit
month, and two-digit day of the month, separated by the "-"
character.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["bday", {}, "date", "1970-01-01"],
...
]]></artwork></figure></t>
</list></t>
</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 formatted using the
<xref target="ISO.8601.2004"/> complete representation, extended
format. The textual format specifies a two-digit, 24-hour of the
day (i.e., values 00-23), two-digit minute in the hour (i.e.,
values 00-59), and two-digit seconds in the minute (i.e., values
00-60). The seconds value of 60 MUST only be used to account for
positive "leap" seconds. Fractions of a second are not supported
by this format. Contrary to
<xref target="draft-kewisch-et-al-icalendar-in-json"/>, UTC
offsets are permitted within a time value.
</t>
<t hangText="Example:"><figure><artwork><![CDATA[
...
["x-time-local", {}, "time", "12:30:00"],
["x-time-utc", {}, "time", "12:30:00Z"],
["x-time-offset", "time", "12:30:00-0800"],
...
]]></artwork></figure></t>
</list></t>
</section>
<section 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
formatted using the <xref target="ISO.8601.2004"/> complete
representation, extended format. The same restrictions with
respect to leap seconds, fractions of a second and UTC offsets as
in <xref target="proptype-time"/> apply.
</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+0100"],
...
]]></artwork></figure></t>
</list></t>
</section>
<section title="Date and/or Time (RFC6350 section 4.3.4)">
<t><list style="hanging">
<t hangText="Description:">
jCard has no direct equivalent to vCard's "DATE-AND-OR-TIME"
property value data type. Instead, the specified date, date-time
or time format MUST be detected and the property MUST be
represented by a property with the detected type identifier.
See <xref target="convert-datetime"/> for more information on
how conversion between jCard and vCard should be handled.
</t>
</list></t>
</section>
<section title="Timestamp (RFC6350 section 4.3.5)">
<t><list style="hanging">
<t hangText="Description:">
jCard has no direct equivalent to vCard's "TIMESTAMP"
property value data type. Instead, the specified complete date and
time of day combination MUST be represented by a property with the
"date-time" identifier.
See <xref target="convert-datetime"/> for more information on
how conversion between jCard and vCard should be handled.
</t>
</list></t>
</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>
jCard properties that do not specify the default type for the vCard
property MUST add a VALUE parameter when converting to vCard. jCard
properties that specify the default type SHOULD NOT add a VALUE
parameter.
</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-or-date-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. As a result, the following rules are applied when dealing
with unrecognized properties and property parameters:
<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
string object. The content of that string is the unprocessed
value text.
</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>
</list>
</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", {}, "text", "mailto:abuse@example.org"],
...
]]></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="Conversion of Date and Time Related Data Types" anchor="convert-datetime">
<t>
<xref target='RFC6350'/> defines the data types DATE, DATE-TIME, TIME,
DATE-AND-OR-TIME and TIMESTAMP, covering various aspects of dates and
times. As jCard is more "strongly typed", some of these types have been
consolidated. This section aims to aid conversion between jCard and
vCard and vice versa.
</t>
<t>
Regardless of the date/time related property converted, jCard and vCard
use different representations of the <xref target="ISO.8601.2004"/>
format. The date format MUST be adjusted during conversion.
</t>
<section title="Conversion from jCard to vCard">
<t>
<list style="symbols">
<t>
If the property type of the jCard property matches the property's
default type, the VALUE parameter MUST NOT be added to the vCard
property.
</t>
<t>
For property types "date-and-or-time" or "timestamp", the property
value MUST be converted to a permitted date and/or time format as
specified in <xref target='RFC6350'/> Section 4.3.4 and 4.3.5 and
the VALUE parameter MUST NOT be added to the vCard property. If a
permitted conversion cannot be done, the VALUE parameter must be
added with the closest available date/time format identifier.
</t>
<t>
If the default type is unknown or the jCal property type does not
match the default type, the VALUE parameter MUST be specified.
</t>
</list>
</t>
</section>
<section title="Conversion from vCard to jCard">
<t>
<list style="symbols">
<t>
If the parser knows the default type of the property and it is one
of "DATE", "DATE-TIME" or "TIME", the properties can be directly
converted following the guidelines of the respective format type in
this document.
</t>
<t>
For the property type "date-and-or-time", the parser SHOULD detect
if it is handling either a date, a time, or a date-time and use the
respective format identifier in jCard.
</t>
<t>
For the property type "timestamp", the parser MUST use the format
type identifier "date-time" in the jCard property.
</t>
<t>
If the (default) property type is unknown, the property value MUST
be treated as opaque text and the "text" format type identifier MUST
be used.
</t>
</list>
</t>
</section>
</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>
<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;
<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>
<reference anchor="draft-kewisch-et-al-icalendar-in-json">
<front>
<title>
jCal: The JSON format for iCalendar
</title>
<author initials="P." surname="Kewisch" fullname="Philipp Kewisch">
<organization abbrev="Mozilla">Mozilla Corporation</organization>
</author>
<author initials="C." surname="Daboo" fullname="Cyrus Daboo">
<organization abbrev="Apple, Inc.">Apple Inc.</organization>
</author>
<author initials="M." surname="Douglass" fullname="Mike Douglass">
<organization abbrev="RPI">Rensselaer Polytechnic Institute</organization>
</author>
<date/>
</front>
<seriesInfo name="draft" value="draft-kewisch-et-al-icalendar-in-json-02"/>
</reference>
</references>
<references title="Informative References">
&rfc4627;
<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>
</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 = string / number / boolean
; 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
; 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", "-02-03"],
["anniversary", {}, "date-time", "2009-08-08T14:30:00-0500"],
["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", {}, "uri", "http://nomis80.org"]
]
]
]]></artwork></figure>
</section>
</section>
</section>
<section title='Open Issues (to be removed prior to publication as an RFC)'>
<t>
<list style="symbols">
<t>
<xref target='RFC6350'/> doesn't define any kind of stream for
multiple vcard elements. For similarity with the jCal draft, I have
added a "vcardstream". Is this wanted and does the name fit? (Maybe
rather "jcardstream" ?)
</t>
<t>
During conversion to jCard, I have dropped "date-and-or-time" and
"timestamp" formats, since they can equally be represented by the
formats "date", "time" and "date-time". I have added guidelines to
<xref target="convert-datetime"/>, but there may be some situations
I am unaware of that make dropping these formats impossible.
</t>
<t>
<xref target="draft-kewisch-et-al-icalendar-in-json"/> and
<xref target='RFC5545'/> define the concept of sub-components. vCard
on the other hand merely mentions the "BEGIN" and "END" properties,
which have only one possible value "VCARD". Should any preparations
be done, in case an extension defines other possible values for the
"BEGIN" and "END" properties, or should an extension to this
document be defined when a such vCard extension emerges?
</t>
<t>
I am not clear on support for using 60 as a value for seconds (i.e.
leap seconds) in vCard. This is defined quite clearly in
<xref target='RFC5545'/>. Please double check this.
</t>
<t>
This document needs some mention of the truncated date format. As I
don't have access to the original ISO 8601 documents, I would
appreciate some advice on how to best handle this.
</t>
<t>
This first draft doesn't yet incorporate all proposed changes
discussed on the vcarddav and calsify mailing lists after publishing
of draft-kewisch-et-al-icalendar-in-json-01. Most notably,
conversion of structured values into arrays or objects. This will be
done in an upcoming draft and when an agreement is reached.
</t>
<t>
This document defines in <xref target="grouping"/>, that grouped
properties are not to be handled differently than normal properties.
This was done for compatibility with the jCal draft to make it
easier for a parser to support both jCal and jCard.
Another option would be to add a pseudo-property with the special
type "group", the property name being the group name and the
property value being an array of properties. Downside is that there
is room for an extra set of parameters in the group container that
does not serialize back to vCard.
</t>
<t>
There is some open discussion on the vcarddav and calsify lists
about structured property and parameter values. The origin of this
format comes from jCal, where structured values are very rare and
processing the remaining ones requires a processing library anyway.
Therefore neither structured property values nor parameter values
were added. For jCard on the other hand, structured values appear
quite often. I have come up with three possible options for
structured property values:
<list style="numbers">
<t>
Use an array as the value, possibly with a null value for any
empty structured property: foo;;bar becomes ["foo", null,
"bar"]
</t>
<t>
Use an object for key-value combinations. Downside is that the
key may not always be known, and needs to be defined at least
for standard properties. (i.e for N: "surnames", "given",
"additional", "honor-prefix", "honor-suffix"). Object values
themselves could also be array values, i.e multiple honorific
prefixes. Upside is that it makes it very easy to access the
values even without using a dedicated client library.
</t>
<t>
Keep the property value as an opaque text and leave any
splitting to client libraries. This makes it very simple to
parse both iCalendar and vCard data into a similar format, but
puts the burden of parsing the structured value on the client or
client library.
</t>
</list>
Also, there should be a mention of how multi-values inside a
structured value should be handled. With the second approach, these
could themselves be an array, similar to how this document currently
defines multi-value parameters.
</t>
</list>
</t>
</section>
<section title='Change History (to be removed prior to publication as an RFC)'>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 03:16:26 |