- From: Maryann Hondo via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 29 Nov 2006 20:15:34 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv27530
Modified Files:
ws-policy-guidelines.html
Log Message:
updates as per open actions 64 and 77, related to f2f resolution3792 and bugzilla entry 3705 - restructure guidelines & incorporate primer sections
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- ws-policy-guidelines.html 28 Nov 2006 00:45:59 -0000 1.9
+++ ws-policy-guidelines.html 29 Nov 2006 20:15:31 -0000 1.10
@@ -63,7 +63,7 @@
guide to using the specifications. </p></div><div>
<h2><a name="status">Status of this Document</a></h2><p><strong>This document is an editors' copy that has
no official standing.</strong></p><p></p></div><hr><div class="toc">
-<h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#introduction">Introduction</a><br>2. <a href="#Assertions">What is an Assertion? </a><br>3. <a href="#d3e178">Who is involved in authoring Assertions? </a><br> 3.1 <a href="#roles"> Roles and Responsibilities </a><br> 3.1.1 <a href="#domain-owners"> WS-Policy Authors</a><br> 3.1.2 <a href="#consumers">Consumers</a><br> 3.1.3 <a href="#providers">Providers</a><br>4. <a href="#general-guidelines">General Guidelines for WS-Policy Assertion Authors</a><br> 4.1 <a href="#assertion-target">Assertions and Their Target Use</a><br> 4.2 <a href="#compact-full">Authoring Styles </a><br> 4.3 <a href="#new-guidelines-domains">Considerations when Modeling New Assertions</a><br> &nbp; 4.3.1 <a href="#minimal-approach">Minimal approach</a><br> 4.3.2 <a href="#QName_and_XML_Information_Set_representation">QName and XML Information Set representation</a><br> 4.3.3 <a href="#self-describing"> Self Describing Messages </a><br> 4.3.4 <a href="#single-domains">Single Domains</a><br> 4.4 <a href="#comparison">Comparison of Nested and Parameterized Assertions</a><br> 4.4.1 <a href="#parameterized-assertions">Assertions with Parameters</a><br> 4.4.2 <a href="#nested-assertions">Nested Assertions</a><br> 4.4.3 <a href="#which-one-to-use">Considerations for choosing parameters vs nesting</a><br> 4.5 <a href="#optional-policy-assertion">Designating Optional Behaviors</a>br> 4.5.1 <a href="#d3e513">Optional behavior in Compact authoring</a><br> 4.5.2 <a href="#d3e521">Optional behavior at runtime</a><br> 4.6 <a href="#typing-assertions">Typing Assertions</a><br> 4.7 <a href="#levels-of-abstraction">Levels of Abstraction in WSDL </a><br>5. <a href="#lifecycle">Lifecycle of Assertions</a><br> 5.1 <a href="#Referencing_Policy_Expressions">Referencing Policy Expressions</a><br> 5.2 <a href="#extending-assertions"> Factors in Extending Assertions within a Domain </a><br> 5.3 <a href="#assertion-evolution">Evolution of Assertions (Versioning and Compatibility)</a><br> 5.3.1 <a href="#versioning-policy-language">Versioning Policy Language</a><br> 5.3.2 <a href="#versioning-policy-fraework">Policy Framework</a><br> 5.3.3 <a href="#versioning-policy-attachment">Policy Attachment</a><br>6. <a href="#inter-policy">Inter-domain Policy and Composition Issues</a><br>7. <a href="#best-practices-attachment">Applying Best Practices for Policy Attachment</a><br> 7.1 <a href="#context-free-policies">Appropriate Attachment: Preserving Context-Free Policies</a><br> 7.2 <a href="#appropriate-attachment-assertion-subjects">Appropriate Attachment: Identifying Assertion Subjects</a><br> 7.2.1 <a href="#interaction">Interaction between Subjects</a><br> 7.3 <a href="#identifying-assertion-sources">Appropriate Attachment: Identifying Assertion Sources </a><br>8. <a href="#scenerio">Scenario and a worked example</a><br></p>
+<h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#introduction">Introduction</a><br>2. <a href="#Assertions">What is an Assertion? </a><br>3. <a href="#d3e178">Who is involved in authoring Assertions? </a><br> 3.1 <a href="#roles"> Roles and Responsibilities </a><br> 3.1.1 <a href="#domain-owners"> WS-Policy Authors</a><br> 3.1.2 <a href="#consumers">Consumers</a><br> 3.1.3 <a href="#providers">Providers</a><br>4. <a href="#general-guidelines">General Guidelines for WS-Policy Assertion Authors</a><br> 4.1 <a href="#assertion-target">Assertions and Their Target Use</a><br> 4.2 <a href="#compact-full">Authoring Styles </a><br> 4.3 <a href="#new-guidelines-domains">Considerations when Modeling New Assertions</a><br> &nbp; 4.3.1 <a href="#minimal-approach">Minimal approach</a><br> 4.3.2 <a href="#QName_and_XML_Information_Set_representation">QName and XML Information Set representation</a><br> 4.3.3 <a href="#self-describing"> Self Describing Messages </a><br> 4.3.4 <a href="#single-domains">Single Domains</a><br> 4.4 <a href="#comparison">Comparison of Nested and Parameterized Assertions</a><br> 4.4.1 <a href="#parameterized-assertions">Assertions with Parameters</a><br> 4.4.2 <a href="#nested-assertions">Nested Assertions</a><br> 4.4.3 <a href="#which-one-to-use">Considerations for choosing parameters vs nesting</a><br> 4.5 <a href="#optional-policy-assertion">Designating Optional Behaviors</a>br> 4.5.1 <a href="#d3e513">Optional behavior in Compact authoring</a><br> 4.5.2 <a href="#d3e521">Optional behavior at runtime</a><br> 4.6 <a href="#typing-assertions">Typing Assertions</a><br> 4.7 <a href="#levels-of-abstraction">Levels of Abstraction in WSDL </a><br>5. <a href="#lifecycle">Lifecycle of Assertions</a><br> 5.1 <a href="#Referencing_Policy_Expressions">Referencing Policy Expressions</a><br> 5.2 <a href="#extending-assertions"> Factors in Extending Assertions within a Domain </a><br> 5.3 <a href="#assertion-evolution">Evolution of Assertions (Versioning and Compatibility)</a><br>6. <a href="#inter-policy">Inter-domain Policy and Composition Issues</a><br>7. <a href="#best-practices-attachment">Applying Best Practices for Policy Attachment</a><br> 7.1 <a href="#cotext-free-policies">Appropriate Attachment: Preserving Context-Free Policies</a><br> 7.2 <a href="#appropriate-attachment-assertion-subjects">Appropriate Attachment: Identifying Assertion Subjects</a><br> 7.2.1 <a href="#interaction">Interaction between Subjects</a><br> 7.3 <a href="#identifying-assertion-sources">Appropriate Attachment: Identifying Assertion Sources </a><br>8. <a href="#scenerio">Scenario and a worked example</a><br></p>
<h3><a name="appendix" id="appendix">Appendices</a></h3><p class="toc">A. <a href="#security-considerations">Security Considerations</a><br>B. <a href="#xml-namespaces">XML Namespaces</a><br>C. <a href="#references">References</a><br>D. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<br>E. <a href="#change-description">Changes in this Version of
the Document</a> (Non-Normative)<br>F. <a href="#change-log">Web Services Policy 1.5 - Guidelines for Policy Assertion Authors Change Log</a> (Non-Normative)<br></p></div><hr><div class="body"><div class="div1">
<h2><a name="introduction"></a>1. Introduction</h2><p>WS-Policy specification defines a policy to be a collection
@@ -795,7 +795,13 @@
rather abstract requirements, this technique does not apply.
</p></div></div><div class="div1">
<h2><a name="lifecycle"></a>5. Lifecycle of Assertions</h2><p>WS-Policy authors need to consider not just the expression of the current set of requirements but
- how they anticipate new assertions being added to the set. There are three aspects that govern an assertions lifecycle:</p><ul><li><p> Assertion Extensibility </p></li><li><p> Policy Language Extensibility </p></li><li><p> Subject attachment Extensibility </p></li></ul><div class="div2">
+ how they anticipate new assertions being added to the set. There are three aspects that govern an assertions lifecycle:</p><ul><li><p> Assertion Extensibility </p></li><li><p> Policy Language Extensibility </p><p>Over time, the Policy WG or third parties can version or extend the Policy Language with new
+ or modified constructs. These constructs may be compatible or incompatible with previous versions.
+ </p><p> Policy authors should review the WS-Policy Primer <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>
+ and the specifications <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite> <cite><a href="#WS-PolicyAttachment">Web Services Policy Attachment</a></cite>
+ for details on extensibility.
+ </p><p> The current WS-Policy language <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite> provides extensibility points
+ on 6 elements with a combination of attribute and/or element extensibility:</p><ol><li><p>Policy: element from ##other namespace and any attribute</p></li><li><p>PolicyReference: any attribute and a proposal to add any element ExactlyOne, All: element from ##other namespace, no attribute extensibility</p></li><li><p>PolicyAttachment: element from ##other namespace and any attribute</p></li><li><p>AppliesTo: any element and any attribute</p></li></ol></li><li><p> Subject attachment Extensibility </p><p>PolicyAttachment and AppliesTo also have extensibility points.</p></li></ul><div class="div2">
<h3><a name="Referencing_Policy_Expressions"></a>5.1 Referencing Policy Expressions</h3><p>The <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite> 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
@@ -819,123 +825,7 @@
behaviors can be modeled as independent assertions. The
policy expression in the example below requires the use of
WSS: SOAP Message Security 1.0. </p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-1. </span>Example 4-2. Message-level Security and WSS: SOAP Message Security 1.0 </i></p><p>ADD THE EXAMPLE HERE </p></div><p>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. </p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-2. </span>Example 4-3. Message-level Security and WSS: SOAP Message Security 1.1</i></p><p>ADD THE EXAMPLE HERE </p></div><p>Best practice: use independent assertions for modeling multiple equivalent behaviors. </p><div class="div3">
-<h4><a name="versioning-policy-language"></a>5.3.1 Versioning Policy Language</h4><p>Over time, the Policy WG or third parties can version or extend the Policy Language with new or modified constructs. These constructs may be compatible or incompatible with previous versions. Some of the possible new constructs that have been mentioned previously are: new operators, operator cardinality, policy identification, compact syntax, Policy Inclusion, security, referencing, attachment points, alternative
- priority, effective dating, negotiation. </p><p>WS-Policy provides extensibility points on 6 elements with a combination of attribute and/or element extensibility.
- The possible extensibility points with their current extensibility - including some outstanding issues related to extensibility - are:</p><ol><li><p>Policy: element from ##other namespace and any attribute</p></li><li><p>PolicyReference: any attribute and a proposal to add any element ExactlyOne, All: element from ##other namespace, no attribute extensibility</p></li><li><p>PolicyAttachment: element from ##other namespace and any attribute</p></li><li><p>AppliesTo: any element and any attribute</p></li></ol></div><div class="div3">
-<h4><a name="versioning-policy-framework"></a>5.3.2 Policy Framework</h4><p>WS-Policy Framework 1.5 specifies that any element that is not known inside a Policy, ExactlyOne or All will be treated as an assertion. The default value for wsp:Optional="false", which means after normalization it will be inside an ExactlyOne/All operator. </p><p>Let us show an example with a hypothetical new operator that is a Choice with a minOccurs and a maxOccurs attributes, ala XSD:Choice, in a new namespace. We use the wsp16 prefix to indicate a hypothetical Policy Language 1.6 that is intended to be compatible with Policy Language 1.5:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-3. </span>Policy containing 1.5 and 1.6 Policies.</i></p><div class="exampleInner"><pre><wsp:Policy>
- <wsp:ExactlyOne>
- <wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
- ...
- </wsp16:Choice>
- <wsp:All>
- ...
- </wsp:All>
- </wsp:ExactlyOne>
-</wsp:Policy></pre></div></div><p>The normalization rule for wsp:Optional="false" would be applied to the wsp16:Choice, yielding the following expression:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-4. </span>Normalized Policy containing 1.5 and 1.6 Policies</i></p><div class="exampleInner"><pre><wsp:Policy>
- <wsp:ExactlyOne>
- <wsp:ExactlyOne>
- <wsp:All>
- <wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
- ...
- </wsp16:Choice>
- </wsp:All>
- </wsp:ExactlyOne>
- <wsp:All>
- ...
- </wsp:All>
- </wsp:ExactlyOne>
-</wsp:Policy></pre></div></div><p>Alternatively, the wsp:Optional could be set to "true" on the choice, as
-in:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-5. </span>Policy containing explicit wsp:Optional="true"</i></p><div class="exampleInner"><pre><wsp:Policy>
- <wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2"
-wsp:Optional="true">
- ...
- </wsp16:Choice>
-</wsp:Policy></pre></div></div><p>The normalized form will be:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-6. </span>Normalized policy</i></p><div class="exampleInner"><pre><wsp:Policy>
- <wsp:ExactlyOne>
- <wsp:All>
- <wsp16:Choice wsp16:minOccurs="1" wsp16:maxOccurs="2">
- ...
- </wsp16:Choice>
- </wsp:All>
- <wsp:All/>
- </wsp:ExactlyOne>
-</wsp:Policy></pre></div></div><p>Because the wsp16:Choice alternative isn't understood in either normalized form, it will not be chosen as one of the alternatives and will effectively be ignored. Policy intersection may be more difficult with such compatible extensions. For example, the previous will "look"
- like it has a wsp16:Choice typed assertion. To determine intersection with a Policy that does not have the wsp16:Choice type assertion, domain specific processing would have to be done. However, there is an alternative that does not have the wsp16:Choice, so intersection would yield the expected result.
- </p><p>Note: it is possible to add new names to the existing namespace, such as: </p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-7. </span>Policy containing 1.5 and 1.6 Policies all in the 1.5 namespace</i></p><div class="exampleInner"><pre><wsp:Policy>
- <wsp:ExactlyOne>
- <wsp:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
- ...
- </wsp:Choice>
- <wsp:All>
- ...
- </wsp:All>
- </wsp:ExactlyOne>
-</wsp:Policy></pre></div></div><p>Notice that using a new namespace can result in backwards and forwards compatibility if
- normalization results in an optional alternative. </p><p>Best practice: insert new elements in an optional alternative or mark with wsp:Optional="true".
- </p><p>Incompatible versions of the Policy language may be indicated by a new namespace name for at
- least the new and/or incompatible elements or attributes. Imagine that the Choice operator is
- required by a future version of Policy, then there will be a new namespace for the Policy element.
- We use the wsp20 prefix to indicate a hypothetical Policy Language 2.0 that is intended to be
- incompatible with Policy Language 1.5:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-8. </span>Policy containing 2.0 only Policies.</i></p><div class="exampleInner"><pre><wsp20:Policy>
- <wsp20:ExactlyOne>
- <wsp20:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
- ...
- </wsp20:Choice>
- ...
- </wsp20:ExactlyOne>
-</wsp20:Policy> </pre></div></div><p>The new Policy operator could be embedded inside an existing Policy element:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-9. </span>Policy containing 2.0 (incompatible with 1.5) Policies embedded in wsp 1.5 Policy.</i></p><div class="exampleInner"><pre><wsp:Policy>
- <wsp20:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
- ...
- </wsp20:Choice>
- ...
-</wsp20:Policy> </pre></div></div><p>This will be treated as an Assertion for normalization and intersection computation.
- This will result in only one alternative that requires the wsp20:Choice, the intended behaviour
- for incompatible changes.</p><p>Best practice: use a new namespace for new incompatible construct and insert inside either: new Policy element OR existing All for future incompatible policy extensions.</p><p>A future version of WS-Policy could support the current operators in the existing namespace,
- such as:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-10. </span>Policy containing 1.5 operator in 2.0 Policy</i></p><div class="exampleInner"><pre><wsp20:Policy>
- <wsp:ExactlyOne>
- <wsp20:Choice wsp:minOccurs="1" wsp:maxOccurs="2">
- ...
- </wsp20:Choice>
- ...
- </wsp:ExactlyOne>
-</wsp20:Policy> </pre></div></div><p>It is difficult to predict whether this functionality would be useful. The future version of WS-Policy doesn't appear to be precluded from doing this.</p></div><div class="div3">
-<h4><a name="versioning-policy-attachment"></a>5.3.3 Policy Attachment</h4><p>Policy attachment provides WSDL 1.1 and UDDI attachment points. It appears that exchange of Policy will be in the
- context of WSDL or UDDI. WRT WSDL, the policy model is an extension of the WSDL definition. As such, it is likely that future versions of Policy will be exchanged as multiple Policy expressions within a WSDL. One alternative is that there would be a separate WSDL for each version of Policy. The problem of how to specify and query for compound documents is very difficult, so it is more likely that each version of Policy will be exchanged within a WSDL. </p><p>We show an example of a new version of policy that allows QName reference to Policies in the PolicyReference:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-11. </span>WSDL containing 1.5 and 2.0 (compatible with 2.0) Policy References.</i></p><div class="exampleInner"><pre><wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
- <wsoap12:binding style="document"
- transport="http://schemas.xmlsoap.org/soap/http" />
- <wsp:Policy>
- <wsp:ExactlyOne>
- <wsp:All>
- <wsp:PolicyReference URI="#RmPolicy"
-wsdl11:required="true" />
- <wsp:PolicyReference URI="#X509EndpointPolicy"
-wsdl11:required="true" />
- </wsp:All>
- <wsp:All>
- <wsp:PolicyReferenceByQName ref="rmp:RMAssertion"
-wsdl11:required="true" />
- <wsp:PolicyReferenceByQName ref="sp:AsymmetricBinding"
-wsdl11:required="true" />
- </wsp:All>
- </wsp:ExactlyOne>
- </wsp:Policy>
- <wsdl11:operation name="GetLastTradePrice" > ....
- ...</pre></div></div><p>The PolicyReference element is attribute extensible. One example of an addition is a list of backup URIs for the PolicyReference:</p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-12. </span>WSDL containing 1.5 and 2.0 (compatible with 2.0) Policy References.</i></p><div class="exampleInner"><pre><wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
- <wsoap12:binding style="document"
- transport="http://schemas.xmlsoap.org/soap/http" />
- <wsp:Policy>
- <wsp:ExactlyOne>
- <wsp:All>
- <wsp:PolicyReference URI="" wsp16:alternateURIs="URI*"
-wsdl11:required="true" />
- <wsp:PolicyReference URI="" wsp16:alternateURIs="URI*"
-wsdl11:required="true" />
- </wsp:All>
- </wsp:ExactlyOne>
- </wsp:Policy>
- <wsdl11:operation name="GetLastTradePrice" > ....
- ...</pre></div></div><p>The policy framework specification says that any unknown attributes are ignored. A Policy 1.5 processor will not understand the wsp16:alternateURI attribute, it will be ignored. A Policy 1.6 processor will understand the alternate URIs so it won't be ignored.</p><p>PolicyAttachment and AppliesTo also have extensibility points. We choose not to illustrate these at this time.</p></div></div></div><div class="div1">
+ equivalent behaviors and are represented using distinct policy assertions. </p><div class="exampleOuter"><p style="text-align: left" class="exampleHead"><i><span>Example 5-2. </span>Example 4-3. Message-level Security and WSS: SOAP Message Security 1.1</i></p><p>ADD THE EXAMPLE HERE </p></div><p>Best practice: use independent assertions for modeling multiple equivalent behaviors. </p></div></div><div class="div1">
<h2><a name="inter-policy"></a>6. Inter-domain Policy and Composition Issues</h2><p>Domain authors must be aware of the interactions between their
domain and other domains. For example, security assertions interact
with other protocol assertions in a composition. Although
@@ -1318,4 +1208,5 @@
<a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0033.html">Frederick</a> and
<a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0054.html">Umit</a> to the list of editors.
Editors' action <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/86">86</a>.
+ </td></tr><tr><td rowspan="1" colspan="1">20061128</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">Replaced section in Lifecycle with pointer to the text in the primer: related to action 77
</td></tr></tbody></table><br></div></div></body></html>
\ No newline at end of file
Received on Wednesday, 29 November 2006 20:15:48 UTC