- From: Asir Vedamuthu via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 19 Jun 2007 03:03:02 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv14008
Modified Files:
ws-policy-guidelines.html ws-policy-guidelines.xml
Log Message:
Implemented Editors' action 295
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.76
retrieving revision 1.77
diff -u -d -r1.76 -r1.77
--- ws-policy-guidelines.html 17 Jun 2007 05:14:27 -0000 1.76
+++ ws-policy-guidelines.html 19 Jun 2007 03:02:59 -0000 1.77
@@ -210,7 +210,7 @@
</p></div><div class="div1">
<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-semantics"><b>1. Semantics Independent of
Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-semantics-and-form"><b>2. Semantics Independent of the Form</b></a></p></li><li><p><a href="#bp-assertion-start"><b>3. Start with Simple Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>4. Use Unique QNames</b></a></p></li><li><p><a href="#XMLOutline"><b>5. Provide an XML Outline</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>6. Specify Semantics Clearly</b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>7. Not Necessary to Understand a Message</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>8. Avoid Duplication of Assertions</b></a></p></li><li><p><a href="#bp-assertion-parameters"><b>9. Use Parameters for Useful
- Information</b></a></p></li><li><p><a href="#bp-dependent-behaviors"><b>10. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>11. Enumerate Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>12. Discourage Domain Specific Intersection</b></a></p></li><li><p><a href="#DefineIgnorable"><b>13. Assertions Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>14. Ignorable Attribute in XML</b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>15. Assertion XML should allow use of wsp:Optional attribute</b></a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional"><b>16. Assertion description should explicitly indicate that wsp:Optional is allowed.</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>17. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>18. Consider entire essage exchange pattern when specifying Assertions that may be optional</b></a></p></li><li><p><a href="#bp-indicate-optional-assertion-use"><b>19. Indicate use of an Optional Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>20. Assertion Authors Should Specify Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>21. Choose the Most Granular Policy Subject</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>22. Define Semantics of Attachment to Multiple Policy Subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>23. Specify Preferred Attachment Point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>24. Describe Semantics of Multiple Assertions of Same Type</b></a></p></li><li><p><a href="#bp-specify-composition"><b>25. Specify Composition with Related Assertions</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>26. Use Independent Assertions fo Different Versions of a Behavior</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>10. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>11. Enumerate Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>12. Discourage Domain Specific Intersection</b></a></p></li><li><p><a href="#DefineIgnorable"><b>13. Assertions Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>14. Ignorable Attribute in XML</b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>15. Assertion XML should allow use of wsp:Optional attribute</b></a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional"><b>16. Use the wsp:Optional attribute to indicate optional</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>17. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>18. Consider entire message exchange pattern whn specifying Assertions that may be optional</b></a></p></li><li><p><a href="#bp-indicate-optional-assertion-use"><b>19. Indicate use of an Optional Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>20. Assertion Authors Should Specify Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>21. Choose the Most Granular Policy Subject</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>22. Define Semantics of Attachment to Multiple Policy Subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>23. Specify Preferred Attachment Point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>24. Describe Semantics of Multiple Assertions of Same Type</b></a></p></li><li><p><a href="#bp-specify-composition"><b>25. Specify Composition with Related Assertions</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>26. Use Independent Assertions for Different Versions of a Bhavior</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
@@ -561,8 +561,8 @@
versus attributes apply is: Use a unique QName to identify a distinct behavior </p><div class="boxedtext"><p><a name="bp-unique-qnames" id="bp-unique-qnames"></a><span class="practicelab">Best
Practice 4: Use Unique QNames</span></p><p class="practice">Assertion Authors should use a unique QName to identify a distinct behavior.</p></div><p> and provide
an XML outline (plus an XML schema document) to specify the syntax of an assertion. </p><div class="boxedtext"><p><a name="XMLOutline" id="XMLOutline"></a><span class="practicelab">Best
-Practice 5: 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.
+Practice 5: Provide an XML Outline</span></p><p class="practice">Assertion authors should provide an XML outline plus an XML schema to
+ specify the syntax of an assertion.
</p></div><p> An example of this method (below) is given in the Web Services Reliable Messaging Policy document. [<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite>]
</p><div class="exampleOuter"><div class="exampleInner"><pre>
<wsrmp:RMAssertion [wsp:Optional="true"]? ...>
@@ -598,8 +598,8 @@
</sp:IssuedToken>
</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 should clearly and completely specify the semantics of a policy
- assertion.
+Practice 6: Specify Semantics Clearly</span></p><p class="practice"> Assertion authors should clearly and completely specify the
+ semantics of a policy assertion.
</p></div></div><div class="div3">
<h4><a name="self-describing" id="self-describing"></a>5.3.3 Self Describing Messages </h4><p> WS-Policy is intended to communicate the requirements, capabilities and
behaviors of nodes that provide the message's path, not specifically to declare properties of the message semantics. One
@@ -731,9 +731,8 @@
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 12: 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.
+Practice 12: Discourage Domain Specific Intersection</span></p><p class="practice">Assertion authors should only specify domain specific
+ intersection semantics when policy intersection is insufficient.</p></div><p>We will use the WS-SecurityPolicy to illustrate the use of nested assertions.
</p><p>Securing messages is a complex usage scenario. The WS-SecurityPolicy Assertion Authors have defined the
<code>sp:TransportBinding</code> policy assertion to indicate
the use of transport-level security for protecting
@@ -858,8 +857,8 @@
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 16: 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
+Practice 16: Use the wsp:Optional attribute to indicate optional</span></p><p class="practice">Assertion authors should use the wsp:Optional attribute to indicate that a
+ behavior indicated by a 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">
<p style="text-align: left" class="exampleHead"><i><span>Example 5-9. </span>Assertion Attachment text mentions optionality for policy assertion subjects</i></p><div class="exampleInner"><pre>The SampleAssertion policy assertion indicates behavior over all messages in a binding, so
@@ -1002,10 +1001,9 @@
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 22: 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.
+Practice 22: 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 author 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><p>Since many attachment points are available in WSDL, it would be
@@ -1043,12 +1041,12 @@
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 24: Describe Semantics of Multiple Assertions of Same Type</span></p><p class="practice">A policy alternative can contain multiple instances of the
- same policy assertion type. An assertion description should specify the
- semantics of multiple instances of same policy assertion type in the same
- policy alternative and the semantics of parameters and nested policy
- (if any) when there are multiple instances of a policy assertion type in
- the same policy alternative.
+Practice 24: Describe Semantics of Multiple Assertions of Same Type</span></p><p class="practice">A policy alternative can contain multiple instances of the same
+ policy assertion type. Assertion authors should specify the semantics of
+ multiple instances of same policy assertion type in the same policy
+ alternative and the semantics of parameters and nested policy (if any)
+ when there are multiple instances of a policy assertion type 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><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%"> </td></tr><tr><td colspan="2" align="left" valign="top">To be re-structured to use the format in the Architecture of the WWW doc.</td></tr></table><p>Assertion Authors need to be clear about how assertions defined in
their domain may fit with assertions for interrelated domains. A
@@ -1062,8 +1060,8 @@
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 25: 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">
+Practice 25: Specify Composition with Related Assertions</span></p><p class="practice">Assertion authors should clearly specify how an 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
or modified constructs. These constructs may be compatible or incompatible with previous versions.
@@ -1237,7 +1235,6 @@
can utilize them. In this case, the WS-SecurityPolicy Assertion Authors
factored out common elements of security mechanisms and utilized a
feature of WS-Policy called "nested" assertions. In the case of
-
an <code>sp:TransportBinding</code> assertion, just indicating the use of
transport-level security for protecting messages is not
sufficient. For a consumer of a web service provided by a company,
@@ -1720,4 +1717,6 @@
for issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4074">4074</a>.
Editors' action
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/286">286</a>.
+ </td></tr><tr><td rowspan="1" colspan="1">200706018</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Implemented Editors' action
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/295">295</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.91
retrieving revision 1.92
diff -u -d -r1.91 -r1.92
--- ws-policy-guidelines.xml 17 Jun 2007 05:14:27 -0000 1.91
+++ ws-policy-guidelines.xml 19 Jun 2007 03:02:59 -0000 1.92
@@ -662,8 +662,8 @@
<p> and provide
an XML outline (plus an XML schema document) to specify the syntax of an assertion. </p>
<p role="practice" id="XMLOutline"> <quote>Provide an XML Outline</quote> >
- <quote> An assertion description should provide an XML outline plus an XML schema to specify the
- syntax of the assertion.
+ <quote>Assertion authors should provide an XML outline plus an XML schema to
+ specify the syntax of an assertion.
</quote>
</p>
<p> An example of this method (below) is given in the Web Services Reliable Messaging Policy document. [<bibref ref="WS-RM-Policy"/>]
@@ -711,8 +711,8 @@
</example>
<p role="practice" id="AssertionDefinitions"> <quote>Specify Semantics Clearly</quote> >
- <quote> An assertion description should clearly and completely specify the semantics of a policy
- assertion.
+ <quote> Assertion authors should clearly and completely specify the
+ semantics of a policy assertion.
</quote>
</p>
@@ -915,9 +915,8 @@
<p role="practice" id="bp-discourage-domain-specific-intersection">
<quote>Discourage Domain Specific Intersection</quote>
- <quote>An
- assertion description should only specify domain specific intersection
- semantics when policy intersection is insufficient.</quote></p>
+ <quote>Assertion authors should only specify domain specific
+ intersection semantics when policy intersection is insufficient.</quote></p>
<p>We will use the WS-SecurityPolicy to illustrate the use of nested assertions.
</p>
@@ -1095,9 +1094,9 @@
<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>
<p role="practice" id="bp-assertion-description-explicitly-allow-optional">
- <quote>Assertion description should explicitly indicate that wsp:Optional is allowed.</quote>
- <quote>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.</quote>
+ <quote>Use the wsp:Optional attribute to indicate optional</quote>
+ <quote>Assertion authors should use the wsp:Optional attribute to indicate that a
+ behavior indicated by a QName is optional for the associated policy subject.</quote>
</p>
<p>Continuing the example with the hypothetical SampleAssertion, the section on Assertion Attachment should
include discussion of optionality.
@@ -1302,10 +1301,9 @@
<p role="practice" id="bp-WSDL-multiple-policy-subjects">
<quote>Define Semantics of 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>If an assertion is allowed to be associated with multiple policy subjects,
+ the assertion author should describe the semantics of multiple instances of
+ the same assertion attached to multiple policy subjects at the same time.
</quote>
</p>
@@ -1365,12 +1363,12 @@
<p role="practice" id="bp-WSDL-policy-multiple-instance-semantics">
<quote>Describe Semantics of Multiple Assertions of Same Type</quote>
- <quote>A policy alternative can contain multiple instances of the
- same policy assertion type. An assertion description should specify the
- semantics of multiple instances of same policy assertion type in the same
- policy alternative and the semantics of parameters and nested policy
- (if any) when there are multiple instances of a policy assertion type in
- the same policy alternative.
+ <quote>A policy alternative can contain multiple instances of the same
+ policy assertion type. Assertion authors should specify the semantics of
+ multiple instances of same policy assertion type in the same policy
+ alternative and the semantics of parameters and nested policy (if any)
+ when there are multiple instances of a policy assertion type in the same
+ policy alternative.
</quote>
</p>
@@ -1396,8 +1394,8 @@
interrelated domain. </p>
<p role="practice" id="bp-specify-composition">
<quote>Specify Composition with Related Assertions</quote>
- <quote>An assertion description should clearly specify how the assertion may compose
- with other related assertions, if any.</quote>
+ <quote>Assertion authors should clearly specify how an assertion
+ may compose with other related assertions, if any.</quote>
</p>
</div2>
</div1>
@@ -2682,6 +2680,13 @@
Editors' action
<loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/286">286</loc>.
</td>
+ </tr>
+ <tr>
+ <td>200706018</td>
+ <td>ASV</td>
+ <td>Implemented Editors' action
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/295">295</loc>.
+ </td>
</tr>
</tbody>
</table>
Received on Tuesday, 19 June 2007 03:03:05 UTC