- From: Maryann Hondo via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 18 Oct 2006 21:25:08 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv10233
Modified Files:
ws-policy-guidelines.xml
Log Message:
updated with editorial changes & examples
Index: ws-policy-guidelines.xml
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- ws-policy-guidelines.xml 14 Oct 2006 03:06:37 -0000 1.4
+++ ws-policy-guidelines.xml 18 Oct 2006 21:25:06 -0000 1.5
@@ -182,25 +182,33 @@
and responsibilities for the authors, consumers and providers.
</p>
<div3 id="domain-owners">
- <head> Domain Owners/WS-Policy Authors</head>
- <p> WS-Policy Domain owners (or WS-Policy authors) are defined
+ <head> WS-Policy Authors</head>
+ <p> WS-Policy Domain owners or WS-Policy authors are defined
by the WS-Policy Framework to be 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
WS-Policy Framework is based on a declarative model, meaning
- that it is incumbent on the WS-Policy authors to define the
+ that it is incumbent on the WS-Policy authors to define both the semantics of
+ the assertions as well as the
scope of their target domain in their specification. The set
- of metadata will vary in the granularity of assertion
- specification, and it is therefore important for WS-Policy
- authors to clearly identify their scope (i.e, the variables of
- the WS-ReliableMessaging specification). It is the intent of
- this primer to help communities utilize the framework in such
+ of metadata for any particular domain will vary in the granularity of assertion
+ specification required. It is the intent of
+ this document to help communities utilize the framework in such
a way that multiple WS-Policy domains can co-exist and
consumers and providers can utilize the framework consistently
across domains.
</p>
- <p>An example of this can be seen in the WS-SecurityPolicy
+ <p>In order to take advantage of the WS-Policy Framework, any
+ domain author attempting to define new WS-Policy assertions
+ must adhere to the MUST's and SHOULD's in the specifications
+ and should review the conformance section of the
+ specification. </p>
+ <p>WS-Policy Domain authors must also specify how to associate
+ the assertions they have defined with the policy subjects
+ identified by the WS-PolicyAttachment specification</p>
+ <p>An example of a domain specificatin that includes these properties
+ can be seen in the WS-SecurityPolicy
specification. The WS-Security authors have defined their
scope as follows: </p>
<p>
@@ -219,24 +227,17 @@
information necessary to actually enable a participant to
engage in a secure exchange of messages." </emph>
</p>
- <p>In order to take advantage of the WS-Policy Framework, any
- domain author attempting to define new WS-Policy assertions
- must adhere to the MUST's and SHOULD's in the specifications
- and should review the conformance section of the
- specification. </p>
- <p>WS-Policy Domain authors must also specify how to associate
- the assertions they have defined with the policy subjects
- identified by the WS-PolicyAttachment specification</p>
- <p>An example of this is also provided by the WS-Security
+
+ <p>An example of scoping individual assertions to policy subjects is also provided by the WS-Security
Policy specification in Appendix A.</p>
</div3>
<div3 id="consumers">
<head>Consumers</head>
- <p>Consumers of WS-Policy Assertions can be any entity that is
+ <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, that it then uses to govern its
- creation of a message to send to the subject that advertised
- the WS-Policy expression. The WS-Policy Attachment
+ alternative from the policy, that it then uses to govern the
+ creation of a message to send to the subject to which the policy alternative
+ was attached. The WS-Policy Attachment
specification defines a set of attachment models for use with
common web service subjects: WSDL definitions, UDDI directory
entries, and WS-Addressing endpoints.
@@ -256,8 +257,8 @@
</div3>
<div3 id="providers">
<head>Providers</head>
- <p>Providers of WS-Policy Assertions can be any web service
- implementation that can specify its on the wire message
+ <p>A provider of WS-Policy Assertions can be any web service
+ implementation that can reflect its on the wire message
behavior as an XML expression that conforms to the
WS-PolicyFramework and WS-PolicyAssertions
specifications. The WS-PolicyAttachment specification has
@@ -268,8 +269,8 @@
requirements of other policy specifications it utilizes (
i.e., WS-SecurityPolicy).
</p>
- <p>Also it is useful for providers to take into account how
- to evolve their services capabilities. If forward
+ <p>Whe deploying services with policies it is uesful for providers to anticipate how
+ 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 <specref ref="lifecycle"/> and
@@ -283,16 +284,13 @@
<head>General Guidelines for WS-Policy Assertion Authors</head>
<div2 id="assertion-target">
<head>Assertions and Their Target Use</head>
- <p>When a community of WS-Policy authors decides to define
- a set of WS-Policy assertions they should understand what
- functionality the framework provides and apply the
+ <p>WS-Policy authors need to have some definition of what the goal is for the assertions
+ they author. WS-Policy authors should also understand the
+ functionality the WS-Policy framework provides and apply the
knowledge of framework processing when defining the set of
- assertions. This will require the WS-Policy authors to have
- some definition and/or understanding of what the goal is
- for the use of the assertions.
+ assertions.
</p>
- <p>Assertions can be simple or they can be complex. A set
- of WS-Policy authors may choose to specify one or two
+ <p>Assertions can be simple or they can be complex. WS-Policy authors may choose to specify one or two
assertions or they may choose to specify many assertion
elements that require parameters or other nested
assertions. There are advantages to simplifying the set of
@@ -306,19 +304,15 @@
considered.
</p>
<p>The number of different subjects to which an assertion
- can be associated is also a factor when defining an
- assertion. It is possible that WS-Policy assertions will be
- consumed by a wide range of client configurations, from
+ can be attached is also a factor when defining an
+ assertion. Determining the appropriate policy subjects can sometimes
+ involve understanding the requirements of wide range of client configurations, from
stand alone client applications to "active" web service
- requestors that are capable of adapting to constraints and
- capabilities modifying their own configurations
- dynamically. If the assertion is intended to be consumed
- by a broad range of clients, then the behavior should be
- simple for all of these clients to understand and
- implement.
+ requestors that are capable of modifying their own configurations
+ dynamically.
</p>
- <p> Once the subjects are identified, one way of attaching
- multiple instances of a simple policy assertion is to
+ <p> Once the range of policy subjects are identified, there are choices for ways of attaching
+ multiple instances of a simple policy assertion to multiple subjects. One way is to
utilize the referencing mechanism that is present in the
framework. By defining the assertion once and using it in
different policies (e.g. with different alternatives) via
@@ -329,7 +323,7 @@
files, EPRs, in which the same set of policies are expected
to be applied.
</p>
- <p>WS-Policy domain authors should consider the following
+ <p>In summary, WS-Policy domain authors should consider the following
factors when composing the set of domain assertions as it
may make sense to factor out some assertions that can be
used by multiple subjects:
@@ -443,7 +437,9 @@
</example>
<p> Note that both authoring styles are equivalent, however
there may be reasons to choose one form over another
- depending on the use. The compact form is more
+ depending on the use. For example, when multiple alternatives are present
+ in a policy, the normal form may express the choices more explicitly.
+ On the other hand, the compact form is more
readable for humans when an assertion is marked as optional
using the <code>@optional</code>attribute as our example
illustrates above.
@@ -451,30 +447,7 @@
</div1>
<div1 id="modeling-guidelines">
<head>Guidelines for Modeling New Assertions</head>
- <div2 id="single-domains">
- <head>Single Domains</head>
- <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 can be well defined. A domain
- that expresses a broad set of capabilities will need to have
- community support to provide value to the consumers.
- Ultimately it is the consumers and providers that will
- determine whether a particular set of assertions correctly
- characterize the domain. A community should avoid duplicating
- assertions that have already been defined as this will create
- ambiguity not clarification and focus on creating assertions
- for those specific constraints and capabilities that do not
- overlap with other domains but that communicate new
- functionality. </p>
- <p>The model advocated is an "opt-in" model. Namely, the
- providers of services should invest to find the set of
- assertions useful to improve interoperability of services 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>
- </div2>
+
<div2 id="new-domains">
<head>New Policy Domains</head>
<p>When creating a new policy domain, it is important to
@@ -510,6 +483,31 @@
expressions.
</p>
</div2>
+ <div2 id="single-domains">
+ <head>Single Domains</head>
+ <p>When considering the creation of a new domain of policy
+ assertions, it is important to identify whether or not the domain is self containted
+ 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 supportin implementation 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 duplicating
+ assertions that have already been defined as this will create
+ ambiguity not clarification. New WS-Policy authors should focus on creating assertions
+ for those specific constraints and capabilities that do not
+ overlap with other domains but that communicate new
+ functionality. </p>
+ <p>The model advocated for new assertion development is a cooperative marketplace
+ [some might say its an "opt-in" model]. The
+ providers 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>
+ </div2>
<div2 id="nested-assertions">
<head>Nested Assertions</head>
<p>The framework provides the ability to "nest" policy
@@ -592,7 +590,7 @@
<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 to qualify an assertion. For some domains it
+ 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>
@@ -628,16 +626,27 @@
to the WS-Policy framework. The tradeoff is the generality
vs. the flexibility and complexity of the comparison expected
for a domain.
-
- </p>
- <!-- EDS TODO ADD THE EARLIER EXAMPLE FROM THE AUTHORS DOCUMENT -->
+ <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>
+ </p> <head>Policy Assertion with Assertion Parameters</head>
+ <example>
+ <eg xml:space="preserve"><Policy>
+ <sp:SignedParts>
+ <sp:Body />
+ <sp:Header />
+ </sp:SignedParts>
+ …
+</Policy></eg>
+ </example>
+
</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 on the message's
- path, not specifically declare properties of the messages
- themselves. One of the advantages of Web services is that an XML
+ 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
@@ -652,25 +661,21 @@
uses of the Ws-Policy framework.
</p>
<p>The assertion authors should take into account that there are
- two important concepts when designing assertions. Firstly, an
+ 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 by additional data
- or metadata that is present in a message. If such a relationship
- exists, it should be incorporated into an assertion design
- document that illustrates the disambiguation of the usage of the
- policy at runtime and in the message if that message is
- persisted.
+ 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 iteself.
</p>
<p>As a result, Policy assertions should not be used to express
- what otherwise should be part of the message. If a property is
+ the semantics of a message. If a property is
required to understand a message, it should be communicated in
- the message, or made available to in a message (e.g., being
+ 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. Thus, the assertion definition should specify how
- the presence of the property will determine the engagement of the
- behavior indicated by the assertion.
+ policy element.
</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
@@ -823,21 +828,14 @@
</p>
<example><p>EXAMPLE</p></example>
</div2>
- <div2 id="subject-scoping-considerations">
- <head>Subject Scoping Considerations</head>
- <p> Appendix A. Which assertions </p>
- <p>Enabled versioning. Conservative composites. </p>
- <p> Anti patterns. Interaction between the subjects and interaction between different attachment points. How you can get into trouble. </p>
- <p>Give wS-RX as example. </p>
- <p>Give examples for WSDL 1.0. </p>
- </div2>
+
<div2 id="levels-of-abstraction">
<head>Levels of Abstraction in WSDL </head>
<p>A behavior identified by a policy assertion applies to the
associated policy subject. If a policy assertion is to be used
within WSDL, policy assertion authors must specify a WSDL
policy subject. The policy subject is determined with respect
- to a behavior as follows behavior?
+ to a behavior as follows:
</p>
<ulist>
<item>
@@ -861,17 +859,14 @@
output and fault message policy subjects.</p>
</item>
</ulist>
- <p>The authors need to understand how the assertions will be
+ <p>WS-Policy authors that wish to utilize WSDL policy subjects need to understand how the assertions will be
processed in intersection and merging and the implications of
the processing for considering a specific attachment point and
policy subject. This topic is considered in detail in <bibref ref="WS-Policy-Primer"/>
</p>
<p>The current set of subjects as mapped to the WSDL 1.1
- elements, can constrain the assertion constructs to a WSDL
- exchange if the authors so choose. For Example, In WS-RM,
- there was not a WSDL subject that was appropriate to some of
- the characteristics of a reliable messaging exchange and the
- domain authors chose to not support certain capabilities at
+ elements, can also constrain the assertion constructs. For Example, In WS-RM,
+ the domain authors chose to support certain capabilities at
the endpoint level. This resulted in the finer granularity of
the assertion to apply at the message policy subject, but the
assertion semantics also indicates that the if the senders
@@ -942,7 +937,8 @@
</div2>
<div2 id="lifecycle">
<head>Lifecycle of Assertions</head>
- <p>There are three aspects that govern an assertions lifecycle:</p>
+ <p>WS-Policy 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 that govern an assertions lifecycle:</p>
<ulist>
<item>
<p> Assertion Extensibility </p>
@@ -956,12 +952,13 @@
</ulist>
<div3 id="Referencing_Policy_Expressions">
<head>Referencing Policy Expressions</head>
- <p>The <bibref ref="WS-Policy-Primer"/> illustrates how the
- utilizing identification mechanism can be useful for exposing
- a complex policy expression as a reusable building block for
+ <p>The <bibref ref="WS-Policy-Primer"/> 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. Domain assertion
- authors, especially those utilizing complex assertions that
- include nesting or complex types should consider utilizing
+ authors, especially those defining complex assertions that
+ include nesting or complex types should consider specifying or recommending
naming conventions in order to promote reuse. Reuse through
referencing allows a policy expression to be utilized not only
within another expression but also allows specification of
@@ -1007,10 +1004,10 @@
</div1>
<div1 id="inter-policy">
<head>Inter-domain Policy and Composition Issues</head>
- <p>Domain authors must be aware of the interactions between
- different domains. For example, security assertions interact
+ <p>Domain authors must be aware of the interactions between their
+ domain and other domains. For example, security assertions interact
with other protocol assertions in a composition. Although
- modeling such assertions may appear independent behaviors,
+ modeling protocol assertions may appear to be an independent behavior,
protocol assertions and security assertions affect transport
bindings and their interactions must be considered. For
example, utilization of WS-Security Policy with other
@@ -1071,11 +1068,7 @@
<p>To illustrate the topics explored in this document, we
include an example of a web service and how a fictitous company
might utilize the WS-Policy Framework to enable Web Service
- interoperability. In addition we provide the following matrix:</p>
- <example>
- <p>ADD MATRIX</p>
- </example>
- <p>CompanyA has determined to utilize WS-Security,
+ interoperability. CompanyA has determined to utilize WS-Security,
WS-Addressing and WS-Reliable Messaging in all its new web
service offerings and has instructed its developers to use the
policy assertions defined by the following documents: </p>
@@ -1532,6 +1525,11 @@
<td>UY</td>
<td>Editorial fixes (suggested by Frederick), fixed references, bibl items, fixed dangling pointers, created eds to do</td>
</tr>
+ <tr>
+ <td>20061018</td>
+ <td>MH</td>
+ <td>Editorial fixes for readability, added example for Encrypted parts</td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Wednesday, 18 October 2006 21:25:24 UTC