- From: Felix Sasaki via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 05 Apr 2007 13:04:56 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv24434/policy
Modified Files:
build.xml ws-policy-guidelines.html ws-policy-guidelines.xml
xmlspec-policy.xsl
Added Files:
generateBPlist.xsl guidelines-bestpractices.xml
Log Message:
AI 223 and 224 done, see http://lists.w3.org/Archives/Public/public-ws-policy-eds/2007Apr/0012.html .
Index: build.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/build.xml,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -d -r1.27 -r1.28
--- build.xml 27 Mar 2007 01:01:33 -0000 1.27
+++ build.xml 5 Apr 2007 13:04:53 -0000 1.28
@@ -9,6 +9,7 @@
<property name="htmlOutputDir" value=""/>
<property name="stylesheet" value="xmlspec-policy.xsl"/>
<property name="glossary" value="extract-glist.xsl"/>
+ <property name="generateBPlist" value="generateBPlist.xsl"/>
<property name="diffformat" value="diffspec.xsl"/>
<property name="last-public-draft" value="20070228"/>
<property name="primer-last-public-draft" value="20061221"/>
@@ -68,7 +69,7 @@
</target>
<target name="html" description="Transforms xml into html.">
- <java fork="true" classname="net.sf.saxon.Transform">
+ <java fork="true" classname="net.sf.saxon.Transform">
<classpath refid="saxon8.classpath"/>
<arg value="-o"/>
<arg value="${htmlOutputDir}ws-policy-framework.html"/>
@@ -89,6 +90,13 @@
<arg value="ws-policy-primer.xml"/>
<arg value="${stylesheet}"/>
</java>
+ <java fork="true" classname="net.sf.saxon.Transform">
+ <classpath refid="saxon8.classpath"/>
+ <arg value="-o"/>
+ <arg value="guidelines-bestpractices.xml"/>
+ <arg value="ws-policy-guidelines.xml"/>
+ <arg value="${generateBPlist}"/>
+ </java>
<java fork="true" classname="net.sf.saxon.Transform">
<classpath refid="saxon8.classpath"/>
<arg value="-o"/>
@@ -96,7 +104,7 @@
<arg value="ws-policy-guidelines.xml"/>
<arg value="${stylesheet}"/>
</java>
- <java fork="true" classname="net.sf.saxon.Transform">
+ <java fork="true" classname="net.sf.saxon.Transform">
<classpath refid="saxon8.classpath"/>
<arg value="-o"/>
<arg value="${htmlOutputDir}wsdl11elementidentifiers.html"/>
@@ -121,7 +129,7 @@
<arg value="${glossary}"/>
</java>
</target>
-
+
<path id="diffmk.classpath">
<pathelement location="${basedir}/diffmk.jar"/>
<pathelement location="${basedir}/DiffMk.properties"/>
--- NEW FILE: guidelines-bestpractices.xml ---
<?xml version="1.0" encoding="UTF-8"?><olist><item><p><loc href="#bp-assertion-specification-parts">Parts of an Assertion Specification</loc></p></item><item><p><loc href="#bp-assertion-semantics">Semantics of Policy Assertions</loc></p></item><item><p><loc href="#bp-semantics-and-form">Semantics of an Assertion and its form</loc></p></item><item><p><loc href="#bp-assertion-start">Starting to Build an Assertion</loc></p></item><item><p><loc href="#bp-unique-qnames">Unique QNames</loc></p></item><item><p><loc href="#bp-assertions-and-message-semantics">Assertions and Message Semantics</loc></p></item><item><p><loc href="#bp-assertion-duplication">Duplication of Assertions</loc></p></item><item><p><loc href="#bp-assertion-definition">Definition of Policy Assertions</loc></p></item><item><p><loc href="#bp-nesting">Nesting of Assertions</loc></p></item><item><p><loc href="#bp-optional-assertions">Optional Assertions</loc></p></item><item><p><loc href="#bp-independent-assertions">Independent Assertions</loc></p>/item><item><p><loc href="#bp-assertion-description">Description of Assertions</loc></p></item><item><p><loc href="#bp-tbd">Change of the Policy Subject Over Time</loc></p></item></olist>
Index: xmlspec-policy.xsl
===================================================================
RCS file: /sources/public/2006/ws/policy/xmlspec-policy.xsl,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- xmlspec-policy.xsl 21 Feb 2007 15:40:43 -0000 1.6
+++ xmlspec-policy.xsl 5 Apr 2007 13:04:53 -0000 1.7
@@ -182,8 +182,10 @@
</xsl:analyze-string>
</xsl:when>
<xsl:when test="self::emph">
- <b><xsl:copy-of select="*|text()"/></b>
- </xsl:when>
+ <b>
+ <xsl:copy-of select="*|text()"/>
+ </b>
+ </xsl:when>
<xsl:otherwise>
<xsl:copy-of select="."/>
</xsl:otherwise>
@@ -195,8 +197,7 @@
</xsl:template>
<xsl:template match="lb" mode="addLineNumbers">
<xsl:choose>
- <xsl:when
- test="not(contains(self::lb/following-sibling::text()[1],'xmlns'))">
+ <xsl:when test="not(contains(self::lb/following-sibling::text()[1],'xmlns'))">
<xsl:text>(</xsl:text>
<xsl:number format="01"
count="lb[not(contains(self::lb/following-sibling::text()[1],'xmlns'))]"/>
@@ -208,9 +209,167 @@
<xsl:copy-of select="."/>
</xsl:template>
-<!-- Used for wsdl11elementidentifiers.xml to allow italics within
+ <!-- Used for wsdl11elementidentifiers.xml to allow italics within
code -->
-<xsl:template match="code[@role='code-emph']">
-<code style="font-style: italic;"><xsl:value-of select="."/></code>
-</xsl:template>
+ <xsl:template match="code[@role='code-emph']">
+ <code style="font-style: italic;">
+ <xsl:value-of select="."/>
+ </code>
+ </xsl:template>
+<!-- Template for Best practices output, used only for guidelines document.-->
+ <xsl:template match="p[@role='practice']">
+ <xsl:variable name="practicenumber">
+ <xsl:number count="p[@role='practice']" level="any"/>
+ </xsl:variable>
+ <div class="boxedtext">
+ <p>
+ <a name="{@id}" id="{@id}"/>
+ <span class="practicelab">
+ <xsl:text>Good
+practice </xsl:text>
+ <xsl:value-of select="$practicenumber"/>
+ <xsl:text>: </xsl:text>
+ <xsl:value-of select="quote[1]"/>
+ </span>
+ </p>
+ <p class="practice">
+ <xsl:value-of select="quote[2]"/>
+ </p>
+ </div>
+ </xsl:template>
+ <xsl:template name="css">
+ <style type="text/css">
+ <xsl:text>
+code { font-family: monospace; }
+
+div.constraint,
+div.issue,
+div.note,
+div.notice { margin-left: 2em; }
+
+ol.enumar { list-style-type: decimal; }
+ol.enumla { list-style-type: lower-alpha; }
+ol.enumlr { list-style-type: lower-roman; }
+ol.enumua { list-style-type: upper-alpha; }
+ol.enumur { list-style-type: upper-roman; }
+
+dt.label { display: run-in; }
+
+li, p { margin-top: 0.3em;
+ margin-bottom: 0.3em; }
+
+.diff-chg { background-color: yellow; }
+.diff-del { background-color: red; text-decoration: line-through;}
+.diff-add { background-color: lime; }
+
+table { empty-cells: show; }
+
+table caption {
+ font-weight: normal;
+ font-style: italic;
+ text-align: left;
+ margin-bottom: .5em;
+}
+
+div.issue {
+ color: red;
+}
+.rfc2119 {
+ font-variant: small-caps;
+}
+
+
+
+.boxedtext {
+ border: solid #bebebe 1px;
+ margin: 2em 1em 1em 2em;
+ }
+
+.principle, .practice, .constraint, .property, div.story {
+ margin: 1.5em 0.5em 1em 1em;
+ }
+
+.principlelab, .constraintlab,
+.propertylab, .practicelab,
+.storylab {
+ margin: 1.5em 0.5em 1em 1em;
+ font-weight: bold;
+ font-style: italic;
+ }
+
+.principlelab { background: #f7ebd7 }
+.constraintlab { background: #becece }
+.propertylab { background: #f7ebd7 }
+.practicelab { background: #dfffff }
+.storylab { background: #005a9c; color: #fff; }
+
+/* Make sure the relative spacing stuff only applies to 'screen'
+ because IE has bugs when it comes to printing relative things. */
+
+@media screen {
+
+.principle, .practice, .constraint, .property, div.story {
+ position: relative;
+ top: -2em;
+ padding: 0;
+ margin: 1.5em 0.5em -1em 1em;
+}
+
+.principlelab, .constraintlab,
+.propertylab, .practicelab,
+.storylab {
+ position: relative;
+ padding: 0 0.5em;
+ top: -1.5em;
+ }
+</xsl:text>
+ <xsl:if test="$tabular.examples = 0">
+ <xsl:text>
+div.exampleInner pre { margin-left: 1em;
+ margin-top: 0em; margin-bottom: 0em}
+div.exampleOuter {border: 4px double gray;
+ margin: 0em; padding: 0em}
+div.exampleInner { background-color: #d5dee3;
+ border-top-width: 4px;
+ border-top-style: double;
+ border-top-color: #d3d3d3;
+ border-bottom-width: 4px;
+ border-bottom-style: double;
+ border-bottom-color: #d3d3d3;
+ padding: 4px; margin: 0em }
+div.exampleWrapper { margin: 4px }
+div.exampleHeader { font-weight: bold;
+ margin: 4px}
+</xsl:text>
+ </xsl:if>
+ <xsl:value-of select="$additional.css"/>
+ </style>
+ <link rel="stylesheet" type="text/css">
+ <xsl:attribute name="href">
+ <xsl:text>http://www.w3.org/StyleSheets/TR/</xsl:text>
+ <xsl:choose>
+ <xsl:when test="/spec/@role='editors-copy'">base</xsl:when>
+ <xsl:otherwise>
+ <xsl:choose>
+ <!-- Editor's review drafts are a special case. -->
+ <xsl:when test="/spec/@w3c-doctype='review'
+ or contains(/spec/header/w3c-doctype, 'Editor')"
+ >base</xsl:when>
+ <xsl:when test="/spec/@w3c-doctype='wd'">W3C-WD</xsl:when>
+ <xsl:when test="/spec/@w3c-doctype='rec'">W3C-REC</xsl:when>
+ <xsl:when test="/spec/@w3c-doctype='pr'">W3C-PR</xsl:when>
+ <xsl:when test="/spec/@w3c-doctype='per'">W3C-PER</xsl:when>
+ <xsl:when test="/spec/@w3c-doctype='cr'">W3C-CR</xsl:when>
+ <xsl:when test="/spec/@w3c-doctype='note'">W3C-NOTE</xsl:when>
+ <xsl:when test="/spec/@w3c-doctype='wgnote'">W3C-WG-NOTE</xsl:when>
+ <xsl:when test="/spec/@w3c-doctype='memsub'">W3C-Member-SUBM</xsl:when>
+ <xsl:when test="/spec/@w3c-doctype='teamsub'">W3C-Team-SUBM</xsl:when>
+ <xsl:otherwise>base</xsl:otherwise>
+ </xsl:choose>
+ </xsl:otherwise>
+ </xsl:choose>
+ <xsl:text>.css</xsl:text>
+ </xsl:attribute>
+ </link>
+ </xsl:template>
</xsl:stylesheet>
--- NEW FILE: generateBPlist.xsl ---
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0">
<xsl:template match="/">
<olist>
<xsl:for-each select="//p[@role='practice']">
<item>
<p>
<loc href="{concat('#',@id)}">
<xsl:value-of select="quote[1]"/>
</loc>
</p>
</item>
</xsl:for-each>
</olist>
</xsl:template>
</xsl:stylesheet>
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -d -r1.38 -r1.39
--- ws-policy-guidelines.html 29 Mar 2007 22:25:43 -0000 1.38
+++ ws-policy-guidelines.html 5 Apr 2007 13:04:53 -0000 1.39
@@ -39,6 +39,51 @@
font-variant: small-caps;
}
+
+
+.boxedtext {
+ border: solid #bebebe 1px;
+ margin: 2em 1em 1em 2em;
+ }
+
+.principle, .practice, .constraint, .property, div.story {
+ margin: 1.5em 0.5em 1em 1em;
+ }
+
+.principlelab, .constraintlab,
+.propertylab, .practicelab,
+.storylab {
+ margin: 1.5em 0.5em 1em 1em;
+ font-weight: bold;
+ font-style: italic;
+ }
+
+.principlelab { background: #f7ebd7 }
+.constraintlab { background: #becece }
+.propertylab { background: #f7ebd7 }
+.practicelab { background: #dfffff }
+.storylab { background: #005a9c; color: #fff; }
+
+/* Make sure the relative spacing stuff only applies to 'screen'
+ because IE has bugs when it comes to printing relative things. */
+
+@media screen {
+
+.principle, .practice, .constraint, .property, div.story {
+ position: relative;
+ top: -2em;
+ padding: 0;
+ margin: 1.5em 0.5em -1em 1em;
+}
+
+.principlelab, .constraintlab,
+.propertylab, .practicelab,
+.storylab {
+ position: relative;
+ padding: 0 0.5em;
+ top: -1.5em;
+ }
+
div.exampleInner pre { margin-left: 1em;
margin-top: 0em; margin-bottom: 0em}
div.exampleOuter {border: 4px double gray;
@@ -72,39 +117,40 @@
<h2><a name="status" id="status"></a>Status of this Document</h2><p><strong>This document is an editors' copy that has
no official standing.</strong></p><p></p></div><div class="toc">
<h2><a name="contents" id="contents"></a>Table of Contents</h2><p class="toc">1. <a href="#introduction">Introduction</a><br>
-2. <a href="#Assertions">What is an Assertion? </a><br>
-3. <a href="#d3e173">Who is involved in authoring Assertions? </a><br>
- 3.1 <a href="#roles"> Roles and Responsibilities </a><br>
- 3.1.1 <a href="#domain-owners"> Assertion Authors</a><br>
- 3.1.2 <a href="#consumers">Consumers</a><br>
- 3.1.3 <a href="#providers">Providers</a><br>
-4. <a href="#general-guidelines">General Guidelines for Assertion Authors</a><br>
- 4.1 <a href="#assertion-target">Assertions and Their Target Use</a><br>
- 4.2 <a href="#compact-full">Authoring Styles </a><br>
- 4.3 <a href="#new-guidelines-domains">Considerations when Modeling New Assertions</a><br>
- 4.3.1 <a href="#minimal-approach">Minimal approach</a><br>
- 4.3.2 <a href="#QName_and_XML_Information_Set_representation">QName and XML Information Set representation</a><br>
- 4.3.3 <a href="#self-describing"> Self Describing Messages </a><br>
- 4.3.4 <a href="#single-domains">Single Domains</a><br>
- 4.4 <a href="#comparison">Comparison of Nested and Parameterized Assertions</a><br>
- 4.4.1 <a href="#parameterized-assertions">Assertions with Parameters</a><br>
- 4.4.2 <a href="#nested-assertions">Nested Assertions</a><br>
- 4.4.3 <a href="#which-one-to-use">Considerations for choosing parameters vs nesting</a><br>
- 4.5 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br>
- 4.5.1 <a href="#d3e552">Optional behavior in Compact authoring</a><br>
- 4.5.2 <a href="#d3e560">Optional behavior at runtime</a><br>
- 4.6 <a href="#levels-of-abstraction">Levels of Abstraction in WSDL </a><br>
- 4.7 <a href="#interrelated-domains">Interrelated domains</a><br>
-5. <a href="#versioning-policy-assertions">Versioning Policy Assertions</a><br>
- 5.1 <a href="#Referencing_Policy_Expressions">Referencing Policy Expressions</a><br>
- 5.2 <a href="#extending-assertions"> Evolution of Assertions (Versioning and Compatibility)</a><br>
- 5.3 <a href="#supporting-new-policy-subjects">Supporting New Policy Subjects</a><br>
-6. <a href="#best-practices-attachment">Applying Best Practices for Policy Attachment</a><br>
- 6.1 <a href="#context-free-policies">Appropriate Attachment: Preserving Context-Free Policies</a><br>
- 6.2 <a href="#appropriate-attachment-assertion-subjects">Appropriate Attachment: Identifying Assertion Subjects</a><br>
- 6.2.1 <a href="#interaction">Interaction between Subjects</a><br>
- 6.3 <a href="#identifying-assertion-sources">Appropriate Attachment: Identifying Assertion Sources </a><br>
-7. <a href="#scenario">Scenario and a worked example</a><br>
+2. <a href="#best-practices-list">List of Best Practices Statements</a><br>
+3. <a href="#Assertions">What is an Assertion? </a><br>
+4. <a href="#d3e232">Who is involved in authoring Assertions? </a><br>
+ 4.1 <a href="#roles"> Roles and Responsibilities </a><br>
+ 4.1.1 <a href="#domain-owners"> Assertion Authors</a><br>
+ 4.1.2 <a href="#consumers">Consumers</a><br>
+ 4.1.3 <a href="#providers">Providers</a><br>
+5. <a href="#general-guidelines">General Guidelines for Assertion Authors</a><br>
+ 5.1 <a href="#assertion-target">Assertions and Their Target Use</a><br>
+ 5.2 <a href="#compact-full">Authoring Styles </a><br>
+ 5.3 <a href="#new-guidelines-domains">Considerations when Modeling New Assertions</a><br>
+ 5.3.1 <a href="#minimal-approach">Minimal approach</a><br>
+ 5.3.2 <a href="#QName_and_XML_Information_Set_representation">QName and XML Information Set representation</a><br>
+ 5.3.3 <a href="#self-describing"> Self Describing Messages </a><br>
+ 5.3.4 <a href="#single-domains">Single Domains</a><br>
+ 5.4 <a href="#comparison">Comparison of Nested and Parameterized Assertions</a><br>
+ 5.4.1 <a href="#parameterized-assertions">Assertions with Parameters</a><br>
+ 5.4.2 <a href="#nested-assertions">Nested Assertions</a><br>
+ 5.4.3 <a href="#which-one-to-use">Considerations for choosing parameters vs nesting</a><br>
+ 5.5 <a href="#optional-policy-assertion">Designating Optional Behaviors</a><br>
+ 5.5.1 <a href="#d3e646">Optional behavior in Compact authoring</a><br>
+ 5.5.2 <a href="#d3e654">Optional behavior at runtime</a><br>
+ 5.6 <a href="#levels-of-abstraction">Levels of Abstraction in WSDL </a><br>
+ 5.7 <a href="#interrelated-domains">Interrelated domains</a><br>
+6. <a href="#versioning-policy-assertions">Versioning Policy Assertions</a><br>
+ 6.1 <a href="#Referencing_Policy_Expressions">Referencing Policy Expressions</a><br>
+ 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>
+7. <a href="#best-practices-attachment">Applying Best Practices for Policy Attachment</a><br>
+ 7.1 <a href="#context-free-policies">Appropriate Attachment: Preserving Context-Free Policies</a><br>
+ 7.2 <a href="#appropriate-attachment-assertion-subjects">Appropriate Attachment: Identifying Assertion Subjects</a><br>
+ 7.2.1 <a href="#interaction">Interaction between Subjects</a><br>
+ 7.3 <a href="#identifying-assertion-sources">Appropriate Attachment: Identifying Assertion Sources </a><br>
+8. <a href="#scenario">Scenario and a worked example</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>
@@ -160,7 +206,8 @@
the Socratic style of beginning with a question, and then answering
the question.
</p></div><div class="div1">
-<h2><a name="Assertions" id="Assertions"></a>2. What is an Assertion? </h2><p>An assertion is a piece of metadata that describes a
+<h2><a name="best-practices-list" id="best-practices-list"></a>2. List of Best Practices Statements</h2><p>TBD:</p><ol class="enumar"><li><p><a href="#bp-assertion-specification-parts">Parts of an Assertion Specification</a></p></li><li><p><a href="#bp-assertion-semantics">Semantics of Policy Assertions</a></p></li><li><p><a href="#bp-semantics-and-form">Semantics of an Assertion and its form</a></p></li><li><p><a href="#bp-assertion-start">Starting to Build an Assertion</a></p></li><li><p><a href="#bp-unique-qnames">Unique QNames</a></p></li><li><p><a href="#bp-assertions-and-message-semantics">Assertions and Message Semantics</a></p></li><li><p><a href="#bp-assertion-duplication">Duplication of Assertions</a></p></li><li><p><a href="#bp-assertion-definition">Definition of Policy Assertions</a></p></li><li><p><a href="#bp-nesting">Nesting of Assertions</a></p></li><li><p><a href="#bp-optional-assertions">Optional Assertions</a></p></li><li><p><a href="#bp-independent-assertions">Independent Assertions</a>/p></li><li><p><a href="#bp-assertion-description">Description of Assertions</a></p></li><li><p><a href="#bp-tbd">Change of the Policy Subject Over Time</a></p></li></ol></div><div class="div1">
+<h2><a name="Assertions" id="Assertions"></a>3. What is an Assertion? </h2><p>An assertion is a piece of metadata that describes a
capability related to a specific WS-Policy domain. Sets of domain-specific assertions
are typically defined in a dedicated specification that describes
their semantics, applicability and scoping requirements as well
@@ -218,7 +265,7 @@
best practices will be an assertion specification that describes
a contract for the consumers and providers of the capabilities and constraints of the domain.
</p></div><div class="div1">
-<h2><a name="d3e173" id="d3e173"></a>3. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
+<h2><a name="d3e232" id="d3e232"></a>4. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
express their own domain knowledge, it is necessary to provide basic
functionality that all domains could exploit and then allow
points of extension where authors of the various WS-Policy
@@ -230,10 +277,10 @@
privacy policy, QoS characteristics). WS-Policy provides a
single policy grammar to allow both kinds of assertions to be reasoned about in a consistent manner.
</p><div class="div2">
-<h3><a name="roles" id="roles"></a>3.1 Roles and Responsibilities </h3><p>Below we capture some of the characteristics of the roles
+<h3><a name="roles" id="roles"></a>4.1 Roles and Responsibilities </h3><p>Below we capture some of the characteristics of the roles
and responsibilities for the authors, consumers and providers.
</p><div class="div3">
-<h4><a name="domain-owners" id="domain-owners"></a>3.1.1 Assertion Authors</h4><p>Assertion Authors are a community that chooses to
+<h4><a name="domain-owners" id="domain-owners"></a>4.1.1 Assertion Authors</h4><p>Assertion Authors are a community that chooses to
exploit the WS-Policy Framework by creating their own
specification to define a set of assertions that express the
capabilities and constraints of that target domain. The
@@ -270,7 +317,7 @@
engage in a secure exchange of messages." </em>
</p><p>An example of scoping individual assertions to policy subjects is also provided by the WS-Security Policy specification in Appendix A.
</p></div><div class="div3">
-<h4><a name="consumers" id="consumers"></a>3.1.2 Consumers</h4><p>A consumer of WS-Policy
+<h4><a name="consumers" id="consumers"></a>4.1.2 Consumers</h4><p>A consumer of WS-Policy
Assertions can be any entity that is capable of parsing a
WS-Policy XML element and selecting one alternative from the
policy. This selected alternative is then used to govern the creation of a message
@@ -291,7 +338,7 @@
expressed in a WS-Policy document and modifying their own
configurations dynamically.
</p></div><div class="div3">
-<h4><a name="providers" id="providers"></a>3.1.3 Providers</h4><p>A provider who expresses capabilities and requirements of a Web service
+<h4><a name="providers" id="providers"></a>4.1.3 Providers</h4><p>A provider who expresses capabilities and requirements of a Web service
as policies can be any web service implementation that can
specify its on-the-wire message behavior as a policy
expression that conforms to the Web Services Policy 1.5 - Framework [<cite><a href="#WS-Policy">Web Services Policy Framework</a></cite>]
@@ -303,16 +350,16 @@
to evolve their services capabilities over time. If
forward compatibility is a concern in order to accommodate
compatibility with different and potentially new clients,
- providers should refer to <a href="#versioning-policy-assertions"><b>5. Versioning Policy Assertions</b></a> and
+ providers should refer to <a href="#versioning-policy-assertions"><b>6. Versioning Policy Assertions</b></a> and
<cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite> that describes service and
policy assertion evolution.
</p></div></div></div><div class="div1">
-<h2><a name="general-guidelines" id="general-guidelines"></a>4. General Guidelines for Assertion Authors</h2><p> As Assertion Authors begin the task of inventing XML dialects to represent policy assertions they can take
+<h2><a name="general-guidelines" id="general-guidelines"></a>5. General Guidelines for Assertion Authors</h2><p> As Assertion Authors begin the task of inventing XML dialects to represent policy assertions they can take
advantage of WS-Policy building on XML principles and XML Schema validation in their design. WS-Policy
relies on the QName of a policy assertion being an XML element but allows Assertion Authors to optionally
provide additional semantics through nesting assertions, or specifying assertion parameters.
This section covers several aspects of assertion design and provides some answers to the following questions:</p><ul><li><p>What is the intended use of the policy assertion?</p></li><li><p>Which authoring style will be used?</p></li><li><p>Is this a new policy domain? Does it need to compose with other domains?</p></li><li><p>How complex are the assertions?</p></li><li><p>Is there a need to consider nesting?</p></li><li><p>Do optional behaviors need to be represented?</p></li></ul><div class="div2">
-<h3><a name="assertion-target" id="assertion-target"></a>4.1 Assertions and Their Target Use</h3><p>
+<h3><a name="assertion-target" id="assertion-target"></a>5.1 Assertions and Their Target Use</h3><p>
Assertion Authors need to have a specific goal in mind for the assertions
that they author. Assertion Authors should also understand the
functionality that the WS-Policy framework provides and apply the
@@ -334,7 +381,7 @@
</p><p>
The WS-Policy Attachment specification defines a number of different
policy subjects to which an assertion can be attached. For attaching to
- WSDL subjects see <a href="#levels-of-abstraction"><b>4.6 Levels of Abstraction in WSDL </b></a> for more detail.
+ WSDL subjects see <a href="#levels-of-abstraction"><b>5.6 Levels of Abstraction in WSDL </b></a> for more detail.
Additionally, the framework provides for the means to extend the set of
policy subjects beyond the set of subjects defined in the WS-Policy
Attachment specification.
@@ -350,10 +397,10 @@
attachment mechanism. Independence from a specific attachment mechanism
allows policy tools to choose the most appropriate mechanism to attach a
policy without having to analyze the contents of the policy.
- </p><p class="practice">
+ </p><div class="boxedtext"><p><a name="bp-assertion-specification-parts" id="bp-assertion-specification-parts"></a><span class="practicelab">Good
+practice 1: Parts of an Assertion Specification</span></p><p class="practice">
Assertion Authors should include the following items in an
- assertion specification:
- </p><p>
+ assertion specification: </p></div><p>
<ul><li><p><em>The definition of the assertion's semantic.</em> </p></li><li><p><em>The specification of the set of valid policy subjects to which an
assertion may be attached.</em></p></li><li><p><em>The scope of the assertion in the context of a particular policy
subject.</em> For example, an assertion with Endpoint Policy Subject can be
@@ -365,11 +412,11 @@
affect the composition. For example, if an assertion applies to the SOAP
protocol, it would be necessary to consider how its presence must interact
with other policy assertions that are defined for security.</p></li></ul>
- </p><p class="practice">
+ </p><div class="boxedtext"><p><a name="bp-assertion-semantics" id="bp-assertion-semantics"></a><span class="practicelab">Good
+practice 2: Semantics of Policy Assertions</span></p><p class="practice">
The semantics a policy assertion should not depend on the
- attachment mechanism used.
- </p></div><div class="div2">
-<h3><a name="compact-full" id="compact-full"></a>4.2 Authoring Styles </h3><p>WS-Policy supports two different authoring styles, compact form and
+ attachment mechanism used.</p></div></div><div class="div2">
+<h3><a name="compact-full" id="compact-full"></a>5.2 Authoring Styles </h3><p>WS-Policy supports two different authoring styles, compact form and
normal form. A compact form is one in which an expression consists of
three constructs: an attribute to decorate an assertion (to indicate
whether it is required or optional), semantics for recursively nested
@@ -436,10 +483,11 @@
policy expression would be when it is processed. As a result, the
description for a policy assertion should not depend on the style used
to author a policy expression that contains the assertion.
- </p><p class="practice">The semantics of an assertion should be independent of
+ </p><div class="boxedtext"><p><a name="bp-semantics-and-form" id="bp-semantics-and-form"></a><span class="practicelab">Good
+practice 3: Semantics of an Assertion and its form</span></p><p class="practice">The semantics of an assertion should be independent of
the form (compact or normal form) of policy expressions that contain the
- assertion.</p></div><div class="div2">
-<h3><a name="new-guidelines-domains" id="new-guidelines-domains"></a>4.3 Considerations when Modeling New Assertions</h3><p>When creating a new policy domain, it is important to
+ assertion.</p></div></div><div class="div2">
+<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.
@@ -449,7 +497,7 @@
order to enable dynamic negotiation of business requirements
and capabilities at runtime.
</p><div class="div3">
-<h4><a name="minimal-approach" id="minimal-approach"></a>4.3.1 Minimal approach</h4><p>New Assertion Authors are encouraged to try to not overload assertions. A single assertion indicates a single
+<h4><a name="minimal-approach" id="minimal-approach"></a>5.3.1 Minimal approach</h4><p>New Assertion Authors are encouraged to try to not overload assertions. A single assertion indicates a single
behavior. Sets of assertions can by grouped by an operator "all". This indicates that there is a relationship between
the assertions and they now constitute a policy alternative.
</p><p>If grouping is utilized, choices between alternatives can be indicated by
@@ -468,9 +516,9 @@
good to start with a simple working policy assertion that allows extensibility. As your
design work progresses, you may add more parameters or nested policy assertions to meet
your interoperability needs.
- </p><p class="practice">Start with a simple working assertion that allows extensibility.
- </p></div><div class="div3">
-<h4><a name="QName_and_XML_Information_Set_representation" id="QName_and_XML_Information_Set_representation"></a>4.3.2 QName and XML Information Set representation</h4><p>Web Services Policy language allows Assertion Authors to invent
+ </p><div class="boxedtext"><p><a name="bp-assertion-start" id="bp-assertion-start"></a><span class="practicelab">Good
+practice 4: Starting to Build an Assertion</span></p><p class="practice">Start with a simple working assertion that allows extensibility.</p></div></div><div class="div3">
+<h4><a name="QName_and_XML_Information_Set_representation" id="QName_and_XML_Information_Set_representation"></a>5.3.2 QName and XML Information Set representation</h4><p>Web Services Policy language allows Assertion Authors to invent
their own XML dialects to represent policy assertions. The policy language relies only
on the policy assertion XML element QName. This QName is unique and identifies the
behavior represented by a policy assertion. Assertion Authors have the option to
@@ -479,10 +527,11 @@
versus attributes apply.</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
outline can enumerate the nested assertions that are allowed.
- </p><p class="practice">Use a unique QName to identify the behavior and provide an XML outline
+ </p><div class="boxedtext"><p><a name="bp-unique-qnames" id="bp-unique-qnames"></a><span class="practicelab">Good
+practice 5: Unique QNames</span></p><p class="practice">Use a unique QName to identify the behavior and provide an XML outline
(plus an XML schema document) to specify the syntax of an assertion.
- </p></div><div class="div3">
-<h4><a name="self-describing" id="self-describing"></a>4.3.3 Self Describing Messages </h4><p> WS-Policy is intended to communicate the requirements, capabilities and
+ </p></div></div><div class="div3">
+<h4><a name="self-describing" id="self-describing"></a>5.3.3 Self Describing Messages </h4><p> WS-Policy is intended to communicate the requirements, capabilities and
behaviors of nodes that provide the message's path, not specifically to declare properties of the message semantics. One
of the advantages of Web services is that an XML message can be stored and later examined (e.g. as a record of a business
transaction) or interpreted by an intermediary; however, if information that is necessary to understand a message is not
@@ -520,9 +569,9 @@
dedicated endpoint may be allocated to ensure the engagement of a
behavior that is expressed by a policy assertion. This approach
can be considered when messages cannot be self describing.
- </p><p class="practice">Policy assertions should not be used to express the semantics of a message.
- </p></div><div class="div3">
-<h4><a name="single-domains" id="single-domains"></a>4.3.4 Single Domains</h4><p>When considering the creation of a
+ </p><div class="boxedtext"><p><a name="bp-assertions-and-message-semantics" id="bp-assertions-and-message-semantics"></a><span class="practicelab">Good
+practice 6: Assertions and Message Semantics</span></p><p class="practice">Policy assertions should not be used to express the semantics of a message.</p></div></div><div class="div3">
+<h4><a name="single-domains" id="single-domains"></a>5.3.4 Single Domains</h4><p>When considering the creation of a
new domain of policy assertions, it is important to identify
whether or not the domain is self-contained or at least if a
subset of the domain can be well defined. A domain that
@@ -545,13 +594,13 @@
</p><p>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 class="practice">Avoid duplication of assertions.
- </p></div></div><div class="div2">
-<h3><a name="comparison" id="comparison"></a>4.4 Comparison of Nested and Parameterized Assertions</h3><p>There are two different ways to provide additional information in an
+ </p><div class="boxedtext"><p><a name="bp-assertion-duplication" id="bp-assertion-duplication"></a><span class="practicelab">Good
+practice 7: Duplication of Assertions</span></p><p class="practice">Avoid duplication of assertions.</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.
</p><div class="div3">
-<h4><a name="parameterized-assertions" id="parameterized-assertions"></a>4.4.1 Assertions with Parameters</h4><p>The framework allows WS-Policy domain authors to define
+<h4><a name="parameterized-assertions" id="parameterized-assertions"></a>5.4.1 Assertions with Parameters</h4><p>The framework allows WS-Policy domain authors to define
policy assertion parameters to qualify an assertion.
Policy assertion parameters are defined <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite>.
Policy assertion parameters are the opaque payload of an assertion.
@@ -568,17 +617,17 @@
<code>sp:SignedParts</code> policy assertion
(this assertion requires the parts of a message to be protected).
</p><div class="exampleOuter">
-<p style="text-align: left" class="exampleHead"><i><span>Example 4-3. </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-3. </span>Policy Assertion with Assertion Parameters</i></p><div class="exampleInner"><pre><wsp:Policy>
<sp:SignedParts>
<sp:Body/>
<sp:Header/>
</sp:SignedParts>
-</wsp:Policy></pre></div></div><p class="practice">Define policy assertion parameters for
+</wsp:Policy></pre></div></div><div class="boxedtext"><p><a name="bp-assertion-definition" id="bp-assertion-definition"></a><span class="practicelab">Good
+practice 8: Definition of Policy Assertions</span></p><p class="practice">Define policy assertion parameters for
specifying useful pieces of information necessary for engaging
the behavior described by an assertion but not relevant to policy
- intersection.
- </p></div><div class="div3">
-<h4><a name="nested-assertions" id="nested-assertions"></a>4.4.2 Nested Assertions</h4><p>The framework provides the ability to "nest" policy assertions. For domains with a complex set of
+ intersection.</p></div></div><div class="div3">
+<h4><a name="nested-assertions" id="nested-assertions"></a>5.4.2 Nested Assertions</h4><p>The framework provides the ability to "nest" policy assertions. For domains with a complex set of
options, nesting provides one way to indicate dependent
elements within a behavior. The granularity of assertions is
determined by the authors and it is recommended that care be
@@ -614,7 +663,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 4-4. </span>Transport Security Policy Assertion</i></p><div class="exampleInner"><pre><sp:TransportBinding>
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-4. </span>Transport Security Policy Assertion</i></p><div class="exampleInner"><pre><sp:TransportBinding>
<Policy>
<sp:TransportToken>
<Policy>
@@ -658,7 +707,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 4-5. </span>Empty Nested Policy Expression</i></p><div class="exampleInner"><pre><sp:TransportToken>
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-5. </span>Empty Nested Policy Expression</i></p><div class="exampleInner"><pre><sp:TransportToken>
<wsp:Policy>
<sp:HttpsToken>
<wsp:Policy/>
@@ -667,7 +716,7 @@
</sp:TransportToken></pre></div></div><p>A non-anonymous client who requires authentication or client
certificate will not be able to use this provider solely on the basis
of intersection algorithm alone.</p></div><div class="div3">
-<h4><a name="which-one-to-use" id="which-one-to-use"></a>4.4.3 Considerations for choosing parameters vs nesting</h4><p>The main consideration for selecting parameters or nesting
+<h4><a name="which-one-to-use" id="which-one-to-use"></a>5.4.3 Considerations for choosing parameters vs nesting</h4><p>The main consideration for selecting parameters or nesting
of assertions is that <em>the framework intersection
algorithm processes nested alternatives, but does not consider
parameters in its algorithm</em>.
@@ -689,15 +738,15 @@
compatible policy alternative then the assertions in a nested policy expression play a
first class role in the outcome. 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><p class="practice">If the assertion
+ avoided when they are not needed.</p><div class="boxedtext"><p><a name="bp-nesting" id="bp-nesting"></a><span class="practicelab">Good
+practice 9: Nesting of Assertions</span></p><p class="practice">If the assertion
authors want to delegate the processing to the framework,
utilizing nesting should be considered. Otherwise, domain
specific comparison algorithms may need to be devised and be
delegated to the specific domain handlers that are not visible
- to the WS-Policy framework.
- </p></div></div><div class="div2">
-<h3><a name="optional-policy-assertion" id="optional-policy-assertion"></a>4.5 Designating Optional Behaviors</h3><div class="div3">
-<h4><a name="d3e552" id="d3e552"></a>4.5.1 Optional behavior in Compact authoring</h4><p>Optional behaviors represent behaviors which may be engaged by a consumer. When using the
+ to the WS-Policy framework.</p></div></div></div><div class="div2">
+<h3><a name="optional-policy-assertion" id="optional-policy-assertion"></a>5.5 Designating Optional Behaviors</h3><div class="div3">
+<h4><a name="d3e646" id="d3e646"></a>5.5.1 Optional behavior in Compact authoring</h4><p>Optional behaviors represent behaviors which may be engaged by a consumer. When using the
compact authoring form for assertions, behaviors are marked by
using <code>wsp:Optional</code> attribute that has a value,
"true". During the process of normalization, the runtime
@@ -708,7 +757,7 @@
runtime behavior. In order to simplify reference to such
assertions, we just use the term optional assertions in this section.
</p></div><div class="div3">
-<h4><a name="d3e560" id="d3e560"></a>4.5.2 Optional behavior at runtime</h4><p>The <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite> document contains an
+<h4><a name="d3e654" id="d3e654"></a>5.5.2 Optional behavior at runtime</h4><p>The <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite> document contains an
example that proposes the use of <cite><a href="#MTOM">MTOM</a></cite> as an
optional behavior that can be engaged by a consumer. The
primer proposes that an assertion that identifies the use of
@@ -739,7 +788,7 @@
with respect to messages that are targeted to the provider
so that the provider can determine that the optional
behavior is engaged. In other words, the requirement of self
- describing nature of messages [<a href="#self-describing"><b>4.3.3 Self Describing Messages </b></a>] in order to engage behaviors must
+ describing nature of messages [<a href="#self-describing"><b>5.3.3 Self Describing Messages </b></a>] in order to engage behaviors must
not be forgotten with regard to the client's ability to
detect and select the alternative if it is to participate in the exchange.
</p></li><li><p> The target scope of an optional assertion is an important factor for
@@ -781,12 +830,12 @@
approach that is currently taken by WS-RM Policy [<cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite>] is to introduce both message and endpoint
policy subjects for one of its assertions and require the
use of endpoint policy subject when message policy subject is used via attachment.
- </p></li></ul><p class="practice">Optional Assertion Authors should explicitly state
+ </p></li></ul><div class="boxedtext"><p><a name="bp-optional-assertions" id="bp-optional-assertions"></a><span class="practicelab">Good
+practice 10: Optional Assertions</span></p><p class="practice">Optional Assertion Authors should explicitly state
how the behavior that is enabled by the assertion would be
engaged when they are designing their assertion, whether by
- specific headers or some other means. See also <a href="#self-describing"><b>4.3.3 Self Describing Messages </b></a>.
- </p></div></div><div class="div2">
-<h3><a name="levels-of-abstraction" id="levels-of-abstraction"></a>4.6 Levels of Abstraction in WSDL </h3><p>A behavior identified by a policy assertion applies to the
+ specific headers or some other means. See also .</p></div></div></div><div class="div2">
+<h3><a name="levels-of-abstraction" id="levels-of-abstraction"></a>5.6 Levels of Abstraction in WSDL </h3><p>A behavior identified by a policy assertion applies to the
associated policy subject. If a policy assertion is to be used
within WSDL, Assertion Authors must specify a WSDL
policy subject. The policy subject is determined with respect
@@ -856,7 +905,7 @@
policy assertions do not target wire-level behaviors but
rather abstract requirements, this technique does not apply.
</p></div><div class="div2">
-<h3><a name="interrelated-domains" id="interrelated-domains"></a>4.7 Interrelated domains</h3><p>Assertion authors need to be clear about how assertions defined in
+<h3><a name="interrelated-domains" id="interrelated-domains"></a>5.7 Interrelated domains</h3><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
@@ -868,7 +917,7 @@
assertions and should also make sure that when adding assertions those new assertions are consistent
with pre-existing assertions of any
interrelated domain. </p></div></div><div class="div1">
-<h2><a name="versioning-policy-assertions" id="versioning-policy-assertions"></a>5. Versioning Policy Assertions</h2><p>Assertion Authors need to consider not just the expression of the current set of requirements but
+<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 assetions:</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
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>
@@ -876,7 +925,7 @@
for details on extensibility.
</p><p> The current WS-Policy language <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite> provides extensibility points
on 6 elements with a combination of attribute and/or element extensibility:</p><ol class="enumar"><li><p>Policy: element from ##other namespace and any attribute</p></li><li><p>ExactlyOne, All: element from ##other namespace; no attribute extensibility</p></li><li><p>PolicyReference: any element and any attribute</p></li><li><p>PolicyAttachment: element from ##other namespace and any attribute</p></li><li><p>AppliesTo: any element and any attribute</p></li><li><p>URI: any attribute</p></li></ol></li><li><p>Supporting New Policy Subjects</p></li></ul><div class="div2">
-<h3><a name="Referencing_Policy_Expressions" id="Referencing_Policy_Expressions"></a>5.1 Referencing Policy Expressions</h3><p>The <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite> illustrates how providers can utilize
+<h3><a name="Referencing_Policy_Expressions" id="Referencing_Policy_Expressions"></a>6.1 Referencing Policy Expressions</h3><p>The <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite> illustrates how providers can utilize
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
@@ -890,7 +939,7 @@
<code>sp:RequestSecurityTokenTemplate</code> parameter that contains necessary
information to request a security token. The contents of the parameter
are static and allows reuse in different security scenerios.</p></div><div class="div2">
-<h3><a name="extending-assertions" id="extending-assertions"></a>5.2 Evolution of Assertions (Versioning and Compatibility)</h3><p>Over time, there may be multiple equivalent behaviors emerging in the Web
+<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
[<cite><a href="#WS-Addressing">WS-Addressing Core</a></cite>]. These equivalent behaviors
@@ -898,16 +947,17 @@
behaviors can be modeled as independent assertions. The
policy expression in the example below requires the use of
WSS: SOAP Message Security 1.0. </p><div class="exampleOuter">
-<p style="text-align: left" class="exampleHead"><i><span>Example 5-1. </span>Message-level Security and WSS: SOAP Message Security 1.0</i></p><div class="exampleInner"><pre><Policy>
+<p style="text-align: left" class="exampleHead"><i><span>Example 6-1. </span>Message-level Security and WSS: SOAP Message Security 1.0</i></p><div class="exampleInner"><pre><Policy>
<sp:Wss10>…</sp:Wss10>
</Policy></pre></div></div><p>The policy expression in the example below requires the use of WSS: SOAP Message
Security 1.1. These are multiple equivalent behaviors and are represented using distinct
policy assertions.</p><div class="exampleOuter">
-<p style="text-align: left" class="exampleHead"><i><span>Example 5-2. </span>Message-level Security and WSS: SOAP Message Security 1.1</i></p><div class="exampleInner"><pre><Policy>
+<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><p class="practice">Use independent assertions for modeling multiple equivalent
- behaviors.</p></div><div class="div2">
-<h3><a name="supporting-new-policy-subjects" id="supporting-new-policy-subjects"></a>5.3 Supporting New Policy Subjects</h3><p>
+</Policy></pre></div></div><div class="boxedtext"><p><a name="bp-independent-assertions" id="bp-independent-assertions"></a><span class="practicelab">Good
+practice 11: Independent Assertions</span></p><p class="practice">Use independent assertions for modeling multiple equivalent
+ behaviors.</p></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>
<a href="#Assertions">Section 2</a> identifies that it is a best practice for policy authors to
define the set of policy subjects to which policy assertions can be
attached. Over time, new policy subjects may need to be defined. When
@@ -923,37 +973,38 @@
provided that endpoint policy subject is also retained in its design. When
new policy subjects are added it is incumbent on the authors to retain the
semantic of the policy assertion.
- </p><p class="practice">An assertion description should specify a policy
- subject.</p><p class="practice">If the policy subjects change over time,
+ </p><div class="boxedtext"><p><a name="bp-assertion-description" id="bp-assertion-description"></a><span class="practicelab">Good
+practice 12: Description of Assertions</span></p><p class="practice">An assertion description should specify a policy
+ subject.</p></div><div class="boxedtext"><p><a name="bp-tbd" id="bp-tbd"></a><span class="practicelab">Good
+practice 13: Change of the Policy Subject Over Time</span></p><p class="practice">If the policy subjects change over time,
the assertion description should also be versioned to reflect this
- change.
- </p></div></div><div class="div1">
-<h2><a name="best-practices-attachment" id="best-practices-attachment"></a>6. Applying Best Practices for Policy Attachment</h2><div class="div2">
-<h3><a name="context-free-policies" id="context-free-policies"></a>6.1 Appropriate Attachment: Preserving Context-Free Policies</h3><p>Policy attachment should not affect the interpretation of
+ change.</p></div></div></div><div class="div1">
+<h2><a name="best-practices-attachment" id="best-practices-attachment"></a>7. Applying Best Practices for Policy Attachment</h2><div class="div2">
+<h3><a name="context-free-policies" id="context-free-policies"></a>7.1 Appropriate Attachment: Preserving Context-Free Policies</h3><p>Policy attachment should not affect the interpretation of
Policy alternatives. If it did, each policy assertion would
need to be written with different (and possibly unknown)
attachment mechanisms in mind. </p></div><div class="div2">
-<h3><a name="appropriate-attachment-assertion-subjects" id="appropriate-attachment-assertion-subjects"></a>6.2 Appropriate Attachment: Identifying Assertion Subjects</h3><p>Each policy attachment mechanism should unambiguously
+<h3><a name="appropriate-attachment-assertion-subjects" id="appropriate-attachment-assertion-subjects"></a>7.2 Appropriate Attachment: Identifying Assertion Subjects</h3><p>Each policy attachment mechanism should unambiguously
identify the subject of the attached assertions. Generally,
this should be a specific SOAP node or a specific message
between two SOAP nodes. Some attachment mechanisms may
encompass multiple notes or messages, for example, "the
message along its entire path". </p><div class="div3">
-<h4><a name="interaction" id="interaction"></a>6.2.1 Interaction between Subjects</h4><p>If the best practices are followed, and the assertions
+<h4><a name="interaction" id="interaction"></a>7.2.1 Interaction between Subjects</h4><p>If the best practices are followed, and the assertions
are scoped according to their subject, then multiple policy
domains may be combined without conflict. Each domain
should define any limitations at the policy subject level
that might impact interoperability (i.e. WS-SecurityPolicy
- binding abstraction to group capabilities per message
exchange). </p></div></div><div class="div2">
-<h3><a name="identifying-assertion-sources" id="identifying-assertion-sources"></a>6.3 Appropriate Attachment: Identifying Assertion Sources </h3><p>As with identifying Policy subjects, policy attachment
+<h3><a name="identifying-assertion-sources" id="identifying-assertion-sources"></a>7.3 Appropriate Attachment: Identifying Assertion Sources </h3><p>As with identifying Policy subjects, policy attachment
mechanisms should make it possible to clearly identify the
source of a policy assertion both for debugging and for
verification. This could take several forms: it could be
assumed (in WSDL, the source of the assertion is the same
as the WSDL provider) or it could be proven (using
<cite><a href="#WS-Trust">WS-Trust</a></cite>). </p></div></div><div class="div1">
-<h2><a name="scenario" id="scenario"></a>7. Scenario and a worked example</h2><p>To illustrate the topics explored in this document, we
+<h2><a name="scenario" id="scenario"></a>8. Scenario and a worked example</h2><p>To illustrate the topics explored in this document, we
include an example of a web service and how a fictitious company
might utilize the WS-Policy Framework to enable Web Service
interoperability. Company A has determined to utilize WS-Security,
@@ -977,7 +1028,7 @@
well as including addressing headers. Employees of Company A have
already incorporated <code>wss:Security</code> headers into their
messages. </p><div class="exampleOuter">
-<p style="text-align: left" class="exampleHead"><i><span>Example 7-1. </span>Message with Security Headers</i></p><div class="exampleInner"><pre><soap:Envelope>
+<p style="text-align: left" class="exampleHead"><i><span>Example 8-1. </span>Message with Security Headers</i></p><div class="exampleInner"><pre><soap:Envelope>
<soap:Header>
<wss:Security soap:mustUnderstand ="1">
<wsu:Timestamp wsu:Id=_0">
@@ -997,7 +1048,7 @@
CompanyA has created for its employees to use on their web
services to indicate the use of addressing and transport-level
security for securing messages. </p><div class="exampleOuter">
-<p style="text-align: left" class="exampleHead"><i><span>Example 7-2. </span> CompanyA-ProfileA </i></p><div class="exampleInner"><pre>
+<p style="text-align: left" class="exampleHead"><i><span>Example 8-2. </span> CompanyA-ProfileA </i></p><div class="exampleInner"><pre>
<Policy URI=http://www.CompanyA.com/WebServicesProfileA.xml>
<wsa:UsingAddressing />
<sp:TransportBinding></sp:TransportBinding>
@@ -1026,7 +1077,7 @@
including WS-Security Headers to protect the message content
after it is processed by the transport. The additional security
processing is not required by all Company A web services. </p><div class="exampleOuter">
-<p style="text-align: left" class="exampleHead"><i><span>Example 7-3. </span>CompanyA-ProfileB (not expanded)</i></p><div class="exampleInner"><pre><Policy wsu:Id="CompanyA-ProfileB">
+<p style="text-align: left" class="exampleHead"><i><span>Example 8-3. </span>CompanyA-ProfileB (not expanded)</i></p><div class="exampleInner"><pre><Policy wsu:Id="CompanyA-ProfileB">
<wsa:UsingAddressing/>
<ExactlyOne>
<sp:TransportBinding></sp:TransportBinding>
@@ -1051,7 +1102,7 @@
assertions. </p><p>In the example below the child Policy element is a nested
policy behavior and further qualifies the behavior of the
<code>sp:TransportBinding</code> policy assertion. </p><div class="exampleOuter">
-<p style="text-align: left" class="exampleHead"><i><span>Example 7-4. </span>CompanyA-ProfileB (fully expanded)</i></p><div class="exampleInner"><pre><Policy wsu:Id="CompanyA-ProfileB">
+<p style="text-align: left" class="exampleHead"><i><span>Example 8-4. </span>CompanyA-ProfileB (fully expanded)</i></p><div class="exampleInner"><pre><Policy wsu:Id="CompanyA-ProfileB">
<wsa:UsingAddressing/>
<ExactlyOne>
<sp:TransportBinding>
@@ -1099,13 +1150,13 @@
policy subject as recommended by the WS-SecurityPolicy
specification. For the default web services, the URI is included
in the wsdl binding for each web service. </p><div class="exampleOuter">
-<p style="text-align: left" class="exampleHead"><i><span>Example 7-5. </span></i></p><div class="exampleInner"><pre><wsdl:binding name="CompanyADefaultBinding" type="tns:CompanyADefault">
+<p style="text-align: left" class="exampleHead"><i><span>Example 8-5. </span></i></p><div class="exampleInner"><pre><wsdl:binding name="CompanyADefaultBinding" type="tns:CompanyADefault">
<wsp:PolicyReference URI="http://www.CompanyA.com/WebServicesProfileA.xml">
<wsdl:operation name="GetQuote"> </wsdl:operation>
</wsdl:binding></pre></div></div><p>The partner specified policy is included in the beginning of
the WSDL 1.1 document and referenced by the binding for the service
as in the example below.</p><div class="exampleOuter">
-<p style="text-align: left" class="exampleHead"><i><span>Example 7-6. </span></i></p><div class="exampleInner"><pre>
+<p style="text-align: left" class="exampleHead"><i><span>Example 8-6. </span></i></p><div class="exampleInner"><pre>
<wsdl:definitions name="StockQuote"
targetNamespace="http:..">
<wsp:Policy wsu:Id="CompanyA-ProfileB">
@@ -1297,14 +1348,14 @@
</p></div><div class="div1">
<h2><a name="change-description" id="change-description"></a>E. Changes in this Version of
the Document (Non-Normative)</h2><p>A list of substantive changes since the Working Draft dated 21 December,
- 2006 is below:</p><ul><li><p>Rewrote section <a href="#supporting-new-policy-subjects"><b>5.3 Supporting New Policy Subjects</b></a> and added two new best practices:
+ 2006 is below:</p><ul><li><p>Rewrote section <a href="#supporting-new-policy-subjects"><b>6.3 Supporting New Policy Subjects</b></a> and added two new best practices:
<ul><li><p>An assertion description should specify a policy subject.</p></li><li><p>If the policy subjects change over time, the assertion description
- should also be versioned to reflect this change.</p></li></ul></p></li><li><p>Rewrote section <a href="#compact-full"><b>4.2 Authoring Styles </b></a> and added a new best practice:
+ should also be versioned to reflect this change.</p></li></ul></p></li><li><p>Rewrote section <a href="#compact-full"><b>5.2 Authoring Styles </b></a> and added a new best practice:
the semantics of an assertion should be independent of the form (compact or normal form)
- of policy expressions that contain the assertion.</p></li><li><p>Rewrote section <a href="#Referencing_Policy_Expressions"><b>5.1 Referencing Policy Expressions</b></a>.</p></li><li><p>Rewrote section <a href="#assertion-target"><b>4.1 Assertions and Their Target Use</b></a> and added a new best practice:
+ of policy expressions that contain the assertion.</p></li><li><p>Rewrote section <a href="#Referencing_Policy_Expressions"><b>6.1 Referencing Policy Expressions</b></a>.</p></li><li><p>Rewrote section <a href="#assertion-target"><b>5.1 Assertions and Their Target Use</b></a> and added a new best practice:
the semantics a policy assertion should not depend on the attachment mechanism used.</p></li><li><p>Dropped section
<a href="http://www.w3.org/TR/2006/WD-ws-policy-guidelines-20061221/#typing-assertions">4.6 Typing
- Assertions</a>.</p></li><li><p>Clarified the semantics of an empty nested policy expression in <a href="#nested-assertions"><b>4.4.2 Nested Assertions</b></a>.</p></li></ul></div><div class="div1">
+ Assertions</a>.</p></li><li><p>Clarified the semantics of an empty nested policy expression in <a href="#nested-assertions"><b>5.4.2 Nested Assertions</b></a>.</p></li></ul></div><div class="div1">
<h2><a name="change-log" id="change-log"></a>F. Web Services Policy 1.5 - Guidelines for Policy Assertion Authors Change Log (Non-Normative)</h2><a name="ws-policy-primer-changelog-table"></a><table border="1"><tbody><tr><th rowspan="1" colspan="1">Date</th><th rowspan="1" colspan="1">Author</th><th rowspan="1" colspan="1">Description</th></tr><tr><td rowspan="1" colspan="1">20060829</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Created first draft based on agreed outline and content</td></tr><tr><td rowspan="1" colspan="1">20061013</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Editorial fixes (suggested by Frederick), fixed references, bibl items, fixed dangling pointers, created eds to do</td></tr><tr><td rowspan="1" colspan="1">20061018</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">Editorial fixes for readability, added example for Encrypted parts</td></tr><tr><td rowspan="1" colspan="1">20061030</td><td rowspan="1" colspan="1">UY</td><td rospan="1" colspan="1">Fixes for Paul Cotton's editorial comments (20061020)</td></tr><tr><td rowspan="1" colspan="1">20061031</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Fixes for Frederick's editorial comments (20061025)</td></tr><tr><td rowspan="1" colspan="1">20061031</td><td rowspan="1" colspan="1">UY</td><td rowspan="1" colspan="1">Optionality discussion feedback integration</td></tr><tr><td rowspan="1" colspan="1">20061115</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">First attempt at restructuring to include primer content</td></tr><tr><td rowspan="1" colspan="1">20061120</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">Restructure to address action items 64,77, which refer to bugzilla 3705 and F2F RESOLUTION 3792 </td></tr><tr><td rowspan="1" colspan="1">20061127</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Updated the list of editors. Added
<a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0033.html">Frederick</a> and
<a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0054.html">Umit</a> to the list of editors.
@@ -1316,8 +1367,8 @@
includes suggestions from Asir:
<a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0129.html">Part 1</a> and
<a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0134.html">Part 2</a>.
- </td></tr><tr><td rowspan="1" colspan="1">20061129</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Formatted examples in <a href="#extending-assertions"><b>5.2 Evolution of Assertions (Versioning and Compatibility)</b></a>.
- </td></tr><tr><td rowspan="1" colspan="1">20061218</td><td rowspan="1" colspan="1">FS</td><td rowspan="1" colspan="1">Formatted examples in <a href="#compact-full"><b>4.2 Authoring Styles </b></a> and <a href="#scenario"><b>7. Scenario and a worked example</b></a>.
+ </td></tr><tr><td rowspan="1" colspan="1">20061129</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Formatted examples in <a href="#extending-assertions"><b>6.2 Evolution of Assertions (Versioning and Compatibility)</b></a>.
+ </td></tr><tr><td rowspan="1" colspan="1">20061218</td><td rowspan="1" colspan="1">FS</td><td rowspan="1" colspan="1">Formatted examples in <a href="#compact-full"><b>5.2 Authoring Styles </b></a> and <a href="#scenario"><b>8. Scenario and a worked example</b></a>.
</td></tr><tr><td rowspan="1" colspan="1">20061219</td><td rowspan="1" colspan="1">TIB</td><td rowspan="1" colspan="1">Editorial revision: most parts of editorial action
<a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/96">96</a>.
Remaining editorials to be reviewed.
Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.52
retrieving revision 1.53
diff -u -d -r1.52 -r1.53
--- ws-policy-guidelines.xml 29 Mar 2007 22:25:43 -0000 1.52
+++ ws-policy-guidelines.xml 5 Apr 2007 13:04:53 -0000 1.53
@@ -8,6 +8,7 @@
<!ENTITY document.status.guidelines "Editors' copy $Date$">
<!ENTITY prevloc "http://www.w3.org/TR/2006/WD-ws-policy-guidelines-20061221">
<!ENTITY hellip "…">
+<!ENTITY guidelines-bestpractices SYSTEM "guidelines-bestpractices.xml">
]>
<?xml-stylesheet type='text/xsl' href='xmlspec-policy.xsl'?>
<spec w3c-doctype="&doctype.guidelines;" role="&document.role;">
@@ -148,7 +149,11 @@
the question.
</p>
</div1>
-
+ <div1 id="best-practices-list">
+ <head>List of Best Practices Statements</head>
+ <p>TBD:</p>
+ &guidelines-bestpractices;
+ </div1>
<div1 id="Assertions">
<head>What is an Assertion? </head>
@@ -444,9 +449,9 @@
attachment mechanism. Independence from a specific attachment mechanism
allows policy tools to choose the most appropriate mechanism to attach a
policy without having to analyze the contents of the policy.
- </p><p role="practice">
+ </p><p role="practice" id="bp-assertion-specification-parts"><quote>Parts of an Assertion Specification</quote><quote>
Assertion Authors should include the following items in an
- assertion specification:
+ assertion specification: </quote>
</p><p>
<ulist>
<item><p><emph>The definition of the assertion's semantic.</emph> </p></item>
@@ -465,9 +470,9 @@
with other policy assertions that are defined for security.</p></item>
</ulist>
</p>
- <p role="practice">
+ <p role="practice" id="bp-assertion-semantics"><quote>Semantics of Policy Assertions</quote><quote>
The semantics a policy assertion should not depend on the
- attachment mechanism used.
+ attachment mechanism used.</quote>
</p>
</div2>
<div2 id="compact-full">
@@ -554,9 +559,9 @@
to author a policy expression that contains the assertion.
</p>
- <p role="practice">The semantics of an assertion should be independent of
+ <p role="practice" id="bp-semantics-and-form"><quote>Semantics of an Assertion and its form</quote><quote>The semantics of an assertion should be independent of
the form (compact or normal form) of policy expressions that contain the
- assertion.</p>
+ assertion.</quote></p>
</div2>
<div2 id="new-guidelines-domains">
@@ -599,7 +604,7 @@
design work progresses, you may add more parameters or nested policy assertions to meet
your interoperability needs.
</p>
- <p role="practice">Start with a simple working assertion that allows extensibility.
+ <p role="practice" id="bp-assertion-start"><quote>Starting to Build an Assertion</quote><quote>Start with a simple working assertion that allows extensibility.</quote>
</p>
</div3>
<div3 id="QName_and_XML_Information_Set_representation">
@@ -615,9 +620,9 @@
document). If the assertion has a nested policy expression then the assertion XML
outline can enumerate the nested assertions that are allowed.
</p>
- <p role="practice">Use a unique QName to identify the behavior and provide an XML outline
+ <p role="practice" id="bp-unique-qnames"><quote>Unique QNames</quote><quote>Use a unique QName to identify the behavior and provide an XML outline
(plus an XML schema document) to specify the syntax of an assertion.
- </p>
+ </quote> </p>
</div3>
<div3 id="self-describing">
<head> Self Describing Messages </head>
@@ -667,7 +672,7 @@
behavior that is expressed by a policy assertion. This approach
can be considered when messages cannot be self describing.
</p>
- <p role="practice">Policy assertions should not be used to express the semantics of a message.
+ <p role="practice" id="bp-assertions-and-message-semantics"><quote>Assertions and Message Semantics</quote><quote>Policy assertions should not be used to express the semantics of a message.</quote>
</p>
</div3>
<div3 id="single-domains">
@@ -698,7 +703,7 @@
the best way to ensure that the granularity of a set of domain
assertions is appropriate.
</p>
- <p role="practice">Avoid duplication of assertions.
+ <p role="practice" id="bp-assertion-duplication"><quote>Duplication of Assertions</quote><quote>Avoid duplication of assertions.</quote>
</p>
</div3>
</div2>
@@ -739,10 +744,10 @@
</sp:SignedParts>
</wsp:Policy></eg>
</example>
- <p role="practice">Define policy assertion parameters for
+ <p role="practice" id="bp-assertion-definition"><quote>Definition of Policy Assertions</quote><quote>Define policy assertion parameters for
specifying useful pieces of information necessary for engaging
the behavior described by an assertion but not relevant to policy
- intersection.
+ intersection.</quote>
</p>
</div3>
@@ -898,12 +903,12 @@
first class role in the outcome. 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>
- <p role="practice">If the assertion
+ <p role="practice" id="bp-nesting"><quote>Nesting of Assertions</quote><quote>If the assertion
authors want to delegate the processing to the framework,
utilizing nesting should be considered. Otherwise, domain
specific comparison algorithms may need to be devised and be
delegated to the specific domain handlers that are not visible
- to the WS-Policy framework.
+ to the WS-Policy framework.</quote>
</p>
</div3>
</div2>
@@ -1021,10 +1026,10 @@
</p>
</item>
</ulist>
- <p role="practice">Optional Assertion Authors should explicitly state
+ <p role="practice" id="bp-optional-assertions"><quote>Optional Assertions</quote><quote>Optional Assertion Authors should explicitly state
how the behavior that is enabled by the assertion would be
engaged when they are designing their assertion, whether by
- specific headers or some other means. See also <specref ref="self-describing"/>.
+ specific headers or some other means. See also <specref ref="self-describing"/>.</quote>
</p>
</div3>
</div2>
@@ -1223,8 +1228,8 @@
<eg xml:space="preserve"><Policy>
<sp:Wss11>…</sp:Wss11>
</Policy></eg></example>
- <p role="practice">Use independent assertions for modeling multiple equivalent
- behaviors.</p>
+ <p role="practice" id="bp-independent-assertions"><quote>Independent Assertions</quote><quote>Use independent assertions for modeling multiple equivalent
+ behaviors.</quote></p>
</div2>
<div2 id="supporting-new-policy-subjects">
<head>Supporting New Policy Subjects</head>
@@ -1246,11 +1251,11 @@
new policy subjects are added it is incumbent on the authors to retain the
semantic of the policy assertion.
</p>
- <p role="practice">An assertion description should specify a policy
- subject.</p>
- <p role="practice">If the policy subjects change over time,
+ <p role="practice" id="bp-assertion-description"><quote>Description of Assertions</quote><quote>An assertion description should specify a policy
+ subject.</quote></p>
+ <p role="practice" id="bp-policy-subject-change"><quote>Change of the Policy Subject Over Time</quote><quote>If the policy subjects change over time,
the assertion description should also be versioned to reflect this
- change.
+ change.</quote>
</p>
</div2>
</div1>
Received on Thursday, 5 April 2007 13:05:14 UTC