W3C home > Mailing lists > Public > public-ws-policy-eds@w3.org > May 2007

2006/ws/policy ws-policy-guidelines.html,1.55,1.56 ws-policy-guidelines.xml,1.70,1.71

From: Prasad Yendluri via cvs-syncmail <cvsmail@w3.org>
Date: Wed, 16 May 2007 15:53:02 +0000
To: public-ws-policy-eds@w3.org
Message-Id: <E1HoLoE-0006he-Cu@lionel-hutz.w3.org>

Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv25684

Modified Files:
	ws-policy-guidelines.html ws-policy-guidelines.xml 
Log Message:
Restructure the sequencing of WSDL guidelines. They were occuring prior to the explanatory text. This bring sit inline with the order folloed by other sections of the document.

Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -d -r1.55 -r1.56
--- ws-policy-guidelines.html	15 May 2007 02:36:21 -0000	1.55
+++ ws-policy-guidelines.html	16 May 2007 15:52:59 -0000	1.56
@@ -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="#d3e265">Who is involved in authoring Assertions? </a><br>
+4. <a href="#d3e262">Who is involved in authoring Assertions? </a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;4.1 <a href="#roles"> Roles and Responsibilities </a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;4.1.1 <a href="#domain-owners"> Assertion Authors</a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;4.1.2 <a href="#consumers">Consumers</a><br>
@@ -139,9 +139,9 @@
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.5.1 <a href="#doc-ignorable-assertions">Assertions and Ignorable Behavior</a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.5.2 <a href="#XML-ignorable-assertions">XML Outline for Ignorable </a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;5.6 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.6.1 <a href="#d3e745">Optional behavior in Compact authoring</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.6.2 <a href="#d3e785">Optional behavior at runtime</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.6.2.1 <a href="#d3e830">Example</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.6.1 <a href="#d3e742">Optional behavior in Compact authoring</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.6.2 <a href="#d3e782">Optional behavior at runtime</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;5.6.2.1 <a href="#d3e827">Example</a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;5.7 <a href="#levels-of-abstraction">Considerations for Policy Attachment in WSDL </a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;5.8 <a href="#interrelated-domains">Interrelated domains</a><br>
 6. <a href="#versioning-policy-assertions">Versioning Policy Assertions</a><br>
@@ -210,7 +210,7 @@
         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-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">
+					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-preferred-attachment-point"><b>24. Preferred attachment point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>25. Semantics of multiple assertions of the same kind</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>26. Independent Assertions</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>27. 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="d3e265" id="d3e265"></a>4. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
+<h2><a name="d3e262" id="d3e262"></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
@@ -813,7 +813,7 @@
 			  	    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="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
+<h4><a name="d3e742" id="d3e742"></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, 
@@ -844,7 +844,7 @@
 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="d3e785" id="d3e785"></a>5.6.2 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
+<h4><a name="d3e782" id="d3e782"></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
@@ -899,7 +899,7 @@
 				</p><div class="boxedtext"><p><a name="bp-indicate-optional-assertion-use" id="bp-indicate-optional-assertion-use"></a><span class="practicelab">Good
 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="d3e830" id="d3e830"></a>5.6.2.1 Example</h5><p>
+<h5><a name="d3e827" id="d3e827"></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. 
@@ -929,25 +929,22 @@
         		associated policy subject. If a policy assertion is to be used
         		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 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 
+        		</p><p>The specific WSDL policy subject is determined with respect to 
 				a behavior as follows:</p><ul><li><p>If the behavior applies to any message exchange
           				using any of the endpoints offered by a service then the
          				subject is the service policy subject. </p></li><li><p>If the behavior applies to any message exchange
           				made using an endpoint then the subject is the endpoint policy subject. </p></li><li><p>If the behavior applies to any message exchange
 	  					defined by an operation then the subject is the operation policy subject. </p></li><li><p>If the behavior applies to an input message then
-	  					the subject is the message policy subject - similarly for output and fault message policy subjects.</p></li></ul><p>Assertion authors that wish to utilize WSDL policy subjects need to 
+	  					the subject is the message policy subject - similarly for output and fault message policy subjects.</p></li></ul><div class="boxedtext"><p><a name="bp-WSDL-policy-subject" id="bp-WSDL-policy-subject"></a><span class="practicelab">Good
+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>Assertion authors that wish to utilize WSDL policy subjects need to 
 				understand how the assertions will be
 				processed in intersection and merging and the implications of
 				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 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
+				</p><p> For a given WSDL policy subject, there may be several
         		attachment points. For example, there are three attachment
         		points for the endpoint policy subject: the port, binding and
         		portType element. Assertion authors should identify the
@@ -970,11 +967,9 @@
         		policy subject instead of a message policy subject. However such 
         		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 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.
+        		</p><div class="boxedtext"><p><a name="bp-WSDL-policy-subject-Granularity" id="bp-WSDL-policy-subject-Granularity"></a><span class="practicelab">Good
+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 authoring convenience, an assertion author may allow the
         		association of an assertion to multiple policy subjects. If an
@@ -983,13 +978,19 @@
         		the burden to describe the semantics of multiple instances of the
         		same assertion attached to multiple policy subjects at the same
         		time in order to avoid conflicting behavior.
-				</p><p>If the capability is not really suitable and may imply
+				</p><div class="boxedtext"><p><a name="bp-WSDL-multiple-policy-subjects" id="bp-WSDL-multiple-policy-subjects"></a><span class="practicelab">Good
+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.
+					</p></div><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 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
+					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><p> 
+					<table border="1" summary="Editorial note"><tr><td align="left" valign="top" width="50%"><b>Editorial note</b></td><td align="right" valign="top" width="50%">&nbsp;</td></tr><tr><td colspan="2" align="left" valign="top">
+							The following paragraph is likely to change, 
+							as there is an open issue 4074 against this paragraph.
+						</td></tr></table>
+				</p><p>The current set of subjects as mapped to the WSDL 1.1
 					elements, can also constrain the assertion constructs. 
 					For Example, in WS-RM, the assertion authors chose to support 
 					certain capabilities at the endpoint level. This resulted in 
@@ -1003,15 +1004,12 @@
 					assertion author can specify additional constraints and assumptions 
 					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 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
+				</p><p>Since many attachment points are available in WSDL, it would be
+				necessary for an assertion author to recommend a preferred attachment 
+				point. One approach would be to identify different attachment points in
 				a policy subject, choose the most granular policy subject that the 
-				behavior applies to and
-				specify that as a preferred attachment point. However, this
-				approach only works if the policy subject is a true WSDL
+				behavior applies to and specify that as a preferred attachment point. 
+				However, this approach only works if the policy subject is a true WSDL
 				construct other than some other protocol concept that is
 				layered over WSDL message exchanges. For example, as described previously
 				the WS-RM Policy is a capability that governs a target endpoints
@@ -1021,13 +1019,10 @@
 				considers when sequences are present. In addition, when the
 				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 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
-					(if any) when there are multiple instances of a policy assertion in 
-					the same policy alternative.
+				</p><div class="boxedtext"><p><a name="bp-WSDL-preferred-attachment-point" id="bp-WSDL-preferred-attachment-point"></a><span class="practicelab">Good
+practice 24: 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>Assertion authors that utilize WSDL policy subjects need to 
 				understand how the assertions will be processed in merging and 
 				the specify implications of ending up with multiple assertions of 
@@ -1043,7 +1038,14 @@
 				at the endpoint could have more than one SignedParts assertion in the
 				same alternative. However, the clear semantics defined by the SignedParts 
 				assertion enable processing of the multiple occurrences properly.	
-			   </p></div><div class="div2">
+			   </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 25: 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
+						(if any) when there are multiple instances of a policy assertion in 
+						the same policy alternative.
+					</p></div></div><div class="div2">
 <h3><a name="interrelated-domains" id="interrelated-domains"></a>5.8 Interrelated domains</h3><p>Assertion authors need to be clear about how assertions defined in  
 				their domain may fit with assertions for interrelated domains. A  
 				classic example of such an interrelated domain is security, because  
@@ -1084,7 +1086,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 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
+practice 26: 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>&lt;Policy&gt;
@@ -1112,7 +1114,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 28: Change of the Policy Subject Over Time</span></p><p class="practice">If the policy subjects change over time, 
+practice 27: 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">

Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.70
retrieving revision 1.71
diff -u -d -r1.70 -r1.71
--- ws-policy-guidelines.xml	15 May 2007 02:36:21 -0000	1.70
+++ ws-policy-guidelines.xml	16 May 2007 15:52:59 -0000	1.71
@@ -1179,13 +1179,6 @@
         		within WSDL, assertion authors must specify a WSDL
         		policy subject. 
         		</p>
-				<p role="practice" id="bp-WSDL-policy-subject">
-					<quote>An assertion description should specify a policy subject</quote>
-					<quote>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.
-				    </quote>
-				</p>
 				
 				<p>The specific WSDL policy subject is determined with respect to 
 				a behavior as follows:</p>
@@ -1208,6 +1201,15 @@
 	  					the subject is the message policy subject - similarly for output and fault message policy subjects.</p>
 					</item>
 				</ulist>
+				
+				<p role="practice" id="bp-WSDL-policy-subject">
+					<quote>An assertion description should specify a policy subject</quote>
+					<quote>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.
+					</quote>
+				</p>
+				
 				<p>Assertion authors that wish to utilize WSDL policy subjects need to 
 				understand how the assertions will be
 				processed in intersection and merging and the implications of
@@ -1215,13 +1217,6 @@
 				policy subject. This topic is considered in detail in <bibref ref="WS-Policy-Primer"/>
 				</p>
 				
-				<p role="practice" id="bp-WSDL-policy-subject-Granularity">
-					<quote>Granularity of policy subjects</quote>
-					<quote>Assertion authors should choose the most granular policy subject 
-					that the behavior represented by a policy assertion applies to.
-					</quote>
-				</p>
-				
 				<p> For a given WSDL policy subject, there may be several
         		attachment points. For example, there are three attachment
         		points for the endpoint policy subject: the port, binding and
@@ -1248,15 +1243,13 @@
         		should be done only after careful evaluation. 
         		</p>
         		
-				<p role="practice" id="bp-WSDL-multiple-policy-subjects">
-					<quote>Assertion attachment to multiple policy subjects</quote>
-					<quote>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.
+				<p role="practice" id="bp-WSDL-policy-subject-Granularity">
+					<quote>Granularity of policy subjects</quote>
+					<quote>Assertion authors should choose the most granular policy subject 
+						that the behavior represented by a policy assertion applies to.
 					</quote>
-				</p>
-				
+				</p>				
+        		
         		<p>
         		For authoring convenience, an assertion author may allow the
         		association of an assertion to multiple policy subjects. If an
@@ -1267,6 +1260,15 @@
         		time in order to avoid conflicting behavior.
 				</p>
 				
+				<p role="practice" id="bp-WSDL-multiple-policy-subjects">
+					<quote>Assertion attachment to multiple policy subjects</quote>
+					<quote>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.
+					</quote>
+				</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>
@@ -1279,14 +1281,15 @@
 					</item>
 				</ulist>
 				
-				<p role="practice" id="bp-WSDL-policy-scope-semantics">
-					<quote>Fully specify constraints on policy scope</quote>
-					<quote>Assertion authors must clearly describe any constraints on the 
-					policy scope if not limited to policy subjects identified by the policy 
-					attachment point.
-					</quote>
+				<p> 
+					<ednote> 
+						<edtext>
+							The following paragraph is likely to change, 
+							as there is an open issue 4074 against this paragraph.
+						</edtext>
+					</ednote>
 				</p>
-					
+				
 				<p>The current set of subjects as mapped to the WSDL 1.1
 					elements, can also constrain the assertion constructs. 
 					For Example, in WS-RM, the assertion authors chose to support 
@@ -1303,19 +1306,12 @@
 					must be clearly specified by the assertion authors.
 				</p>
 				
-				<p role="practice" id="bp-WSDL-preferred-attachment-point">
-					<quote>Preferred attachment point for an Assertion</quote>
-					<quote>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.
-					</quote>
-				</p>
-				
-				<p>One approach in WSDL is to identify different attachment points in
+				<p>Since many attachment points are available in WSDL, it would be
+				necessary for an assertion author to recommend a preferred attachment 
+				point. One approach would be to identify different attachment points in
 				a policy subject, choose the most granular policy subject that the 
-				behavior applies to and
-				specify that as a preferred attachment point. However, this
-				approach only works if the policy subject is a true WSDL
+				behavior applies to and specify that as a preferred attachment point. 
+				However, this approach only works if the policy subject is a true WSDL
 				construct other than some other protocol concept that is
 				layered over WSDL message exchanges. For example, as described previously
 				the WS-RM Policy is a capability that governs a target endpoints
@@ -1327,16 +1323,14 @@
 				rather abstract requirements, this technique does not apply. 
 				</p>
 				
-				<p role="practice" id="bp-WSDL-policy-multiple-instance-semantics">
-					<quote>Semantics of multiple assertions of the same kind</quote>
-					<quote>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
-					(if any) when there are multiple instances of a policy assertion in 
-					the same policy alternative.
+				<p role="practice" id="bp-WSDL-preferred-attachment-point">
+					<quote>Preferred attachment point for an Assertion</quote>
+					<quote>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.
 					</quote>
 				</p>
+				
 				<p>Assertion authors that utilize WSDL policy subjects need to 
 				understand how the assertions will be processed in merging and 
 				the specify implications of ending up with multiple assertions of 
@@ -1353,6 +1347,17 @@
 				same alternative. However, the clear semantics defined by the SignedParts 
 				assertion enable processing of the multiple occurrences properly.	
 			   </p>
+			   
+				<p role="practice" id="bp-WSDL-policy-multiple-instance-semantics">
+					<quote>Semantics of multiple assertions of the same kind</quote>
+					<quote>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
+						(if any) when there are multiple instances of a policy assertion in 
+						the same policy alternative.
+					</quote>
+				</p>
 				
 			</div2>
 		<div2 id="interrelated-domains">
Received on Wednesday, 16 May 2007 15:53:05 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:21:03 GMT