- From: Frederick Hirsch <frederick.hirsch@nokia.com>
- Date: Thu, 5 Oct 2006 10:39:33 -0400
- To: public-ws-policy@w3.org
- Cc: Hirsch Frederick <frederick.hirsch@nokia.com>
Comment on Guidelines Document Web Services Policy 1.5 - Assertion Authors Guideline for WS-Policy Editors' copy $Date: 2006/10/05 06:27:08 $ @@ @@@@ @@@@ <http://tinyurl.com/gxrh3> or <http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy- assertion-guidelines.html?content-type=text/html;charset=utf-8> Comments on Content 1) Add wsp:Policy elements to Example 8.4 CompanyAProfileB (fully expanded), and also example 8.6 - wsp:Policy element required as child of sp:TransportBinding and parent of sp:TransportToken, since sp:TransportToken is an assertion. 2) Is this statement at end of section 4 true? "For example, when multiple alternatives are present in a policy (designated by multiple wsp:exactlyOne, the compact form can not be used." A compact form policy can imply multiple alternatives through the use of wsp:Optional. ExactlyOne can also be used in compact form, as noted in 4.3 of Framework. 3) Section 5 states "The model is an opt-in model". Not sure this really makes sense or should be stated here. Isn't opt- in generally used with regards to privacy? Is there such a thing as an opt-out policy description? Suggest removing this sentence. 4) Add guidance as to when and why to use parameters versus nested assertions. I think it would make the document flow better and be clearer if section 5.4 "Assertions with Parameters" were to be combined with 5.5 "Comparison of Nested and Parametrized Assertions" and placed before 5.3 "Nested Assertions". This could answer the question of when to use parameters versus nested assertions before getting into the details of nested assertions. 5) Add description and guidance related to policy and SOAP intermediary processing, before section 5.6 Self Describing Messages Editorial comments 1) There still seem to be a spurious characters in document, perhaps formatting statements that were not processed. For example in last sentence of section 2 "�cookbook� ", and "don�t" (2 times), and in examples 8.2 ("<sp:TransportBinding>�</spTransportBinding>"), 8.3 ("�"), 8.5 (" �`") and 8.6 (" �" and "��.."�"). 2) Pretty-print (indent) all xml for readability 3) section 1 replace " The focus of this document is to capture best practices and usage patterns for practitioners to follow as well as provide guidance to achieve the best possible result. It is a complementary guide to using the specifications and is intended to provide non-normative descriptions to supplement the specification text. This document is intended for use by: " with "The focus of these guidelines is to capture best practices and usage patterns for practitioners to follow. It is a complementary guide to the Framework and Attachments specifications and primer. It is intended to provide non-normative guidelines for:" 4) End of section 2 remove: "This document, then can also be considered a �cookbook� of techniques and guidelines for the use of the framework. You don�t have to follow the recipe, but you may not end up with the same result if you don�t." 5) Section 2.1, not past tense: s/knowledge, it needed to/knowledge, it is necessary to/ s/could/can/ 6) 2.1.1 s/consistenly/consistently/ 7) in 2.1.2 replace "In the degenerative case, a human could be capable of reading the xml expression and could determine whether or not it was capable of constructing a message that the service advertised." with "In the degenerate case, a human could read the xml and determine if a message could be constructed conformant to the advertised policy." 8) 2.1.3 s/can reflect its on the wire/can specify its on-the-wire/ 9) 3.1 5th paragraph s/ (i.e.different alternatives)/(e.g. with different alternatives)/ 10) 3.1 first bullet s/context or does the/context or is the/ 11) 3.1 second bullet s/Determination of the assertions subject is helpful/Determination of the subject of an assertion is helpful/ 12) 3.1 third bullet s/how does// s/\?// 13) in 5.2 last paragraph, start with simpler one, add "also", replace "Domain authors are encouraged to look at WS-SecurityPolicy [ADD REFERENCE HERE doc references] to see an example of a complex domain that has been decomposed into a set of policy expressions. New aurthors are encouraged to look at WS-ReliableMessaging Policy to see an example of a simple domain that has only defined 2 assertions." with "New aurthors are encouraged to look at WS-ReliableMessaging Policy to see an example of a simple domain that has only defined 2 assertions. Domain authors are also encouraged to look at WS- SecurityPolicy [ADD REFERENCE HERE doc references] to see an example of a complex domain that has been decomposed into a set of policy expressions. " 14) 5.3 3rd paragraph s/what algorithm suite/the algorithm suite/ 15) 5.4 1st bullet s/which can not/that cannot/ 16) 5.6 put last paragraph first removing "REWRITEAs a result,". This last paragraph is the main concept. Tighten earlier material. regards, Frederick Frederick Hirsch Nokia On Oct 5, 2006, at 2:30 AM, ext Felix Sasaki wrote: > > Hi all, > > I did my action item 125 "Felix to Input Guidelines doc in CVS". > > Please have a look at http://tinyurl.com/gxrh3 or > http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy- > assertion-guidelines.html?content-type=text/html;charset=utf-8 > . > > For the editors: the build.xml is updated respectively. > > Felix >
Received on Thursday, 5 October 2006 14:39:50 UTC