- From: Frederick Hirsch via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 24 Oct 2007 14:52:02 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv5724
Modified Files:
ws-policy-guidelines-diff20070928.xml
ws-policy-guidelines-diff20070928.html
ws-policy-guidelines.html ws-policy-guidelines.xml
Log Message:
Implemented the resolution for issue 5184. Editors' action 372. Implemented as originally proposed b,c,e,f,h,j. Implemented as amended a, k,l. Did not implement g which was not processed by WG.
Index: ws-policy-guidelines-diff20070928.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines-diff20070928.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- ws-policy-guidelines-diff20070928.html 22 Oct 2007 04:24:33 -0000 1.1
+++ ws-policy-guidelines-diff20070928.html 24 Oct 2007 14:51:59 -0000 1.2
@@ -145,10 +145,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="#d4e817">Ignorable behavior in authoring</a><br>
- 5.5.2 <a href="#d4e830">Ignorable behavior at runtime</a><br>
+ 5.5.1 <a href="#d4e879">Ignorable behavior in authoring</a><br>
+ 5.5.2 <a href="#d4e892">Ignorable behavior at runtime</a><br>
5.6 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br>
- 5.6.1 <a href="#d4e845">Optional behavior at runtime</a><br>
+ 5.6.1 <a href="#d4e907">Optional behavior at runtime</a><br>
5.7 <a href="#levels-of-abstraction">Considerations for Policy Attachment</a><br>
5.7.1 <a href="#general-attachment-guidelines">General Guidelines</a><br>
5.7.2 <a href="#wsdl-attachment-guidelines">Considerations for Policy Attachment in WSDL</a><br>
@@ -157,7 +157,8 @@
6. <a href="#versioning-policy-assertions">Versioning Policy Assertions</a><br>
6.1 <a href="#Referencing_Policy_Expressions">Referencing Policy Expressions</a><br>
6.2 <a href="#extending-assertions"> Evolution of Assertions (Versioning and Compatibility)</a><br>
- 6.3 <a href="#supporting-new-policy-subjects">Supporting New Policy Subjects</a><br>
+ 6.3 <a href="#supporting-new-policy-subjects">Supporting New Policy Subjects (see Section
+ 6.3 Supporting New Policy Subjects)</a><br>
</p>
<h3><a name="appendices" id="appendices"></a>Appendices</h3><p class="toc">A. <a href="#security-considerations">Security Considerations</a><br>
B. <a href="#xml-namespaces">XML Namespaces</a><br>
@@ -213,14 +214,16 @@
the question.
</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-compatibility-tests"><b>1. Define assertions relevant to compatibility tests</b></a></p></li><li><p><a href="#bp-ignorable-for-not-related-to-compatibility-tests"><b>2. Mark Ignorable Assertions not related to compatibility</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 definition</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. Document Ignorable Behavior</b></a></p></li><li><p><a hrf="#ignorableAssertions"><b>9. Document Use of the Ignorable
-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</b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>11. Define message format only</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
+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</b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>11. Assertions should not describe message
+ semanticsonly</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-assertion-semantics"><b>20. Semantics IndependentAssertions
Assertion of Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-semantics-multiple-same-type"><b>21. Describe Semantics of Multiple Assertions of Same Type</b></a></p></li><li><p><a href="#bp-leverage-defined-attachment-mechanisms"><b>22. Leverage Defined Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-use-defined-policy-subjects"><b>23. Use Defined Policy Subjects</b></a></p></li><li><p><a href="#bp-identify-policy-subjects"><b>24. Identify Policy Subjects</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>25. Specify WSDL Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-consider-scope"><b>26. Consider Scope of Attachment Points</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>27. Choose the Most Granular WSDL Policy Subject</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>28. Define Rules for Attachment of an Assertion
type to Multiple WSDL policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>29. Specify Preferred WSDL Attachment Point</b></a></p></li><li><p><a href="#bp-UDDI-tmodels"><b>30. Use defined tModels when appropriate</b></a></p></li><li><p><a href="#bp-specify-composition"><b>31. Specify Composition with Related Assertions</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>32. Independent Assertions for Different Versions of a
Behavior</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>33. Document changes to policy
subject</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
+<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 <span class="diff-add"><span>domain that
+ has chosen to express their capabilities
+ via the </span></span>WS-Policy <span class="diff-chg"><span>expressions. </span></span>Sets of domain-specific assertions
are typically defined in a dedicated specification that describes
their semantics, applicability and scoping requirements as well
as their data type definition using XML Schema [<cite><a href="#XMLSchemaPart1">XML Schema Structures</a></cite>].
@@ -304,11 +307,15 @@
this document to help communities utilize the framework in such
a way that multiple WS-Policy domains can co-exist and
consumers and providers can utilize the framework consistently across domains.
- </p><p>When using the WS-Policy Framework, any
- Assertion Authors defining new WS-Policy assertions
- must adhere to the MUST's and SHOULD's in the specification
- and should review the conformance section of the specification.
- </p><p>Assertion Authors should also specify a policy subject. For
+ </p><p><span class="diff-add"><span>Assertion</span></span><span class="diff-del"><span>When using </span></span><span class="diff-chg"><span>authors should review </span></span><span class="diff-add"><span>the</span></span><span class="diff-del"><span>any
+ Assertion </span></span><span class="diff-chg"><span>conformance sections of </span></span><span class="diff-add"><span>the
+ </span></span>WS-Policy <span class="diff-add"><span>Framework</span></span><span class="diff-del"><span>assertions
+ must adhere </span></span><span class="diff-chg"><span>and Attachment specifications </span></span>and an<span class="diff-del"><span>SHOULD's in </span></span><span class="diff-chg"><span>assertion </span></span><span class="diff-add"><span>must</span></span><span class="diff-del"><span>specification
+ and </span></span><span class="diff-add"><span>adhere
+ to</span></span><span class="diff-del"><span>should </span></span><span class="diff-chg"><span>all </span></span>the <span class="diff-chg"><span>constraints contained in </span></span>the <span class="diff-add"><span>Framework and Attachment
+ specifications.
+ </span></span><span class="diff-del"><span>specification.
+ </span></span></p><p>Assertion Authors should also specify a policy subject. For
instance, if a policy assertion were to be used with WSDL, an assertion
description should specify a WSDL policy subject.
</p><p>An example of a domain specification that follows these practices is the WS-SecurityPolicy
@@ -533,7 +540,8 @@
<h3><a name="new-guidelines-domains" id="new-guidelines-domains"></a>5.3 Considerations when Modeling New Assertions</h3><p>When creating a new policy domain, it is important to
understand how policy expressions are used by a
framework implementation that has followed the specifications.
- </p><p>The examples given in this document reference WS-Policy like WS-SecurityPolicy and WS-RM Policy.
+ </p><p>The examples given in this document <span class="diff-add"><span>are
+ based</span></span><span class="diff-del"><span>reference </span></span><span class="diff-chg"><span>on </span></span><span class="diff-add"><span>existing assertions such as</span></span><span class="diff-del"><span>like </span></span>WS-SecurityPolicy and WS-RM Policy.
These policy expressions represent web services message exchange requirements, but policy authoring can
be done by individual groups that wish to represent web services application requirements and
deployments that wish to reuse the WS-Policy framework in
@@ -621,11 +629,12 @@
Practice 9: 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><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:
+ </p></div><div class="diff-del"><p class="diff-del">To give an example, the WS-ReliableMessaging Policy document specifies attribute extensibility as part of the XML definition, allowing the wsp:Ignorable attribute:
+
+
+ WS-ReliableMessaging Policy use of attribute extensibility
+
+</p></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 <code>wsp:Optional</code> attribute. Assertion Authors should allow
@@ -635,7 +644,7 @@
Practice 10: Assertion Authors should allow use of wsp:Optional</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>
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-5. </span>Normal form expression:</i></p><div class="exampleInner"><pre><wsp:Policy>
<wsp:ExactlyOne>
<wsp:All>
<wsam:Addressing>
@@ -646,7 +655,7 @@
</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>
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-6. </span>Compact form expression:</i></p><div class="exampleInner"><pre><wsp:Policy>
<wsam:Addressing wsp:Optional="true">
<wsp:Policy/>
</wsam:Addressing>
@@ -686,7 +695,8 @@
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 11: Define message format only</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: Assertions should not describe message
+ semanticsonly</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
@@ -745,7 +755,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-8. </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-7. </span>Policy Assertion with Assertion Parameters</i></p><div class="exampleInner"><pre><wsp:Policy>
<sp:SignedParts>
<sp:Body/>
<sp:Header/>
@@ -819,7 +829,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-9. </span>Transport Security Policy Assertion</i></p><div class="exampleInner"><pre><sp:TransportBinding>
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-8. </span>Transport Security Policy Assertion</i></p><div class="exampleInner"><pre><sp:TransportBinding>
<Policy>
<sp:TransportToken>
<Policy>
@@ -865,7 +875,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-10. </span>Empty Nested Policy Expression</i></p><div class="exampleInner"><pre><sp:TransportToken>
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-9. </span>Empty Nested Policy Expression</i></p><div class="exampleInner"><pre><sp:TransportToken>
<wsp:Policy>
<sp:HttpsToken>
<wsp:Policy/>
@@ -875,16 +885,16 @@
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="d4e817" id="d4e817"></a>5.5.1 Ignorable behavior in authoring</h4><p>
+<h4><a name="d4e879" id="d4e879"></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 compatibility 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. Document Ignorable Behavior</b></a> and <a href="#ignorableAssertions"><b>9. 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="d4e830" id="d4e830"></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="d4e892" id="d4e892"></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="d4e845" id="d4e845"></a>5.6.1 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
+<h4><a name="d4e907" id="d4e907"></a>5.6.1 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
@@ -966,7 +976,7 @@
</p></div></div><div class="div2">
<h3><a name="levels-of-abstraction" id="levels-of-abstraction"></a>5.7 Considerations for Policy Attachment</h3><div class="div3">
<h4><a name="general-attachment-guidelines" id="general-attachment-guidelines"></a>5.7.1 General Guidelines</h4><p><span class="diff-add"><span>Although
- </span></span><span class="diff-del"><span>The </span></span><span class="diff-chg"><span>a policy assertion may </span></span><span class="diff-add"><span>be constrained </span></span>to
+ </span></span><span class="diff-del"><span>The </span></span><span class="diff-chg"><span>a policy assertion </span></span><span class="diff-add"><span>may be constrained</span></span><span class="diff-del"><span>used </span></span>to
<span class="diff-del"><span>communicate </span></span><span class="diff-chg"><span>a specific set of policy subjects by Assertion </span></span><span class="diff-add"><span>Authors,
its </span></span><span class="diff-del"><span>additional
</span></span>semantics <span class="diff-chg"><span>should not be dependent upon the mechanism by which the </span></span>policy <span class="diff-chg"><span>expression is attached </span></span>to <span class="diff-chg"><span>a
@@ -981,7 +991,7 @@
assertions </span></span><span class="diff-chg"><span>analyze </span></span><span class="diff-add"><span>the contents of the policy.</span></span><span class="diff-del"><span>present.
</span></span></p><div class="diff-chg"><div class="boxedtext"><p><a name="bp-assertion-semantics" id="bp-assertion-semantics"></a><span class="practicelab">Best
Practice 20: Semantics IndependentAssertions
- Assertion of Attachment Mechanisms</span></p><p class="practice">Theencouraged semantics of acreate policy assertion shouldthat
+ Assertion of Attachment Mechanisms</span></p><p class="practice">Theencouraged semantics of a policy assertion shouldthat
can not depend on the attachment mechanismmechanism. used.</p></div></div><p>For example, a security policy expression can be assigned a key reference and
be attached to a UDDI binding or can be embedded in a WSDL document. </p><div class="diff-add"><p class="diff-add"><span class="diff-add"><span>Since multiple attachment mechanisms may be used, a policy alternative created during the process of calculating
an effective policy can contain multiple instances of the same policy assertion type
@@ -1020,9 +1030,10 @@
the policy subject level that might impact interoperability.</p></div><p>
Assertion Authors should review the policy subjects defined in WS-PolicyAttachments
and identify which of the existing policy subjects can be used with the assertions
- they define. That identification will facilitate the deployment of their policy
- assertions and include such information in the assertion definition.
- </p><p> An example of this practice is
+ they define. That
+ identification will facilitate the deployment of their policy
+ <span class="diff-del"><span>assertions and include such information in the assertion </span></span><span class="diff-chg"><span>assertions.
+ </span></span></p><p> An example of this practice is
the Reliable Messaging Policy Assertion document [<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy Assertion</a></cite>]. In the Sequence STR Assertion (section
2.5.1) the Reliable Messaging Policy Assertion authors state that "The
STR assertion defines the requirement that an RM Sequence MUST be bound
@@ -1048,8 +1059,8 @@
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 WSDL 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 25: Specify WSDL Policy Subject(s)</span></p><p class="practice">Assertion Authors should specify the set of relevant WSDL policy subjects with which
- the assertion may be associated. For instance, if a policy assertion is to be used with
+Practice 25: Specify WSDL Policy Subject(s)</span></p><p class="practice">Assertion Authors should specify the set of
+ relevant WSDL policy subjects with which the assertion may be associated. For instance, if a policy assertion is to be used with
a WSDL policy subject - such as service, endpoint, operation and message it should be stated.
</p></div><p>Assertion Authors that utilize WSDL policy subjects need to
understand how the assertions will be
@@ -1078,10 +1089,12 @@
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. However such
- policy attachments to WSDL 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
+ policy subject instead of a message policy subject. <span class="diff-chg"><span>The </span></span><span class="diff-add"><span>best</span></span><span class="diff-del"><span>such
+ policy </span></span><span class="diff-add"><span>practice
+ is</span></span><span class="diff-del"><span>attachments </span></span>to <span class="diff-chg"><span>choose the most granular WSDL policy subject </span></span><span class="diff-add"><span>to</span></span><span class="diff-del"><span>granularity
+ should </span></span><span class="diff-chg"><span>which the </span></span><span class="diff-add"><span>behavior
+ represented</span></span><span class="diff-del"><span>only </span></span><span class="diff-add"><span>by a</span></span><span class="diff-del"><span>after </span></span><span class="diff-add"><span>policy assertion</span></span><span class="diff-del"><span>careful </span></span><span class="diff-chg"><span>applies.
+ </span></span></p><div class="boxedtext"><p><a name="bp-WSDL-policy-subject-Granularity" id="bp-WSDL-policy-subject-Granularity"></a><span class="practicelab">Best
Practice 27: Choose the Most Granular WSDL Policy Subject</span></p><p class="practice">Assertion Authors should choose the most granular WSDL policy subject
to which the behavior represented by a policy assertion applies.
</p></div><p>
@@ -1103,9 +1116,9 @@
Web Services Reliable Messaging Policy Assertion specification
[<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy Assertion</a></cite>] gives rules on which WSDL policy subjects may be associated with the RM
Policy assertion, and which WSDL 1.1 elements may have RM Policy assertions attached.
- </p><p>If the capability 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>Since many attachment points are available in WSDL, it would be
+ </p><p>If the <span class="diff-chg"><span>behavior indicated </span></span><span class="diff-add"><span>by</span></span><span class="diff-del"><span>imply
+ different </span></span><span class="diff-chg"><span>an assertion </span></span><span class="diff-add"><span>varies when</span></span><span class="diff-del"><span>respect </span></span><span class="diff-add"><span>attached </span></span>to <span class="diff-chg"><span>different </span></span><span class="diff-add"><span>policy subjects</span></span><span class="diff-del"><span>points, </span></span>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 <span class="diff-add"><span>policy </span></span>subject. </p></li></ul><p>Since many attachment points are available in WSDL, it would be
necessary for Assertion Authors to recommend a preferred attachment
point. One approach would be to identify different attachment points in
a policy subject, choose the most granular policy subject that the
@@ -1173,13 +1186,15 @@
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-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
+<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
"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>)".
</p></div></div><div class="div1">
<h2><a name="versioning-policy-assertions" id="versioning-policy-assertions"></a>6. Versioning Policy Assertions</h2><p>Assertion Authors need to consider not just the expression of the current set of requirements but
- how they anticipate new assertions being added to the set. There are three aspects to versioning policy assertions:</p><ul><li><p> Assertion Extensibility </p></li><li><p> Policy Language Extensibility </p><p>Over time, the Policy WG or third parties can version or extend the Policy Language with new
+ how they anticipate new assertions being added to the set. There are three aspects to versioning policy assertions:</p><ul><li><p> Assertion <span class="diff-add"><span>Extensibility. Assertion authors should allow for extensibility
+ (see best practice 5. Start with a Simple</span></span><span class="diff-del"><span>Extensibility </span></span><span class="diff-add"><span>Assertion)
+ </span></span></p></li><li><p> Policy Language Extensibility </p><p>Over time, the Policy WG or third parties can version or extend the Policy Language with new
or modified constructs. These constructs may be compatible or incompatible with previous versions.
</p><p> Assertion Authors should review the WS-Policy Primer <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>
and the specifications <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite> <cite><a href="#WS-PolicyAttachment">Web Services Policy Attachment</a></cite>
@@ -1198,8 +1213,9 @@
As an example, in <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>
Section 4.2, the <code>sp:issuedToken</code> assertion utilizes the
<code>sp:RequestSecurityTokenTemplate</code> parameter that contains necessary
- information to request a security token. The contents of the parameter
- are static and allow reuse in different security scenarios.</p></div><div class="div2">
+ information to request a security token. The contents of the parameter are static and <span class="diff-chg"><span>may be </span></span><span class="diff-add"><span>reused
+ </span></span>in different security <span class="diff-add"><span>scenarios using other referencing mechanisms (these are
+ outside the scope of the WS-Policy Framework).</span></span><span class="diff-del"><span>scenarios.</span></span></p></div><div class="div2">
<h3><a name="extending-assertions" id="extending-assertions"></a>6.2 Evolution of Assertions (Versioning and Compatibility)</h3><p>Over time, there may be multiple equivalent behaviors emerging in the Web
Service interaction space. Examples of such multiple equivalent behaviors are WSS: SOAP Message Security 1.0
vs. 1.1 and WS-Addressing August 2004 version vs. WS-Addressing W3C Recommendation
@@ -1219,7 +1235,8 @@
<p style="text-align: left" class="exampleHead"><i><span>Example 6-2. </span>Message-level Security and WSS: SOAP Message Security 1.1</i></p><div class="exampleInner"><pre><Policy>
<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>
+<h3><a name="supporting-new-policy-subjects" id="supporting-new-policy-subjects"></a>6.3 Supporting New Policy Subjects <span class="diff-add"><span>(see Section
+ 6.3 Supporting New Policy Subjects)</span></span></h3><p>
The best practice <a href="#bp-WSDL-policy-subject"><b>25. Specify WSDL 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
@@ -1579,7 +1596,8 @@
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 colspan="1" rowspan="1">20070520</td><td colspan="1" rowspan="1">ASV</td><td colspan="1" rowspan="1">Added Best Practice <a href="#bp-not-necessary-to-understand-a-message"><b>11. Define message format only</b></a> (from
+ </td></tr><tr><td colspan="1" rowspan="1">20070520</td><td colspan="1" rowspan="1">ASV</td><td colspan="1" rowspan="1">Added Best Practice <a href="#bp-not-necessary-to-understand-a-message"><b>11. Assertions should not describe message
+ semanticsonly</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>.
@@ -1713,4 +1731,9 @@
</td></div></tr></div><div class="diff-add"><tr class="diff-add"><div class="diff-add"><td colspan="1" class="diff-add" rowspan="1">20071017</td></div><div class="diff-add"><td colspan="1" class="diff-add" rowspan="1">FJH</td></div><div class="diff-add"><td colspan="1" class="diff-add" rowspan="1">Implemented the resolution for issue
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5185"><span class="diff-add"><span>5185</span></span></a>. Editors' action
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/373"><span class="diff-add"><span>373</span></span></a>.
+ </td></div></tr></div><div class="diff-add"><tr class="diff-add"><div class="diff-add"><td colspan="1" class="diff-add" rowspan="1">20071024</td></div><div class="diff-add"><td colspan="1" class="diff-add" rowspan="1">FJH</td></div><div class="diff-add"><td colspan="1" class="diff-add" rowspan="1">Implemented the resolution for issue
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5185"><span class="diff-add"><span>5184</span></span></a>. Editors' action
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/372"><span class="diff-add"><span>372</span></span></a>.
+ Implemented as originally proposed b,c,e,f,h,j. Implemented as amended a, k,l. Did not implement g which was not processed by WG.
+
</td></div></tr></div></tbody></table><br></div></div></body></html>
\ No newline at end of file
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.110
retrieving revision 1.111
diff -u -d -r1.110 -r1.111
--- ws-policy-guidelines.html 17 Oct 2007 20:16:09 -0000 1.110
+++ ws-policy-guidelines.html 24 Oct 2007 14:51:59 -0000 1.111
@@ -125,10 +125,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="#d3e809">Ignorable behavior in authoring</a><br>
- 5.5.2 <a href="#d3e822">Ignorable behavior at runtime</a><br>
+ 5.5.1 <a href="#d3e802">Ignorable behavior in authoring</a><br>
+ 5.5.2 <a href="#d3e815">Ignorable behavior at runtime</a><br>
5.6 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br>
- 5.6.1 <a href="#d3e837">Optional behavior at runtime</a><br>
+ 5.6.1 <a href="#d3e830">Optional behavior at runtime</a><br>
5.7 <a href="#levels-of-abstraction">Considerations for Policy Attachment</a><br>
5.7.1 <a href="#general-attachment-guidelines">General Guidelines</a><br>
5.7.2 <a href="#wsdl-attachment-guidelines">Considerations for Policy Attachment in WSDL</a><br>
@@ -137,7 +137,8 @@
6. <a href="#versioning-policy-assertions">Versioning Policy Assertions</a><br>
6.1 <a href="#Referencing_Policy_Expressions">Referencing Policy Expressions</a><br>
6.2 <a href="#extending-assertions"> Evolution of Assertions (Versioning and Compatibility)</a><br>
- 6.3 <a href="#supporting-new-policy-subjects">Supporting New Policy Subjects</a><br>
+ 6.3 <a href="#supporting-new-policy-subjects">Supporting New Policy Subjects (see Section
+ 6.3 Supporting New Policy Subjects)</a><br>
</p>
<h3><a name="appendices" id="appendices"></a>Appendices</h3><p class="toc">A. <a href="#security-considerations">Security Considerations</a><br>
B. <a href="#xml-namespaces">XML Namespaces</a><br>
@@ -193,13 +194,15 @@
the question.
</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-compatibility-tests"><b>1. Define assertions relevant to compatibility tests</b></a></p></li><li><p><a href="#bp-ignorable-for-not-related-to-compatibility-tests"><b>2. Mark Ignorable Assertions not related to compatibility</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 definition</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. Document Ignorable Behavior</b></a></p></li><li><p><a hrf="#ignorableAssertions"><b>9. Document Use of the Ignorable
-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</b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>11. Define message format only</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
+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</b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>11. Assertions should not describe message
+ semantics</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-assertion-semantics"><b>20. Semantics Independent of Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-semantics-multiple-same-type"><b>21. Describe Semantics of Multiple Assertions of Same Type</b></a></p></li><li><p><a href="#bp-leverage-defined-attacment-mechanisms"><b>22. Leverage Defined Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-use-defined-policy-subjects"><b>23. Use Defined Policy Subjects</b></a></p></li><li><p><a href="#bp-identify-policy-subjects"><b>24. Identify Policy Subjects</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>25. Specify WSDL Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-consider-scope"><b>26. Consider Scope of Attachment Points</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>27. Choose the Most Granular WSDL Policy Subject</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>28. Define Rules for Attachment of an Assertion
type to Multiple WSDL policy subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>29. Specify Preferred WSDL Attachment Point</b></a></p></li><li><p><a href="#bp-UDDI-tmodels"><b>30. Use defined tModels when appropriate</b></a></p></li><li><p><a href="#bp-specify-composition"><b>31. Specify Composition with Related Assertions</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>32. Independent Assertions for Different Versions of a
Behavior</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>33. Document changes to policy
subject</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
+<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 domain that
+ has chosen to express their capabilities
+ via the WS-Policy expressions. Sets of domain-specific assertions
are typically defined in a dedicated specification that describes
their semantics, applicability and scoping requirements as well
as their data type definition using XML Schema [<cite><a href="#XMLSchemaPart1">XML Schema Structures</a></cite>].
@@ -283,10 +286,10 @@
this document to help communities utilize the framework in such
a way that multiple WS-Policy domains can co-exist and
consumers and providers can utilize the framework consistently across domains.
- </p><p>When using the WS-Policy Framework, any
- Assertion Authors defining new WS-Policy assertions
- must adhere to the MUST's and SHOULD's in the specification
- and should review the conformance section of the specification.
+ </p><p>Assertion authors should review the conformance sections of the
+ WS-Policy Framework and Attachment specifications and an assertion must adhere
+ to all the constraints contained in the Framework and Attachment
+ specifications.
</p><p>Assertion Authors should also specify a policy subject. For
instance, if a policy assertion were to be used with WSDL, an assertion
description should specify a WSDL policy subject.
@@ -495,7 +498,8 @@
<h3><a name="new-guidelines-domains" id="new-guidelines-domains"></a>5.3 Considerations when Modeling New Assertions</h3><p>When creating a new policy domain, it is important to
understand how policy expressions are used by a
framework implementation that has followed the specifications.
- </p><p>The examples given in this document reference WS-Policy like WS-SecurityPolicy and WS-RM Policy.
+ </p><p>The examples given in this document are
+ based on existing assertions such as WS-SecurityPolicy and WS-RM Policy.
These policy expressions represent web services message exchange requirements, but policy authoring can
be done by individual groups that wish to represent web services application requirements and
deployments that wish to reuse the WS-Policy framework in
@@ -583,11 +587,7 @@
Practice 9: 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><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:
+ </p></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 <code>wsp:Optional</code> attribute. Assertion Authors should allow
@@ -597,7 +597,7 @@
Practice 10: Assertion Authors should allow use of wsp:Optional</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>
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-5. </span>Normal form expression:</i></p><div class="exampleInner"><pre><wsp:Policy>
<wsp:ExactlyOne>
<wsp:All>
<wsam:Addressing>
@@ -608,7 +608,7 @@
</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>
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-6. </span>Compact form expression:</i></p><div class="exampleInner"><pre><wsp:Policy>
<wsam:Addressing wsp:Optional="true">
<wsp:Policy/>
</wsam:Addressing>
@@ -648,7 +648,8 @@
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 11: Define message format only</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: Assertions should not describe message
+ semantics</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
@@ -707,7 +708,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-8. </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-7. </span>Policy Assertion with Assertion Parameters</i></p><div class="exampleInner"><pre><wsp:Policy>
<sp:SignedParts>
<sp:Body/>
<sp:Header/>
@@ -781,7 +782,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-9. </span>Transport Security Policy Assertion</i></p><div class="exampleInner"><pre><sp:TransportBinding>
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-8. </span>Transport Security Policy Assertion</i></p><div class="exampleInner"><pre><sp:TransportBinding>
<Policy>
<sp:TransportToken>
<Policy>
@@ -827,7 +828,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-10. </span>Empty Nested Policy Expression</i></p><div class="exampleInner"><pre><sp:TransportToken>
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-9. </span>Empty Nested Policy Expression</i></p><div class="exampleInner"><pre><sp:TransportToken>
<wsp:Policy>
<sp:HttpsToken>
<wsp:Policy/>
@@ -837,16 +838,16 @@
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="d3e809" id="d3e809"></a>5.5.1 Ignorable behavior in authoring</h4><p>
+<h4><a name="d3e802" id="d3e802"></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 compatibility 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. Document Ignorable Behavior</b></a> and <a href="#ignorableAssertions"><b>9. 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="d3e822" id="d3e822"></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="d3e815" id="d3e815"></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="d3e837" id="d3e837"></a>5.6.1 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
+<h4><a name="d3e830" id="d3e830"></a>5.6.1 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
@@ -971,8 +972,8 @@
the policy subject level that might impact interoperability.</p></div><p>
Assertion Authors should review the policy subjects defined in WS-PolicyAttachments
and identify which of the existing policy subjects can be used with the assertions
- they define. That identification will facilitate the deployment of their policy
- assertions and include such information in the assertion definition.
+ they define. That
+ identification will facilitate the deployment of their policy assertions.
</p><p> An example of this practice is
the Reliable Messaging Policy Assertion document [<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy Assertion</a></cite>]. In the Sequence STR Assertion (section
2.5.1) the Reliable Messaging Policy Assertion authors state that "The
@@ -999,9 +1000,8 @@
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 WSDL 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 25: Specify WSDL Policy Subject(s)</span></p><p class="practice">Assertion Authors should specify the set of relevant WSDL policy subjects with which
- the assertion may be associated. For instance, if a policy assertion is to be used with
- a WSDL policy subject - such as service, endpoint, operation and message it should be stated.
+Practice 25: Specify WSDL Policy Subject(s)</span></p><p class="practice">Assertion Authors should specify the set of
+ relevant WSDL policy subjects with which the assertion may be associated.
</p></div><p>Assertion Authors that utilize WSDL policy subjects need to
understand how the assertions will be
processed in intersection and merging, and the specific implications of
@@ -1029,9 +1029,9 @@
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. However such
- policy attachments to WSDL policy subjects of broader scope and granularity
- should be done only after careful evaluation.
+ policy subject instead of a message policy subject. The best practice
+ is to choose the most granular WSDL policy subject to which the behavior
+ represented by a policy assertion applies.
</p><div class="boxedtext"><p><a name="bp-WSDL-policy-subject-Granularity" id="bp-WSDL-policy-subject-Granularity"></a><span class="practicelab">Best
Practice 27: Choose the Most Granular WSDL Policy Subject</span></p><p class="practice">Assertion Authors should choose the most granular WSDL policy subject
to which the behavior represented by a policy assertion applies.
@@ -1054,9 +1054,8 @@
Web Services Reliable Messaging Policy Assertion specification
[<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy Assertion</a></cite>] gives rules on which WSDL policy subjects may be associated with the RM
Policy assertion, and which WSDL 1.1 elements may have RM Policy assertions attached.
- </p><p>If the capability 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>Since many attachment points are available in WSDL, it would be
+ </p><p>If the behavior indicated by an assertion varies when attached to different policy subjects 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 policy subject. </p></li></ul><p>Since many attachment points are available in WSDL, it would be
necessary for Assertion Authors to recommend a preferred attachment
point. One approach would be to identify different attachment points in
a policy subject, choose the most granular policy subject that the
@@ -1124,13 +1123,15 @@
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-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
+<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
"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>)".
</p></div></div><div class="div1">
<h2><a name="versioning-policy-assertions" id="versioning-policy-assertions"></a>6. Versioning Policy Assertions</h2><p>Assertion Authors need to consider not just the expression of the current set of requirements but
- how they anticipate new assertions being added to the set. There are three aspects to versioning policy assertions:</p><ul><li><p> Assertion Extensibility </p></li><li><p> Policy Language Extensibility </p><p>Over time, the Policy WG or third parties can version or extend the Policy Language with new
+ how they anticipate new assertions being added to the set. There are three aspects to versioning policy assertions:</p><ul><li><p> Assertion Extensibility. Assertion authors should allow for extensibility
+ (see best practice 5. Start with a Simple Assertion)
+ </p></li><li><p> Policy Language Extensibility </p><p>Over time, the Policy WG or third parties can version or extend the Policy Language with new
or modified constructs. These constructs may be compatible or incompatible with previous versions.
</p><p> Assertion Authors should review the WS-Policy Primer <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>
and the specifications <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite> <cite><a href="#WS-PolicyAttachment">Web Services Policy Attachment</a></cite>
@@ -1149,8 +1150,9 @@
As an example, in <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>
Section 4.2, the <code>sp:issuedToken</code> assertion utilizes the
<code>sp:RequestSecurityTokenTemplate</code> parameter that contains necessary
- information to request a security token. The contents of the parameter
- are static and allow reuse in different security scenarios.</p></div><div class="div2">
+ information to request a security token. The contents of the parameter are static and may be reused
+ in different security scenarios using other referencing mechanisms (these are
+ outside the scope of the WS-Policy Framework).</p></div><div class="div2">
<h3><a name="extending-assertions" id="extending-assertions"></a>6.2 Evolution of Assertions (Versioning and Compatibility)</h3><p>Over time, there may be multiple equivalent behaviors emerging in the Web
Service interaction space. Examples of such multiple equivalent behaviors are WSS: SOAP Message Security 1.0
vs. 1.1 and WS-Addressing August 2004 version vs. WS-Addressing W3C Recommendation
@@ -1170,7 +1172,8 @@
<p style="text-align: left" class="exampleHead"><i><span>Example 6-2. </span>Message-level Security and WSS: SOAP Message Security 1.1</i></p><div class="exampleInner"><pre><Policy>
<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>
+<h3><a name="supporting-new-policy-subjects" id="supporting-new-policy-subjects"></a>6.3 Supporting New Policy Subjects (see Section
+ 6.3 Supporting New Policy Subjects)</h3><p>
The best practice <a href="#bp-WSDL-policy-subject"><b>25. Specify WSDL 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
@@ -1530,7 +1533,8 @@
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>11. Define message format only</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. Assertions should not describe message
+ semantics</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>.
@@ -1664,4 +1668,9 @@
</td></tr><tr><td rowspan="1" colspan="1">20071017</td><td rowspan="1" colspan="1">FJH</td><td rowspan="1" colspan="1">Implemented the resolution for issue
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5185">5185</a>. Editors' action
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/373">373</a>.
+ </td></tr><tr><td rowspan="1" colspan="1">20071024</td><td rowspan="1" colspan="1">FJH</td><td rowspan="1" colspan="1">Implemented the resolution for issue
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5185">5184</a>. Editors' action
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/372">372</a>.
+ Implemented as originally proposed b,c,e,f,h,j. Implemented as amended a, k,l. Did not implement g which was not processed by WG.
+
</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.126
retrieving revision 1.127
diff -u -d -r1.126 -r1.127
--- ws-policy-guidelines.xml 17 Oct 2007 20:16:09 -0000 1.126
+++ ws-policy-guidelines.xml 24 Oct 2007 14:51:59 -0000 1.127
@@ -157,8 +157,9 @@
<div1 id="Assertions">
<head>What is an Assertion? </head>
- <p>An assertion is a piece of metadata that describes a
- capability related to a specific WS-Policy domain. Sets of domain-specific assertions
+ <p>An assertion is a piece of metadata that describes a capability related to a specific domain that
+ has chosen to express their capabilities
+ via the WS-Policy expressions. Sets of domain-specific assertions
are typically defined in a dedicated specification that describes
their semantics, applicability and scoping requirements as well
as their data type definition using XML Schema [<bibref ref="XMLSchemaPart1" />].
@@ -296,10 +297,10 @@
a way that multiple WS-Policy domains can co-exist and
consumers and providers can utilize the framework consistently across domains.
</p>
- <p>When using the WS-Policy Framework, any
- Assertion Authors defining new WS-Policy assertions
- must adhere to the MUST's and SHOULD's in the specification
- and should review the conformance section of the specification.
+ <p>Assertion authors should review the conformance sections of the
+ WS-Policy Framework and Attachment specifications and an assertion must adhere
+ to all the constraints contained in the Framework and Attachment
+ specifications.
</p>
<p>Assertion Authors should also specify a policy subject. For
instance, if a policy assertion were to be used with WSDL, an assertion
@@ -596,7 +597,8 @@
understand how policy expressions are used by a
framework implementation that has followed the specifications.
</p>
- <p>The examples given in this document reference WS-Policy like WS-SecurityPolicy and WS-RM Policy.
+ <p>The examples given in this document are
+ based on existing assertions such as WS-SecurityPolicy and WS-RM Policy.
These policy expressions represent web services message exchange requirements, but policy authoring can
be done by individual groups that wish to represent web services application requirements and
deployments that wish to reuse the WS-Policy framework in
@@ -722,13 +724,6 @@
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
@@ -810,7 +805,8 @@
etc. that must be present in a message as part of their assertion design.
</p>
<p role="practice" id="bp-not-necessary-to-understand-a-message">
- <quote>Define message format only</quote>
+ <quote>Assertions should not describe message
+ semantics</quote>
<quote>Assertion Authors should not define policy assertions to represent information that is necessary to understand a message.</quote>
</p>
<p>For example, if the details of a message's encryption ( e.g., the cipher used, etc) are expressed
@@ -1274,8 +1270,8 @@
<p>
Assertion Authors should review the policy subjects defined in WS-PolicyAttachments
and identify which of the existing policy subjects can be used with the assertions
- they define. That identification will facilitate the deployment of their policy
- assertions and include such information in the assertion definition.
+ they define. That
+ identification will facilitate the deployment of their policy assertions.
</p>
<p> An example of this practice is
@@ -1328,9 +1324,8 @@
<p role="practice" id="bp-WSDL-policy-subject">
<quote>Specify WSDL Policy Subject(s)</quote>
- <quote>Assertion Authors should specify the set of relevant WSDL policy subjects with which
- the assertion may be associated. For instance, if a policy assertion is to be used with
- a WSDL policy subject - such as service, endpoint, operation and message it should be stated.
+ <quote>Assertion Authors should specify the set of
+ relevant WSDL policy subjects with which the assertion may be associated.
</quote>
</p>
@@ -1369,9 +1364,9 @@
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. However such
- policy attachments to WSDL policy subjects of broader scope and granularity
- should be done only after careful evaluation.
+ policy subject instead of a message policy subject. The best practice
+ is to choose the most granular WSDL policy subject to which the behavior
+ represented by a policy assertion applies.
</p>
<p role="practice" id="bp-WSDL-policy-subject-Granularity">
@@ -1406,18 +1401,18 @@
</p>
- <p>If the capability may imply
- different semantics with respect to attachment points, the
- Assertion Authors should consider the following:</p>
+ <p>If the behavior indicated by an assertion varies when attached to different policy subjects the Assertion Authors
+ should consider the following:</p>
<ulist>
<item>
<p> Decompose the semantics with several assertions.</p>
</item>
<item>
- <p> Rewrite a single assertion targeting a specific subject. </p>
+ <p> Rewrite a single assertion targeting a specific policy subject. </p>
</item>
</ulist>
-
+
+
<p>Since many attachment points are available in WSDL, it would be
necessary for Assertion Authors to recommend a preferred attachment
point. One approach would be to identify different attachment points in
@@ -1526,7 +1521,9 @@
how they anticipate new assertions being added to the set. There are three aspects to versioning policy assertions:</p>
<ulist>
<item>
- <p> Assertion Extensibility </p>
+ <p> Assertion Extensibility. Assertion authors should allow for extensibility
+ (see best practice 5. Start with a Simple Assertion)
+ </p>
</item>
<item>
<p> Policy Language Extensibility </p>
@@ -1568,8 +1565,9 @@
As an example, in <bibref ref="WS-Policy-Primer"/>
Section 4.2, the <code>sp:issuedToken</code> assertion utilizes the
<code>sp:RequestSecurityTokenTemplate</code> parameter that contains necessary
- information to request a security token. The contents of the parameter
- are static and allow reuse in different security scenarios.</p>
+ information to request a security token. The contents of the parameter are static and may be reused
+ in different security scenarios using other referencing mechanisms (these are
+ outside the scope of the WS-Policy Framework).</p>
</div2>
<div2 id="extending-assertions">
<head> Evolution of Assertions (Versioning and Compatibility)</head>
@@ -1604,7 +1602,8 @@
</div2>
<div2 id="supporting-new-policy-subjects">
- <head>Supporting New Policy Subjects</head>
+ <head>Supporting New Policy Subjects (see Section
+ 6.3 Supporting New Policy Subjects)</head>
<p>
The best practice <specref ref="bp-WSDL-policy-subject"/> specifies that policy authors should
define the set of policy subjects to which policy assertions can be
@@ -2748,6 +2747,16 @@
<loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/373">373</loc>.
</td>
</tr>
+ <tr>
+ <td>20071024</td>
+ <td>FJH</td>
+ <td>Implemented the resolution for issue
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5185">5184</loc>. Editors' action
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/372">372</loc>.
+ Implemented as originally proposed b,c,e,f,h,j. Implemented as amended a, k,l. Did not implement g which was not processed by WG.
+
+ </td>
+ </tr>
</tbody>
</table>
</inform-div1>
Index: ws-policy-guidelines-diff20070928.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines-diff20070928.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- ws-policy-guidelines-diff20070928.xml 22 Oct 2007 04:24:33 -0000 1.1
+++ ws-policy-guidelines-diff20070928.xml 24 Oct 2007 14:51:59 -0000 1.2
@@ -57,8 +57,9 @@
</p><p> As a companion document to the primer, this document also follows
the Socratic style of beginning with a question, and then answering
the question.
- </p></div1><div1 id="best-practices-list"><head>List of Best Practice Statements</head><p>The following Best Practices appear in this document with discussion and examples, and are summarized here for quick reference:</p><ulist><item><p><specref ref="bp-compatibility-tests"/></p></item><item><p><specref ref="bp-ignorable-for-not-related-to-compatibility-tests"/></p></item><item><p><specref ref="bp-semantics-and-form"/></p></item><item><p><specref ref="bp-assertion-start"/></p></item><item><p><specref ref="bp-unique-qnames"/></p></item><item><p><specref ref="XMLOutline"/></p></item><item><p><specref ref="AssertionDefinitions"/></p></item><item><p><specref ref="DefineIgnorable"/></p></item><item><p><specref ref="ignorableAssertions"/></p></item><item><p><specref ref="bp-assertion-xml-allow-optional"/></p></item><item><p><specref ref="bp-not-necessary-to-understand-a-message"/></p></item><item><p><specref ref="bp-assertion-duplication"/></p></item><item><p><specref ref="bp-assertion-parameters"/></p><item><item><p><specref ref="bp-dependent-behaviors"/></p></item><item><p><specref ref="bp-declare-nested-assertions"/></p></item><item><p><specref ref="bp-discourage-domain-specific-intersection"/></p></item><item><p><specref ref="bp-limit-optional-assertions"/></p></item><item><p><specref ref="bp-entire-mep-for-optional"/></p></item><item><p><specref ref="bp-indicate-optional-assertion-use"/></p></item><item><p><specref ref="bp-assertion-semantics"/></p></item><item><p><specref ref="bp-semantics-multiple-same-type"/></p></item><item><p><specref ref="bp-leverage-defined-attachment-mechanisms"/></p></item><item><p><specref ref="bp-use-defined-policy-subjects"/></p></item><item><p><specref ref="bp-identify-policy-subjects"/></p></item><item><p><specref ref="bp-WSDL-policy-subject"/></p></item><item><p><specref ref="bp-WSDL-consider-scope"/></p></item><item><p><specref ref="bp-WSDL-policy-subject-Granularity"/></p></item><item><p><specref ref="bp-WSDL-multiple-policy-subjects"/></p></item><item><p><specref ref"bp-WSDL-preferred-attachment-point"/></p></item><item><p><specref ref="bp-UDDI-tmodels"/></p></item><item><p><specref ref="bp-specify-composition"/></p></item><item><p><specref ref="bp-independent-assertions"/></p></item><item><p><specref ref="bp-policy-subject-change"/></p></item></ulist></div1><div1 id="Assertions"><head>What is an Assertion? </head><p>An assertion is a piece of metadata that describes a
- capability related to a specific WS-Policy domain. Sets of domain-specific assertions
+ </p></div1><div1 id="best-practices-list"><head>List of Best Practice Statements</head><p>The following Best Practices appear in this document with discussion and examples, and are summarized here for quick reference:</p><ulist><item><p><specref ref="bp-compatibility-tests"/></p></item><item><p><specref ref="bp-ignorable-for-not-related-to-compatibility-tests"/></p></item><item><p><specref ref="bp-semantics-and-form"/></p></item><item><p><specref ref="bp-assertion-start"/></p></item><item><p><specref ref="bp-unique-qnames"/></p></item><item><p><specref ref="XMLOutline"/></p></item><item><p><specref ref="AssertionDefinitions"/></p></item><item><p><specref ref="DefineIgnorable"/></p></item><item><p><specref ref="ignorableAssertions"/></p></item><item><p><specref ref="bp-assertion-xml-allow-optional"/></p></item><item><p><specref ref="bp-not-necessary-to-understand-a-message"/></p></item><item><p><specref ref="bp-assertion-duplication"/></p></item><item><p><specref ref="bp-assertion-parameters"/></p><item><item><p><specref ref="bp-dependent-behaviors"/></p></item><item><p><specref ref="bp-declare-nested-assertions"/></p></item><item><p><specref ref="bp-discourage-domain-specific-intersection"/></p></item><item><p><specref ref="bp-limit-optional-assertions"/></p></item><item><p><specref ref="bp-entire-mep-for-optional"/></p></item><item><p><specref ref="bp-indicate-optional-assertion-use"/></p></item><item><p><specref ref="bp-assertion-semantics"/></p></item><item><p><specref ref="bp-semantics-multiple-same-type"/></p></item><item><p><specref ref="bp-leverage-defined-attachment-mechanisms"/></p></item><item><p><specref ref="bp-use-defined-policy-subjects"/></p></item><item><p><specref ref="bp-identify-policy-subjects"/></p></item><item><p><specref ref="bp-WSDL-policy-subject"/></p></item><item><p><specref ref="bp-WSDL-consider-scope"/></p></item><item><p><specref ref="bp-WSDL-policy-subject-Granularity"/></p></item><item><p><specref ref="bp-WSDL-multiple-policy-subjects"/></p></item><item><p><specref ref"bp-WSDL-preferred-attachment-point"/></p></item><item><p><specref ref="bp-UDDI-tmodels"/></p></item><item><p><specref ref="bp-specify-composition"/></p></item><item><p><specref ref="bp-independent-assertions"/></p></item><item><p><specref ref="bp-policy-subject-change"/></p></item></ulist></div1><div1 id="Assertions"><head>What is an Assertion? </head><p>An assertion is a piece of metadata that describes a capability related to a specific <phrase diff="add">domain that
+ has chosen to express their capabilities
+ via the </phrase>WS-Policy <phrase diff="chg">expressions. </phrase>Sets of domain-specific assertions
are typically defined in a dedicated specification that describes
their semantics, applicability and scoping requirements as well
as their data type definition using XML Schema [<bibref ref="XMLSchemaPart1"/>].
@@ -139,11 +140,15 @@
this document to help communities utilize the framework in such
a way that multiple WS-Policy domains can co-exist and
consumers and providers can utilize the framework consistently across domains.
- </p><p>When using the WS-Policy Framework, any
- Assertion Authors defining new WS-Policy assertions
- must adhere to the MUST's and SHOULD's in the specification
- and should review the conformance section of the specification.
- </p><p>Assertion Authors should also specify a policy subject. For
+ </p><p><phrase diff="add">Assertion</phrase><phrase diff="del">When using </phrase><phrase diff="chg">authors should review </phrase><phrase diff="add">the</phrase><phrase diff="del">any
+ Assertion </phrase><phrase diff="chg">conformance sections of </phrase><phrase diff="add">the
+ </phrase>WS-Policy <phrase diff="add">Framework</phrase><phrase diff="del">assertions
+ must adhere </phrase><phrase diff="chg">and Attachment specifications </phrase>and an<phrase diff="del">SHOULD's in </phrase><phrase diff="chg">assertion </phrase><phrase diff="add">must</phrase><phrase diff="del">specification
+ and </phrase><phrase diff="add">adhere
+ to</phrase><phrase diff="del">should </phrase><phrase diff="chg">all </phrase>the <phrase diff="chg">constraints contained in </phrase>the <phrase diff="add">Framework and Attachment
+ specifications.
+ </phrase><phrase diff="del">specification.
+ </phrase></p><p>Assertion Authors should also specify a policy subject. For
instance, if a policy assertion were to be used with WSDL, an assertion
description should specify a WSDL policy subject.
</p><p>An example of a domain specification that follows these practices is the WS-SecurityPolicy
@@ -366,7 +371,8 @@
</wsp:Policy></eg></example></div2><div2 id="new-guidelines-domains"><head>Considerations when Modeling New Assertions</head><p>When creating a new policy domain, it is important to
understand how policy expressions are used by a
framework implementation that has followed the specifications.
- </p><p>The examples given in this document reference WS-Policy like WS-SecurityPolicy and WS-RM Policy.
+ </p><p>The examples given in this document <phrase diff="add">are
+ based</phrase><phrase diff="del">reference </phrase><phrase diff="chg">on </phrase><phrase diff="add">existing assertions such as</phrase><phrase diff="del">like </phrase>WS-SecurityPolicy and WS-RM Policy.
These policy expressions represent web services message exchange requirements, but policy authoring can
be done by individual groups that wish to represent web services application requirements and
deployments that wish to reuse the WS-Policy framework in
@@ -457,10 +463,12 @@
<quote> 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.
</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 xml:space="preserve">/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:
+ </p><p diff="del">To give an example, the WS-ReliableMessaging Policy document specifies attribute extensibility as part of the XML definition, allowing the wsp:Ignorable attribute:
+
+
+ WS-ReliableMessaging Policy use of attribute extensibility
+
+</p><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 <code>wsp:Optional</code> attribute. Assertion Authors should allow
@@ -520,7 +528,8 @@
their assertions by specifying additional properties, headers,
etc. that must be present in a message as part of their assertion design.
</p><p id="bp-not-necessary-to-understand-a-message" role="practice">
- <quote>Define message format only</quote>
+ <quote><phrase diff="chg">Assertions should not </phrase><phrase diff="add">describe message
+ semantics</phrase><phrase diff="del">only</phrase></quote>
<quote>Assertion Authors should not define policy assertions to represent information that is necessary to understand a message.</quote>
</p><p>For example, if the details of a message's encryption ( e.g., the cipher used, etc) are expressed
in policy that isn't attached to the message, it isn't possible
@@ -799,7 +808,7 @@
exchange when optionally used in part of that exchange
(<loc xmlns:xlink="http://www.w3.org/1999/xlink" href="#bp-entire-mep-for-optional" xlink:actuate="onRequest" xlink:show="replace" xlink:type="simple">Best Practice: Consider entire message exchange pattern when specifying Assertions that may be optional</loc>).
</p></div3></div2><div2 id="levels-of-abstraction"><head>Considerations for Policy Attachment</head><div3 id="general-attachment-guidelines"><head>General Guidelines</head><p><phrase diff="add">Although
- </phrase><phrase diff="del">The </phrase><phrase diff="chg">a policy assertion may </phrase><phrase diff="add">be constrained </phrase>to
+ </phrase><phrase diff="del">The </phrase><phrase diff="chg">a policy assertion </phrase><phrase diff="add">may be constrained</phrase><phrase diff="del">used </phrase>to
<phrase diff="del">communicate </phrase><phrase diff="chg">a specific set of policy subjects by Assertion </phrase><phrase diff="add">Authors,
its </phrase><phrase diff="del">additional
</phrase>semantics <phrase diff="chg">should not be dependent upon the mechanism by which the </phrase>policy <phrase diff="chg">expression is attached </phrase>to <phrase diff="chg">a
@@ -815,7 +824,7 @@
</phrase></p><p diff="chg" id="bp-assertion-semantics" role="practice">
<quote><phrase diff="chg">Semantics </phrase><phrase diff="add">Independent</phrase><phrase diff="del">Assertions
Assertion </phrase><phrase diff="chg">of Attachment </phrase><phrase diff="add">Mechanisms</phrase></quote>
- <quote diff="add"><phrase diff="add">The</phrase><phrase diff="del">encouraged </phrase><phrase diff="chg">semantics </phrase><phrase diff="add">of a</phrase><phrase diff="del">create </phrase>policy <phrase diff="chg">assertion </phrase><phrase diff="add">should</phrase><phrase diff="del">that
+ <quote diff="add"><phrase diff="add">The</phrase><phrase diff="del">encouraged </phrase><phrase diff="chg">semantics of </phrase>a policy <phrase diff="chg">assertion </phrase><phrase diff="add">should</phrase><phrase diff="del">that
can </phrase><phrase diff="chg">not depend on the </phrase>attachment <phrase diff="add">mechanism</phrase><phrase diff="del">mechanism. </phrase><phrase diff="add">used.</phrase></quote>
</p><p>For example, a security policy expression can be assigned a key reference and
be attached to a UDDI binding or can be embedded in a WSDL document. </p><p diff="add"><phrase diff="add">Since multiple attachment mechanisms may be used, a policy alternative created during the process of calculating
@@ -855,9 +864,10 @@
the policy subject level that might impact interoperability.</quote> </p><p>
Assertion Authors should review the policy subjects defined in WS-PolicyAttachments
and identify which of the existing policy subjects can be used with the assertions
- they define. That identification will facilitate the deployment of their policy
- assertions and include such information in the assertion definition.
- </p><p> An example of this practice is
+ they define. That
+ identification will facilitate the deployment of their policy
+ <phrase diff="del">assertions and include such information in the assertion </phrase><phrase diff="chg">assertions.
+ </phrase></p><p> An example of this practice is
the Reliable Messaging Policy Assertion document [<bibref ref="WS-RM-Policy"/>]. In the Sequence STR Assertion (section
2.5.1) the Reliable Messaging Policy Assertion authors state that "The
STR assertion defines the requirement that an RM Sequence MUST be bound
@@ -883,10 +893,10 @@
defined by an operation then the subject is the operation policy subject. </p></item><item><p>If the behavior applies to an input message then
the subject is the message policy subject - similarly for output and fault message WSDL policy subjects.</p></item></ulist><p id="bp-WSDL-policy-subject" role="practice">
<quote>Specify WSDL Policy Subject(s)</quote>
- <quote>Assertion Authors should specify the set of relevant WSDL policy subjects with which
- the assertion may be associated. For instance, if a policy assertion is to be used with
+ <quote>Assertion Authors should specify the set of
+ relevant WSDL policy subjects with which the assertion may be associated. <phrase diff="del">For instance, if a policy assertion is to be used with
a WSDL policy subject - such as service, endpoint, operation and message it should be stated.
- </quote>
+ </phrase></quote>
</p><p>Assertion Authors that utilize WSDL policy subjects need to
understand how the assertions will be
processed in intersection and merging, and the specific implications of
@@ -916,10 +926,12 @@
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. However such
- policy attachments to WSDL policy subjects of broader scope and granularity
- should be done only after careful evaluation.
- </p><p id="bp-WSDL-policy-subject-Granularity" role="practice">
+ policy subject instead of a message policy subject. <phrase diff="chg">The </phrase><phrase diff="add">best</phrase><phrase diff="del">such
+ policy </phrase><phrase diff="add">practice
+ is</phrase><phrase diff="del">attachments </phrase>to <phrase diff="chg">choose the most granular WSDL policy subject </phrase><phrase diff="add">to</phrase><phrase diff="del">granularity
+ should </phrase><phrase diff="chg">which the </phrase><phrase diff="add">behavior
+ represented</phrase><phrase diff="del">only </phrase><phrase diff="add">by a</phrase><phrase diff="del">after </phrase><phrase diff="add">policy assertion</phrase><phrase diff="del">careful </phrase><phrase diff="chg">applies.
+ </phrase></p><p id="bp-WSDL-policy-subject-Granularity" role="practice">
<quote>Choose the Most Granular WSDL Policy Subject</quote>
<quote>Assertion Authors should choose the most granular WSDL policy subject
to which the behavior represented by a policy assertion applies.
@@ -945,9 +957,9 @@
Web Services Reliable Messaging Policy Assertion specification
[<bibref ref="WS-RM-Policy"/>] gives rules on which WSDL policy subjects may be associated with the RM
Policy assertion, and which WSDL 1.1 elements may have RM Policy assertions attached.
- </p><p>If the capability may imply
- different semantics with respect to attachment points, the
- Assertion Authors should consider the following:</p><ulist><item><p> Decompose the semantics with several assertions.</p></item><item><p> Rewrite a single assertion targeting a specific subject. </p></item></ulist><p>Since many attachment points are available in WSDL, it would be
+ </p><p>If the <phrase diff="chg">behavior indicated </phrase><phrase diff="add">by</phrase><phrase diff="del">imply
+ different </phrase><phrase diff="chg">an assertion </phrase><phrase diff="add">varies when</phrase><phrase diff="del">respect </phrase><phrase diff="add">attached </phrase>to <phrase diff="chg">different </phrase><phrase diff="add">policy subjects</phrase><phrase diff="del">points, </phrase>the Assertion Authors
+ should consider the following:</p><ulist><item><p> Decompose the semantics with several assertions.</p></item><item><p> Rewrite a single assertion targeting a specific <phrase diff="add">policy </phrase>subject. </p></item></ulist><p>Since many attachment points are available in WSDL, it would be
necessary for Assertion Authors to recommend a preferred attachment
point. One approach would be to identify different attachment points in
a policy subject, choose the most granular policy subject that the
@@ -1023,7 +1035,9 @@
<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>)</quote>.
</p></div2></div1><div1 id="versioning-policy-assertions"><head>Versioning Policy Assertions</head><p>Assertion Authors need to consider not just the expression of the current set of requirements but
- how they anticipate new assertions being added to the set. There are three aspects to versioning policy assertions:</p><ulist><item><p> Assertion Extensibility </p></item><item><p> Policy Language Extensibility </p><p>Over time, the Policy WG or third parties can version or extend the Policy Language with new
+ how they anticipate new assertions being added to the set. There are three aspects to versioning policy assertions:</p><ulist><item><p> Assertion <phrase diff="add">Extensibility. Assertion authors should allow for extensibility
+ (see best practice 5. Start with a Simple</phrase><phrase diff="del">Extensibility </phrase><phrase diff="add">Assertion)
+ </phrase></p></item><item><p> Policy Language Extensibility </p><p>Over time, the Policy WG or third parties can version or extend the Policy Language with new
or modified constructs. These constructs may be compatible or incompatible with previous versions.
</p><p> Assertion Authors should review the WS-Policy Primer <bibref ref="WS-Policy-Primer"/>
and the specifications <bibref ref="WS-Policy"/> <bibref ref="WS-PolicyAttachment"/>
@@ -1041,8 +1055,9 @@
As an example, in <bibref ref="WS-Policy-Primer"/>
Section 4.2, the <code>sp:issuedToken</code> assertion utilizes the
<code>sp:RequestSecurityTokenTemplate</code> parameter that contains necessary
- information to request a security token. The contents of the parameter
- are static and allow reuse in different security scenarios.</p></div2><div2 id="extending-assertions"><head> Evolution of Assertions (Versioning and Compatibility)</head><p>Over time, there may be multiple equivalent behaviors emerging in the Web
+ information to request a security token. The contents of the parameter are static and <phrase diff="chg">may be </phrase><phrase diff="add">reused
+ </phrase>in different security <phrase diff="add">scenarios using other referencing mechanisms (these are
+ outside the scope of the WS-Policy Framework).</phrase><phrase diff="del">scenarios.</phrase></p></div2><div2 id="extending-assertions"><head> Evolution of Assertions (Versioning and Compatibility)</head><p>Over time, there may be multiple equivalent behaviors emerging in the Web
Service interaction space. Examples of such multiple equivalent behaviors are WSS: SOAP Message Security 1.0
vs. 1.1 and WS-Addressing August 2004 version vs. WS-Addressing W3C Recommendation
[<bibref ref="WS-Addressing"/>]. These equivalent behaviors
@@ -1059,7 +1074,8 @@
Security 1.1. These are multiple equivalent behaviors and are represented using distinct
policy assertions.</p><example><head>Message-level Security and WSS: SOAP Message Security 1.1</head><eg xml:space="preserve"><Policy>
<sp:Wss11>…</sp:Wss11>
-</Policy></eg></example></div2><div2 id="supporting-new-policy-subjects"><head>Supporting New Policy Subjects</head><p>
+</Policy></eg></example></div2><div2 id="supporting-new-policy-subjects"><head>Supporting New Policy Subjects <phrase diff="add">(see Section
+ 6.3 Supporting New Policy Subjects)</phrase></head><p>
The best practice <specref ref="bp-WSDL-policy-subject"/> 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
@@ -1553,4 +1569,9 @@
</td></tr><tr diff="add"><td colspan="1" diff="add" rowspan="1">20071017</td><td colspan="1" diff="add" rowspan="1">FJH</td><td colspan="1" diff="add" rowspan="1">Implemented the resolution for issue
<loc xmlns:xlink="http://www.w3.org/1999/xlink" href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5185" xlink:actuate="onRequest" xlink:show="replace" xlink:type="simple"><phrase diff="add">5185</phrase></loc>. Editors' action
<loc xmlns:xlink="http://www.w3.org/1999/xlink" href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/373" xlink:actuate="onRequest" xlink:show="replace" xlink:type="simple"><phrase diff="add">373</phrase></loc>.
+ </td></tr><tr diff="add"><td colspan="1" diff="add" rowspan="1">20071024</td><td colspan="1" diff="add" rowspan="1">FJH</td><td colspan="1" diff="add" rowspan="1">Implemented the resolution for issue
+ <loc xmlns:xlink="http://www.w3.org/1999/xlink" href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=5185" xlink:actuate="onRequest" xlink:show="replace" xlink:type="simple"><phrase diff="add">5184</phrase></loc>. Editors' action
+ <loc xmlns:xlink="http://www.w3.org/1999/xlink" href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/372" xlink:actuate="onRequest" xlink:show="replace" xlink:type="simple"><phrase diff="add">372</phrase></loc>.
+ Implemented as originally proposed b,c,e,f,h,j. Implemented as amended a, k,l. Did not implement g which was not processed by WG.
+
</td></tr></tbody></table></inform-div1></back></spec>
\ No newline at end of file
Received on Wednesday, 24 October 2007 14:52:26 UTC