- From: Prasad Yendluri via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 29 May 2007 22:45:14 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv22660
Modified Files:
ws-policy-guidelines.html ws-policy-guidelines.xml
Log Message:
Implemented Resolution in Editors' action 290. Consistent use of Assertion Authors.
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.64
retrieving revision 1.65
diff -u -d -r1.64 -r1.65
--- ws-policy-guidelines.html 29 May 2007 21:37:31 -0000 1.64
+++ ws-policy-guidelines.html 29 May 2007 22:45:12 -0000 1.65
@@ -107,8 +107,8 @@
<a href="http://www.w3.org/TR/2006/WD-ws-policy-guidelines-20061221">http://www.w3.org/TR/2006/WD-ws-policy-guidelines-20061221</a>
</dd><dt>Editors:</dt><dd>Asir S Vedamuthu, Microsoft Corporation</dd><dd>David Orchard, BEA Systems, Inc.</dd><dd>Frederick Hirsch, Nokia</dd><dd>Maryann Hondo, IBM Corporation</dd><dd>Prasad Yendluri, webMethods, Inc.</dd><dd>Toufic Boubez, Layer 7 Technologies</dd><dd>Ümit Yalçinalp, SAP AG.</dd></dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © @@@@ <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.org/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark/a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr><div>
<h2><a name="abstract" id="abstract"></a>Abstract</h2><p>
- <em>Web Services Policy 1.5 - Guidelines for Policy Assertion Authors</em> is intended to provide guidance for assertion
- authors that will work with the Web Services Policy 1.5 - Framework [<cite><a href="#WS-Policy">Web Services Policy Framework</a></cite>] and Web Services Policy 1.5 - Attachment [<cite><a href="#WS-PolicyAttachment">Web Services Policy Attachment</a></cite>] specifications to create domain
+ <em>Web Services Policy 1.5 - Guidelines for Policy Assertion Authors</em> is intended to provide guidance for Assertion
+ Authors that will work with the Web Services Policy 1.5 - Framework [<cite><a href="#WS-Policy">Web Services Policy Framework</a></cite>] and Web Services Policy 1.5 - Attachment [<cite><a href="#WS-PolicyAttachment">Web Services Policy Attachment</a></cite>] specifications to create domain
specific assertions. The focus of this document is to provide
best practices and patterns to follow as well as illustrate
the care needed in using WS-Policy to achieve the best
@@ -300,7 +300,7 @@
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>An assertion author should also specify a policy subject. For
+ </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
@@ -407,7 +407,7 @@
Attachment specification.
</p><p>Although a policy
assertion may be constrained to a specific set of policy subjects by
- assertion authors, its semantics should not be dependent upon the
+ Assertion Authors, its semantics should not be dependent upon the
mechanism by which the policy expression is attached to a given policy
subject. For instance, an assertion "Foo" has the same semantic when
attached to an operation policy subject regardless of whether it was
@@ -421,7 +421,7 @@
The semantics of a policy assertion should not depend on the
attachment mechanism used.</p></div><table border="1" summary="Editorial note"><tr><td align="left" valign="top" width="50%"><b>Editorial note</b></td><td align="right" valign="top" width="50%"> </td></tr><tr><td colspan="2" align="left" valign="top">April 25th 07, editors
<a href="http://www.w3.org/2007/04/25-ws-policy-eds-minutes.html#item03">decided</a> to add G2 -
- "An assertion author should define
+ "Assertion Authors should define
policy assertions for behaviors that are relevant to compatibility tests,
such as web service protocols that manifest on the wire." - to Section 5.1.
May 9th 07, an issue was opened against G2 - issue
@@ -540,12 +540,12 @@
assertions to define. Interoperability testing of new policy
domains is recommended to ensure that consumers and providers
are able to use the new domain assertions. To facilitate proper
- progression of an assertion, assertion authors should start with
+ progression of an assertion, Assertion Authors should start with
a simple working assertion that allows extensibility. As the design
work progresses, one may add more parameters or nested policy assertions
to meet one's interoperability needs.
</p><div class="boxedtext"><p><a name="bp-assertion-start" id="bp-assertion-start"></a><span class="practicelab">Best
-Practice 4: Start with Simple Assertion</span></p><p class="practice">An assertion author should start with a simple working assertion
+Practice 4: Start with Simple Assertion</span></p><p class="practice">Assertion Authors should start with a simple working assertion
that allows assertion parameter extensibility. </p></div><p>New Assertion Authors are encouraged to look at <cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite> to see an example of a
relatively simple domain that has defined three assertions. Assertion Authors are encouraged to look at <cite><a href="#WS-SecurityPolicy">WS-SecurityPolicy</a></cite> to see an example of a complex domain that has been decomposed into a set of policy expressions.
</p></div><div class="div3">
@@ -557,7 +557,7 @@
or an attribute of an assertion. The general guidelines on when to use XML elements
versus attributes apply is. Use a unique QName to identify a distinct behavior and provide
an XML outline (plus an XML schema document) to specify the syntax of an assertion. </p><div class="boxedtext"><p><a name="bp-unique-qnames" id="bp-unique-qnames"></a><span class="practicelab">Best
-Practice 5: Use Unique QNames</span></p><p class="practice">An assertion author should use a unique QName to identify a distinct behavior.</p></div><p>The syntax of an assertion can be represented using an XML outline (plus an XML schema
+Practice 5: Use Unique QNames</span></p><p class="practice">Assertion Authors should use a unique QName to identify a distinct behavior.</p></div><p>The syntax of an assertion can be represented using an XML outline (plus an XML schema
document). If the assertion has a nested policy expression then the assertion XML
outline can enumerate the nested assertions that are allowed. An example is the following:
</p><div class="exampleOuter"><div class="exampleInner"><pre>
@@ -616,7 +616,7 @@
their assertions by specifying additional properties, headers,
etc. that must be present in a message as part of their assertion design.
</p><div class="boxedtext"><p><a name="bp-not-necessary-to-understand-a-message" id="bp-not-necessary-to-understand-a-message"></a><span class="practicelab">Best
-Practice 8: Not Necessary to Understand a Message</span></p><p class="practice">An assertion author should not define policy assertions to represent information that is necessary to understand a message.</p></div><p>For example, if the details of a message's encryption ( e.g., the cipher used, etc) are expressed
+Practice 8: Not Necessary to Understand a Message</span></p><p class="practice">Assertion Authors should not define policy assertions to represent information that is necessary to understand a message.</p></div><p>For example, if the details of a message's encryption ( e.g., the cipher used, etc) are expressed
in policy that isn't attached to the message, it isn't possible
to later decipher it. This is very different from expressing, in
policy, what ciphers (and so forth) are supported by a particular
@@ -643,10 +643,10 @@
of services need to find value in the set of
assertions or they will not include the assertions in
their service descriptions.
- </p><p>It is the responsibility of the assertion authors to avoid duplication of assertions.
+ </p><p>It is the responsibility of the Assertion Authors to avoid duplication of assertions.
A review by a broad community is the best way to ensure that the granularity of a set
of domain assertions is appropriate.</p><div class="boxedtext"><p><a name="bp-assertion-duplication" id="bp-assertion-duplication"></a><span class="practicelab">Best
-Practice 9: Avoid Duplication of Assertions</span></p><p class="practice">An assertion author should reuse an existing assertion (rather than create a new one) whenever possible.</p></div></div></div><div class="div2">
+Practice 9: Avoid Duplication of Assertions</span></p><p class="practice">Assertion Authors should reuse an existing assertion (rather than create a new one) whenever possible.</p></div></div></div><div class="div2">
<h3><a name="comparison" id="comparison"></a>5.4 Comparison of Nested and Parameterized Assertions</h3><p>There are two different ways to provide additional information in an
assertion beyond its type. We cover these two cases below followed by a
comparison of these approaches targeting when to use either of the approach.
@@ -662,7 +662,7 @@
and attributes of the assertion excluding child elements and attributes
from the policy language namespace name are the assertion parameters.</p><div class="boxedtext"><p><a name="bp-assertion-parameters" id="bp-assertion-parameters"></a><span class="practicelab">Best
Practice 10: Use Parameters for Useful
- Information</span></p><p class="practice">An assertion author should represent useful (or additional)
+ Information</span></p><p class="practice">Assertion Authors should represent useful (or additional)
information necessary for engaging the behavior represented by a policy
assertion as assertion parameters.
</p></div><p>In the example below, <code>sp:Body</code> and <code>sp:Header</code>
@@ -695,7 +695,7 @@
that are allowed. There is one caveat to watch out for: policy assertions
with deeply nested policy can greatly increase the complexity of a policy and should be
avoided when they are not needed.</p><div class="boxedtext"><p><a name="bp-dependent-behaviors" id="bp-dependent-behaviors"></a><span class="practicelab">Best
-Practice 11: Use Nested Assertions for Dependent Behaviors</span></p><p class="practice">An assertion author should represent dependent behaviors that are relevant
+Practice 11: Use Nested Assertions for Dependent Behaviors</span></p><p class="practice">Assertion Authors should represent dependent behaviors that are relevant
to a compatibility test and apply to the same policy subject using
nested policy assertions.</p></div><div class="boxedtext"><p><a name="bp-declare-nested-assertions" id="bp-declare-nested-assertions"></a><span class="practicelab">Best
Practice 12: Declare Nested Assertions</span></p><p class="practice">If there is a nested policy expression, an assertion description should declare it
@@ -779,7 +779,7 @@
dependent behaviors automatically. This means the complexity of
security usage is absorbed by a policy-aware client and hidden
from Web service application developers.
- </p><p>Assertion authors should note the effect of nested policy expressions
+ </p><p>Assertion Authors should note the effect of nested policy expressions
on policy intersection in their nested policy design. The result of
intersecting an assertion that contains an empty nested policy
expression with an assertion of the same type without a nested policy
@@ -808,7 +808,7 @@
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><table border="1" summary="Editorial note"><tr><td align="left" valign="top" width="50%"><b>Editorial note</b></td><td align="right" valign="top" width="50%"> </td></tr><tr><td colspan="2" align="left" valign="top">Looks incomplete – carries Best Practices but there isn’t any explanatory text.</td></tr></table><p>Policy assertions can be marked with an attribute to indicate that the assertion
- can be ignored by the interstection algorithm. Assertion authors should consider
+ can be ignored by the interstection algorithm. Assertion Authors should consider
whether the behavior represented by the Assertion they are defining can be ignored for the purposes of
intersection, and indicate this in the definition of the assertion. The use of the
ignorable attribute influences whether or not certain assertions are part of the
@@ -836,7 +836,7 @@
the consumer by selecting the appropriate policy alternative.
The provider may influence what is possible by choosing whether or not to
include policy alternatives in a policy expression, by using
- the wsp:Optional attribute. An assertion author should clearly indicate in the assertion
+ the wsp:Optional attribute. Assertion Authors should clearly indicate in the assertion
definition that it is possible to be optional
and to allow the use of the wsp:Optional attribute in the XML definition. </p><div class="boxedtext"><p><a name="bp-assertion-xml-allow-optional" id="bp-assertion-xml-allow-optional"></a><span class="practicelab">Best
Practice 16: Assertion XML should allow use of wsp:Optional attribute</span></p><p class="practice">An assertion XML outline should allow the use of the wsp:Optional attribute to
@@ -938,7 +938,7 @@
</p></div></div></div><div class="div2">
<h3><a name="levels-of-abstraction" id="levels-of-abstraction"></a>5.7 Considerations for Policy Attachment in WSDL </h3><p>A behavior identified by a policy assertion applies to the
associated policy subject. If a policy assertion is to be used
- within WSDL, assertion authors must specify a WSDL
+ within WSDL, Assertion Authors must specify a WSDL
policy subject.
</p><p>The specific WSDL policy subject is determined with respect to
a behavior as follows:</p><ul><li><p>If the behavior applies to any message exchange
@@ -947,10 +947,10 @@
made using an endpoint then the subject is the endpoint policy subject. </p></li><li><p>If the behavior applies to any message exchange
defined by an operation then the subject is the operation policy subject. </p></li><li><p>If the behavior applies to an input message then
the subject is the message policy subject - similarly for output and fault message policy subjects.</p></li></ul><div class="boxedtext"><p><a name="bp-WSDL-policy-subject" id="bp-WSDL-policy-subject"></a><span class="practicelab">Best
-Practice 21: Assertion Description Should Specify a Policy Subject</span></p><p class="practice">Assertion authors should associate assertions with the appropriate policy subject.
+Practice 21: Assertion Description Should Specify a Policy Subject</span></p><p class="practice">Assertion Authors should associate assertions with the appropriate policy subject.
For instance, if a policy assertion is to be used with WSDL, the assertion description
should specify a WSDL policy subject – such as service, endpoint, operation and message.
- </p></div><p>Assertion authors that wish to utilize WSDL policy subjects need to
+ </p></div><p>Assertion Authors that wish to utilize WSDL policy subjects need to
understand how the assertions will be
processed in an intersection and merging, and the implications of
the processing for considering a specific attachment point and
@@ -958,9 +958,9 @@
</p><p> For a given WSDL policy subject, there may be several
attachment points. For example, there are three attachment
points for the endpoint policy subject: the port, binding and
- portType element. Assertion authors should identify the
+ portType element. Assertion Authors should identify the
relevant attachment point when defining a new assertion. To
- determine the relevant attachment points, assertion authors should
+ determine the relevant attachment points, Assertion Authors should
consider the scope of the attachment point. For example, an
assertion should only be allowed in the portType element if
the assertion reasonably applies to any endpoint that ever
@@ -979,13 +979,13 @@
policy attachments to policy subjects of broader scope and granularity
should be done only after careful evaluation.
</p><div class="boxedtext"><p><a name="bp-WSDL-policy-subject-Granularity" id="bp-WSDL-policy-subject-Granularity"></a><span class="practicelab">Best
-Practice 22: Choose a Granular Policy Subject</span></p><p class="practice">Assertion authors should choose the most granular policy subject
+Practice 22: Choose a Granular Policy Subject</span></p><p class="practice">Assertion Authors should choose the most granular policy subject
that the behavior represented by a policy assertion applies to.
</p></div><p>
- For authoring convenience, an assertion author may allow the
+ For authoring convenience, Assertion Authors may allow the
association of an assertion to multiple policy subjects. If an
assertion is allowed to be associated with multiple policy
- subjects as is possible with WSDL, then the assertion author has
+ subjects as is possible with WSDL, then the Assertion Authors have
the burden to describe the semantics of multiple instances of the
same assertion attached to different policy subjects at the same
time in order to avoid conflicting behavior.
@@ -996,14 +996,14 @@
at the same time.
</p></div><p>If the capability is not really suitable and may imply
different semantics with respect to attachment points, the
- assertion authors should consider the following:</p><ul><li><p> Decompose the semantics with several assertions.</p></li><li><p> Rewrite a single assertion targeting a specific subject. </p></li></ul><p>
+ 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>
<table border="1" summary="Editorial note"><tr><td align="left" valign="top" width="50%"><b>Editorial note</b></td><td align="right" valign="top" width="50%"> </td></tr><tr><td colspan="2" align="left" valign="top">
The following paragraph is likely to change,
as there is an issue 4074, open against this paragraph.
</td></tr></table>
</p><p>The current set of subjects as mapped to the WSDL 1.1
elements, can also constrain the assertion constructs.
- For Example, in WS-RM, the assertion authors chose to support
+ For Example, in WS-RM, the Assertion Authors chose to support
certain capabilities at the endpoint level. This resulted in
the finer granularity of the assertion to apply at the message
policy subject, but the assertion semantics also indicates that
@@ -1012,11 +1012,11 @@
the engagement of RM. So, the WS-RM Policy is a capability that
governs a target endpoints capability to accept sequences that
is beyond single message exchanges. This is illustrative of how the
- assertion author can specify additional constraints and assumptions
+ Assertion Authors can specify additional constraints and assumptions
for attachment and engagement of behavior. Such additional constraints
- must be clearly specified by the assertion authors.
+ must be clearly specified by the Assertion Authors.
</p><p>Since many attachment points are available in WSDL, it would be
- necessary for an assertion author to recommend a preferred attachment
+ 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
behavior applies to and specify that as a preferred attachment point.
@@ -1032,9 +1032,9 @@
rather abstract requirements, this technique does not apply.
</p><div class="boxedtext"><p><a name="bp-WSDL-preferred-attachment-point" id="bp-WSDL-preferred-attachment-point"></a><span class="practicelab">Best
Practice 24: Specify Preferred Attachment Point for an Assertion</span></p><p class="practice">If an assertion can be attached at multiple points within a policy
- subject, an assertion author should specify a preferred attachment
+ subject, Assertion Authors should specify a preferred attachment
point for the chosen policy subject.
- </p></div><p>Assertion authors that utilize WSDL policy subjects need to
+ </p></div><p>Assertion Authors that utilize WSDL policy subjects need to
understand how the assertions will be processed in merging and
the specify implications of ending up with multiple assertions of
the same kind in an alternative, in the merged policy. For example,
@@ -1057,7 +1057,7 @@
(if any) when there are multiple instances of a policy assertion in
the same policy alternative.
</p></div></div><div class="div2">
-<h3><a name="interrelated-domains" id="interrelated-domains"></a>5.8 Interrelated domains</h3><table border="1" summary="Editorial note"><tr><td align="left" valign="top" width="50%"><b>Editorial note</b></td><td align="right" valign="top" width="50%"> </td></tr><tr><td colspan="2" align="left" valign="top">To be re-structured to use the format in the Architecture of the WWW doc.</td></tr></table><p>Assertion authors need to be clear about how assertions defined in
+<h3><a name="interrelated-domains" id="interrelated-domains"></a>5.8 Interrelated domains</h3><table border="1" summary="Editorial note"><tr><td align="left" valign="top" width="50%"><b>Editorial note</b></td><td align="right" valign="top" width="50%"> </td></tr><tr><td colspan="2" align="left" valign="top">To be re-structured to use the format in the Architecture of the WWW doc.</td></tr></table><p>Assertion Authors need to be clear about how assertions defined in
their domain may fit with assertions for interrelated domains. A
classic example of such an interrelated domain is security, because
security tends to
@@ -1065,7 +1065,7 @@
of additional assertions
related to the interrelated security domain [<cite><a href="#WS-SecurityPolicy">WS-SecurityPolicy</a></cite>] in
Web Services Reliable Messaging Policy
- Assertions [<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite>]. </p><p>Assertion authors should not duplicate existing
+ Assertions [<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite>]. </p><p>Assertion Authors should not duplicate existing
assertions and should also make sure that when adding assertions those new assertions are consistent
with pre-existing assertions of any
interrelated domain. </p><div class="boxedtext"><p><a name="bp-specify-composition" id="bp-specify-composition"></a><span class="practicelab">Best
@@ -1083,7 +1083,7 @@
the identification mechanism defined in the Policy specification to
expose a complex policy expression as a reusable building block for
other policy expressions by reference. Reuse may also be useful for
- domain assertion authors, especially those defining complex assertions
+ domain Assertion Authors, especially those defining complex assertions
utilizing references to policy expressions by nesting. Statically
available parameterized content may also be reused by different
assertions. However, such referencing mechanism is outside the scope of
@@ -1099,7 +1099,7 @@
[<cite><a href="#WS-Addressing">WS-Addressing Core</a></cite>]. These equivalent behaviors
are mutually exclusive for an interaction. Such equivalent
behaviors can be modeled as independent assertions. </p><div class="boxedtext"><p><a name="bp-independent-assertions" id="bp-independent-assertions"></a><span class="practicelab">Best
-Practice 27: Use Independent Assertions for Multiple Versions of a Behavior</span></p><p class="practice">An assertion author should use independent assertions for modeling multiple
+Practice 27: Use Independent Assertions for Multiple Versions of a Behavior</span></p><p class="practice">Assertion Authors should use independent assertions for modeling multiple
versions of a behavior.</p></div><p>The
policy expression in the example below requires the use of
WSS: SOAP Message Security 1.0. </p><div class="exampleOuter">
@@ -1115,7 +1115,7 @@
The <a href="#bp-assertion-specification-parts">Best Practice: Parts of an Assertion Specification</a> specifies that policy authors should
define the set of policy subjects to which policy assertions can be
attached. Over time, new policy subjects may need to be defined. When
- this occurs, a policy assertion author may update the list of policy
+ this occurs, policy Assertion Authors may update the list of policy
subjects supported by an assertion.
</p><p>
When the assertion's semantics do not change to invalidate any of the
@@ -1600,7 +1600,6 @@
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4073">4073</a>
in response to editor's action
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/199">199 </a>
-
as outlined in
<a href="http://lists.w3.org/Archives/Public/public-ws-policy/2007Mar/0093.html">proposal </a>.
</td></tr><tr><td rowspan="1" colspan="1">20070320</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Implemented the <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4319#c1">resolution</a>
@@ -1695,4 +1694,7 @@
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/284">284</a>.
</td></tr><tr><td rowspan="1" colspan="1">20070529</td><td rowspan="1" colspan="1">PY</td><td rowspan="1" colspan="1">Implemented Resolution for <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4573">issue 4573</a>.
Apply "Best Practices" consistently.
+ </td></tr><tr><td rowspan="1" colspan="1">20070529</td><td rowspan="1" colspan="1">PY</td><td rowspan="1" colspan="1">Implemented Resolution in Editors' action
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/290">290</a>.
+ Consistent use of Assertion Authors.
</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.78
retrieving revision 1.79
diff -u -d -r1.78 -r1.79
--- ws-policy-guidelines.xml 29 May 2007 21:37:31 -0000 1.78
+++ ws-policy-guidelines.xml 29 May 2007 22:45:12 -0000 1.79
@@ -62,8 +62,8 @@
</authlist>
<abstract>
<p>
- <emph>&guidelines.title;</emph> is intended to provide guidance for assertion
- authors that will work with the &framework.title; [<bibref
+ <emph>&guidelines.title;</emph> is intended to provide guidance for Assertion
+ Authors that will work with the &framework.title; [<bibref
ref="WS-Policy"/>] and &attachment.title; [<bibref
ref="WS-PolicyAttachment"/>] specifications to create domain
specific assertions. The focus of this document is to provide
@@ -301,7 +301,7 @@
must adhere to the MUST's and SHOULD's in the specification
and should review the conformance section of the specification.
</p>
- <p>An assertion author should also specify a policy subject. For
+ <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>
@@ -467,7 +467,7 @@
</p>
<p>Although a policy
assertion may be constrained to a specific set of policy subjects by
- assertion authors, its semantics should not be dependent upon the
+ Assertion Authors, its semantics should not be dependent upon the
mechanism by which the policy expression is attached to a given policy
subject. For instance, an assertion "Foo" has the same semantic when
attached to an operation policy subject regardless of whether it was
@@ -485,7 +485,7 @@
<ednote>
<edtext>April 25th 07, editors
<loc href="http://www.w3.org/2007/04/25-ws-policy-eds-minutes.html#item03">decided</loc> to add G2 -
- "An assertion author should define
+ "Assertion Authors should define
policy assertions for behaviors that are relevant to compatibility tests,
such as web service protocols that manifest on the wire." - to Section 5.1.
May 9th 07, an issue was opened against G2 - issue
@@ -631,13 +631,13 @@
assertions to define. Interoperability testing of new policy
domains is recommended to ensure that consumers and providers
are able to use the new domain assertions. To facilitate proper
- progression of an assertion, assertion authors should start with
+ progression of an assertion, Assertion Authors should start with
a simple working assertion that allows extensibility. As the design
work progresses, one may add more parameters or nested policy assertions
to meet one's interoperability needs.
</p>
<p role="practice" id="bp-assertion-start"><quote>Start with Simple Assertion</quote>
- <quote>An assertion author should start with a simple working assertion
+ <quote>Assertion Authors should start with a simple working assertion
that allows assertion parameter extensibility. </quote>
</p>
<p>New Assertion Authors are encouraged to look at <bibref ref="WS-RM-Policy"/> to see an example of a
@@ -657,7 +657,7 @@
an XML outline (plus an XML schema document) to specify the syntax of an assertion. </p>
<p role="practice" id="bp-unique-qnames"><quote>Use Unique QNames</quote>
- <quote>An assertion author should use a unique QName to identify a distinct behavior.</quote>
+ <quote>Assertion Authors should use a unique QName to identify a distinct behavior.</quote>
</p>
<p>The syntax of an assertion can be represented using an XML outline (plus an XML schema
document). If the assertion has a nested policy expression then the assertion XML
@@ -740,7 +740,7 @@
</p>
<p role="practice" id="bp-not-necessary-to-understand-a-message">
<quote>Not Necessary to Understand a Message</quote>
- <quote>An assertion author should not define policy assertions to represent information that is necessary to understand a message.</quote>
+ <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
@@ -774,12 +774,12 @@
assertions or they will not include the assertions in
their service descriptions.
</p>
- <p>It is the responsibility of the assertion authors to avoid duplication of assertions.
+ <p>It is the responsibility of the Assertion Authors to avoid duplication of assertions.
A review by a broad community is the best way to ensure that the granularity of a set
of domain assertions is appropriate.</p>
<p role="practice" id="bp-assertion-duplication"><quote>Avoid Duplication of Assertions</quote>
- <quote>An assertion author should reuse an existing assertion (rather than create a new one) whenever possible.</quote>
+ <quote>Assertion Authors should reuse an existing assertion (rather than create a new one) whenever possible.</quote>
</p>
</div3>
</div2>
@@ -807,7 +807,7 @@
<p role="practice" id="bp-assertion-parameters"><quote>Use Parameters for Useful
Information</quote>
- <quote>An assertion author should represent useful (or additional)
+ <quote>Assertion Authors should represent useful (or additional)
information necessary for engaging the behavior represented by a policy
assertion as assertion parameters.
</quote>
@@ -865,7 +865,7 @@
<p role="practice" id="bp-dependent-behaviors">
<quote>Use Nested Assertions for Dependent Behaviors</quote>
- <quote>An assertion author should represent dependent behaviors that are relevant
+ <quote>Assertion Authors should represent dependent behaviors that are relevant
to a compatibility test and apply to the same policy subject using
nested policy assertions.</quote></p>
@@ -974,7 +974,7 @@
from Web service application developers.
</p>
- <p>Assertion authors should note the effect of nested policy expressions
+ <p>Assertion Authors should note the effect of nested policy expressions
on policy intersection in their nested policy design. The result of
intersecting an assertion that contains an empty nested policy
expression with an assertion of the same type without a nested policy
@@ -1020,7 +1020,7 @@
<edtext>Looks incomplete – carries Best Practices but there isn’t any explanatory text.</edtext>
</ednote>
<p>Policy assertions can be marked with an attribute to indicate that the assertion
- can be ignored by the interstection algorithm. Assertion authors should consider
+ can be ignored by the interstection algorithm. Assertion Authors should consider
whether the behavior represented by the Assertion they are defining can be ignored for the purposes of
intersection, and indicate this in the definition of the assertion. The use of the
ignorable attribute influences whether or not certain assertions are part of the
@@ -1061,7 +1061,7 @@
the consumer by selecting the appropriate policy alternative.
The provider may influence what is possible by choosing whether or not to
include policy alternatives in a policy expression, by using
- the wsp:Optional attribute. An assertion author should clearly indicate in the assertion
+ the wsp:Optional attribute. Assertion Authors should clearly indicate in the assertion
definition that it is possible to be optional
and to allow the use of the wsp:Optional attribute in the XML definition. </p>
@@ -1202,7 +1202,7 @@
<head>Considerations for Policy Attachment in WSDL </head>
<p>A behavior identified by a policy assertion applies to the
associated policy subject. If a policy assertion is to be used
- within WSDL, assertion authors must specify a WSDL
+ within WSDL, Assertion Authors must specify a WSDL
policy subject.
</p>
@@ -1230,13 +1230,13 @@
<p role="practice" id="bp-WSDL-policy-subject">
<quote>Assertion Description Should Specify a Policy Subject</quote>
- <quote>Assertion authors should associate assertions with the appropriate policy subject.
+ <quote>Assertion Authors should associate assertions with the appropriate policy subject.
For instance, if a policy assertion is to be used with WSDL, the assertion description
should specify a WSDL policy subject – such as service, endpoint, operation and message.
</quote>
</p>
- <p>Assertion authors that wish to utilize WSDL policy subjects need to
+ <p>Assertion Authors that wish to utilize WSDL policy subjects need to
understand how the assertions will be
processed in an intersection and merging, and the implications of
the processing for considering a specific attachment point and
@@ -1246,9 +1246,9 @@
<p> For a given WSDL policy subject, there may be several
attachment points. For example, there are three attachment
points for the endpoint policy subject: the port, binding and
- portType element. Assertion authors should identify the
+ portType element. Assertion Authors should identify the
relevant attachment point when defining a new assertion. To
- determine the relevant attachment points, assertion authors should
+ determine the relevant attachment points, Assertion Authors should
consider the scope of the attachment point. For example, an
assertion should only be allowed in the portType element if
the assertion reasonably applies to any endpoint that ever
@@ -1271,16 +1271,16 @@
<p role="practice" id="bp-WSDL-policy-subject-Granularity">
<quote>Choose a Granular Policy Subject</quote>
- <quote>Assertion authors should choose the most granular policy subject
+ <quote>Assertion Authors should choose the most granular policy subject
that the behavior represented by a policy assertion applies to.
</quote>
</p>
<p>
- For authoring convenience, an assertion author may allow the
+ For authoring convenience, Assertion Authors may allow the
association of an assertion to multiple policy subjects. If an
assertion is allowed to be associated with multiple policy
- subjects as is possible with WSDL, then the assertion author has
+ subjects as is possible with WSDL, then the Assertion Authors have
the burden to describe the semantics of multiple instances of the
same assertion attached to different policy subjects at the same
time in order to avoid conflicting behavior.
@@ -1297,7 +1297,7 @@
<p>If the capability is not really suitable and may imply
different semantics with respect to attachment points, the
- assertion authors should consider the following:</p>
+ Assertion Authors should consider the following:</p>
<ulist>
<item>
<p> Decompose the semantics with several assertions.</p>
@@ -1318,7 +1318,7 @@
<p>The current set of subjects as mapped to the WSDL 1.1
elements, can also constrain the assertion constructs.
- For Example, in WS-RM, the assertion authors chose to support
+ For Example, in WS-RM, the Assertion Authors chose to support
certain capabilities at the endpoint level. This resulted in
the finer granularity of the assertion to apply at the message
policy subject, but the assertion semantics also indicates that
@@ -1327,13 +1327,13 @@
the engagement of RM. So, the WS-RM Policy is a capability that
governs a target endpoints capability to accept sequences that
is beyond single message exchanges. This is illustrative of how the
- assertion author can specify additional constraints and assumptions
+ Assertion Authors can specify additional constraints and assumptions
for attachment and engagement of behavior. Such additional constraints
- must be clearly specified by the assertion authors.
+ must be clearly specified by the Assertion Authors.
</p>
<p>Since many attachment points are available in WSDL, it would be
- necessary for an assertion author to recommend a preferred attachment
+ 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
behavior applies to and specify that as a preferred attachment point.
@@ -1352,12 +1352,12 @@
<p role="practice" id="bp-WSDL-preferred-attachment-point">
<quote>Specify Preferred Attachment Point for an Assertion</quote>
<quote>If an assertion can be attached at multiple points within a policy
- subject, an assertion author should specify a preferred attachment
+ subject, Assertion Authors should specify a preferred attachment
point for the chosen policy subject.
</quote>
</p>
- <p>Assertion authors that utilize WSDL policy subjects need to
+ <p>Assertion Authors that utilize WSDL policy subjects need to
understand how the assertions will be processed in merging and
the specify implications of ending up with multiple assertions of
the same kind in an alternative, in the merged policy. For example,
@@ -1391,7 +1391,7 @@
<ednote>
<edtext>To be re-structured to use the format in the Architecture of the WWW doc.</edtext>
</ednote>
- <p>Assertion authors need to be clear about how assertions defined in
+ <p>Assertion Authors need to be clear about how assertions defined in
their domain may fit with assertions for interrelated domains. A
classic example of such an interrelated domain is security, because
security tends to
@@ -1401,7 +1401,7 @@
related to the interrelated security domain [<bibref ref="WS-SecurityPolicy"/>] in
Web Services Reliable Messaging Policy
Assertions [<bibref ref="WS-RM-Policy"/>]. </p>
- <p>Assertion authors should not duplicate existing
+ <p>Assertion Authors should not duplicate existing
assertions and should also make sure that when adding assertions those new assertions are consistent
with pre-existing assertions of any
interrelated domain. </p>
@@ -1452,7 +1452,7 @@
the identification mechanism defined in the Policy specification to
expose a complex policy expression as a reusable building block for
other policy expressions by reference. Reuse may also be useful for
- domain assertion authors, especially those defining complex assertions
+ domain Assertion Authors, especially those defining complex assertions
utilizing references to policy expressions by nesting. Statically
available parameterized content may also be reused by different
assertions. However, such referencing mechanism is outside the scope of
@@ -1473,7 +1473,7 @@
behaviors can be modeled as independent assertions. </p>
<p role="practice" id="bp-independent-assertions">
<quote>Use Independent Assertions for Multiple Versions of a Behavior</quote>
- <quote>An assertion author should use independent assertions for modeling multiple
+ <quote>Assertion Authors should use independent assertions for modeling multiple
versions of a behavior.</quote></p>
<p>The
@@ -1500,7 +1500,7 @@
The <loc href="#bp-assertion-specification-parts">Best Practice: Parts of an Assertion Specification</loc> specifies that policy authors should
define the set of policy subjects to which policy assertions can be
attached. Over time, new policy subjects may need to be defined. When
- this occurs, a policy assertion author may update the list of policy
+ this occurs, policy Assertion Authors may update the list of policy
subjects supported by an assertion.
</p>
<p>
@@ -2596,7 +2596,15 @@
<td>Implemented Resolution for <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4573">issue 4573</loc>.
Apply "Best Practices" consistently.
</td>
- </tr>
+ </tr>
+ <tr>
+ <td>20070529</td>
+ <td>PY</td>
+ <td>Implemented Resolution in Editors' action
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/290">290</loc>.
+ Consistent use of Assertion Authors.
+ </td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Tuesday, 29 May 2007 22:45:24 UTC