- From: Frederick Hirsch via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 27 Apr 2007 15:07:20 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv1993
Modified Files:
ws-policy-guidelines.html ws-policy-guidelines.xml
Log Message:
Update section 5.5.1 with new good practices G7 and G8, update TBD in section 2.
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.48
retrieving revision 1.49
diff -u -d -r1.48 -r1.49
--- ws-policy-guidelines.html 26 Apr 2007 20:46:30 -0000 1.48
+++ ws-policy-guidelines.html 27 Apr 2007 15:07:17 -0000 1.49
@@ -117,9 +117,9 @@
<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 Best Practices Statements</a><br>
+2. <a href="#best-practices-list">List of Good Practice Statements</a><br>
3. <a href="#Assertions">What is an Assertion? </a><br>
-4. <a href="#d3e236">Who is involved in authoring Assertions? </a><br>
+4. <a href="#d3e244">Who is involved in authoring Assertions? </a><br>
4.1 <a href="#roles"> Roles and Responsibilities </a><br>
4.1.1 <a href="#domain-owners"> Assertion Authors</a><br>
4.1.2 <a href="#consumers">Consumers</a><br>
@@ -137,9 +137,9 @@
5.4.2 <a href="#nested-assertions">Nested Assertions</a><br>
5.4.3 <a href="#which-one-to-use">Considerations for choosing parameters vs nesting</a><br>
5.5 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br>
- 5.5.1 <a href="#d3e657">Optional behavior in Compact authoring</a><br>
- 5.5.2 <a href="#d3e665">Optional behavior at runtime</a><br>
- 5.5.2.1 <a href="#d3e710">Example</a><br>
+ 5.5.1 <a href="#d3e665">Optional behavior in Compact authoring</a><br>
+ 5.5.2 <a href="#d3e705">Optional behavior at runtime</a><br>
+ 5.5.2.1 <a href="#d3e750">Example</a><br>
5.6 <a href="#levels-of-abstraction">Levels of Abstraction in WSDL </a><br>
5.7 <a href="#interrelated-domains">Interrelated domains</a><br>
6. <a href="#versioning-policy-assertions">Versioning Policy Assertions</a><br>
@@ -207,7 +207,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 Best Practices Statements</h2><p>TBD:</p><ol class="enumar"><li><p><a href="#bp-assertion-specification-parts">Parts of an Assertion Specification</a></p></li><li><p><a href="#bp-assertion-semantics">Semantics of Policy Assertions</a></p></li><li><p><a href="#bp-semantics-and-form">Semantics of an Assertion and its form</a></p></li><li><p><a href="#bp-assertion-start">Starting to Build an Assertion</a></p></li><li><p><a href="#bp-unique-qnames">Unique QNames</a></p></li><li><p><a href="#bp-assertions-and-message-semantics">Assertions and Message Semantics</a></p></li><li><p><a href="#bp-assertion-duplication">Duplication of Assertions</a></p></li><li><p><a href="#bp-assertion-definition">Definition of Policy Assertions</a></p></li><li><p><a href="#bp-nesting">Nesting of Assertions</a></p></li><li><p><a href="#bp-limit-optional-assertions">Limit use of Optional Assertions</a></p></li><li><p><a href="#bp-entire-mep-for-optional">Considr entire message exchange pattern when specifying Assertions that may be optional</a></p></li><li><p><a href="#bp-indicate-optional-assertion-use">Indicate use of an Optional Assertion</a></p></li><li><p><a href="#bp-independent-assertions">Independent Assertions</a></p></li><li><p><a href="#bp-policy-subject-change">Change of the Policy Subject Over Time</a></p></li></ol></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><ol class="enumar"><li><p><a href="#bp-assertion-specification-parts">Parts of an Assertion Specification</a></p></li><li><p><a href="#bp-assertion-semantics">Semantics of Policy Assertions</a></p></li><li><p><a href="#bp-semantics-and-form">Semantics of an Assertion and its form</a></p></li><li><p><a href="#bp-assertion-start">Starting to Build an Assertion</a></p></li><li><p><a href="#bp-unique-qnames">Unique QNames</a></p></li><li><p><a href="#bp-assertions-and-message-semantics">Assertions and Message Semantics</a></p></li><li><p><a href="#bp-assertion-duplication">Duplication of Assertions</a></p></li><li><p><a href="#bp-assertion-definition">Definition of Policy Assertions</a></p></li><li><p><a href="#bp-nesting">Nesting of Assertions</a></p></li><li><p><a href="#bp-asertion-xml-allow-optional">Assertion XML should allow use of wsp:Optional attribute</a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional">Assertion description should explicitly indicate that wsp:Optional is allowed.</a></p></li><li><p><a href="#bp-limit-optional-assertions">Limit use of Optional Assertions</a></p></li><li><p><a href="#bp-entire-mep-for-optional">Consider entire message exchange pattern when specifying Assertions that may be optional</a></p></li><li><p><a href="#bp-indicate-optional-assertion-use">Indicate use of an Optional Assertion</a></p></li><li><p><a href="#bp-independent-assertions">Independent Assertions</a></p></li><li><p><a href="#bp-policy-subject-change">Change of the Policy Subject Over Time</a></p></li></ol></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
@@ -266,7 +266,7 @@
best practices will be an assertion specification that describes
a contract for the consumers and providers of the capabilities and constraints of the domain.
</p></div><div class="div1">
-<h2><a name="d3e236" id="d3e236"></a>4. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
+<h2><a name="d3e244" id="d3e244"></a>4. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
express their own domain knowledge, it is necessary to provide basic
functionality that all domains could exploit and then allow
points of extension where authors of the various WS-Policy
@@ -765,7 +765,7 @@
delegated to the specific domain handlers that are not visible
to the WS-Policy framework.</p></div></div></div><div class="div2">
<h3><a name="optional-policy-assertion" id="optional-policy-assertion"></a>5.5 Designating Optional Behaviors</h3><div class="div3">
-<h4><a name="d3e657" id="d3e657"></a>5.5.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="d3e665" id="d3e665"></a>5.5.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,
@@ -777,16 +777,33 @@
the consumer by selecting the appropriate policy alternative.
The provider may influence what is possible by choosing whether or not to
include policy alternatives in a policy expression, by using
- the wsp:Optional attribute.
- </p></div><div class="div3">
-<h4><a name="d3e665" id="d3e665"></a>5.5.2 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
+ 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">Good
+practice 10: 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">
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-7. </span>Use of @any for attribute extensibility</i></p><div class="exampleInner"><pre>/samplePrefix:SampleAssertion/@any
+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">Good
+practice 11: 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">
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-8. </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
+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="d3e705" id="d3e705"></a>5.5.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
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">Good
-practice 10: Limit use of Optional Assertions</span></p><p class="practice">Assertion Authors should not use optional assertions for behaviors that must be present
+practice 12: 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
@@ -818,7 +835,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">Good
-practice 11: 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 13: 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
@@ -832,9 +849,9 @@
(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">Good
-practice 12: 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 14: 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="d3e710" id="d3e710"></a>5.5.2.1 Example</h5><p>
+<h5><a name="d3e750" id="d3e750"></a>5.5.2.1 Example</h5><p>
The <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite> document contains an example that outlines the
use of
<cite><a href="#MTOM">MTOM</a></cite> as an optional behavior that can be engaged by a consumer.
@@ -970,7 +987,7 @@
[<cite><a href="#WS-Addressing">WS-Addressing Core</a></cite>]. These equivalent behaviors
are mutually exclusive for an interaction. Such equivalent
behaviors can be modeled as independent assertions. </p><div class="boxedtext"><p><a name="bp-independent-assertions" id="bp-independent-assertions"></a><span class="practicelab">Good
-practice 13: Independent Assertions</span></p><p class="practice">An assertion author should use independent assertions for modeling multiple versions of a behavior.</p></div><p>The
+practice 15: Independent Assertions</span></p><p class="practice">An assertion author should use independent assertions for modeling multiple versions of a behavior.</p></div><p>The
policy expression in the example below requires the use of
WSS: SOAP Message Security 1.0. </p><div class="exampleOuter">
<p style="text-align: left" class="exampleHead"><i><span>Example 6-1. </span>Message-level Security and WSS: SOAP Message Security 1.0</i></p><div class="exampleInner"><pre><Policy>
@@ -998,7 +1015,7 @@
new policy subjects are added it is incumbent on the authors to retain the
semantic of the policy assertion.
</p><div class="boxedtext"><p><a name="bp-policy-subject-change" id="bp-policy-subject-change"></a><span class="practicelab">Good
-practice 14: Change of the Policy Subject Over Time</span></p><p class="practice">If the policy subjects change over time,
+practice 16: 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">
@@ -1490,4 +1507,10 @@
For <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4318">issue 4318</a>.
Editors' action
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/245">245</a>.
+ </td></tr><tr><td rowspan="1" colspan="1">20070427</td><td rowspan="1" colspan="1">FJH</td><td rowspan="1" colspan="1">Updated 5.5.1 Optional behavior in Compact authoring adding G7 and G8 for
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>
+ and editors' action item
+ <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></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.63
retrieving revision 1.64
diff -u -d -r1.63 -r1.64
--- ws-policy-guidelines.xml 26 Apr 2007 20:46:30 -0000 1.63
+++ ws-policy-guidelines.xml 27 Apr 2007 15:07:17 -0000 1.64
@@ -150,8 +150,8 @@
</p>
</div1>
<div1 id="best-practices-list">
- <head>List of Best Practices Statements</head>
- <p>TBD:</p>
+ <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>
&guidelines-bestpractices;
</div1>
<div1 id="Assertions">
@@ -947,8 +947,40 @@
the consumer by selecting the appropriate policy alternative.
The provider may influence what is possible by choosing whether or not to
include policy alternatives in a policy expression, by using
- the wsp:Optional attribute.
+ 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>
+
+ <p role="practice" id="bp-assertion-xml-allow-optional">
+ <quote>Assertion XML should allow use of wsp:Optional attribute</quote>
+ <quote>An assertion XML outline should allow the use of the wsp:Optional attribute to
+ indicate optional behaviors.</quote>
</p>
+
+ <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>
+ <example>
+ <head>Use of @any for attribute extensibility</head>
+ <eg xml:space="preserve">/samplePrefix:SampleAssertion/@any
+This is an extensibility mechanism to allow additional attributes to be added to the element, including wsp:Optional.
+ </eg></example>
+ <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>
+ </p>
+ <p>Continuing the example with the hypothetical SampleAssertion, the section on Assertion Attachment should
+ include discussion of optionality.
+ </p>
+ <example>
+ <head>Assertion Attachment text mentions optionality for policy assertion subjects</head>
+ <eg xml:space="preserve">The SampleAssertion policy assertion indicates behavior over all messages in a binding, so
+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.
+ </eg></example>
</div3>
<div3>
<head>Optional behavior at runtime</head>
@@ -2173,6 +2205,17 @@
<loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/245">245</loc>.
</td>
</tr>
+ <tr>
+ <td>20070427</td>
+ <td>FJH</td>
+ <td>Updated 5.5.1 Optional behavior in Compact authoring adding G7 and G8 for
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</loc>
+ and editors' action item
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/250">250</loc>
+ as noted in <loc href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/0069.html">message 69</loc>.
+ Also replaced TBD in section 2 with descriptive text."
+ </td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Friday, 27 April 2007 15:07:25 UTC