- From: Maryann Hondo <mhondo@us.ibm.com>
- Date: Fri, 23 Mar 2007 11:39:55 -0400
- To: public-ws-policy@w3.org
- Message-ID: <OFB2FFE8B4.D7CAF943-ON872572A7.005451A7-852572A7.0055E781@us.ibm.com>
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.
Received on Friday, 23 March 2007 15:40:14 UTC