W3C home > Mailing lists > Public > public-ws-policy-eds@w3.org > November 2006

2006/ws/policy ws-policy-guidelines.xml,1.7,1.8

From: Umit Yalsinap via cvs-syncmail <cvsmail@w3.org>
Date: Wed, 01 Nov 2006 01:18:15 +0000
To: public-ws-policy-eds@w3.org
Message-Id: <E1Gf4kB-0005xN-C0@lionel-hutz.w3.org>

Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv22794

Modified Files:
	ws-policy-guidelines.xml 
Log Message:
Fixes for Frederick's comments (20061025)

Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -d -r1.7 -r1.8
--- ws-policy-guidelines.xml	31 Oct 2006 04:04:10 -0000	1.7
+++ ws-policy-guidelines.xml	1 Nov 2006 01:18:13 -0000	1.8
@@ -264,7 +264,7 @@
 					<head>Providers</head>
 					<p>A provider of WS-Policy
 	   Assertions can be any web service implementation that can
-	   reflect it's on the wire message behavior as an XML
+	   specify its' on-the-wire message behavior as an XML
 	   expression that conforms to the WS-PolicyFramework and
 	   WS-Policy Attachment specifications. The
 	   WS-PolicyAttachment specification has defined a set of
@@ -518,8 +518,53 @@
 		their service descriptions. </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> </div2> <div2
-        id="nested-assertions"> <head>Nested Assertions</head>
+        assertions is appropriate. </p> 
+                        </div2>
+			<div2 id="comparison">
+				<head>Comparison of Nested and Parameterized Assertions</head>
+				<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>
+
+				<div3 id="parameterized-assertions">
+				<head>Assertions with Parameters</head>
+				<p>The framework allows WS-Policy
+        domain authors to define name value pairs, for example, to
+        qualify an assertion.  For some domains it will be appropriate
+        to specify these parameters instead of nesting assertion elements. </p>
+				<p> Note that parameters of assertions include the following:</p>
+				<ulist>
+					<item>
+						<p> Complex elements
+					with element children
+					that cannot be policy
+					assertions.  </p> </item>
+					<item>
+						<p> Elements that have attributes </p>
+					</item>
+				</ulist>
+				<p>In the example below,
+            <code>sp:Body</code> and <code>sp:Header</code> elements
+            are the two assertion parameters of the
+            <code>sp:SignedParts</code> policy assertion (this
+            assertion requires the parts of a message to be
+            protected). </p>
+
+	<example> <head>Policy Assertion with Assertion Parameters</head>
+            <eg xml:space="preserve">&lt;Policy&gt;
+  &lt;sp:SignedParts&gt;
+    &lt;sp:Body /&gt;
+    &lt;sp:Header /&gt;
+  &lt;/sp:SignedParts&gt;
+&lt;/Policy&gt;</eg>
+          </example>
+			</div3>
+
+			<div3 id="nested-assertions"> <head>Nested Assertions</head>
 				<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
@@ -594,28 +639,10 @@
         security usage is absorbed by a policy-aware client and hidden
         from these Web service developers.
         </p>
-			</div2>
-			<div2 id="parameterized-assertions">
-				<head>Assertions with Parameters</head>
-				<p>The framework provides an alternative approach for
-        providing additional information for an assertion beyond its
-        type.  The framework allows WS-Policy domain authors to define
-        name value pairs, for example,  to qualify an assertion.  For some domains it
-        will be appropriate to specify these parameters instead of
-        nesting elements. </p>
-				<p> Note that parameters of assertions include the following:</p>
-				<ulist>
-					<item>
-						<p> Complex elements that have element children which can not be policy assertions.  </p>
-					</item>
-					<item>
-						<p> Elements that have attributes </p>
-					</item>
-				</ulist>
-			</div2>
-			<div2 id="comparison">
-				<head>Comparison of Nested and Parameterized Assertions</head>
-				<p>The main consideration for selecting parameters or nesting
+			</div3>
+			<div3 id="which-one-to-use">
+                        <head>Considerations for choosing parameters vs nesting</head>
+			<p>The main consideration for selecting parameters or nesting
 	of assertions, is that <emph>the framework intersection
 	algorithm processes nested alternatives, but does not consider
 	parameters in its algorithm</emph>. </p>
@@ -636,66 +663,66 @@
         to the WS-Policy framework. The tradeoff is the generality
         vs. the flexibility and complexity of the comparison expected
         for a domain. </p>
- <p>In the example below, <code>sp:Body</code> and <code>sp:Header</code> elements are the
-            two assertion parameters of the <code>sp:SignedParts</code> policy assertion (this
-            assertion requires the parts of a message to be protected). </p>
-	<example> <head>Policy Assertion with Assertion Parameters</head>
-            <eg xml:space="preserve">&lt;Policy&gt;
-  &lt;sp:SignedParts&gt;
-    &lt;sp:Body /&gt;
-    &lt;sp:Header /&gt;
-  &lt;/sp:SignedParts&gt;
-&lt;/Policy&gt;</eg>
-          </example>
-		
+
+		        </div3>
 			</div2>
 			<div2 id="self-describing">
 				<head> Self Describing Messages </head>
-				<p>WS-Policy is intended to communicate the requirements,
-     capabilities, preferences 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
+				<p> WS-Policy is intended to
+     communicate the requirements, capabilities, preferences 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
      available, these capabilities suffer.
      </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 to later decipher it. This is
-     very different from expressing, in policy, what ciphers (and so
-     forth) are supported by a particular endpoint, or those that are
-     required in a particular message; the latter are the intended
-     uses of the Ws-Policy framework.
+                                <p>Policy assertions should not be
+     used to express the semantics of a message. Rather, if a property is
+     required to understand a message, it should be communicated in
+     the message, or be made available by some other means (e.g., being
+     referenced by a URI in the message) instead of being communicated as a
+     policy element.
      </p>
-				<p>The assertion authors should take into account that there are
-     two important concepts when designing assertions and documenting the semantics of the
-     assertion types. Firstly, an
-     assertion type indicates a <emph>runtime</emph> behavior.  Secondly,
-     an assertion should also indicate how the assertion type can be
-     inferred or indicated from a message.  If there is a need for the
-     behavior to be represented in a persistent way or if there s a need for additional data
-     or metadata that is present in a message to be persisted, it should be incorporated
-     into the assertion design or in the message itself. 
+				<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
+     endpoint, or those that are required in a particular message; the
+     latter are the intended uses of the WS-Policy framework.
      </p>
-				<p>As a result, Policy assertions should not be used to express
-     the semantics of a message. If a property is
-     required to understand a message, it should be communicated in
-     the message, or be made available by some other means(e.g., being
-     referenced by a URI in the message) rather than communicated as a
-     policy element. 
+				<p>As a result, the assertion authors
+     should take into account that the following important concepts
+     when designing assertions and documenting the semantics of the
+     assertion types. Firstly, an assertion type indicates a
+     <emph>runtime</emph> behavior.  Secondly, an assertion should
+     also indicate how the assertion type can be inferred or indicated
+     from a message at runtime.  If there is a need for the behavior
+     to be represented in a persistent way or if there is a need for
+     additional data or metadata that is present in a message to be
+     persisted, it should be incorporated into the assertion design or
+     in the message itself. In essence, the assertion authors should
+     consider how to make messages self describing when utilizing
+     their assertions by specifying additional properties, headers,
+     etc. that must be present in a message as part of their assertion
+     design.
      </p>
-				<p>If the messages could not be made self describing by utilizing
-    additional properties present in the message as required by the assertion, it would be
-    necessary to determine the behaviors engaged at runtime by
-    additional means. A general protocol that aids in determining
-    such behaviors may be utilized, however a standard protocol for
-    this purpose is currently not available to ensure
-    interoperability. Thus, a private protocol should be used with
-    care. Another alternative is to use
-    of the assertion to selectively apply to subjects. For example, creating a separate endpoint to ensure
-    engagement of the behavior is an option that can be
-    considered as an alternate approach when messages can not be self describing. 
+				
+				<p>If the messages could not be made
+    self describing by utilizing additional properties present in the
+    message as required by the assertion, it would be necessary to
+    determine the behaviors engaged at runtime by additional means. A
+    general protocol that aids in determining such behaviors may be
+    utilized, however a standard protocol for this purpose is
+    currently not available to ensure interoperability. Thus, a
+    private protocol should be used with care. </p>
+                                 <p>Another approach is to use of the
+    assertion to selectively apply to subjects. For example, a
+    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 can not be self describing. 
      </p>
 			</div2>
 			<div2 id="optional-policy-assertion">
@@ -1142,7 +1169,7 @@
 				<eg xml:space="preserve">
 &lt;Policy URI=http://www.CompanyA.com/WebServicesProfileA.xml&gt; 
 	&lt;wsa:UsingAddressing /&gt;
-	&lt;sp:TransportBinding&gt;&lt;/spTransportBinding&gt;
+	&lt;sp:TransportBinding&gt;&lt;/sp:TransportBinding&gt;
 &lt;/Policy&gt;</eg>
 			</example>
 			<p>The <code>sp:TransportBinding</code> element is a policy assertion. The
@@ -1208,17 +1235,19 @@
 	&lt;wsa:UsingAddressing /&gt;
 	&lt;ExactlyOne&gt;
 	   &lt;sp:TransportBinding&gt;
-   	 &lt;sp:TransportToken&gt;
-		   &lt;Policy&gt;
-		      &lt;sp:HttpsToken RequireClienCertificate="false" /&gt;
-              &lt;/Policy&gt;
-            &lt;/sp:TransportToken&gt;
-            &lt;sp:AlgorithmSuite&gt;
               &lt;Policy&gt;
-		      &lt;sp:Basic256Rsa15 /&gt;
+   	         &lt;sp:TransportToken&gt;
+		    &lt;Policy&gt;
+		      &lt;sp:HttpsToken RequireClienCertificate="false" /&gt;
+                    &lt;/Policy&gt;
+                 &lt;/sp:TransportToken&gt;
+                 &lt;sp:AlgorithmSuite&gt;
+                    &lt;Policy&gt;
+		       &lt;sp:Basic256Rsa15 /&gt;
+                    &lt;/Policy&gt;
+                 &lt;/sp:AlgorithmSuite&gt;
               &lt;/Policy&gt;
-            &lt;/spAlgorithmSuite&gt;
-       &lt;/sp:TransportBinding&gt;
+        &lt;/sp:TransportBinding&gt;
 	   &lt;sp:AsymmetricBinding&gt;
   &lt;/sp:AssymetricBinding&gt;
 	&lt;/ExactlyOne&gt;
@@ -1276,22 +1305,22 @@
 	&lt;wsa:UsingAddressing /&gt;
 	&lt;ExactlyOne&gt;
 	   &lt;sp:TransportBinding&gt;
-     	 &lt;sp:TransportToken&gt;
+              &lt;Policy&gt;
+     	         &lt;sp:TransportToken&gt;
 		   &lt;wsp:Policy&gt;
 		      &lt;sp:HttpsToken RequireClienCertificate="false" /&gt;
-              &lt;/wsp:Policy&gt;
-            &lt;/sp:TransportToken&gt;
-            &lt;sp:AlgorithmSuite&gt;
-              &lt;wsp:Policy&gt;
-		      &lt;sp:Basic256Rsa15 /&gt;
-              &lt;/wsp:Policy&gt;
-            &lt;/spAlgorithmSuite&gt;
-       &lt;/sp:TransportBinding&gt;
+                   &lt;/wsp:Policy&gt;
+                 &lt;/sp:TransportToken&gt;
+                 &lt;sp:AlgorithmSuite&gt;
+                    &lt;wsp:Policy&gt;
+		       &lt;sp:Basic256Rsa15 /&gt;
+                    &lt;/wsp:Policy&gt;
+                 &lt;/spAlgorithmSuite&gt;
+              &lt;/Policy&gt;
+           &lt;/sp:TransportBinding&gt;
 	   &lt;sp:AsymmetricBinding&gt;
-
-&lt;/sp:AssymetricBinding&gt;
+           &lt;/sp:AssymetricBinding&gt;
 	&lt;/ExactlyOne&gt;
-
 &lt;/wsp:Policy&gt;
 
 &lt;wsdl:binding name="CompanyADefaultBinding" type="tns:CompanyADefault"&gt; 
@@ -1574,11 +1603,16 @@
 						<td>MH</td>
 						<td>Editorial fixes for readability, added example for Encrypted parts</td>
 					</tr>
-<tr>
+					<tr>
 						<td>20061030</td>
 						<td>UY</td>
 						<td>Fixes for Paul Cotton's editorial comments (20061020)</td>
 					</tr>
+					<tr>
+						<td>20061031</td>
+						<td>UY</td>
+						<td>Fixes for Frederick's editorial comments (20061025)</td>
+					</tr>
 				</tbody>
 			</table>
 		</inform-div1>
Received on Wednesday, 1 November 2006 01:18:33 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:20:58 GMT