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

[Philipp Kewisch <[e-mail]>]

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

>
> 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".
Done
>
> 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."
Done
>
> 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.
Yes, indeed. I think I previously had more properties in that example. 
Fixed both issues.
>
> 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?
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. 
> Instead, why not "can"?
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.
>
> 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.
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