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

2006/ws/policy ws-policy-guidelines.html,1.63,1.64 xmlspec-policy.xsl,1.9,1.10 ws-policy-guidelines.xml,1.77,1.78

From: Prasad Yendluri via cvs-syncmail <cvsmail@w3.org>
Date: Tue, 29 May 2007 21:37:34 +0000
To: public-ws-policy-eds@w3.org
Message-Id: <E1Ht9Nm-0001bu-IM@lionel-hutz.w3.org>

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

Modified Files:
	ws-policy-guidelines.html xmlspec-policy.xsl 
	ws-policy-guidelines.xml 
Log Message:
Implemented resolution for Isssue 4573 use "Best Practice" everywhere.

Index: xmlspec-policy.xsl
===================================================================
RCS file: /sources/public/2006/ws/policy/xmlspec-policy.xsl,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- xmlspec-policy.xsl	24 May 2007 14:29:09 -0000	1.9
+++ xmlspec-policy.xsl	29 May 2007 21:37:31 -0000	1.10
@@ -226,7 +226,7 @@
                 <a name="{@id}" id="{@id}"/>
                 <span class="practicelab">
                     <xsl:text>Best
-practice </xsl:text>
+Practice </xsl:text>
                     <xsl:value-of select="$practicenumber"/>
                     <xsl:text>: </xsl:text>
                     <xsl:value-of select="quote[1]"/>

Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.63
retrieving revision 1.64
diff -u -d -r1.63 -r1.64
--- ws-policy-guidelines.html	24 May 2007 17:19:00 -0000	1.63
+++ ws-policy-guidelines.html	29 May 2007 21:37:31 -0000	1.64
@@ -117,7 +117,7 @@
 <h2><a name="status" id="status"></a>Status of this Document</h2><p><strong>This document is an editors' copy that has
         no official standing.</strong></p><p></p></div><div class="toc">
 <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>
+2. <a href="#best-practices-list">List of Best 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>
 &nbsp;&nbsp;&nbsp;&nbsp;4.1 <a href="#roles"> Roles and Responsibilities </a><br>
@@ -208,7 +208,7 @@
         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 Independent of 
+<h2><a name="best-practices-list" id="best-practices-list"></a>2. List of Best Practice Statements</h2><p>The following Best 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 Independent of 
 				Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-semantics-and-form"><b>3. Semantics Independent of the Form</b></a></p></li><li><p><a href="#bp-assertion-start"><b>4. Start with Simple Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>5. Use Unique QNames</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>6. Specify Semantics Clearly</b></a></p></li><li><p><a href="#XMLOutline"><b>7. Provide an XML Outline</b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>8. Not Necessary to Understand a Message</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>9. Avoid Duplication of Assertions</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. Assertion Description Should Specify a Policy Subject</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>22. Choose a Granular Policy Subject</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>23. Define Semantics of Attachment to Multiple Policy Subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>24. Specify Preferred Attachment Point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>25. Describe Semantics of Multiple Assertions of Same Kind</b></a></p></li><li><p><a href="#bp-specify-composition"><b>26. Specify Composition with Related Assertions</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>27. Use Independent Assertions for Multple Versions of a Behavior</b></a></p></li><li><p><a href="#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
@@ -391,7 +391,7 @@
 				to consider how its presence must interact with other policy assertions that
 				are defined for security.
 				</p><div class="boxedtext"><p><a name="bp-assertion-specification-parts" id="bp-assertion-specification-parts"></a><span class="practicelab">Best
-practice 1: Parts of an Assertion Specification</span></p><p class="practice">
+Practice 1: Parts of an Assertion Specification</span></p><p class="practice">
 					Assertion Authors should include the following items in an 
 					assertion specification: </p></div><p>
 					<ul><li><p><em>The definition of the assertion's semantic.</em> </p></li><li><p><em>The specification of the set of valid policy subjects to which an 
@@ -416,7 +416,7 @@
 				allows policy tools to choose the most appropriate mechanism to attach a 
 				policy without having to analyze the contents of the policy. 
 				</p><div class="boxedtext"><p><a name="bp-assertion-semantics" id="bp-assertion-semantics"></a><span class="practicelab">Best
-practice 2: Semantics Independent of 
+Practice 2: Semantics Independent of 
 				Attachment Mechanisms</span></p><p class="practice">
 			    The semantics of a policy assertion should not depend on the 
 				attachment mechanism used.</p></div><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">April 25th 07, editors 
@@ -448,7 +448,7 @@
 				description for a policy assertion should not depend on the style used
 				to author a policy expression that contains the assertion.
 			</p><div class="boxedtext"><p><a name="bp-semantics-and-form" id="bp-semantics-and-form"></a><span class="practicelab">Best
-practice 3: Semantics Independent of the Form</span></p><p class="practice">The semantics of an assertion should be independent of
+Practice 3: Semantics Independent of the Form</span></p><p class="practice">The semantics of an assertion should be independent of
 					the form (compact or normal form) of policy expressions that contain the
 					assertion.</p></div><p>
 				In the example below, the policy expression is shown in its two forms,
@@ -545,7 +545,7 @@
 					work progresses, one may add more parameters or nested policy assertions 
 					to meet one's interoperability needs. 
          			</p><div class="boxedtext"><p><a name="bp-assertion-start" id="bp-assertion-start"></a><span class="practicelab">Best
-practice 4: Start with Simple Assertion</span></p><p class="practice">An assertion author should start with a simple working assertion 
+Practice 4: Start with Simple Assertion</span></p><p class="practice">An assertion author should start with a simple working assertion 
           				that allows assertion parameter extensibility. </p></div><p>New Assertion Authors are encouraged to look at <cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite> to see an example of a
          			relatively simple domain that has defined three assertions. Assertion Authors are encouraged to look at <cite><a href="#WS-SecurityPolicy">WS-SecurityPolicy</a></cite> to see an example of a complex domain that has been decomposed into a set of policy expressions.
         			</p></div><div class="div3">
@@ -557,7 +557,7 @@
             		or an attribute of an assertion. The general guidelines on when to use XML elements
           			versus attributes apply is. Use a unique QName to identify a distinct behavior and provide 
           			an XML outline (plus an XML schema document) to specify the syntax of an assertion. </p><div class="boxedtext"><p><a name="bp-unique-qnames" id="bp-unique-qnames"></a><span class="practicelab">Best
-practice 5: Use Unique QNames</span></p><p class="practice">An assertion author should use a unique QName to identify a distinct behavior.</p></div><p>The syntax of an assertion can be represented using an XML outline (plus an XML schema
+Practice 5: Use Unique QNames</span></p><p class="practice">An assertion author should use a unique QName to identify a distinct behavior.</p></div><p>The syntax of an assertion can be represented using an XML outline (plus an XML schema
             		document). If the assertion has a nested policy expression then the assertion XML
             		outline can enumerate the nested assertions that are allowed. An example is the following:
             		</p><div class="exampleOuter"><div class="exampleInner"><pre>
@@ -576,10 +576,10 @@
 &lt;/sp:IssuedToken&gt;
  
  </pre></div></div><div class="boxedtext"><p><a name="AssertionDefinitions" id="AssertionDefinitions"></a><span class="practicelab">Best
-practice 6: Specify Semantics Clearly</span></p><p class="practice"> An assertion description must clearly and completely specify the semantics of a policy 
+Practice 6: Specify Semantics Clearly</span></p><p class="practice"> An assertion description must clearly and completely specify the semantics of a policy 
 			  	    assertion.
 			  	    </p></div><div class="boxedtext"><p><a name="XMLOutline" id="XMLOutline"></a><span class="practicelab">Best
-practice 7: Provide an XML Outline</span></p><p class="practice"> An assertion description should provide an XML outline plus an XML schema to specify the
+Practice 7: Provide an XML Outline</span></p><p class="practice"> An assertion description should provide an XML outline plus an XML schema to specify the
 			  	    syntax of the assertion.
 			  	    </p></div><div class="exampleOuter"><div class="exampleInner"><pre>
  &lt;wsrmp:RMAssertion [wsp:Optional="true"]? ...&gt; 
@@ -616,7 +616,7 @@
      				their assertions by specifying additional properties, headers,
      				etc. that must be present in a message as part of their assertion design.
      				</p><div class="boxedtext"><p><a name="bp-not-necessary-to-understand-a-message" id="bp-not-necessary-to-understand-a-message"></a><span class="practicelab">Best
-practice 8: Not Necessary to Understand a Message</span></p><p class="practice">An assertion author should not define policy assertions to represent information that is necessary to understand a message.</p></div><p>For example, if the details of a message's encryption ( e.g., the cipher used, etc) are expressed
+Practice 8: Not Necessary to Understand a Message</span></p><p class="practice">An assertion author should not define policy assertions to represent information that is necessary to understand a message.</p></div><p>For example, if the details of a message's encryption ( e.g., the cipher used, etc) are expressed
      				in policy that isn't attached to the message, it isn't possible
      				to later decipher it. This is very different from expressing, in
      				policy, what ciphers (and so forth) are supported by a particular
@@ -646,7 +646,7 @@
 					</p><p>It is the responsibility of the assertion authors to avoid duplication of assertions. 
 					A review by a broad community is the best way to ensure that the granularity of a set 
 					of domain assertions is appropriate.</p><div class="boxedtext"><p><a name="bp-assertion-duplication" id="bp-assertion-duplication"></a><span class="practicelab">Best
-practice 9: Avoid Duplication of Assertions</span></p><p class="practice">An assertion author should reuse an existing assertion (rather than create a new one) whenever possible.</p></div></div></div><div class="div2">
+Practice 9: Avoid Duplication of Assertions</span></p><p class="practice">An assertion author should reuse an existing assertion (rather than create a new one) whenever possible.</p></div></div></div><div class="div2">
 <h3><a name="comparison" id="comparison"></a>5.4 Comparison of Nested and Parameterized Assertions</h3><p>There are two different ways to provide additional information in an
 				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.  
@@ -661,7 +661,7 @@
 					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">Best
-practice 10: Use Parameters for Useful 
+Practice 10: Use Parameters for Useful 
 					Information</span></p><p class="practice">An assertion author should represent useful (or additional) 
                         information necessary for engaging the behavior represented by a policy 
                         assertion as assertion parameters.	
@@ -695,10 +695,10 @@
 						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">Best
-practice 11: Use Nested Assertions for Dependent Behaviors</span></p><p class="practice">An assertion author should represent dependent behaviors that are relevant 
+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">Best
-practice 12: Declare Nested Assertions</span></p><p class="practice">If there is a nested policy expression, an assertion description should declare it 
+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
@@ -720,7 +720,7 @@
 						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">Best
-practice 13: Discourage Domain Specific Intersection</span></p><p class="practice">An 
+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
@@ -807,7 +807,7 @@
 &lt;/sp:TransportToken&gt;</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><div class="div2">
-<h3><a name="Ignorable" id="Ignorable"></a>5.5 Designating Ignorable Behavior</h3><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">Looks incomplete – carries Good Practices but there isn’t any explanatory text.</td></tr></table><p>Policy assertions can be marked with an attribute to indicate that the assertion
+<h3><a name="Ignorable" id="Ignorable"></a>5.5 Designating Ignorable Behavior</h3><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">Looks incomplete – carries Best Practices but there isn’t any explanatory text.</td></tr></table><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 
 			  	intersection, and indicate this in the definition of the assertion.  The use of the 
@@ -816,11 +816,11 @@
 			  	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">Best
-practice 14: 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">Best
-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
+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">
@@ -839,7 +839,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">Best
-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 
+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">
@@ -847,7 +847,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">Best
-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 
+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">
@@ -862,7 +862,7 @@
 					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">Best
-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 
+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
@@ -894,7 +894,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">Best
-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 
+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
@@ -908,7 +908,7 @@
 					(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">Best
-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, 
+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="d3e851" id="d3e851"></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 
@@ -925,7 +925,7 @@
 					inbound message to a web service that requires MTOM must adhere to  Optimized MIME 
 					Serialization. By examining the message, the provider can determine whether the policy
 					alternate that contains the MTOM assertion is being obeyed (
-						<a href="#bp-indicate-optional-assertion-use">Good Practice: Indicate use of an Optional Assertion</a>).
+						<a href="#bp-indicate-optional-assertion-use">Best Practice: Indicate use of an Optional Assertion</a>).
 				</p><p>
 					Note that if a MTOM assertion were only bound to an inbound message endpoint, 
 					then it would not be clear whether the outbound message from the provider would 
@@ -934,7 +934,7 @@
 					to avoid inappropriate assumptions by implementations. This is important for an 
 					optional assertion where  it may not be clear whether it is to apply in a message 
 					exchange when optionally used in part of that exchange  
-					(<a href="#bp-entire-mep-for-optional">Good Practice: Consider entire message exchange pattern when specifying Assertions that may be optional</a>).
+					(<a href="#bp-entire-mep-for-optional">Best Practice: Consider entire message exchange pattern when specifying Assertions that may be optional</a>).
 				</p></div></div></div><div class="div2">
 <h3><a name="levels-of-abstraction" id="levels-of-abstraction"></a>5.7 Considerations for Policy Attachment in WSDL </h3><p>A behavior identified by a policy assertion applies to the
         		associated policy subject. If a policy assertion is to be used
@@ -947,7 +947,7 @@
           				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><div class="boxedtext"><p><a name="bp-WSDL-policy-subject" id="bp-WSDL-policy-subject"></a><span class="practicelab">Best
-practice 21: Assertion Description Should Specify a Policy Subject</span></p><p class="practice">Assertion authors should associate assertions with the appropriate policy subject.  
+Practice 21: 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 
@@ -979,7 +979,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-policy-subject-Granularity" id="bp-WSDL-policy-subject-Granularity"></a><span class="practicelab">Best
-practice 22: Choose a Granular Policy Subject</span></p><p class="practice">Assertion authors should choose the most granular policy subject 
+Practice 22: Choose a Granular Policy Subject</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
@@ -990,7 +990,7 @@
         		same assertion attached to different policy subjects at the same
         		time in order to avoid conflicting behavior.
 				</p><div class="boxedtext"><p><a name="bp-WSDL-multiple-policy-subjects" id="bp-WSDL-multiple-policy-subjects"></a><span class="practicelab">Best
-practice 23: Define Semantics of Attachment to Multiple Policy Subjects</span></p><p class="practice">If an assertion is allowed to be associated with multiple policy 
+Practice 23: Define Semantics of 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.
@@ -1031,7 +1031,7 @@
 				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-preferred-attachment-point" id="bp-WSDL-preferred-attachment-point"></a><span class="practicelab">Best
-practice 24: Specify Preferred Attachment Point for an Assertion</span></p><p class="practice">If an assertion can be attached at multiple points within a policy 
+Practice 24: Specify 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 
@@ -1050,7 +1050,7 @@
 				same alternative. However, the clear semantics defined by the SignedParts 
 				assertion enable processing of the multiple occurrences properly.	
 			   </p><div class="boxedtext"><p><a name="bp-WSDL-policy-multiple-instance-semantics" id="bp-WSDL-policy-multiple-instance-semantics"></a><span class="practicelab">Best
-practice 25: Describe Semantics of Multiple Assertions of Same Kind</span></p><p class="practice">A policy alternative can contain multiple instances of the 
+Practice 25: Describe Semantics of Multiple Assertions of 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
@@ -1069,7 +1069,7 @@
 				assertions and should also make sure that when adding assertions those new assertions are consistent  
 				with pre-existing assertions of any  
 				interrelated domain. </p><div class="boxedtext"><p><a name="bp-specify-composition" id="bp-specify-composition"></a><span class="practicelab">Best
-practice 26: Specify Composition with Related Assertions</span></p><p class="practice">An assertion description should clearly specify how the assertion may compose 
+Practice 26: Specify Composition with Related Assertions</span></p><p class="practice">An assertion description should clearly specify how the assertion may compose 
 				with other related assertions, if any.</p></div></div></div><div class="div1">
 <h2><a name="versioning-policy-assertions" id="versioning-policy-assertions"></a>6. Versioning Policy Assertions</h2><p>Assertion 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 to versioning policy assetions:</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 
@@ -1099,7 +1099,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">Best
-practice 27: Use Independent Assertions for Multiple Versions of a Behavior</span></p><p class="practice">An assertion author should use independent assertions for modeling multiple 
+Practice 27: Use Independent Assertions for Multiple Versions of a Behavior</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">
@@ -1112,7 +1112,7 @@
   &lt;sp:Wss11&gt;…&lt;/sp:Wss11&gt;
 &lt;/Policy&gt;</pre></div></div></div><div class="div2">
 <h3><a name="supporting-new-policy-subjects" id="supporting-new-policy-subjects"></a>6.3 Supporting New Policy Subjects</h3><p>
-				The <a href="#bp-assertion-specification-parts">Good practice: Parts of an Assertion Specification</a> specifies that policy authors should 
+				The <a href="#bp-assertion-specification-parts">Best Practice: Parts of an Assertion Specification</a> specifies that policy authors should 
 				define the set of policy subjects to which policy assertions can be 
 				attached.  Over time, new policy subjects may need to be defined.  When 
 				this occurs, a policy assertion author may update the list of policy 
@@ -1128,7 +1128,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">Best
-practice 28: 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">
@@ -1519,9 +1519,9 @@
 <h2><a name="change-description" id="change-description"></a>E. Changes in this Version of the Document (Non-Normative)</h2><p>A list of substantive changes since the Working Draft dated 30 March, 
 			2007 is below:</p><ul><li><p>Reformatted the document to follow the model of the
 				   	<a href="http://www.w3.org/TR/webarch/#uri-benefits">WWW Architecture Document.</a>
-					</p></li><li><p>Created a consolidated list of good practices at the beginning of the document 
-					(<a href="#best-practices-list"><b>2. List of Good Practice Statements</b></a>).
-					</p></li><li><p>Incorporated the good practices from 
+					</p></li><li><p>Created a consolidated list of Best Practices at the beginning of the document 
+					(<a href="#best-practices-list"><b>2. List of Best Practice Statements</b></a>).
+					</p></li><li><p>Incorporated the Best Practices from 
 						<a href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/att-0069/good-practices-4-assertion-authors-03-05-2007.pdf">IBM/Microsoft Contibution.</a>
 					</p></li><li><p>Made editorial changes to align with the OASIS WS-SecurityPolicy specification.</p></li><li><p>Made editorial changes to align with the W3C WS-Addressing 1.0 Metadata specification.</p></li></ul></div><div class="div1">
 <h2><a name="change-log" id="change-log"></a>F. Web Services Policy 1.5 - Guidelines for Policy Assertion Authors Change Log (Non-Normative)</h2><a name="ws-policy-primer-changelog-table"></a><table border="1"><tbody><tr><th rowspan="1" colspan="1">Date</th><th rowspan="1" colspan="1">Author</th><th rowspan="1" colspan="1">Description</th></tr><tr><td rowspan="1" colspan="1">20060829</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Created first draft based on agreed outline and content</td></tr><tr><td rowspan="1" colspan="1">20061013</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Editorial fixes (suggested by Frederick), fixed references, bibl items, fixed dangling pointers, created eds to do</td></tr><tr><td rowspan="1" colspan="1">20061018</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">Editorial fixes for readability, added example for Encrypted parts</td></tr><tr><td rowspan="1" colspan="1">20061030</td><td rowspan="1" colspan="1">UY</td><td rospan="1" colspan="1">Fixes for Paul Cotton's editorial comments (20061020)</td></tr><tr><td rowspan="1" colspan="1">20061031</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Fixes for Frederick's editorial comments (20061025)</td></tr><tr><td rowspan="1" colspan="1">20061031</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Optionality discussion feedback integration</td></tr><tr><td rowspan="1" colspan="1">20061115</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">First attempt at restructuring to include primer content</td></tr><tr><td rowspan="1" colspan="1">20061120</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">Restructure to address action items 64,77, which refer to bugzilla 3705 and F2F RESOLUTION 3792 </td></tr><tr><td rowspan="1" colspan="1">20061127</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Updated the list of editors. Added 
@@ -1600,6 +1600,7 @@
 							<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4073">4073</a>
 							in response to editor's action 
 							<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/199">199 </a>
+
 							as outlined in 
 							<a href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/0093.html">proposal </a>.
 							</td></tr><tr><td rowspan="1" colspan="1">20070320</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Implemented the <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4319#c1">resolution</a> 
@@ -1669,17 +1670,17 @@
 							<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/255">255</a>. 
 						</td></tr><tr><td rowspan="1" colspan="1">20070516</td><td rowspan="1" colspan="1">PY</td><td rowspan="1" colspan="1">Editorial change to section 5.7 to place best practices after the associated 
 						    explanatory text and to fix grammar. 
-						</td></tr><tr><td rowspan="1" colspan="1">20070518</td><td rowspan="1" colspan="1">PY</td><td rowspan="1" colspan="1">Ensured Good Practices G1, G3 and G20 of
+						</td></tr><tr><td rowspan="1" colspan="1">20070518</td><td rowspan="1" colspan="1">PY</td><td rowspan="1" colspan="1">Ensured Best Practices G1, G3 and G20 of
 							<a href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/att-0069/good-practices-4-assertion-authors-03-05-2007.pdf">original IBM/MS Contribution</a> 
 						    are reflected. 
 						</td></tr><tr><td rowspan="1" colspan="1">20070518</td><td rowspan="1" colspan="1">PY</td><td rowspan="1" colspan="1">Updated Appendix E, Changes in this Version of the Document
 							(<a href="#change-description"><b>E. Changes in this Version of the Document</b></a>). 
-						</td></tr><tr><td rowspan="1" colspan="1">20070520</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Added Good Practice <a href="#bp-specify-composition"><b>26. Specify Composition with Related Assertions</b></a> (from
+						</td></tr><tr><td rowspan="1" colspan="1">20070520</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Added Best Practice <a href="#bp-specify-composition"><b>26. Specify Composition with Related Assertions</b></a> (from
 							the <a href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/att-0069/good-practices-4-assertion-authors-03-05-2007.pdf">IBM 
 							and MS Contribution</a> to 
 							<a href="#interrelated-domains"><b>5.8 Interrelated domains</b></a>. Added an ed note that 
 							Section <a href="#interrelated-domains"><b>5.8 Interrelated domains</b></a> needs to be re-structured.
-						</td></tr><tr><td rowspan="1" colspan="1">20070520</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Added Good Practice <a href="#bp-not-necessary-to-understand-a-message"><b>8. Not Necessary to Understand a Message</b></a> (from
+						</td></tr><tr><td rowspan="1" colspan="1">20070520</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Added Best Practice <a href="#bp-not-necessary-to-understand-a-message"><b>8. Not Necessary to Understand a Message</b></a> (from
 							the <a href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/att-0069/good-practices-4-assertion-authors-03-05-2007.pdf">IBM 
 								and MS Contribution</a> to 
 							<a href="#self-describing"><b>5.3.3  Self Describing Messages </b></a>.
@@ -1687,9 +1688,11 @@
 							Section <a href="#Ignorable"><b>5.5 Designating Ignorable Behavior</b></a> looks incomplete.
 						</td></tr><tr><td rowspan="1" colspan="1">20070520</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Fixed typos.
 						</td></tr><tr><td rowspan="1" colspan="1">20070520</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Added an ed note in Section <a href="#assertion-target"><b>5.1 Assertions and Their Target Use</b></a> that 
-						there is an open issue against Good Practice G2.
+						there is an open issue against Best Practice G2.
 						</td></tr><tr><td rowspan="1" colspan="1">20070524</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Editorial changes to align with the W3C WS-Addressing Metadata specification.
       For <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4375">issue 4375</a>.
       Editors' action 
       <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/284">284</a>.
-    </td></tr></tbody></table><br></div></div></body></html>
\ No newline at end of file
+    </td></tr><tr><td rowspan="1" colspan="1">20070529</td><td rowspan="1" colspan="1">PY</td><td rowspan="1" colspan="1">Implemented Resolution for <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4573">issue 4573</a>.
+							Apply "Best Practices" consistently.
+						</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.77
retrieving revision 1.78
diff -u -d -r1.77 -r1.78
--- ws-policy-guidelines.xml	24 May 2007 17:19:00 -0000	1.77
+++ ws-policy-guidelines.xml	29 May 2007 21:37:31 -0000	1.78
@@ -150,8 +150,8 @@
         </p>
     </div1>
       <div1 id="best-practices-list">
-          <head>List of Good Practice Statements</head>
-          <p>The following good practices appear in this document with discussion and examples, and are summarized here for quick reference:</p>
+          <head>List of Best Practice Statements</head>
+          <p>The following Best Practices appear in this document with discussion and examples, and are summarized here for quick reference:</p>
           &guidelines-bestpractices;
       </div1>
 	<div1 id="Assertions">
@@ -1017,7 +1017,7 @@
 		    <div2 id="Ignorable">
 				<head>Designating Ignorable Behavior</head>
 				<ednote>
-					<edtext>Looks incomplete – carries Good Practices but there isn’t any explanatory text.</edtext>
+					<edtext>Looks incomplete – carries Best Practices but there isn’t any explanatory text.</edtext>
 				</ednote>
 				<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
@@ -1182,7 +1182,7 @@
 					inbound message to a web service that requires MTOM must adhere to  Optimized MIME 
 					Serialization. By examining the message, the provider can determine whether the policy
 					alternate that contains the MTOM assertion is being obeyed (
-						<loc href="#bp-indicate-optional-assertion-use">Good Practice: Indicate use of an Optional Assertion</loc>).
+						<loc href="#bp-indicate-optional-assertion-use">Best Practice: Indicate use of an Optional Assertion</loc>).
 				</p><p>
 					Note that if a MTOM assertion were only bound to an inbound message endpoint, 
 					then it would not be clear whether the outbound message from the provider would 
@@ -1191,7 +1191,7 @@
 					to avoid inappropriate assumptions by implementations. This is important for an 
 					optional assertion where  it may not be clear whether it is to apply in a message 
 					exchange when optionally used in part of that exchange  
-					(<loc href="#bp-entire-mep-for-optional">Good Practice: Consider entire message exchange pattern when specifying Assertions that may be optional</loc>).
+					(<loc href="#bp-entire-mep-for-optional">Best Practice: Consider entire message exchange pattern when specifying Assertions that may be optional</loc>).
 				</p>
 					</div4>
 			</div3>
@@ -1497,7 +1497,7 @@
 		<div2 id="supporting-new-policy-subjects">
 			<head>Supporting New Policy Subjects</head>
 			<p>
-				The <loc href="#bp-assertion-specification-parts">Good practice: Parts of an Assertion Specification</loc> specifies that policy authors should 
+				The <loc href="#bp-assertion-specification-parts">Best Practice: Parts of an Assertion Specification</loc> specifies that policy authors should 
 				define the set of policy subjects to which policy assertions can be 
 				attached.  Over time, new policy subjects may need to be defined.  When 
 				this occurs, a policy assertion author may update the list of policy 
@@ -2071,12 +2071,12 @@
 					</p>
 				</item>
 				<item>
-					<p>Created a consolidated list of good practices at the beginning of the document 
+					<p>Created a consolidated list of Best Practices at the beginning of the document 
 					(<specref ref="best-practices-list"/>).
 					</p>
 				</item>
 				<item>
-					<p>Incorporated the good practices from 
+					<p>Incorporated the Best Practices from 
 						<loc href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/att-0069/good-practices-4-assertion-authors-03-05-2007.pdf">IBM/Microsoft Contibution.</loc>
 					</p>
 				</item>
@@ -2530,7 +2530,7 @@
 					<tr>
 						<td>20070518</td>
 						<td>PY</td>
-						<td>Ensured Good Practices G1, G3 and G20 of
+						<td>Ensured Best Practices G1, G3 and G20 of
 							<loc href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/att-0069/good-practices-4-assertion-authors-03-05-2007.pdf">original IBM/MS Contribution</loc> 
 						    are reflected. 
 						</td>
@@ -2545,7 +2545,7 @@
 					<tr>
 						<td>20070520</td>
 						<td>ASV</td>
-						<td>Added Good Practice <specref ref="bp-specify-composition"/> (from
+						<td>Added Best Practice <specref ref="bp-specify-composition"/> (from
 							the <loc href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/att-0069/good-practices-4-assertion-authors-03-05-2007.pdf">IBM 
 							and MS Contribution</loc> to 
 							<specref ref="interrelated-domains"/>. Added an ed note that 
@@ -2555,7 +2555,7 @@
 					<tr>
 						<td>20070520</td>
 						<td>ASV</td>
-						<td>Added Good Practice <specref ref="bp-not-necessary-to-understand-a-message"/> (from
+						<td>Added Best Practice <specref ref="bp-not-necessary-to-understand-a-message"/> (from
 							the <loc href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/att-0069/good-practices-4-assertion-authors-03-05-2007.pdf">IBM 
 								and MS Contribution</loc> to 
 							<specref ref="self-describing"/>.
@@ -2578,10 +2578,10 @@
 						<td>20070520</td>
 						<td>ASV</td>
 						<td>Added an ed note in Section <specref ref="assertion-target"/> that 
-						there is an open issue against Good Practice G2.
+						there is an open issue against Best Practice G2.
 						</td>
 					</tr>
-					<tr>
+	<tr>				
     <td>20070524</td>
     <td>DBO</td>
     <td>Editorial changes to align with the W3C WS-Addressing Metadata specification.
@@ -2589,7 +2589,14 @@
       Editors' action 
       <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/284">284</loc>.
     </td>
-  </tr>                       			 
+  </tr>     
+					<tr>
+						<td>20070529</td>
+						<td>PY</td>
+						<td>Implemented Resolution for <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4573">issue 4573</loc>.
+							Apply "Best Practices" consistently.
+						</td>
+					</tr>                  			 
 				</tbody>
 			</table>
 		</inform-div1>
Received on Tuesday, 29 May 2007 21:37:38 GMT

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