- From: David Orchard via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 18 Jul 2007 12:46:22 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv2529
Modified Files:
ws-policy-guidelines.xml ws-policy-guidelines.html
Log Message:
Removed ednotes, fixed 341
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.84
retrieving revision 1.85
diff -u -d -r1.84 -r1.85
--- ws-policy-guidelines.html 18 Jul 2007 10:13:16 -0000 1.84
+++ ws-policy-guidelines.html 18 Jul 2007 12:46:19 -0000 1.85
@@ -136,11 +136,11 @@
5.4.1 <a href="#parameterized-assertions">Assertions with Parameters</a><br>
5.4.2 <a href="#nested-assertions">Nested Assertions</a><br>
5.5 <a href="#Ignorable">Designating Ignorable Behavior</a><br>
- 5.5.1 <a href="#d3e764">Ignorable behavior in authoring</a><br>
- 5.5.2 <a href="#d3e777">Ignorable behavior at runtime</a><br>
+ 5.5.1 <a href="#d3e751">Ignorable behavior in authoring</a><br>
+ 5.5.2 <a href="#d3e764">Ignorable behavior at runtime</a><br>
5.6 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br>
- 5.6.1 <a href="#d3e792">Optional behavior in Compact authoring</a><br>
- 5.6.2 <a href="#d3e832">Optional behavior at runtime</a><br>
+ 5.6.1 <a href="#d3e779">Optional behavior in Compact authoring</a><br>
+ 5.6.2 <a href="#d3e819">Optional behavior at runtime</a><br>
5.7 <a href="#levels-of-abstraction">Considerations for Policy Attachment in WSDL </a><br>
5.8 <a href="#interrelated-domains">Interrelated domains</a><br>
6. <a href="#versioning-policy-assertions">Versioning Policy Assertions</a><br>
@@ -202,9 +202,9 @@
the question.
</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-compatibility-tests"><b>2. Behaviors Relevant to Compatibility Tests</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 a 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="#XMLOutline"><b>6. Provide an XML Outline</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>7. Specify Semantics Clearly</b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>10. Not Necessary to Understand a Message</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>11. Avoid Duplication of Assertions</b></a></p></li><li><p><a href="#bp-assertion-parameters"><b>12. Use Parameters for Useful
- Information</b></a></p></li><li><p><a href="#bp-dependent-behaviors"><b>13. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>14. Enumerate Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>15. Discourage Domain Specific Intersection</b></a></p></li><li><p><a href="#DefineIgnorable"><b>8. Assertion Authors Should Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>9. Assertion Authors Should Document Use of the 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. Use the wsp:Optional attribute to indicate optional</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 message 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. Specify Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>22. Choose the Most 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 Type</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 Different 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">
+ Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-compatibility-tests"><b>2. Behaviors Relevant to Compatibility Tests</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 a 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="#XMLOutline"><b>6. Provide an XML Outline</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>7. Specify Semantics Clearly</b></a></p></li><li><p><a href="#DefineIgnorable"><b>8. Assertion Authors Should Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>9. Assertion Authors Should Document Use of the Ignorable
+Attribute in XML </b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>10. Not Necessary to Understand a Message</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>11. Avoid Duplication of Assertions</b></a></p></li><li><p><a href="#bp-assertion-parameters"><b>12. Use Parameters for Useful
+ Information</b></a></p></li><li><p><a href="#bp-dependent-behaviors"><b>13. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>14. Enumerate Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>15. Discourage Domain Specific Intersection</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. Use the wsp:Optional attribute to indicate optional</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 message 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. Specify Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>22. Choose the Most 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 Type</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 Different 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
capability related to a specific WS-Policy domain. Sets of domain-specific assertions
are typically defined in a dedicated specification that describes
@@ -415,19 +415,12 @@
Practice 1: 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%"> </td></tr><tr><td colspan="2" align="left" valign="top">April 25th 07, editors
- <a href="http://www.w3.org/2007/04/25-ws-policy-eds-minutes.html#item03">decided</a> to add G2 -
- "Assertion Authors should define
- policy assertions for behaviors that are relevant to compatibility tests,
- such as web service protocols that manifest on the wire." - to Section 5.1.
- May 9th 07, an issue was opened against G2 - issue
- <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4566">4566</a>.
- </td></tr></table><div class="boxedtext"><p><a name="bp-compatibility-tests" id="bp-compatibility-tests"></a><span class="practicelab">Best
+ attachment mechanism used.</p></div><div class="boxedtext"><p><a name="bp-compatibility-tests" id="bp-compatibility-tests"></a><span class="practicelab">Best
Practice 2: Behaviors Relevant to Compatibility Tests</span></p><p class="practice">
- Whenever possible, Assertion Authors should define policy asswertions
+ Whenever possible, Assertion Authors should define policy assertions
for behaviors that are relevant to compatibility tests, such as web service
protocols that manifest on the wire.
- </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%"> </td></tr><tr><td colspan="2" align="left" valign="top">Place holder.</td></tr></table></div><div class="div2">
+ </p></div></div><div class="div2">
<h3><a name="compact-full" id="compact-full"></a>5.2 Authoring Styles </h3><p>WS-Policy supports two different authoring styles, compact form and
normal form. A compact form is one in which an expression consists of
three constructs: an attribute to decorate an assertion (to indicate
@@ -823,16 +816,16 @@
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><div class="div3">
-<h4><a name="d3e764" id="d3e764"></a>5.5.1 Ignorable behavior in authoring</h4><p>
+<h4><a name="d3e751" id="d3e751"></a>5.5.1 Ignorable behavior in authoring</h4><p>
The Policy Framework provides an intersection algorithm that has two defined modes for processing (lax and strict). The Framework also defines an attribute (wsp:Ignorable) that can be used to influence whether assertions are part of the compatability assessment between two alternatives. [see <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite> and <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>]. Assertion authors should consider whether the behavior represented by the Assertion they are defining can be safely ignored for the purposes of intersection, and should follow <a href="#DefineIgnorable"><b>8. Assertion Authors Should Document Ignorable Behavior</b></a> and <a href="#ignorableAssertions"><b>9. Assertion Authors Should Document Use of the Ignorable
Attribute in XML </b></a> to include this guidance in the assertion's definition.</p></div><div class="div3">
-<h4><a name="d3e777" id="d3e777"></a>5.5.2 Ignorable behavior at runtime</h4><p>Regardless of whether the assertion allows the ignorable attribute, assertion authors should
+<h4><a name="d3e764" id="d3e764"></a>5.5.2 Ignorable behavior at runtime</h4><p>Regardless of whether the assertion allows the ignorable attribute, assertion authors should
indicate the semantic of the runtime behavior in the description of the assertion.
</p><p>
As said in <a href="ws-policy-primer.html#strict-lax-policy-intersection">section 3.4.1 Strict and Lax Policy Intersection</a> in <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>, "Regardless of the chosen intersection mode, ignorable assertions do not express any wire-level requirements on the behavior of consumers - in other words, a consumer could choose to ignore any such assertions that end up in the resulting policy after intersection, with no adverse effects on runtime interactions." Therefore, any assertion that is marked with ignorable should not impose any wire-level requirements on the part of consumers. Assertion Authors are reminded that regardless of whether an assertion is marked as ignorable, policy consumers using strict intersection will not 'ignore' the assertion.
</p></div></div><div class="div2">
<h3><a name="optional-policy-assertion" id="optional-policy-assertion"></a>5.6 Designating Optional Behaviors</h3><div class="div3">
-<h4><a name="d3e792" id="d3e792"></a>5.6.1 Optional behavior in Compact authoring</h4><p>Optional behaviors represent behaviors that may be engaged by a consumer. When using the
+<h4><a name="d3e779" id="d3e779"></a>5.6.1 Optional behavior in Compact authoring</h4><p>Optional behaviors represent behaviors that may be engaged by a consumer. When using the
compact authoring form for assertions, such behaviors are marked by
using <code>wsp:Optional</code> attribute with a value of
"true". (In order to simplify reference to such assertions,
@@ -863,7 +856,7 @@
it has an Endpoint Policy Subject and must be attached to a wsdl:binding or wsdl:port.
The assertion may be optional when attached to these subjects, allowing use of wsp:Optional.
</pre></div></div></div><div class="div3">
-<h4><a name="d3e832" id="d3e832"></a>5.6.2 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
+<h4><a name="d3e819" id="d3e819"></a>5.6.2 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
both the provider and the consumer, behaviors that must
always be engaged by a consumer must not be marked as
"optional" with a value "true" since this would allow the
@@ -1312,7 +1305,7 @@
<a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0129.html">Part 1</a> and
<a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0134.html">Part 2</a>.
</td></tr><tr><td rowspan="1" colspan="1">20061129</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Formatted examples in <a href="#extending-assertions"><b>6.2 Evolution of Assertions (Versioning and Compatibility)</b></a>.
- </td></tr><tr><td rowspan="1" colspan="1">20061218</td><td rowspan="1" colspan="1">FS</td><td rowspan="1" colspan="1">Formatted examples in <a href="#compact-full"><b>5.2 Authoring Styles </b></a> and .
+ </td></tr><tr><td rowspan="1" colspan="1">20061218</td><td rowspan="1" colspan="1">FS</td><td rowspan="1" colspan="1">Formatted examples in <a href="#compact-full"><b>5.2 Authoring Styles </b></a> and scenario section.
</td></tr><tr><td rowspan="1" colspan="1">20061219</td><td rowspan="1" colspan="1">TIB</td><td rowspan="1" colspan="1">Editorial revision: most parts of editorial action
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/96">96</a>.
Remaining editorials to be reviewed.
@@ -1527,7 +1520,7 @@
for issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3988">3988</a>.
Editors' action:
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/338">338</a>,
- drop <a href="http://www.w3.org/TR/2007/WD-ws-policy-guidelines-20070330/#scenario">Section
+ drop <a href="http://www.w3.org/TR/2007/WD-ws-policy-guidelines-20070330/">Section
7 Scenario and a worked example</a></td></tr><tr><td rowspan="1" colspan="1">20070718</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Implemented the resolution
for issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3988">3978</a>.
Editors' action:
Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.99
retrieving revision 1.100
diff -u -d -r1.99 -r1.100
--- ws-policy-guidelines.xml 18 Jul 2007 10:13:16 -0000 1.99
+++ ws-policy-guidelines.xml 18 Jul 2007 12:46:19 -0000 1.100
@@ -483,28 +483,14 @@
attachment mechanism used.</quote>
</p>
- <ednote>
- <edtext>April 25th 07, editors
- <loc href="http://www.w3.org/2007/04/25-ws-policy-eds-minutes.html#item03">decided</loc> to add G2 -
- "Assertion Authors should define
- policy assertions for behaviors that are relevant to compatibility tests,
- such as web service protocols that manifest on the wire." - to Section 5.1.
- May 9th 07, an issue was opened against G2 - issue
- <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4566">4566</loc>.
- </edtext>
- </ednote>
<p role="practice" id="bp-compatibility-tests">
<quote>Behaviors Relevant to Compatibility Tests</quote>
<quote>
- Whenever possible, Assertion Authors should define policy asswertions
+ Whenever possible, Assertion Authors should define policy assertions
for behaviors that are relevant to compatibility tests, such as web service
protocols that manifest on the wire.
</quote>
</p>
- <ednote>
- <edtext>Place holder.</edtext>
- </ednote>
-
</div2>
<div2 id="compact-full">
@@ -1898,7 +1884,7 @@
<tr>
<td>20061218</td>
<td>FS</td>
- <td>Formatted examples in <specref ref="compact-full"/> and <specref ref="scenario"/>.
+ <td>Formatted examples in <specref ref="compact-full"/> and scenario section.
</td>
</tr>
<tr>
@@ -2475,7 +2461,7 @@
for issue <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3988">3988</loc>.
Editors' action:
<loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/338">338</loc>,
- drop <loc href="http://www.w3.org/TR/2007/WD-ws-policy-guidelines-20070330/#scenario">Section
+ drop <loc href="http://www.w3.org/TR/2007/WD-ws-policy-guidelines-20070330/">Section
7 Scenario and a worked example</loc></td>
</tr>
<tr>
Received on Wednesday, 18 July 2007 12:46:32 UTC