- From: Asir Vedamuthu via cvs-syncmail <cvsmail@w3.org>
- Date: Sun, 20 May 2007 17:34:24 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv5926
Modified Files:
ws-policy-guidelines.html ws-policy-guidelines.xml
Log Message:
1. Added Good Practice 26. Specify Composition with Related Assertions (from the IBM and MS Contribution to 5.8 Interrelated domains. Added an ed note that Section 5.8 Interrelated domains needs to be re-structured.
2. Added Good Practice 8. Not Necessary to Understand a Message (from the IBM and MS Contribution to 5.3.3 Self Describing Messages.
3. Added an ed note that Section 5.5 Designating Ignorable Behavior looks incomplete.
4. Fixed typos.
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.59
retrieving revision 1.60
diff -u -d -r1.59 -r1.60
--- ws-policy-guidelines.html 19 May 2007 01:31:00 -0000 1.59
+++ ws-policy-guidelines.html 20 May 2007 17:34:21 -0000 1.60
@@ -119,7 +119,7 @@
<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>
3. <a href="#Assertions">What is an Assertion? </a><br>
-4. <a href="#d3e262">Who is involved in authoring Assertions? </a><br>
+4. <a href="#d3e265">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>
@@ -139,9 +139,9 @@
5.5.1 <a href="#doc-ignorable-assertions">Assertions and Ignorable Behavior</a><br>
5.5.2 <a href="#XML-ignorable-assertions">XML Outline for Ignorable </a><br>
5.6 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br>
- 5.6.1 <a href="#d3e747">Optional behavior in Compact authoring</a><br>
- 5.6.2 <a href="#d3e787">Optional behavior at runtime</a><br>
- 5.6.2.1 <a href="#d3e832">Example</a><br>
+ 5.6.1 <a href="#d3e757">Optional behavior in Compact authoring</a><br>
+ 5.6.2 <a href="#d3e797">Optional behavior at runtime</a><br>
+ 5.6.2.1 <a href="#d3e842">Example</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>
@@ -208,8 +208,9 @@
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 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. 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="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
+ 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
capability related to a specific WS-Policy domain. Sets of domain-specific assertions
are typically defined in a dedicated specification that describes
@@ -268,7 +269,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="d3e262" id="d3e262"></a>4. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
+<h2><a name="d3e265" id="d3e265"></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
@@ -415,8 +416,9 @@
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">Good
-practice 2: Semantics of Policy Assertions</span></p><p class="practice">
- The semantics a policy assertion should not depend on the
+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></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
@@ -439,7 +441,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">Good
-practice 3: Semantics of an Assertion and its 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,
@@ -536,7 +538,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">Good
-practice 4: Start with simple Assertions</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">
@@ -567,10 +569,10 @@
</sp:IssuedToken>
</pre></div></div><div class="boxedtext"><p><a name="AssertionDefinitions" id="AssertionDefinitions"></a><span class="practicelab">Good
-practice 6: Clear Semantics</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">Good
-practice 7: 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>
<wsrmp:RMAssertion [wsp:Optional="true"]? ...>
@@ -596,9 +598,8 @@
dedicated endpoint may be allocated to ensure the engagement of a
behavior that is expressed by a policy assertion. This approach
can be considered when messages cannot be self describing.
- </p><div class="boxedtext"><p><a name="bp-assertions-and-message-semantics" id="bp-assertions-and-message-semantics"></a><span class="practicelab">Good
-practice 8: Assertions and Message Semantics</span></p><p class="practice">Policy assertions should not be used to express the semantics of a message.
- Firstly, an assertion type indicates a runtime behavior. Secondly, Assertion Authors need to indicate how the runtime behavior represented in the assertion type can be inferred or indicated
+ </p><p>Policy assertions should not be used to express the semantics of a message.
+ Firstly, an assertion type indicates a <em>runtime</em> behavior. Secondly, Assertion Authors need to indicate how the runtime behavior represented in the assertion type can be inferred or indicated
from a message at runtime. If there is a need for the behavior
to be represented in a persistent way or if there is a need for
additional data or metadata that is present in a message to be
@@ -607,7 +608,8 @@
consider how to make messages self describing when utilizing
their assertions by specifying additional properties, headers,
etc. that must be present in a message as part of their assertion design.
- </p></div><p>For example, if the details of a message's encryption ( e.g., the cipher used, etc) are expressed
+ </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">Good
+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
@@ -654,7 +656,7 @@
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">Good
practice 10: Use Parameters for Useful
Information</span></p><p class="practice">An assertion author should represent useful (or additional)
- nformation necessary for engaging the behavior represented by a policy
+ information necessary for engaging the behavior represented by a policy
assertion as assertion parameters.
</p></div><p>In the example below, <code>sp:Body</code> and <code>sp:Header</code>
elements are the two assertion parameters of the
@@ -737,7 +739,6 @@
<code>sp:TransportBinding</code> policy assertion. The
<code>sp:TransportToken</code> is a nested policy assertion of
the <code>sp:TransportBinding</code> policy assertion. The
-
<code>sp:TransportToken</code> assertion requires the use of a
specific transport token and further qualifies the behavior of
the <code>sp:TransportBinding</code> policy assertion (which
@@ -799,7 +800,7 @@
</sp:TransportToken></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><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%"> </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
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,7 +817,7 @@
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">
-<h4><a name="d3e747" id="d3e747"></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="d3e757" id="d3e757"></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,
@@ -847,7 +848,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="d3e787" id="d3e787"></a>5.6.2 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
+<h4><a name="d3e797" id="d3e797"></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
@@ -902,7 +903,7 @@
</p><div class="boxedtext"><p><a name="bp-indicate-optional-assertion-use" id="bp-indicate-optional-assertion-use"></a><span class="practicelab">Good
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="d3e832" id="d3e832"></a>5.6.2.1 Example</h5><p>
+<h5><a name="d3e842" id="d3e842"></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
use of
<cite><a href="#MTOM">MTOM</a></cite> as an optional behavior that can be engaged by a consumer.
@@ -1049,7 +1050,7 @@
(if any) when there are multiple instances of a policy assertion 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><p>Assertion authors need to be clear about how assertions defined in
+<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
classic example of such an interrelated domain is security, because
security tends to
@@ -1060,7 +1061,9 @@
Assertions [<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite>]. </p><p>Assertion authors should not duplicate existing
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></div><div class="div1">
+ interrelated domain. </p><div class="boxedtext"><p><a name="bp-specify-composition" id="bp-specify-composition"></a><span class="practicelab">Good
+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
or modified constructs. These constructs may be compatible or incompatible with previous versions.
@@ -1089,7 +1092,8 @@
[<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 26: 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 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">
<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>
@@ -1117,7 +1121,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 27: 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">
@@ -1654,4 +1658,16 @@
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
+ 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
+ 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>.
+ </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 that
+ 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></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.74
retrieving revision 1.75
diff -u -d -r1.74 -r1.75
--- ws-policy-guidelines.xml 19 May 2007 01:31:01 -0000 1.74
+++ ws-policy-guidelines.xml 20 May 2007 17:34:21 -0000 1.75
@@ -476,8 +476,9 @@
allows policy tools to choose the most appropriate mechanism to attach a
policy without having to analyze the contents of the policy.
</p>
- <p role="practice" id="bp-assertion-semantics"><quote>Semantics of Policy Assertions</quote><quote>
- The semantics a policy assertion should not depend on the
+ <p role="practice" id="bp-assertion-semantics"><quote>Semantics Independent of
+ Attachment Mechanisms</quote><quote>
+ The semantics of a policy assertion should not depend on the
attachment mechanism used.</quote>
</p>
</div2>
@@ -507,7 +508,7 @@
to author a policy expression that contains the assertion.
</p>
<p role="practice" id="bp-semantics-and-form">
- <quote>Semantics of an Assertion and its form</quote>
+ <quote>Semantics Independent of the Form</quote>
<quote>The semantics of an assertion should be independent of
the form (compact or normal form) of policy expressions that contain the
assertion.</quote>
@@ -624,7 +625,7 @@
work progresses, one may add more parameters or nested policy assertions
to meet one's interoperability needs.
</p>
- <p role="practice" id="bp-assertion-start"><quote>Start with simple Assertions</quote>
+ <p role="practice" id="bp-assertion-start"><quote>Start with Simple Assertion</quote>
<quote>An assertion author should start with a simple working assertion
that allows assertion parameter extensibility. </quote>
</p>
@@ -670,12 +671,12 @@
</eg>
</example>
- <p role="practice" id="AssertionDefinitions"> <quote>Clear Semantics</quote> >
+ <p role="practice" id="AssertionDefinitions"> <quote>Specify Semantics Clearly</quote> >
<quote> An assertion description must clearly and completely specify the semantics of a policy
assertion.
</quote>
</p>
- <p role="practice" id="XMLOutline"> <quote>XML Outline</quote> >
+ <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>
@@ -715,7 +716,7 @@
behavior that is expressed by a policy assertion. This approach
can be considered when messages cannot be self describing.
</p>
- <p role="practice" id="bp-assertions-and-message-semantics"><quote>Assertions and Message Semantics</quote><quote>Policy assertions should not be used to express the semantics of a message.
+ <p>Policy assertions should not be used to express the semantics of a message.
Firstly, an assertion type indicates a <emph>runtime</emph> behavior. Secondly, Assertion Authors need to indicate how the runtime behavior represented in the assertion type can be inferred or indicated
from a message at runtime. If there is a need for the behavior
to be represented in a persistent way or if there is a need for
@@ -725,8 +726,11 @@
consider how to make messages self describing when utilizing
their assertions by specifying additional properties, headers,
etc. that must be present in a message as part of their assertion design.
- </quote>
</p>
+ <p role="practice" id="bp-not-necessary-to-understand-a-message">
+ <quote>Not Necessary to Understand a Message</quote>
+ <quote>An assertion author should not define policy assertions to represent information that is necessary to understand a message.</quote>
+ </p>
<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
@@ -793,7 +797,7 @@
<p role="practice" id="bp-assertion-parameters"><quote>Use Parameters for Useful
Information</quote>
<quote>An assertion author should represent useful (or additional)
- nformation necessary for engaging the behavior represented by a policy
+ information necessary for engaging the behavior represented by a policy
assertion as assertion parameters.
</quote>
</p>
@@ -1001,6 +1005,9 @@
</div2>
<div2 id="Ignorable">
<head>Designating Ignorable Behavior</head>
+ <ednote>
+ <edtext>Looks incomplete – carries Good 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
whether the behavior represented by the Assertion they are defining can be ignored for the purposes of
@@ -1370,6 +1377,9 @@
</div2>
<div2 id="interrelated-domains">
<head>Interrelated domains</head>
+ <ednote>
+ <edtext>To be re-structured to use the format in the Architecture of the WWW doc.</edtext>
+ </ednote>
<p>Assertion authors need to be clear about how assertions defined in
their domain may fit with assertions for interrelated domains. A
classic example of such an interrelated domain is security, because
@@ -1384,6 +1394,11 @@
assertions and should also make sure that when adding assertions those new assertions are consistent
with pre-existing assertions of any
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>
+ </p>
</div2>
</div1>
<div1 id="versioning-policy-assertions">
@@ -1445,7 +1460,11 @@
[<bibref ref="WS-Addressing"/>]. These equivalent behaviors
are mutually exclusive for an interaction. Such equivalent
behaviors can be modeled as independent assertions. </p>
- <p role="practice" id="bp-independent-assertions"><quote>Independent Assertions</quote><quote>An assertion author should use independent assertions for modeling multiple versions of a behavior.</quote></p>
+ <p role="practice" id="bp-independent-assertions">
+ <quote>Use Independent Assertions for Multiple Versions of a Behavior</quote>
+ <quote>An assertion author should use independent assertions for modeling multiple
+ versions of a behavior.</quote></p>
+
<p>The
policy expression in the example below requires the use of
WSS: SOAP Message Security 1.0. </p>
@@ -2492,6 +2511,38 @@
<td>Updated Appendix E, Changes in this Version of the Document
(<specref ref="change-description"/>).
</td>
+ </tr>
+ <tr>
+ <td>20070520</td>
+ <td>ASV</td>
+ <td>Added Good 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
+ Section <specref ref="interrelated-domains"/> needs to be re-structured.
+ </td>
+ </tr>
+ <tr>
+ <td>20070520</td>
+ <td>ASV</td>
+ <td>Added Good 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"/>.
+ </td>
+ </tr>
+ <tr>
+ <td>20070520</td>
+ <td>ASV</td>
+ <td>Added an ed note that
+ Section <specref ref="Ignorable"/> looks incomplete.
+ </td>
+ </tr>
+ <tr>
+ <td>20070520</td>
+ <td>ASV</td>
+ <td>Fixed typos.
+ </td>
</tr>
</tbody>
</table>
Received on Sunday, 20 May 2007 17:34:27 UTC