[Nmc-wg] Clarifications on the base-doc

[Jason Zurawski]

Hi Inder/All;


> These were my comments on the base document. I am still new to perfSONAR
> suite of services, so would love to get educated as well through the
> responses. I volunteer to fix the nits on SVN if you agree they are
> valid comments :).


In general I would like to see more people editing the document (or at 
least inserting the comments directly into the tex source).  To date 
this has been a side project of my own that needs to be transitioned to 
the entire WG.  I have updated the TODO list to include some of your 
concerns, and have some other comments are inline:


> 1. It seems odd to have requirements specific MUST, SHOULD in a
> preliminary example. It would be great to consolidate the requirements
> either in Sections 4.3/4.4 or message structure protocol requirements
> before the example in Section 4.1.


Freek (and now you! :)) can work through the document and correct the 
use of RFC 2119 words.  As I have stated before, I used these with a 
heavy hand initially and did not pay must attention to the use in many 
areas.  Editors with experience in writing these types of documents like 
yourself will be very valuable to correct these mistakes.


> 2. In Section 4.1, page 7
> a. I understand the concept behind "rejected outright" but it will good
> to elaborate what that means like " message is discarded and an response
> sent with a corresponding error message".
> b. In my understanding "Note this message is similar to the response in
> many ways" - the word response should actually be "request"?


I have corrected 'b', good eye.  I added a comment in the document about 
'a' so we don't forget this.  I believe there is a standard 'message 
type is not accepted' result code which will be described in the result 
code section, but we can soften the text in this case.


> 3. In section 4.3.2.2, it seems that different services can react
> radically differently to the presence of objects in an API. I do not
> think it is wise for some services to view inclusion of this element as
> an "error". For optional elements, if a service that does not expect
> those elements and they are not mandatory, it should ignore it, as long
> as the overall request makes sense. Is there a particular case where
> inclusion of this element should generate an error?


I believe this comment can be addressed in Jeff's suggestion from last 
week, and something that I have added to the agenda for this week.  A 
protocol that is implemented in software can't be very 'open', as it 
makes the design of clients, services, and the specification of said 
protocol hell.  Locking things down, e.g. being extremely specific about 
what may go where even though the current generation of tools may not 
speak the language currently, may make the job easier and the resulting 
software much better.

We can talk about all of this on the call, but to directly address your 
comment: the wording on this is poor.  Services *should* (I am speaking 
only on the knowledge of services I have worked on - others can comment 
further) currently treat the message parameters section as an ignorable 
chunk if they are not expecting it.  To ensure future compatibility we 
should explicitly mark this as an optional element and avoid errors.


> 4. It is mentioned many times that /id/ *may* be used to track state
> between messages and services. The examples in the doc do illustrate how
> request/response and /metadataidref/ use the /id/ to do chaining. What
> is unclear is what other state can be tracked with "id"'s? An example
> would be great here.


I have noted that we need to define the rules regarding the scope and 
statefullness of IDs in the TODO.  The NM-WG document 
(https://forge.gridforum.org/sf/go/doc15649?nav=1) at one time had a 
very large section devoted to Ids but I can't seem to locate it in my 
very quick read.


> 5. Section 5.1, it seems like incorrect bold/highlighting of should,
> shall etc. I think Freek volunteered to fix it...but I could take a shot
> there as well.
>
> 6. Section 5.1.2 - The first line "When we are faced with like elements
> that MAY NOT share a common namespace, we SHOULD NOT combine." I am
> unclear what it means, would the meaning the sentence means to convey
> stay the say if I rephrased it as
> "When we are faced with like elements that do not share a common
> namespace, we SHOULD NOT combine". In the current instantiation within
> the document, it seems to indicate that if there are like elements that
> share a common namespace, there may be reasons not to combine. If there
> are exceptions like these, we should highlight what cases might those
> be.....
>
> 7. I am still trying to wrap my head around all the nuances of chaining,
> though the base concepts are simple. The confusion is especially around
> the descriptions of the three approaches "safe and stupid, dangerous yet
> intelligent and slow and steady". Should these three approaches be
> broken into their own sub-sections for better readability?


Chaining is giving lots of people headaches.  As a part of the 'locking 
down' discussion we will decide how to narrow the scope here.  After 
reading the comments from others, I think the 3 examples I originally 
gave do not belong here and should be in NM-WG.  We should devote the 
space on chaining to giving exact examples instead of possibilities 
(merge chaining + explicit filter chaining examples).

Thanks for your comments Inder;

-jason