Subject: [Jcardcal] AD review of draft-ietf-jcardcal-jcard-03

From: Pete Resnick <[email-masked]>
Date: Mon, 17 Jun 2013 11:20:11 -0500

I think there are a few things in here that definitely need changing 
before it goes for Last Call, in particular my comments on 3.2. Beyond 
3.2, I'll leave that up to the WG to decide what needs to change before 
Last Call. I'll mark the document as "Revised I-D needed" so that I get 
notification when you post a new one, but the chairs should also ping me 
when it's good to go:

Introduction: As a strictly editorial suggestion, I think the first two 
paragraphs in the intro could use a little editing and re-arrangement. 
See if you like this:

    The vCard data format [RFC6350] provides for the capture and exchange
    of information normally stored within an address book or directory
    application. The vCard format has gone through multiple revisions,
    most recently vCard 4. 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 [RFC4627] over the classic vCard
    format is easier processing for JavaScript based widgets and
    libraries, especially in the scope of web-based applications.

    As certain similarities exist between vCard and the iCalendar data
    format [RFC5545], there is also an effort to define a JSON-based data
    format for calendar information  called jCal [I-D.ietf-jcardcal-jcal]
    that parallels the format defined in this specification.

3.1, second paragraph: I think there's an ambiguity in this paragraph. 
Though I think it's not likely to cause a problem for an implementer, 
it's probably better to be clear. I suggest:

    vCard data uses an "escape" character sequence for text values and
    property parameter values.  See Section 3.4 of [RFC6350].  When such
    text elements are converted into jCard, the vCard escaping MUST be
    removed first.  The only escaping that may be applied is any escaping
    mandated by JSON.

3.2: This section is very confusing. Starting from the title, it appears 
not to be defining a vCard stream, but rather a jCard stream. The first 
paragraph already mooshes this up:

    In certain cases it makes sense to group a sequence of vcard objects
    into a stream of objects.

The document never justifies this assertion (why couldn't they simply go 
in a simple array without an identifying first element?), but I'll set 
that aside for the moment.

    While the vCard 4 standard doesn't define
    a stream of vcard objects, having one makes it easier to identify
    multiple jCard objects

Having a stream of *vCard* objects doesn't make it easier to identify 
multiple *jCard* objects. Do you perhaps mean:

    While the vCard 4 specification doesn't define
    a stream of vCard objects, having a stream of jCard objects makes
    it easier to identify a group of jCard objects

Is that what you intended?

    and also ensures compatibility to jCal.

The above statement is also never justified in this document. How does 
having a group of jCard objects get you *compatibility* with jCal? (It 
might create a similar structure, but why is that desirable?)

    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.

Having jCard objects start with the element "vcard" is a weirdness that 
I can simply put aside, but it is causing confusions like the one above: 
Subsequent elements are *jCard* objects, not vCard objects.

    In the typical case where there is only one vCard object,
    encapsulation inside a "vcardstream" array MAY be omitted.

The above is probably true, but has a weird implication as written: Are 
you saying that when there is more than one jCard object, the 
"vcardstram" array is REQUIRED? I don't think so. How about:

    Encapsulation inside a "vcardstream" array is OPTIONAL. A jCard
    object MAY appear inside a "vcardstream" array or MAY appear
    in other JSON objects.

Does that capture it?

    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:

Again, I'd call it a "jCard stream", but either way, it does not contain 
vCard objects; it contains jCard objects. The mention of "BEGIN: VCARD" 
and "END: VCARD" here I don't understand at all, since these will not 
appear in the jCard.

Finally, the last paragraph of this section seems to have nothing to do 
with streams. It looks like it's supposed to be an intro paragraph for 
sections 3.3, 3.4, and 3.5. If so, it should come out into its own 
section and the subsequent sections should be subsections. (It also 
confuses vCards and jCards.)

Section 3.2 needs serious help.

3.3:

    The array describing the property can then be inserted into the array
    designated for properties in the "vcard" component.

The "'vcard' component" probably should have been defined before this 
section. Somewhere earlier (maybe that last paragraph of 3.2 once it 
gets moved to the right place) it should say "A jCard is an array of 
properties, elements, and values contained in a JSON array, the first 
element of which is 'vcard'." Or something like that.

3.3.1.2: I found this section a bit weird. It sounds like you're adding 
a pre-processing step: Take a 6350 group and turn it into a new *vCard* 
GROUP parameter before converting it to a jCard the normal way. Instead 
of registering a new GROUP parameter for vCard (which you already define 
as "MUST NOT be used"), why not describe this as a special case for the 
conversion (both forward and back)? The way you have seems destined to 
leak one of these things into a vCard.

3.3.1.3:

    If a multi-valued text component is changed to hold only one value,
    the text component SHOULD be represented as a single primitive value,
    but MAY be represented as an array with a single primitive value.

That paragraph is contradictory. You can't say something both SHOULD and 
MAY be done. Either it will cause an interoperability problem if you do 
it this way (in which case it's a MUST if there are no conceivable 
reasons to do otherwise, or a SHOULD if there could possibly be 
exceptions, but the implementation had better be prepared for problems) 
or it is entirely up to the implementation and it doesn't make a 
difference (in which case it's a MAY). Pick one.

    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.

I think the MAY is probably wrong. You're not defining a new option 
here, right? You're simply restating what 6350 states. I think you mean 
"can" here, not "MAY". As for the SHOULD, I'm a bit confused by what I'm 
supposed to implement there.  Are you saying that an converter from a 
vCard to a jCard SHOULD check something? If so, how should it check it? 
I think rewording this to identify who is doing the checking and what 
they should be looking for that is important.

3.4.2:

    Single-value parameters SHOULD
    be represented using a single string value, but an array with one
    element MAY also be used.

SHOULD/MAY contradiction.

3.5.3, 3.5.4., 3.5.5, 3.5.7:

    This information is to be seen as an informative reference, the
    normative reference is...

That's a bizzarre construction. It's not an informative "reference" at 
all. I suggest instead:

    This information is just an example and not a formal specification of
    the syntax. The specification can be found in...

4: Do I understand correctly that explicit vCard VALUE parameters might 
not round-trip if it is simply re-specifying the default? I assume the 
WG thought this was OK?

5:

    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.

That sentence got a bit confusing. I suggest something like:

    In vCard, properties have a default value type specified by their
    definition, but the value type can be explicitly changed to a
    different one. For example, "BDAY"'s value type is
    "date-and-or-time", but a vCard can explicitly put a "VALUE=text"
    property on a "BDAY" and use a string as it's value.

Did I get that right?

As with GROUP, I'm a bit worried about registering "UNKNOWN" for vCard. 
Why not simply make this special-case processing for jCard, since it's 
never going to be used in a real vCard?

Appendix A:

    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

That can't be right. jcardobject is defined twice.

    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

s/propery-value/property-value

    simple-prop-value = string / number / boolean

"boolean" is undefined, here or in 4627.

-- 
Pete Resnick<http://www.qualcomm.com/~presnick/>
Qualcomm Technologies, Inc. - +1 (858)651-4478

---

From: Simon Perreault <[email-masked]>
Date: Mon, 17 Jun 2013 18:42:49 +0200

> not round-trip if it is simply re-specifying the default? I assume the

I never considered this. Now that you mention it, I think it's fine.

One thing though. This is the text:

    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.

The SHOULD NOT is too strong. Nothing bad happens is you always 
explicitly set the VALUE parameter.

Suggestion: s/SHOULD NOT/MAY not/

> never going to be used in a real vCard?

The reason for registering "GROUP" and "UNKNOWN" is precisely because we 
do not want them to be used in vCard, ever. I don't understand what you 
are proposing as an alternative.

Simon

---

From: Pete Resnick <[email-masked]>
Date: Mon, 17 Jun 2013 11:59:39 -0500

On 6/17/13 11:42 AM, Simon Perreault wrote:

> The reason for registering "GROUP" and "UNKNOWN" is precisely because 
> we do not want them to be used in vCard, ever. I don't understand what 
> you are proposing as an alternative.

Aha! That wasn't clear because the registration looks more or less 
normal. Effectively, you are reserving these in the registry. So, I 
guess I'm suggesting two things:

1. Make it clearer in the jCard spec that you are introducing a group 
construct, but not a "group" parameter in jcard or a "GROUP" parameter 
in vCard. You are *reserving* a "GROUP" parameter in vCard.

2. Make it clearer in the jCard spec that you *are* introducing an 
"unknown" value type in jCard, but you are *not* introducing an 
"UNKNOWN" value type in vCard; you are only *reserving* the "UNKNOWN" 
value type in vCard.

Does that make sense? (It would be nice if the vCard registries had a 
"comments" field in addition to the "reference" field.)

pr

---

From: Simon Perreault <[email-masked]>
Date: Mon, 17 Jun 2013 19:13:19 +0200

Le 2013-06-17 18:59, Pete Resnick a écrit :
> Does that make sense?

Makes total sense, IMHO.

Simon

---

From: Peter Saint-Andre <[email-masked]>
Date: Mon, 17 Jun 2013 11:22:41 -0600

>> "UNKNOWN" value type in vCard; you are only *reserving* the "UNKNOWN"

Yes, it would be good to make that clear in the spec and the registration.

Peter

--
Peter Saint-Andre
https://stpeter.im/

---

From: Cyrus Daboo <[email-masked]>
Date: Mon, 17 Jun 2013 13:41:04 -0400

Hi Pete,

>     that parallels the format defined in this specification.

Your text is better.

>     removed first.  The only escaping that may be applied is any escaping

That is fine, however I see that we are missing a reference to RFC6868 
which also defines a new parameter encoding mechanism (applicable to 
iCalendar as well). We need to add that reference in:

    vCard data uses an "escape" character sequence for text values and
    property parameter values.  See Section 3.4 of [RFC6350] and [RFC6868].
    When such text elements are converted into jCard, the vCard escaping
    MUST be removed first.  The only escaping that may be applied is any
    escaping mandated by JSON.

6868 then needs to be added as a normative reference. A similar change 
should be done for the jCal document.

> Having jCard objects start with the element "vcard" is a weirdness that I
> can simply put aside, but it is causing confusions like the one above:

Yes.

>     property on a "BDAY" and use a string as it's value.

Actually I think we need to make it clear that you cannot just arbitrarily 
change the value of a property. The key issue is that the property 
definitions defines an explicit list of allowed properties, of which one is 
the default. Only values from that list can be used. How about:

    In vCard, properties can have one or more value types as specified by
    their definition, with one of those values being defined as the
    default. When a property uses its default value type, the "VALUE"
    property parameter does not need to be specified on the property. For
    example, "BDAY"'s default value type is "date-and-or-time", so
    "VALUE=date-and-or-time" need not be set as a property parameter.
    However, "BDAY" also allows a "text" value to be specified, and if that
    is used, "VALUE=text" has to be set as a property parameter.

> That can't be right. jcardobject is defined twice.

Yup - first one should be removed.

> "boolean" is undefined, here or in 4627.

Probably should be:

simple-prop-value = string / number / true / false

-- 
Cyrus Daboo

---

From: Pete Resnick <[email-masked]>
Date: Mon, 17 Jun 2013 13:43:21 -0500

On 6/17/13 12:41 PM, Cyrus Daboo wrote:
>> That sentence got a bit confusing.
>
> Actually I think we need to make it clear that you cannot just 
> arbitrarily change the value of a property. The key issue is that the 
> property definitions defines an explicit list of allowed properties, 
> of which one is the default. Only values from that list can be used. 
> How about:
>
>

Works for me.

pr