- From: Asir Vedamuthu via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 15 May 2007 02:36:23 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv31194
Modified Files:
ws-policy-guidelines.html ws-policy-guidelines.xml
Log Message:
Updated Section 5.4.1 to use the new format re issue issue 3989. Editors' action 230.
Updated Section 5.4.2 to use the new format re issue issue 3989. Editors' action 230. Collapsed Section 5.4.2 and 5.4.3.
Added G11 and G13 to Section 5.4.1 and 5.4.2 re issue issue 3989. Editors' action 252 and 255.
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.54
retrieving revision 1.55
diff -u -d -r1.54 -r1.55
--- ws-policy-guidelines.html 11 May 2007 22:51:01 -0000 1.54
+++ ws-policy-guidelines.html 15 May 2007 02:36:21 -0000 1.55
@@ -119,7 +119,7 @@
<h2><a name="contents" id="contents"></a>Table of Contents</h2><p class="toc">1. <a href="#introduction">Introduction</a><br>
2. <a href="#best-practices-list">List of Good Practice Statements</a><br>
3. <a href="#Assertions">What is an Assertion? </a><br>
-4. <a href="#d3e259">Who is involved in authoring Assertions? </a><br>
+4. <a href="#d3e265">Who is involved in authoring Assertions? </a><br>
4.1 <a href="#roles"> Roles and Responsibilities </a><br>
4.1.1 <a href="#domain-owners"> Assertion Authors</a><br>
4.1.2 <a href="#consumers">Consumers</a><br>
@@ -135,14 +135,13 @@
5.4 <a href="#comparison">Comparison of Nested and Parameterized Assertions</a><br>
5.4.1 <a href="#parameterized-assertions">Assertions with Parameters</a><br>
5.4.2 <a href="#nested-assertions">Nested Assertions</a><br>
- 5.4.3 <a href="#which-one-to-use">Considerations for choosing parameters vs nesting</a><br>
5.5 <a href="#Ignorable">Designating Ignorable Behavior</a><br>
5.5.1 <a href="#doc-ignorable-assertions">Assertions and Ignorable Behavior</a><br>
5.5.2 <a href="#XML-ignorable-assertions">XML Outline for Ignorable </a><br>
5.6 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br>
- 5.6.1 <a href="#d3e724">Optional behavior in Compact authoring</a><br>
- 5.6.2 <a href="#d3e764">Optional behavior at runtime</a><br>
- 5.6.2.1 <a href="#d3e809">Example</a><br>
+ 5.6.1 <a href="#d3e745">Optional behavior in Compact authoring</a><br>
+ 5.6.2 <a href="#d3e785">Optional behavior at runtime</a><br>
+ 5.6.2.1 <a href="#d3e830">Example</a><br>
5.7 <a href="#levels-of-abstraction">Considerations for Policy Attachment in WSDL </a><br>
5.8 <a href="#interrelated-domains">Interrelated domains</a><br>
6. <a href="#versioning-policy-assertions">Versioning Policy Assertions</a><br>
@@ -210,7 +209,8 @@
the Socratic style of beginning with a question, and then answering
the question.
</p></div><div class="div1">
-<h2><a name="best-practices-list" id="best-practices-list"></a>2. List of Good Practice Statements</h2><p>The following good practices appear in this document with discussion and examples, and are summarized here for quick reference:</p><ul><li><p><a href="#bp-assertion-specification-parts"><b>1. Parts of an Assertion Specification</b></a></p></li><li><p><a href="#bp-assertion-semantics"><b>2. Semantics of Policy Assertions</b></a></p></li><li><p><a href="#bp-semantics-and-form"><b>3. Semantics of an Assertion and its form</b></a></p></li><li><p><a href="#bp-assertion-start"><b>4. Starting to Build an Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>5. Unique QNames</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>6. Clear Semantics</b></a></p></li><li><p><a href="#XMLOutline"><b>7. XML Outline</b></a></p></li><li><p><a href="#bp-assertions-and-message-semantics"><b>8. Assertions and Message Semantics</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>9. Duplication of Asertions</b></a></p></li><li><p><a href="#bp-assertion-definition"><b>10. Definition of Policy Assertions</b></a></p></li><li><p><a href="#bp-nesting"><b>11. Nesting of Assertions</b></a></p></li><li><p><a href="#DefineIgnorable"><b>12. Assertions Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>13. Ignorable Attribute in XML</b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>14. Assertion XML should allow use of wsp:Optional attribute</b></a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional"><b>15. Assertion description should explicitly indicate that wsp:Optional is allowed.</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>16. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>17. Consider entire message exchange pattern when specifying Assertions that may be optional</b></a></p></li><li><p><a href="#bp-indicate-optional-assertion-use"><b>18. Indicate use of an Opional Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>19. An assertion description should specify a policy subject</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>20. Granularity of policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>21. Assertion attachment to multiple policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-policy-scope-semantics"><b>22. Fully specify constraints on policy scope</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>23. Preferred attachment point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>24. Semantics of multiple assertions of the same kind</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>25. Independent Assertions</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>26. Change of the Policy Subject Over Time</b></a></p></li></ul></div><div class="div1">
+<h2><a name="best-practices-list" id="best-practices-list"></a>2. List of Good Practice Statements</h2><p>The following good practices appear in this document with discussion and examples, and are summarized here for quick reference:</p><ul><li><p><a href="#bp-assertion-specification-parts"><b>1. Parts of an Assertion Specification</b></a></p></li><li><p><a href="#bp-assertion-semantics"><b>2. Semantics of Policy Assertions</b></a></p></li><li><p><a href="#bp-semantics-and-form"><b>3. Semantics of an Assertion and its form</b></a></p></li><li><p><a href="#bp-assertion-start"><b>4. Starting to Build an Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>5. Unique QNames</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>6. Clear Semantics</b></a></p></li><li><p><a href="#XMLOutline"><b>7. XML Outline</b></a></p></li><li><p><a href="#bp-assertions-and-message-semantics"><b>8. Assertions and Message Semantics</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>9. Duplication of Asertions</b></a></p></li><li><p><a href="#bp-assertion-parameters"><b>10. Use Parameters for Useful
+ Information</b></a></p></li><li><p><a href="#bp-dependent-behaviors"><b>11. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>12. Declare Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>13. Discourage Domain Specific Intersection</b></a></p></li><li><p><a href="#DefineIgnorable"><b>14. Assertions Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>15. Ignorable Attribute in XML</b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>16. Assertion XML should allow use of wsp:Optional attribute</b></a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional"><b>17. Assertion description should explicitly indicate that wsp:Optional is allowed.</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>18. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>19. Consider entire mesage exchange pattern when specifying Assertions that may be optional</b></a></p></li><li><p><a href="#bp-indicate-optional-assertion-use"><b>20. Indicate use of an Optional Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>21. An assertion description should specify a policy subject</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>22. Granularity of policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>23. Assertion attachment to multiple policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-policy-scope-semantics"><b>24. Fully specify constraints on policy scope</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>25. Preferred attachment point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>26. Semantics of multiple assertions of the same kind</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>27. Independent Assertions</b></a></p></li><li><p><a hrf="#bp-policy-subject-change"><b>28. Change of the Policy Subject Over Time</b></a></p></li></ul></div><div class="div1">
<h2><a name="Assertions" id="Assertions"></a>3. What is an Assertion? </h2><p>An assertion is a piece of metadata that describes a
capability related to a specific WS-Policy domain. Sets of domain-specific assertions
are typically defined in a dedicated specification that describes
@@ -269,7 +269,7 @@
best practices will be an assertion specification that describes
a contract for the consumers and providers of the capabilities and constraints of the domain.
</p></div><div class="div1">
-<h2><a name="d3e259" id="d3e259"></a>4. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
+<h2><a name="d3e265" id="d3e265"></a>4. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
express their own domain knowledge, it is necessary to provide basic
functionality that all domains could exploit and then allow
points of extension where authors of the various WS-Policy
@@ -640,40 +640,78 @@
assertion beyond its type. We cover these two cases below followed by a
comparison of these approaches targeting when to use either of the approach.
</p><div class="div3">
-<h4><a name="parameterized-assertions" id="parameterized-assertions"></a>5.4.1 Assertions with Parameters</h4><p>The framework allows WS-Policy domain authors to define
- policy assertion parameters to qualify an assertion.
- Policy assertion parameters are defined <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite>.
- Policy assertion parameters are the opaque payload of an assertion.
- Assertion parameters carry additional useful pieces of information
- necessary for engaging the behavior described by an assertion.
- Assertion parameters are not considered when performing policy
- intersection unless domain specific compatibility processing
- semantics are specified by the assertion.
- In the XML representation of a policy assertion the child elements
- and attributes of the assertion excluding child elements and attributes
- from the policy xml language namespace are the assertion parameters.
- </p><p>In the example below, <code>sp:Body</code> and <code>sp:Header</code>
- elements are the two assertion parameters of the
- <code>sp:SignedParts</code> policy assertion
- (this assertion requires the parts of a message to be protected).
- </p><div class="exampleOuter">
+<h4><a name="parameterized-assertions" id="parameterized-assertions"></a>5.4.1 Assertions with Parameters</h4><p>Policy assertion parameters are the opaque payload of an assertion.
+ Parameters carry additional useful information for engaging the
+ behavior described by an assertion and are preserved through policy
+ processing such as normalize, merge and policy intersection.
+ Requesters may use policy intersection to select a compatible
+ policy alternative for an interaction. Assertion parameters do not
+ affect the outcome of policy intersection unless the assertion specifies
+ domain specific processing for policy intersection.</p><p>In the XML representation of a policy assertion, the child elements
+ and attributes of the assertion excluding child elements and attributes
+ from the policy language namespace name are the assertion parameters.</p><div class="boxedtext"><p><a name="bp-assertion-parameters" id="bp-assertion-parameters"></a><span class="practicelab">Good
+practice 10: Use Parameters for Useful
+ Information</span></p><p class="practice">An assertion author should represent useful (or additional)
+ nformation necessary for engaging the behavior represented by a policy
+ assertion as assertion parameters.
+ </p></div><p>In the example below, <code>sp:Body</code> and <code>sp:Header</code>
+ elements are the two assertion parameters of the
+ <code>sp:SignedParts</code> policy assertion
+ (this assertion requires the parts of a message to be protected).
+ These two parameters identify the parts of a wire message that should be
+ protected. These parameters carry additional useful information for
+ engaging the behavior.</p><div class="exampleOuter">
<p style="text-align: left" class="exampleHead"><i><span>Example 5-5. </span>Policy Assertion with Assertion Parameters</i></p><div class="exampleInner"><pre><wsp:Policy>
<sp:SignedParts>
<sp:Body/>
<sp:Header/>
</sp:SignedParts>
-</wsp:Policy></pre></div></div><div class="boxedtext"><p><a name="bp-assertion-definition" id="bp-assertion-definition"></a><span class="practicelab">Good
-practice 10: Definition of Policy Assertions</span></p><p class="practice">Define policy assertion parameters for
- specifying useful pieces of information necessary for engaging
- the behavior described by an assertion but not relevant to policy
- intersection.</p></div></div><div class="div3">
+</wsp:Policy></pre></div></div></div><div class="div3">
<h4><a name="nested-assertions" id="nested-assertions"></a>5.4.2 Nested Assertions</h4><p>The framework provides the ability to "nest" policy assertions. For domains with a complex set of
options, nesting provides one way to indicate dependent
elements within a behavior. 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.
- </p><p>We will use the WS-SecurityPolicy to illustrate the use of nested assertions.
+ </p><p>
+ The following design questions below can help
+ to determine when to use nested policy expressions:</p><ul><li><p>Are these assertions designed for the same policy subject? </p></li><li><p>Do these assertions represent dependent behaviors?</p></li></ul><p>If the answers are yes to both of these questions then leveraging nested policy
+ expressions is something to consider. Keep in mind that a nested policy expression participates in
+ the policy intersection algorithm. If a requester uses policy intersection to select a
+ compatible policy alternative then the assertions in a nested policy expression play a
+ first class role in the outcome. If there is a nested policy expression, an assertion
+ description should declare it and enumerate the nested policy assertions
+ that are allowed. There is one caveat to watch out for: policy assertions
+ with deeply nested policy can greatly increase the complexity of a policy and should be
+ avoided when they are not needed.</p><div class="boxedtext"><p><a name="bp-dependent-behaviors" id="bp-dependent-behaviors"></a><span class="practicelab">Good
+practice 11: Use Nested Assertions for Dependent Behaviors</span></p><p class="practice">An assertion author should represent dependent behaviors that are relevant
+ to a compatibility test and apply to the same policy subject using
+ nested policy assertions.</p></div><div class="boxedtext"><p><a name="bp-declare-nested-assertions" id="bp-declare-nested-assertions"></a><span class="practicelab">Good
+practice 12: Declare Nested Assertions</span></p><p class="practice">If there is a nested policy expression, an assertion description should declare it
+ and enumerate the nested policy assertions that are allowed.</p></div><p>The main consideration for selecting parameters or nesting
+ of assertions is that <em>the framework intersection
+ algorithm processes nested alternatives, but does not consider
+ parameters in its algorithm</em>.
+ </p><p>Assertion Authors should recognize that the framework can
+ yield multiple assertions of the same type. The <em>QName</em>
+ of the assertion is the only vehicle for the framework to
+ match a specific assertion, NOT the contents of the
+ element. If the assertion is a parameterized assertion the
+ authors must understand that this type of assertion will
+ require additional processing by consumers in order to
+ disambiguate the assertions or to understand the semantics of
+ the name value pairs, complex content, attribute values
+ contribution to the processing. The tradeoff is the generality
+ vs. the flexibility and complexity of the comparison expected for a domain. </p><p>If the assertion
+ authors want to delegate the processing to the framework,
+ utilizing nesting should be considered. Otherwise, domain
+ specific comparison algorithms may need to be devised and be
+ delegated to the specific domain handlers that are not visible
+ to the WS-Policy framework. However, domain specific intersection processing reduces
+ interop and increases the burden to implement an assertion.</p><div class="boxedtext"><p><a name="bp-discourage-domain-specific-intersection" id="bp-discourage-domain-specific-intersection"></a><span class="practicelab">Good
+practice 13: Discourage Domain Specific Intersection</span></p><p class="practice">An
+ assertion description should only specify domain specific intersection
+ semantics when policy intersection is insufficient.</p></div><p>We will use the WS-SecurityPolicy to illustrate the use of nested assertions.
</p><p>Securing messages is a complex usage scenario. The WS-SecurityPolicy Assertion Authors have defined the
<code>sp:TransportBinding</code> policy assertion to indicate
the use of transport-level security for protecting
@@ -707,9 +745,9 @@
<Policy>
<sp:TransportToken>
<Policy>
- <sp:HttpsToken>
- <wsp:Policy/>
- </sp:HttpsToken>
+ <sp:HttpsToken>
+ <wsp:Policy/>
+ </sp:HttpsToken>
</Policy>
</sp:TransportToken>
<sp:AlgorithmSuite>
@@ -757,36 +795,7 @@
</wsp:Policy>
</sp:TransportToken></pre></div></div><p>A non-anonymous client who requires authentication or client
certificate will not be able to use this provider solely on the basis
- of intersection algorithm alone.</p></div><div class="div3">
-<h4><a name="which-one-to-use" id="which-one-to-use"></a>5.4.3 Considerations for choosing parameters vs nesting</h4><p>The main consideration for selecting parameters or nesting
- of assertions is that <em>the framework intersection
- algorithm processes nested alternatives, but does not consider
- parameters in its algorithm</em>.
- </p><p>Assertion Authors should recognize that the framework can
- yield multiple assertions of the same type. The <em>QName</em>
- of the assertion is the only vehicle for the framework to
- match a specific assertion, NOT the contents of the
- element. If the assertion is a parameterized assertion the
- authors must understand that this type of assertion will
- require additional processing by consumers in order to
- disambiguate the assertions or to understand the semantics of
- the name value pairs, complex content, attribute values
- contribution to the processing. The tradeoff is the generality
- vs. the flexibility and complexity of the comparison expected for a domain. </p><p>
- The following design questions below can help
- to determine when to use nested policy expressions:</p><ul><li><p>Are these assertions designed for the same policy subject? </p></li><li><p>Do these assertions represent dependent behaviors?</p></li></ul><p>If the answers are yes to both of these questions then leveraging nested policy
- expressions is something to consider. Keep in mind that a nested policy expression participates in
- the policy intersection algorithm. If a requester uses policy intersection to select a
- compatible policy alternative then the assertions in a nested policy expression play a
- first class role in the outcome. There is one caveat to watch out for: policy assertions
- with deeply nested policy can greatly increase the complexity of a policy and should be
- avoided when they are not needed.</p><div class="boxedtext"><p><a name="bp-nesting" id="bp-nesting"></a><span class="practicelab">Good
-practice 11: Nesting of Assertions</span></p><p class="practice">If the assertion
- authors want to delegate the processing to the framework,
- utilizing nesting should be considered. Otherwise, domain
- specific comparison algorithms may need to be devised and be
- delegated to the specific domain handlers that are not visible
- to the WS-Policy framework.</p></div></div></div><div class="div2">
+ of intersection algorithm alone.</p></div></div><div class="div2">
<h3><a name="Ignorable" id="Ignorable"></a>5.5 Designating Ignorable Behavior</h3><p>Policy assertions can be marked with an attribute to indicate that the assertion
can be ignored by the interstection algorithm. Assertion authors should consider
whether the behavior represented by the Assertion they are defining can be ignored for the purposes of
@@ -796,15 +805,15 @@
of the ignorable attribute.
</p><div class="div3">
<h4><a name="doc-ignorable-assertions" id="doc-ignorable-assertions"></a>5.5.1 Assertions and Ignorable Behavior</h4><div class="boxedtext"><p><a name="DefineIgnorable" id="DefineIgnorable"></a><span class="practicelab">Good
-practice 12: Assertions Document Ignorable Behavior</span></p><p class="practice"> An assertion description should use the wsp:Ignorable attribute
+practice 14: Assertions Document Ignorable Behavior</span></p><p class="practice"> An assertion description should use the wsp:Ignorable attribute
to indicate that the behavior indicated by the QName may be ignored by policy intersection.
</p></div></div><div class="div3">
<h4><a name="XML-ignorable-assertions" id="XML-ignorable-assertions"></a>5.5.2 XML Outline for Ignorable </h4><div class="boxedtext"><p><a name="ignorableAssertions" id="ignorableAssertions"></a><span class="practicelab">Good
-practice 13: Ignorable Attribute in XML</span></p><p class="practice"> An assertion XML outline should allow for the use of the wsp:Ignorable attribute
+practice 15: Ignorable Attribute in XML</span></p><p class="practice"> An assertion XML outline should allow for the use of the wsp:Ignorable attribute
to indicate ignorable behavior.
</p></div></div></div><div class="div2">
<h3><a name="optional-policy-assertion" id="optional-policy-assertion"></a>5.6 Designating Optional Behaviors</h3><div class="div3">
-<h4><a name="d3e724" id="d3e724"></a>5.6.1 Optional behavior in Compact authoring</h4><p>Optional behaviors represent behaviors that may be engaged by a consumer. When using the
+<h4><a name="d3e745" id="d3e745"></a>5.6.1 Optional behavior in Compact authoring</h4><p>Optional behaviors represent behaviors that may be engaged by a consumer. When using the
compact authoring form for assertions, such behaviors are marked by
using <code>wsp:Optional</code> attribute with a value of
"true". (In order to simplify reference to such assertions,
@@ -819,7 +828,7 @@
the wsp:Optional attribute. An assertion author should clearly indicate in the assertion
definition that it is possible to be optional
and to allow the use of the wsp:Optional attribute in the XML definition. </p><div class="boxedtext"><p><a name="bp-assertion-xml-allow-optional" id="bp-assertion-xml-allow-optional"></a><span class="practicelab">Good
-practice 14: Assertion XML should allow use of wsp:Optional attribute</span></p><p class="practice">An assertion XML outline should allow the use of the wsp:Optional attribute to
+practice 16: Assertion XML should allow use of wsp:Optional attribute</span></p><p class="practice">An assertion XML outline should allow the use of the wsp:Optional attribute to
indicate optional behaviors.</p></div><p>To give a general example, the definition of assertion syntax for a hypothetical assertion such as SampleAssertion,
should allow attribute extensibility as part of the XML definition, allowing the wsp:Optional attribute to be used:
</p><div class="exampleOuter">
@@ -827,7 +836,7 @@
This is an extensibility mechanism to allow additional attributes to be added to the element, including wsp:Optional.
</pre></div></div><p>The portion of the assertion definition that describes policy subjects and assertion attachment should indicate
that wsp:Optional can be used to indicate that the behavior is optional for the policy subject.</p><div class="boxedtext"><p><a name="bp-assertion-description-explicitly-allow-optional" id="bp-assertion-description-explicitly-allow-optional"></a><span class="practicelab">Good
-practice 15: Assertion description should explicitly indicate that wsp:Optional is allowed.</span></p><p class="practice">An assertion description should use the wsp:Optional attribute to indicate that the
+practice 17: Assertion description should explicitly indicate that wsp:Optional is allowed.</span></p><p class="practice">An assertion description should use the wsp:Optional attribute to indicate that the
behavior indicated by the QName is optional for the associated policy subject.</p></div><p>Continuing the example with the hypothetical SampleAssertion, the section on Assertion Attachment should
include discussion of optionality.
</p><div class="exampleOuter">
@@ -835,14 +844,14 @@
it has an Endpoint Policy Subject and must be attached to a wsdl:binding or wsdl:port.
The assertion may be optional when attached to these subjects, allowing use of wsp:Optional.
</pre></div></div></div><div class="div3">
-<h4><a name="d3e764" id="d3e764"></a>5.6.2 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
+<h4><a name="d3e785" id="d3e785"></a>5.6.2 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
both the provider and the consumer, behaviors that must
always be engaged by a consumer must not be marked as
"optional" with a value "true" since this would allow the
consumer to select the policy alternative that does not contain the assertion,
and thus not engaging the behavior.
</p><div class="boxedtext"><p><a name="bp-limit-optional-assertions" id="bp-limit-optional-assertions"></a><span class="practicelab">Good
-practice 16: Limit use of Optional Assertions</span></p><p class="practice">Assertion Authors should not use optional assertions for behaviors that must be present
+practice 18: Limit use of Optional Assertions</span></p><p class="practice">Assertion Authors should not use optional assertions for behaviors that must be present
in compatible policy expressions.</p></div><p> The target scope of an optional assertion is an important factor for
Assertion Authors to consider as it determines the
<em>granularity</em> where the behavior is optionally
@@ -874,7 +883,7 @@
assertions and require the use of endpoint policy subject
when message policy subject is used via attachment.
</p><div class="boxedtext"><p><a name="bp-entire-mep-for-optional" id="bp-entire-mep-for-optional"></a><span class="practicelab">Good
-practice 17: Consider entire message exchange pattern when specifying Assertions that may be optional</span></p><p class="practice">Assertion Authors should associate optional assertions with the appropriate endpoint and use the smallest
+practice 19: Consider entire message exchange pattern when specifying Assertions that may be optional</span></p><p class="practice">Assertion Authors should associate optional assertions with the appropriate endpoint and use the smallest
possible granularity to limit the degree to which optionality applies.</p></div><p>
Behaviors must be engaged
with respect to messages that are targeted to the provider
@@ -888,9 +897,9 @@
(Such an out of band mechanism is outside the scope of WS-Policy
Framework).
</p><div class="boxedtext"><p><a name="bp-indicate-optional-assertion-use" id="bp-indicate-optional-assertion-use"></a><span class="practicelab">Good
-practice 18: Indicate use of an Optional Assertion</span></p><p class="practice">When a given behavior may be optional, it must be possible for both message participants to determine that the assertion is selected by both parties,
+practice 20: Indicate use of an Optional Assertion</span></p><p class="practice">When a given behavior may be optional, it must be possible for both message participants to determine that the assertion is selected by both parties,
either out of band or as reflected by the message content.</p></div><div class="div4">
-<h5><a name="d3e809" id="d3e809"></a>5.6.2.1 Example</h5><p>
+<h5><a name="d3e830" id="d3e830"></a>5.6.2.1 Example</h5><p>
The <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite> document contains an example that outlines the
use of
<cite><a href="#MTOM">MTOM</a></cite> as an optional behavior that can be engaged by a consumer.
@@ -921,7 +930,7 @@
within WSDL, assertion authors must specify a WSDL
policy subject.
</p><div class="boxedtext"><p><a name="bp-WSDL-policy-subject" id="bp-WSDL-policy-subject"></a><span class="practicelab">Good
-practice 19: An assertion description should specify a policy subject</span></p><p class="practice">Assertion authors should associate assertions with the appropriate policy subject.
+practice 21: An assertion description should specify a policy subject</span></p><p class="practice">Assertion authors should associate assertions with the appropriate policy subject.
For instance, if a policy assertion is to be used with WSDL, the assertion description
should specify a WSDL policy subject – such as service, endpoint, operation and message.
</p></div><p>The specific WSDL policy subject is determined with respect to
@@ -936,7 +945,7 @@
the processing for considering a specific attachment point and
policy subject. This topic is considered in detail in <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>
</p><div class="boxedtext"><p><a name="bp-WSDL-policy-subject-Granularity" id="bp-WSDL-policy-subject-Granularity"></a><span class="practicelab">Good
-practice 20: Granularity of policy subjects</span></p><p class="practice">Assertion authors should choose the most granular policy subject
+practice 22: Granularity of policy subjects</span></p><p class="practice">Assertion authors should choose the most granular policy subject
that the behavior represented by a policy assertion applies to.
</p></div><p> For a given WSDL policy subject, there may be several
attachment points. For example, there are three attachment
@@ -962,7 +971,7 @@
policy attachments to policy subjects of broader scope and granularity
should be done only after careful evaluation.
</p><div class="boxedtext"><p><a name="bp-WSDL-multiple-policy-subjects" id="bp-WSDL-multiple-policy-subjects"></a><span class="practicelab">Good
-practice 21: Assertion attachment to multiple policy subjects</span></p><p class="practice">If an assertion is allowed to be associated with multiple policy
+practice 23: Assertion attachment to multiple policy subjects</span></p><p class="practice">If an assertion is allowed to be associated with multiple policy
subjects, the assertion description should describe the semantics of multiple
instances of the same assertion attached to multiple policy subjects
at the same time.
@@ -977,7 +986,7 @@
</p><p>If the capability is not really suitable and may imply
different semantics with respect to attachment points, the
assertion authors should consider the following:</p><ul><li><p> Decompose the semantics with several assertions.</p></li><li><p> Rewrite a single assertion targeting a specific subject. </p></li></ul><div class="boxedtext"><p><a name="bp-WSDL-policy-scope-semantics" id="bp-WSDL-policy-scope-semantics"></a><span class="practicelab">Good
-practice 22: Fully specify constraints on policy scope</span></p><p class="practice">Assertion authors must clearly describe any constraints on the
+practice 24: Fully specify constraints on policy scope</span></p><p class="practice">Assertion authors must clearly describe any constraints on the
policy scope if not limited to policy subjects identified by the policy
attachment point.
</p></div><p>The current set of subjects as mapped to the WSDL 1.1
@@ -995,7 +1004,7 @@
for attachment and engagement of behavior. Such additional constraints
must be clearly specified by the assertion authors.
</p><div class="boxedtext"><p><a name="bp-WSDL-preferred-attachment-point" id="bp-WSDL-preferred-attachment-point"></a><span class="practicelab">Good
-practice 23: Preferred attachment point for an Assertion</span></p><p class="practice">If an assertion can be attached at multiple points within a policy
+practice 25: Preferred attachment point for an Assertion</span></p><p class="practice">If an assertion can be attached at multiple points within a policy
subject, an assertion author should specify a preferred attachment
point for the chosen policy subject.
</p></div><p>One approach in WSDL is to identify different attachment points in
@@ -1013,7 +1022,7 @@
policy assertions do not target wire-level behaviors but
rather abstract requirements, this technique does not apply.
</p><div class="boxedtext"><p><a name="bp-WSDL-policy-multiple-instance-semantics" id="bp-WSDL-policy-multiple-instance-semantics"></a><span class="practicelab">Good
-practice 24: Semantics of multiple assertions of the same kind</span></p><p class="practice">A policy alternative can contain multiple instances of the
+practice 26: Semantics of multiple assertions of the same kind</span></p><p class="practice">A policy alternative can contain multiple instances of the
same policy assertion. An assertion description should specify the
semantics of multiple instances of a policy assertion in the same
policy alternative and the semantics of parameters and nested policy
@@ -1075,7 +1084,7 @@
[<cite><a href="#WS-Addressing">WS-Addressing Core</a></cite>]. These equivalent behaviors
are mutually exclusive for an interaction. Such equivalent
behaviors can be modeled as independent assertions. </p><div class="boxedtext"><p><a name="bp-independent-assertions" id="bp-independent-assertions"></a><span class="practicelab">Good
-practice 25: Independent Assertions</span></p><p class="practice">An assertion author should use independent assertions for modeling multiple versions of a behavior.</p></div><p>The
+practice 27: Independent Assertions</span></p><p class="practice">An assertion author should use independent assertions for modeling multiple versions of a behavior.</p></div><p>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 6-1. </span>Message-level Security and WSS: SOAP Message Security 1.0</i></p><div class="exampleInner"><pre><Policy>
@@ -1103,7 +1112,7 @@
new policy subjects are added it is incumbent on the authors to retain the
semantic of the policy assertion.
</p><div class="boxedtext"><p><a name="bp-policy-subject-change" id="bp-policy-subject-change"></a><span class="practicelab">Good
-practice 26: Change of the Policy Subject Over Time</span></p><p class="practice">If the policy subjects change over time,
+practice 28: Change of the Policy Subject Over Time</span></p><p class="practice">If the policy subjects change over time,
the assertion description should also be versioned to reflect this
change.</p></div></div></div><div class="div1">
<h2><a name="best-practices-attachment" id="best-practices-attachment"></a>7. Applying Best Practices for Policy Attachment</h2><div class="div2">
@@ -1617,4 +1626,18 @@
corresponding to editors' action item
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/232">256</a>
- now complete.
+ </td></tr><tr><td rowspan="1" colspan="1">20070513</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Updated Section 5.4.1 to use the new format re issue
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>.
+ Editors' action
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/230">230</a>.
+ </td></tr><tr><td rowspan="1" colspan="1">20070514</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Updated Section 5.4.2 to use the new format re issue
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>.
+ Editors' action
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/230">230</a>.
+ Collapsed Section 5.4.2 and 5.4.3.
+ </td></tr><tr><td rowspan="1" colspan="1">20070514</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Added G11 and G13 to Section 5.4.1 and 5.4.2 re issue
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>.
+ Editors' action
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/252">252</a> and
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/255">255</a>.
</td></tr></tbody></table><br></div></div></body></html>
\ No newline at end of file
Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.69
retrieving revision 1.70
diff -u -d -r1.69 -r1.70
--- ws-policy-guidelines.xml 11 May 2007 22:51:35 -0000 1.69
+++ ws-policy-guidelines.xml 15 May 2007 02:36:21 -0000 1.70
@@ -769,25 +769,34 @@
<div3 id="parameterized-assertions">
<head>Assertions with Parameters</head>
- <p>The framework allows WS-Policy domain authors to define
- policy assertion parameters to qualify an assertion.
- Policy assertion parameters are defined <bibref ref="WS-Policy"/>.
- Policy assertion parameters are the opaque payload of an assertion.
- Assertion parameters carry additional useful pieces of information
- necessary for engaging the behavior described by an assertion.
- Assertion parameters are not considered when performing policy
- intersection unless domain specific compatibility processing
- semantics are specified by the assertion.
- In the XML representation of a policy assertion the child elements
- and attributes of the assertion excluding child elements and attributes
- from the policy xml language namespace are the assertion parameters.
- </p>
+ <p>Policy assertion parameters are the opaque payload of an assertion.
+ Parameters carry additional useful information for engaging the
+ behavior described by an assertion and are preserved through policy
+ processing such as normalize, merge and policy intersection.
+ Requesters may use policy intersection to select a compatible
+ policy alternative for an interaction. Assertion parameters do not
+ affect the outcome of policy intersection unless the assertion specifies
+ domain specific processing for policy intersection.</p>
+
+ <p>In the XML representation of a policy assertion, the child elements
+ and attributes of the assertion excluding child elements and attributes
+ from the policy language namespace name are the assertion parameters.</p>
+
+ <p role="practice" id="bp-assertion-parameters"><quote>Use Parameters for Useful
+ Information</quote>
+ <quote>An assertion author should represent useful (or additional)
+ nformation necessary for engaging the behavior represented by a policy
+ assertion as assertion parameters.
+ </quote>
+ </p>
<p>In the example below, <code>sp:Body</code> and <code>sp:Header</code>
- elements are the two assertion parameters of the
- <code>sp:SignedParts</code> policy assertion
- (this assertion requires the parts of a message to be protected).
- </p>
+ elements are the two assertion parameters of the
+ <code>sp:SignedParts</code> policy assertion
+ (this assertion requires the parts of a message to be protected).
+ These two parameters identify the parts of a wire message that should be
+ protected. These parameters carry additional useful information for
+ engaging the behavior.</p>
<example> <head>Policy Assertion with Assertion Parameters</head>
<eg xml:space="preserve"><wsp:Policy>
@@ -797,11 +806,7 @@
</sp:SignedParts>
</wsp:Policy></eg>
</example>
- <p role="practice" id="bp-assertion-definition"><quote>Definition of Policy Assertions</quote><quote>Define policy assertion parameters for
- specifying useful pieces of information necessary for engaging
- the behavior described by an assertion but not relevant to policy
- intersection.</quote>
- </p>
+
</div3>
@@ -814,6 +819,70 @@
taken when defining nested policies to ensure that the options
provided appropriately specify policy alternatives within a specific behavior.
</p>
+ <p>
+ The following design questions below can help
+ to determine when to use nested policy expressions:</p>
+ <ulist>
+ <item>
+ <p>Are these assertions designed for the same policy subject? </p>
+ </item>
+ <item>
+ <p>Do these assertions represent dependent behaviors?</p>
+ </item>
+ </ulist>
+ <p>If the answers are yes to both of these questions then leveraging nested policy
+ expressions is something to consider. Keep in mind that a nested policy expression participates in
+ the policy intersection algorithm. If a requester uses policy intersection to select a
+ compatible policy alternative then the assertions in a nested policy expression play a
+ first class role in the outcome. If there is a nested policy expression, an assertion
+ description should declare it and enumerate the nested policy assertions
+ that are allowed. There is one caveat to watch out for: policy assertions
+ with deeply nested policy can greatly increase the complexity of a policy and should be
+ avoided when they are not needed.</p>
+
+ <p role="practice" id="bp-dependent-behaviors">
+ <quote>Use Nested Assertions for Dependent Behaviors</quote>
+ <quote>An assertion author should represent dependent behaviors that are relevant
+ to a compatibility test and apply to the same policy subject using
+ nested policy assertions.</quote></p>
+
+ <p role="practice" id="bp-declare-nested-assertions">
+ <quote>Declare Nested Assertions</quote>
+ <quote>If there is a nested policy expression, an assertion description should declare it
+ and enumerate the nested policy assertions that are allowed.</quote></p>
+
+ <p>The main consideration for selecting parameters or nesting
+ of assertions is that <emph>the framework intersection
+ algorithm processes nested alternatives, but does not consider
+ parameters in its algorithm</emph>.
+ </p>
+
+ <p>Assertion Authors should recognize that the framework can
+ yield multiple assertions of the same type. The <emph>QName</emph>
+ of the assertion is the only vehicle for the framework to
+ match a specific assertion, NOT the contents of the
+ element. If the assertion is a parameterized assertion the
+ authors must understand that this type of assertion will
+ require additional processing by consumers in order to
+ disambiguate the assertions or to understand the semantics of
+ the name value pairs, complex content, attribute values
+ contribution to the processing. The tradeoff is the generality
+ vs. the flexibility and complexity of the comparison expected for a domain. </p>
+
+ <p>If the assertion
+ authors want to delegate the processing to the framework,
+ utilizing nesting should be considered. Otherwise, domain
+ specific comparison algorithms may need to be devised and be
+ delegated to the specific domain handlers that are not visible
+ to the WS-Policy framework. However, domain specific intersection processing reduces
+ interop and increases the burden to implement an assertion.</p>
+
+ <p role="practice" id="bp-discourage-domain-specific-intersection">
+ <quote>Discourage Domain Specific Intersection</quote>
+ <quote>An
+ assertion description should only specify domain specific intersection
+ semantics when policy intersection is insufficient.</quote></p>
+
<p>We will use the WS-SecurityPolicy to illustrate the use of nested assertions.
</p>
<p>Securing messages is a complex usage scenario. The WS-SecurityPolicy Assertion Authors have defined the
@@ -853,9 +922,9 @@
<Policy>
<sp:TransportToken>
<Policy>
- <sp:HttpsToken>
- <wsp:Policy/>
- </sp:HttpsToken>
+ <sp:HttpsToken>
+ <wsp:Policy/>
+ </sp:HttpsToken>
</Policy>
</sp:TransportToken>
<sp:AlgorithmSuite>
@@ -921,51 +990,6 @@
</div3>
- <div3 id="which-one-to-use">
- <head>Considerations for choosing parameters vs nesting</head>
- <p>The main consideration for selecting parameters or nesting
- of assertions is that <emph>the framework intersection
- algorithm processes nested alternatives, but does not consider
- parameters in its algorithm</emph>.
- </p>
-
- <p>Assertion Authors should recognize that the framework can
- yield multiple assertions of the same type. The <emph>QName</emph>
- of the assertion is the only vehicle for the framework to
- match a specific assertion, NOT the contents of the
- element. If the assertion is a parameterized assertion the
- authors must understand that this type of assertion will
- require additional processing by consumers in order to
- disambiguate the assertions or to understand the semantics of
- the name value pairs, complex content, attribute values
- contribution to the processing. The tradeoff is the generality
- vs. the flexibility and complexity of the comparison expected for a domain. </p>
- <p>
- The following design questions below can help
- to determine when to use nested policy expressions:</p>
- <ulist>
- <item>
- <p>Are these assertions designed for the same policy subject? </p>
- </item>
- <item>
- <p>Do these assertions represent dependent behaviors?</p>
- </item>
- </ulist>
- <p>If the answers are yes to both of these questions then leveraging nested policy
- expressions is something to consider. Keep in mind that a nested policy expression participates in
- the policy intersection algorithm. If a requester uses policy intersection to select a
- compatible policy alternative then the assertions in a nested policy expression play a
- first class role in the outcome. There is one caveat to watch out for: policy assertions
- with deeply nested policy can greatly increase the complexity of a policy and should be
- avoided when they are not needed.</p>
- <p role="practice" id="bp-nesting"><quote>Nesting of Assertions</quote><quote>If the assertion
- authors want to delegate the processing to the framework,
- utilizing nesting should be considered. Otherwise, domain
- specific comparison algorithms may need to be devised and be
- delegated to the specific domain handlers that are not visible
- to the WS-Policy framework.</quote>
- </p>
- </div3>
</div2>
<div2 id="Ignorable">
<head>Designating Ignorable Behavior</head>
@@ -2389,8 +2413,37 @@
corresponding to editors' action item
<loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/232">256</loc>
- now complete.
+ </td>
+ </tr>
+ <tr>
+ <td>20070513</td>
+ <td>ASV</td>
+ <td>Updated Section 5.4.1 to use the new format re issue
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</loc>.
+ Editors' action
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/230">230</loc>.
</td>
- </tr>
+ </tr>
+ <tr>
+ <td>20070514</td>
+ <td>ASV</td>
+ <td>Updated Section 5.4.2 to use the new format re issue
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</loc>.
+ Editors' action
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/230">230</loc>.
+ Collapsed Section 5.4.2 and 5.4.3.
+ </td>
+ </tr>
+ <tr>
+ <td>20070514</td>
+ <td>ASV</td>
+ <td>Added G11 and G13 to Section 5.4.1 and 5.4.2 re issue
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</loc>.
+ Editors' action
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/252">252</loc> and
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/255">255</loc>.
+ </td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Tuesday, 15 May 2007 02:36:34 UTC