Re: New Issue: 5184 Editorial Changes - Guidelines

Comments inline.





Asir Vedamuthu <asirveda@microsoft.com> 
Sent by: public-ws-policy-request@w3.org
10/12/2007 10:31 PM

To
"public-ws-policy@w3.org" <public-ws-policy@w3.org>
cc

Subject
New Issue: 5184 Editorial Changes - Guidelines







These are editorial comments on the Guidelines document at 
http://www.w3.org/TR/2007/WD-ws-policy-guidelines-20070928/

Section 3

a) s/An assertion is a piece of metadata that describes a capability 
related to a specific WS-Policy domain/An assertion is a piece of metadata 
that describes a capability related to a specific domain/


<mh> I don't agree. We are not defining "general assertions" for any 
domain, we are defining WS-Policy Assertions which releate to domains that 
have chosed to express their capabilities via the WS-Policy expressions.
</mh>


Section 4.1.1

b) s/When using the WS-Policy Framework, any Assertion Authors defining 
new WS-Policy assertions must adhere to the MUST's and SHOULD's in the 
specification and should review the conformance section of the 
specification./Assertion authors should review the conformance sections of 
the WS-Policy Framework and Attachment specifications and an assertion 
must adhere to all the constraints contained in the Framework and 
Attachment specifications./

Section 5.3

c) s/The examples given in this document reference WS-Policy like 
WS-SecurityPolicy and WS-RM Policy./The examples given in this document 
are based on existing assertions such as WS-SecurityPolicy and WS-RM 
Policy./

Section 5.3.1

d) s/This indicates that there is a relationship between the 
assertions./This indicates a consistent set of behaviors./

<mh>  I disagree.  I think "relationship" is the right word.</mh>


Section 5.3.2

e) s/"To give an example, the WS-ReliableMessaging Policy document 
specifies attribute extensibility as part of the XML definition, allowing 
the wsp:Ignorable attribute:
Example 5-5. WS-ReliableMessaging Policy use of attribute extensibility
/wsrmp:RMAssertion/@{any}
This is an extensibility mechanism to allow different {extensible} types 
of information, based on a schema, to be passed."//

The RM policy assertion manifests on the wire, is relevant to 
compatibility assessment and cannot be ignored by a requester. 
Illustrating the use of ignorable marker on the RM policy assertion is 
incorrect.


<mh> I thought the idea was to follow the other guidelines documents which 
specifically say "an example". I'm confused by this alternative. It's much 
more obtuse.  what is this last sentence? </mh>






Section 5.3.3

f) s/Define message format only/Assertions should not describe message 
semantics/

Section 5.7.1

g) s/If there are multiple instances of a policy assertion type in the 
same policy alternative without parameters and nested policies, these have 
the same meaning as a single assertion of the type within the policy 
alternative./If policy assertion authors did not specify the semantics of 
repetition of policy assertions of a type that allows neither parameters 
nor nested policy expressions within a policy alternative, then repetition 
is simply redundancy, and multiple assertions of the assertion type within 
a policy alternative have the same meaning as a single assertion of the 
type within the policy alternative./


<mh> I disagree, the alternative is confusing 



h) s/That identification will facilitate the deployment of their policy 
assertions and include such information in the assertion definition./That 
identification will facilitate the deployment of their policy assertions./

i) s/Assertion Authors should specify the set of relevant WSDL policy 
subjects with which the assertion may be associated. For instance, if a 
policy assertion is to be used with a WSDL policy subject - such as 
service, endpoint, operation and message it should be stated./Assertion 
Authors should specify the set of relevant WSDL policy subjects with which 
the assertion may be associated./


<mh> Again, I thought the entire purpose of taking on the template for 
guidance was to include examples. Now you seem to want to remove them, 
why?



j) s/However such policy attachments to WSDL policy subjects of broader 
scope and granularity should be done only after careful evaluation./The 
best practice is to choose the most granular WSDL policy subject to which 
the behavior represented by a policy assertion applies./

k) s/If the capability may imply different semantics with respect to 
attachment points, the Assertion Authors should consider the following:
Decompose the semantics with several assertions.
Rewrite a single assertion targeting a specific subject./If the behavior 
indicated by an assertion varies when attached to different policy 
subjects, Assertion Authors should consider decomposing the assertion into 
multiple assertions and associate them to multiple subjects./

        <mh> I think this is fine the way it is.

Section 6

l) s/Assertion Extensibility/Assertion authors should allow for 
extensibility (see best practice 5. Start with a Simple Assertion)/

        <mh> I don't see this in section 6

m) s/Supporting New Policy Subjects/Supporting New Policy Subjects (see 
Section 6.3 Supporting New Policy Subjects)/

Section 6.1

n) s/The contents of the parameter are static and allow reuse in different 
security scenarios./The contents of the parameter are static and may be 
reused in different security scenarios using other referencing mechanisms 
(these are outside the scope of the WS-Policy Framework)./

Regards,

Asir S Vedamuthu
Microsoft Corporation