Subject: Re: [calsify] Benjamin Kaduk's Discuss on draft-ietf-calext-ical-relations-09: (with DISCUSS and COMMENT)

From: Benjamin Kaduk <[email-masked]>
Date: Mon, 7 Mar 2022 11:38:40 -0800

Hi Michael,

Most of this looks really good, and I'll go lift my Discuss shortly.
Just a handful of notes scattered inline...

On Sun, Feb 27, 2022 at 06:10:37PM -0500, Michael Douglass wrote:
> Thank you for your detailed response - please see below ...
> 
> On 2/15/22 17:26, Benjamin Kaduk via Datatracker wrote:
> 
> > ...
> >
> >
> > ----------------------------------------------------------------------
> > DISCUSS:
> > ----------------------------------------------------------------------
> >
> > The ABNF for linkparam (§8.2) incorporates a "langparam" production, but
> > that is not defined in any of this document, RFC 5455, RFC 8288, or RFC
> > 7986.  We need to define it somehow, whether by reference or directly.
> > RFC 5545 does define a LANGUAGE parameter (our prose references a "LANG"
> > parameter) and languageparam ABNF production, which is perhaps the
> > simplest explanation for what was intended.
> Yes - it should have been languageparam - corrected

Excellent, I'm glad it was the easy fix.

> >
> > ----------------------------------------------------------------------
> > COMMENT:
> > ----------------------------------------------------------------------
> >
> > A couple broad comments before getting into the section-by-section
> > details:
> >
> > I'm a little unclear on the value gained by having RELTYPE=REFID and
> > RELTYPE=CONCEPT.  If the semantics were just supposed to be "is a member
> > of the indicated group", then why do we need a relation type to say so.
> > But if there's some other semantics associated, where do we define those
> > semantics?
> The idea is to associate one entity with others without that entity 
> necessarily having the associated attribute. The semantics are more like 
> - this is an aggregator for those things with the designated REFID or 
> CONCEPT

Ah, thanks for the extra explanation.  Perhaps I was just being a bit dense
when I first read it; I don't really have any suggestions for how we might
add more text that would have prevented my confusion.

> > There are a number of places (e.g., §1.4) where this document uses the
> > term "collection" in a context that suggests that it should be a defined
> > term of iCalendar, corresponding roughly to a "site" or administrative
> > domain, but I didn't find any usage in RFC 5545 that would correspond to
> > what's being described here.  Can we say more about what level of grouping
> > this is intended to refer to?
> 
> More of a CalDAV thing. I'll precede the first occurrence with some text
> 
> ------ OLD -------
> 
> It is also often necessary to reference calendar components in other
> 
> collections.  For example, a VEVENT might refer to a VTODO from which
> 
> ------ NEW -------
> 
> Calendar components are often grouped into collections to represent a
> calendar or a series of tasks, for example [RFC4791] (CalDAV) calendar
> collections.
> 
> It is often necessary for calendar components in one such collection
> to reference components in other collections.  For example, a VEVENT
> might refer to a VTODO from which...
> 
> ------------------
> 
> > Section 1.1
> >
> >     The iCalendar [RFC5545] RELATED-TO property has no support for
> >     temporal relationships as used by standard project management tools.
> >
> > I am admittedly not really the target audience of this specification, but
> > I have no idea what the "standard project management tools" are that are
> > being referred to.  Would (informative) references to a handful be
> > appropriate?
> 
> I guess I should drop 'standard' and just write
> 
>     temporal relationships as used by project management tools.
> 
> 
> It's really the relationships which are 'standard' in the sense they are 
> apparently used by all/most project management tools.There is also the 
> Project Management Institute which has /A Guide to the Project 
> Management Body of Knowledge /which apparently defines these terms also. 
> I'm not sure if we want a reference to that - I think it's as close as 
> we get to a standard
> //
> 
> > Section 1.2
> >
> >     REFID is used to identify a key allowing the association of
> >     components that are related to the same object and retrieval of a
> >     component based on this key.  [...]
> >
> > This says "related to the same *object*" (emphasis mine), but the rest of
> > the section just talks about an unstructured grouping.  It seems like we
> > could give some hint of the nature of the "object" to which all the
> > elements of the group are related, prior to the RELTYPE=REFID definition
> > in §5.
> 
> Not sure how to reword this. The examples were an attempt to define 
> that. I should probably at least stick with component instead of object.
> 
> I've tried a bit of rewording...
> 
> ------ OLD -------
> 
> REFID is used to identify a key allowing the association of
> components that are related to the same object and retrieval of a
> component based on this key.  Two examples of how this may be used
> are to identify the tasks associated with a given project without
> having to communicate the task structure of the project, and to group
> all tasks associated to a specific package in a package delivery
> system.
> 
> ------ NEW -------
> 
> REFID is used to identify a key allowing the association of
> components that are all related to the referring, aggregating component and
> the retrieval of components based on this key.  For example, this may be used
> to identify the tasks associated with a given project without
> having to communicate the task structure of the project. A further example
> is the grouping of all sub-tasks associated with the delivery of a specific
> package in a package delivery system.
> ------------------
> 
> >
> > Section 1.3
> >
> >     The current [RFC5545] CATEGORY property is used as a free form
> >     'tagging' field.  [...]
> >
> > In light of the discussion in the previous section about grouping without
> > semantics, we might consider mentioning here that this is "tagging with
> > semantics", just vaguely defined ones, as opposed to the REFID-type
> > "tagging without semantics".
> Added some text.
> >
> > Section 1.4
> >
> >     server-side management and stripping of inline data.  Clients may
> >     choose to handle attachments differently from the LINK property as
> >     they are often an integral part of the message - for example, the
> >     agenda.
> >
> > (See the NITS entries as well, but) is it particularly noteworthy that
> > clients might handle LINKs different from ATTACHments?  They are different
> > properties after all -- why would someone assume equivalent treatment?
> 
> I'm not sure why - but it seems worth pointing out just in case. There's 
> some degree of similarity between a LINK and an ATTACHMENT - especially 
> if the attachment value is a uri.
> 
> Also I think when I wrote this managed attachments wasn't an RFC. I have 
> the ref but the text is vague.
> 
> ------------ OLD ----------
> 
> The LINK property MUST NOT be treated as just another attachment.
> The ATTACH property defined in [RFC5545] is being extended to handle
> server-side management and stripping of inline data.  Clients may
> choose to handle attachments differently from the LINK property as
> they are often an integral part of the message - for example, the
> agenda.
> 
> For more information on managed attachments see [RFC8607]
> 
> ------------ NEW ----------
> 
> The LINK property MUST NOT be treated as just another attachment.
> The ATTACH property defined in [RFC5545] has been extended by [RFC8607]
> to handle server-side management and stripping of inline data and to
> provide additional data about the attachment (size, filename etc).
> 
> Additionally clients may choose to handle attachments differently
> from the LINK property as attachments are often an integral part
> of the message - for example, the agenda.
> ---------------------------
> 
> 
> >
> > Section 1.5
> >
> >     To facilitate offline display the link type may identify important
> >     pieces of data which should be downloaded in advance.
> >
> >     In general, the calendar entity should be self explanatory without
> >     the need to download referenced meta-data such as a web page.
> >
> > I'm not sure how to relate these two statements.  It sounds like a "<X>
> > may happen, but in general don't do <X>" scenario, in which case it might
> > flow better to give the general advice first, followed by the specific
> > scenario in which there is an exception to the general guidance.
> It does read better - changed
> >
> > Section 2
> >
> >     The actual reference value can take three forms specified by the type
> >     parameter
> >
> > Is this list fixed for eternity or do we want to give some guidance that
> > implementations need to prepare for future extensibility?
> >
> >     REFERENCE:  In an XML environment it may be necessary to refer to a
> >
> > This qualification in the description ("XML environment") suggests that
> > perhaps the name being used for these semantics is an overly generic name.
> 
> Having reread the text section has a number of problems, e.g - it's not 
> "type" - it's the VALUE parameter. I think the title is wrong - this is 
> really about LINK property references so I'll change the title. Also 
> LINK has no default type and - to get ahead a little - in the LINK 
> definition VALUE-TEXT should be VALUE=UID.
> 
> Your point about REFERENCE stands - I'll change it to XML-REFERENCE 
> elsewhere.
> 
> I'll update the text and get a new version out.
> 
> I've added some text to point out that UID references may need updating 
> on import and export.
> 
> >
> > Section 4
> >
> > We do have some text here about the GAP parameter that specifies the lead
> > or lag time here, but then we go on to describe the various RELTYPE values
> > in language like "cannot start until", "can only be completed after",
> > etc., that is very absolute and does not acknowledge the potential for a
> > GAP.  I think it would be helpful to reframe as that we are making a
> > comparison between the indicated pair of events, and that the relationship
> > between when the events occur is affected by the GAP interval.
> > (Also, the text in this section on the GAP parameter doesn't give a great
> > sense that the lead time would be a negative gap.)
> Rather than reframe I'll add a note and a couple of examples of the 
> relationships with a GAP parameter.
> >
> > Section 5
> >
> >     RELTYPE=FIRST:  Indicates that the referenced calendar component is
> >        the first in a series the referenced calendar component is part
> >        of.
> >
> > I wonder if we want to explicitly contrast this with PARENT and provide an
> > example of them being different.
> 
> I added this to allow jscalendar and icalendar events to be mapped. 
> Unfortunately I omitted to add RELTYPE=NEXT.
> 
> I'll add the NEXT relation,
> 
> The difference is that PARENT, CHILD and SIBLING relationships are about 
> hierarchy and FIRST, NEXT about order. I can add some text.
> 
> >
> > Section 6.1
> >
> >        In addition to the values defined here any value defined in
> >        [RFC8288] may be used.  However these uses SHOULD be documented in
> >        an RFC updating both [RFC5545] and [RFC8288]
> >
> > In some sense this feels a little like saying "the current document SHOULD
> > have documented this stuff, but we didn't".  Is there anything useful to
> > say about why this documenting can't be done now?  (Oh, I guess there are
> > rather more values in the registry than I remembered, though the number of
> > them actually defined in RFC 8288 might be zero?)
> 
> In response to other comments I cut this back to
> 
> In addition to the value defined here any link relation
> in the link registry established by [RFC8288],
> or new link relations, may be used.
> 
> but I'm a little uneasy about that. Maybe add the text ", but should be 
> documented in an RFC" at the end?
> 
> It seems to me that we should at least document how these are to be used 
> in a calendaring environment.

Maybe something like "It is expected that link relation types seeing
significant usage in calendaring will have the calendaring usage described
in an RFC"?  There are probably a lot of different approaches here, and I
have no strong sense of which would be "best".

> >
> > Section 8.1
> >
> >     Conformance:  This property can be specified zero or more times in
> >        any iCalendar component.
> >     [...]
> >        Within the "VEVENT", "VTODO", or "VJOURNAL" calendar components,
> >        more than one formal category can be specified by using multiple
> >        CONCEPT properties.
> >
> > Are these two statements fully compatible?  The former seems to give
> > leeway to put multiple CONCEPT properties in any iCalendar component, but
> > the latter seems to limit to the "more than one" ability to just the three
> > named components.
> I suspect that's something that remained after a copy/paste exercise. 
> The paragraph naming components should go - it just repeats what was 
> written before it.
> >
> > Section 8.2
> >
> > I am not entirely sure when the TEXT value type would be used.  If it's
> > just there to allow for certain types of extensibility, that might be
> > worth stating specifically.
> That should have been VALUE=UID.
> >
> >        There is no mapping for [RFC8288] "title*", "anchor", "rev" or
> >        "media".
> >
> > Maybe "there is currently no mapping"?  Or is the definition of such
> > mapping prevented for some technical reason(s)?
> They don't work or have meaning in the calendar context
> >
> > Section 9
> >
> >     This specification updates the RELATED-TO property defined in
> >     Section 3.8.4.5 of [RFC5545].
> >
> > I'd consider adding a note that "the contents of Section 9.1 below replace
> > Section 3.8.4.5 of [RFC5545]" to clarify the relationship between the two
> > sections.
> Done
> >
> > Section 9.1
> >
> >        By default, the property value points to another calendar
> >        component that has a PARENT relationship to the referencing
> >        object.  The "RELTYPE" property parameter is used to either
> >        explicitly state the default PARENT relationship type to the
> >        referenced calendar component or to override the default PARENT
> >        relationship type and specify either a CHILD or SIBLING
> >        relationship or a temporal relationship.
> >
> > We allow some new relationship types that are neither CHILD/SIBLING nor
> > temporal (e.g., CONCEPT, REFID).  Should those get some text in the
> > description too?  (I am not sure if DEPENDS-ON and FIRST should get lumped
> > in as "temporal", either -- we don't do so in §5.)
> 
> I'll change that to
> 
>        relationship type and specify some other relationship.
> 
> I'll add some text for the other types.
> >
> >        The FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH or STARTTOSTART
> >        relationships define temporal relationships as specified in the
> >        reltype parameter definition.
> >
> > Likewise here, it seems some more discussion is in order for the other
> > relationship types.
> >
> >        Changes to a calendar component referenced by this property can
> >        have an implicit impact on the related calendar component.  For
> >
> > Do we want to say anything about changes to a component referenced by this
> > property using any of the new relationship types?
> I've added a paragraph to explicitly mention the possibility of broken 
> links.
> >
> > Section 10
> >
> > Many thanks for referencing the URI security considerations and calling
> > out "reliability and consistency"!
> >
> > We might say that the security considerations of RFC 5545 continue to
> > apply.
> >
> > There are perhaps some privacy considerations if a user uses the new
> > CATEGORY or REFID functionality to expose information about a related
> > group of events, but it's a little hard to concoct a scenario where this
> > information gets to an attacker other than the calendar server, which is
> > already in something of a trusted position with respect to the user.
> >
> > Are there any considerations about the new linking and relation operators
> > exposing information to other users about calendar components that they're
> > not authorized to access?
> >
> > Very large "gap" parameters seem likely to lead to unexpected behavior.
> >
> > NITS
> >
> > Section 1.4
> >
> >     iCalendar component.  This new LINK property is closely aligned to
> >     the LINK header defined in [RFC8288]
> >
> > There are probably some pedantic distinctions that could be made here
> > relating to how RFC 8288 defines the generic concept of Web Linking (which
> > is not intrinsically tied to HTTP), as well as its expression in an HTTP
> > header *field*.
> 
> How about:
> 
> component. This new LINK property is closely aligned to
> RFC8288  which defines the generic concept
> of Web Linking as well as its expression in the HTTP LINK header
> field.

Looks good, thanks.

> > Also, please put a full stop at the end of the sentence.
> Done
> >
> >     The ATTACH property defined in [RFC5545] is being extended to handle
> >     server-side management and stripping of inline data.  [...]
> >
> > It's hard (at least on first read) to tell if this sentence is referring
> > to the RFC 8607 work or something being done by this document.
> ...is being extended in other specifications to handle
> >
> >                                                           Clients may
> >     choose to handle attachments differently from the LINK property as
> >     they are often an integral part of the message - for example, the
> >     agenda.
> >
> > Please clarify whether "they" refers to attachments of the LINK property.
> > The singular/plural signal implies it's "attachments" but we could
> > probably be more clear to the reader.
> >
> > Also, two hyphens for an em dash.
> replaced "they" with "attachments"
> >
> > Section 4
> >
> >     This section defines the usual temporal relationships for use with
> >
> > What's the context behind "usual"?  I don't remember (but may have missed)
> > a previous reference giving context for temporal relationships.
> 
> Maybe I should remove "the usual". Looking at things liek
> 
> https://project-management.info/pdm-precedence-diagramming-method/
> 
> these relationships are almost universal - but I don't know what could 
> be considered a standard. That organization does appear to create 
> standards but I don't know I can go much beyond saying "widely used".
> 
> >
> >     RELTYPE=FINISHTOFINISH:  Task-B can only be completed after Task-A is
> >        finished.  The related tasks may run in parallel before
> >        completion.
> >
> >        For example, if the goal is to prepare a meal, we start the
> >        potatoes, then the meat then the peas but they should all be
> >        cooked at the same time.
> >
> > This doesn't look like a great example for "finish-to-finish", as we
> > prefer all things to finish at the same time, rather than with a strict
> > ordering between end times.
> 
> In finish-to-finish we're trying to express that one task cannot be 
> completed until another task has completed. Both may run concurrently 
> but it's the end of both that matters. Perhaps this is a better example?
> 
> ------------ New --------------
> 
> For example, in the development of two related pieces of software, e.g. 
> the api and the implementation, the design of the implementation (B) 
> cannot be completed until the design of the api (A) has been completed.
> 
> -------------------------------

I like it better, at least.

> >
> > Section 6.1
> >
> >     Registration:  These relation types are registered in [RFC8288]
> >
> > I think we mean '''registered in the "Link Relation Types" registry
> > established by [RFC8288]'''.
> Yes
> >
> > Section 8.2
> >
> >     Property Parameters:  The VALUE parameter is required.  Non-standard,
> >        reference type or format type parameters can also be specified on
> >        this property.  The LABEL parameter is defined in [RFC7986]
> >
> > I'm not sure I see what in the ABNF would correspond to the "reference
> > type" parameters.  The closest seems to be the linkrelparam, but that's a
> > relation type, not a reference type.
> 
> I think it should be
> 
>     Property Parameters:  The VALUE parameter is required.
>           Non-standard, link relation type,
>           format type, label and language parameters can also be
>           specified on this property. The LABEL parameter
>           is defined in [RFC7986]

Ok, that does seem easier for me to make sense of.

Thanks again for all the good stuff here,

Ben

> >
> > Section 9.1
> >
> > Looking at the diff from RFC 5545, we should title case "Property Name"
> > and "Value Type".  We also have changed the order in which we list the
> > options for property parameters but that seems unimportant.
> OK
> >
> > Section 11.1
> >
> >     The following iCalendar property names have been added to the
> >     iCalendar Properties Registry defined in Section 8.3.2 of [RFC5545]
> >
> > Pedantically, RELATED-TO is not "added" but is rather covered by the "has
> > added a reference to this document where ... have been updated by this
> > document".  So if we were to keep this phrasing we might make two tables,
> > or we could try to fudge the wording here a bit.
> >
> >
> >
> > _______________________________________________
> > calsify mailing list
> > [email-masked]
> > https://www.ietf.org/mailman/listinfo/calsify

---

From: Michael Douglass <[email-masked]>
Date: Mon, 7 Mar 2022 15:36:53 -0500

Thanks Ben.

Your comments were very helpful.

I'll probably make at least one change along the lines suggested below 
but I'll wait till after the calext session

---

From: Francesca Palombini <[email-masked]>
Date: Thu, 17 Mar 2022 13:15:39 +0000

Indeed, thank you very much Ben for the thoughtful review.

Mike: I will mark this as “revised ID needed” while waiting for the last (final) update with this minor change, then when v-11 is posted I’ll send this forward to the RFC Editor.

Thanks for the good work!
Francesca

From: iesg <[email-masked]> on behalf of Michael Douglass <[email-masked]>
Date: Monday, 7 March 2022 at 21:40
To: Benjamin Kaduk <[email-masked]>, Michael Douglass <[email-masked]>
Cc: [email-masked] <[email-masked]>, The IESG <[email-masked]>, [email-masked] <[email-masked]>, [email-masked] <[email-masked]>
Subject: Re: [calsify] Benjamin Kaduk's Discuss on draft-ietf-calext-ical-relations-09: (with DISCUSS and COMMENT)
Thanks Ben.

On 3/7/22 14:38, Benjamin Kaduk wrote:
>> https://protect2.fireeye.com/v1/url?k=31323334-501d5122-313273af-454445555731-c6425350d8ccb11e&q=1&e=5275fae3-e0fe-41ff-b644-6d633dd1d924&u=https%3A%2F%2Fproject-management.info%2Fpdm-precedence-diagramming-method%2F
>>