[Jmap] Re: Publication has been requested for draft-ietf-jmap-calendars-16

["Murray S. Kucherawy" <[e-mail]>]

On Tue, Apr 9, 2024 at 7:03 PM Bron Gondwana via Datatracker <
[e-mail]> wrote:

> Bron Gondwana has requested publication of draft-ietf-jmap-calendars-16 as
> Proposed Standard on behalf of the JMAP working group.
>
> Please verify the document's state at
> https://datatracker.ietf.org/doc/draft-ietf-jmap-calendars/
>

Sorry this has taken so long to dequeue.  The good news is that it looks
like it's mostly ready to go forward; most of my comments have to do with
presentation rather than substance.

AD Evaluation comments, in no particular order, based on the -17 content:

* What's the distinction being made in the registrations in terms of
"Intended Use"?  Some are "common" while others are "reserved", but the
latter group seems to me to be going into common use by advancing this
protocol.

* Why the SHOULD in Section 3?  How would a consumer interpret all of them
being false?  When might a producer legitimately send them all as false?
The same issue appears in Section 4.

* What interoperability problem is created if I disregard the SHOULD NOT in
Section 4.3?

* The SHOULD NOT in Section 5.8 seems like it ought to be a MUST NOT for
integrity reasons.  Why would one permit this?

* I disagree with the use of SHOULDs in Section 5.10.1.  If you're giving
flexibility intentionally, then I think you should lowercase them all.
You've already given up on enforcing any kind of interoperability and made
it mushy in the paragraph that comes before them.

* The SHOULDs in Section 6 and 7 seem weakly supported to me.  What's the
interoperability concern if one chooses to deviate from what's stated there?

* In Section 2.1, the "accountId" definition with parenthetical stuff
removed reads:

> Id of Account with the urn:ietf:params:jmap:calendars capability that
contains the calendar data for this principal, or null if none, or the user
does not have access to any data in the account. The corresponding Account
object can be found in the principal's "accounts" property, as per Section 2
<https://datatracker.ietf.org/doc/html/draft-ietf-jmap-sharing-08#section-2>
of [I-D.ietf-jmap-sharing
<https://datatracker.ietf.org/api/v1/doc/document/draft-ietf-jmap-sharing/>]
.

I have trouble parsing that.  Perhaps:

> Id of Account with the urn:ietf:params:jmap:calendars capability that
contains the calendar data for this principal, or null if either (a) there
is none, or (b) the user does not have access to any data in the account.
The corresponding Account object can be found in the principal's "accounts"
property, as per Section 2
<https://datatracker.ietf.org/doc/html/draft-ietf-jmap-sharing-08#section-2>
of [I-D.ietf-jmap-sharing
<https://datatracker.ietf.org/api/v1/doc/document/draft-ietf-jmap-sharing/>]
.

...assuming I understand what's going on here.

* In Section 2.1, the definitions of "mayGetAvailability" and
"mayShareWith" (booleans) are posed as questions, while in Section 2.2 the
boolean is defined with "If true, ...".  I think the latter reads better
and suggest changing the others.  This appears again in Section 4 for
"isVisible" and "includeInAvailability", but curiously not with the ones
starting "may".

* At the end of Section 3.3, "uri values" should be "URI values".

* In Section 4, there's this:

> True if the user has indicated they wish to see this Calendar in their
client. This should default to false for Calendars in shared accounts the
user has access to and true for any new Calendars created by the user
themself.
>
> If false, the calendar should only be displayed when the user explicitly
requests it or to offer it for the user to subscribe to. For example, a
company may have a large number of shared calendars which all employees
have permission to access, but you would only subscribe to the ones you
care about and want to be able to have normally accessible.

The first paragraph refers to users in the third person, the second uses
the second person.  I suggest normalizing on the third.

* Section 4 recommends use of UUIDs; you can make a reference here to RFC
9562.

* Section 4.3 (and I missed it in 2.1) uses the word "sharee", and I know
what it's supposed to mean, but it doesn't appear in either Merriam-Webster
or Oxford.  Have we used it in RFCs previously?

* In Section 5.8, it says "Clients SHOULD NOT allow users to manually edit
anything ..."; why is "manually" there?  What other kinds of editing are
you considering?

* Staying with Section 5.8:

> Similarly, the "utcEnd" property is translated into a "duration" property
if set. It MUST NOT be set in addition to a "duration" property and it
cannot be set inside "recurrenceOverrides"; this MUST be rejected with an
invalidProperties SetError.

This might be a function of the rendering of the document (I read it via
the HTML link in the datatracker), but (a) it seems to me
"invalidProperties" should be quoted, just like the other tokens are, and
as a result of observing that, now I've noticed that (b) quoting of tokens
(as rendered to me at least) is generally inconsistent throughout the
document.

* In Section 5.2, there's a reference to "[?@RFC8607]"; is this a rendering
problem or a typo?

-MSK