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- see
http://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]. 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 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 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 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.