Subject: RE: [Simple] WGLC: draft-ietf-simple-event-list-01.txt

From: "Drage, Keith (Keith)" <[email-masked]>
Date: Tue, 15 Apr 2003 12:50:46 +0100

Some comments:

1)	The use of Supported and Require headers in this document goes beyond what I understand is specified elsewhere.

Section 3.1, 2nd paragraph seems to assume that this operation is conformant with other documents because it does not add extra normative requirements, but I could find no other document that required such behaviour. RFC 3261 specifies that the Require header MUST appear in a non 421 response to a request that contained a Supported header. RFC 3265 specifies no extension to these requirements, even though there is the added concept of the first NOTIFY request confirming the dialog.

Thus if I follow RFC 3261 then only the SUBSCRIBE response should contain a Require header containing "eventlist" and none of the NOTIFY requests should contain it. Is there any functionality that will be missed by not having the Require header in the first NOTIFY request sent to the SUBSCRIBE request? If we do need to put the Require header in the NOTIFY request, then we should identify a bug to RFC 3265, because the procedure should be described there.

2)	The document would benefit by having a definitions clause. Just going through the first few pages I consider that I would have inserted definitions for "resource list server", "resource", "list subscription", "back-end subscription". I am sure there are others.

3)	Section 3.3. What is the relationship of this paragraph to draft-ietf-simple-presence-10.txt section 6.5. Is it additional to that requirement, or does it replace that requirement.

4)	Section 3.4, 1st paragraph. What is the relative weight of "SHOULD" in the first line versus "RECOMMENDED" in the second line. Is one meant to be subservient to the other? Do you mean the second sentence to be "If authentication is applied, then the subscriber SHOULD use the ..." Additionally, for anything of SHOULD strength, it is good practice to include some description of the conditions under which the requirements is not expected to apply.

5)	Section 3.7. I assume that the RFC 3265 reference here is to section 4.4.9. As well as including a more precise reference, could I suggest the section is rephrased using the terminology of RFC 3265 section 4.4.9. Something along the lines of "Subscribers to the "presence" package MUST NOT install multiple subscriptions when the initial request is forked. If multiple responses are received, then they are handled as specified in RFC 3265 section 4.4.9."

However according to RFC 3265, this is meant to be specified for the event package, which is "presence"; if we look at draft-ietf-simple-presence-10.txt section 6.9 which defines that package, this restriction relating to forking already occurs, so that requirement does not need to be repeated here.

6)	Section 3.9, 3rd paragraph and section 6.1, 2nd paragraph. Reference [7] does not relate to network asserted identity. It is appropriate to make the reference, but the text needs to distinguish between the two forms of asserted identity.

7)	Many of the references are out of date, both in case of internet draft version, and in some cases where the reference has become an RFC. Reference [6] is RFC 3325.

8)	Section 4.2. Lots of paragraphs beginning "Note that..." I though the convention in RFC 3261 was to indent these paragraphs and treat them as lesser status. Note that I do not intend this comment to apply to section 5, which is all of this status.

9)	At least one of these "Note that..." paragraphs contains inappropriate text, i.e. section 4.2, 4th paragraph "Note that the first NOTIFY sent in a subscription MUST contain full state, as must the first NOTIFY sent after receipt of a SUBSCRIBE request for the subscription." As a reader, I cannot just note something that contains a MUST.

10)	Also for section 5, item 1, "Note that we must advertise support for application/rlmi+xml and multipart/related because we support the eventlist extension, and we must advertise application/cpim-pidf+xml because we are requesting a subscription to a list." it would be better if this sentence used a word other than "must" (2 instances) as this might be confused as a mandating statement, even though it is lower case.

11)	Section 4.3, 2nd paragraph. "This attribute must be present." Is this sentence necessary (or is it already effectively stated by the syntax), and if so should the "must" be uppercase?

12)	Section 4.4, 5th paragraph. Replace "must be" by "is".

13)	Section 5, 3rd paragraph. Replace "must consult" by "consults".

14)	Section 6.2. "Implementations MUST NOT attempt to perform this type of optimization unless adequate access to complete authorizaton policy can be guaranteed.  Note that this is a very difficult problem to solve correctly; even in the cases that such access is beleived possible, this mode of operation is NOT RECOMMENDED." The conditions in this sentence are not precise enough to justify the "MUST". Suggest some rework may be necessary - with keeping in mind "How do I test this?".

15)	Section 3.5, 5th paragraph. "If an instance of a resource was previously reported to the subscriber but is no longer available (i.e.  the virtual subscription to that instance has been terminated), the resource list server SHOULD include that resource instance in the meta-information in the first NOTIFY message sent to the subscriber following the instance's unavailability." For a requirement of SHOULD strength, it is good practice to include some informative material of the conditions under which the requirements is not expected to apply. Similarly for the 9th paragraph (same text?)

regards

Keith

Keith Drage
Lucent Technologies
Tel: +44 1793 776249
Email: [email-masked] 

> -----Original Message-----
> From: Robert Sparks [mailto:[email-masked]]
> Sent: 01 April 2003 17:26
> To: [email-masked]
> Subject: [Simple] WGLC: draft-ietf-simple-event-list-01.txt
> 
> 
> This is a SIMPLE working group Last Call for comments on
> the below draft. 
> 
> This WGLC ends April 15, 2003.
> 
> RjS
> SIMPLE co-chair
> 
> On Tue, 2003-04-01 at 05:49, [email-masked] wrote:
> > A New Internet-Draft is available from the on-line 
> Internet-Drafts directories.
> > This draft is a work item of the SIP for Instant Messaging 
> and Presence Leveraging Extensions Working Group of the IETF.
> > 
> > 	Title		: A Session Initiation Protocol (SIP) 
> Event Notification
> >                           Extension for Collections
> > 	Author(s)	: A. Roach, J. Rosenberg, B. Campbell
> > 	Filename	: draft-ietf-simple-event-list-01.txt
> > 	Pages		: 38
> > 	Date		: 2003-3-31
> > 	
> > This document presents an extension to the Session Initiation
> > Protocol (SIP)-Specific Event Notification mechanism for subscribing
> > to a homogenous collection of event packages.  Instead of the
> > subscriber sending a SUBSCRIBE for each resource individually, the
> > subscriber can subscribe to an entire collection, and then receive
> > notifications when the state of any of the resources in the
> > collection changes.
> > 
> > A URL for this Internet-Draft is:
> > 
> http://www.ietf.org/internet-drafts/draft-ietf-simple-event-li
st-01.txt
> 
> To remove yourself from the IETF Announcement list, send a message to 
> ietf-announce-request with the word unsubscribe in the body of the message.
> 
> Internet-Drafts are also available by anonymous FTP. Login with the username
> "anonymous" and a password of your e-mail address. After logging in,
> type "cd internet-drafts" and then
> 	"get draft-ietf-simple-event-list-01.txt".
> 
> A list of Internet-Drafts directories can be found in
> http://www.ietf.org/shadow.html
> or ftp://ftp.ietf.org/ietf/1shadow-sites.txt
> 
> 
> Internet-Drafts can also be obtained by e-mail.
> 
> Send a message to:
> 	[email-masked].
> In the body type:
> 	"FILE /internet-drafts/draft-ietf-simple-event-list-01.txt".
> 	
> NOTE:	The mail server at ietf.org can return the document in
> 	MIME-encoded form by using the "mpack" utility.  To use this
> 	feature, insert the command "ENCODING mime" before the "FILE"
> 	command.  To decode the response(s), you will need "munpack" or
> 	a MIME-compliant mail reader.  Different MIME-compliant mail readers
> 	exhibit different behavior, especially when dealing with
> 	"multipart" MIME messages (i.e. documents which have been split
> 	up into multiple messages), so check your local documentation on
> 	how to manipulate these messages.
> 		
> 		
> Below is the data which will enable a MIME compliant mail reader
> implementation to automatically retrieve the ASCII version of the
> Internet-Draft.
> 

_______________________________________________
Simple mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/simple
_______________________________________________
Simple mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/simple

---

From: Adam Roach <[email-masked]>
Date: Wed, 23 Apr 2003 21:33:06 -0500

> From: Drage, Keith (Keith) [mailto:[email-masked]]
> Sent: Tuesday, April 15, 2003 6:51
> To: [email-masked]
> Subject: RE: [Simple] WGLC: draft-ietf-simple-event-list-01.txt
> 
> 
> Some comments:
> 
> 1)	The use of Supported and Require headers in this 
> document goes beyond what I understand is specified elsewhere.
> 
> Section 3.1, 2nd paragraph seems to assume that this 
> operation is conformant with other documents because it does 
> not add extra normative requirements, but I could find no 
> other document that required such behaviour. RFC 3261 
> specifies that the Require header MUST appear in a non 421 
> response to a request that contained a Supported header. RFC 
> 3265 specifies no extension to these requirements, even 
> though there is the added concept of the first NOTIFY request 
> confirming the dialog.
> 
> Thus if I follow RFC 3261 then only the SUBSCRIBE response 
> should contain a Require header containing "eventlist" and 
> none of the NOTIFY requests should contain it. Is there any 
> functionality that will be missed by not having the Require 
> header in the first NOTIFY request sent to the SUBSCRIBE 
> request? If we do need to put the Require header in the 
> NOTIFY request, then we should identify a bug to RFC 3265, 
> because the procedure should be described there.

I've added the following paragraph to the document
to stem the confusion that you describe:

  Use of "Require: eventlist" in NOTIFY messages
  is applied by the notifier to satisfy the RFC3261
  requirement that a UAC MUST insert a Require header
  field into a request if the UAC wishes to insist
  that a UAS understand an extension in order to
  process the request. Because the NOTIFY would not
  be usable without applying the eventlist option,
  the notifier is obligated to include it.

> 2)	The document would benefit by having a definitions 
> clause. Just going through the first few pages I consider 
> that I would have inserted definitions for "resource list 
> server", "resource", "list subscription", "back-end 
> subscription". I am sure there are others.

I have added definitions for these terms and several others.

> 3)	Section 3.3. What is the relationship of this paragraph 
> to draft-ietf-simple-presence-10.txt section 6.5. Is it 
> additional to that requirement, or does it replace that requirement.

I've clarified this by modifying the paragraph:

   An implementation compliant to this specification MUST support the
   multipart/related and application/rlmi+xml MIME types.  These types
   MUST be included in an Accept header sent in SUBSCRIBE message, in
   addition to any other types supported by the client (including
   any types required by the event package being used).

> 4)	Section 3.4, 1st paragraph. What is the relative weight 
> of "SHOULD" in the first line versus "RECOMMENDED" in the 
> second line. Is one meant to be subservient to the other? Do 
> you mean the second sentence to be "If authentication is 
> applied, then the subscriber SHOULD use the ..." 

I've removed this paragraph altogether, as it is only
repeating provisions already specified in RFC 3265.

> 5)	Section 3.7. I assume that the RFC 3265 reference here 
> is to section 4.4.9. As well as including a more precise 
> reference, could I suggest the section is rephrased using the 
> terminology of RFC 3265 section 4.4.9. Something along the 
> lines of "Subscribers to the "presence" package MUST NOT 
> install multiple subscriptions when the initial request is 
> forked. If multiple responses are received, then they are 
> handled as specified in RFC 3265 section 4.4.9."

I've updated the document to use your phrasing.

> However according to RFC 3265, this is meant to be specified 
> for the event package, which is "presence"; if we look at 
> draft-ietf-simple-presence-10.txt section 6.9 which defines 
> that package, this restriction relating to forking already 
> occurs, so that requirement does not need to be repeated here.

The event lists extension applies to more than just presence.

> 6)	Section 3.9, 3rd paragraph and section 6.1, 2nd 
> paragraph. Reference [7] does not relate to network asserted 
> identity. It is appropriate to make the reference, but the 
> text needs to distinguish between the two forms of asserted identity.

Section 3.9 has been removed.

> 7)	Many of the references are out of date, both in case of 
> internet draft version, and in some cases where the reference 
> has become an RFC. Reference [6] is RFC 3325.

Thanks. I'll update the reference section.

> 8)	Section 4.2. Lots of paragraphs beginning "Note 
> that..." I though the convention in RFC 3261 was to indent 
> these paragraphs and treat them as lesser status. Note that I 
> do not intend this comment to apply to section 5, which is 
> all of this status.

I've gone through the document, and removed "Note that..." from
all normative sections except for informative, explanatory
text. I've indented such text as you suggest.

> 9)	At least one of these "Note that..." paragraphs 
> contains inappropriate text, i.e. section 4.2, 4th paragraph 
> "Note that the first NOTIFY sent in a subscription MUST 
> contain full state, as must the first NOTIFY sent after 
> receipt of a SUBSCRIBE request for the subscription." As a 
> reader, I cannot just note something that contains a MUST.

As above.

> 10)	Also for section 5, item 1, "Note that we must 
> advertise support for application/rlmi+xml and 
> multipart/related because we support the eventlist extension, 
> and we must advertise application/cpim-pidf+xml because we 
> are requesting a subscription to a list." it would be better 
> if this sentence used a word other than "must" (2 instances) 
> as this might be confused as a mandating statement, even 
> though it is lower case.

I mean the plain English word "must". We can't
allow RFC 2119 to complely hijack these terms; doing so
would make writing clear prose nearly impossible.

> 11)	Section 4.3, 2nd paragraph. "This attribute must be 
> present." Is this sentence necessary (or is it already 
> effectively stated by the syntax), and if so should the 
> "must" be uppercase?

I've made it normative. I think that expressing it in
syntax and reinforcing it in description leaves less
room for misinterpretation than specifying it in only
one place.

> 12)	Section 4.4, 5th paragraph. Replace "must be" by "is".

Using the same logic as above, replaces with "MUST be".

> 13)	Section 5, 3rd paragraph. Replace "must consult" by "consults".

Same response as to (10), above.

> 14)	Section 6.2. "Implementations MUST NOT attempt to 
> perform this type of optimization unless adequate access to 
> complete authorizaton policy can be guaranteed.  Note that 
> this is a very difficult problem to solve correctly; even in 
> the cases that such access is beleived possible, this mode of 
> operation is NOT RECOMMENDED." The conditions in this 
> sentence are not precise enough to justify the "MUST". 
> Suggest some rework may be necessary - with keeping in mind 
> "How do I test this?".

Without arguing about whether requirements need to be
black-box testable, I assert that the particular
phrase you object to is quite testable. User A subscribes
to a list that contains a list of resources. An element (x)
of this this requires a back-end subscription to retrieve
its state. Policy on the notifier servicing this back-end
subscription provides state (m) for User A, and state
(n) for user B. Verify that User A receives state (m) for
element (x). After User A has established a subscription,
User B subscribes to a list that contains element (x).
Verify that user B receives state (n) for element (x).

> 15)	Section 3.5, 5th paragraph. "If an instance of a 
> resource was previously reported to the subscriber but is no 
> longer available (i.e.  the virtual subscription to that 
> instance has been terminated), the resource list server 
> SHOULD include that resource instance in the meta-information 
> in the first NOTIFY message sent to the subscriber following 
> the instance's unavailability." For a requirement of SHOULD 
> strength, it is good practice to include some informative 
> material of the conditions under which the requirements is 
> not expected to apply. Similarly for the 9th paragraph (same text?)

Not the same text; paragraph 5 talks about removing a resource
from a list. Paragraph 9 talks about NOTIFY messages sent
upon receipt of SUBSCRIBE.

In both cases, violation of the "SHOULD" strength clause
would typically be due to design tradeoffs that are extremely
specific to the implementation. Outlining such scenarios would
require substantial quantities of text that would really add
nothing of use to the document.

Thanks for your review of the document.

/a

---

From: Michael Hammer <[email-masked]>
Date: Mon, 28 Apr 2003 16:10:31 -0400

Adam,

RFC 2119 is attempting to add strength and remove ambiguity to the
existing plain English word.  I find it confusing when
"must" doesn't always mean "must".  That is to
Clintonesque for me.  There usually are alternative words that could
be used to distinguish a statement to be non-normative:

must   -> needs to

should -> ought to

may    -> might

Otherwise, I am always left wondering if a MUST was inadvertently left as
must.  Without consistent usage of words, writing clear requirements
documents is nearly impossible.

Mike

At 09:33 PM 4/23/2003 -0500, Adam Roach wrote:

I mean the plain English word
"must". We can't

would make writing clear prose nearly
impossible.

---

From: Adam Roach <[email-masked]>
Date: Mon, 28 Apr 2003 23:30:33 -0500

-----Original Message-----
From: Michael Hammer [mailto:[email-masked]]

> RFC 2119 is attempting to add strength and remove ambiguity
> to the existing plain English word.  I find it confusing when
> "must" doesn't always mean "must".  That is to Clintonesque for me.
...
> Otherwise, I am always left wondering if a MUST was inadvertently
> left as must.  Without consistent usage of words, writing clear
> requirements documents is nearly impossible.

Okay, well, the hints for this case are:

a) The section under discussion is an example, and
b) The section has a rather rambling disclaimer
   pointing out in unambiguous terms that it, in its
   entirety, is completely non-normative.

Further, the statement under discussion is taking
a normative statement of the form "A MUST do Y",
and substituting the values from the example scenario
into A and Y. Even if it is interpreted by someone
who can't pick up on the treble-clue of "this is
lowercase," "this is in an example," and "this section
is clearly marked as non-normative," there is no harm
to be done, as it merely restates a normative clause
from elsewhere in the document.

/a