Subject: [VCARDDAV] New Internet-Draft: jCard: The JSON format for vCard

From: Philipp Kewisch <[email-masked]>
Date: Wed, 13 Feb 2013 21:52:04 +0100

Hello apps-discuss,

as you might know, the calconnect group has been working on a draft for 
a JSON based data format for iCalendar, which you can find here [1]. 
This draft comes with a fully functional javascript parser/converter 
that you can find at [2]. The library can also process recurrence data 
and timezone conversion and is being used in the latest version of 
Firefox OS and is also targeted at the Lightning extension to Thunderbird.

The data format we chose has gone through various iterations. Although 
it may not be the common object-as-root type JSON, I think its suited 
best for its task: bidirectional, semantically lossless conversion 
between iCalendar and JSON. It has been discussed on the vcarddav and 
calsify lists.

Consequently, I have created a draft for vCard in JSON using a similar 
notation [3]. There are of course some slight differences between vCard 
and iCalendar causing some open issues ready for discussion in a WG. You 
can find them at the end of the draft, any input is appreciated. For 
additional reading, check out some related discussion on the calsify [4] 
and vcarddav [5] lists. I have not yet adapted my ical.js parser to also 
read data as in this draft, but the changes are so minimal that it 
should not be a big deal.

I'll be happy to take part in any WG calls or discussion related to 
moving vCard in JSON forward, so let me know what you think.

Philipp

[1] http://www.ietf.org/id/draft-kewisch-et-al-icalendar-in-json-01.txt
[2] https://github.com/kewisch/ical.js/
[3] http://www.ietf.org/id/draft-kewisch-vcard-in-json-00.txt
[4] http://www.ietf.org/mail-archive/web/calsify/current/maillist.html
[5] http://www.ietf.org/mail-archive/web/vcarddav/current/maillist.html

-------- Original Message --------
Subject: 	New Version Notification for draft-kewisch-vcard-in-json-00.txt
Date: 	Wed, 13 Feb 2013 12:03:24 -0800
From: 	[email-masked]
To: 	[email-masked]

A new version of I-D, draft-kewisch-vcard-in-json-00.txt
has been successfully submitted by Philipp Kewisch and posted to the
IETF repository.

Filename:	 draft-kewisch-vcard-in-json
Revision:	 00
Title:		 jCard: The JSON format for vCard
Creation date:	 2013-02-13
Group:		 Individual Submission
Number of pages: 25
URL:             http://www.ietf.org/internet-drafts/draft-kewisch-vcard-in-json-00.txt
Status:          http://datatracker.ietf.org/doc/draft-kewisch-vcard-in-json
Htmlized:        http://tools.ietf.org/html/draft-kewisch-vcard-in-json-00

Abstract:
    This specification defines "jCard", a JSON format for vCard data.

The IETF Secretariat

---

From: Simon Perreault <[email-masked]>
Date: Wed, 13 Feb 2013 22:35:24 +0100

Le 2013-02-13 21:52, Philipp Kewisch a écrit :
> I have created a draft for vCard in JSON

Cool! Here's some quick initial feedback. I'll reply only on vcarddav 
since that's where the actual WG work will happen I suppose.

3.2. vCard Stream

    The vCard 4 standard doesn't define a stream of vcard elements.

--> What's a stream? I think I can infer it from the context, but please 
make it explicit.

On page 7, I think the table might actually be creating confusion in the 
future. Two issues:
- It creates the impression that mapping names is not simply 
lower/uppercasing.
- The actual set of properties is a dynamic thing, managed by IANA.
I say just remove the table, the description is good as is.

3.3.1.1. Multi-valued Properties

    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.

               +------------+------------+-------------------+
               | Property   | jCard Name | RFC6350 Section   |
               +------------+------------+-------------------+
               | NICKNAME   | nickname   | [RFC6350] # 6.2.3 |
               | CATEGORIES | categories | [RFC6350] # 6.7.1 |
               +------------+------------+-------------------+

--> Again, this table might create confusion. This is not the definitive 
set of multi-valued properties. That set is dynamic, managed by IANA. 
Please instead just refer to multi-valued properties in general, give 
one or two examples, but do not include a definitive set of such 
properties. You could even refer to IANA if you wish. Same with the 
tables in sections 3.4 and 3.4.2.

3.3.1.2. Grouping of Properties

    [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
    [draft-kewisch-et-al-icalendar-in-json].

    Example:

    ["vcard",
      [
        ["groupname.email", {}, "text", "[email-masked]"],
        ...
      ],
      ...
    ]

--> I hate this. It's going to get badly implemented 9 times out of 10. 
When people write code to find all instances of the "email" property, 
they won't bother to remove the group prefix. The alternative would be 
to make the group a separate array parameter and set it to the empty 
string most of the time. That's super ugly, but at least it will get 
implemented correctly. *sigh* I hate vCard groups.

3.5.3. Date (RFC6350 section 4.3.1)

    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 [RFC6350], but
       formatted using the [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.

--> Why? Also, IIRC some things in basic format don't have an equivalent 
in extended format. Don't remember exactly what. I'll have to re-read 
ISO8601 *again*!

    o  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 [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.

--> Looks like this breaks round-tripping for properties with unknown 
default type.

3.5.11. UTC Offset (RFC6350 section 4.7)

    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 [RFC6350], with the exception that the hour and minute
       components are separated by a ":" character, for consistency with
       the [ISO.8601.2004] timezone offset, extended format.

--> Why? This looks more frivolous than for the other types.

    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.

--> This is good, but I'd phrase it differently: "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."

--> In Annex B, this:

    URL;TYPE=home:http://nomis80.org

was changed into this:

        ["url", {}, "uri", "http://nomis80.org"]

The type parameter is missing.

That's it for now. I'll have to review the conversion sections in more 
detail.

Thanks a lot for writing this!

Simon
-- 
DTN made easy, lean, and smart --> http://postellation.viagenie.ca
NAT64/DNS64 open-source        --> http://ecdysis.viagenie.ca
STUN/TURN server               --> http://numb.viagenie.ca

---

From: Philipp Kewisch <[email-masked]>
Date: Thu, 14 Feb 2013 00:22:30 +0100

On 2/13/13 10:35 PM, Simon Perreault wrote:
> --> What's a stream? I think I can infer it from the context, but 
> please make it explicit.
How is this?
           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.

> On page 7, I think the table might actually be creating confusion in 
> the future. Two issues:
If we do this here, I'm going to do the same in the jCal draft. I 
thought I added a note in most places that the table contains just the 
set of properties currently defined by the core rfc and that extensions 
may add more. The next point you write about proves I didn't add that 
note everywhere.

> --> Again, this table might create confusion. This is not the 
> definitive set of multi-valued properties. That set is dynamic, 
> managed by IANA. Please instead just refer to multi-valued properties 
> in general, give one or two examples, but do not include a definitive 
> set of such properties. You could even refer to IANA if you wish. Same 
> with the tables in sections 3.4 and 3.4.2.
Especially when there is just a small list of properties like here, I do 
think there should be a table. Would you be fine with making it clearer, 
that these are just those currently defined by RFC6350 and that 
extensions may add any amount of additional properties? I think this is 
mentioned in an extra section, but a reference to that section or a 
similar note will probably make it clearer.

> --> I hate this. It's going to get badly implemented 9 times out of 
> 10. When people write code to find all instances of the "email" 
> property, they won't bother to remove the group prefix. The 
> alternative would be to make the group a separate array parameter and 
> set it to the empty string most of the time. That's super ugly, but at 
> least it will get implemented correctly. *sigh* I hate vCard groups.
I don't want to bend over backwards for groups. There is no equivalent 
for groups in jCal, so adding a further array member lets the two 
formats diverge. If you want something different, see the open issues 
section and also 
<http://www.ietf.org/mail-archive/web/vcarddav/current/msg02698.html> 
where I proposed an alternative syntax for groups. This doesn't stop 
people from doing it wrong, but at least it groups the group properties 
together.

Another approach that just came to mind, to translate the group name to 
a parameter. Downside is that its semantically different and may collide 
with an extension that defines a paramter of the same name, but it does 
make it harder to forget grouped parameters when enumerating all 
properties with a specific name.

> --> Why? Also, IIRC some things in basic format don't have an 
> equivalent in extended format. Don't remember exactly what. I'll have 
> to re-read ISO8601 *again*!
We have found that the extended format is much more common in web 
applications and APIs. Since JSON is mostly targeted at the web, we 
decided it makes sense to use it here. This works out nicely in 
iCalendar/jCal, because the only allowed formats are date, date-time and 
time and reduced accuracy is not permitted. I did leave this as an open 
issue though, especially since I am not sure omitting years or other 
parts of a date are allowed in the extended format.

The only thing that is important for me here is that a common format is 
used for jCal and jCard. Since we are already actively using the jCal 
draft in Firefox OS I would of course also like to avoid date format 
changes, but if in doubt, integrity of the data format is a priority.

> --> Looks like this breaks round-tripping for properties with unknown 
I think we should be good here. This point is specifically for known 
(default) property types "date-and-or-time" and "timestamp".  Maybe this 
needs better wording, but what I had in mind is if you have a jCard 
property ["foo", {}, "date-time", "2012-01-01T01:02:03Z"] and you know 
the default type for foo is "timestamp", then it should be converted as 
such. If you have ["bar", {}, "time", "01:02:03"] and you know the 
default type for bar is "timestamp", then conversion cannot be done and 
the VALUE parameter must be specified. I think all other cases are 
covered by the fact that "date", "date-time", and "time" all map 1:1 
into "date-and-or-time".

Properties with unknown default types are covered by the next bullet item:

If the default type is unknown or the jCal property type does not match the default type, the VALUE parameter MUST be specified.

> --> Why? This looks more frivolous than for the other types.
Using a such UTC Offset is consistent with other date-like data types 
using the extended format. This should of course also be changed if we 
should agree on a different date format, but for similar reasons I'd 
love to keep it.

>    jCard properties that do not specify the default type for the vCard ...
>
ok, changed locally.
> The type parameter is missing.
Good catch, changed that locally!

> Thanks a lot for writing this!
My pleasure! Looking forward to your feedback on the conversion section.

Philipp

---

From: Simon Perreault <[email-masked]>
Date: Thu, 14 Feb 2013 09:46:56 +0100

>            represented as described in this document.

So it's "just" an array of vCards. Hmm...

In my mind, the "stream" word refers to the *action* of streaming, for 
example a process that receives streaming data and processes it as it 
receives it (as opposed to a non-streaming process which would just 
process the whole data when it has received it completely).

Anyhow, I don't object, I just want to mention that I find the term a 
little bit odd.

> may add more. The next point you write about proves I didn't add that

I think a note is not sufficient. And what's the usefulness of having 
that (incomplete) table in there? Just give one or two examples.

> similar note will probably make it clearer.

No, I don't think it's sufficient. It's a trap for implementers. They 
will think it's a complete list *unless* they read the fine print. We 
can avoid that by just enunciating the algorithm and giving one or two 
examples.

> properties with a specific name.

Another idea: define the GROUP parameter. Register it from IANA in your 
draft. Make it so that these mean the same thing in vCard:

FOO.BAR:baz

BAR;GROUP=FOO:baz

Then in jCard, write it like this:

[ "bar", { "group": "foo" }, "text", "baz" ]

When converting from jCard to vCard, always use the FOO.BAR:baz syntax.

> parts of a date are allowed in the extended format.

Right. I'll get back to you on that. I'm pretty sure we chose to go with 
basic exactly for this kind of reason.

> changes, but if in doubt, integrity of the data format is a priority.

Makes sense.

> If the default type is unknown or the jCal property type does not match the default type, the VALUE parameter MUST be specified.

Exactly, it breaks round-tripping. Example:

X-UNKNOWN;VALUE=timestamp:20120101T010203Z

becomes:

[ "x-unknown", {}, "date-time", "2012-01-01T01:02:03Z" ]

---

From: Simon Perreault <[email-masked]>
Date: Thu, 14 Feb 2013 09:49:10 +0100

aarrrgh, hit ctrl+enter by mistake... Here's the finished mail.

==============

FOO.BAR:baz

BAR;GROUP=FOO:baz

Makes sense.

becomes:

becomes:

X-UNKNOWN;VALUE=date-time:20120101T010203Z

> should agree on a different date format, but for similar reasons I'd

ok.

Thanks,
Simon

---

From: Simon Perreault <[email-masked]>
Date: Thu, 14 Feb 2013 11:46:01 +0100

Le 2013-02-14 11:23, Philipp Kewisch a écrit :
> On 2/14/13 9:49 AM, Simon Perreault wrote:
> The term comes from rfc5545, Section 3:
>
>     The following sections define the details of a Calendaring and
>     Scheduling Core Object Specification.  The Calendaring and Scheduling
>     Core Object is a collection of calendaring and scheduling
>     information.  Typically, this information will consist of an
>     iCalendar stream with one or more iCalendar objects.  The body of the
>     iCalendar object consists of a sequence of calendar properties and
>     one or more calendar components.

Ah, got it. What they call a "stream", we call a "text/vcard MIME 
content type". We also have this curious ABNF:

    vcard-entity = 1*vcard

:)

>> Another idea: define the GROUP parameter. Register it from IANA in
>> your draft. Make it so that these mean the same thing in vCard:
>>
>> FOO.BAR:baz
>> BAR;GROUP=FOO:baz
> This would definitely aid jCard, but I fear it might cause trouble for
> vCard. From what I hear, vCard has a history of being mis-implemented
> and full of vendor extensions. If we do this, some vendors might use
> FOO.BAR:baz and others might use BAR;GROUP=FOO:baz and not bother to
> make the two interoperable. Existing implementations that rely on
> grouping will not understand the new format.

That's why I suggest to specify that a jCard-->vCard converter always 
use FOO.BAR:baz syntax.

An alternative idea: register the GROUP parameter from IANA, but do not 
define it. Only use it in jCard. All other formats cannot use it. You're 
just reserving the name from IANA to ensure there is never any conflict.

> I personally would have preferred if the grouping in the vcard spec
> would have been done as a parameter like this though. Maybe something to
> consider for vCard 5 :)

Definitely!

>>> If the default type is unknown or the jCal property type does not
>>> match the default type, the VALUE parameter MUST be specified.
> Ah I see, very unfortunate. I am not quite happy with the alternatives
> though:
>
> This means we at least need to add "timestamp". What about
> date-and-or-time? Theoretically you have the same issue:
>
> X-UNKNOWN;VALUE=date-and-or-time:20120101
> ["x-unknown", {}, "date", "2012-01-01"]
> X-UNKNOWN;VALUE=date:20120101
>
> But since its a date anyway, is it really losing semantics? Its not
> wrong to say that this specific property instance is a "date" value. If
> the value changes, then the VALUE parameter needs to change if its no
> longer a date. The vcard processing code must know how to do this,
> regardless of if it knows the default type for x-unknown.
>
> Which brings us back to timestamp. 20120101T010203Z is both a timestamp
> and a date-time, so in that case it shouldn't matter what the type is
> when converted back to vCard since its not wrong.
>
> I do agree that changing the type when converting back and forth isn't
> ideal either though. So what options do we have? Does this convince you
> that its not so bad to change the type? Do we just need "timestamp" as a
> type id, or also "date-and-or-time" ?

I'll have to meditate about this. :) And I'd like to see what others think.

Simon

---

From: Cyrus Daboo <[email-masked]>
Date: Thu, 14 Feb 2013 10:06:03 -0500

Hi Simon,

> When converting from jCard to vCard, always use the FOO.BAR:baz syntax.

Yes. This is a good solution - we should have done that for vCard v4 text 
format...

However, we also need to think about the interaction xCard too, since xCard 
uses <group> element to group properties - and it is possible that someone 
might convert directly between xCard and jCard. We could have a similar 
"hierarchical" construct for groups in jCard. Something like that might 
look like:

[ "vcard",
  {
    "":   [ /* ungrouped properties */ ],
    "foo": [ /* group foo properties */],
    "foo2": [ /* group foo2 properties */ ]
  }
]

Using an object as the second element of the "vcard" array would only 
happen if there were grouped properties - i.e. without groups the second 
element is just an array. That would make the parsing/generation logic a 
little trickier.

-- 
Cyrus Daboo