- From: Prasad Yendluri via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 11 May 2007 22:51:03 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv21884
Modified Files:
ws-policy-guidelines.html
Log Message:
Updated 5.6 WSDL guidelines section to add G19 identified in AI 256 (now G24). Accounts for parts of resolution for issue 3989 corresponding to editors' action item 256 - now complete.
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.53
retrieving revision 1.54
diff -u -d -r1.53 -r1.54
--- ws-policy-guidelines.html 8 May 2007 20:33:48 -0000 1.53
+++ ws-policy-guidelines.html 11 May 2007 22:51:01 -0000 1.54
@@ -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="#d3e253">Who is involved in authoring Assertions? </a><br>
+4. <a href="#d3e259">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>
@@ -140,9 +140,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="#d3e718">Optional behavior in Compact authoring</a><br>
- 5.6.2 <a href="#d3e758">Optional behavior at runtime</a><br>
- 5.6.2.1 <a href="#d3e803">Example</a><br>
+ 5.6.1 <a href="#d3e724">Optional behavior in Compact authoring</a><br>
+ 5.6.2 <a href="#d3e764">Optional behavior at runtime</a><br>
+ 5.6.2.1 <a href="#d3e809">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>
@@ -210,7 +210,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 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. Starting to Build an Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>5. 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. Duplication of Asertions</b></a></p></li><li><p><a href="#bp-assertion-definition"><b>10. Definition of Policy Assertions</b></a></p></li><li><p><a href="#bp-nesting"><b>11. Nesting of Assertions</b></a></p></li><li><p><a href="#DefineIgnorable"><b>12. Assertions Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>13. Ignorable Attribute in XML</b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>14. Assertion XML should allow use of wsp:Optional attribute</b></a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional"><b>15. Assertion description should explicitly indicate that wsp:Optional is allowed.</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>16. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>17. 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>18. Indicate use of an Opional Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>19. An assertion description should specify a policy subject</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>20. Granularity of policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>21. Assertion attachment to multiple policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>22. Preferred attachment point for an Assertion</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>23. Independent Assertions</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>24. 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 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. Starting to Build an Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>5. 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. Duplication of Asertions</b></a></p></li><li><p><a href="#bp-assertion-definition"><b>10. Definition of Policy Assertions</b></a></p></li><li><p><a href="#bp-nesting"><b>11. Nesting of Assertions</b></a></p></li><li><p><a href="#DefineIgnorable"><b>12. Assertions Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>13. Ignorable Attribute in XML</b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>14. Assertion XML should allow use of wsp:Optional attribute</b></a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional"><b>15. Assertion description should explicitly indicate that wsp:Optional is allowed.</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>16. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>17. 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>18. Indicate use of an Opional Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>19. An assertion description should specify a policy subject</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>20. Granularity of policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>21. Assertion attachment to multiple policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-policy-scope-semantics"><b>22. Fully specify constraints on policy scope</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>23. Preferred attachment point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>24. Semantics of multiple assertions of the same kind</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>25. Independent Assertions</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>26. 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
@@ -269,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="d3e253" id="d3e253"></a>4. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
+<h2><a name="d3e259" id="d3e259"></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
@@ -804,7 +804,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="d3e718" id="d3e718"></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="d3e724" id="d3e724"></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,
@@ -835,7 +835,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="d3e758" id="d3e758"></a>5.6.2 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
+<h4><a name="d3e764" id="d3e764"></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
@@ -890,7 +890,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 18: 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="d3e803" id="d3e803"></a>5.6.2.1 Example</h5><p>
+<h5><a name="d3e809" id="d3e809"></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.
@@ -952,13 +952,15 @@
</p><p> In using WSDL attachment, it should be noted that the
service policy subject is a collection of endpoint policy
subjects. The endpoint policy subject is a collection of
- operation policy subjects and etc. As a result, the WSDL
+ operation policy subjects and so on. As a result, the WSDL
policy subjects compose naturally. It is quite tempting to
associate the identified behavior to a broader policy subject
than to a fine granular policy subject. For instance, it is
convenient to attach a supporting token assertion (defined by
the Web Services Security Policy specification) to an endpoint
- policy subject instead of a message policy subject.
+ policy subject instead of a message policy subject. However such
+ policy attachments to policy subjects of broader scope and granularity
+ should be done only after careful evaluation.
</p><div class="boxedtext"><p><a name="bp-WSDL-multiple-policy-subjects" id="bp-WSDL-multiple-policy-subjects"></a><span class="practicelab">Good
practice 21: Assertion 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
@@ -974,21 +976,26 @@
time in order to avoid conflicting behavior.
</p><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>The current set of subjects as mapped to the WSDL 1.1
+ 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><div class="boxedtext"><p><a name="bp-WSDL-policy-scope-semantics" id="bp-WSDL-policy-scope-semantics"></a><span class="practicelab">Good
+practice 22: Fully specify constraints on policy scope</span></p><p class="practice">Assertion authors must clearly describe any constraints on the
+ policy scope if not limited to policy subjects identified by the policy
+ attachment point.
+ </p></div><p>The current set of subjects as mapped to the WSDL 1.1
elements, can also constrain the assertion constructs.
- For Example, in WS-RM,
- the assertion authors chose to support certain capabilities at
- the endpoint level. This resulted in the finer granularity of
- the assertion to apply at the message policy subject, but the
- assertion semantics also indicates that the if
- a sender chose to engage RM
- semantics (although not specified via attachment in WSDL at incoming
- messages), the providers will honor the engagement of RM.
- This is illustrative of how the
- assertion author can specify additional constraints and
- assumptions for attachment and engagement of behavior.
+ For Example, in WS-RM, the assertion authors chose to support
+ certain capabilities at the endpoint level. This resulted in
+ the finer granularity of the assertion to apply at the message
+ policy subject, but the assertion semantics also indicates that
+ the if a sender chose to engage RM semantics (although not specified
+ via attachment in WSDL at incoming messages), the providers will honor
+ the engagement of RM. So, the WS-RM Policy is a capability that
+ governs a target endpoints capability to accept sequences that
+ is beyond single message exchanges. This is illustrative of how the
+ assertion author can specify additional constraints and assumptions
+ for attachment and engagement of behavior. Such additional constraints
+ must be clearly specified by the assertion authors.
</p><div class="boxedtext"><p><a name="bp-WSDL-preferred-attachment-point" id="bp-WSDL-preferred-attachment-point"></a><span class="practicelab">Good
-practice 22: Preferred attachment point for an Assertion</span></p><p class="practice">If an assertion can be attached at multiple points within a policy
+practice 23: Preferred attachment point for an Assertion</span></p><p class="practice">If an assertion can be attached at multiple points within a policy
subject, an assertion author should specify a preferred attachment
point for the chosen policy subject.
</p></div><p>One approach in WSDL is to identify different attachment points in
@@ -997,15 +1004,37 @@
specify that as a preferred attachment point. However, this
approach only works if the policy subject is a true WSDL
construct other than some other protocol concept that is
- layered over WSDL message exchanges. For example, the WS-RM
- Policy is a capability that governs a target endpoints
+ layered over WSDL message exchanges. For example, as described previously
+ the WS-RM Policy is a capability that governs a target endpoints
capability to accept sequences that is beyond single message
exchanges. Therefore, its semantics encompasses the cases when
message level policy subjects may be used as attachment but
considers when sequences are present. In addition, when the
policy assertions do not target wire-level behaviors but
rather abstract requirements, this technique does not apply.
- </p></div><div class="div2">
+ </p><div class="boxedtext"><p><a name="bp-WSDL-policy-multiple-instance-semantics" id="bp-WSDL-policy-multiple-instance-semantics"></a><span class="practicelab">Good
+practice 24: Semantics of multiple assertions of the same kind</span></p><p class="practice">A policy alternative can contain multiple instances of the
+ same policy assertion. An assertion description should specify the
+ semantics of multiple instances of a policy assertion in the same
+ policy alternative and the semantics of parameters and nested policy
+ (if any) when there are multiple instances of a policy assertion in
+ the same policy alternative.
+ </p></div><p>Assertion authors that utilize WSDL policy subjects need to
+ understand how the assertions will be processed in merging and
+ the specify implications of ending up with multiple assertions of
+ the same kind in an alternative, in the merged policy. For example,
+ consider the SignedParts assertion defined in WS-SecurityPolicy 1.2.
+ The definition of SignedParts assertion explicitly permits multiple
+ SignedParts assertions to be present within a policy alternative,
+ and declares it to be equivalent to a single SignedParts assertion
+ containing the union of all specified message parts. So, if a SignedParts
+ assertion is specified in a WSDL binding at the input message level
+ and subsequently an additional SignedParts assertion is specified
+ at the WSDL endpoint policy subject level, then the effective policy
+ at the endpoint could have more than one SignedParts assertion in the
+ same alternative. However, the clear semantics defined by the SignedParts
+ assertion enable processing of the multiple occurrences properly.
+ </p></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
their domain may fit with assertions for interrelated domains. A
classic example of such an interrelated domain is security, because
@@ -1046,7 +1075,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 23: 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 25: 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>
@@ -1074,7 +1103,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 24: Change of the Policy Subject Over Time</span></p><p class="practice">If the policy subjects change over time,
+practice 26: 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">
@@ -1582,4 +1611,10 @@
to address editors' action items
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/251">251</a>.
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/256">256</a>.
+ </td></tr><tr><td rowspan="1" colspan="1">20070511</td><td rowspan="1" colspan="1">PY</td><td rowspan="1" colspan="1">Updated 5.6 WSDL guidelines section to add G19 identified in AI 256 (now G24).
+ Accounts for parts of resolution for
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>
+ corresponding to editors' action item
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/232">256</a>
+ - now complete.
</td></tr></tbody></table><br></div></div></body></html>
\ No newline at end of file
Received on Friday, 11 May 2007 22:51:21 UTC