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/

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./

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.

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./

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./

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./

Section 6

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

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