- From: Asir Vedamuthu via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 30 Nov 2006 06:03:55 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy
In directory hutz:/tmp/cvs-serv16499
Modified Files:
ws-policy-guidelines.html ws-policy-guidelines.xml
Log Message:
Two changes:
a) Formatted examples in 5.2 Evolution of Assertions (Versioning and Compatibility).
b) Updated change log to record all the paper trails for revisions 1.16, 1.17 and 1.18
Index: ws-policy-guidelines.html
===================================================================
RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -d -r1.10 -r1.11
--- ws-policy-guidelines.html 29 Nov 2006 20:15:31 -0000 1.10
+++ ws-policy-guidelines.html 30 Nov 2006 06:03:53 -0000 1.11
@@ -63,29 +63,29 @@
guide to using the specifications. </p></div><div>
<h2><a name="status">Status of this Document</a></h2><p><strong>This document is an editors' copy that has
no official standing.</strong></p><p></p></div><hr><div class="toc">
-<h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#introduction">Introduction</a><br>2. <a href="#Assertions">What is an Assertion? </a><br>3. <a href="#d3e178">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"> WS-Policy 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 WS-Policy 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> &nbp; 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="#d3e513">Optional behavior in Compact authoring</a><br> 4.5.2 <a href="#d3e521">Optional behavior at runtime</a><br> 4.6 <a href="#typing-assertions">Typing Assertions</a><br> 4.7 <a href="#levels-of-abstraction">Levels of Abstraction in WSDL </a><br>5. <a href="#lifecycle">Lifecycle of Assertions</a><br> 5.1 <a href="#Referencing_Policy_Expressions">Referencing Policy Expressions</a><br> 5.2 <a href="#extending-assertions"> Factors in Extending Assertions within a Domain </a><br> 5.3 <a href="#assertion-evolution">Evolution of Assertions (Versioning and Compatibility)</a><br>6. <a href="#inter-policy">Inter-domain Policy and Composition Issues</a><br>7. <a href="#best-practices-attachment">Applying Best Practices for Policy Attachment</a><br> 7.1 <a href="#cotext-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="#scenerio">Scenario and a worked example</a><br></p>
+<h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#introduction">Introduction</a><br>2. <a href="#Assertions">What is an Assertion? </a><br>3. <a href="#d3e176">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"> WS-Policy 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 WS-Policy 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> &nbp; 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="#d3e514">Optional behavior in Compact authoring</a><br> 4.5.2 <a href="#d3e522">Optional behavior at runtime</a><br> 4.6 <a href="#typing-assertions">Typing Assertions</a><br> 4.7 <a href="#levels-of-abstraction">Levels of Abstraction in WSDL </a><br>5. <a href="#lifecycle">Lifecycle of 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>6. <a href="#inter-policy">Inter-domain Policy and Composition Issues</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 <ahref="#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="appendix" id="appendix">Appendices</a></h3><p class="toc">A. <a href="#security-considerations">Security Considerations</a><br>B. <a href="#xml-namespaces">XML Namespaces</a><br>C. <a href="#references">References</a><br>D. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<br>E. <a href="#change-description">Changes in this Version of
the Document</a> (Non-Normative)<br>F. <a href="#change-log">Web Services Policy 1.5 - Guidelines for Policy Assertion Authors Change Log</a> (Non-Normative)<br></p></div><hr><div class="body"><div class="div1">
-<h2><a name="introduction"></a>1. Introduction</h2><p>WS-Policy specification defines a policy to be a collection
- of policy alternatives, where each policy alternative is a
- collection of policy assertions. Policy is a flexible framework to represent
- consistent compinations of behaviors from a variety of domains.
- A policy assertion is a machine readable metadata exxpression that
+<h2><a name="introduction"></a>1. Introduction</h2><p>The WS-Policy specification defines a policy to be a collection
+ of policy alternatives with each policy alternative a
+ collection of policy assertions. The Web Services Policy 1.5 - Framework provides a flexible framework to
+ represent
+ consistent combinations of behaviors from a variety of domains.
+ A policy assertion is a machine readable metadata expression that
identifies behaviors required for Web services interactions.
<em>Web Services Policy 1.5 - Guidelines for Policy Assertion Authors</em>
- is a resource primarily for assertion authors that provides
+ is a resource primarily for assertion authors and provides
guidelines on the use of Web Services Policy 1.5 - Framework and
Web Services Policy 1.5 - Attachment specifications to create and use domain specific
assertions to enable interoperability.
</p><p>WS-Policy Assertions are XML expressions
that communicate the requirements and capabilities of a web
- service by adhering to the specification, WS-Policy Framework. It
- was recognized that in order to enable interoperability of web
- services, different sets of WS-Policy Assertions needed to be
- defined by different communities based upon the requirements of
+ service by adhering to the specification, WS-Policy Framework. To enable interoperability of web
+ services different sets of WS-Policy Assertions need to be
+ defined by different communities based upon domain-specific requirements of
the web service.
</p><p>The focus of these guidelines is to capture best practices
- and usage patterns for practitioners to follow. It is a
+ and usage patterns for practitioners. It is a
complementary guide to the Framework and Attachments
specifications and primer. It is intended to provide
non-normative guidelines for:
@@ -113,33 +113,35 @@
the question.
</p></div><div class="div1">
<h2><a name="Assertions"></a>2. What is an Assertion? </h2><p>An assertion is a piece of metadata that describes a
- capability of a specific WS-Policy domain. Sets of assertions
- are typically defined in a dedicated specification that describe
+ 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
as their data type definition using XML Schema.
- </p><p>Given that interoperability and automation are the motivations, policy assertions that
- represent, shared and visible behaviors are useful pieces of metadata. Such
- assertions enable tooling and improve interoperability. The key to understanding when to
+ </p><p>Policy assertions representing shared and visible behaviors are useful pieces of metadata to enable
+ interoperability and tooling for automation. The key to understanding when to
design policy assertions is to have clarity on the characteristics of a behavior
represented by a policy assertion. Some useful ways to discover relevant behaviors are
to ask questions like the following:
</p><ul><li><p>Is this behavior a requirement?
</p></li><li><p>Is the behavior visible?
- </p><p>A visible behavior refers to a requirement that manifests on the wire. Web services
+ </p><p>A visible behavior refers to a requirement that manifests itself on the wire. Web services
provide interoperable machine-to-machine interaction among disparate systems. Web
service interoperability is the capability of disparate systems to exchange data using
- common data formats and protocols such as messaging, security, reliability and
+ common data formats and protocols supporting characteristics such as messaging, security,
+ reliability and
transaction. Such data formats and protocols manifest on the wire. Providers and
- requesters only rely on these wire messages that conform to such formats and protocols
- for interoperability. If an assertion describes a behavior that does not manifest on the
- wire then the assertion is not relevant to an interoperable interaction.
- </p><p>For example, say an assertion describes the privacy notice information of a provider
- and there is an associated regulatory safeguard in place on the provider’s side. Such
+ requesters rely on wire messages conforming to such formats and protocols
+ to achieve interoperability.
+ </p><p>If an assertion describes a behavior that does not manifest on the
+ wire then the assertion is not relevant to an interoperable interaction.
+ An example is an assertion that describes the privacy notice information of a provider
+ and the associated regulatory safeguard in place on the provider’s side. Such
assertions may represent business or regulatory level metadata but do not add any value
to interoperability.
- </p><p>If an assertion has no wire- or message-level visible behavior, then the interacting
- participants may require some sort of additional non-repudiation mechanism to indicate
- compliance with the assertion. Introducing an additional non-repudiation mechanism adds
+ </p><p>If an assertion has no wire or message-level visible behavior then the interacting
+ participants may require some sort of additional mechanism to indicate
+ compliance with the assertion and to enable dispute resolution.
+ Introducing an additional non-repudiation mechanism adds
unnecessary complexity to processing a policy assertion.
</p></li><li><p>Does the behavior apply to two or more Web service participants?
</p><p>A shared behavior refers to a requirement that is relevant to an interoperable Web
@@ -148,13 +150,13 @@
relevant to an interoperable interaction. Non-shared behaviors do not add any value for
tooling or interoperability. An example of a non-shared behavior is the use of logging
or auditing by the provider.
- </p><p>requesters may use the policy intersection to select a compatible policy alternative
+ Requesters may use the policy intersection to select a compatible policy alternative
for a Web service interaction. If an assertion only describes one participant’s behavior
then this assertion will not be present in the other participants’ policy and the policy
intersection will unnecessarily produce false negatives.
</p></li><li><p>Does the behavior have an implied scoping to a policy subject such as service, endpoint, operation and message?
- </p></li><li><p>Is there a requirement that a choice must be made for successful interaction?</p><p>Some behaviors refer to a requirement that providers and requesters must deliberately choose
- to engage in. Examples, of such behaviors are the use of optimization, and reliable messaging.
+ </p></li><li><p>Is there a requirement that a choice must be made for successful interaction?</p><p>Sometimes providers and requesters are required to engage in certain behaviors.
+ The use of optimization and reliable messaging are two examples.
</p></li></ul><p>There are already many examples in the industry that adhere to this practice, such as <cite><a href="#WS-RM-Policy">Web Services Reliable Messaging Policy</a></cite>
and <cite><a href="#WS-SecurityPolicy">WS-SecurityPolicy</a></cite>. Some common characteristics from these documents may be considered as <em>best practices</em> for new assertion authors:
</p><ul><li><p>Specify both the syntax and the semantics of the assertions
@@ -170,7 +172,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="d3e178"></a>3. Who is involved in authoring Assertions? </h2><p>In order for the policy framework to enable communities to
+<h2><a name="d3e176"></a>3. 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
@@ -198,16 +200,15 @@
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>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
+ </p><p>When using the WS-Policy Framework, any
+ domain author defining new WS-Policy assertions
+ must adhere to the MUST's and SHOULD's in the specification
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 specification that
- includes these properties can be seen in the WS-SecurityPolicy
- pecification [<cite><a href="#WS-SecurityPolicy">WS-SecurityPolicy</a></cite>]. The
+ identified by the WS-PolicyAttachment specification.
+ </p><p>An example of a domain specification that follows these practices is the WS-SecurityPolicy
+ specification [<cite><a href="#WS-SecurityPolicy">WS-SecurityPolicy</a></cite>]. The
WS-SecurityPolicy authors have defined their scope as follows:
</p><p><em>"This document [WS-SecurityPolicy] defines a set of
security policy assertions for use with the WS-Policy
@@ -226,8 +227,8 @@
</p></div><div class="div3">
<h4><a name="consumers"></a>3.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, that it then uses to govern the creation of a message
+ WS-Policy XML element and selecting one alternative from the
+ policy. This selected alternative is then used 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
@@ -235,7 +236,7 @@
<cite><a href="#UDDI30">UDDI 3.0</a></cite>], and WS-Addressing Endpoint
References (EPR) [<cite><a href="#WS-Addressing">WS-Addressing Core</a></cite>].
</p><p>
- In the degenerate case, a human could read the xml and
+ In the degenerate case, a human could read the XML and
determine if a message could be constructed conformant to the
advertised policy.
</p><p>It is expected that consumers of WS-Policy will include a
@@ -246,7 +247,7 @@
configurations dynamically.
</p></div><div class="div3">
<h4><a name="providers"></a>3.1.3 Providers</h4><p>A provider of WS-Policy Assertions can be any web service implementation that can
- specify its' 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
@@ -255,7 +256,7 @@
chooses to make its capabilities and constraints available,
it may also need to conform to requirements of other policy
specifications it utilizes ( i.e., WS-SecurityPolicy).
- </p><p>When deploying services with policies it is uesful for providers to anticipate how
+ </p><p>When deploying services with policies it is useful 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,
@@ -264,10 +265,10 @@
policy assertion evolution.
</p></div></div></div><div class="div1">
<h2><a name="general-guidelines"></a>4. General Guidelines for WS-Policy Assertion Authors</h2><p> As 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 desgin. WS-Policy
- relies on the Qname of a policy assertion being an XML element but allows authors to optionally
+ 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 authors to optionally
provide additional semantics through nesting assertions, or specifying assertion parameters.
- This section covers several aspects of assertion design and provides somes 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">
+ 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"></a>4.1 Assertions and Their Target Use</h3><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
@@ -288,7 +289,7 @@
involve understanding the requirements of wide range of client configurations, from
stand alone client applications to "active" web service
requestors that are capable of modifying their own configurations dynamically.
- </p><p> Once the range of policy subjects are identified, there are choices for ways of
+ </p><p> Once the range of policy subjects is 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
@@ -296,7 +297,7 @@
in different policies (e.g. with different
alternatives) via reference, a policy assertion may be
associated with different alternatives and subjects. A
- eferencing mechanism is very useful in a tooling
+ referencing mechanism is very useful in a tooling
environment; when creating a domain specific
attachment in multiple WSDL files or Endpoint
References in which the same set of policies are expected to be applied.
@@ -324,7 +325,7 @@
its presence must interact with other policy assertions
that are defined for security.
</p></li></ul></div><div class="div2">
-<h3><a name="compact-full"></a>4.2 Authoring Styles </h3><p> WS-Policy supports 2 different authoring styles. A compact form is one in which an expression consists of three
+<h3><a name="compact-full"></a>4.2 Authoring Styles </h3><p> WS-Policy supports two different authoring styles. 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/@@@@/@@/ws-policy' xmlns:sp='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy'
@@ -380,7 +381,7 @@
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.
+ using the <code>wsp:optional</code> attribute as our example illustrates above.
</p><p>Best practice: use the authoring style most appropriate for the target audience </p></div><div class="div2">
<h3><a name="new-guidelines-domains"></a>4.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
@@ -400,18 +401,18 @@
authors a wide range of options for expressing the possible combinations of assertions within their domain.
</p><p>It requires a good deal of effort to evaluate the
capabilities of a domain and capture them in a way that
- eflects the options of the domain if the domain has a lot of
+ reflects the options of the domain if the domain has a lot of
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 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 3 assertions. Domain 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.
+ relatively simple domain that has defined three assertions. Domain 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><p>Best practice: start with a simple working assertion that allows extensibility.
+ </p><p>Best practice: Start with a simple working assertion that allows extensibility.
</p></div><div class="div3">
<h4><a name="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
their own XML dialects to represent policy assertions. The policy language relies only
@@ -422,7 +423,7 @@
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>Best practice: use a unique QName to identify the behavior and provide an XML outline
+ </p><p>Best 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"></a>4.3.3 Self Describing Messages </h4><p> WS-Policy is intended to communicate the requirements, capabilities, preferences and
@@ -461,8 +462,8 @@
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><p>Best practice:Policy assertions should not be used to express the semantics of a message.
+ can be considered when messages cannot be self describing.
+ </p><p>Best practice: Policy assertions should not be used to express the semantics of a message.
</p></div><div class="div3">
<h4><a name="single-domains"></a>4.3.4 Single Domains</h4><p>When considering the creation of a
new domain of policy assertions, it is important to identify
@@ -480,7 +481,7 @@
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
+ [some might say it is 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.
@@ -556,20 +557,20 @@
</sp:AlgorithmSuite>
</Policy>
</sp:TransportBinding></pre></div></div><p>The <code>sp:AlgorithmSuite</code> is a nested policy assertion of
- the <code>sp:TransportBinding</code> policy assertion. The<code>sp:AlgorithmSuite</code>
+ the <code>sp:TransportBinding</code> policy assertion. The <code>sp:AlgorithmSuite</code>
assertion requires the use of the algorithm suite identified by its nested policy
assertion (<code>sp:Basic256Rsa15</code>
<em>in the example above</em>) and further qualifies the behavior of the
<code>sp:TransportBinding</code> policy assertion.
</p><p>Setting aside the details of using transport-level
- security,, a policy-aware client that recognizes this policy
+ security, a policy-aware client that recognizes this policy
assertion can engage transport-level security and its
- dependent behaviors automatically. That is, the complexity of
+ dependent behaviors automatically. This means the complexity of
security usage is absorbed by a policy-aware client and hidden
- from these Web service developers.
+ from Web service application developers.
</p></div><div class="div3">
<h4><a name="which-one-to-use"></a>4.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
+ of assertions is that <em>the framework intersection
algorithm processes nested alternatives, but does not consider
parameters in its algorithm</em>.
</p><p>Domain authors should recognize that the framework can
@@ -584,7 +585,7 @@
contribution to the processing. The tradeoff is the generality
vs. the flexibility and complexity of the comparison expected for a domain. </p><p>
The following design questions below can help
- you to determine when to use nested policy expressions:</p><p>Are these assertions designed for the same policy subject? </p><p>Do these assertions represent dependent behaviors?</p><p>If the answers are yes to both of these questions then leveraging nested policy
+ to determine when to use nested policy expressions:</p><ul><li><p>Are these assertions designed for the same policy subject? </p></li><li><p>Do these assertions represent dependent behaviors?</p></li></ul><p>If the answers are yes to both of these questions then leveraging nested policy
expressions is something to consider. Keep in mind that a nested policy expression participates in
the policy intersection algorithm. If a requester uses policy intersection to select a
compatible policy alternative then the assertions in a nested policy expression play a
@@ -598,9 +599,9 @@
to the WS-Policy framework.
</p></div></div><div class="div2">
<h3><a name="optional-policy-assertion"></a>4.5 Designating Optional Behaviors</h3><div class="div3">
-<h4><a name="d3e513"></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
+<h4><a name="d3e514"></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
compact authoring form for assertions, behaviors are marked by
- using <code>wsp:optional</code> attribute that has a value,
+ using <code>wsp:Optional</code> attribute that has a value,
"true". During the process of normalization, the runtime
behavior is indicated by two policy alternatives, one with and
one without the assertion. In a consumer/provider
@@ -609,7 +610,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="d3e521"></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="d3e522"></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
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
@@ -620,7 +621,7 @@
Serialization for messages. </p><p>The semantics of this assertion declare that the behavior
is reflected in messages: they use an optimized wire format
(MIME Multipart/Related serialization). Note that in order for
- an optional behaviors to be engaged, the wire message that
+ an optional behavior to be engaged, the wire message that
would utilize the specific assertion must be self
describing. For example, an inbound message to a web service
that asserts MTOM, must evaluate, the protocol format of the
@@ -670,12 +671,12 @@
when optional behaviors are specified for message
exchanges within a request response for response messages,
using message policy subject. Leaving the semantics
- undescribed may result in providers making assumptions
+ not specified or incompletely specified may result in providers making assumptions
(i.e. if the incoming message utilized the optimization,
the response will be returned utilizing the MTOM
serialization). Similarly, if engagement of a behavior is
only specified for an outbound message, the policy
- assertion authors should consider to describe the
+ assertion authors should consider describing the
semantics if the incoming messages also utilized the
behavior. This is especially important if the assertion is
applicable to more than one specific policy subject. One
@@ -704,7 +705,7 @@
if an assertion is specific to a policy attachment
mechanism. An example could be identifying whether the
assertion expressed is associated with behaviors
- (endpoints) or artifacts ( messages) and then constraining
+ (endpoints) or artifacts (messages) and then constraining
the use of an assertion to one of these subjects.
</p><p>Thus our example encryption assertion would have a
subject of "message", and could only be attached to
@@ -717,7 +718,7 @@
</p><p>Best Practice- To avoid confusion, assertion definitions should be
precise about their semantics and include information that
restricts their set of permissible policy subjects
- appropriately and indicates which Qnames are associated with
+ appropriately and indicates which QNames are associated with
which subjects.</p><ol><li><p>Description must clearly and completely specify the syntax (plus an XML Schema
document) and semantics of a policy assertion.</p></li><li><p>If there is a nested policy expression, description must declare it and enumerate the
nested policy assertions that are allowed. </p></li><li><p>A policy alternative may contain multiple instances of the same policy assertion.
@@ -744,10 +745,11 @@
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
- choose to engage RM semantics (although not specified via
- attachment in WSDL at incoming messages), the providers will
- honor the engagement of RM. This is illustrative of how the
+ assertion semantics also indicates that the if
+ a sender chose to engage RM
+ semantics (although not specified via attachment in WSDL at incoming
+ messages), the providers will honor the engagement of RM.
+ This is illustrative of how the
assertion author can specify additional constraints and
assumptions for attachment and engagement of behavior.
</p><p>If the capability is not really suitable and may imply
@@ -816,24 +818,29 @@
manageability of the expressions as they are uniquely
identified.
</p></div><div class="div2">
-<h3><a name="extending-assertions"></a>5.2 Factors in Extending Assertions within a Domain </h3><p> Extensibility affects the policy subjects and attachment semantics. </p></div><div class="div2">
-<h3><a name="assertion-evolution"></a>5.3 Evolution of Assertions (Versioning and Compatibility)</h3><p>4.4.7. Over time, there may be multiple equivalent behaviors emerging in the Web
+<h3><a name="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
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
are mutually exclusive for an interaction. Such equivalent
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>Example 4-2. Message-level Security and WSS: SOAP Message Security 1.0 </i></p><p>ADD THE EXAMPLE HERE </p></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>Example 4-3. Message-level Security and WSS: SOAP Message Security 1.1</i></p><p>ADD THE EXAMPLE HERE </p></div><p>Best practice: use independent assertions for modeling multiple equivalent behaviors. </p></div></div><div class="div1">
+ 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>
+ <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>
+ <sp:Wss11>…</sp:Wss11>
+</Policy></pre></div></div><p>Best practice: use independent assertions for modeling multiple equivalent
+ behaviors.</p></div></div><div class="div1">
<h2><a name="inter-policy"></a>6. Inter-domain Policy and Composition Issues</h2><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 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
- protocols affect transport binding and would result in nested
+ example utilization of WS-Security Policy with other
+ protocols affects transport bindings and would result in nested
policy assertions when additional protocols are composed with
<cite><a href="#WS-Security2004">WS-Security 2004</a></cite>. Thus, domain authors should
be aware of the compositional semantics with other related
@@ -865,19 +872,19 @@
mechanisms should make it possible to clearly identify the
source of a poly 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
+ 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="scenerio"></a>8. Scenario and a worked example</h2><p>To illustrate the topics explored in this document, we
+<h2><a name="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. CompanyA has determined to utilize WS-Security,
+ interoperability. Company A 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><ul><li><p>Web Services Security Policy </p></li><li><p>Web Services Reliable Messaging Policy </p></li><li><p>Web Services Addressing WSDL Binding</p></li></ul><p>The application developers at CompanyA are instructed to
- review the current web services at CompanyA and propose a plan
+ policy assertions defined by the following documents: </p><ul><li><p>Web Services Security Policy </p></li><li><p>Web Services Reliable Messaging Policy </p></li><li><p>Web Services Addressing WSDL Binding</p></li></ul><p>The application developers at Company A are instructed to
+ review the current web services at Company A and propose a plan
for adding policy assertions. </p><p>The application developers collect information about web
- services within CompanyA and determine that all of the web
+ services within Company A and determine that all of the web
services already have a WSDL 1.1 description. The developers
have determined that Company A's web services fall into two
types of web services. There are those that fall into the
@@ -889,7 +896,7 @@
messages for the web service not to any one individual operation
or message exchange. </p><p>Service A is a WSDL 1.1 conformant web service and requires
the use of transport-level security for protecting messages as
- well as including addressing headers. Employees of CompanyA have
+ 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 8-1. </span>Message with Security Headers</i></p><div class="exampleInner"><pre><soap:Envelope>
<soap:Header>
@@ -905,7 +912,7 @@
<soap:Body>
</soap:Envelope></pre></div></div><p>The SOAP message in the example above includes security
timestamps that express creation and expiration times of this
- message. CompanyA requires the use of these security timestamps
+ message. Company A requires the use of these security timestamps
and transport-level security, such as HTTPS for protecting
messages. </p><p>The example below illustrates a policy expression that
CompanyA has created for its employees to use on their web
@@ -917,7 +924,7 @@
</Policy></pre></div></div><p>The <code>sp:TransportBinding</code> element is a policy assertion. The
assertion identifies the use of transport-level-security - such
as HTTPS for protecting messages at the transport
- level. CompanyA's policy aware clients can now recognize this
+ level. Company A's policy aware clients can now recognize this
policy assertion and if they support it, engage in transport
level security for protecting messages and providing security
timestamps in SOAP envelopes for any WSDL with this policy
@@ -928,21 +935,21 @@
they wanted to ensure that where possible they would support
alternatives rather than forcing a single client
configuration. </p><p>The developers read the WS-Policy specification and noted that
- there were 3 ways to express combinations of behaviors. The three
- policy operators, ( Policy, All and ExactlyOne) were considered
+ there were three ways to express combinations of behaviors. The three
+ policy operators, (Policy, All and ExactlyOne) were considered
and the result was the creation of two policy elements. </p><p>The first policy is shown in Figure
<em>CompanyA-ProfileA</em> and it is the policy that is used
- by many web services at Company A that rely on https to provide
+ by many web services at Company A that rely on HTTPS to provide
transport level protection of messages. </p><p>The second policy is shown in Figure
<em>CompanyA-ProfileB</em> and it offers requestors of a
service the ability to provide additional integrity protection by
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 CompanyA web services. </p><div class="exampleOuter"><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">
+ processing is not required by all Company A web services. </p><div class="exampleOuter"><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>
<sp:AsymmetricBinding></sp:AssymetricBinding>
- </ExactlyOne> </Policy> </pre></div></div><p>We have shown above that CompanyA offered a
+ </ExactlyOne> </Policy> </pre></div></div><p>We have shown above that Company A offered a
second profile that included two security options. The details of
the Bindings, requires a more detailed exploration of some of the
other features of the WS-Policy Framework. </p><p>When WS-Policy authors create sets of Policy assertions, like
@@ -954,7 +961,7 @@
an <code>sp:TransportBinding</code> assertion, just indicating the use of
transport-level security for protecting messages is not
sufficient. For a consumer of a web service provided by a company,
- like CompanyA, to successfully interact, the consumer must also
+ like Company A, to successfully interact, the consumer must also
know what transport token, what algorithm suite, etc. is
required. The <code>sp:TransportBinding</code> assertion, can (and has)
represent (ed) these dependent behaviors as "nested" policy
@@ -988,22 +995,22 @@
<code>sp:TransportToken</code> is a nested policy assertion that
indicates the use of a specific type of token, in this case an
HttpsToken. </p><p>It should be noted that each policy has an Identifier. In the
- case of the default policy expression, CompanyA has decided that
+ case of the default policy expression, Company A has decided that
this policy expression should be broadly available via a URI.
There are advantages and disadvantages to using each type of
identifier. For URI's there is the issue of maintaining the
- policy expression when it may no longer be used ( CompanyA gets
- bought by CompanyB and starts using the policies of Company B,
+ policy expression when it may no longer be used (Company A gets
+ bought by Company B and starts using the policies of Company B,
but some "old" consumers may still try to reference the
URI). </p><p> For the second type of web services, which may be used only
- by certain of CompanyA's business partners, the id is an XML ID.
+ by certain of Company A's business partners, the id is an XML ID.
The relative URI for referencing this within the same WSDL
document is #CompanyA-ProfileB. This can be useful for company's
when the policy expressions are agreed to between partners but
may be changed as the business agreements change. But the
disadvantage is that the policy expression must be included in
- each WSDL document. </p><p>Since CompanyA has decided to use well known policy
- expressions that are themselves part of a specification, they
+ each WSDL document. </p><p>Since Company A has decided to use well known policy
+ expressions that are part of a specification, they
adhere to the guidance given in the WS-SecurityPolicy
specification and attach the policies to the web service endpoint
policy subject as recommended by the WS-SecurityPolicy
@@ -1014,7 +1021,7 @@
<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.1document and referenced by the binding for the service
+ 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 8-6. </span></i></p><div class="exampleInner"><pre>
<wsdl:definitions name="StokeQuote"
targetNamespace="http:..">
@@ -1209,4 +1216,11 @@
<a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0054.html">Umit</a> to the list of editors.
Editors' action <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/86">86</a>.
</td></tr><tr><td rowspan="1" colspan="1">20061128</td><td rowspan="1" colspan="1">MH</td><td rowspan="1" colspan="1">Replaced section in Lifecycle with pointer to the text in the primer: related to action 77
+ </td></tr><tr><td rowspan="1" colspan="1">20061129</td><td rowspan="1" colspan="1">FH</td><td rowspan="1" colspan="1">Editorial revision (editorial actions
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/84">84</a> and
+ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/90">90</a>) -
+ 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></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.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- ws-policy-guidelines.xml 30 Nov 2006 04:44:59 -0000 1.18
+++ ws-policy-guidelines.xml 30 Nov 2006 06:03:53 -0000 1.19
@@ -1212,19 +1212,17 @@
WSS: SOAP Message Security 1.0. </p>
<example>
<head>Message-level Security and WSS: SOAP Message Security 1.0</head>
- <eg xml:space="preserve"><Policy>
- <sp:Wss10>…</sp:Wss10>
- </Policy></eg>
- </example>
+<eg xml:space="preserve"><Policy>
+ <sp:Wss10>…</sp:Wss10>
+</Policy></eg></example>
<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>
<example>
<head>Message-level Security and WSS: SOAP Message Security 1.1</head>
- <eg xml:space="preserve"><Policy>
- <sp:Wss11>…</sp:Wss11>
- </Policy></eg>
- </example>
+<eg xml:space="preserve"><Policy>
+ <sp:Wss11>…</sp:Wss11>
+</Policy></eg></example>
<p>Best practice: use independent assertions for modeling multiple equivalent
behaviors.</p>
</div2>
@@ -1839,9 +1837,20 @@
<tr>
<td>20061129</td>
<td>FH</td>
- <td>Editorial revision (editorial actions 84 and for action 90)
+ <td>Editorial revision (editorial actions
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/84">84</loc> and
+ <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/90">90</loc>) -
+ includes suggestions from Asir:
+ <loc href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0129.html">Part 1</loc> and
+ <loc href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0134.html">Part 2</loc>.
</td>
- </tr>
+ </tr>
+ <tr>
+ <td>20061129</td>
+ <td>ASV</td>
+ <td>Formatted examples in <specref ref="extending-assertions"/>.
+ </td>
+ </tr>
</tbody>
</table>
</inform-div1>
Received on Thursday, 30 November 2006 06:04:05 UTC