[Bug 5184] Editorial Changes - Guidelines

http://www.w3.org/Bugs/Public/show_bug.cgi?id=5184

           Summary: Editorial Changes - Guidelines
           Product: WS-Policy
           Version: LC
          Platform: PC
        OS/Version: Windows NT
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Guidelines
        AssignedTo: fsasaki@w3.org
        ReportedBy: asirveda@microsoft.com
         QAContact: public-ws-policy-qa@w3.org


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

Received on Saturday, 13 October 2007 02:24:11 UTC