Internet DRAFT - draft-bhat-vcarddav-json
draft-bhat-vcarddav-json
Network Working Group R. Bhat
Internet-Draft P. Saint-Andre
Intended status: Standards Track Cisco Systems, Inc.
Expires: December 7, 2012 June 5, 2012
A JavaScript Object Notation (JSON) Representation for vCard
draft-bhat-vcarddav-json-00
Abstract
This document defines a representation of vCard data in JavaScript
Object Notation (JSON).
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 7, 2012.
Copyright Notice
Copyright (c) 2012 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Bhat & Saint-Andre Expires December 7, 2012 [Page 1]
Internet-Draft vCard in JSON June 2012
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Discussion Venue . . . . . . . . . . . . . . . . . . . . . . . 3
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
5. Design Considerations . . . . . . . . . . . . . . . . . . . . 5
6. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 7
7. Format Conversions . . . . . . . . . . . . . . . . . . . . . . 8
8. Schema definition . . . . . . . . . . . . . . . . . . . . . . 8
9. Security Considerations . . . . . . . . . . . . . . . . . . . 8
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9
12.1. Normative References . . . . . . . . . . . . . . . . . . 9
12.2. Informative References . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10
Bhat & Saint-Andre Expires December 7, 2012 [Page 2]
Internet-Draft vCard in JSON June 2012
1. Introduction
vCard [RFC6350] is a data format for representing and exchanging
information about individuals and other entities. It is a text-based
format (as opposed to a binary format). This document defines a
representation for vCard data in JavaScript Object Notation (JSON), a
lightweight, text-based, language-independent data interchange format
derived from the ECMAScript Programming Language Standard (see
[RFC4627]). As with the XML representation of vCard defined in
[RFC6351], the data structure is exactly the same as for plain vCard,
enabling a 1-to-1 mapping between the plain vCard format and the JSON
representation (or the XML representation). The JSON formatting
might be preferred in some contexts where JSON facilities are readily
available and can be reused instead of writing a standalone vCard
parser.
2. Discussion Venue
The preferred discussion venue for this document is the
vcarddav@ietf.org mailing list, for which subscription information
and archives can be found at
<https://www.ietf.org/mailman/listinfo/vcarddav>.
3. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[RFC2119].
4. Example
To ease comparison with both plain vCard and the XML representation,
the following example is a JSON representation of the same vCard (for
Simon Perreault) that is also shown in [RFC6350] and [RFC6351].
{
"version":"4.0",
"fn": "Simon Perreault",
"n": {
"surname": "Simon",
"given": "Perreault",
"suffix": [ "ing. jr", "M.Sc."]
},
"bday": { "date": "--0203" },
Bhat & Saint-Andre Expires December 7, 2012 [Page 3]
Internet-Draft vCard in JSON June 2012
"anniversary": { "date-time": "20090808T1430-0500" },
"gender": { "sex" : "M" },
"lang": [ {
"pref": 1,
"language-tag": "fr",
},
{
"pref": 2,
"language-tag": "en",
},
],
"org": {
"type": "work",
"text": "Viagenie"
},
"adr": {
"type": "work",
"label": "Simon Perreault
2875 boul. Laurier, suite D2-630
Quebec, QC, Canada G1V 2M2",
"street": "2875 boul. Laurier, suite D2-630",
"locality": "Quebec",
"region": "QC",
"code": "G1V 2M2",
"country": "CA"
},
"tel": [ {
"type": ["work", "voice"],
"uri": "tel:+1-418-656-9254;ext=102"
},
{
"type": ["work", "text", "voice", "cell", "video"],
"uri": "tel:+1-418-262-6501"
}
],
"email": {
"type": "work",
"text": "simon.perreault@viagenie.ca"
},
"geo": {
"type": "work",
"uri": "geo:46.766336,-71.28955"
},
"key": {
"type": "work",
"uri": "http://www.viagenie.ca/simon.perreault/simon.asc"
},
"tz": "America/Montreal",
Bhat & Saint-Andre Expires December 7, 2012 [Page 4]
Internet-Draft vCard in JSON June 2012
"url": {
"type": "home",
"uri": "http://nomis80.org"
}
}
Figure 1: JSON representation of RFC 6350 example
5. Design Considerations
The general idea is to map vCard parameters, properties and value
types to JSON property/value pairs. For example, the "FN" property
is mapped to the fn property. Value contains a text string that
corresponds to the vCard property's value. vCard parameters are also
mapped to JSON objects which are contained in the value object. For
example, the "TYPE" parameter applied to the "TEL" property would
look like the following in JSON.
"tel": {
"type": [ "voice", "video" ],
"uri": "tel:+1-555-555-555"
}
Figure 2: Mapping of a vCard parameter
Parameters taking a list of values and properties with cardinality of
more than one are converted to a JSON array object. Properties
having structured values (e.g., the "N" property) are expressed by
nested JSON object trees. Properties within that tree ("surname",
"given", etc.) are mapped as simple name/value pairs. These pairs
should follow the schema defined by the XML mapping of vCard(Appendix
A in [RFC6351]) Line folding is a non-issue in JSON. Therefore, the
mapping from vCard to JSON is done after the unfolding procedure is
carried out. Conversely, the mapping from JSON to vCard is done
before the folding procedure is carried out. The group construct
(Section 3.2 in [RFC6350]) is represented with the JSON object of the
same name. For example:
Bhat & Saint-Andre Expires December 7, 2012 [Page 5]
Internet-Draft vCard in JSON June 2012
{
"version" : "4.0"
"contact": {
"fn": "...",
"email": "..."
},
"media" : {
"photo": "..."
},
"categories": "..."
}
Figure 3: Mapping of lists and structured values
... is equivalent to:
BEGIN:VCARD
VERSION:4.0
contact.FN=...
contact.EMAIL=...
media.PHOTO=...
CATEGORIES=...
END:VCARD
Figure 4: Plain vCard equivalent
The VALUE parameter from the plain VCARD format is used as the
property name in the JSON format. If there is no VALUE parameter
specified, it is treated as equivalent to VALUE=text. For example:
{
"email": {
"type": "work",
"text": "simon.perreault@viagenie.ca"
},
"geo": {
"type": "work",
"uri": "geo:46.766336,-71.28955"
},
"bday": { "date": "--0203" },
}
Figure 5: Mapping of VALUE parameter
... is equivalent to:
Bhat & Saint-Andre Expires December 7, 2012 [Page 6]
Internet-Draft vCard in JSON June 2012
BEGIN:VCARD
VERSION:4.0
EMAIL;VALUE=text;type=work:simon.perreault@viagenie.ca
GEO;VALUE=uri;type=work:geo:46.766336,-71.28955
BDATE;VALUE=date:--0203
END:VCARD
Figure 6: Plain vCard equivalent
In the plain vCard format, the "VERSION" property was mandatory and
played a role in extensibility. In XML, this property was dropped in
favor of the XML namespace mechanism. In the JSON mapping, we keep
the "version" property, which plays a similar role as in the plain
vCard format.
Finally, there is no reason to include a top-level name of "vcard" or
"vcards", since the data type can be determined from the media type
of the data file.
6. Extensibility
The plain vCard format is extensible. New properties, parameters,
data types and values (collectively known as vCard elements, not to
be confused with XML elements) can be registered with IANA (see
[RFC6350], Section 10.2). It is expected that these vCard extensions
will also specify extensions to the JSON format described in this
document. New JSON vCard property and parameter element names MUST
be lower-case. This is necessary to ensure that round-tripping
between JSON and plain-text vCard works correctly. Unregistered
extensions (i.e., those starting with "X-" and "VND-...-") are
expressed in JSON by using properties starting with "x-" and
"vnd-...-". Refer to Section 7 for the implications when converting
between plain-text vCard and JSON. For example:
{
"x-my-prop": {
"pref": 1,
"text": "value goes here"
}
}
Figure 7: An example of extensibility
A vCard JSON parser MUST ignore JSON parameters and properties for
which it doesn't recognize the name.
In the XML representation of vCard [RFC6351], extensibility is
Bhat & Saint-Andre Expires December 7, 2012 [Page 7]
Internet-Draft vCard in JSON June 2012
handled in part by using XML namespaces [XML-NAMES] for properties
and parameters that have no equivalent in plain-text vCard. For
extensions that might appear in both the JSON representation and the
XML representation, it is RECOMMENDED to represent the JSON parameter
or property name in "Clark Notation" [CLARK] by preceding the name
itself with the Uniform Resource Identifier [RFC3986] of the XML
namespace, enclosed in curly brackets ('{' and '}'); thus the
"expanded name" will be of the form "{URI}name". For extensions that
will appear in the JSON representation but not the XML
representation, a mere (non-expanded) name can be used, or the name
can be an expanded name formed in another manner (e.g., using the
"reverse domain name" convention such as "com.example.vcard.foo").
The JSON format does not validate the cardinality of properties.
This is a limitation of the JSON format specification. Cardinalities
of the plain vCard format [RFC6350] MUST still be respected.
7. Format Conversions
To follow
8. Schema definition
To follow
9. Security Considerations
All the security considerations applicable to plain vCard [RFC6350]
are also applicable to the JSON representation of vCard.
As explained in [RFC4627], JSON is a subset of JavaScript, but it is
a safe subset that excludes assignment and invocation. A JSON text
can be safely passed into JavaScript's eval() function (which
compiles and executes a string) if all the characters not enclosed in
strings are in the set of characters that form JSON tokens.
10. IANA Considerations
To: ietf-types@iana.org
Subject: Registration of media type application/vcard+json
Bhat & Saint-Andre Expires December 7, 2012 [Page 8]
Internet-Draft vCard in JSON June 2012
Type name: application
Subtype name: vcard+json
Required parameters: (none)
Optional parameters: (none)
Encoding considerations: 8bit if UTF-8; binary if UTF-16 or UTF-32;
see RFC 4627.
Security considerations: All of the security considerations
specified in RFC 4627 and RFC 6350 apply.
Interoperability considerations: (none)
Specification: XXXX
Applications that use this media type: vCard processors.
Additional information:
Magic number(s): (none)
File extension(s): .jcard
Macintosh file type code(s): TEXT
Person and email address to contact for further information: vCard
discussion mailing list, <vcarddav@ietf.org>
Intended usage: COMMON
Restrictions on usage: (none)
Author: Peter Saint-Andre, <psaintan@cisco.com>
Change controller: Peter Saint-Andre, <psaintan@cisco.com>
11. Acknowledgements
Thanks to Joe Hildebrand for his feedback.
Some text in this document was borrowed from [RFC6351].
12. References
12.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC6350] Perreault, S., "vCard Format Specification", RFC 6350,
August 2011.
12.2. Informative References
[CLARK] Clark, J., "Clark Notation", February 1999,
<http://www.jclark.com/xml/xmlns.htm>.
Bhat & Saint-Andre Expires December 7, 2012 [Page 9]
Internet-Draft vCard in JSON June 2012
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005.
[RFC6351] Perreault, S., "xCard: vCard XML Representation",
RFC 6351, August 2011.
[XML-NAMES]
Thompson, H., Hollander, D., Layman, A., Bray, T., and R.
Tobin, "Namespaces in XML 1.0 (Third Edition)", World Wide
Web Consortium Recommendation REC-xml-names-20091208,
December 2009,
<http://www.w3.org/TR/2009/REC-xml-names-20091208>.
Authors' Addresses
Raghurama Bhat
Cisco Systems, Inc.
900 McCarthy Blvd.
Milpitas, CA 95035
USA
Phone: +1-408-902-2123
Email: ragbhat@cisco.com
Peter Saint-Andre
Cisco Systems, Inc.
1899 Wynkoop Street, Suite 600
Denver, CO 80202
USA
Phone: +1-303-308-3282
Email: psaintan@cisco.com
Bhat & Saint-Andre Expires December 7, 2012 [Page 10]
