NEW ISSUE (4074): [Guidelines] Collection of unclear Guidance or text issues

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

Title: [Guidelines] Collection of unclear Guidance or text issues

Description:

1.) Section 3.1.1 states:  "The WS-Policy Framework is based on a declarative model, meaning that it is incumbent on the WS-Policy authors to define both the semantics of the assertions as well as the scope of their target domain in their specification. The set of metadata for any particular domain will vary in the granularity of assertion specification required." [1]

It is not clear what it means to define the "scope of their target domain."

2.) Section 3.1.1 later quotes an unknown section from WS-SecurityPolicy (needs a reference) and prefaces the quote with: "An example of a domain specification that follows these practices is the WS-SecurityPolicy specification [WS-SecurityPolicy]. The WS-SecurityPolicy authors have defined their scope as follows:"

It is not clear what practice the quote is trying to demonstrate, though I think the is referring to an assertion author defining the "scope of their target domain"

3.) Section 4.4.2, 1st paragraph states: "The granularity of assertions is determined by the authors and it is recommended that care be taken when defining nested policies to ensure that the options provided appropriately specify policy alternatives within a specific behavior." [2]

It is not clear what it means to "define nested policies to ensure that the options provided appropriately specify policy alternatives within a specific behavior."

4.)  Section 4.7 states: "The current set of subjects as mapped to the WSDL 1.1 elements, can also constrain the assertion constructs. For Example, In WS-RM, the domain authors chose to support certain capabilities at the endpoint level. This resulted in the finer granularity of the assertion to apply at the message policy subject, but the assertion semantics also indicates that the if the senders choose to engage RM semantics (although not specified via attachment in WSDL at incoming messages), the providers will honor the engagement of RM. This is illustrative of how the assertion author can specify additional constraints and assumptions for attachment and engagement of behavior." [3]

It is not clear how "the current set of subjects as mapped to the WSDL 1.1 elements, can also constrain the assertion."  It's not clear how supporting RM policy at the endpoint "resulted in the finer granularity of the assertion to apply at the message policy subject."  It is not clear what "constraints and assumptions for attachment and engagement of behavior" an assertion author should specify.

5.) Section 6 states: "domain authors should be aware of the compositional semantics with other related domains. The protocol assertions that require composition with WS-Security should be particularly aware of the nesting requirements on top of transport level security."  [4]

It is not clear what Section 6 is recommending that policy assertion authors do.

Justification: The text in these sections does not provide clear guidance, which could result in confusion and misinterpretation.

Target: Guidelines for Policy Assertion Authors

Proposal:

1,2.) Replace "The WS-SecurityPolicy authors have defined their scope as follows:" with "The WS-SecurityPolicy authors have defined the scope of their target domain (security) as follows:"

3.) Remove or clarify the sentence

4.) Remove the section

5.) Remove or clarify the section.

[1] http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-guidelines.html?rev=1.11&content-type=text/html;%20charset=utf-8#domain-owners
[2] http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-guidelines.html?rev=1.11&content-type=text/html;%20charset=utf-8#nested-assertions
[3] http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-guidelines.html?rev=1.11&content-type=text/html;%20charset=utf-8#levels-of-abstraction
[4] http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-guidelines.html?rev=1.11&content-type=text/html;%20charset=utf-8#inter-policy