- From: Maryann Hondo via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 25 Apr 2007 13:42:08 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv16871
Modified Files:
ws-policy-guidelines.xml
Log Message:
Updated 5.3 "Considerations when Modeling New Assertions" related to issue 3989 [Editorial Action 229] Restructured text to follow examples
Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.58
retrieving revision 1.59
diff -u -d -r1.58 -r1.59
--- ws-policy-guidelines.xml 24 Apr 2007 18:26:05 -0000 1.58
+++ ws-policy-guidelines.xml 25 Apr 2007 13:42:04 -0000 1.59
@@ -593,19 +593,15 @@
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 <bibref ref="WS-RM-Policy"/> to see an example of a
+ </p>
+ <p role="practice" id="bp-assertion-start"><quote>Starting to Build an Assertion</quote><quote>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. </quote>
+ </p>
+ <p>New Assertion Authors are encouraged to look at <bibref ref="WS-RM-Policy"/> to see an example of a
relatively simple domain that has defined three assertions. Assertion Authors are encouraged to look at <bibref
ref="WS-SecurityPolicy"/> 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>
- <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">
<head>QName and XML Information Set representation</head>
@@ -616,13 +612,22 @@
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 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. </quote>
+ </p>
<p>The syntax of an assertion can be represented using an XML outline (plus an XML schema
document). If the assertion has a nested policy expression then the assertion XML
- outline can enumerate the nested assertions that are allowed.
+ outline can enumerate the nested assertions that are allowed. An example is the following:
</p>
- <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.
- </quote> </p>
+ <example>
+ <eg>
+ <wsrmp:RMAssertion [wsp:Optional="true"]? ...>
+ ...
+ </wsrmp:RMAssertion/>
+ </eg>
+ </example>
+
</div3>
<div3 id="self-describing">
<head> Self Describing Messages </head>
@@ -632,48 +637,42 @@
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 <bibref ref="SAWSDL"/>.
- </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 <emph>runtime</emph> 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>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 <bibref ref="SAWSDL"/>.
</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>
+ 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>
- <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 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.
+ Firstly, an assertion type indicates a <emph>runtime</emph> 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.
+ </quote>
</p>
+ <p>For example, if the details of a message's encryption ( e.g., the cipher used, etc) are expressed
+ in policy that isn't attached to the message, it isn't possible
+ 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>
</div3>
<div3 id="single-domains">
<head>Single Domains</head>
@@ -681,8 +680,8 @@
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
@@ -699,11 +698,9 @@
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>
- <p role="practice" id="bp-assertion-duplication"><quote>Duplication of Assertions</quote><quote>Avoid duplication of assertions.</quote>
+ <p role="practice" id="bp-assertion-duplication"><quote>Duplication of Assertions</quote><quote>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. </quote>
</p>
</div3>
</div2>
@@ -2124,7 +2121,13 @@
<td>Updated 5.5 Designating Optional Behaviors for
<loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3989">issue 3989</loc>. 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>
+ </tr>
+ <tr>
+ <td>20070425</td>
+ <td>MH</td>
+ <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>
</tbody>
</table>
</inform-div1>
Received on Wednesday, 25 April 2007 13:42:14 UTC