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