- From: Toufic Boubez via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 25 Apr 2007 17:52:39 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv24479
Modified Files:
ws-policy-guidelines.xml ws-policy-guidelines.html
Log Message:
Updated 5.2 Authoring Styles for issue 3989 and editors' action item 227
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.44
retrieving revision 1.45
diff -u -d -r1.44 -r1.45
--- ws-policy-guidelines.html 24 Apr 2007 18:26:05 -0000 1.44
+++ ws-policy-guidelines.html 25 Apr 2007 17:52:37 -0000 1.45
@@ -137,9 +137,9 @@
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="#d3e650">Optional behavior in Compact authoring</a><br>
- 5.5.2 <a href="#d3e658">Optional behavior at runtime</a><br>
- 5.5.2.1 <a href="#d3e703">Example</a><br>
+ 5.5.1 <a href="#d3e657">Optional behavior in Compact authoring</a><br>
+ 5.5.2 <a href="#d3e665">Optional behavior at runtime</a><br>
+ 5.5.2.1 <a href="#d3e710">Example</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>
@@ -418,76 +418,84 @@
The semantics a policy assertion should not depend on the
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
- policy operators, and a policy reference/inclusion mechanism.
- </p><div class="exampleOuter"><div class="exampleInner"><pre><wsp:Policy xmlns:wsp='http://www.w3.org/ns/ws-policy'
- xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'
- xmlns:wsrmp='http://docs.oasis-open.org/ws-rx/wsrmp/200608'>
- <wsrmp:RMAssertion wsp:Optional="true"/>
- <wsp:ExactlyOne>
- <wsp:All>
- <sp:TransportBinding>
- <wsp:Policy>
- <sp:TransportToken>
- <wsp:Policy>
- <sp:HttpsToken RequireClientCertificate='true' />
- </wsp:Policy>
- </sp:TransportToken>
- </sp:TransportBinding>
- </wsp:All>
- </wsp:ExactlyOne>
-</wsp:Policy></pre></div></div><p>A policy expression in the compact form can be translated into its
- normal form using the policy normalization algorithm described in the
- Web Service Policy Framework (see section 4.3 Compact Policy
- Expression).
- </p><div class="exampleOuter"><div class="exampleInner"><pre><wsp:Policy xmlns:wsp='http://www.w3.org/ns/ws-policy'
- xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'
- xmlns:wsrmp='http://docs.oasis-open.org/ws-rx/wsrmp/200608'>
- <wsp:ExactlyOne>
-
- <wsp:All>
- <wsrmp:RMAssertion/>
- <sp:TransportBinding>
- <wsp:Policy>
- <sp:TransportToken>
- <wsp:Policy>
- <sp:HttpsToken RequireClientCertificate='true' />
- </wsp:Policy>
- </sp:TransportToken>
- </wsp:Policy>
- </sp:TransportBinding>
- </wsp:All>
-
- <wsp:All>
- <sp:TransportBinding>
- <wsp:Policy>
- <sp:TransportToken>
- <wsp:Policy>
- <sp:HttpsToken RequireClientCertificate='true' />
- </wsp:Policy>
- </sp:TransportToken>
- </wsp:Policy>
- </sp:TransportBinding>
- </wsp:All>
-
- </wsp:ExactlyOne>
-</wsp:Policy></pre></div></div><p>These two forms of the same policy expression are semantically
- equivalent. When multiple alternatives are present in a policy, the
- normal form may express the choices more explicitly. On the other hand,
- the compact form may be more readable for humans when an assertion is
- marked as optional using the <code>wsp:optional</code> attribute as our example
- illustrates above.</p><p>A policy processor may normalize a policy expression originally authored
- in compact form at any time without changing the semantics of the
- policy. In general, it is not possible to guarantee in what form a
- 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><div class="boxedtext"><p><a name="bp-semantics-and-form" id="bp-semantics-and-form"></a><span class="practicelab">Good
+ 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
+ policy operators, and a policy reference/inclusion mechanism.
+ A policy expression in the compact form can be translated into its
+ normal form using the policy normalization algorithm described in the
+ Web Service Policy Framework (see section 4.3 Compact Policy
+ Expression).
+ </p><p>The two forms of a policy expression are semantically
+ equivalent. When multiple alternatives are present in a policy, the
+ normal form may express the choices more explicitly. On the other hand,
+ the compact form may be more readable for humans when an assertion is
+ marked as optional using the <code>wsp:optional</code> attribute.
+ A policy processor may normalize a policy expression originally authored
+ in compact form at any time without changing the semantics of the
+ policy. In general, it is not possible to guarantee in what form a
+ 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><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><div class="div2">
+ assertion.</p></div><p>
+ In the example below, the policy expression is shown in its two forms,
+ compact and normal. In compact form, the <code>wsrmp:RMAssertion</code> assertion
+ is augmented by the <code>wsp:Optional="true"</code> attribute.
+ While the compact form of the expression might be more human readable, the semantics of the
+ particular assertion are independent of the form and of the presence (or absence)
+ of the <code>wsp:optional</code> attribute.
+ </p><div class="exampleOuter">
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-1. </span>Policy Expression in Compact Form</i></p><div class="exampleInner"><pre><wsp:Policy xmlns:wsp='http://www.w3.org/ns/ws-policy'
+ xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'
+ xmlns:wsrmp='http://docs.oasis-open.org/ws-rx/wsrmp/200608'>
+<wsrmp:RMAssertion wsp:Optional="true"/>
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <sp:TransportBinding>
+ <wsp:Policy>
+ <sp:TransportToken>
+ <wsp:Policy>
+ <sp:HttpsToken RequireClientCertificate='true' />
+ </wsp:Policy>
+ </sp:TransportToken>
+ </wsp:Policy>
+ </sp:TransportBinding>
+ </wsp:All>
+ </wsp:ExactlyOne>
+</wsp:Policy></pre></div></div><div class="exampleOuter">
+<p style="text-align: left" class="exampleHead"><i><span>Example 5-2. </span>Policy Expression in Normal Form</i></p><div class="exampleInner"><pre><wsp:Policy xmlns:wsp='http://www.w3.org/ns/ws-policy'
+ xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'
+ xmlns:wsrmp='http://docs.oasis-open.org/ws-rx/wsrmp/200608'>
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <wsrmp:RMAssertion/>
+ <sp:TransportBinding>
+ <wsp:Policy>
+ <sp:TransportToken>
+ <wsp:Policy>
+ <sp:HttpsToken RequireClientCertificate='true' />
+ </wsp:Policy>
+ </sp:TransportToken>
+ </wsp:Policy>
+ </sp:TransportBinding>
+ </wsp:All>
+
+ <wsp:All>
+ <sp:TransportBinding>
+ <wsp:Policy>
+ <sp:TransportToken>
+ <wsp:Policy>
+ <sp:HttpsToken RequireClientCertificate='true' />
+ </wsp:Policy>
+ </sp:TransportToken>
+ </wsp:Policy>
+ </sp:TransportBinding>
+ </wsp:All>
+ </wsp:ExactlyOne>
+</wsp:Policy></pre></div></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.
@@ -510,74 +518,71 @@
assertions to define. Interoperability testing of new policy
domains is recommended to ensure that consumers and providers
are able to use the new domain assertions.
- </p><p>New Assertion Authors are encouraged to look at <cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite> to see an example of a
+ </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.
+ As your design work progresses, you may add more parameters or nested policy assertions to meet
+ your interoperability needs. </p></div><p>New Assertion Authors are encouraged to look at <cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite> to see an example of a
relatively simple domain that has defined three assertions. Assertion Authors are encouraged to look at <cite><a href="#WS-SecurityPolicy">WS-SecurityPolicy</a></cite> to see an example of a complex domain that has been decomposed into a set of policy expressions.
- </p><p>How big should an assertion be? How many assertion parameters should the assertion
- enumerate? How many dependent behaviors should the assertion enumerate? It is always
- 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><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">
+ </p></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
represent an assertion parameter as a child element (by leveraging natural XML nesting)
or an attribute of an assertion. The general guidelines on when to use XML elements
- 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><div class="boxedtext"><p><a name="bp-unique-qnames" id="bp-unique-qnames"></a><span class="practicelab">Good
+ versus attributes apply.</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><div class="div3">
+ (plus an XML schema document) to specify the syntax of an assertion. </p></div><p>The syntax of an assertion can be represented using an XML outline (plus an XML schema
+ document). If the assertion has a nested policy expression then the assertion XML
+ outline can enumerate the nested assertions that are allowed. An example is the following:
+ </p><div class="exampleOuter"><div class="exampleInner"><pre>
+ <wsrmp:RMAssertion [wsp:Optional="true"]? ...>
+ ...
+ </wsrmp:RMAssertion/>
+ </pre></div></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
available, these capabilities suffer.
- </p><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. Note that there are other specifications that target specification of semantics of a message, such as <cite><a href="#SAWSDL">SAWSDL</a></cite>.
- </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><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.
- </p><p>Firstly, an assertion type indicates a <em>runtime</em> behavior.
- </p><p>Secondly, Assertion Authors need to indicate how the runtime behavior represented in 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>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.
+ Note that there are other specifications that target specification of semantics of a message, such as <cite><a href="#SAWSDL">SAWSDL</a></cite>.
</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. </p><p>Another approach is to use of the assertion to selectively apply to subjects. For example, a
+ 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 cannot be self describing.
</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">
+practice 6: Assertions and Message Semantics</span></p><p class="practice">Policy assertions should not be used to express the semantics of a message.
+ Firstly, an assertion type indicates a runtime behavior. Secondly, Assertion Authors need to indicate how the runtime behavior represented in 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></div><p>For example, if the details of a message's encryption ( e.g., the cipher used, etc) are expressed
+ in policy that isn't attached to the message, it isn't possible
+ to later decipher it. This is very different from expressing, in
+ policy, what ciphers (and so forth) are supported by a particular
+ endpoint, or those that are required in a particular message; the
+ latter are the intended uses of the WS-Policy framework.
+ </p></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
- expresses a broad set of capabilities will also need to have
- community supporting implementations to provide value to the
+ expresses a broad set of capabilities will also need to have a
+ community supporting implementations of these capabilities to provide value to the
consumers. Ultimately it is the consumers and providers that
will determine whether a particular set of assertions
correctly characterize a domain. A new community should avoid
@@ -592,11 +597,10 @@
of services need to find value in the set of
assertions or they will not include the assertions in
their service descriptions.
- </p><p>A review by a broad community is
- the best way to ensure that the granularity of a set of domain
- assertions is appropriate.
- </p><div class="boxedtext"><p><a name="bp-assertion-duplication" id="bp-assertion-duplication"></a><span class="practicelab">Good
-practice 7: Duplication of Assertions</span></p><p class="practice">Avoid duplication of assertions.</p></div></div></div><div class="div2">
+ </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.
+ A review by a broad community is the best way to ensure that the granularity of a set of domain
+ assertions is appropriate. </p></div></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.
@@ -618,7 +622,7 @@
<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 5-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-4. </span>Policy Assertion with Assertion Parameters</i></p><div class="exampleInner"><pre><wsp:Policy>
<sp:SignedParts>
<sp:Body/>
<sp:Header/>
@@ -664,7 +668,7 @@
already requires the use of transport-level security for
protecting messages).
</p><div class="exampleOuter">
-<p style="text-align: left" class="exampleHead"><i><span>Example 5-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-5. </span>Transport Security Policy Assertion</i></p><div class="exampleInner"><pre><sp:TransportBinding>
<Policy>
<sp:TransportToken>
<Policy>
@@ -708,7 +712,7 @@
<code>HttpToken</code> is used with an empty nested policy in a policy expression
by a provider, it will indicate that none of the dependent behaviors
namely authentication or client certificate is required.</p><div class="exampleOuter">
-<p style="text-align: left" class="exampleHead"><i><span>Example 5-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-6. </span>Empty Nested Policy Expression</i></p><div class="exampleInner"><pre><sp:TransportToken>
<wsp:Policy>
<sp:HttpsToken>
<wsp:Policy/>
@@ -747,7 +751,7 @@
delegated to the specific domain handlers that are not visible
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="d3e650" id="d3e650"></a>5.5.1 Optional behavior in Compact authoring</h4><p>Optional behaviors represent behaviors that may be engaged by a consumer. When using the
+<h4><a name="d3e657" id="d3e657"></a>5.5.1 Optional behavior in Compact authoring</h4><p>Optional behaviors represent behaviors that may be engaged by a consumer. When using the
compact authoring form for assertions, such behaviors are marked by
using <code>wsp:Optional</code> attribute with a value of
"true". (In order to simplify reference to such assertions,
@@ -761,7 +765,7 @@
include policy alternatives in a policy expression, by using
the wsp:Optional attribute.
</p></div><div class="div3">
-<h4><a name="d3e658" id="d3e658"></a>5.5.2 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
+<h4><a name="d3e665" id="d3e665"></a>5.5.2 Optional behavior at runtime</h4><p>Since optional behaviors indicate optionality for
both the provider and the consumer, behaviors that must
always be engaged by a consumer must not be marked as
"optional" with a value "true" since this would allow the
@@ -816,7 +820,7 @@
</p><div class="boxedtext"><p><a name="bp-indicate-optional-assertion-use" id="bp-indicate-optional-assertion-use"></a><span class="practicelab">Good
practice 12: Indicate use of an Optional Assertion</span></p><p class="practice">When a given behavior may be optional, it must be possible for both message participants to determine that the assertion is selected by both parties,
either out of band or as reflected by the message content.</p></div><div class="div4">
-<h5><a name="d3e703" id="d3e703"></a>5.5.2.1 Example</h5><p>
+<h5><a name="d3e710" id="d3e710"></a>5.5.2.1 Example</h5><p>
The <cite><a href="#WS-Policy-Primer">Web Services Policy Primer</a></cite> document contains an example that outlines the
use of
<cite><a href="#MTOM">MTOM</a></cite> as an optional behavior that can be engaged by a consumer.
@@ -1459,4 +1463,9 @@
</td></tr><tr><td rowspan="1" colspan="1">20070321</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Updated section <a href="#change-description"><b>E. Changes in this Version of
the Document</b></a>. </td></tr><tr><td rowspan="1" colspan="1">20070329</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Changed all <p>Best Practice: to <p role="practice"></td></tr><tr><td rowspan="1" colspan="1">20070416</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Updated 6.2 and 6.3 for <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>. Note, removed one best practice that was a dup.</td></tr><tr><td rowspan="1" colspan="1">20070423</td><td rowspan="1" colspan="1">FJH</td><td rowspan="1" colspan="1">Updated 5.5 Designating Optional Behaviors for
<a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>. Added informative reference for MTOMPolicy.
- Added two best practices, one is similar to G16 but focused on optional. Revised practice that was there.</td></tr></tbody></table><br></div></div></body></html>
\ No newline at end of file
+ Added two best practices, one is similar to G16 but focused on optional. Revised practice that was there.</td></tr><tr><td rowspan="1" colspan="1">20070425</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">Updated 5.3 "Considerations when Modeling New Assertions" related to
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>. [Editorial Action 229] Restructured text to follow examples</td></tr><tr><td rowspan="1" colspan="1">20070425</td><td rowspan="1" colspan="1">TIB</td><td rowspan="1" colspan="1">Updated 5.2 Authoring Styles for
+ <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</a>
+ and editors' action item
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/227">227</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.59
retrieving revision 1.60
diff -u -d -r1.59 -r1.60
--- ws-policy-guidelines.xml 25 Apr 2007 13:42:04 -0000 1.59
+++ ws-policy-guidelines.xml 25 Apr 2007 17:52:37 -0000 1.60
@@ -475,95 +475,103 @@
attachment mechanism used.</quote>
</p>
</div2>
- <div2 id="compact-full">
+
+ <div2 id="compact-full">
<head>Authoring Styles </head>
- <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
- policy operators, and a policy reference/inclusion mechanism.
- </p>
+ <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
+ policy operators, and a policy reference/inclusion mechanism.
+ A policy expression in the compact form can be translated into its
+ normal form using the policy normalization algorithm described in the
+ Web Service Policy Framework (see section 4.3 Compact Policy
+ Expression).
+ </p>
+ <p>The two forms of a policy expression are semantically
+ equivalent. When multiple alternatives are present in a policy, the
+ normal form may express the choices more explicitly. On the other hand,
+ the compact form may be more readable for humans when an assertion is
+ marked as optional using the <code>wsp:optional</code> attribute.
+ A policy processor may normalize a policy expression originally authored
+ in compact form at any time without changing the semantics of the
+ policy. In general, it is not possible to guarantee in what form a
+ 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 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.</quote>
+ </p>
+ <p>
+ In the example below, the policy expression is shown in its two forms,
+ compact and normal. In compact form, the <code>wsrmp:RMAssertion</code> assertion
+ is augmented by the <code>wsp:Optional="true"</code> attribute.
+ While the compact form of the expression might be more human readable, the semantics of the
+ particular assertion are independent of the form and of the presence (or absence)
+ of the <code>wsp:optional</code> attribute.
+ </p>
+
<example>
- <eg xml:space="preserve"><wsp:Policy xmlns:wsp='&nsuri;'
- xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'
- xmlns:wsrmp='http://docs.oasis-open.org/ws-rx/wsrmp/200608'>
- <wsrmp:RMAssertion wsp:Optional="true"/>
- <wsp:ExactlyOne>
- <wsp:All>
- <sp:TransportBinding>
- <wsp:Policy>
- <sp:TransportToken>
- <wsp:Policy>
- <sp:HttpsToken RequireClientCertificate='true' />
- </wsp:Policy>
- </sp:TransportToken>
- </sp:TransportBinding>
- </wsp:All>
- </wsp:ExactlyOne>
+ <head>Policy Expression in Compact Form</head>
+<eg xml:space="preserve"><wsp:Policy xmlns:wsp='&nsuri;'
+ xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'
+ xmlns:wsrmp='http://docs.oasis-open.org/ws-rx/wsrmp/200608'>
+<wsrmp:RMAssertion wsp:Optional="true"/>
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <sp:TransportBinding>
+ <wsp:Policy>
+ <sp:TransportToken>
+ <wsp:Policy>
+ <sp:HttpsToken RequireClientCertificate='true' />
+ </wsp:Policy>
+ </sp:TransportToken>
+ </wsp:Policy>
+ </sp:TransportBinding>
+ </wsp:All>
+ </wsp:ExactlyOne>
</wsp:Policy></eg>
</example>
- <p>A policy expression in the compact form can be translated into its
- normal form using the policy normalization algorithm described in the
- Web Service Policy Framework (see section 4.3 Compact Policy
- Expression).
- </p>
-
-
<example>
- <eg xml:space="preserve"><wsp:Policy xmlns:wsp='&nsuri;'
- xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'
- xmlns:wsrmp='http://docs.oasis-open.org/ws-rx/wsrmp/200608'>
- <wsp:ExactlyOne>
-
- <wsp:All>
- <wsrmp:RMAssertion/>
- <sp:TransportBinding>
- <wsp:Policy>
- <sp:TransportToken>
- <wsp:Policy>
- <sp:HttpsToken RequireClientCertificate='true' />
- </wsp:Policy>
- </sp:TransportToken>
- </wsp:Policy>
- </sp:TransportBinding>
- </wsp:All>
-
- <wsp:All>
- <sp:TransportBinding>
- <wsp:Policy>
- <sp:TransportToken>
- <wsp:Policy>
- <sp:HttpsToken RequireClientCertificate='true' />
- </wsp:Policy>
- </sp:TransportToken>
- </wsp:Policy>
- </sp:TransportBinding>
- </wsp:All>
-
- </wsp:ExactlyOne>
+ <head>Policy Expression in Normal Form</head>
+<eg xml:space="preserve"><wsp:Policy xmlns:wsp='&nsuri;'
+ xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'
+ xmlns:wsrmp='http://docs.oasis-open.org/ws-rx/wsrmp/200608'>
+ <wsp:ExactlyOne>
+ <wsp:All>
+ <wsrmp:RMAssertion/>
+ <sp:TransportBinding>
+ <wsp:Policy>
+ <sp:TransportToken>
+ <wsp:Policy>
+ <sp:HttpsToken RequireClientCertificate='true' />
+ </wsp:Policy>
+ </sp:TransportToken>
+ </wsp:Policy>
+ </sp:TransportBinding>
+ </wsp:All>
+
+ <wsp:All>
+ <sp:TransportBinding>
+ <wsp:Policy>
+ <sp:TransportToken>
+ <wsp:Policy>
+ <sp:HttpsToken RequireClientCertificate='true' />
+ </wsp:Policy>
+ </sp:TransportToken>
+ </wsp:Policy>
+ </sp:TransportBinding>
+ </wsp:All>
+ </wsp:ExactlyOne>
</wsp:Policy></eg>
</example>
-
- <p>These two forms of the same policy expression are semantically
- equivalent. When multiple alternatives are present in a policy, the
- normal form may express the choices more explicitly. On the other hand,
- the compact form may be more readable for humans when an assertion is
- marked as optional using the <code>wsp:optional</code> attribute as our example
- illustrates above.</p>
- <p>A policy processor may normalize a policy expression originally authored
- in compact form at any time without changing the semantics of the
- policy. In general, it is not possible to guarantee in what form a
- 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 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.</quote></p>
- </div2>
-
+ </div2>
+
<div2 id="new-guidelines-domains">
<head>Considerations when Modeling New Assertions</head>
<p>When creating a new policy domain, it is important to
@@ -2128,6 +2136,15 @@
<td>Updated 5.3 "Considerations when Modeling New Assertions" related to
<loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</loc>. [Editorial Action 229] Restructured text to follow examples</td>
</tr>
+ <tr>
+ <td>20070425</td>
+ <td>TIB</td>
+ <td>Updated 5.2 Authoring Styles for
+ <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</loc>
+ and editors' action item
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/227">227</loc>
+ </td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Wednesday, 25 April 2007 17:53:21 UTC