Subject: [Jcardcal] Barry Leiba's Discuss on draft-ietf-jcardcal-jcal-09: (with DISCUSS and COMMENT)

From: "Barry Leiba" <[email-masked]>
Date: Fri, 21 Mar 2014 16:58:59 -0700

Barry Leiba has entered the following ballot position for
draft-ietf-jcardcal-jcal-09: Discuss

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)

Please refer to http://www.ietf.org/iesg/statement/discuss-criteria.html
for more information about IESG DISCUSS and COMMENT positions.

The document, along with other ballot positions, can be found here:
http://datatracker.ietf.org/doc/draft-ietf-jcardcal-jcal/

----------------------------------------------------------------------
DISCUSS:
----------------------------------------------------------------------

I very much like this document, and will switch to "Yes" after we resolve
a couple of easy points.

RFC 4627 is clearly a normative reference, not an informative one.  Apart
from that, the replacement to 4627 is in the RFC Editor queue, and will
become an RFC before this document does.  I strongly suggest replacing
the 4627 reference with one to the I-D, so the new RFC gets dropped in by
the RFC Editor.  (If you do that, the eval() advice in Section 6 needs to
change accordingly.)

-- Section 4 --

   Character escaping and line folding MUST be applied to the resulting
   iCalendar data as required by [RFC5545] and [RFC6868].

The line folding part is in conflict with Section 3.1:

   The reverse order applies when converting from jCal to iCalendar.
   First, JSON escaping MUST be unescaped.  Afterwards, iCalendar
   escaping MUST be applied.  Finally, long lines SHOULD be folded as
   described in [RFC5545].

Which is meant, SHOULD (Section 3.1) or MUST (Section 4) ?

----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

Non-blocking comments to consider:

-- Appendix B --
I'm quite unhappy with using raw ABNF to describe JSON payloads.  You're
duplicating the ABNF in the JSON spec, and it's prone to errors, not to
mention being hard to read.  What you want to do here is to specify JSON
structures, not to specify the JSON syntax itself.

Look at RFC 7071 Section 6.2 for one way that this has been handled. 
http://tools.ietf.org/html/draft-newton-json-content-rules-01 specifies
another way.  Please consider changing to one of those.

I know that Cyrus has responded that he's reluctant to change this now,
but please consider it: I think this section is essentially useless as it
stands.  On the other hand, note that this is a non-blocking comment, so
I will not hold anything up if you decide to leave it be.

-- Section 3 --
Pedantic nit pet peeve:

   In [RFC5545], iCalendar objects are comprised of a set of
   "components", "properties", "parameters" and "values".

In correct usage, the whole "comprises" the parts.  So:

NEW
   In [RFC5545], an iCalendar object comprises a set of
   "components", "properties", "parameters" and "values".
END

(If you don't like that, use "is composed of" instead of "is comprosed
of".)

---

From: Philipp Kewisch <[email-masked]>
Date: Mon, 24 Mar 2014 22:04:14 +0100

Hi Barry,

thanks for the comments. See my feedback inline:

Done, I've changed it in this way:

OLD
   With this in mind, a parser for JSON data should be used for jCal
   that is aware of the security implications.  For example, the use of
   JavaScript's eval() function is only allowed using the regular
   expression in Section 6 of [RFC4627].  A native parser with full
   awareness of the JSON format should be preferred.
NEW
   With this in mind, a parser for JSON data should be used for jCal that
   is aware of the security implications. For example, the use of
   JavaScript's eval() function is considered an unacceptable security
   risk, as described in [RFC7159], Section 12. A native parser with full
   awareness of the JSON format should be preferred.
END

> Which is meant, SHOULD (Section 3.1) or MUST (Section 4) ?

rfc5545 Section 3.1 mentions that 'Long content lines SHOULD be split
into a multiple line representations using a line "folding" technique'.
So yes, that "SHOULD" MUST be considered. The SHOULD in jCal section 3.1
is an extension of the SHOULD in rfc5545. All very confusing, so lets
change it. How is this?

OLD

NEW

   The reverse order applies when converting from jCal to iCalendar.
   First, JSON escaping MUST be unescaped.  Afterwards, iCalendar
   escaping MUST be applied. Finally, if desired, long lines can be 
   folded in accordance with [RFC5545] Section 3.1.

END

> I'm quite unhappy with using raw ABNF to describe JSON payloads. 
> [...]
While it is indeed a little harder to read with the JSON structures in
place, I don't think it makes the ABNF useless. I looked at rfc 7071, I
don't find this any easier to read. The draft you mentioned looks a lot
more promising, but I am reluctant to use a -01 draft here. We never
know what might change until that draft goes into its final version.

That said, I agree with Cyrus and I don't think its a good idea to
change it now. I will definitely keep this in my mind for the next
document, or a possible revision of the jCard/jCal documents.

> (If you don't like that, use "is composed of" instead of "is comprosed
Thanks, taking it as you suggested!

Philipp

---

From: Barry Leiba <[email-masked]>
Date: Mon, 24 Mar 2014 17:24:17 -0400

>    awareness of the JSON format should be preferred.

Perfectitude; thanks.

> rfc5545 Section 3.1 mentions that 'Long content lines SHOULD be split into a
> multiple line representations using a line "folding" technique'. So yes,
> that "SHOULD" MUST be considered. The SHOULD in jCal section 3.1 is an
> extension of the SHOULD in rfc5545. All very confusing, so lets change it.

Let's change it, indeed.  Things like "You MUST obey the SHOULD over
in the other document" are just asking for misunderstandings.

Unfortunately, I think you chose to change the wrong bit -- the SHOULD
in Section 3.1 is clear, echoing the SHOULD in 5545.  It's the "MUST
obey the SHOULD" part that ought to be changed, in Section 4.  How
about this change instead (leaving 3.1 as it is)?:

OLD
   Character escaping and line folding MUST be applied to the resulting
   iCalendar data as required by [RFC5545] and [RFC6868].
NEW
   Character escaping and MUST be applied to the resulting iCalendar
   data as required by [RFC5545] and [RFC6868], and lines SHOULD
   be folded as described in [RFC5545].
END

Of course, one could also ask why the same normative requirements are
in both sections 3.1 and 4.  Shouldn't it be in one place only?

> I'm quite unhappy with using raw ABNF to describe JSON payloads.

Enough said on this... my opinion is non-blocking, and I leave it to
your judgment to keep it as it is.  Thanks for discussing it.

Barry

---

From: Philipp Kewisch <[email-masked]>
Date: Mon, 24 Mar 2014 23:08:03 +0100

>    be folded as described in [RFC5545].
Ok, sounds good. I've left 3.1 as is and changed 4 as you suggested, but
explicitly added the reference to Section 3.1 at the end:

NEW

   Character escaping and MUST be applied to the resulting iCalendar
   data as required by [RFC5545] and [RFC6868], and lines SHOULD
   be folded as described in [RFC5545], Section 3.1.

END
> in both sections 3.1 and 4.  Shouldn't it be in one place only?
The excerpt in Section 3.1 speaks of the reverse process, which is of
course described in more detail in section 4. Its there for convenience
and to complement the former paragraph. I guess what we could do is move
that paragraph to Section 4 and just mention that the reverse process
works similarly, as further described in Section 4. Would you prefer that?

Philipp

---

From: Barry Leiba <[email-masked]>
Date: Mon, 24 Mar 2014 18:40:32 -0400

> works similarly, as further described in Section 4. Would you prefer that?

I would prefer that, because I prefer to have information in one
place, avoiding errors and confusion caused by imperfect duplication.
But check with your responsible AD (Pete) for further instruction.
You have certainly resolved all my DISCUSS issues.

Barry

---

From: Philipp Kewisch <[email-masked]>
Date: Tue, 25 Mar 2014 22:31:55 +0100

> You have certainly resolved all my DISCUSS issues.
Hi Barry, Pete, all,

I have taken a look at this issue, here is my proposal to fix it:

First of all, the paragraphs in Section 3.1:

OLD
   When converting from iCalendar to jCal, first iCalendar lines MUST be
   unfolded.  Afterwards, any iCalendar escaping MUST be unescaped.
   Finally JSON escaping (e.g., for control characters) MUST be applied.

   The reverse order applies when converting from jCal to iCalendar.
   First, JSON escaping MUST be unescaped.  Afterwards, iCalendar
   escaping MUST be applied.  Finally, long lines SHOULD be folded as
   described in [RFC5545].
NEW
  When converting from iCalendar to jCal, first iCalendar lines MUST be
   unfolded.  Afterwards, any iCalendar escaping MUST be unescaped.
   Finally JSON escaping, as described in [RFC7159] Section 7, MUST be
   applied.  The reverse order applies when converting from jCal to
   iCalendar, which is further described in Section 4.
END

Then I looked into Section 4, I think it requires some additional words
in general. Here is what I changed:

OLD
   When converting component, property and property parameter values,
   the names SHOULD be converted to uppercase.  Although iCalendar names
   are case insensitive, common practice is to keep them all uppercase
   following the actual definitions in [RFC5545].
  
   Character escaping and line folding MUST be applied to the resulting
   iCalendar data as required by [RFC5545] and [RFC6868].
NEW
   Converting jCal to iCalendar reverses the process described in
   Section 3.  This section describes a few additional requirements for
   conversion.

   When converting component, property and property parameter names,
   they names SHOULD be converted to uppercase.  Although iCalendar
   names are case insensitive, common practice is to keep them all
   uppercase following the actual definitions in [RFC5545].

   During conversion, JSON escaping MUST be unescaped.  Afterwards,
   iCalendar escaping, as defined by [RFC5545] and [RFC6868] MUST be
   applied.  Finally, long lines SHOULD be folded as described in
   [RFC5545], Section 3.1.
END

Let me know what you think.
Philipp