- From: Prasad Yendluri via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 07 May 2007 20:04:38 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv1669
Modified Files:
ws-policy-guidelines.html
Log Message:
Updated 5.6 WSDL guidelines section, to follow the new format and added G15, G16, G17 and G18. Accounts for parts of resolution for issue 3989 corresponding to editors' action items 232, 253, and 256.
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.50
retrieving revision 1.51
diff -u -d -r1.50 -r1.51
--- ws-policy-guidelines.html 1 May 2007 23:24:56 -0000 1.50
+++ ws-policy-guidelines.html 7 May 2007 20:04:36 -0000 1.51
@@ -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="#d3e244">Who is involved in authoring Assertions? </a><br>
+4. <a href="#d3e240">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,10 +137,10 @@
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="#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.5.1 <a href="#d3e661">Optional behavior in Compact authoring</a><br>
+ 5.5.2 <a href="#d3e701">Optional behavior at runtime</a><br>
+ 5.5.2.1 <a href="#d3e746">Example</a><br>
+ 5.6 <a href="#levels-of-abstraction">Considerations for Policy Attachment 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>
6.1 <a href="#Referencing_Policy_Expressions">Referencing Policy Expressions</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 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="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="#bp-assertions-and-message-semantics"><b>6. Assertions and Message Semantics</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>7. Duplication of Assertions</b></a></p></li><li><p><a href="#bp-assertion-definition"><b>8. Definition of Policy Assertions</b></a></p></li><li><p><a href="#bpnesting"><b>9. Nesting of Assertions</b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>10. Assertion XML should allow use of wsp:Optional attribute</b></a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional"><b>11. Assertion description should explicitly indicate that wsp:Optional is allowed.</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>12. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>13. 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>14. Indicate use of an Optional Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>15. An assertion description should specify a policy subject</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>16. Granularity of policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>17. Assertin attachment to multiple policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>18. Preferred attachment point for an Assertion</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>19. Independent Assertions</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>20. 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
@@ -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="d3e244" id="d3e244"></a>4. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
+<h2><a name="d3e240" id="d3e240"></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
@@ -382,7 +382,7 @@
</p><p>
The WS-Policy Attachment specification defines a number of different
policy subjects to which an assertion can be attached. For attaching to
- WSDL subjects see <a href="#levels-of-abstraction"><b>5.6 Levels of Abstraction in WSDL </b></a> for more detail.
+ WSDL subjects see <a href="#levels-of-abstraction"><b>5.6 Considerations for Policy Attachment in WSDL </b></a> for more detail.
Additionally, the framework provides for the means to extend the set of
policy subjects beyond the set of subjects defined in the WS-Policy
Attachment specification.
@@ -747,7 +747,6 @@
authors must understand that this type of assertion will
require additional processing by consumers in order to
disambiguate the assertions or to understand the semantics of
-
the name value pairs, complex content, attribute values
contribution to the processing. The tradeoff is the generality
vs. the flexibility and complexity of the comparison expected for a domain. </p><p>
@@ -766,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="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
+<h4><a name="d3e661" id="d3e661"></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,
@@ -797,7 +796,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="d3e705" id="d3e705"></a>5.5.2 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
+<h4><a name="d3e701" id="d3e701"></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
@@ -852,7 +851,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 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="d3e750" id="d3e750"></a>5.5.2.1 Example</h5><p>
+<h5><a name="d3e746" id="d3e746"></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.
@@ -878,40 +877,34 @@
exchange when optionally used in part of that exchange
(<a href="#bp-entire-mep-for-optional">Good Practice: Consider entire message exchange pattern when specifying Assertions that may be optional</a>).
</p></div></div></div><div class="div2">
-<h3><a name="levels-of-abstraction" id="levels-of-abstraction"></a>5.6 Levels of Abstraction in WSDL </h3><p>A behavior identified by a policy assertion applies to the
+<h3><a name="levels-of-abstraction" id="levels-of-abstraction"></a>5.6 Considerations for Policy Attachment in WSDL </h3><p>A behavior identified by a policy assertion applies to the
associated policy subject. If a policy assertion is to be used
- within WSDL, Assertion Authors must specify a WSDL
- policy subject. The policy subject is determined with respect
- to a behavior as follows:
- </p><ul><li><p>If the behavior applies to any message exchange
+ within WSDL, assertion authors must specify a WSDL
+ policy subject.
+ </p><div class="boxedtext"><p><a name="bp-WSDL-policy-subject" id="bp-WSDL-policy-subject"></a><span class="practicelab">Good
+practice 15: An assertion description should specify a policy subject</span></p><p class="practice">Assertion authors should associate assertions with the appropriate policy subject.
+ For instance, if a policy assertion is to be used with WSDL, the assertion description
+ should specify a WSDL policy subject – such as service, endpoint, operation and message.
+ </p></div><p>The specific WSDL policy subject is determined with respect to
+ a behavior as follows:</p><ul><li><p>If the behavior applies to any message exchange
using any of the endpoints offered by a service then the
subject is the service policy subject. </p></li><li><p>If the behavior applies to any message exchange
made using an endpoint then the subject is the endpoint policy subject. </p></li><li><p>If the behavior applies to any message exchange
defined by an operation then the subject is the operation policy subject. </p></li><li><p>If the behavior applies to an input message then
- the subject is the message policy subject - similarly for output and fault message policy subjects.</p></li></ul><p>Assertion Authors that wish to utilize WSDL policy subjects need to understand how the assertions will be
+ the subject is the message policy subject - similarly for output and fault message policy subjects.</p></li></ul><p>Assertion authors that wish to utilize WSDL policy subjects need to
+ understand how the assertions will be
processed in intersection and merging and the implications of
the processing for considering a specific attachment point and
policy subject. This topic is considered in detail in <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>
- </p><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.
- </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> For a given WSDL policy subject, there may be several
+ </p><div class="boxedtext"><p><a name="bp-WSDL-policy-subject-Granularity" id="bp-WSDL-policy-subject-Granularity"></a><span class="practicelab">Good
+practice 16: Granularity of policy subjects</span></p><p class="practice">Assertion authors should choose the most granular policy subject
+ that the behavior represented by a policy assertion applies to.
+ </p></div><p> For a given WSDL policy subject, there may be several
attachment points. For example, there are three attachment
points for the endpoint policy subject: the port, binding and
- portType element. Assertion Authors should identify the
+ portType element. Assertion authors should identify the
relevant attachment point when defining a new assertion. To
- determine the relevant attachment points, Assertion Authors should
+ determine the relevant attachment points, assertion authors should
consider the scope of the attachment point. For example, an
assertion should only be allowed in the portType element if
the assertion reasonably applies to any endpoint that ever
@@ -926,17 +919,43 @@
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. Similarly,
- for authoring convenience, an assertion author may allow the
+ policy subject instead of a message policy subject.
+ </p><div class="boxedtext"><p><a name="bp-WSDL-multiple-policy-subjects" id="bp-WSDL-multiple-policy-subjects"></a><span class="practicelab">Good
+practice 17: 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
+ instances of the same assertion attached to multiple policy subjects
+ at the same time.
+ </p></div><p>
+ For authoring convenience, an assertion author may allow the
association of an assertion to multiple policy subjects. If an
assertion is allowed to be associated with multiple policy
- subjects then <em>the assertion author has the burden to
- describe the semantics of multiple instances of the same
- assertion attached to multiple policy subjects at the same
- time in order to avoid conflicting behavior. </em>
- </p><p>One approach is to specify a policy subject, choose the
- most granular policy subject that the behavior applies to and
- specify a preferred attachment point in WSDL. However, this
+ subjects as is possible with WSDL, then the assertion author has
+ the burden to describe the semantics of multiple instances of the
+ same assertion attached to multiple policy subjects at the same
+ 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
+ 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.
+ </p><div class="boxedtext"><p><a name="bp-WSDL-preferred-attachment-point" id="bp-WSDL-preferred-attachment-point"></a><span class="practicelab">Good
+practice 18: 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
+ a policy subject, choose the most granular policy subject that the
+ behavior applies to and
+ 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
@@ -988,7 +1007,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 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
+practice 19: 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>
@@ -1016,7 +1035,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 16: Change of the Policy Subject Over Time</span></p><p class="practice">If the policy subjects change over time,
+practice 20: 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">
@@ -1509,4 +1528,11 @@
Also replaced TBD in section 2 with descriptive text."
</td></tr><tr><td rowspan="1" colspan="1">20070501</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Reset Section <a href="#change-description"><b>E. Changes in this Version of
the Document</b></a>.
+ </td></tr><tr><td rowspan="1" colspan="1">20070507</td><td rowspan="1" colspan="1">PY</td><td rowspan="1" colspan="1">Updated 5.6 WSDL guidelines section, to follow the new format and added G15, G16, G17 and G18.
+ 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 items
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/232">232</a>,
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/232">253</a>, and
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/232">256</a>.
</td></tr></tbody></table><br></div></div></body></html>
\ No newline at end of file
Received on Monday, 7 May 2007 20:04:41 UTC