Subject: [Jcardcal] AD Evaluation of draft-ietf-jcardcal-jcal-08

From: Pete Resnick <[email-masked]>
Date: Wed, 5 Feb 2014 00:29:48 -0600

Sorry for the delay in this. This document is pretty much ready for IETF 
Last Call. Only one issue that I'd like to address before I send it out. 
After that one's cleared up, I'll ship; you can deal with the rest of 
the comments as if they were Last Call comments.

Here's the big one. 3.4.1.1 (and similarly in 3.4.1.2):

    This kind of special casing can be seen as a "structured value", as
    described in [I-D.ietf-jcardcal-jcard], Section 3.3.1.3.
    Implementors may want to keep this in mind in case they aim to
    support both jCard and jCal in their product.  For example, checking
    the data type of all property values instead of assuming an array for
    just GEO is RECOMMENDED.

I find that paragraph incomprehensible. I don't understand what it 
means. Please explain.

The rest of these are non-blocking IMO. I ignored grammatical stuff 
unless it potentially confused the meaning; I'll leave those for the RFC 
Editor.

3.1: "So the following rules MUST be applied..." is redundant with the 
MUSTs below. Instead: "So the following rules are applied".

3.2:

    If you
    plan to transport multiple jCal objects in a stream, it is
    recommended to use a simple JSON array.

I'm not a big fan of using "recommended" when you just mean "can". I 
suggest instead "To transport multiple jCal objects in a stream, a 
simple JSON array can be used."

3.4:

- Typo: "followed by at one or more additional". I think you just want 
to strike "at".
- "while all other properties are single-valued:" I think you mean 
"while the 'summary' property is single-valued:", since there are no 
other properties.

3.5.2:

    Single-value parameters SHOULD
    be represented using a single string value, although a more simple
    implementation might prefer an array with one string element.

What harm will come to me or the other side if I don't? Isn't this just 
an aesthetic choice and I should do whichever is easier in my 
implementation?

3.6.4/3.6.5/3.6.12: "are not permitted"? Why not "MUST NOT be used"?

3.6.8: Does this need to say "MUST NOT have a 'frac' or 'exp' portion"?

3.6.10: "it is RECOMMENDED to represent it as a...". Same question from 
3.5.2.

6: Please move this to an appendix

8: I have no idea what the "SHOULD" in the opening paragraph means. 
Instead, why not "can"?

8.1: So, I think the template specified in 5545 is useless and broken, 
because the information in this template is simply thrown away and does 
not go into the registry. Instead the template have the name of the data 
type, the status to be listed, and the reference. In this case those 
would be "UNKNOWN", "RESERVED - DO NOT USE", and "RFC XXXX, Section 5" 
(or something like that). But 5545 says what it says. So I would make 
the following changes to this section:

First paragraph, change to:

    IANA is asked to add the following entry to the iCalendar Data Types
    registry:

and strike the rest of the paragraph.

Change "Description" to:

    Description: The UNKNOWN value data type is reserved for the
       exclusive use of the jCal format. Its use is described in
       section 5 of this document.

Then add a paragraph at the end:

    IANA is asked to make the "Status" column for this entry in the
    registry say, "Reserved - Do not use" and to make the "Reference"
    column refer to section 5 of this document.

(It turns out that the vCard registry entry for UNKNOWN points to the 
wrong section of 7095; we'll get that fixed, but we should also probably 
put some sort of note field in that entry that says, "Reserved; do not 
use". I'll send a separate note about that.)

Make sense?

pr

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

---

From: Cyrus Daboo <[email-masked]>
Date: Wed, 05 Feb 2014 08:46:08 -0800

Hi Pete,

--On February 5, 2014 at 12:29:48 AM -0600 Pete Resnick 
<[email-masked]> wrote:

> I find that paragraph incomprehensible. I don't understand what it means.
> Please explain.

To be perfectly honest I think both those paragraphs can be dropped. I 
don't see them as adding much value. At some point having an implementation 
note describing the similarities/differences between jcard and jcal might 
be good but I don't think that needs to be an IETF document.

NB If we drop those two it will remove the need to reference jcard at all.

> an aesthetic choice and I should do whichever is easier in my

Oddly enough I am at CalConnect interop event right now and we ran into an 
issue with this! Several of us have added jcal support to our CalDAV 
servers and we are using a common test suite to validate the behavior. The 
test suite had hard-coded the behavior for a multi-valued property and 
expected a list with a single item, which worked fine with my server 
because my library generated that, but another server used the single 
value. Anyway, we resolved that issue with some added normalization in the 
test suite, but it did throw up a warning flag that this might be an 
interop issue. Other than that interop testing of jcal went pretty well.

I think my preference is to make it clear that either format is valid and 
must be expected, rather than stating a preference (via the SHOULD) for one 
over the other. The same should apply to section 3.6.10 as well.

I am OK with all your other proposed changes - Philipp and Mike can comment 
more if they feel the need.

-- 
Cyrus Daboo

---

From: Peter Saint-Andre <[email-masked]>
Date: Wed, 05 Feb 2014 10:09:14 -0700

[ no hat ]

What Cyrus says makes sense to me.

On 2/5/14, 9:46 AM, Cyrus Daboo wrote:
> don't see them as adding much value. At some point having an
> implementation note describing the similarities/differences between
> jcard and jcal might be good but I don't think that needs to be an IETF
> document.
>
> Oddly enough I am at CalConnect interop event right now and we ran into
> an issue with this! Several of us have added jcal support to our CalDAV
> servers and we are using a common test suite to validate the behavior.
> The test suite had hard-coded the behavior for a multi-valued property
> and expected a list with a single item, which worked fine with my server
> value. Anyway, we resolved that issue with some added normalization in
> the test suite, but it did throw up a warning flag that this might be an
> I think my preference is to make it clear that either format is valid
> and must be expected, rather than stating a preference (via the SHOULD)
> for one over the other. The same should apply to section 3.6.10 as well.
>
> I am OK with all your other proposed changes - Philipp and Mike can
> comment more if they feel the need.
>

---

From: Pete Resnick <[email-masked]>
Date: Thu, 6 Feb 2014 13:38:49 -0600

On 2/5/14 10:46 AM, Cyrus Daboo wrote:
>> means.
> jcard and jcal might be good but I don't think that needs to be an 
> IETF document.

If everyone's OK with that, so am I.

> Oddly enough I am at CalConnect interop event right now and we ran 
> into an issue with this! Several of us have added jcal support to our 
> CalDAV servers and we are using a common test suite to validate the 
> behavior. The test suite had hard-coded the behavior for a 
> multi-valued property and expected a list with a single item, which 
> worked fine with my server because my library generated that, but 
> another server used the single value. Anyway, we resolved that issue 
> with some added normalization in the test suite, but it did throw up a 
> warning flag that this might be an interop issue. Other than that 
> interop testing of jcal went pretty well.
>
> and must be expected, rather than stating a preference (via the 
> SHOULD) for one over the other. The same should apply to section 
> 3.6.10 as well.

That's the info I was looking for. Seems reasonable.

> comment more if they feel the need.

Unless there is objection to removing the text from 3.4.1.1 and 3.4.1.2, 
I'll ask you all to roll a new version with the changes, and then I will 
generate the IETF Last Call.

Thanks,

pr

---

From: Philipp Kewisch <[email-masked]>
Date: Tue, 18 Feb 2014 12:23:28 +0100

On 2/5/14, 7:29 AM, Pete Resnick wrote:
> Sorry for the delay in this. This document is pretty much ready for 
> IETF Last Call. Only one issue that I'd like to address before I send 
> it out. After that one's cleared up, I'll ship; you can deal with the 
> rest of the comments as if they were Last Call comments.
>
Ok, I've removed these paragraphs as suggested by Cyrus. There is one 
detail I would like to keep though and I think I found a good place to 
put it. I want to make clear that its a bad idea to rely on the third 
element of the property array (i.e "float" in the GEO case) to determine 
the data type of the value elements of the property array. I found some 
text about this in Section 3.4 that was a bit sparse, and made this 
modification:

OLD
    3.  The type identifier string of the value, in lowercase.  It is
        important that parsers check this to determine the data type of
        the value, and that they do not rely on assumptions.

NEW
    3.  The type identifier string of the value, in lowercase.  Due to
        special casing of certain properties as described in
        Section 3.4.1, it is important that parsers check both the type
        identifier and the value data type and do not rely on assumptions
        based on the property name.
END

> unless it potentially confused the meaning; I'll leave those for the 
> RFC Editor.
>
Done
> simple JSON array can be used."
Done
> "while the 'summary' property is single-valued:", since there are no 
Yes, indeed. I think I previously had more properties in that example. 
Fixed both issues.
> What harm will come to me or the other side if I don't? Isn't this 
> just an aesthetic choice and I should do whichever is easier in my 
> implementation?
Yes, my intent was to do whichever is easier, but prefer using a single 
string value. Given the findings at calconnect and Cyrus' suggestion, I 
have revised it in the following way:

OLD
    In [RFC5545], some parameters allow using a COMMA-separated list of
    values.  To ease processing in jCal, 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, although a more simple
    implementation might prefer an array with one string element. An
    example for a such parameter is the iCalendar "DELEGATED-FROM" and
    "DELEGATED-TO" parameter, more such parameters may be added in
    extensions.
NEW
    In [RFC5545], some parameters allow using a COMMA-separated list of
    values.  To ease processing in jCal, 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 can be
    represented either using a single string value or an array with one
    string element.  A jCal parser MUST be able to understand both value
    data types.  An example for a such parameter is the iCalendar
    "DELEGATED-FROM" and "DELEGATED-TO" parameter, more such parameters
    may be added in extensions.
END

> 3.6.4/3.6.5/3.6.12: "are not permitted"? Why not "MUST NOT be used"?
Fixed
> 3.6.8: Does this need to say "MUST NOT have a 'frac' or 'exp' portion"?
Hmm I agree the number usually shouldn't have a fractional part, but 
what speaks against a positive exponent? 3e+8 is still a valid integer. 
To be pedantic, certain negative exponents will also work, i.e 30e-1, as 
do certain fractional parts like 3.1e1.

Also, this is just about the value data type used in jCal. At latest 
when converting back to iCalendar, the value must stay in the range 
specified in 5545 and not contain an e. I have changed the text as follows:

OLD
   Description:  vCard "INTEGER" property values are represented by a
       property with the type identifier "integer".  The value elements
       are JSON primitive number values.
NEW
    Description:  vCard "INTEGER" property values are represented by a
       property with the type identifier "integer".  The value elements
       are JSON primitive number values which MUST resolve to an integer
       value in the range specified in [RFC5545], Section 3.3.8. Thus a
       fractional and/or exponential part are only allowed under limited
       circumstances.
END
>
> 3.6.10: "it is RECOMMENDED to represent it as a...". Same question 
> from 3.5.2.
Fixed, using the following text:

OLD
      *  The following rule parts can have one or more numeric values:
          "bysecond", "byminute", "byhour", "bymonthday", "byyearday",
          "byweekno", "bymonth", and "bysetpos".  If a rule part contains
          multiple values, an array of numbers MUST be used for that rule
          part.  Although it is allowed for the array to contain just one
          value, it is RECOMMENDED to represent it as a single JSON
          number value instead, omitting the array completely.

       *  Similarly, the "byday" rule part can have one or more string
          values.  If it contains multiple values, an array of strings
          MUST be used.  As before, it is RECOMMENDED to represent a
          single value as a JSON string, omitting the array completely.
NEW
      *  The following rule parts can have one or more numeric values:
          "bysecond", "byminute", "byhour", "bymonthday", "byyearday",
          "byweekno", "bymonth", and "bysetpos".  If a rule part contains
          multiple values, an array of numbers MUST be used for that rule
          part.  Single-valued rule parts can be represented either using
          a single number value, omitting the array completely, or an
          array with one number element.  A jCal parser MUST be able to
          understand both data types.

       *  Similarly, the "byday" rule part can have one or more string
          values.  If it contains multiple values, an array of strings
          MUST be used.  As before, a single-valued rule part can be
          represented either using a single string value or an array with
          one string element, both of which a jCal parser MUST
          be able to understand.
END

> 6: Please move this to an appendix
Done, moved to Appendix A
> 8: I have no idea what the "SHOULD" in the opening paragraph means. 
There may exist valid reasons to use something other than jCal for 
transferring calendar data in JSON, but I think everyone should be doing 
this :) Given this is the same opening text as in jCard, I have left it 
this way for now. If this requires further discussion I'm sure we can do 
it during the last call.
> because the information in this template is simply thrown away and 
> does not go into the registry. Instead the template have the name of 
> the data type, the status to be listed, and the reference. In this 
> case those would be "UNKNOWN", "RESERVED - DO NOT USE", and "RFC XXXX, 
> Section 5" (or something like that). But 5545 says what it says. So I 
> would make the following changes to this section:
>
By the time of publication, the IANA will have done this already? Its 
also the same text jCard uses. I've made this and other related changes 
nevertheless, since this is clearly a part of the document you have more 
experience in.

Thanks for the input, the updated draft is coming up in a few minutes.
Philipp