- From: Frederick Hirsch via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 18 Jul 2007 22:44:06 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv18739
Modified Files:
ws-policy-guidelines.html ws-policy-guidelines.xml
Log Message:
Implemented the resolution for issue 4862 Editors' actio 348.
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.88
retrieving revision 1.89
diff -u -d -r1.88 -r1.89
--- ws-policy-guidelines.html 18 Jul 2007 16:42:54 -0000 1.88
+++ ws-policy-guidelines.html 18 Jul 2007 22:44:03 -0000 1.89
@@ -136,10 +136,10 @@
5.4.1 <a href="#parameterized-assertions">Assertions with Parameters</a><br>
5.4.2 <a href="#nested-assertions">Nested Assertions</a><br>
5.5 <a href="#Ignorable">Designating Ignorable Behavior</a><br>
- 5.5.1 <a href="#d3e795">Ignorable behavior in authoring</a><br>
- 5.5.2 <a href="#d3e808">Ignorable behavior at runtime</a><br>
+ 5.5.1 <a href="#d3e797">Ignorable behavior in authoring</a><br>
+ 5.5.2 <a href="#d3e810">Ignorable behavior at runtime</a><br>
5.6 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br>
- 5.6.1 <a href="#d3e823">Optional behavior at runtime</a><br>
+ 5.6.1 <a href="#d3e825">Optional behavior at runtime</a><br>
5.7 <a href="#levels-of-abstraction">Considerations for Policy Attachment in WSDL </a><br>
5.8 <a href="#interrelated-domains">Interrelated domains</a><br>
6. <a href="#versioning-policy-assertions">Versioning Policy Assertions</a><br>
@@ -201,7 +201,7 @@
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-assertion-semantics"><b>1. Semantics Independent of
- Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-compatibility-tests"><b>2. Behaviors Relevant to Compatibility Tests</b></a></p></li><li><p><a href="#bp-ignorable-for-not-related-to-compatibility-tests"><b>3. Mark Ignorable Assertions not related to compatibility</b></a></p></li><li><p><a href="#bp-semantics-and-form"><b>4. Semantics Independent of the Form</b></a></p></li><li><p><a href="#bp-assertion-start"><b>5. Start with a Simple Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>6. Use Unique QNames</b></a></p></li><li><p><a href="#XMLOutline"><b>7. Provide an XML Outline</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>8. Specify Semantics Clearly</b></a></p></li><li><p><a href="#DefineIgnorable"><b>9. Assertion Authors Should Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>10. Assertion Authors Should Document Use of the Ignorable
+ Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-compatibility-tests"><b>2. Behaviors Relevant to Compatibility Tests</b></a></p></li><li><p><a href="#bp-ignorable-for-not-related-to-compatibility-tests"><b>3. Mark Ignorable Assertions not related to compatibility</b></a></p></li><li><p><a href="#bp-semantics-and-form"><b>4. Semantics Independent of the Form</b></a></p></li><li><p><a href="#bp-assertion-start"><b>5. Start with a Simple Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>6. Use Unique QNames</b></a></p></li><li><p><a href="#XMLOutline"><b>7. Provide an XML definition</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>8. Specify Semantics Clearly</b></a></p></li><li><p><a href="#DefineIgnorable"><b>9. Assertion Authors Should Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>10. Assertion Authors Should Document Use of the Ignorable
Attribute in XML </b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>11. Assertion Authors should allow use of wsp:Optional
attribute</b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>12. Not Necessary to Understand a Message</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>13. Avoid Duplication of Assertions</b></a></p></li><li><p><a href="#bp-assertion-parameters"><b>14. Use Parameters for Useful
Information</b></a></p></li><li><p><a href="#bp-dependent-behaviors"><b>15. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>16. Enumerate Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>17. Discourage Domain Specific Intersection</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>18. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>19. Consider entire message exchange pattern when specifying Assertions that may be optional</b></a></p></li><li><p><a href="#bp-indicate-optional-assertion-use"><b>20. Indicate use of an Optional Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>21. Specify Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>22. Choose the Most Granular Policy Subject</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>23. Define Semantics f Attachment to Multiple Policy Subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>24. Specify Preferred Attachment Point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>25. Describe Semantics of Multiple Assertions of Same Type</b></a></p></li><li><p><a href="#bp-specify-composition"><b>26. Specify Composition with Related Assertions</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>27. Use Independent Assertions for Different Versions of a Behavior</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>28. Change of the Policy Subject Over Time</b></a></p></li></ul></div><div class="div1">
@@ -209,7 +209,7 @@
capability related to a specific WS-Policy domain. 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.
+ as their data type definition using XML Schema [<cite><a href="#XMLSchemaPart1">XML Schema Structures</a></cite>].
</p><p>Policy assertions representing shared and visible behaviors are useful pieces of metadata to enable
interoperability and tooling for automation. The key to understanding when to
design policy assertions is to have clarity on the characteristics of a behavior
@@ -552,9 +552,14 @@
or an attribute of an assertion. The general guidelines on when to use XML elements
versus attributes apply. Use a unique QName to identify a distinct behavior.</p><div class="boxedtext"><p><a name="bp-unique-qnames" id="bp-unique-qnames"></a><span class="practicelab">Best
Practice 6: Use Unique QNames</span></p><p class="practice">Assertion Authors should use a unique QName to identify a distinct behavior.</p></div><div class="boxedtext"><p><a name="XMLOutline" id="XMLOutline"></a><span class="practicelab">Best
-Practice 7: Provide an XML Outline</span></p><p class="practice">Assertion authors should provide an XML outline plus an XML schema to
- specify the syntax of an assertion.
- </p></div><p> An example of this method (below) is given in the Web Services Reliable Messaging Policy document. [<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite>]
+Practice 7: Provide an XML definition</span></p><p class="practice">Assertion authors should provide an XML schema definition to
+ specify the syntax of an assertion. A reader-friendly description such as an
+ XML outline (see below) is also useful.
+ </p></div><p> An example of a specification that provides an XML Outline is the Web Services
+ Reliable Messaging Policy document [<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite>].
+ The definition of the outline syntax used in that specification is found in its
+ Terminology section (1.1). As an example of the outline syntax in use, the
+ following outline has been copied from the aforementioned specification.
</p><div class="exampleOuter"><div class="exampleInner"><pre>
<wsrmp:RMAssertion [wsp:Optional="true"]? ...>
<wsp:Policy >
@@ -851,16 +856,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="d3e795" id="d3e795"></a>5.5.1 Ignorable behavior in authoring</h4><p>
+<h4><a name="d3e797" id="d3e797"></a>5.5.1 Ignorable behavior in authoring</h4><p>
The Policy Framework provides an intersection algorithm that has two defined modes for processing (lax and strict). The Framework also defines an attribute (wsp:Ignorable) that can be used to influence whether assertions are part of the compatability assessment between two alternatives. [see <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite> and <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite>]. Assertion authors should consider whether the behavior represented by the Assertion they are defining can be safely ignored for the purposes of intersection, and should follow <a href="#DefineIgnorable"><b>9. Assertion Authors Should Document Ignorable Behavior</b></a> and <a href="#ignorableAssertions"><b>10. Assertion Authors Should Document Use of the Ignorable
Attribute in XML </b></a> to include this guidance in the assertion's definition.</p></div><div class="div3">
-<h4><a name="d3e808" id="d3e808"></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="d3e810" id="d3e810"></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="d3e823" id="d3e823"></a>5.6.1 Optional behavior at runtime</h4><table border="1" summary="Editorial note"><tr><td align="left" valign="top" width="50%"><b>Editorial note</b></td><td align="right" valign="top" width="50%"> </td></tr><tr><td colspan="2" align="left" valign="top">This section does not have Working Group consensus and there is an outstanding action item to revise it</td></tr></table><p>Since optional behaviors indicate optionality for
+<h4><a name="d3e825" id="d3e825"></a>5.6.1 Optional behavior at runtime</h4><table border="1" summary="Editorial note"><tr><td align="left" valign="top" width="50%"><b>Editorial note</b></td><td align="right" valign="top" width="50%"> </td></tr><tr><td colspan="2" align="left" valign="top">This section does not have Working Group consensus and there is an outstanding action item to revise it</td></tr></table><p>Since optional behaviors indicate optionality for
both the provider and the consumer, behaviors that must
always be engaged by a consumer must not be marked as
"optional" with a value "true" since this would allow the
@@ -1275,7 +1280,24 @@
</dd><dt class="label"><a name="SAWSDL"></a>[SAWSDL] </dt><dd>
<cite><a href="http://www.w3.org/TR/sawsdl/">Semantic Annotations for WSDL and XML Schema</a></cite> Joel Farrell, Holger Lausen, Editors. World Wide Web Consortium, 26 January 2007. This version of the
specification is at http://www.w3.org/TR/sawsdl. The <a href="http://www.w3.org/TR/sawsdl/"> latest version of Semantic Annotations for WSDL and XML Schema</a> is available at
- http://www.w3.org/TR/sawsdl/.</dd></dl></div><div class="div1">
+ http://www.w3.org/TR/sawsdl/.</dd><dt class="label"><a name="XMLSchemaPart2"></a>[XML Schema Datatypes] </dt><dd>
+ <cite><a href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/">XML Schema Part 2: Datatypes Second
+ Edition</a></cite>, P. Byron and A. Malhotra, Editors. World
+ Wide Web Consortium, 2 May 2001, revised 28 October 2004. This
+ version of the XML Schema Part 2 Recommendation is
+ http://www.w3.org/TR/2004/REC-xmlschema-2-20041028. The <a href="http://www.w3.org/TR/xmlschema-2/">latest version of XML
+ Schema Part 2</a> is available at
+ http://www.w3.org/TR/xmlschema-2.
+ </dd><dt class="label"><a name="XMLSchemaPart1"></a>[XML Schema Structures] </dt><dd>
+ <cite><a href="http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/">XML Schema Part 1: Structures Second
+ Edition</a></cite>, H. Thompson, D. Beech, M. Maloney, and
+ N. Mendelsohn, Editors. World Wide Web Consortium, 2 May 2001,
+ revised 28 October 2004. This version of the XML Schema Part 1
+ Recommendation is
+ http://www.w3.org/TR/2004/REC-xmlschema-1-20041028. The <a href="http://www.w3.org/TR/xmlschema-1/">latest version of XML
+ Schema Part 1</a> is available at
+ http://www.w3.org/TR/xmlschema-1.
+ </dd></dl></div><div class="div1">
<h2><a name="acknowledgments" id="acknowledgments"></a>D. Acknowledgements (Non-Normative)</h2><p>This document is the work of the <a href="http://www.w3.org/2002/ws/policy/">W3C Web Services Policy
Working Group</a>.</p><p>
Members of the Working Group are (at the time of writing, and by
@@ -1539,4 +1561,7 @@
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/343">343</a>. </td></tr><tr><td rowspan="1" colspan="1">20070718</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Implemented the resolution
for issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4566">4566</a>.
Editors' action:
- <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/249">249</a>, <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/328">328</a>. </td></tr></tbody></table><br></div></div></body></html>
\ No newline at end of file
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/249">249</a>, <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/328">328</a>. </td></tr><tr><td rowspan="1" colspan="1">20070718</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=4862">4862</a>.
+ Editors' action:
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/348">348</a>. </td></tr></tbody></table><br></div></div></body></html>
\ No newline at end of file
Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.103
retrieving revision 1.104
diff -u -d -r1.103 -r1.104
--- ws-policy-guidelines.xml 18 Jul 2007 16:42:53 -0000 1.103
+++ ws-policy-guidelines.xml 18 Jul 2007 22:44:03 -0000 1.104
@@ -161,7 +161,7 @@
capability related to a specific WS-Policy domain. 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.
+ as their data type definition using XML Schema [<bibref ref="XMLSchemaPart1" />].
</p>
<p>Policy assertions representing shared and visible behaviors are useful pieces of metadata to enable
@@ -662,12 +662,21 @@
<p role="practice" id="bp-unique-qnames"><quote>Use Unique QNames</quote>
<quote>Assertion Authors should use a unique QName to identify a distinct behavior.</quote> </p>
- <p role="practice" id="XMLOutline"> <quote>Provide an XML Outline</quote> >
- <quote>Assertion authors should provide an XML outline plus an XML schema to
- specify the syntax of an assertion.
+
+
+
+
+ <p role="practice" id="XMLOutline"> <quote>Provide an XML definition</quote> >
+ <quote>Assertion authors should provide an XML schema definition to
+ specify the syntax of an assertion. A reader-friendly description such as an
+ XML outline (see below) is also useful.
</quote>
</p>
- <p> An example of this method (below) is given in the Web Services Reliable Messaging Policy document. [<bibref ref="WS-RM-Policy"/>]
+ <p> An example of a specification that provides an XML Outline is the Web Services
+ Reliable Messaging Policy document [<bibref ref="WS-RM-Policy" />].
+ The definition of the outline syntax used in that specification is found in its
+ Terminology section (1.1). As an example of the outline syntax in use, the
+ following outline has been copied from the aforementioned specification.
</p>
<example>
<eg>
@@ -1774,6 +1783,25 @@
<titleref>Semantic Annotations for WSDL and XML Schema</titleref> Joel Farrell, Holger Lausen, Editors. World Wide Web Consortium, 26 January 2007. This version of the
specification is at http://www.w3.org/TR/sawsdl. The <loc href="http://www.w3.org/TR/sawsdl/"> latest version of Semantic Annotations for WSDL and XML Schema</loc> is available at
http://www.w3.org/TR/sawsdl/.</bibl>
+ <bibl key="XML Schema Datatypes" id="XMLSchemaPart2" href="http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/">
+ <titleref>XML Schema Part 2: Datatypes Second
+ Edition</titleref>, P. Byron and A. Malhotra, Editors. World
+ Wide Web Consortium, 2 May 2001, revised 28 October 2004. This
+ version of the XML Schema Part 2 Recommendation is
+ http://www.w3.org/TR/2004/REC-xmlschema-2-20041028. The <loc href="http://www.w3.org/TR/xmlschema-2/">latest version of XML
+ Schema Part 2</loc> is available at
+ http://www.w3.org/TR/xmlschema-2.
+ </bibl>
+ <bibl id="XMLSchemaPart1" key="XML Schema Structures" href="http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/">
+ <titleref>XML Schema Part 1: Structures Second
+ Edition</titleref>, H. Thompson, D. Beech, M. Maloney, and
+ N. Mendelsohn, Editors. World Wide Web Consortium, 2 May 2001,
+ revised 28 October 2004. This version of the XML Schema Part 1
+ Recommendation is
+ http://www.w3.org/TR/2004/REC-xmlschema-1-20041028. The <loc href="http://www.w3.org/TR/xmlschema-1/">latest version of XML
+ Schema Part 1</loc> is available at
+ http://www.w3.org/TR/xmlschema-1.
+ </bibl>
</blist>
</div1>&acknowledgements; <inform-div1 id="change-description">
<head>Changes in this Version of the Document</head>
@@ -2510,7 +2538,15 @@
for issue <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4566">4566</loc>.
Editors' action:
<loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/249">249</loc>, <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/328">328</loc>. </td>
-</tr>
+</tr>
+ <tr>
+ <td>20070718</td>
+ <td>FJH</td>
+ <td>Implemented the resolution
+ for issue <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4862">4862</loc>.
+ Editors' action:
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/348">348</loc>. </td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Wednesday, 18 July 2007 22:44:09 UTC