RE: proposal for AI 259- bug 3978 with diff

> Proposal c) change Guidelines-Section 5 to:

Thank you for the Primer diff. I think it would help if there is a diff version to highlight the proposed changes to the Guidelines document.

Regards,

Asir S Vedamuthu
Microsoft Corporation


From: public-ws-policy-request@w3.org [mailto:public-ws-policy-request@w3.org] On Behalf Of Maryann Hondo
Sent: Thursday, March 29, 2007 12:08 PM
To: public-ws-policy@w3.org
Subject: Fw: proposal for AI 259- bug 3978 with diff


as per request...diff of text changes for proposal a.....note, the docs have been changed to
rename section 3.10 to 4 in a different editorial action item, so the changes appear as changes to section 4 as
opposed to section 3.10 in the text below
.

Maryann
----- Forwarded by Maryann Hondo/Austin/IBM on 03/29/2007 03:00 PM -----
Maryann Hondo/Austin/IBM

03/23/2007 11:39 AM

To

public-ws-policy@w3.org

cc

Subject

Re: proposal for AI 259- bug 3978






>From the Bug-

Description: Section 7 in the Guidelines document currently discusses
guidelines for authoring new policy attachment mechanisms [1].  These
guidelines are not relevant to policy assertion authors.  Does the working
group plan on providing guidance on creating new policy attachment mechanisms?
If no, then this section should be removed.  If yes, then this section needs to
be reviewed for completeness.


Description: There is some information in the Primer on Versioning of the Policy Language ( which includes Policy Attachment)
but it is unclear whether the Primer is the right place for this ( see the Note below) and in addition there are many places in this text where a "best practice" is cited which should be in the Guidelines (which is probably what motivated this bug, since the information currently in the guidelines did not duplicate the text that was already in the Primer) or potentially some other document (see proposal below). Also there is text in here that is not targetted to policy expression authors who is the targetted audience for the Primer.  So, for completeness and consistency, several coordinated changes across documents may be necessary.

Proposal:
This proposal has 4 parts:
a) Split the existing text in section 3.10 into examples that are targetted for a policy expression author [detailed proposal below]
b) create additional "negative" test cases to reflect these examples given in the primer in section 3.10
c) Take existing text that describes best practices related to authoring assertions into Section 7 of the Guidelines document.[detailed proposal below]
d) Create  a working group note from the rest of the text in section 3.10 that deals with the versioning of the policy framework and the policy attachment mechanisms  to document this information for input into future working group activities.

Related issue:
There is already work [resolution for 4300 taken at the F2F] for splitting section 3.10 into a new section, section 4 and the proposal below may be affected by that change.

Proposal a) change Primer  section 3.10 title to be "Policy Expressions and the impact of WS-Policy Language extensibility"

change text in section 3.10.1 to:

WS-Policy Framework 1.5 specifies that any child element that is not known inside a Policy, ExactlyOne or All will be treated as a policy assertion. The WS-Policy Framework 1.5 also specifies that omitting the optional attribute is semantically equivalent to including it with a value of false. Attempts to extend the WS-Policy Framkework may therefore be interpreted as new policy assertions with an optional attribute with a value of false. After normalization, such elements will appear as assertions within an ExactlyOne/All operator.

Let us show an example with a hypothetical new "operator" that is a Choice element with a minOccurs and a maxOccurs attributes, ala XSD:Choice, in a new namespace. We use the wsp16 prefix to indicate a hypothetical namespace for a new policy language, 1.6 that is intended to be compatible with the Policy Language 1.5[reference to the spec]. This Policy expression in Example 3-14 contains both assertions that conform to the spec[sp:TransportBinding] and a  new "1.6" element [wsp16:Choice].

Example 3-14.

<wsp:Policy>
 <wsp:ExactlyOne>
   <wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
           </wsp16:Choice>
   <wsp:All>
           <sp:TransportBinding>...</sp:TransportBinding>
   </wsp:All>
 </wsp:ExactlyOne>
</wsp:Policy>

The normalization algorithm [step 3b] would interpret the "wsp16:Choice" element as an assertion, yielding the following  policy expression:
Example 3-15. Normalized Policy Expression from example 3-14
<wsp:Policy>
 <wsp:ExactlyOne>
   <wsp:All>
             <wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
             </wsp16:Choice>
   </wsp:All>
   <wsp:All>
           <sp:TransportBinding>...</sp:TransportBinding>
   </wsp:All>
 </wsp:ExactlyOne>
</wsp:Policy>

This normalization process yields two assertions. Intersection  between two policy expressions would need to have a wsp16:Choice assertion in at least one alternative in each policy expression to succeed.

If the policy expression were to contain the optional attribute,  the normalization algorithm [step 3b] would interpret the "wsp16:Choice" element as an optional assertion, yielding the following  policy expression:

Example 3-16.  Policy Expression from example 3-14 with an optional atttribute
<wsp:Policy>
 <wsp:ExactlyOne>
   <wsp:All>
             <wsp16:Choice wsp:Optional="true"
                        wsp16:minOccurs="1" wsp16:maxOccurs="2">
             </wsp16:Choice>
   </wsp:All>
   <wsp:All>
           <sp:TransportBinding>...</sp:TransportBinding>
   </wsp:All>
 </wsp:ExactlyOne>
</wsp:Policy>

This normalization process now yields two alternatives.
Example 3-17.  Policy Expression from example 3-16  normalized
<wsp:Policy>
 <wsp:ExactlyOne>
   <wsp:All>
             <wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
             </wsp16:Choice>
           <sp:TransportBinding>...</sp:TransportBinding>
   </wsp:All>
   <wsp:All>
           <sp:TransportBinding>...</sp:TransportBinding>
   </wsp:All>
 </wsp:ExactlyOne>
</wsp:Policy>

Because the "wsp16:Choice" element becomes an assertion in the policy expression any semantics of an "operator" isn't understood by the framework. Policy intersection based on any semantics indicated by the "wsp16" namespace, may be more difficult with such extensions. For example, the previous example will  appear to have a new assertion, a "wsp16:Choice" assertion. There is an alternative that does not have the wsp16:Choice, so requestors with implementations of the Policy Framework that implemented the intersection defined in the specification, would yield one result, which would be to select the alternative without the "wsp16:Choice" assertion.  For a requestor that was aware of the extension to intersect with the "wsp16:Choice" element would require  domain specific processing to override the intersection algorithm defined in the specification.

Given the extensibility of the Web Services Policy 1.5 schema, it is possibleto add new element names to the existing namespace but these elements are also treated as assertions as indicated in the examples above.

Example 3-18. Policy containing current wsp elements and new elements(Choice) in the wsp: namespace
<wsp:Policy>
 <wsp:ExactlyOne>
   <wsp:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
     ...
   </wsp:Choice>
   <wsp:All>
      ...
   </wsp:All>
 </wsp:ExactlyOne>
</wsp:Policy>

Proposal b) add these examples to negative tests:
note: running these examples through our policy engine did not produce the same results as are documented in the current text....would be good to get the group to agree to what is the right output from these operations.

<wsp:Policy>
 <wsp:ExactlyOne>
   <wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
           </wsp16:Choice>
   <wsp:All>
           <sp:TransportBinding>...</sp:TransportBinding>
   </wsp:All>
 </wsp:ExactlyOne>
</wsp:Policy>



<wsp:Policy>
 <wsp:ExactlyOne>
   <wsp:All>
             <wsp16:Choice wsp:Optional="true"
                        wsp16:minOccurs="1" wsp16:maxOccurs="2">
             </wsp16:Choice>
   </wsp:All>
   <wsp:All>
           <sp:TransportBinding>...</sp:TransportBinding>
   </wsp:All>
 </wsp:ExactlyOne>
</wsp:Policy>
Proposal c) change Guidelines-Section 5 to:

5.   Versioning and extensibility considerations
Assertion Authors need to consider not just the current expression of the requirements but how they anticipate and enable  new assertions  and new policy subjects being added. There are several aspects to versioning and extensibility that may impact policy assetion authors:

 *   Assertion Extensibility
 *   Policy Expression Extensibility
 *   Policy Language/Attachments Extensibility
See the Policy Note [give reference to new doc]

 *   Supporting New Policy Subjects

5.1  Assertion Extensibility
 A policy assertion represents a requirement, capability or property of a behavior. Policy assertions have a type, which implies a schema for the assertion and assertion-specific semantics.  These assertions are then represented as a policy expression which is the XML Infoset representation either in compact or normal form.

The schema for a policy assertion may change over time. Authors of any schema should be aware of best practices- seehttp://www.w3.org/XML/2005/xsd-versioning-use-cases/

5.1.1  Assertion Versioning and Compatibility
Over time, there may be multiple equivalent behaviors emerging in the Web Service interaction space. Examples of such multiple equivalent behaviors are WSS: SOAP Message Security 1.0 vs. 1.1 and WS-Addressing August 2004 version vs. WS-Addressing W3C Recommendation [WS-Addressing Core<http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-guidelines.html?content-type=text/html;%20charset=utf-8#WS-Addressing>]. These equivalent behaviors can be mutually exclusive for an interaction. When equivalent behaviors exist they can be modeled as independent assertions. The policy expression in the example below requires the use of WSS: SOAP Message Security 1.0.
Example 5-1. Message-level Security and WSS: SOAP Message Security 1.0
<Policy>
 <sp:Wss10>...</sp:Wss10>
</Policy>
The policy expression in the example below requires the use of WSS: SOAP Message Security 1.1. These are multiple equivalent behaviors and are represented using distinct policy assertions.
Example 5-2. Message-level Security and WSS: SOAP Message Security 1.1
<Policy>
 <sp:Wss11>...</sp:Wss11>
</Policy>

Best practice: use independent assertions for modeling multiple equivalent behaviors

5.2 Policy expression Versioning
The Primer document contains examples of  the versioning of policy expressions. Assertion authors should consider the patterns in the primer and take into consideration the examples and best practices to ensure that assertions they define can be utilized in policy expressions.

5.2.1 Utilizing References

The Web Services Policy Primer<http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-guidelines.html?content-type=text/html;%20charset=utf-8#WS-Policy-Primer> illustrates how providers can utilize the identification mechanism defined in the Policy specification to expose a complex policy expression as a reusable building block for other policy expressions by reference. Reuse may also be useful for domain assertion authors, especially those defining complex assertions utilizing references to policy expressions by nesting. Statically available parameterized content may also be reused by different assertions. However, such referencing mechanism is outside the scope of WS-Policy naming and referencing framework and other mechanisms could be used. As an example, in Web Services Policy Primer<http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-guidelines.html?content-type=text/html;%20charset=utf-8#WS-Policy-Primer> Section 4.2, the sp:issuedToken assertion utilizes the sp:RequestSecurityTokenTemplate parameter that contains necessary information to request a security token. The contents of the parameter are static and allows reuse in different security scenerios.
 5.2.2 Preserving Context-Free Policies
Policy attachment should not affect the interpretation of Policy alternatives. If it did, each policy assertion would need to be written with different (and possibly unknown) attachment mechanisms in mind.

Best Practice: Policy assertion authors should define assertions that are attachment agnostic.  Policy subjects should be identified by policy authors.

5.3 Policy Framework and Attachments Extensibility

Best Practice: Policy assertion authors should utilize the framework and attachments provided whenever possible.
Best Practice: If they need to extend the framework or attachments provided, Policy assertions authors should read the Note on extensibility and utilize only the extensibility points provided by the framework and attachments.

5.4 Supporting New Policy Subjects

Section 2<http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-guidelines.html?content-type=text/html;%20charset=utf-8#Assertions> identifies that it is a best practice for policy authors to define the set of policy subjects to which policy assertions can be attached. Over time, new policy subjects may need to be defined. When this occurs, a policy assertion author may update the list of policy subjects supported by an assertion.

When the assertion's semantics do not change to invalidate any of the original policy subjects but new policy subjects need to be added, it may be possible to use the same assertion to designate the additional policy subjects without a namespace change. For example, a policy assertion for a protocol that is originally designed for endpoint policy subject may add message policy subject to indicate finer granularity in the attachment provided that endpoint policy subject is also retained in its design. When new policy subjects are added it is incumbent on the authors to retain the semantic of the policy assertion.

Best Practice: An assertion description should specify a policy subject.