- From: David Orchard via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 18 Jul 2007 15:52:19 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy In directory hutz:/tmp/cvs-serv24475 Modified Files: ws-policy-guidelines.xml ws-policy-guidelines.html Log Message: Resolution for 4661, 4662, 4861 Index: ws-policy-guidelines.html =================================================================== RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v retrieving revision 1.85 retrieving revision 1.86 diff -u -d -r1.85 -r1.86 --- ws-policy-guidelines.html 18 Jul 2007 12:46:19 -0000 1.85 +++ ws-policy-guidelines.html 18 Jul 2007 15:52:16 -0000 1.86 @@ -136,11 +136,10 @@ 5.4.1 <a href="#parameterized-assertions">Assertions with Parameters</a><br> 5.4.2 <a href="#nested-assertions">Nested Assertions</a><br> 5.5 <a href="#Ignorable">Designating Ignorable Behavior</a><br> - 5.5.1 <a href="#d3e751">Ignorable behavior in authoring</a><br> - 5.5.2 <a href="#d3e764">Ignorable behavior at runtime</a><br> + 5.5.1 <a href="#d3e780">Ignorable behavior in authoring</a><br> + 5.5.2 <a href="#d3e793">Ignorable behavior at runtime</a><br> 5.6 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br> - 5.6.1 <a href="#d3e779">Optional behavior in Compact authoring</a><br> - 5.6.2 <a href="#d3e819">Optional behavior at runtime</a><br> + 5.6.1 <a href="#d3e808">Optional behavior at runtime</a><br> 5.7 <a href="#levels-of-abstraction">Considerations for Policy Attachment in WSDL </a><br> 5.8 <a href="#interrelated-domains">Interrelated domains</a><br> 6. <a href="#versioning-policy-assertions">Versioning Policy Assertions</a><br> @@ -203,8 +202,9 @@ </p></div><div class="div1"> <h2><a name="best-practices-list" id="best-practices-list"></a>2. List of Best Practice Statements</h2><p>The following Best Practices appear in this document with discussion and examples, and are summarized here for quick reference:</p><ul><li><p><a href="#bp-assertion-semantics"><b>1. Semantics Independent of Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-compatibility-tests"><b>2. Behaviors Relevant to Compatibility Tests</b></a></p></li><li><p><a href="#bp-semantics-and-form"><b>3. Semantics Independent of the Form</b></a></p></li><li><p><a href="#bp-assertion-start"><b>4. Start with a Simple Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>5. Use Unique QNames</b></a></p></li><li><p><a href="#XMLOutline"><b>6. Provide an XML Outline</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>7. Specify Semantics Clearly</b></a></p></li><li><p><a href="#DefineIgnorable"><b>8. Assertion Authors Should Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>9. Assertion Authors Should Document Use of the Ignorable -Attribute in XML </b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>10. Not Necessary to Understand a Message</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>11. Avoid Duplication of Assertions</b></a></p></li><li><p><a href="#bp-assertion-parameters"><b>12. Use Parameters for Useful - Information</b></a></p></li><li><p><a href="#bp-dependent-behaviors"><b>13. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>14. Enumerate Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>15. Discourage Domain Specific Intersection</b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>16. Assertion XML should allow use of wsp:Optional attribute</b></a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional"><b>17. Use the wsp:Optional attribute to indicate optional</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>18. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>19. Consider entire message exchange pattern when specifying Assertions that may be optional</b></a></p></li><li><p><a href="#bp-indicate-optional-assertion-use"><b>20. Indicate use of an Optional Assertion</b></a></p></li><li><p>a href="#bp-WSDL-policy-subject"><b>21. Specify Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>22. Choose the Most Granular Policy Subject</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>23. Define Semantics of Attachment to Multiple Policy Subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>24. Specify Preferred Attachment Point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>25. Describe Semantics of Multiple Assertions of Same Type</b></a></p></li><li><p><a href="#bp-specify-composition"><b>26. Specify Composition with Related Assertions</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>27. Use Independent Assertions for Different Versions of a Behavior</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>28. Change of the Policy Subject Over Time</b></a></p></li></ul></div><div class="div1"> +Attribute in XML </b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>10. Assertion Authors should allow use of wsp:Optional +attribute</b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>11. Not Necessary to Understand a Message</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>12. Avoid Duplication of Assertions</b></a></p></li><li><p><a href="#bp-assertion-parameters"><b>13. Use Parameters for Useful + Information</b></a></p></li><li><p><a href="#bp-dependent-behaviors"><b>14. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>15. Enumerate Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>16. Discourage Domain Specific Intersection</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>17. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>18. 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>19. Indicate use of an Optional Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>20. Specify Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>21. Choose the Most Granular Policy Subject</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>22. Define Semantics f Attachment to Multiple Policy Subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>23. Specify Preferred Attachment Point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>24. Describe Semantics of Multiple Assertions of Same Type</b></a></p></li><li><p><a href="#bp-specify-composition"><b>25. Specify Composition with Related Assertions</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>26. Use Independent Assertions for Different Versions of a Behavior</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="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 @@ -390,10 +390,10 @@ <ul><li><p>The definition of the assertion's semantic (See best practice <a href="#AssertionDefinitions"><b>7. Specify Semantics Clearly</b></a>).</p></li><li><p>The specification of the set of valid policy subjects to which an assertion may be attached - (See best practice <a href="#bp-WSDL-policy-subject"><b>21. Specify Policy Subject(s)</b></a>).</p></li><li><p>The scope of the assertion in the context of a particular policy + (See best practice <a href="#bp-WSDL-policy-subject"><b>20. Specify Policy Subject(s)</b></a>).</p></li><li><p>The scope of the assertion in the context of a particular policy subject (See best practices in Section <a href="#levels-of-abstraction"><b>5.7 Considerations for Policy Attachment in WSDL </b></a>).</p></li><li><p>Any composition considerations if the assertion is used with other assertions in a context - (See best practice <a href="#bp-specify-composition"><b>26. Specify Composition with Related Assertions</b></a>).</p></li></ul> + (See best practice <a href="#bp-specify-composition"><b>25. Specify Composition with Related Assertions</b></a>).</p></li></ul> </p><p> The WS-Policy Attachment specification defines a number of different policy subjects to which an assertion can be attached. For attaching to @@ -598,7 +598,38 @@ Practice 9: Assertion Authors Should Document Use of the Ignorable Attribute in XML </span></p><p class="practice"> An Assertion Author should document, in the XML outline and/or schema for the assertion, whether or not the assertion allows for the use of the wsp:Ignorable attribute. - </p></div></div><div class="div3"> + </p></div><p>To give an example, the WS-ReliableMessaging Policy document specifies attribute extensibility as part of the XML definition, allowing the wsp:Ignorable attribute: + </p><div class="exampleOuter"> +<p style="text-align: left" class="exampleHead"><i><span>Example 5-5. </span>WS-ReliableMessaging Policy use of attribute extensibility</i></p><div class="exampleInner"><pre>/wsrmp:RMAssertion/@{any} +This is an extensibility mechanism to allow different {extensible} types of information, based on a schema, to be passed. + </pre></div></div><p> The Policy Framework provides two modes of authoring policy expressions: +compact and normal form. One of the mechanisms that the Policy Framework +provides to policy authors for purposes of writing compact policy +expressions is the wsp:Optional attribute. Assertion Authors should allow +for the use of the wsp:Optional attribute in the XML outline and/or schema +definition of an assertion as this will allow policy expression authors to +compose compact policy expressions.</p><div class="boxedtext"><p><a name="bp-assertion-xml-allow-optional" id="bp-assertion-xml-allow-optional"></a><span class="practicelab">Best +Practice 10: Assertion Authors should allow use of wsp:Optional +attribute</span></p><p class="practice">An assertion's XML outline and/or schema definition should allow the use +of the wsp:Optional attribute so as to enable policy authors to compose +compact policy expressions.</p></div><p>For example, consider the following two equivalent policy expressions:</p><div class="exampleOuter"> +<p style="text-align: left" class="exampleHead"><i><span>Example 5-6. </span>Normal form expression:</i></p><div class="exampleInner"><pre><wsp:Policy> + <wsp:ExactlyOne> + <wsp:All> + <wsam:Addressing> + <wsp:Policy/> + </wsam:Addressing> + </wsp:All> + <wsp:All> + </wsp:All> + </wsp:ExactlyOne> +</wsp:Policy></pre></div></div><div class="exampleOuter"> +<p style="text-align: left" class="exampleHead"><i><span>Example 5-7. </span>Compact form expression:</i></p><div class="exampleInner"><pre><wsp:Policy> + <wsam:Addressing wsp:Optional="true"> + <wsp:Policy/> + </wsam:Addressing> +</wsp:Policy></pre></div></div><p> +If the assertion author had not provided for the wsp:Optional attribute to be included on the assertion, then policy expression authors would be forced to express the optionality of a behavior as two explicit policy alternatives, one with and one without that assertion when including assertions of that type in their policies.</p></div><div class="div3"> <h4><a name="self-describing" id="self-describing"></a>5.3.3 Self Describing Messages </h4><p> WS-Policy is intended to communicate the requirements, capabilities and behaviors of nodes that provide the message's path, not specifically to declare properties of the message semantics. One of the advantages of Web services is that an XML message can be stored and later examined (e.g. as a record of a business @@ -629,7 +660,7 @@ their assertions by specifying additional properties, headers, etc. that must be present in a message as part of their assertion design. </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">Best -Practice 10: Not Necessary to Understand a Message</span></p><p class="practice">Assertion Authors 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 +Practice 11: Not Necessary to Understand a Message</span></p><p class="practice">Assertion Authors 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 @@ -659,7 +690,7 @@ </p><p>It is the responsibility of the Assertion Authors to avoid duplication of assertions. A review by a broad community is the best way to ensure that the granularity of a set of domain assertions is appropriate.</p><div class="boxedtext"><p><a name="bp-assertion-duplication" id="bp-assertion-duplication"></a><span class="practicelab">Best -Practice 11: Avoid Duplication of Assertions</span></p><p class="practice">Assertion Authors should reuse an existing assertion (rather than create a new one) whenever possible.</p></div></div></div><div class="div2"> +Practice 12: Avoid Duplication of Assertions</span></p><p class="practice">Assertion Authors should reuse an existing assertion (rather than create a new one) whenever possible.</p></div></div></div><div class="div2"> <h3><a name="comparison" id="comparison"></a>5.4 Comparison of Nested and Parameterized Assertions</h3><p>There are two different ways to provide additional information in an assertion beyond its type. We cover these two cases below followed by a comparison of these approaches targeting when to use either of the approach. @@ -674,7 +705,7 @@ domain specific processing for policy intersection.</p><p>In the XML representation of a policy assertion, the child elements and attributes of the assertion excluding child elements and attributes 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">Best -Practice 12: Use Parameters for Useful +Practice 13: Use Parameters for Useful Information</span></p><p class="practice">Assertion Authors should represent useful (or additional) information necessary for engaging the behavior represented by a policy assertion as assertion parameters. @@ -685,7 +716,7 @@ These two parameters identify the parts of a wire message that should be protected. These parameters carry additional useful information for engaging the behavior.</p><div class="exampleOuter"> -<p style="text-align: left" class="exampleHead"><i><span>Example 5-5. </span>Policy Assertion with Assertion Parameters</i></p><div class="exampleInner"><pre><wsp:Policy> +<p style="text-align: left" class="exampleHead"><i><span>Example 5-8. </span>Policy Assertion with Assertion Parameters</i></p><div class="exampleInner"><pre><wsp:Policy> <sp:SignedParts> <sp:Body/> <sp:Header/> @@ -704,10 +735,10 @@ that are allowed. There is one caveat to watch out for: policy assertions with deeply nested policy can greatly increase the complexity of a policy and should be avoided when they are not needed.</p><div class="boxedtext"><p><a name="bp-dependent-behaviors" id="bp-dependent-behaviors"></a><span class="practicelab">Best -Practice 13: Use Nested Assertions for Dependent Behaviors</span></p><p class="practice">Assertion Authors should represent dependent behaviors that are relevant +Practice 14: Use Nested Assertions for Dependent Behaviors</span></p><p class="practice">Assertion Authors should represent dependent behaviors that are relevant to a compatibility test and apply to the same policy subject using nested policy assertions.</p></div><div class="boxedtext"><p><a name="bp-declare-nested-assertions" id="bp-declare-nested-assertions"></a><span class="practicelab">Best -Practice 14: Enumerate Nested Assertions</span></p><p class="practice">If there is a nested policy expression, then the Assertion Authors +Practice 15: Enumerate Nested Assertions</span></p><p class="practice">If there is a nested policy expression, then the Assertion Authors should enumerate the nested policy assertions that are allowed.</p></div><p>The main consideration for selecting parameters or nesting of assertions is that <em>the framework intersection algorithm processes nested alternatives, but does not consider @@ -729,7 +760,7 @@ delegated to the specific domain handlers that are not visible to the WS-Policy framework. However, domain specific intersection processing reduces interop and increases the burden to implement an assertion.</p><div class="boxedtext"><p><a name="bp-discourage-domain-specific-intersection" id="bp-discourage-domain-specific-intersection"></a><span class="practicelab">Best -Practice 15: Discourage Domain Specific Intersection</span></p><p class="practice">Assertion authors should only specify domain specific +Practice 16: Discourage Domain Specific Intersection</span></p><p class="practice">Assertion authors should only specify domain specific intersection semantics when policy intersection is insufficient.</p></div><p>We will use the WS-SecurityPolicy to illustrate the use of nested assertions. </p><p>Securing messages is a complex usage scenario. The WS-SecurityPolicy Assertion Authors have defined the <code>sp:TransportBinding</code> policy assertion to indicate @@ -760,7 +791,7 @@ already requires the use of transport-level security for protecting messages). </p><div class="exampleOuter"> -<p style="text-align: left" class="exampleHead"><i><span>Example 5-6. </span>Transport Security Policy Assertion</i></p><div class="exampleInner"><pre><sp:TransportBinding> +<p style="text-align: left" class="exampleHead"><i><span>Example 5-9. </span>Transport Security Policy Assertion</i></p><div class="exampleInner"><pre><sp:TransportBinding> <Policy> <sp:TransportToken> <Policy> @@ -806,7 +837,7 @@ <code>HttpToken</code> is used with an empty nested policy in a policy expression by a provider, it will indicate that none of the dependent behaviors namely authentication or client certificate is required.</p><div class="exampleOuter"> -<p style="text-align: left" class="exampleHead"><i><span>Example 5-7. </span>Empty Nested Policy Expression</i></p><div class="exampleInner"><pre><sp:TransportToken> +<p style="text-align: left" class="exampleHead"><i><span>Example 5-10. </span>Empty Nested Policy Expression</i></p><div class="exampleInner"><pre><sp:TransportToken> <wsp:Policy> <sp:HttpsToken> <wsp:Policy/> @@ -816,54 +847,23 @@ certificate will not be able to use this provider solely on the basis of intersection algorithm alone.</p></div></div><div class="div2"> <h3><a name="Ignorable" id="Ignorable"></a>5.5 Designating Ignorable Behavior</h3><div class="div3"> -<h4><a name="d3e751" id="d3e751"></a>5.5.1 Ignorable behavior in authoring</h4><p> +<h4><a name="d3e780" id="d3e780"></a>5.5.1 Ignorable behavior in authoring</h4><p> The Policy Framework provides an intersection algorithm that has two defined modes for processing (lax and strict). The Framework also defines an attribute (wsp:Ignorable) that can be used to influence whether assertions are part of the compatability assessment between two alternatives. [see <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite> and <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>]. Assertion authors should consider whether the behavior represented by the Assertion they are defining can be safely ignored for the purposes of intersection, and should follow <a href="#DefineIgnorable"><b>8. Assertion Authors Should Document Ignorable Behavior</b></a> and <a href="#ignorableAssertions"><b>9. Assertion Authors Should Document Use of the Ignorable Attribute in XML </b></a> to include this guidance in the assertion's definition.</p></div><div class="div3"> -<h4><a name="d3e764" id="d3e764"></a>5.5.2 Ignorable behavior at runtime</h4><p>Regardless of whether the assertion allows the ignorable attribute, assertion authors should +<h4><a name="d3e793" id="d3e793"></a>5.5.2 Ignorable behavior at runtime</h4><p>Regardless of whether the assertion allows the ignorable attribute, assertion authors should indicate the semantic of the runtime behavior in the description of the assertion. </p><p> As said in <a href="ws-policy-primer.html#strict-lax-policy-intersection">section 3.4.1 Strict and Lax Policy Intersection</a> in <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>, "Regardless of the chosen intersection mode, ignorable assertions do not express any wire-level requirements on the behavior of consumers - in other words, a consumer could choose to ignore any such assertions that end up in the resulting policy after intersection, with no adverse effects on runtime interactions." Therefore, any assertion that is marked with ignorable should not impose any wire-level requirements on the part of consumers. Assertion Authors are reminded that regardless of whether an assertion is marked as ignorable, policy consumers using strict intersection will not 'ignore' the assertion. </p></div></div><div class="div2"> <h3><a name="optional-policy-assertion" id="optional-policy-assertion"></a>5.6 Designating Optional Behaviors</h3><div class="div3"> -<h4><a name="d3e779" id="d3e779"></a>5.6.1 Optional behavior in Compact authoring</h4><p>Optional behaviors represent behaviors that may be engaged by a consumer. When using the - compact authoring form for assertions, such behaviors are marked by - using <code>wsp:Optional</code> attribute with a value of - "true". (In order to simplify reference to such assertions, - we just use the phrase “optional assertions” in this section.) - During the process of normalization the runtime - behavior is indicated by two policy alternatives, one with and - one without the assertion. In a consumer/provider - scenario, the choice of engaging the runtime behavior is upon - 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. Assertion Authors 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">Best -Practice 16: 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-8. </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">Best -Practice 17: Use the wsp:Optional attribute to indicate optional</span></p><p class="practice">Assertion authors should use the wsp:Optional attribute to indicate that a - behavior indicated by a 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-9. </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="d3e819" id="d3e819"></a>5.6.2 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for +<h4><a name="d3e808" id="d3e808"></a>5.6.1 Optional behavior at runtime</h4><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">This section does not have Working Group consensus and there is an outstanding action item to revise it</td></tr></table><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">Best -Practice 18: Limit use of Optional Assertions</span></p><p class="practice">Assertion Authors should not use optional assertions for behaviors that must be present +Practice 17: 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 @@ -895,7 +895,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">Best -Practice 19: 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 18: 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 @@ -909,7 +909,7 @@ (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">Best -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, +Practice 19: 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><p> The <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite> document contains an example that outlines the use of @@ -947,7 +947,7 @@ 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><div class="boxedtext"><p><a name="bp-WSDL-policy-subject" id="bp-WSDL-policy-subject"></a><span class="practicelab">Best -Practice 21: Specify Policy Subject(s)</span></p><p class="practice">Assertion Authors should specify the set of relevant policy subjects with which +Practice 20: Specify Policy Subject(s)</span></p><p class="practice">Assertion Authors should specify the set of relevant policy subjects with which the assertion may be associated. 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. @@ -980,7 +980,7 @@ 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-policy-subject-Granularity" id="bp-WSDL-policy-subject-Granularity"></a><span class="practicelab">Best -Practice 22: Choose the Most Granular Policy Subject</span></p><p class="practice">Assertion Authors should choose the most granular policy subject +Practice 21: Choose the Most Granular Policy Subject</span></p><p class="practice">Assertion Authors should choose the most granular policy subject to which the behavior represented by a policy assertion applies. </p></div><p> For authoring convenience, Assertion Authors may allow the @@ -991,7 +991,7 @@ same assertion attached to different policy subjects at the same time in order to avoid conflicting behavior. </p><div class="boxedtext"><p><a name="bp-WSDL-multiple-policy-subjects" id="bp-WSDL-multiple-policy-subjects"></a><span class="practicelab">Best -Practice 23: Define Semantics of Attachment to Multiple Policy Subjects</span></p><p class="practice">If an assertion is allowed to be associated with multiple policy subjects, +Practice 22: Define Semantics of Attachment to Multiple Policy Subjects</span></p><p class="practice">If an assertion is allowed to be associated with multiple policy subjects, the assertion author should describe the semantics of multiple instances of the same assertion attached to multiple policy subjects at the same time. </p></div><p>If the capability is not really suitable and may imply @@ -1012,7 +1012,7 @@ when the policy assertions do not target wire-level behaviors but rather abstract requirements, this technique does not apply. </p><div class="boxedtext"><p><a name="bp-WSDL-preferred-attachment-point" id="bp-WSDL-preferred-attachment-point"></a><span class="practicelab">Best -Practice 24: Specify Preferred Attachment Point for an Assertion</span></p><p class="practice">If an assertion can be attached at multiple attachment points +Practice 23: Specify Preferred Attachment Point for an Assertion</span></p><p class="practice">If an assertion can be attached at multiple attachment points within a policy subject, Assertion Authors should specify a preferred attachment point for the chosen policy subject. </p></div><p>Assertion Authors that utilize WSDL policy subjects need to @@ -1031,7 +1031,7 @@ same alternative. However, the clear semantics defined by the SignedParts assertion enable processing of the multiple occurrences properly. </p><div class="boxedtext"><p><a name="bp-WSDL-policy-multiple-instance-semantics" id="bp-WSDL-policy-multiple-instance-semantics"></a><span class="practicelab">Best -Practice 25: Describe Semantics of Multiple Assertions of Same Type</span></p><p class="practice">A policy alternative can contain multiple instances of the same +Practice 24: Describe Semantics of Multiple Assertions of Same Type</span></p><p class="practice">A policy alternative can contain multiple instances of the same policy assertion type. Assertion authors should specify the semantics of multiple instances of same policy assertion type in the same policy alternative and the semantics of parameters and nested policy (if any) @@ -1043,7 +1043,7 @@ 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 class="boxedtext"><p><a name="bp-specify-composition" id="bp-specify-composition"></a><span class="practicelab">Best -Practice 26: Specify Composition with Related Assertions</span></p><p class="practice">Assertion authors should clearly specify how an assertion +Practice 25: Specify Composition with Related Assertions</span></p><p class="practice">Assertion authors should clearly specify how an assertion may compose with other related assertions, if any.</p></div><p> A classic example of such an interrelated domain is security, because security tends to @@ -1053,7 +1053,7 @@ additional assertions related to [<cite><a href="#WS-SecurityPolicy">WS-SecurityPolicy</a></cite>], an interrelated security domain. One such additional assertion specifies the use of transport security to protect a message sequence, for example.</p><div class="exampleOuter"> -<p style="text-align: left" class="exampleHead"><i><span>Example 5-10. </span>Reliable Message Sequence Security</i></p><div class="exampleInner"><pre><wsrmp:SequenceTransportSecurity [wsp:Optional="true"]? ... /></pre></div></div><p>The Reliable Message Policy specification states +<p style="text-align: left" class="exampleHead"><i><span>Example 5-11. </span>Reliable Message Sequence Security</i></p><div class="exampleInner"><pre><wsrmp:SequenceTransportSecurity [wsp:Optional="true"]? ... /></pre></div></div><p>The Reliable Message Policy specification states "This assertion is effectively meaningless unless it occurs in conjunction with the <code>RMAssertion</code> and a <code>sp:TransportBinding</code> assertion that requires the use of some transport-level security mechanism (e.g. <code>sp:HttpsToken</code>)". @@ -1086,7 +1086,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">Best -Practice 27: Use Independent Assertions for Different Versions of a Behavior</span></p><p class="practice">Assertion Authors should use independent assertions for modeling different +Practice 26: Use Independent Assertions for Different Versions of a Behavior</span></p><p class="practice">Assertion Authors should use independent assertions for modeling different 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"> @@ -1099,7 +1099,7 @@ <sp:Wss11>…</sp:Wss11> </Policy></pre></div></div></div><div class="div2"> <h3><a name="supporting-new-policy-subjects" id="supporting-new-policy-subjects"></a>6.3 Supporting New Policy Subjects</h3><p> - The best practice <a href="#bp-WSDL-policy-subject"><b>21. Specify Policy Subject(s)</b></a> specifies that policy authors should + The best practice <a href="#bp-WSDL-policy-subject"><b>20. Specify Policy Subject(s)</b></a> specifies that policy authors should define the set of policy subjects to which policy assertions can be attached. Over time, new policy subjects may need to be defined. When this occurs, policy Assertion Authors may update the list of policy @@ -1115,7 +1115,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">Best -Practice 28: Change of the Policy Subject Over Time</span></p><p class="practice">If the policy subjects change over time, +Practice 27: 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><div class="back"><div class="div1"> <h2><a name="security-considerations" id="security-considerations"></a>A. Security Considerations</h2><p> Security considerations are discussed in the <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite> document.</p></div><div class="div1"> @@ -1292,7 +1292,7 @@ (<a href="#best-practices-list"><b>2. List of Best Practice Statements</b></a>). </p></li><li><p>Incorporated the Best Practices from <a href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/att-0069/good-practices-4-assertion-authors-03-05-2007.pdf">IBM/Microsoft Contibution.</a> - </p></li><li><p>Made editorial changes to align with the OASIS WS-SecurityPolicy specification.</p></li><li><p>Made editorial changes to align with the W3C WS-Addressing 1.0 Metadata specification.</p></li><li><p>Updated Section 5.5 for 4661/4662.</p></li></ul></div><div class="div1"> + </p></li><li><p>Made editorial changes to align with the OASIS WS-SecurityPolicy specification.</p></li><li><p>Made editorial changes to align with the W3C WS-Addressing 1.0 Metadata specification.</p></li><li><p>Updated Section 5.5 for 4661/4662.</p></li><li><p>Updated Section 5.3.2, 5.6 for 4661/4662.</p></li></ul></div><div class="div1"> <h2><a name="change-log" id="change-log"></a>F. Web Services Policy 1.5 - Guidelines for Policy Assertion Authors Change Log (Non-Normative)</h2><a name="ws-policy-primer-changelog-table"></a><table border="1"><tbody><tr><th rowspan="1" colspan="1">Date</th><th rowspan="1" colspan="1">Author</th><th rowspan="1" colspan="1">Description</th></tr><tr><td rowspan="1" colspan="1">20060829</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Created first draft based on agreed outline and content</td></tr><tr><td rowspan="1" colspan="1">20061013</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Editorial fixes (suggested by Frederick), fixed references, bibl items, fixed dangling pointers, created eds to do</td></tr><tr><td rowspan="1" colspan="1">20061018</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">Editorial fixes for readability, added example for Encrypted parts</td></tr><tr><td rowspan="1" colspan="1">20061030</td><td rowspan="1" colspan="1">UY</td><td rospan="1" colspan="1">Fixes for Paul Cotton's editorial comments (20061020)</td></tr><tr><td rowspan="1" colspan="1">20061031</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Fixes for Frederick's editorial comments (20061025)</td></tr><tr><td rowspan="1" colspan="1">20061031</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Optionality discussion feedback integration</td></tr><tr><td rowspan="1" colspan="1">20061115</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">First attempt at restructuring to include primer content</td></tr><tr><td rowspan="1" colspan="1">20061120</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">Restructure to address action items 64,77, which refer to bugzilla 3705 and F2F RESOLUTION 3792 </td></tr><tr><td rowspan="1" colspan="1">20061127</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Updated the list of editors. Added <a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0033.html">Frederick</a> and <a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0054.html">Umit</a> to the list of editors. @@ -1443,12 +1443,12 @@ 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 Best Practice <a href="#bp-specify-composition"><b>26. Specify Composition with Related Assertions</b></a> (from + </td></tr><tr><td rowspan="1" colspan="1">20070520</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Added Best Practice <a href="#bp-specify-composition"><b>25. 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 Best Practice <a href="#bp-not-necessary-to-understand-a-message"><b>10. Not Necessary to Understand a Message</b></a> (from + </td></tr><tr><td rowspan="1" colspan="1">20070520</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Added Best Practice <a href="#bp-not-necessary-to-understand-a-message"><b>11. 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>. @@ -1526,4 +1526,7 @@ Editors' action: <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/339">339</a>, drop <a href="http://www.w3.org/TR/2007/WD-ws-policy-guidelines-20070330/#best-practices-attachment">Section - 6 Applying Best Practices for Policy Attachment</a></td></tr></tbody></table><br></div></div></body></html> \ No newline at end of file + 6 Applying Best Practices for Policy Attachment</a></td></tr><tr><td rowspan="1" colspan="1">20070718</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Implemented the resolution + for issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4661">4661</a>, <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4662">4662</a>, <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4861">4861</a>. + Editors' action: + <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/342">342</a>, <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/346">346</a>. </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.100 retrieving revision 1.101 diff -u -d -r1.100 -r1.101 --- ws-policy-guidelines.xml 18 Jul 2007 12:46:19 -0000 1.100 +++ ws-policy-guidelines.xml 18 Jul 2007 15:52:16 -0000 1.101 @@ -724,8 +724,54 @@ the assertion, whether or not the assertion allows for the use of the wsp:Ignorable attribute. </quote> </p> - + <p>To give an example, the WS-ReliableMessaging Policy document specifies attribute extensibility as part of the XML definition, allowing the wsp:Ignorable attribute: + </p> + <example> + <head>WS-ReliableMessaging Policy use of attribute extensibility</head> + <eg>/wsrmp:RMAssertion/@{any} +This is an extensibility mechanism to allow different {extensible} types of information, based on a schema, to be passed. + </eg></example> +<p> The Policy Framework provides two modes of authoring policy expressions: +compact and normal form. One of the mechanisms that the Policy Framework +provides to policy authors for purposes of writing compact policy +expressions is the wsp:Optional attribute. Assertion Authors should allow +for the use of the wsp:Optional attribute in the XML outline and/or schema +definition of an assertion as this will allow policy expression authors to +compose compact policy expressions.</p> + <p role="practice" id="bp-assertion-xml-allow-optional"> + <quote>Assertion Authors should allow use of wsp:Optional +attribute</quote> + <quote>An assertion's XML outline and/or schema definition should allow the use +of the wsp:Optional attribute so as to enable policy authors to compose +compact policy expressions.</quote> + </p> +<p>For example, consider the following two equivalent policy expressions:</p> +<example> <head>Normal form expression:</head> + <eg xml:space="preserve"><wsp:Policy> + <wsp:ExactlyOne> + <wsp:All> + <wsam:Addressing> + <wsp:Policy/> + </wsam:Addressing> + </wsp:All> + <wsp:All> + </wsp:All> + </wsp:ExactlyOne> +</wsp:Policy></eg> +</example> +<example><head>Compact form expression:</head> +<eg xml:space="preserve"><wsp:Policy> + <wsam:Addressing wsp:Optional="true"> + <wsp:Policy/> + </wsam:Addressing> +</wsp:Policy></eg> +</example> +<p> +If the assertion author had not provided for the wsp:Optional attribute to be included on the assertion, then policy expression authors would be forced to express the optionality of a behavior as two explicit policy alternatives, one with and one without that assertion when including assertions of that type in their policies.</p> + </div3> + + <div3 id="self-describing"> <head> Self Describing Messages </head> <p> WS-Policy is intended to communicate the requirements, capabilities and @@ -1058,57 +1104,12 @@ <div2 id="optional-policy-assertion"> <head>Designating Optional Behaviors</head> - <div3> - <head>Optional behavior in Compact authoring</head> - <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, - we just use the phrase “optional assertions” in this section.) - During the process of normalization the runtime - behavior is indicated by two policy alternatives, one with and - one without the assertion. In a consumer/provider - scenario, the choice of engaging the runtime behavior is upon - 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. Assertion Authors 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>Use the wsp:Optional attribute to indicate optional</quote> - <quote>Assertion authors should use the wsp:Optional attribute to indicate that a - behavior indicated by a 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> + <ednote> +<edtext>This section does not have Working Group consensus and there is an outstanding action item to revise it</edtext> +</ednote> <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 @@ -1791,6 +1792,9 @@ <item> <p>Updated Section 5.5 for 4661/4662.</p> </item> + <item> +<p>Updated Section 5.3.2, 5.6 for 4661/4662.</p> +</item> </ulist> </inform-div1> <inform-div1 id="change-log"> @@ -2473,7 +2477,15 @@ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/339">339</loc>, drop <loc href="http://www.w3.org/TR/2007/WD-ws-policy-guidelines-20070330/#best-practices-attachment">Section 6 Applying Best Practices for Policy Attachment</loc></td> - </tr> + </tr> + <tr> +<td>20070718</td> +<td>DBO</td> + <td>Implemented the resolution + for issue <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4661">4661</loc>, <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4662">4662</loc>, <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4861">4861</loc>. + Editors' action: + <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/342">342</loc>, <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/346">346</loc>. </td> +</tr> </tbody> </table> </inform-div1>
Received on Wednesday, 18 July 2007 15:52:50 UTC