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

2006/ws/policy ws-policy-guidelines.html,1.58,1.59 ws-policy-guidelines.xml,1.73,1.74

From: Prasad Yendluri via cvs-syncmail <cvsmail@w3.org>
Date: Sat, 19 May 2007 01:31:04 +0000
To: public-ws-policy-eds@w3.org
Message-Id: <E1HpDmi-00054P-4c@lionel-hutz.w3.org>

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

Modified Files:
	ws-policy-guidelines.html ws-policy-guidelines.xml 
Log Message:
Updated Appendix E, Changes in this Version of the Document 

Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.58
retrieving revision 1.59
diff -u -d -r1.58 -r1.59
--- ws-policy-guidelines.html	19 May 2007 01:04:21 -0000	1.58
+++ ws-policy-guidelines.html	19 May 2007 01:31:00 -0000	1.59
@@ -159,8 +159,7 @@
 B. <a href="#xml-namespaces">XML Namespaces</a><br>
 C. <a href="#references">References</a><br>
 D. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<br>
-E. <a href="#change-description">Changes in this Version of
-          the Document</a> (Non-Normative)<br>
+E. <a href="#change-description">Changes in this Version of the Document</a> (Non-Normative)<br>
 F. <a href="#change-log">Web Services Policy 1.5 - Guidelines for Policy Assertion Authors Change Log</a> (Non-Normative)<br>
 </p></div><hr><div class="body"><div class="div1">
 <h2><a name="introduction" id="introduction"></a>1. Introduction</h2><p>The WS-Policy specification defines a policy to be a collection
@@ -210,7 +209,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. Start with simple Assertions</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. 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. Avoid Duplicatin 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. 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">
+					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-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
@@ -1043,7 +1042,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">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 
+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
@@ -1497,9 +1496,14 @@
     on public-ws-policy@w3.org</a> are also gratefully
     acknowledged.
   </p></div><div class="div1">
-<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>Editorial changes to align with the OASIS WS-SecurityPolicy specification.</p></li></ul></div><div class="div1">
+<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 
+						<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></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 
 							<a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0033.html">Frederick</a> and 
 							<a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0054.html">Umit</a> to the list of editors.
@@ -1525,8 +1529,7 @@
 						</td></tr><tr><td rowspan="1" colspan="1">20070104</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Resolution of Issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3982">3982</a>
                                                     Based on <a href="http://www.w3.org/2006/12/06-ws-policy-irc#T18-55-00">Minutes for resolution</a>, Minor formatting for consistent use of the term "Assertion Author"
 						</td></tr><tr><td rowspan="1" colspan="1">20070104</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Resolution of Issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3980">3980</a>
-						</td></tr><tr><td rowspan="1" colspan="1">20070108</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Reset Section <a href="#change-description"><b>E. Changes in this Version of
-          the Document</b></a>.
+						</td></tr><tr><td rowspan="1" colspan="1">20070108</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Reset Section <a href="#change-description"><b>E. Changes in this Version of the Document</b></a>.
 						</td></tr><tr><td rowspan="1" colspan="1">20070122</td><td rowspan="1" colspan="1">PY</td><td rowspan="1" colspan="1">Completed action item:
 							<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/127">127</a>
 							Resolution for issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4197">4197</a></td></tr><tr><td rowspan="1" colspan="1">20070130</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Completed action item:
@@ -1591,8 +1594,7 @@
 							for <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4212">issue 4212</a>.
 							Editors' action 
 							<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/207">207</a>.
-						</td></tr><tr><td rowspan="1" colspan="1">20070321</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Updated section <a href="#change-description"><b>E. Changes in this Version of
-          the Document</b></a>. </td></tr><tr><td rowspan="1" colspan="1">20070329</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Changed all &lt;p&gt;Best Practice:  to &lt;p role="practice"&gt;</td></tr><tr><td rowspan="1" colspan="1">20070416</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Updated 6.2 and 6.3 for <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>.  Note, removed one best practice that was a dup.</td></tr><tr><td rowspan="1" colspan="1">20070423</td><td rowspan="1" colspan="1">FJH</td><td rowspan="1" colspan="1">Updated 5.5 Designating Optional Behaviors for 
+						</td></tr><tr><td rowspan="1" colspan="1">20070321</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Updated section <a href="#change-description"><b>E. Changes in this Version of the Document</b></a>. </td></tr><tr><td rowspan="1" colspan="1">20070329</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Changed all &lt;p&gt;Best Practice:  to &lt;p role="practice"&gt;</td></tr><tr><td rowspan="1" colspan="1">20070416</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Updated 6.2 and 6.3 for <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>.  Note, removed one best practice that was a dup.</td></tr><tr><td rowspan="1" colspan="1">20070423</td><td rowspan="1" colspan="1">FJH</td><td rowspan="1" colspan="1">Updated 5.5 Designating Optional Behaviors for 
 							<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>.  Added informative reference for MTOMPolicy. 
 							Added two best practices, one is similar to G16 but focused on optional. Revised practice that was there.</td></tr><tr><td rowspan="1" colspan="1">20070425</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">Updated 5.3 "Considerations when Modeling New Assertions" related to
 							<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>.  [Editorial Action 229] Restructured text to follow examples</td></tr><tr><td rowspan="1" colspan="1">20070425</td><td rowspan="1" colspan="1">TIB</td><td rowspan="1" colspan="1">Updated 5.2 Authoring Styles for 
@@ -1609,8 +1611,7 @@
 							<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/250">250</a>
 							as noted  in <a href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/0069.html">message 69</a>.
 							Also  replaced TBD in section 2 with descriptive text."
-						</td></tr><tr><td rowspan="1" colspan="1">20070501</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Reset Section <a href="#change-description"><b>E. Changes in this Version of
-          the Document</b></a>.
+						</td></tr><tr><td rowspan="1" colspan="1">20070501</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Reset Section <a href="#change-description"><b>E. Changes in this Version of the Document</b></a>.
 						</td></tr><tr><td rowspan="1" colspan="1">20070507</td><td rowspan="1" colspan="1">PY</td><td rowspan="1" colspan="1">Updated 5.6 WSDL guidelines section, to follow the new format and added G15, G16, G17 and G18.
 						Accounts for parts of resolution for  
 							<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>
@@ -1651,4 +1652,6 @@
 						</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
 							<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></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.73
retrieving revision 1.74
diff -u -d -r1.73 -r1.74
--- ws-policy-guidelines.xml	19 May 2007 01:04:22 -0000	1.73
+++ ws-policy-guidelines.xml	19 May 2007 01:31:01 -0000	1.74
@@ -1357,7 +1357,7 @@
 			   </p>
 			   
 				<p role="practice" id="bp-WSDL-policy-multiple-instance-semantics">
-					<quote>Semantics of multiple assertions of the same kind</quote>
+					<quote>Describe Semantics of Multiple Assertions of 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 
@@ -2013,12 +2013,26 @@
           http://www.w3.org/TR/sawsdl/.</bibl>
 			</blist>
 		</div1>&acknowledgements; <inform-div1 id="change-description">
-			<head>Changes in this Version of
-          the Document</head>
+			<head>Changes in this Version of the Document</head>
 			<p>A list of substantive changes since the Working Draft dated 30 March, 
 			2007 is below:</p>
 			<ulist>
-				<item><p>Editorial changes to align with the OASIS WS-SecurityPolicy specification.</p></item>
+				<item>
+				   <p>Reformatted the document to follow the model of the
+				   	<loc href="http://www.w3.org/TR/webarch/#uri-benefits">WWW Architecture Document.</loc>
+					</p>
+				</item>
+				<item>
+					<p>Created a consolidated list of good practices at the beginning of the document 
+					(<specref ref="best-practices-list"/>).
+					</p>
+				</item>
+				<item>
+					<p>Incorporated the good 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>
+				<item><p>Made editorial changes to align with the OASIS WS-SecurityPolicy specification.</p></item>
 			</ulist>
 		</inform-div1>
 		<inform-div1 id="change-log">
@@ -2471,6 +2485,13 @@
 							<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>
+					</tr>
+					<tr>
+						<td>20070518</td>
+						<td>PY</td>
+						<td>Updated Appendix E, Changes in this Version of the Document
+							(<specref ref="change-description"/>). 
+						</td>
 					</tr>					 
 				</tbody>
 			</table>
Received on Saturday, 19 May 2007 01:31:14 GMT

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