Subject: [VCARDDAV] Comments and Comparison between vcarddav-json and the icalendar-in-json

From: Philipp Kewisch <[email-masked]>
Date: Mon, 19 Nov 2012 12:09:25 +0100

TL;DR; I've summarzied differences between jCal and the vcarddav spec 
here. There are some issues with data type consistency, the use of 
objects vs arrays and extensibility. Read the bold headlines.

Hello Raghurama and Peter,

I have also read through the draft (I hope I found the latest version, I 
got it from here: <https://github.com/stpeter/json-vcard>) and have some 
comments. Most of these comments are summarized comparison to the jCal 
draft we have recently put up at: 
<http://tools.ietf.org/html/draft-kewisch-et-al-icalendar-in-json-00>. 
Due to the similarity between iCalendar and vCard, I think it is of the 
essence that the JSON representations also match. This would allow 
client libraries to easily parse both iCalendar and vCards without a 
substantially different parser. While this might make some constructs 
like vcard grouping a bit less easy to access without a client library, 
I think this would nevertheless benefit both formats.

Peter, since you mentioned you won't be able to bring this forward 
within the next few weeks, I am happy to drive the vcard in json spec 
forward. I'd be delighted if you could take a moment to at least read 
and reply to this email, I've done my best to summarize the differences. 
Afterwards, I am willing to summarize the general discussion and put 
together a new draft with the results.

*1. Position of the Value Type:*

    There is some trouble with using the type name as the key. A client
    library will have to go through the keys of the object to detect the
    value type. Consider this example:

        X-THING;VALUE=FLOAT:123.456
        vcarddav-json representation: { "x-thing": { "float": 123.456 }}
        jCal representation: ["x-thing", {}, "float", 123.456]

    With the vcarddav-json representation, client code will have to do
    something like this and it must know all valid property types:

        for (var key in xthing) { if (key in validTypes) { type = key;
        value = xthing[key]; break; } }

    While with the jCal format the type is explicitly mentioned. Another
    issue here might be extensibility. What happens if an extension
    draft specifies a new value type that is the same as a parameter, or
    vice versa?

        X-THING;VALUE=URI;URI="urn:foo":urn:bar
        vcarddav-json: { "x-thing": { "uri": ??? }}
        jCal: ["x-thing", { "uri": "urn:foo" }, "uri", "urn:bar"]

*2. Multiple Properties of the same Name*

    jCal: multiple property entries in an array:

        [
        ["tel", { "type": ["work", "voice"] }, "uri",
        "tel:+1-418-656-9254;ext=102"],
        ["tel", { "type": ["work", "text", "voice", "cell", "video"] },
        "uri", "tel:+1-418-262-6501"],
        ]

    vcarddav-json: Use an array with multiple objects

        "tel": [
        { "type": ["work", "voice"], "uri": "tel:+1-418-656-9254;ext=102" },
            { "type": ["work", "text", "voice", "cell", "video"], "uri":
        "tel:+1-418-262-6501" }
        ],

    We also considered using the method provided in vcarddav-json to
    represent properties with multiple values but in the end we decided
    against it. Most importantly, we wanted to provide consistency for
    data types. If a value can be either a string or an array, then
    client libraries will always have to check if (typeof val ==
    "string") before handling it. Note there is an open issue on
    multi-value parameters, see below.

*3. Multi-Valued Parameters and Parameter Data Types.*

    One issue in jCal was how to handle parameters that (can) have
    multiple values, like for example DELGATED-TO. This has been left as
    an open issue in the draft, we haven't come to a consensus here. I'm
    happy to bring this up in the vcard space since multi-value
    parameters are used much more often in this space. The proposals are
    to either leave it raw (not so good for vcard), use array of string
    (breaking the consistency we aimed for) or always using an array
    (which might be a performance decrease while parsing). Maybe this
    should be discussed in a thread separate from this one since its a
    larger issue, please read our draft for details.

    Another issue related to this is what primitive type should be used
    for parameter values. In iCalendar, aside from the open issue
    mentioned, we decided it would be best to keep the parameter value a
    string value, even if its a known parameter like RSVP. As the type
    for a parameter is not explicitly mentioned like it is for iCalendar
    properties themselves, we aim for data consistency so that its clear
    to the parser how to handle unknown parameters. If an extension to
    the iCalendar specification defines the default type for a new
    parameter to be a number and the server's parser can not yet handle
    this new parameter, it would default to using a string. A client
    that may already know of this new parameter might expect it to be a
    number and run into Javascript errors when handling the value.

*3. Top Level vcalendar/vcard Objects*

    vcarddav-json doesn't define a top level object and I understand the
    reasons why. For compatibility with the jCal format, this would be
    required though. jCal also defines a parent "icalendar" object, but
    only requires using it when grouping multiple VCALENDAR objects.

*4. Extensibility*

    One of the key design considerations we aimed for with jCal is
    "Ability to handle many extensions to the underlying iCalendar
    specification without requiring an update to this document".
    vcarddav-json on the other hand expects extensions to also provide
    extensions to the JSON format. I fear this might cause some
    divergence between extension properties supported if the extension
    doesn't do a specific definition for vcarddav-json.

Thats all for now. Although our formats are very different I think our 
intentions are not that far apart. Thanks for reading until the end and 
I am eager to hear your comments.

Philipp Kewisch